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/status/draft/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-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Pooja Ranjanhttps://github.com/poojaranjan https://wg-eips.ritovision.com/8134/

Blob parameter changes with BPO1 on Ethereum mainnet.

<h2 id="abstract">Abstract</h2> <p>This Meta EIP documents the activation details, parameter changes, and specification references for the first Blob-Parameter-Only (BPO) network upgrades, BPO1. It provides a canonical registry of blob targets, blob maximum limits, and associated configuration values to improve transparency, traceability, and ecosystem coordination for early-stage data availability scaling under Ethereum’s Surge roadmap.</p> <h2 id="motivation">Motivation</h2> <p>Blob-Parameter-Only (BPO) upgrades enable Ethereum to scale data availability through incremental parameter adjustments rather than large multi-feature network upgrades. While this approach improves safety and iteration speed, there is currently no canonical reference documenting what changed in each BPO upgrade, when it was activated, and which parameter values were applied.</p> <p><a href="https://wg-eips.ritovision.com/7892/">EIP-7892</a> specifies the mechanism and constraints for BPO upgrades but does not track individual BPO instances. In practice, activation timing and parameter values for BPO1 are distributed across client repositories, coordination notes, and operational artifacts, making consistent interpretation and historical analysis difficult for ecosystem participants.</p> <p>This EIP addresses this gap by recording authoritative data for BPO1 in a canonical reference to improve transparency, traceability, and ecosystem coordination.</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>This section documents the Blob-Parameter-Only upgrade identified as <strong>BPO1</strong>.</p> <p>The upgrade modifies blob-related protocol parameters as defined in <a href="https://wg-eips.ritovision.com/7892/">EIP-7892</a>. No other protocol behavior is affected. All timestamps are expressed as Unix epoch seconds (UTC).</p> <h3 id="bpo-1-parameters">BPO-1 Parameters</h3> <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody> <tr><td>BPO Identifier</td><td>BPO1</td></tr> <tr><td>Activation Time (UTC)</td><td>1765290071</td></tr> <tr><td>Blob Target</td><td>10</td></tr> <tr><td>Blob Max</td><td>15</td></tr> <tr><td>Base Fee Update Fraction</td><td>8,346,193</td></tr> </tbody></table> <p>BPO-1 represents the first mainnet deployment of a Blob-Parameter-Only upgrade and establishes the initial incremental increase in blob capacity following the Fusaka upgrade.</p> <h3 id="historical-context">Historical Context</h3> <p>For reference, the blob schedule before BPO upgrades was established in earlier network upgrades:</p> <table><thead><tr><th>Upgrade</th><th>Blob Target</th><th>Blob Max</th><th>Base Fee Update Fraction</th></tr></thead><tbody> <tr><td><strong>Cancun</strong></td><td>3</td><td>6</td><td>3,338,477</td></tr> <tr><td><strong>Prague</strong></td><td>6</td><td>9</td><td>5,007,716</td></tr> </tbody></table> <h3 id="data-source">Data Source</h3> <p>The parameter values and activation times in this EIP are derived from eth_client genesis configuration, including:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">bpo1Time</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-constant">1765290071</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">blobSchedule</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">cancun</span><span class="z-support">&quot;</span><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 class="z-constant"> 3</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">baseFeeUpdateFraction</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 3338477</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">prague</span><span class="z-support">&quot;</span><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 class="z-constant"> 6</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">baseFeeUpdateFraction</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5007716</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">bpo1</span><span class="z-support">&quot;</span><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 class="z-constant"> 10</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"> 15</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"> 8346193</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Client implementations may expose these values in different formats; this EIP reflects the canonical mainnet configuration values.</p> <h2 id="rationale">Rationale</h2> <p>BPO-1 formalizes the first post-Fusaka adjustment to blob parameters, providing a controlled expansion of blob capacity to support empirical evaluation under mainnet conditions. This change enables the network to collect real-world performance data across clients, validators, and proposers, supporting evidence-based assessment of slot stability and system behavior before any further scaling decisions. Documenting BPO-1 as a standalone parameter update improves transparency and process clarity by establishing an authoritative record of blob parameter changes.</p> <h2 id="security-considerations">Security Considerations</h2> <p>BPO upgrades may impact network load characteristics. Careful monitoring, staged rollout, and ecosystem coordination are required to ensure stability.</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-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-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Tim Beikohttps://github.com/timbeiko Alex Stokeshttps://github.com/ralexstokes https://wg-eips.ritovision.com/8081/

EIPs included in the Hegotá Ethereum network upgrade.

<h2 id="abstract">Abstract</h2> <p>This Meta EIP lists the EIPs formally Proposed, Considered, Declined for &amp; Scheduled for Inclusion in the Hegotá network upgrade.</p> <h2 id="specification">Specification</h2> <p>Definitions for <code>Scheduled for Inclusion</code>, <code>Considered for Inclusion</code>, <code>Declined for Inclusion</code> and <code>Proposed for Inclusion</code> can be found in <a href="https://wg-eips.ritovision.com/7723/">EIP-7723</a>.</p> <h3 id="eips-scheduled-for-inclusion">EIPs Scheduled for Inclusion</h3> <h3 id="considered-for-inclusion">Considered for Inclusion</h3> <ul> <li><a href="https://wg-eips.ritovision.com/7805/">EIP-7805</a>: Fork-choice enforced Inclusion Lists (FOCIL)</li> </ul> <h3 id="declined-for-inclusion">Declined for Inclusion</h3> <h3 id="proposed-for-inclusion">Proposed for Inclusion</h3> <h3 id="activation">Activation</h3> <table><thead><tr><th>Network Name</th><th>Activation Epoch</th><th>Activation Timestamp</th></tr></thead><tbody> <tr><td>Sepolia</td><td></td><td></td></tr> <tr><td>Hoodi</td><td></td><td></td></tr> <tr><td>Mainnet</td><td></td><td></td></tr> </tbody></table> <p><strong>Note</strong>: rows in the table above will be filled as activation times are decided by client teams.</p> <h2 id="rationale">Rationale</h2> <p>This Meta EIP provides a global view of all changes included in the network upgrade, as well as links to full specification.</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-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: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-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: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-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-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Maria Silvahttps://github.com/misilva73 Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/8007/

Directory of EIPs introducing changes to the gas pricing model for the Glamsterdam fork

<h2 id="abstract">Abstract</h2> <p>This Meta EIP documents all the proposals for Glamsterdam related to the gas repricing effort. The goal of this effort is to harmonize gas costs across the EVM, thereby reducing the impact of specific bottlenecks on scaling. Proposals include changes to the cost of single EVM operations, as well as bigger changes to the gas model. This Meta EIP is purely informational and does not aim to have an active role in the governance process for the Glamsterdam fork. Instead, it serves as a directory for all repricing-related proposals, helping to organize the work and keeping the community informed about the status of each EIP.</p> <h2 id="motivation">Motivation</h2> <p>The main objective of the Glamsterdam fork is to improve L1 scalability. A crucial aspect of this initiative is to create a better alignment between gas costs and actual resource usage. Currently, the gas model often misprices operations, resulting in inefficiencies and unintended incentives. For instance, within the pure compute operations, there is a high variance in execution time per gas unit, which indicates that a single unit of computation is not priced equally across the various opcodes.</p> <p>By standardizing gas costs across EVM operations and other resources, we can reduce bottlenecks and enhance the utilization of EVM resources, which will subsequently enable further scalability. The EIPs listed below constitute a significant first step in that direction. We expect that further iteration will be necessary in future hardforks.</p> <h2 id="specification">Specification</h2> <p>The following table lists all EIPs related to repricings that are being discussed in the scope of the Glamsterdam fork. There are three types of EIPs in this list:</p> <ol> <li><strong>Broad harmonization</strong>. These EIPs reprice a class of operations with the goal of harmonizing them and removing single bottlenecks.</li> <li><strong>Pricing extension</strong>. These EIPs make targeted changes to a specific opcode or component of the gas model, usually coupled with a new mechanism.</li> <li><strong>Supporting</strong>. These EIPs are not directly doing a repricing, but instead introduce a change that support other repricing EIPs or enhance the scalability potential of repricings.</li> </ol> <h3 id="considered-for-inclusion">Considered for Inclusion</h3> <table><thead><tr><th style="text-align: center">EIP</th><th>Description</th><th>Type</th><th style="text-align: center">Resource class</th><th>Gas change overview</th></tr></thead><tbody> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/2780/">EIP-2780</a></td><td>Reduce intrinsic transaction gas and charge 25k when a value transfer creates a new account.</td><td>Broad harmonization</td><td style="text-align: center">Multi-resource</td><td>Decrease <code>TX_BASE_COST</code> (21k→4.5k); increase new-account surcharge (0→25k)</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/7778/">EIP-7778</a></td><td>Prevent Block Gas Limit Circumvention by Excluding Refunds from Block Gas Accounting.</td><td>Pricing extension</td><td style="text-align: center">General Accounting</td><td>No opcode repricing; excludes gas refunds (e.g. <code>SSTORE</code> clearing) from block gas accounting</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/7904/">EIP-7904</a></td><td>Gas Cost Increase to reflect computational complexity and transaction throughput increase</td><td>Broad harmonization</td><td style="text-align: center">Compute</td><td>All increase: <code>DIV</code>, <code>SDIV</code>, <code>MOD</code>, <code>MULMOD</code>, <code>KECCAK256</code>, precompiles (<code>BLAKE2F</code>, <code>BLS12_G1ADD</code>, <code>BLS12_G2ADD</code>, <code>ECADD</code>, <code>ECPAIRING</code>, <code>POINT_EVALUATION</code>)</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/7976/">EIP-7976</a></td><td>Further increase calldata cost to 15/60 gas per byte to reduce maximum block size.</td><td>Pricing extension</td><td style="text-align: center">Data</td><td>Increase calldata floor cost (10/40 → 15/60 per byte)</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/7981/">EIP-7981</a></td><td>Introduce floor pricing for access lists to reduce maximum block size.</td><td>Pricing extension</td><td style="text-align: center">Data</td><td>Increase: new floor charge on access list data (addresses + storage keys)</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a></td><td>Harmonization, increase and separate metering of state creation gas costs to mitigate state growth and unblock scaling.</td><td>Broad harmonization</td><td style="text-align: center">State</td><td>All increase (dynamic with gas limit): <code>GAS_CREATE</code>, <code>GAS_CODE_DEPOSIT</code>, <code>GAS_NEW_ACCOUNT</code>, <code>GAS_STORAGE_SET</code>, <code>PER_AUTH_BASE_COST</code></td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/8038/">EIP-8038</a></td><td>Increases the gas cost of state-access operations to reflect Ethereum's larger state.</td><td>Broad harmonization</td><td style="text-align: center">State</td><td>All increase: cold storage write/access, cold account access, warm access, <code>EXTCODESIZE</code>/<code>EXTCODECOPY</code> extra read, access list costs</td></tr> </tbody></table> <h3 id="declined-for-inclusion">Declined for Inclusion</h3> <table><thead><tr><th style="text-align: center">EIP</th><th>Description</th><th>Type</th><th style="text-align: center">Resource class</th></tr></thead><tbody> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/2926/">EIP-2926</a></td><td>Introduce code-chunking in an MPT context.</td><td>Pricing extension</td><td style="text-align: center">State</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/7686/">EIP-7686</a></td><td>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.</td><td>Pricing extension</td><td style="text-align: center">Memory</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/7923/">EIP-7923</a></td><td>Linearize Memory Costing and replace the current quadratic formula with a page-based cost model.</td><td>Pricing extension</td><td style="text-align: center">Memory</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/7971/">EIP-7971</a></td><td>Decrease costs for <code>TLOAD</code> and <code>TSTORE</code> with a transaction-global limit.</td><td>Pricing extension</td><td style="text-align: center">Memory</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/7973/">EIP-7973</a></td><td>Introduce warm account writes, decreasing the cost of writing to an account after the first write.</td><td>Pricing extension</td><td style="text-align: center">State</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a></td><td>Gas accounting by EVM resource, increasing throughput and improving resource usage controls, with minimal changes to the protocol and UX.</td><td>Supporting</td><td style="text-align: center">NA</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a></td><td>Makes <code>SSTORE</code> gas cost scale with a contract's storage size to discourage state bloat.</td><td>Pricing extension</td><td style="text-align: center">State</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/8053/">EIP-8053</a></td><td>Adds <code>milli-gas</code> as the EVM's internal gas accounting unit, reducing rounding errors without impacting UX.</td><td>Supporting</td><td style="text-align: center">NA</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/8057/">EIP-8057</a></td><td>Multi‑block temporal locality discounts for state and account access.</td><td>Pricing extension</td><td style="text-align: center">State</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/8058/">EIP-8058</a></td><td>Reduces gas costs for deploying duplicate contract bytecode via access-list based mechanism.</td><td>Pricing extension</td><td style="text-align: center">State</td></tr> <tr><td style="text-align: center"><a href="https://wg-eips.ritovision.com/8059/">EIP-8059</a></td><td>Gas parameters and variables are increased to a factor of <code>REBASE_FACTOR</code> to reduce rounding errors without major changes to the EVM.</td><td>Supporting</td><td style="text-align: center">NA</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <h3 id="gas-cost-changes-by-operation">Gas cost changes by operation</h3> <p>The following tables summarize the preliminary gas cost changes. Numbers are not yet finalized and will be subject to change.</p> <h4 id="compute-opcodes-eip-7904-all-increase">Compute Opcodes — <a href="https://wg-eips.ritovision.com/7904/">EIP-7904</a> (all increase)</h4> <table><thead><tr><th>Opcode</th><th>Name</th><th style="text-align: right">Current</th><th style="text-align: right">New</th><th>Direction</th></tr></thead><tbody> <tr><td>0x04</td><td><code>DIV</code></td><td style="text-align: right">5</td><td style="text-align: right">15</td><td>increase</td></tr> <tr><td>0x05</td><td><code>SDIV</code></td><td style="text-align: right">5</td><td style="text-align: right">20</td><td>increase</td></tr> <tr><td>0x06</td><td><code>MOD</code></td><td style="text-align: right">5</td><td style="text-align: right">12</td><td>increase</td></tr> <tr><td>0x09</td><td><code>MULMOD</code></td><td style="text-align: right">8</td><td style="text-align: right">11</td><td>increase</td></tr> <tr><td>0x20</td><td><code>KECCAK256</code> (base)</td><td style="text-align: right">30</td><td style="text-align: right">45</td><td>increase</td></tr> </tbody></table> <p><code>KECCAK256</code> per-word cost stays at 6. <code>ADDMOD</code>, <code>SMOD</code>, and <code>ECRECOVER</code> are unchanged.</p> <h4 id="precompiles-eip-7904-all-increase">Precompiles — <a href="https://wg-eips.ritovision.com/7904/">EIP-7904</a> (all increase)</h4> <table><thead><tr><th>Precompile</th><th style="text-align: right">Current</th><th style="text-align: right">New</th><th>Direction</th></tr></thead><tbody> <tr><td><code>BLAKE2F</code> (base)</td><td style="text-align: right">0</td><td style="text-align: right">170</td><td>increase</td></tr> <tr><td><code>BLAKE2F</code> (per round)</td><td style="text-align: right">1</td><td style="text-align: right">2</td><td>increase</td></tr> <tr><td><code>BLS12_G1ADD</code></td><td style="text-align: right">375</td><td style="text-align: right">643</td><td>increase</td></tr> <tr><td><code>BLS12_G2ADD</code></td><td style="text-align: right">600</td><td style="text-align: right">765</td><td>increase</td></tr> <tr><td><code>ECADD</code></td><td style="text-align: right">150</td><td style="text-align: right">314</td><td>increase</td></tr> <tr><td><code>ECPAIRING</code> (per pair)</td><td style="text-align: right">34,000</td><td style="text-align: right">34,103</td><td>increase (slight)</td></tr> <tr><td><code>POINT_EVALUATION</code></td><td style="text-align: right">50,000</td><td style="text-align: right">89,363</td><td>increase</td></tr> </tbody></table> <h4 id="state-access-eip-8038-all-increase-values-tbd">State Access — <a href="https://wg-eips.ritovision.com/8038/">EIP-8038</a> (all increase, values TBD)</h4> <table><thead><tr><th>Opcode(s)</th><th>Component</th><th style="text-align: right">Current</th><th>New</th><th>Direction</th></tr></thead><tbody> <tr><td><code>SSTORE</code></td><td><code>GAS_COLD_STORAGE_WRITE</code></td><td style="text-align: right">5,000</td><td>TBD</td><td>increase</td></tr> <tr><td><code>SSTORE</code>, <code>SLOAD</code></td><td><code>GAS_COLD_STORAGE_ACCESS</code></td><td style="text-align: right">2,100</td><td>TBD</td><td>increase</td></tr> <tr><td><code>CALL</code>, <code>STATICCALL</code>, <code>DELEGATECALL</code>, <code>BALANCE</code>, <code>EXT*</code>, <code>SELFDESTRUCT</code></td><td><code>GAS_COLD_ACCOUNT_ACCESS</code></td><td style="text-align: right">2,600</td><td>TBD</td><td>increase</td></tr> <tr><td>All state ops (warm)</td><td><code>GAS_WARM_ACCESS</code></td><td style="text-align: right">100</td><td>TBD</td><td>increase</td></tr> <tr><td><code>EXTCODESIZE</code></td><td>Extra warm read for 2nd DB lookup</td><td style="text-align: right">0</td><td>+<code>GAS_WARM_ACCESS</code></td><td>increase (new)</td></tr> <tr><td><code>EXTCODECOPY</code></td><td>Extra warm read for 2nd DB lookup</td><td style="text-align: right">0</td><td>+<code>GAS_WARM_ACCESS</code></td><td>increase (new)</td></tr> <tr><td><code>SSTORE</code>, <code>SLOAD</code> (access list)</td><td><code>ACCESS_LIST_STORAGE_KEY_COST</code></td><td style="text-align: right">1,900</td><td>TBD</td><td>increase</td></tr> <tr><td><code>CALL</code> etc. (access list)</td><td><code>ACCESS_LIST_ADDRESS_COST</code></td><td style="text-align: right">2,400</td><td>TBD</td><td>increase</td></tr> </tbody></table> <h4 id="state-creation-eip-8037-all-increase-dynamic-with-gas-limit">State Creation — <a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a> (all increase, dynamic with gas limit)</h4> <p>At 60M gas limit, <code>cost_per_state_byte</code> (cpsb) = 662. Costs scale up with higher gas limits.</p> <table><thead><tr><th>Operation</th><th>Opcodes Affected</th><th style="text-align: right">Current</th><th style="text-align: right">New (at 60M)</th><th>Direction</th></tr></thead><tbody> <tr><td><code>GAS_CREATE</code></td><td><code>CREATE</code>, <code>CREATE2</code>, create txs</td><td style="text-align: right">32,000</td><td style="text-align: right">112 x cpsb + 9,000 (~83k)</td><td>increase</td></tr> <tr><td><code>GAS_CODE_DEPOSIT</code></td><td><code>CREATE</code>, <code>CREATE2</code>, create txs</td><td style="text-align: right">200/byte</td><td style="text-align: right">cpsb/byte + hash (~662/byte)</td><td>increase</td></tr> <tr><td><code>GAS_NEW_ACCOUNT</code></td><td><code>CALL*</code> to new accounts</td><td style="text-align: right">25,000</td><td style="text-align: right">112 x cpsb (~74k)</td><td>increase</td></tr> <tr><td><code>GAS_STORAGE_SET</code></td><td><code>SSTORE</code> (0 -&gt; non-zero)</td><td style="text-align: right">20,000</td><td style="text-align: right">32 x cpsb + 2,900 (~24k)</td><td>increase</td></tr> <tr><td><code>PER_AUTH_BASE_COST</code></td><td>EIP-7702 auth</td><td style="text-align: right">12,500</td><td style="text-align: right">23 x cpsb + 7,500 (~22.7k)</td><td>increase</td></tr> <tr><td><code>PER_EMPTY_ACCOUNT_COST</code></td><td>EIP-7702 auth</td><td style="text-align: right">25,000</td><td style="text-align: right">112 x cpsb (~74k)</td><td>increase</td></tr> </tbody></table> <h4 id="transaction-level-costs">Transaction-Level Costs</h4> <table><thead><tr><th>Parameter</th><th style="text-align: right">Current</th><th>New</th><th>Direction</th><th>EIP</th></tr></thead><tbody> <tr><td><code>TX_BASE_COST</code></td><td style="text-align: right">21,000</td><td>4,500</td><td>decrease</td><td><a href="https://wg-eips.ritovision.com/2780/">2780</a></td></tr> <tr><td>New account surcharge (top-level value tx)</td><td style="text-align: right">0</td><td>25,000</td><td>increase</td><td><a href="https://wg-eips.ritovision.com/2780/">2780</a></td></tr> <tr><td>Calldata floor cost</td><td style="text-align: right">10/40 per byte</td><td>15/60 per byte</td><td>increase</td><td><a href="https://wg-eips.ritovision.com/7976/">7976</a></td></tr> <tr><td>Access list data cost</td><td style="text-align: right">0</td><td><code>floor_token_cost</code> per token</td><td>increase (new)</td><td><a href="https://wg-eips.ritovision.com/7981/">7981</a></td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>Discussed in the individual EIPs.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 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-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-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-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-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-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-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-19T00:00:00+00:00 2026-02-11T14:49:28+00:00 Justin Florentinehttps://github.com/jflojustin@florentine.us Jochem Brouwerhttps://github.com/jochem-brouwerjochem@ethereum.org Barnabas Busahttps://github.com/barnabasbusabbusa@ethereum.org https://wg-eips.ritovision.com/7949/

Schema for `genesis.json` files

<h2 id="abstract">Abstract</h2> <p>This EIP defines a canonical structure for Ethereum genesis files (<code>genesis.json</code>) used to bootstrap Ethereum networks. The standard aligns with the de facto structure implemented by Geth (Go-Ethereum), and already adopted by other clients. It introduces a JSON Schema to ensure consistency and tool compatibility across clients.</p> <h2 id="motivation">Motivation</h2> <p>The lack of an official standard for the <code>genesis.json</code> file has led to incompatibilities, bugs and confusion, as well as added workload for those running multiple clients together in test networks. This EIP aims to reduce ambiguity by defining a consistent structure and enabling tooling through schema-based validation.</p> <h2 id="specification">Specification</h2> <p>The canonical genesis file MUST be a JSON object with the following top-level fields:</p> <h3 id="top-level-fields">Top-Level Fields</h3> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody> <tr><td><code>config</code></td><td>Object</td><td>Chain configuration object.</td><td>(see below)</td></tr> <tr><td><code>alloc</code></td><td>Object</td><td>Map of addresses to pre-allocated balances and/or code/storage.</td><td>(see below)</td></tr> <tr><td><code>nonce</code></td><td>String</td><td>Block nonce as a hex string.</td><td><code>0x0</code></td></tr> <tr><td><code>timestamp</code></td><td>String</td><td>UNIX timestamp as a hex string.</td><td><code>0x6720f180</code></td></tr> <tr><td><code>extraData</code></td><td>String</td><td>Arbitrary extra data as hex string.</td><td><code>0x00</code></td></tr> <tr><td><code>gasLimit</code></td><td>String</td><td>Block gas limit as a hex string.</td><td><code>0x1c9c380</code></td></tr> <tr><td><code>difficulty</code></td><td>String</td><td>Block difficulty as a hex string.</td><td><code>0x1</code></td></tr> <tr><td><code>mixhash</code></td><td>String</td><td>Mix hash as a hex string.</td><td><code>0x0000000000000000000000000000000000000000000000000000000000000000</code></td></tr> <tr><td><code>coinbase</code></td><td>String</td><td>Coinbase address as a hex string.</td><td><code>0x0000000000000000000000000000000000000000</code></td></tr> </tbody></table> <h3 id="config-object"><code>config</code> Object</h3> <p>The <code>config</code> object contains hardfork activation block numbers and fork configurations. Known keys include:</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody> <tr><td><code>chainId</code></td><td>Integer</td><td>Unique identifier for the blockchain as a decimal integer.</td><td><code>1</code> (mainnet)</td></tr> <tr><td><code>&lt;hardfork(Block|Time)&gt;</code></td><td>Integer</td><td>Block height or timestamp to activate the named hardfork as a decimal integer.</td><td><code>shanghaiTime: 1681338455</code></td></tr> <tr><td><code>terminalTotalDifficulty</code></td><td>String</td><td>Total difficulty after which to switch from PoW to PoS as a hex string.</td><td><code>0xc70d815d562d3cfa955</code></td></tr> <tr><td><code>depositContractAddress</code></td><td>String</td><td>Ethereum address for the deposit contract as a hex string.</td><td><code>0x00000000219ab540356cBB839Cbe05303d7705Fa</code></td></tr> <tr><td><code>blobSchedule</code></td><td>Object</td><td>Map of hardforks and their EIP-4844 DAS <a href="https://wg-eips.ritovision.com/7840/">configuration parameters</a>.</td><td>(see below)</td></tr> </tbody></table> <h3 id="blobschedule-object"><code>blobSchedule</code> Object</h3> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody> <tr><td><code>target</code></td><td>Integer</td><td>Desired number of blobs to include per block as a decimal integer.</td><td><code>3</code></td></tr> <tr><td><code>max</code></td><td>Integer</td><td>Maximum number of blobs to include per block as a decimal integer.</td><td><code>6</code></td></tr> <tr><td><code>baseFeeUpdateFraction</code></td><td>Integer</td><td>Input to pricing formula per EIP-4844 as a decimal integer.</td><td><code>3338477</code></td></tr> </tbody></table> <h3 id="alloc-object"><code>alloc</code> Object</h3> <p>The <code>alloc</code> field defines the initial state at genesis. It maps addresses (as hex strings) to the following object:</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody> <tr><td><code>balance</code></td><td>String</td><td>Account balance in wei as a hex string.</td><td><code>0xde0b6b3a7640000</code> (1 ETH)</td></tr> <tr><td><code>code</code></td><td>String</td><td>EVM bytecode as a hex string.</td><td><code>0x6060604052600436106100af576000357c0100000000000000000000000000000000000000000000000000000000</code></td></tr> <tr><td><code>nonce</code></td><td>String</td><td>Account nonce as a hex string.</td><td><code>0x0</code></td></tr> <tr><td><code>storage</code></td><td>Object</td><td>Key-value map where keys and values are 32-byte hex strings representing storage slots.</td><td><code>"0x0000000000000000000000000000000000000000000000000000000000000001": "0x00000000000000000000000000000000000000000000000000000000000000ff"</code></td></tr> </tbody></table> <h3 id="json-schema">JSON Schema</h3> <pre class="giallo z-code"><code data-lang="json"><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">$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-07/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">$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">hexUint</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="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">pattern</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">^0x[0-9a-fA-F]+$</span><span class="z-punctuation z-definition z-string">&quot;</span></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">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="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">pattern</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">^0x[0-9a-fA-F]{40}$</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="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">pattern</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">^0x[0-9a-f]{64}$</span><span class="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">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 Genesis File</span><span class="z-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">alloc</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">gasLimit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">difficulty</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">config</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">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">chainId</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">integer</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">homesteadBlock</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">integer</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">daoForkBlock</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">integer</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">eip150Block</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">integer</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">tangerineWhistleBlock</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">integer</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">eip155Block</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">integer</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">spuriousDragonBlock</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">integer</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">byzantiumBlock</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">integer</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">constantinopleBlock</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">integer</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">petersburgBlock</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">integer</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">istanbulBlock</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">integer</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">muirGlacierBlock</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">integer</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">berlinBlock</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">integer</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">londonBlock</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">integer</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">arrowGlacierBlock</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">integer</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">grayGlacierBlock</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">integer</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">terminalTotalDifficulty</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/hexUint</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">mergeNetsplitBlock</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">integer</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">shanghaiTime</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">integer</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">cancunTime</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">integer</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">pragueTime</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">integer</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">osakaTime</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">integer</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">depositContractAddress</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/address</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">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">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">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">target</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">integer</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">max</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">integer</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">baseFeeUpdateFraction</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">integer</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></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>,</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> {</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/hexUint</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">timestamp</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/hexUint</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">extraData</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">anyOf</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">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-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-support"> &quot;</span><span class="z-support">const</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></span> <span class="giallo-l"><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 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">^0x([0-9a-fA-F]{2})*$</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">gasLimit</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/hexUint</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">difficulty</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/hexUint</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">mixhash</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/hash</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">coinbase</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/address</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">alloc</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">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">^0x[0-9a-fA-F]{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">balance</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/hexUint</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">nonce</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/hexUint</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">code</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 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">^0x([0-9a-f])*$</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">storage</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">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">^0x[0-9a-f]{64}$</span><span 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/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> <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 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">additionalProperties</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></code></pre><h2 id="rationale">Rationale</h2> <p>There are a growing number of EIPs that propose improvements to how a network is configured at genesis:</p> <p><a href="https://wg-eips.ritovision.com/7840/">Add Blob Schedule to EL Config File</a></p> <p><a href="https://wg-eips.ritovision.com/7892/">Blob Parameter Only Hardforks</a></p> <p><a href="https://wg-eips.ritovision.com/7910/">eth_config JSON-RPC method</a></p> <p>However, the root configuration element amended by these remains unspecified. Adopting a minimal schema to define that will make subsequent changes more accurate and concise.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Since this is an optional and informational EIP, which offers only developer convenience, and must be used with admin access to the node, no new security concerns are introduced.</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 Ameen Soleimanihttps://github.com/ameensol Gregory Markou https://wg-eips.ritovision.com/7940/

Proposal to elect an Ethereum Shah who will act as a "protector" for the core devs and the Ethereum protocol.

<h2 id="abstract">Abstract</h2> <p>Ethereum needs a Shah. The role of the Shah is to be the "protector". A Shah, empowered by the community and with a mandate to represent their interests, could solve the communication gaps between the Ethereum community and core devs, represent the interests of the Ethereum community (holders, stakers, app devs &amp; businesses especially) to the core devs with a tighter feedback loop, and eventually dissolve their position when the imminent danger of Ethereum coordination failure is meaningfully addressed.</p> <h2 id="motivation">Motivation</h2> <p>It is clear from recent events that Ethereum is suffering from a coordination breakdown between the user ecosystem and the core devs. A case in point is the EOF debacle, with years wasted in EOF development that <del>seems ultimately likely to be</del> was just rejected as a result of 1) fragmented communication between researchers/core devs and the greater Ethereum ecosystem, to the extent that even tentative supporters of EOF weren't aware of the toolchain update requirements on the rest of the ecosystem as well as 2) a lack of rigorous compatibility testing such that EOF exposes protocol level risks.</p> <p>A Shah is of course centralized, but we've seen the decentralized alternative: First a tacit acceptance of a seemingly unnecessary EIP involving years of labor, approved by committee, and ultimately rejected by the Ethereum community. The costs on our collective time are large, not to mention the opportunity cost.</p> <p>Ethereum could spare itself these inefficiencies by electing a Shah to manage the core dev roadmap and EIPs.</p> <h2 id="specification">Specification</h2> <p>The Shah SHOULD be elected by the Ethereum community, using a combination of ETH voting, social signalling, and core dev ratification.</p> <p>The Shah SHOULD be singularly responsible for deciding on the EIP inclusion roadmap, as well as having veto power over which EIPs to include.</p> <p>The Shah SHOULD maintain communication channels with the Ethereum community (holders, stakers, app devs &amp; businesses) to understand their needs &amp; request feedback on EIPs.</p> <p>The Shah SHOULD play a coordinator role in the All Core Devs (ACD) calls, and submit a quarterly progress update to Ethereum stakeholders.</p> <p>The Shah SHOULD NOT have any special privileges, for example: to relieve developers of duty at organizations not under the Shah's control.</p> <p>The Shah SHOULD explicitly call out blockers, communications breakdowns, and when deserving, the core devs that get in the way of addressing them.</p> <p>The Shah SHOULD NOT report to the Ethereum Foundation. The Shah's position would be paid directly from the most credibly "Ethereum" source of funding, which has received its budget from a diverse set of Ethereum community members: The Protocol Guild.</p> <p>The Shah SHOULD have an expiration date for their role set at the time of election, that does exceed 2 years.</p> <p>The Shah SHOULD be able to step down willingly before the end of their 2 year term.</p> <hr /> <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "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>During times of war, the Roman Senate would elect an "Imperator" that would be responsible for dealing with an imminent threat, and once the threat was dealt with, would abdicate their power. The Shah is a similar concept, but rooted in the culture of the Persian Empire, which pioneered a "pluralistic" multi-national empire that respected cultural and religious diversity of its member nations—as aligned with Ethereum's culture of pluralism today.</p> <p>This EIP is largely inspired by Greg the Greek's post (below) about the EF core devs lacking strong leadership who can take responsibility for saying "NO" to EIPs that they expect will ultimately be defeated by community consensus, and thus saving everyone their time, effort, and mental health. The Greeks pioneered democracy—if the will of the people is to elect (even for a limited time) a strong leader, would it not be undemocratic to deny it?</p> <p>Link: x (dot) com/gregthegreek/status/1914811701901623746</p> <blockquote> <p>All Core Devs need to centralize. They need a leader who will say, NO. They need to be told what not to do. They need someone to shield them.</p> <p><img src="https://wg-eips.ritovision.com/7940/./assets/acd_leader.jpeg" alt="Figure 1" /></p> <p>Story Time</p> <p>I vividly remember hearing about EOF 4-5 years ago</p> <p>I asked a simple question: Q: How does this benefit users interacting with the chain? A: It allows future implementations of the EVM to add those things!</p> <p>👎</p> <p>Cold, hard truth. Engineers are trying to solve a problem because it's fun, not because it's needed. It has some long-tail benefits, but not enough to justify the pain that it will cause.</p> <p>This is a full-blown toolchain update (almost). We need to prioritize things that provide incremental wins. If the team behind EOF had spent more time improving the EVM in incremental steps (ditching EOF altogether), they could have shipped so much more, which could have, in aggregate, contributed to a 10x improvement.</p> <p>Instead, they continue to fight for a proposal that was shot down ~3 times?</p> <p>What has EOF done?</p> <ul> <li>Distracted ACD for the 4th time</li> <li>Delaying roadmap by jamming a MASSIVE change into core code</li> <li>Distract @ethPandaOps who will inevitably be responsible for creating an ungodly testing framework for this change</li> <li>Caused ProgPow level wars because they can't take "no" for an answer</li> </ul> <p>ONE YEAR AGO in Brussels, I asked Marius "How's work?" and he responded:</p> <blockquote> <p>The EOF folks are back, the proposal is bigger than before.</p> </blockquote> <p>ONE YEAR AGO - does no one see the problem here?</p> <p>@tkstanczak @hwwonx This is the hardest role to hire for, but it needs to be done. That or one of you will need to step up and actually own this. It's clear @VitalikButerin, and we shouldn't force him to, he's better on the research side. Someone needs to run DAY-To-DAY ops/product on ACD.</p> <p>It's exhausting. Let the devs ship. Stop the politics. Turn the ship around.</p> <p>Please 💕</p> </blockquote> <p>The role of the Shah would be primarily social, and they would not have any <em>formal</em> power. Their power solely comes from the belief that the community has in their power. In the context of steering the ACD calls &amp; EIP inclusion roadmap, this is actually enough. In my personal experience helping kill ProgPow, the core devs were not convinced that I adequately represented enough of the Ethereum community (despite my position as the Summoner of MolochDAO) and it took Martin Koeppelman &amp; several others to step forward to socially signal against ProgPow and ultimately join the ACD meeting to advocate against it in order to finally convince the core devs that ProgPow was against the interest of the greater Ethereum community. The role of the Shah can help short-circuit this suspicion from the core devs by having the default understanding be that the Shah does in fact represent the will of the greater Ethereum community.</p> <p>In his post a few weeks ago, Tim Beiko (the current Ethereum Hard Fork Coordinator) also suggested that the ACD was missing the roadmapping role this EIP proposes to be coordinated by the Shah.</p> <blockquote> <p><strong>Roadmap Setting</strong> The most important missing piece in the current AllCoreDevs process is a focus on the high level roadmap (“why we do things”), rather than individual proposals (“what we do”). This is true both for when planning the next fork(s), but also when thinking about Ethereum’s longer-term direction.</p> </blockquote> <p>Link: ethereum-magicians (dot) org/t/reconfiguring-allcoredevs/23370</p> <h2 id="security-considerations">Security Considerations</h2> <p>The obvious risk of having a Shah is that they could veto EIPs that <em>are</em> actually aligned with the Ethereum community stakeholders or prioritize EIPs that are not. In this case, it is the role of the community to publicly dissent from the Shah and ultimately remove them from office. I would expect that long before the Shah was officially deposed, the all core devs would start ignoring the Shah's input anyway, as the position does not hold any formal power. I think a fair minimum term would be 6 months (for there to be two quarterly reports at least) and with at least the same degree of community consensus around deposing the Shah as there was to enshrine them in the first 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> 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-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 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech https://wg-eips.ritovision.com/7919/

List of EIPs belonging to the Pureth proposal

<h2 id="abstract">Abstract</h2> <p>This Meta EIP bundles a set of improvements to make Ethereum data easier to access and verify without relying on trusted RPC providers or third-party indexers. The improvements achieve this by changing data structures for blocks, transactions, and receipts, so that efficient correctness (i.e., validity) and completion (i.e., nothing omitted) proofs can be added to the RPC responses.</p> <h2 id="motivation">Motivation</h2> <ul> <li> <p><strong>Security</strong>: Today, most wallets and dApps consume data from very few large RPC providers, which exposes users to the risk of incorrect and incomplete data in case the RPC provider gets hacked, becomes malicious, or uses a faulty software version.</p> </li> <li> <p><strong>Privacy</strong>: Centralized infrastructure is subject to external data collection and privacy policies; users may be profiled across distinct wallets even when there is no on-chain link between them.</p> </li> <li> <p><strong>Cost</strong>: External indexers can be quite costly, however, are required for even basic wallet use cases. Reducing reliance on them helps lower-funded developers.</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="improve-ux-eth-transfer-logs">Improve UX: ETH transfer logs</h3> <p>ETH transfers currently don't emit logs, and in many situations don't leave any on-chain record in neither transaction nor receipt that they took place. For example, SENDALL can send an arbitrary ETH balance to an arbitrary account as part of a smart contract based wallet. Or a new contract deployment may send ETH to a new account of which not even the address is known yet. This makes basic flows, such as detecting a user deposit onto an exchange, very tricky. Wallets, dApps etc. either have to use tracing debug APIs on every single transaction of every single block, or integrate an external trusted indexing service which can be costly.</p> <ul> <li><a href="https://wg-eips.ritovision.com/7708/">EIP-7708: ETH transfers emit a log</a></li> <li><a href="https://wg-eips.ritovision.com/7799/">EIP-7799: System logs</a></li> </ul> <h3 id="scale-l1-improve-ux-log-reform">Scale L1 / Improve UX: LOG reform</h3> <p>The current 2048-bit Bloom filter has a high false positive rate, which grows further as more logs are packed into each block. Combined with the requirements to obtain all historical block headers to obtain a complete view of an account's history, the Bloom filter becomes practically irrelevant. A new on-chain 2D log index with bounded false positive rate and a historical accumulator is proposed that is highly efficient, further reducing the need for external indexing services for basic wallet use cases.</p> <ul> <li><a href="https://wg-eips.ritovision.com/7668/">EIP-7668: Remove bloom filters</a></li> <li><a href="https://wg-eips.ritovision.com/7745/">EIP-7745: Light client and DHT friendly log index</a></li> <li><a href="https://wg-eips.ritovision.com/7792/">EIP-7792: Verifiable logs</a> (alternative, with log index root provided via ZK instead of block header)</li> </ul> <h3 id="improve-ux-normalized-transactions-receipts">Improve UX: Normalized transactions / receipts</h3> <p>There are various JSON-RPC fields that are missing on-chain and inefficient to prove:</p> <ul> <li><strong><code>from</code>, <code>contractAddress</code>, and <code>authority</code> addresses</strong>: need to fetch transaction + use <code>ecrecover</code></li> <li><strong><code>gasUsed</code></strong>: needs current and prior receipt, as on-chain data stores cumulative not individual gas used</li> <li><strong><code>logIndex</code></strong>: need to fetch all receipts in the block</li> <li><strong><code>txHash</code></strong>: the on-chain data is based on an MPT-prefixed hash, which is different from the RPC hash</li> </ul> <p>Further, <strong><code>calldata</code> and log <code>data</code></strong> can be very large, but can only be verified by downloading the entire receipt / transaction data. This data is needed even if just basic items such as amount and destination are queried.</p> <p>Switching transactions and receipts to SSZ normalizes the format, changes to tree-based hash for more efficient proofs, and is also extensible for future transaction features such as multidimensional fees, CREATE2 deployment, and post-quantum signature types, without breaking verifiers that only check common fields.</p> <ul> <li><a href="https://wg-eips.ritovision.com/6404/">EIP-6404: SSZ transactions</a></li> <li><a href="https://wg-eips.ritovision.com/6466/">EIP-6466: SSZ receipts</a></li> </ul> <h3 id="improve-ux-serialization-harmonization">Improve UX: Serialization harmonization</h3> <p>Changing the remainder of the EL to SSZ enables a switch to a binary API as an alternative to the dated JSON-RPC API. This is especially interesting for the engine API which currently encodes all blobs as ASCII hex-strings over JSON. That binary API would follow the same approach as beacon-APIs, be based on REST, SSZ, and Snappy compression, and support similar functionality as JSON-RPC, except that all response data now comes with a correctness and exhaustiveness proof. The SSZ objects are designed to efficiently serve API requests, often allowing to answer directly from the database without having to decompress stored data on the server and without having to consult auxiliary indices.</p> <ul> <li><a href="https://wg-eips.ritovision.com/6465/">EIP-6465: SSZ withdrawals root</a></li> <li><a href="https://wg-eips.ritovision.com/7807/">EIP-7807: SSZ execution blocks</a></li> </ul> <h3 id="simple-serialize-ssz-requirements">Simple Serialize (SSZ) requirements</h3> <p>The EIPs require adding production-grade Simple Serialize (SSZ) libraries to all execution client implementations. Further, new SSZ data types are required to achieve forward compatibility while maintaining reasonable efficiency when using nested lists of large theoretical capacity.</p> <ul> <li><a href="https://wg-eips.ritovision.com/7916/">EIP-7916: SSZ ProgressiveList</a></li> <li><a href="https://wg-eips.ritovision.com/7495/">EIP-7495: SSZ ProgressiveContainer</a></li> </ul> <h2 id="rationale">Rationale</h2> <p>See individual EIPs.</p> <h2 id="security-considerations">Security Considerations</h2> <p>See individual EIPs.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 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-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-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-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-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-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-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-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-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-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: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-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-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-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-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-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-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Jordan Holberghttps://github.com/eviljordan Andrew B Coathuphttps://github.com/abcoathup https://wg-eips.ritovision.com/8066/

Process for assigning a mascot to each Ethereum network upgrade

<h2 id="abstract">Abstract</h2> <p>This EIP establishes a mascot for each Ethereum network upgrade. Mascots serve to humanize and celebrate upgrades, fostering community engagement while adhering to principles of cuteness, relevance, and inclusivity. The mascot is selected through community-driven processes, with safeguards for appropriateness, by a designated facilitator (the "Mascot Wrestler").</p> <h2 id="motivation">Motivation</h2> <p>Ethereum network upgrades often introduce complex technical changes that can feel abstract to the broader community. Mascots provide a fun, memorable, and relatable symbol for each upgrade, drawing inspiration from its headliner(s). By mandating emoji-representable mascots that are cute and non-offensive, this process:</p> <ul> <li>Enhances community participation and excitement around network upgrades.</li> <li>Creates opportunities for creative expression in upgrade event branding (e.g., watch parties, POAPs).</li> <li>Builds a consistent, whimsical tradition that differentiates Ethereum's upgrade narrative from other ecosystems.</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="1-mascot-requirements">1. Mascot Requirements</h3> <ul> <li><strong>Relevance</strong>: The mascot <strong>SHOULD</strong> relate thematically to the network upgrade's headliner(s).</li> <li><strong>Representation</strong>: The mascot <strong>MUST</strong> be expressible using one or more standard Unicode emojis (e.g., :panda: for the Merge).</li> <li><strong>Form</strong>: The mascot <strong>SHOULD</strong> depict an animal (real, mythical, or stylized, but always animal-adjacent).</li> <li><strong>Tone</strong>: The mascot <strong>MUST NOT</strong> be offensive (no depictions of violence, discrimination, or controversy) and <strong>SHOULD</strong> be inherently cute (e.g., avoiding aggressive or fearsome traits unless softened for adorability).</li> </ul> <h3 id="2-roles-and-responsibilities">2. Roles and Responsibilities</h3> <ul> <li> <p><strong>Mascot Wrestler</strong>: A self-selected community facilitator responsible for proposing, selecting, and adopting the mascot for a network upgrade. The role <strong>MAY</strong> rotate voluntarily per upgrade cycle to encourage diverse participation.</p> <ul> <li>Duties include: <ul> <li>Soliciting and curating mascot candidates.</li> <li>Facilitating selection processes.</li> <li>Announcing the final mascot (e.g., Ethereum Magicians, All Core Devs).</li> </ul> </li> </ul> </li> <li> <p><strong>Veto Powers</strong>:</p> <ul> <li>The Mascot Wrestler <strong>MAY</strong> veto any candidate mascot not meeting the mascot requirements above.</li> <li>A rough consensus of client teams <strong>MAY</strong> veto the selected mascot, triggering fallback to the next-highest-ranked candidate mascot.</li> </ul> </li> </ul> <h3 id="3-selection-process">3. Selection Process</h3> <p>The Mascot Wrestler <strong>SHALL</strong> conduct selection using one or more community-appropriate mechanisms.</p> <p>The process <strong>MUST</strong>:</p> <ul> <li>Run for a minimum of 7 days.</li> <li>Present at least 2 candidates.</li> <li>Rank finalists by popularity.</li> <li>Document results publicly.</li> </ul> <p>If no consensus is reached, the Mascot Wrestler selects the top candidate by default, subject to veto.</p> <h3 id="4-usage-guidelines">4. Usage Guidelines</h3> <p>All uses <strong>MUST</strong> respect the network upgrade mascot's cute, non-offensive nature and credit original concept creators where applicable.</p> <h2 id="rationale">Rationale</h2> <p>This specification balances creativity with guardrails to prevent mascot drift (e.g., unrelated or edgy choices). Emoji-based representation ensures accessibility across digital platforms, while the animal/cute mandate aligns with Ethereum's community ethos of approachability. The self-selected Mascot Wrestler role decentralizes coordination, leveraging vetoes for accountability. Selection flexibility accommodates Ethereum's decentralized governance evolution.</p> <p>Alternatives considered:</p> <ul> <li>Fully onchain mandates: Too rigid for creative processes.</li> <li>No formal process: Risks ad-hoc or absent mascots.</li> <li>Non-animal options: Animals evoke universality and whimsy.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP does not directly change the Ethereum protocol. It formalizes part of the current network upgrade process. Past upgrades (e.g., Shapella's owl :owl:) are retroactively honored if they fit the criteria; future upgrades <strong>MUST</strong> comply starting with the next hard fork post-adoption.</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-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-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-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-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-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-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Tim Beikohttps://github.com/timbeiko Alex Stokeshttps://github.com/ralexstokes Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/7773/

EIPs included in the Glamsterdam Ethereum network upgrade.

<h2 id="abstract">Abstract</h2> <p>This Meta EIP lists the EIPs formally Proposed, Considered, Declined for &amp; Scheduled for Inclusion in the Glamsterdam network upgrade.</p> <h2 id="specification">Specification</h2> <p>Definitions for <code>Scheduled for Inclusion</code>, <code>Considered for Inclusion</code>, <code>Declined for Inclusion</code> and <code>Proposed for Inclusion</code> can be found in <a href="https://wg-eips.ritovision.com/7723/">EIP-7723</a>.</p> <h3 id="eips-scheduled-for-inclusion">EIPs Scheduled for Inclusion</h3> <ul> <li><a href="https://wg-eips.ritovision.com/7732/">EIP-7732</a>: Enshrined Proposer-Builder Separation</li> <li><a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a>: Block-Level Access Lists</li> </ul> <h3 id="considered-for-inclusion">Considered for Inclusion</h3> <ul> <li><a href="https://wg-eips.ritovision.com/2780/">EIP-2780</a>: Reduce intrinsic transaction gas</li> <li><a href="https://wg-eips.ritovision.com/7688/">EIP-7688</a>: Forward compatible consensus data structures</li> <li><a href="https://wg-eips.ritovision.com/7708/">EIP-7708</a>: ETH transfers emit a log</li> <li><a href="https://wg-eips.ritovision.com/7778/">EIP-7778</a>: Block Gas Accounting without Refunds</li> <li><a href="https://wg-eips.ritovision.com/7843/">EIP-7843</a>: SLOTNUM opcode</li> <li><a href="https://wg-eips.ritovision.com/7904/">EIP-7904</a>: General Repricing</li> <li><a href="https://wg-eips.ritovision.com/7954/">EIP-7954</a>: Increase Maxiumum Contract Size</li> <li><a href="https://wg-eips.ritovision.com/7976/">EIP-7976</a>: Increase Calldata Floor Cost</li> <li><a href="https://wg-eips.ritovision.com/7981/">EIP-7981</a>: Increase Access List Cost</li> <li><a href="https://wg-eips.ritovision.com/7997/">EIP-7997</a>: Deterministic Factory Predeploy</li> <li><a href="https://wg-eips.ritovision.com/8024/">EIP-8024</a>: Backward compatible SWAPN, DUPN, EXCHANGE</li> <li><a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a>: State Creation Gas Cost Increase</li> <li><a href="https://wg-eips.ritovision.com/8038/">EIP-8038</a>: State-access gas cost increase</li> <li><a href="https://wg-eips.ritovision.com/8045/">EIP-8045</a>: Exclude slashed validators from proposing</li> <li><a href="https://wg-eips.ritovision.com/8061/">EIP-8061</a>: Increase exit and consolidation churn</li> <li><a href="https://wg-eips.ritovision.com/8070/">EIP-8070</a>: Sparse Blobpool</li> <li><a href="https://wg-eips.ritovision.com/8080/">EIP-8080</a>: Let exits use the consolidation queue</li> </ul> <h3 id="declined-for-inclusion">Declined for Inclusion</h3> <ul> <li><a href="https://wg-eips.ritovision.com/2926/">EIP-2926</a>: Chunk-based code merkelization</li> <li><a href="https://wg-eips.ritovision.com/5920/">EIP-5920</a>: PAY opcode</li> <li><a href="https://wg-eips.ritovision.com/6404/">EIP-6404</a>: SSZ transactions</li> <li><a href="https://wg-eips.ritovision.com/6466/">EIP-6466</a>: SSZ receipts</li> <li><a href="https://wg-eips.ritovision.com/7619/">EIP-7619</a>: Precompile Falcon512 generic verifier</li> <li><a href="https://wg-eips.ritovision.com/7668/">EIP-7668</a>: Remove bloom filters</li> <li><a href="https://wg-eips.ritovision.com/7686/">EIP-7686</a>: Linear EVM memory limits</li> <li><a href="https://wg-eips.ritovision.com/7692/">EIP-7692</a>: EVM Object Format (EOFv1) Meta</li> <li><a href="https://wg-eips.ritovision.com/7745/">EIP-7745</a>: Trustless log index</li> <li><a href="https://wg-eips.ritovision.com/7782/">EIP-7782</a>: Reduce Block Latency</li> <li><a href="https://wg-eips.ritovision.com/7791/">EIP-7791</a>: GAS2ETH opcode</li> <li><a href="https://wg-eips.ritovision.com/7793/">EIP-7793</a>: Conditional Transactions</li> <li><a href="https://wg-eips.ritovision.com/7805/">EIP-7805</a>: Fork-choice enforced Inclusion Lists (FOCIL)</li> <li><a href="https://wg-eips.ritovision.com/7819/">EIP-7819</a>: SETDELEGATE instruction</li> <li><a href="https://wg-eips.ritovision.com/7886/">EIP-7886</a>: Delayed execution</li> <li><a href="https://wg-eips.ritovision.com/7903/">EIP-7903</a>: Remove Initcode Size Limit</li> <li><a href="https://wg-eips.ritovision.com/7907/">EIP-7907</a>: Meter Contract Code Size And Increase Limit</li> <li><a href="https://wg-eips.ritovision.com/7919/">EIP-7919</a>: Pureth Meta</li> <li><a href="https://wg-eips.ritovision.com/7923/">EIP-7923</a>: Linear, Page-Based Memory Costing</li> <li><a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>: Secondary Signature Algorithms</li> <li><a href="https://wg-eips.ritovision.com/7937/">EIP-7937</a>: EVM64 - 64-bit mode EVM opcodes</li> <li><a href="https://wg-eips.ritovision.com/7942/">EIP-7942</a>: Available Attestation</li> <li><a href="https://wg-eips.ritovision.com/7971/">EIP-7971</a>: Hard Limits for Transient Storage</li> <li><a href="https://wg-eips.ritovision.com/7973/">EIP-7973</a>: Warm Account Write Metering</li> <li><a href="https://wg-eips.ritovision.com/7979/">EIP-7979</a>: Call and Return Opcodes for the EVM</li> <li><a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a>: Multidimensional Gas Metering</li> <li><a href="https://wg-eips.ritovision.com/8013/">EIP-8013</a>: Static relative jumps and calls for the EVM</li> <li><a href="https://wg-eips.ritovision.com/8030/">EIP-8030</a>: P256 transaction support</li> <li><a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a>: Size-Based Storage Gas Pricing</li> <li><a href="https://wg-eips.ritovision.com/8051/">EIP-8051</a>: Precompile for ML-DSA signature verification</li> <li><a href="https://wg-eips.ritovision.com/8053/">EIP-8053</a>: Milli-gas for High-precision Gas Metering</li> <li><a href="https://wg-eips.ritovision.com/8057/">EIP-8057</a>: Inter-Block Temporal Locality Gas Discounts</li> <li><a href="https://wg-eips.ritovision.com/8058/">EIP-8058</a>: Contract Bytecode Deduplication Discount</li> <li><a href="https://wg-eips.ritovision.com/8059/">EIP-8059</a>: Gas Units Rebase for High-precision Metering</li> <li><a href="https://wg-eips.ritovision.com/8062/">EIP-8062</a>: Add sweep withdrawal fee for 0x01 validators</li> <li><a href="https://wg-eips.ritovision.com/8068/">EIP-8068</a>: Neutral effective balance design</li> <li><a href="https://wg-eips.ritovision.com/8071/">EIP-8071</a>: Prevent using consolidations as withdrawals</li> </ul> <h3 id="proposed-for-inclusion">Proposed for Inclusion</h3> <ul> <li><a href="https://wg-eips.ritovision.com/7610/">EIP-7610</a>: Revert creation in case of non-empty storage</li> <li><a href="https://wg-eips.ritovision.com/7872/">EIP-7872</a>: Max blob flag for local builders</li> <li><a href="https://wg-eips.ritovision.com/7949/">EIP-7949</a>: Schema for <code>genesis.json</code> files</li> </ul> <h3 id="activation">Activation</h3> <table><thead><tr><th>Network Name</th><th>Activation Epoch</th><th>Activation Timestamp</th></tr></thead><tbody> <tr><td>Sepolia</td><td></td><td></td></tr> <tr><td>Holešky</td><td></td><td></td></tr> <tr><td>Mainnet</td><td></td><td></td></tr> </tbody></table> <p><strong>Note</strong>: rows in the table above will be filled as activation times are decided by client teams.</p> <h2 id="rationale">Rationale</h2> <p>This Meta EIP provides a global view of all changes included in the Glamsterdam network upgrade, as well as links to full specification.</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-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-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-14T00:00:00+00:00 2026-02-11T14:49:28+00:00 William Entrikenhttps://github.com/fulldecent https://wg-eips.ritovision.com/7768/

Externally-owned account having no Ether can send transactions and pay tips using a new "free-for-all" bucket

<h2 id="abstract">Abstract</h2> <p>A technique is introduced where an externally-owned account having no Ether can send transactions and pay tips using a new "free-for-all" bucket and using their own <code>origin.tx</code>. This requires no client changes and is compatible with existing ecosystem parts.</p> <h2 id="motivation">Motivation</h2> <p>There is much interest in third-party-pay transactions on Ethereum and competing networks.</p> <p>Other proposals require changes to the Ethereum client, that transactions be sent to the network (i.e. <code>tx.origin</code>) using a separate account and/or other additional things.</p> <p>In contrast, this proposal introduces and standardizes a solution to this problem that works only with existing client and technology, and which preserves the <code>tx.origin</code> of the originator of a transaction.</p> <h2 id="specification">Specification</h2> <h3 id="end-user-process">End user process</h3> <ol> <li>An end user who controls an externally-owned account, say Alice, will prepare transaction(s) she would like to execute and she signs this (series of) transactions.</li> <li>If Alice will like to provide consideration for executing these transactions, she will ensure that a well-known address on the network, "the free-for-all bucket" will control tokens (such as 20, 721, 1155 tokens) at the end of her series of transactions.</li> <li>Alice orders her transaction nonces carefully considering that what will eventually be executed may be: <ol> <li>None of them;</li> <li>Only the first;</li> <li>The first then the second;</li> <li>The first, then the second, ... then the Nth transaction, which is not the last in her series of transactions; or</li> <li>All her transactions, in order.</li> </ol> </li> <li>Alice sends this series of transactions to a service that communicates with block proposers. <ol> <li>Currently mempools in baseline clients would not propagate such transactions.</li> </ol> </li> </ol> <p>For example, if consideration is sent to the free-for-all address, this would typically be the last in her series of transactions.</p> <h3 id="block-preparer-process">Block preparer process</h3> <ol> <li>Sign a transaction (from any origin) to send Ether to Alice representing the current gas price times the current block size.</li> <li>(Optional) Prepare and sign a transaction to the free-for-all account, to preload any necessary responses.</li> <li>Start an execution context and include this send-Ether transaction and all of Alice's transactions.</li> <li>In the execution context, identify tokens (e.g. 20, 721, 1155) sent to the free-for-all contract address or other valuable consideration accrued to the free-for-all account.</li> <li>Sign a transaction to (from any origin) to take security of the consideration from the free-for-all account and include this transaction in the execution context.</li> <li>Evaluate the total gas spent.</li> <li>Rollback the execution context. And repeat steps 1 through 4 with these changes: <ol> <li>Step 1: use the actual required gas amount (in Ether).</li> <li>Step 4: abort if the consideration received in this second iteration is not the expected amount from the first iteration.</li> </ol> </li> <li>Use some local business logic to compare the Ether spent in step 1 (second iteration) versus the consideration received in step 4 and classify the result as favorable or not.</li> <li>If the result is favorable, commit this execution context to the mainline. Or if the result is not favorable, rollback this execution context. <ol> <li>The result of this decision may feed into a reputation tracking system to avoid evaluating future unfruitful transaction(s).</li> </ol> </li> <li>Continue execution, and publish the block.</li> </ol> <h3 id="free-for-all-bucket">Free-for-all bucket</h3> <p>This approach requires that the end user must be able to send consideration the block proposer without knowing who they are, and the block proposer must be able to realize this consideration.</p> <p>This EIP proposes to use a well-known contract account deployment for this purpose. And here is the required 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"> FreeForAll</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Performs a 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"> recipient</span><span>,</span><span class="z-storage z-type"> memory</span><span class="z-support"> bytes</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> gasLimit</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"> Prepare return values for the next N times this contract is called only in this block</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">: spell this out]</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preloadExecutions</span><span>(</span><span class="z-storage z-type">memory</span><span class="z-support"> bytes</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-comment"> Return the next return value in this block from preloadExecutions</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></code></pre><h2 id="rationale">Rationale</h2> <p>This approach can be useful for end users who do not want to or are not able to add Ether to their account.</p> <p>This approach allows to use the correct <code>origin.tx</code> which may be required for important transactions like ERC-721 <code>setApprovalForAll</code>.</p> <p>This approach may use more gas than other approaches where the consensus client is changed or where transactions can execute from (<code>origin.tx</code>) a different account.</p> <h3 id="alternatives-considered">Alternatives considered</h3> <ul> <li>Update <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> so that transactions with gasPrice = 0 are legal, but only if the commensurate amount of gas will be burnt by the block preparer in that same block.</li> <li>Create a new transaction type that encapsulates another signed transaction.</li> <li>Create a new opcode to get the coinbase of the next block.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</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> 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-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: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-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-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-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-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-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-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-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-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-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-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-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-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-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: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-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-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: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-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-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-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-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> 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-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-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-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-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-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-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-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: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-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-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-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 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-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-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: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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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> 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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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> 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-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> 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-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-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> 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> 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>