Restrict builder deposits to payload builders (#5439)

Alternative to #5435
which restricts builder registrations to the payload builder version in
Gloas, i.e. only builders with `version` of `PAYLOAD_BUILDER_VERSION`
can exist for now.

Builder deposit requests are ignored unless the withdrawal credentials
start with `BUILDER_WITHDRAWAL_PREFIX`. This keeps Gloas strict about
accepted builder deposit credentials while leaving room for future forks
to define additional builder versions.

Author: nflaig

pysetup/spec_builders/heze.py

@@ -68,7 +68,6 @@ def is_inclusion_list_satisfied(self: ExecutionEngine,
     def deprecate_functions(cls) -> set[str]:
         return {
             "initialize_ptc_window",
-            "is_builder_withdrawal_credential",
             "is_pending_validator",
             "onboard_builders_from_pending_deposits",
             "upgrade_to_gloas",

specs/gloas/beacon-chain.md

@@ -1774,13 +1774,17 @@ caching should account for this behavior.
 
 ```python
 def process_builder_deposit_request(state: BeaconState, request: BuilderDepositRequest) -> None:
+    # Ignore deposits with unexpected withdrawal credential prefixes
+    if not is_builder_withdrawal_credential(request.withdrawal_credentials):
+        return
+
     builder_pubkeys = [b.pubkey for b in state.builders]
     if request.pubkey not in builder_pubkeys:
         if is_valid_builder_deposit_signature(request):
             add_builder_to_registry(
                 state,
                 request.pubkey,
-                uint8(request.withdrawal_credentials[0]),
+                PAYLOAD_BUILDER_VERSION,
                 ExecutionAddress(request.withdrawal_credentials[12:]),
                 request.amount,
                 state.slot,

specs/gloas/builder.md

@@ -43,13 +43,15 @@ must include:
 
 - `pubkey`: The builder's BLS public key.
 - `withdrawal_credentials`: The withdrawal credentials, where the first byte is
-  the builder version and the last 20 bytes are the execution-layer address that
-  will receive withdrawals. For the version, execution payload builders should
-  use `PAYLOAD_BUILDER_VERSION`.
+  `BUILDER_WITHDRAWAL_PREFIX` and the last 20 bytes are the execution-layer
+  address that will receive withdrawals.
 - `amount`: At least `MIN_DEPOSIT_AMOUNT` gwei.
 - `signature`: BLS proof of possession over the corresponding `DepositMessage`
   under `DOMAIN_BUILDER_DEPOSIT`.
 
+*Note*: A builder deposit request with withdrawal credentials that do not start
+with `BUILDER_WITHDRAWAL_PREFIX` will be ignored and the funds will be lost.
+
 *Note*: Builders may be onboarded at the fork by submitting a deposit to the
 validator deposit contract with a `BUILDER_WITHDRAWAL_PREFIX` withdrawal
 credential. This must be done late enough that the deposit is still pending at

tests/core/pyspec/eth_consensus_specs/test/gloas/block_processing/test_process_builder_deposit_request.py

@@ -80,17 +80,14 @@ def test_process_builder_deposit_request__new_builder(spec, state):
 
 @with_gloas_and_later
 @spec_state_test
-def test_process_builder_deposit_request__new_builder_nonzero_version(spec, state):
+def test_process_builder_deposit_request__new_builder_non_builder_withdrawal_prefix(spec, state):
     """
-    Test fresh builder deposit with a non-zero version.
+    Test fresh builder deposit with a non-builder withdrawal prefix.
 
-    The version (the first byte of the withdrawal credentials) is not
-    constrained: it is recorded on the builder verbatim and is committed to by
-    the proof of possession.
+    Gloas drops new builder deposits that do not use BUILDER_WITHDRAWAL_PREFIX.
     """
     amount = spec.MIN_DEPOSIT_AMOUNT
-    version = spec.uint8(7)
-    withdrawal_credentials = bytes([version]) + b"\x00" * 11 + b"\x42" * 20
+    withdrawal_credentials = b"\x01" + b"\x00" * 11 + b"\x42" * 20
     builder_deposit_request = prepare_builder_deposit_request(
         spec, state, amount, withdrawal_credentials=withdrawal_credentials, signed=True
     )
@@ -103,16 +100,9 @@ def test_process_builder_deposit_request__new_builder_nonzero_version(spec, stat
         state,
         pre_state,
         builder_deposit_request=builder_deposit_request,
-        expected_builder_balance=amount,
-        expected_execution_address=spec.ExecutionAddress(
-            builder_deposit_request.withdrawal_credentials[12:]
-        ),
-        expected_builder_withdrawable_epoch=spec.FAR_FUTURE_EPOCH,
+        state_unchanged=True,
     )
 
-    builder_index = [b.pubkey for b in state.builders].index(builder_deposit_request.pubkey)
-    assert state.builders[builder_index].version == version
-
 
 @with_gloas_and_later
 @spec_state_test
@@ -403,16 +393,16 @@ def test_process_builder_deposit_request__top_up_last_index(spec, state):
 @spec_state_test
 def test_process_builder_deposit_request__top_up_ignores_request_fields(spec, state):
     """
-    Test that a top-up for an existing builder ignores the supplied withdrawal
-    credentials. The existing registration is unchanged.
+    Test that a top-up for an existing builder ignores the supplied execution
+    address. The existing registration is unchanged.
     """
     builder_pubkey = state.builders[0].pubkey
     amount = spec.MIN_DEPOSIT_AMOUNT
     pre_balance = state.builders[0].balance
     pre_builder_count = len(state.builders)
 
     # Use withdrawal credentials that differ from the registration
-    withdrawal_credentials = b"\x07" + b"\x00" * 11 + b"\x42" * 20
+    withdrawal_credentials = spec.BUILDER_WITHDRAWAL_PREFIX + b"\x00" * 11 + b"\x42" * 20
     assert state.builders[0].version != spec.uint8(withdrawal_credentials[0])
     assert state.builders[0].execution_address != spec.ExecutionAddress(withdrawal_credentials[12:])
 
@@ -441,6 +431,34 @@ def test_process_builder_deposit_request__top_up_ignores_request_fields(spec, st
     assert state.builders[0].execution_address == pre_state.builders[0].execution_address
 
 
+@with_gloas_and_later
+@spec_state_test
+def test_process_builder_deposit_request__top_up_non_builder_withdrawal_prefix(spec, state):
+    """Test that top-ups with a non-builder withdrawal prefix are ignored."""
+    builder_pubkey = state.builders[0].pubkey
+    amount = spec.MIN_DEPOSIT_AMOUNT
+    withdrawal_credentials = b"\x01" + b"\x00" * 11 + b"\x42" * 20
+    builder_deposit_request = prepare_builder_deposit_request(
+        spec,
+        state,
+        amount,
+        pubkey=builder_pubkey,
+        withdrawal_credentials=withdrawal_credentials,
+        signed=True,
+    )
+    pre_state = state.copy()
+
+    yield from run_builder_deposit_request_processing(spec, state, builder_deposit_request)
+
+    assert_process_builder_deposit_request(
+        spec,
+        state,
+        pre_state,
+        builder_deposit_request=builder_deposit_request,
+        state_unchanged=True,
+    )
+
+
 #
 # Invalid deposits
 #

tests/core/pyspec/eth_consensus_specs/test/helpers/builder_deposit_requests.py

@@ -42,8 +42,8 @@ def prepare_process_builder_deposit_request(
         builder_index: Index for builder pubkey lookup. Default: len(state.builders)
             (a new builder).
         pubkey: Explicit BLSPubkey. Default: derived from builder_index.
-        withdrawal_credentials: Explicit Bytes32 credentials. Default: version zero
-            followed by an eth1 address derived from the pubkey.
+        withdrawal_credentials: Explicit Bytes32 credentials. Default:
+            BUILDER_WITHDRAWAL_PREFIX followed by an eth1 address derived from the pubkey.
         amount: Deposit amount in Gwei. Default: MIN_ACTIVATION_BALANCE.
         signed: If True, sign with a valid builder deposit signature.
         builders: Override state.builders list entirely. Use [] for empty registry.
@@ -70,8 +70,10 @@ def prepare_process_builder_deposit_request(
     if withdrawal_credentials is not None:
         effective_withdrawal_credentials = withdrawal_credentials
     else:
-        # Version zero followed by an eth1 address derived from the pubkey
-        effective_withdrawal_credentials = b"\x00" * 12 + spec.hash(effective_pubkey)[12:]
+        # Builder withdrawal prefix followed by an eth1 address derived from the pubkey
+        effective_withdrawal_credentials = (
+            spec.BUILDER_WITHDRAWAL_PREFIX + b"\x00" * 11 + spec.hash(effective_pubkey)[12:]
+        )
 
     # Phase 3: Apply state overrides (before creating request)
     if builders is not None:

tests/core/pyspec/eth_consensus_specs/test/helpers/deposits.py

@@ -280,8 +280,10 @@ def prepare_builder_deposit_request(
         privkey = builder_pubkey_to_privkey[pubkey]
 
     if withdrawal_credentials is None:
-        # Version zero followed by an eth1 address derived from the pubkey
-        withdrawal_credentials = b"\x00" * 12 + spec.hash(pubkey)[12:]
+        # Builder withdrawal prefix followed by an eth1 address derived from the pubkey
+        withdrawal_credentials = (
+            spec.BUILDER_WITHDRAWAL_PREFIX + b"\x00" * 11 + spec.hash(pubkey)[12:]
+        )
 
     request = spec.BuilderDepositRequest(
         pubkey=pubkey,