From 6b728c18800cc0611d8630e35e15bba4003f6784 Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Fri, 11 Dec 2020 14:46:16 -0700 Subject: [PATCH] add eth1 withdrawal credentials to spec --- specs/phase0/beacon-chain.md | 5 +++ specs/phase0/deposit-contract.md | 13 ++++-- specs/phase0/validator.md | 42 +++++++++++++++--- .../block_processing/test_process_deposit.py | 43 +++++++++++++++++++ 4 files changed, 93 insertions(+), 10 deletions(-) diff --git a/specs/phase0/beacon-chain.md b/specs/phase0/beacon-chain.md index b47558484..7fdf027bc 100644 --- a/specs/phase0/beacon-chain.md +++ b/specs/phase0/beacon-chain.md @@ -13,6 +13,7 @@ - [Misc](#misc) - [Gwei values](#gwei-values) - [Initial values](#initial-values) + - [Validator withdrawal credential versions](#validator-withdrawal-credential-versions) - [Time parameters](#time-parameters) - [State list lengths](#state-list-lengths) - [Rewards and penalties](#rewards-and-penalties) @@ -209,7 +210,11 @@ The following values are (non-configurable) constants used throughout the specif | Name | Value | | - | - | | `GENESIS_FORK_VERSION` | `Version('0x00000000')` | + +### Validator withdrawal credential versions + | `BLS_WITHDRAWAL_PREFIX` | `Bytes1('0x00')` | +| `ETH1_ADDRESS_WITHDRAWAL_PREFIX` | `Bytes1('0x01')` | ### Time parameters diff --git a/specs/phase0/deposit-contract.md b/specs/phase0/deposit-contract.md index 23d831917..ef21d35e0 100644 --- a/specs/phase0/deposit-contract.md +++ b/specs/phase0/deposit-contract.md @@ -58,12 +58,17 @@ The amount of ETH (rounded down to the closest Gwei) sent to the deposit contrac #### Withdrawal credentials -One of the `DepositData` fields is `withdrawal_credentials`. It is a commitment to credentials for withdrawing validator balance (e.g. to another validator, or to shards). The first byte of `withdrawal_credentials` is a version number. As of now, the only expected format is as follows: +One of the `DepositData` fields is `withdrawal_credentials`. -* `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX` -* `withdrawal_credentials[1:] == hash(withdrawal_pubkey)[1:]` where `withdrawal_pubkey` is a BLS pubkey +This field is a commitment to credentials for withdrawing validator balance (e.g. to another validator, or to shards). +The first byte of `withdrawal_credentials` is a version number. The remaining +bytes are content specific to the version. -The private key corresponding to `withdrawal_pubkey` will be required to initiate a withdrawal. It can be stored separately until a withdrawal is required, e.g. in cold storage. +Currently, `BLS_WITHDRAWAL_PREFIX` and `ETH1_ADDRESS_WITHDRAWAL_PREFIX` +versioned withdrawal credentials are supported. Read more in the [validator guide](./validator.md). + +*Note*: The deposit contract does *not* validate withdrawal credentials. +Thus, new versions can be added without modifications of the deposit contract. #### `DepositEvent` log diff --git a/specs/phase0/validator.md b/specs/phase0/validator.md index cb45e65e8..4fafcbad4 100644 --- a/specs/phase0/validator.md +++ b/specs/phase0/validator.md @@ -15,7 +15,9 @@ This is an accompanying document to [Ethereum 2.0 Phase 0 -- The Beacon Chain](. - [Becoming a validator](#becoming-a-validator) - [Initialization](#initialization) - [BLS public key](#bls-public-key) - - [BLS withdrawal key](#bls-withdrawal-key) + - [Withdrawal credentials](#withdrawal-credentials) + - [BLS key credentials](#bls-key-credentials) + - [Eth1 address credentials](#eth1-address-credentials) - [Submit deposit](#submit-deposit) - [Process deposit](#process-deposit) - [Validator index](#validator-index) @@ -100,14 +102,42 @@ A validator must initialize many parameters locally before submitting a deposit Validator public keys are [G1 points](beacon-chain.md#bls-signatures) on the [BLS12-381 curve](https://z.cash/blog/new-snark-curve). A private key, `privkey`, must be securely generated along with the resultant `pubkey`. This `privkey` must be "hot", that is, constantly available to sign data throughout the lifetime of the validator. -#### BLS withdrawal key +#### Withdrawal credentials -A secondary withdrawal private key, `withdrawal_privkey`, must also be securely generated along with the resultant `withdrawal_pubkey`. This `withdrawal_privkey` does not have to be available for signing during the normal lifetime of a validator and can live in "cold storage". +The `withdrawal_credentials` ultimately control the deposited ETH once the +validator has exited and is withdrawable. The 0th byte of this 32-byte field, +called the "withdrawal prefix" defines the withdrawal credential version +while the remaining 31 bytes define the version-specific content. -The validator constructs their `withdrawal_credentials` via the following: +The following withdrawal credentials versions are currently supported. The +validator must choose and construct a version for the `withdrawal_credentials` field. -* Set `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX`. -* Set `withdrawal_credentials[1:] == hash(withdrawal_pubkey)[1:]`. +##### BLS key credentials + +BLS withdrawal credentials are controlled by a secondary withdrawal BLS private key, `bls_withdrawal_privkey`. +This key is securely generated along with the resultant `bls_withdrawal_pubkey`. +This `withdrawal_privkey` does not have to be available for signing during +the normal lifetime of a validator and can live in "cold storage". + +The validator constructs `withdrawal_credentials` as the following: +* Set `withdrawal_credentials[:1] = BLS_WITHDRAWAL_PREFIX`. +* Set `withdrawal_credentials[1:] = hash(bls_withdrawal_pubkey)[1:]`. + +##### Eth1 address credentials + +Eth1 address credentials are controlled by an eth1 address. This can be an either an externally owned account or a contract. + +The withdrawal to the address specified will be a normal ETH transfer (with no payload other than the validator's ETH) +triggered by an eth1 transaction that will handle gas price/limit and payment of fees. + +As long as such a withdrawal account/contract can receive ETH transfers, +the future withdrawal protocol is agnostic to all other implementation details. + +The validator selects a 20-byte eth1 address, `eth1_withdrawal_address`, and constructs `withdrawal_credentials` as the following: +* Set `withdrawal_credentials[:1] = ETH1_ADDRESS_WITHDRAWAL_PREFIX`. +* Set `withdrawal_credentials[12:] = eth1_withdrawal_address`. + +*Note*: Bytes `withdrawal_credentials[1:12]` remain the default `0x00` value. ### Submit deposit diff --git a/tests/core/pyspec/eth2spec/test/phase0/block_processing/test_process_deposit.py b/tests/core/pyspec/eth2spec/test/phase0/block_processing/test_process_deposit.py index b7a0de6c8..36e76f46c 100644 --- a/tests/core/pyspec/eth2spec/test/phase0/block_processing/test_process_deposit.py +++ b/tests/core/pyspec/eth2spec/test/phase0/block_processing/test_process_deposit.py @@ -94,6 +94,49 @@ def test_new_deposit_over_max(spec, state): yield from run_deposit_processing(spec, state, deposit, validator_index) +@with_all_phases +@spec_state_test +def test_new_deposit_eth1_withdrawal_credentials(spec, state): + # fresh deposit = next validator index = validator appended to registry + validator_index = len(state.validators) + withdrawal_credentials = ( + spec.ETH1_ADDRESS_WITHDRAWAL_PREFIX + + b'\x00' * 11 # specified 0s + + b'\x59' * 20 # a 20-byte eth1 address + ) + amount = spec.MAX_EFFECTIVE_BALANCE + deposit = prepare_state_and_deposit( + spec, state, + validator_index, + amount, + withdrawal_credentials=withdrawal_credentials, + signed=True, + ) + + yield from run_deposit_processing(spec, state, deposit, validator_index) + + +@with_all_phases +@spec_state_test +def test_new_deposit_non_versioned_withdrawal_credentials(spec, state): + # fresh deposit = next validator index = validator appended to registry + validator_index = len(state.validators) + withdrawal_credentials = ( + b'\xFF' # Non specified withdrawal credentials version + + b'\x02' * 31 # Garabage bytes + ) + amount = spec.MAX_EFFECTIVE_BALANCE + deposit = prepare_state_and_deposit( + spec, state, + validator_index, + amount, + withdrawal_credentials=withdrawal_credentials, + signed=True, + ) + + yield from run_deposit_processing(spec, state, deposit, validator_index) + + @with_all_phases @spec_state_test @always_bls