Update EIP-7251: return fee from getter and add usage example

Merged by EIP-Bot.

EIPS/eip-7251.md

@@ -12,13 +12,13 @@ requires: 7002, 7685
 ---
 ## Abstract
 
-Increases the constant `MAX_EFFECTIVE_BALANCE`, while keeping the minimum staking balance `32 ETH`. This permits large node operators to consolidate into fewer validators while also allowing solo-stakers to earn compounding rewards and stake in more flexible increments. 
+Increases the constant `MAX_EFFECTIVE_BALANCE`, while keeping the minimum staking balance `32 ETH`. This permits large node operators to consolidate into fewer validators while also allowing solo-stakers to earn compounding rewards and stake in more flexible increments.
 
 ## Motivation
 
-As of October 3, 2023, there are currently over 830,000 validators participating in the consensus layer. The size of this set continues to grow due, in part, to the `MAX_EFFECTIVE_BALANCE`, which limits the stake of a single validator to `32 ETH`. This leads to large amounts of "redundant validators", which are controlled by a single entity, possibly running on the same beacon node, but with distinct BLS signing keys. The limit on the `MAX_EFFECTIVE_BALANCE` is technical debt from the original sharding design, in which subcommittees (not the attesting committee but the committee calculated in `is_aggregator`) needed to be majority honest. As a result, keeping the weights of subcommittee members approximately equal reduced the risk of a single large validator containing too much influence. Under the current design, these subcommittees are only used for attestation aggregation, and thus only have a `1/N` honesty assumption.   
+As of October 3, 2023, there are currently over 830,000 validators participating in the consensus layer. The size of this set continues to grow due, in part, to the `MAX_EFFECTIVE_BALANCE`, which limits the stake of a single validator to `32 ETH`. This leads to large amounts of "redundant validators", which are controlled by a single entity, possibly running on the same beacon node, but with distinct BLS signing keys. The limit on the `MAX_EFFECTIVE_BALANCE` is technical debt from the original sharding design, in which subcommittees (not the attesting committee but the committee calculated in `is_aggregator`) needed to be majority honest. As a result, keeping the weights of subcommittee members approximately equal reduced the risk of a single large validator containing too much influence. Under the current design, these subcommittees are only used for attestation aggregation, and thus only have a `1/N` honesty assumption.
 
-With the security model of the protocol no longer dependent on a low value for `MAX_EFFECTIVE_BALANCE`, we propose raising this value while keeping the minimum validator threshold of `32 ETH`. This increase aims to reduce the validator set size, thereby reducing the number of P2P messages over the network, the number of BLS signatures that need to be aggregated each epoch, and the `BeaconState` memory footprint. This change adds value for both small and large validators. Large validators can consolidate to run fewer validators and thus fewer beacon nodes. Small validators now benefit from compounding rewards and the ability to stake in more flexible increments (e.g., the ability to stake `40 ETH` instead of needing to accumulate `64 ETH` to run two validators today). 
+With the security model of the protocol no longer dependent on a low value for `MAX_EFFECTIVE_BALANCE`, we propose raising this value while keeping the minimum validator threshold of `32 ETH`. This increase aims to reduce the validator set size, thereby reducing the number of P2P messages over the network, the number of BLS signatures that need to be aggregated each epoch, and the `BeaconState` memory footprint. This change adds value for both small and large validators. Large validators can consolidate to run fewer validators and thus fewer beacon nodes. Small validators now benefit from compounding rewards and the ability to stake in more flexible increments (e.g., the ability to stake `40 ETH` instead of needing to accumulate `64 ETH` to run two validators today).
 
 ## Specification
 
@@ -135,13 +135,9 @@ def fake_exponential(factor: int, numerator: int, denominator: int) -> int:
     return output // denominator
 ```
 
-##### Excess Consolidation Requests Getter
+##### Fee Getter
 
-```python
-def get_excess_consolidation_requests():
-    count = sload(CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS, EXCESS_CONSOLIDATION_REQUESTS_STORAGE_SLOT)
-    return count
-```
+When the input to the contract is length zero, interpret this as a get request for the current fee, i.e. the contract returns the result of `get_fee()`.
 
 ##### System Call
 
@@ -232,6 +228,7 @@ push20 0xfffffffffffffffffffffffffffffffffffffffe
 eq
 push1 0xd3
 jumpi
+
 push1 0x11
 push0
 sload
@@ -240,19 +237,22 @@ push32 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
 eq
 push2 0x019a
 jumpi
+
 push1 0x01
 dup3
 mul
 push1 0x01
 swap1
 push0
+
 jumpdest
 push0
 dup3
 gt
 iszero
 push1 0x68
 jumpi
+
 dup2
 add
 swap1
@@ -270,6 +270,7 @@ swap2
 swap1
 push1 0x4d
 jump
+
 jumpdest
 swap1
 swap4
@@ -284,22 +285,27 @@ push1 0x60
 eq
 push1 0x88
 jumpi
+
 calldatasize
 push2 0x019a
 jumpi
+
 callvalue
 push2 0x019a
 jumpi
+
 push0
 mstore
 push1 0x20
 push0
 return
+
 jumpdest
 callvalue
 lt
 push2 0x019a
 jumpi
+
 push1 0x01
 sload
 push1 0x01
@@ -351,6 +357,7 @@ add
 push1 0x03
 sstore
 stop
+
 jumpdest
 push1 0x03
 sload
@@ -364,16 +371,20 @@ push1 0x01
 gt
 push1 0xe7
 jumpi
+
 pop
 push1 0x01
+
 jumpdest
 push0
+
 jumpdest
 dup2
 dup2
 eq
 push2 0x0129
 jumpi
+
 dup3
 dup2
 add
@@ -418,6 +429,7 @@ push1 0x01
 add
 push1 0xe9
 jump
+
 jumpdest
 swap2
 add
@@ -426,11 +438,13 @@ swap3
 eq
 push2 0x013b
 jumpi
+
 swap1
 push1 0x02
 sstore
 push2 0x0146
 jump
+
 jumpdest
 swap1
 pop
@@ -440,6 +454,7 @@ sstore
 push0
 push1 0x03
 sstore
+
 jumpdest
 push0
 sload
@@ -449,8 +464,10 @@ eq
 iszero
 push2 0x0173
 jumpi
+
 pop
 push0
+
 jumpdest
 push1 0x01
 sload
@@ -461,16 +478,19 @@ add
 gt
 push2 0x0188
 jumpi
+
 pop
 pop
 push0
 push2 0x018e
 jump
+
 jumpdest
 add
 push1 0x01
 swap1
 sub
+
 jumpdest
 push0
 sstore
@@ -481,6 +501,7 @@ push1 0x74
 mul
 push0
 return
+
 jumpdest
 push0
 push0
@@ -528,7 +549,7 @@ The defining features of this EIP are:
 1. ***Increasing the `MAX_EFFECTIVE_BALANCE`, while creating a `MIN_ACTIVATION_BALANCE`.*** The core feature of allowing variable size validators.
 2. ***Allowing for multiple validator indices to be combined through the protocol.*** A mechanism by which large node operators can combine validators without cycling through the exit and activation queues.
 3. ***Adding execution layer partial withdrawals (part of [EIP-7002](./eip-7002.md)).*** Allowing Execution Layer messages to trigger partial withdrawals in addition to full exits (e.g., a `100 ETH` validator can remove up to `68 ETH` without exiting the validator).
-4. ***Removing the initial slashing penalty (still in discussion).*** This reduces the risk of consolidation for large validators. 
+4. ***Removing the initial slashing penalty (still in discussion).*** This reduces the risk of consolidation for large validators.
 
 The [Rationale](#rationale) section contains an explanation for each of these proposed core features. A sketch of the resulting changes to the consensus layer is included below.
 
@@ -543,7 +564,7 @@ The [Rationale](#rationale) section contains an explanation for each of these pr
 9. Modify `process_registry_updates` to activate all eligible validators.
 10. Add a per-epoch helper, `process_pending_balance_deposits`, to consume some of the pending deposits.
 10. Modify `get_validator_from_deposit` to initialize the effective balance to zero (it's updated by the pending deposit flow).
-11. Modify `apply_deposit` to store incoming deposits in `state.pending_balance_deposits`. 
+11. Modify `apply_deposit` to store incoming deposits in `state.pending_balance_deposits`.
 12. Modify `is_aggregator` to be weight-based.
 13. Modify `compute_weak_subjectivity_period` to use the new churn limit function.
 14. Add `has_compounding_withdrawal_credential` to check for the `0x02` credential.
@@ -556,11 +577,11 @@ The [Rationale](#rationale) section contains an explanation for each of these pr
 
 ## Rationale
 
-This EIP aims to reduce the total number of validators without changing anything about the economic security of the protocol. It provides a mechanism by which large node operators who control significant amounts of stake can consolidate into fewer validators. We analyze the reasoning behind each of the core features. 
+This EIP aims to reduce the total number of validators without changing anything about the economic security of the protocol. It provides a mechanism by which large node operators who control significant amounts of stake can consolidate into fewer validators. We analyze the reasoning behind each of the core features.
 
-1. ***Increasing the `MAX_EFFECTIVE_BALANCE`, while creating a `MIN_ACTIVATION_BALANCE`.*** 
+1. ***Increasing the `MAX_EFFECTIVE_BALANCE`, while creating a `MIN_ACTIVATION_BALANCE`.***
     * *While increasing the `MAX_EFFECTIVE_BALANCE` to allow larger-stake validators, it is important to keep the lower bound of `32 ETH` (by introducing a new constant – `MIN_ACTIVATION_BALANCE`) to encourage solo-staking.*
-2. ***Allowing for multiple validator indices to be combined through the protocol.*** 
+2. ***Allowing for multiple validator indices to be combined through the protocol.***
     * *For large staking pools that already control thousands of validators, exiting and re-entering would be extremely slow and costly. The adoption of the EIP will be much higher by allowing in-protocol consolidation.*
 3. ***Adding execution layer partial withdrawals (part of [EIP-7002](./eip-7002.md)).***
     * *For validators that choose to raise their effective balance ceiling, allowing for custom partial withdrawals triggered from the execution layer increases the flexibility of the staking configurations. Validators can choose when and how much they withdraw but will have to pay gas for the EL transaction.*
@@ -595,6 +616,35 @@ Sync committee selection is also already weighted by effective balance, so this
 
 This proposal maintains the activation and exit churn invariants limiting active weight instead of validator count. Balance top-ups are now handled explicitly, being subject to the same activation queue as full deposits.
 
+### Fee Overpayment
+
+Calls to the system contract require a fee payment defined by the current contract state. Overpaid fees are not returned to the caller. It is not generally possible to compute the exact required fee amount ahead of time. When adding a consolidation request from a contract, the contract can perform a read operation to check for the current fee and then pay exactly the required amount. Here is an example in Solidity:
+
+```
+function addConsolidation(bytes memory srcPubkey, bytes memory targetPubkey) private {
+    assert(srcPubkey.length == 48);
+    assert(targetPubkey.length == 48);
+
+    // Read current fee from the contract.
+    (bool readOK, bytes memory feeData) = ConsolidationsContract.staticcall('');
+    if (!readOK) {
+        revert('reading fee failed');
+    }
+    uint256 fee = uint256(bytes32(feeData));
+
+    // Add the request.
+    bytes memory callData = bytes.concat(srcPubkey, targetPubkey);
+    (bool writeOK,) = ConsolidationsContract.call{value: fee}(callData);
+    if (!writeOK) {
+        revert('adding request failed');
+    }
+}
+```
+
+Note: the system contract uses the EVM `CALLER` operation (Solidity: `msg.sender`) to get the address used in the consolidation request, i.e. the address that calls the system contract must match the 0x01 withdrawal credential recorded in the beacon state.
+
+Using an EOA to request consolidations will always result in overpayment of fees. There is no way for an EOA to use a wrapper contract to request a consolidation. And even if a way existed, the gas cost of returning the overage would likely be higher than the overage itself. If requesting consolidations from an EOA to the system contract is desired, we recommend that users perform transaction simulations to estimate a reasonable fee amount to send.
+
 ## Copyright
 
 Copyright and related rights waived via [CC0](../LICENSE.md).