Add 0_deposit-contract.md
This commit is contained in:
Justin Drake
parent
a103e79e67
commit
0bdd8e778b
|
|
@ -97,12 +97,6 @@
|
||||||
- [`activate_validator`](#activate_validator)
|
- [`activate_validator`](#activate_validator)
|
||||||
- [`initiate_validator_exit`](#initiate_validator_exit)
|
- [`initiate_validator_exit`](#initiate_validator_exit)
|
||||||
- [`slash_validator`](#slash_validator)
|
- [`slash_validator`](#slash_validator)
|
||||||
- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract)
|
|
||||||
- [Deposit arguments](#deposit-arguments)
|
|
||||||
- [Withdrawal credentials](#withdrawal-credentials)
|
|
||||||
- [`Deposit` logs](#deposit-logs)
|
|
||||||
- [`Eth2Genesis` log](#eth2genesis-log)
|
|
||||||
- [Vyper code](#vyper-code)
|
|
||||||
- [On genesis](#on-genesis)
|
- [On genesis](#on-genesis)
|
||||||
- [Beacon chain state transition function](#beacon-chain-state-transition-function)
|
- [Beacon chain state transition function](#beacon-chain-state-transition-function)
|
||||||
- [State caching](#state-caching)
|
- [State caching](#state-caching)
|
||||||
|
|
@ -182,7 +176,6 @@ These configurations are updated for releases, but may be out of sync during `de
|
||||||
|
|
||||||
| Name | Value |
|
| Name | Value |
|
||||||
| - | - |
|
| - | - |
|
||||||
| `DEPOSIT_CONTRACT_ADDRESS` | **TBD** |
|
|
||||||
| `DEPOSIT_CONTRACT_TREE_DEPTH` | `2**5` (= 32) |
|
| `DEPOSIT_CONTRACT_TREE_DEPTH` | `2**5` (= 32) |
|
||||||
|
|
||||||
### Gwei values
|
### Gwei values
|
||||||
|
|
@ -1267,49 +1260,6 @@ def slash_validator(state: BeaconState, slashed_index: ValidatorIndex, whistlebl
|
||||||
decrease_balance(state, slashed_index, whistleblowing_reward)
|
decrease_balance(state, slashed_index, whistleblowing_reward)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Ethereum 1.0 deposit contract
|
|
||||||
|
|
||||||
The initial deployment phases of Ethereum 2.0 are implemented without consensus changes to Ethereum 1.0. A deposit contract at address `DEPOSIT_CONTRACT_ADDRESS` is added to Ethereum 1.0 for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the shards in phase 2, i.e. when the EVM2.0 is deployed and the shards have state.
|
|
||||||
|
|
||||||
### Deposit arguments
|
|
||||||
|
|
||||||
The deposit contract has a single `deposit` function which takes as argument a SimpleSerialize'd `DepositData`.
|
|
||||||
|
|
||||||
### Withdrawal credentials
|
|
||||||
|
|
||||||
One of the `DepositData` fields is `withdrawal_credentials`. It is a commitment to credentials for withdrawals to shards. The first byte of `withdrawal_credentials` is a version number. As of now the only expected format is as follows:
|
|
||||||
|
|
||||||
* `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX_BYTE`
|
|
||||||
* `withdrawal_credentials[1:] == hash(withdrawal_pubkey)[1:]` where `withdrawal_pubkey` is a BLS pubkey
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
### `Deposit` logs
|
|
||||||
|
|
||||||
Every Ethereum 1.0 deposit, of size between `MIN_DEPOSIT_AMOUNT` and `MAX_DEPOSIT_AMOUNT`, emits a `Deposit` log for consumption by the beacon chain. The deposit contract does little validation, pushing most of the validator onboarding logic to the beacon chain. In particular, the proof of possession (a BLS12 signature) is not verified by the deposit contract.
|
|
||||||
|
|
||||||
### `Eth2Genesis` log
|
|
||||||
|
|
||||||
When a sufficient amount of full deposits have been made, the deposit contract emits the `Eth2Genesis` log. The beacon chain state may then be initialized by calling the `get_genesis_beacon_state` function (defined below) where:
|
|
||||||
|
|
||||||
* `genesis_time` equals `time` in the `Eth2Genesis` log
|
|
||||||
* `latest_eth1_data.deposit_root` equals `deposit_root` in the `Eth2Genesis` log
|
|
||||||
* `latest_eth1_data.deposit_count` equals `deposit_count` in the `Eth2Genesis` log
|
|
||||||
* `latest_eth1_data.block_hash` equals the hash of the block that included the log
|
|
||||||
* `genesis_validator_deposits` is a list of `Deposit` objects built according to the `Deposit` logs up to the deposit that triggered the `Eth2Genesis` log, processed in the order in which they were emitted (oldest to newest)
|
|
||||||
|
|
||||||
### Vyper code
|
|
||||||
|
|
||||||
The source for the Vyper contract lives in a [separate repository](https://github.com/ethereum/deposit_contract) at [https://github.com/ethereum/deposit_contract/blob/master/deposit_contract/contracts/validator_registration.v.py](https://github.com/ethereum/deposit_contract/blob/master/deposit_contract/contracts/validator_registration.v.py).
|
|
||||||
|
|
||||||
Note: to save ~10x on gas this contract uses a somewhat unintuitive progressive Merkle root calculation algo that requires only O(log(n)) storage. See https://github.com/ethereum/research/blob/master/beacon_chain_impl/progressive_merkle_tree.py for an implementation of the same algo in python tested for correctness.
|
|
||||||
|
|
||||||
For convenience, we provide the interface to the contract here:
|
|
||||||
|
|
||||||
* `__init__()`: initializes the contract
|
|
||||||
* `get_deposit_root() -> bytes32`: returns the current root of the deposit tree
|
|
||||||
* `deposit(bytes[512])`: adds a deposit instance to the deposit tree, incorporating the input argument and the value transferred in the given call. Note: the amount of value transferred *must* be within `MIN_DEPOSIT_AMOUNT` and `MAX_DEPOSIT_AMOUNT`, inclusive. Each of these constants are specified in units of Gwei.
|
|
||||||
|
|
||||||
## On genesis
|
## On genesis
|
||||||
|
|
||||||
When enough full deposits have been made to the deposit contract, an `Eth2Genesis` log is emitted. Construct a corresponding `genesis_state` and `genesis_block` as follows:
|
When enough full deposits have been made to the deposit contract, an `Eth2Genesis` log is emitted. Construct a corresponding `genesis_state` and `genesis_block` as follows:
|
||||||
|
|
@ -1348,6 +1298,7 @@ def get_genesis_beacon_state(genesis_validator_deposits: List[Deposit],
|
||||||
return state
|
return state
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Beacon chain state transition function
|
## Beacon chain state transition function
|
||||||
|
|
||||||
We now define the state transition function. At a high level, the state transition is made up of four parts:
|
We now define the state transition function. At a high level, the state transition is made up of four parts:
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,76 @@
|
||||||
|
# Ethereum 2.0 Phase 0 -- Deposit Contract
|
||||||
|
|
||||||
|
**NOTICE**: This document is a work in progress for researchers and implementers.
|
||||||
|
|
||||||
|
## Table of contents
|
||||||
|
<!-- TOC -->
|
||||||
|
|
||||||
|
- [Ethereum 2.0 Phase 0 -- Deposit Contract](#ethereum-20-phase-0----deposit-contract)
|
||||||
|
- [Table of contents](#table-of-contents)
|
||||||
|
- [Introduction](#introduction)
|
||||||
|
- [Constants](#constants)
|
||||||
|
- [Deposit contract](#time-parameters)
|
||||||
|
- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract)
|
||||||
|
- [Deposit arguments](#deposit-arguments)
|
||||||
|
- [Withdrawal credentials](#withdrawal-credentials)
|
||||||
|
- [`Deposit` logs](#deposit-logs)
|
||||||
|
- [`Eth2Genesis` log](#eth2genesis-log)
|
||||||
|
- [Vyper code](#vyper-code)
|
||||||
|
|
||||||
|
<!-- /TOC -->
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
This document represents is the specification for the beacon chain deposit contract, part of Ethereum 2.0 phase 0.
|
||||||
|
|
||||||
|
## Constants
|
||||||
|
|
||||||
|
### Deposit contract
|
||||||
|
|
||||||
|
| Name | Value |
|
||||||
|
| - | - |
|
||||||
|
| `DEPOSIT_CONTRACT_ADDRESS` | **TBD** |
|
||||||
|
| `DEPOSIT_CONTRACT_TREE_DEPTH` | `2**5` (= 32) |
|
||||||
|
|
||||||
|
## Ethereum 1.0 deposit contract
|
||||||
|
|
||||||
|
The initial deployment phases of Ethereum 2.0 are implemented without consensus changes to Ethereum 1.0. A deposit contract at address `DEPOSIT_CONTRACT_ADDRESS` is added to Ethereum 1.0 for deposits of ETH to the beacon chain. Validator balances will be withdrawable to the shards in phase 2, i.e. when the EVM2.0 is deployed and the shards have state.
|
||||||
|
|
||||||
|
### Deposit arguments
|
||||||
|
|
||||||
|
The deposit contract has a single `deposit` function which takes as argument a SimpleSerialize'd `DepositData`.
|
||||||
|
|
||||||
|
### Withdrawal credentials
|
||||||
|
|
||||||
|
One of the `DepositData` fields is `withdrawal_credentials`. It is a commitment to credentials for withdrawals to shards. The first byte of `withdrawal_credentials` is a version number. As of now the only expected format is as follows:
|
||||||
|
|
||||||
|
* `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX_BYTE`
|
||||||
|
* `withdrawal_credentials[1:] == hash(withdrawal_pubkey)[1:]` where `withdrawal_pubkey` is a BLS pubkey
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
### `Deposit` logs
|
||||||
|
|
||||||
|
Every Ethereum 1.0 deposit, of size between `MIN_DEPOSIT_AMOUNT` and `MAX_DEPOSIT_AMOUNT`, emits a `Deposit` log for consumption by the beacon chain. The deposit contract does little validation, pushing most of the validator onboarding logic to the beacon chain. In particular, the proof of possession (a BLS12 signature) is not verified by the deposit contract.
|
||||||
|
|
||||||
|
### `Eth2Genesis` log
|
||||||
|
|
||||||
|
When a sufficient amount of full deposits have been made, the deposit contract emits the `Eth2Genesis` log. The beacon chain state may then be initialized by calling the `get_genesis_beacon_state` function (defined below) where:
|
||||||
|
|
||||||
|
* `genesis_time` equals `time` in the `Eth2Genesis` log
|
||||||
|
* `latest_eth1_data.deposit_root` equals `deposit_root` in the `Eth2Genesis` log
|
||||||
|
* `latest_eth1_data.deposit_count` equals `deposit_count` in the `Eth2Genesis` log
|
||||||
|
* `latest_eth1_data.block_hash` equals the hash of the block that included the log
|
||||||
|
* `genesis_validator_deposits` is a list of `Deposit` objects built according to the `Deposit` logs up to the deposit that triggered the `Eth2Genesis` log, processed in the order in which they were emitted (oldest to newest)
|
||||||
|
|
||||||
|
### Vyper code
|
||||||
|
|
||||||
|
The source for the Vyper contract lives in a [separate repository](https://github.com/ethereum/deposit_contract) at [https://github.com/ethereum/deposit_contract/blob/master/deposit_contract/contracts/validator_registration.v.py](https://github.com/ethereum/deposit_contract/blob/master/deposit_contract/contracts/validator_registration.v.py).
|
||||||
|
|
||||||
|
Note: to save ~10x on gas this contract uses a somewhat unintuitive progressive Merkle root calculation algo that requires only O(log(n)) storage. See https://github.com/ethereum/research/blob/master/beacon_chain_impl/progressive_merkle_tree.py for an implementation of the same algo in python tested for correctness.
|
||||||
|
|
||||||
|
For convenience, we provide the interface to the contract here:
|
||||||
|
|
||||||
|
* `__init__()`: initializes the contract
|
||||||
|
* `get_deposit_root() -> bytes32`: returns the current root of the deposit tree
|
||||||
|
* `deposit(bytes[512])`: adds a deposit instance to the deposit tree, incorporating the input argument and the value transferred in the given call. Note: the amount of value transferred *must* be within `MIN_DEPOSIT_AMOUNT` and `MAX_DEPOSIT_AMOUNT`, inclusive. Each of these constants are specified in units of Gwei.
|
||||||
|
|
@ -17,7 +17,7 @@
|
||||||
|
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
This document represents is the specification for the beacon chain fork choice rule, part of phase 0 of Ethereum 2.0.
|
This document represents is the specification for the beacon chain fork choice rule, part of Ethereum 2.0 phase 0.
|
||||||
|
|
||||||
## Constants
|
## Constants
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue