eth2.0-specs/specs/core/0_deposit-contract.md

94 lines
4.8 KiB
Markdown
Raw Normal View History

2019-04-22 13:29:19 +00:00
# Ethereum 2.0 Phase 0 -- Deposit Contract
2019-05-06 15:30:32 +00:00
**Notice**: This document is a work-in-progress for researchers and implementers.
2019-04-22 13:29:19 +00:00
## 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)
2019-04-25 07:02:14 +00:00
- [Gwei values](#gwei-values)
2019-04-25 07:06:21 +00:00
- [Contract](#contract)
2019-04-22 13:29:19 +00:00
- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract)
2019-04-25 07:06:21 +00:00
- [Arguments](#arguments)
- [Withdrawal credentials](#withdrawal-credentials)
- [Amount](#amount)
- [Event logs](#event-logs)
2019-04-22 13:29:19 +00:00
- [`Deposit` logs](#deposit-logs)
- [`Eth2Genesis` log](#eth2genesis-log)
2019-04-25 07:06:21 +00:00
- [Vyper code](#vyper-code)
2019-04-22 13:29:19 +00:00
<!-- /TOC -->
## Introduction
2019-05-06 15:30:32 +00:00
This document represents the specification for the beacon chain deposit contract, part of Ethereum 2.0 Phase 0.
2019-04-22 13:29:19 +00:00
## Constants
2019-04-25 07:02:14 +00:00
### Gwei values
| Name | Value | Unit |
| - | - | - |
| `FULL_DEPOSIT_AMOUNT` | `32 * 10**9` | Gwei |
2019-04-25 07:06:21 +00:00
### Contract
2019-04-22 13:29:19 +00:00
| Name | Value |
| - | - |
| `DEPOSIT_CONTRACT_ADDRESS` | **TBD** |
| `DEPOSIT_CONTRACT_TREE_DEPTH` | `2**5` (= 32) |
2019-05-06 15:30:32 +00:00
| `CHAIN_START_FULL_DEPOSIT_THRESHOLD` | `2**16` (= 65,536) |
2019-04-22 13:29:19 +00:00
## Ethereum 1.0 deposit contract
2019-05-06 15:30:32 +00:00
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 EVM 2.0 is deployed and the shards have state).
2019-04-22 13:29:19 +00:00
2019-04-25 07:06:21 +00:00
### Arguments
2019-04-22 13:29:19 +00:00
2019-04-26 13:59:12 +00:00
The deposit contract has a `deposit` function which takes the amount in Ethereum 1.0 transaction, and arguments `pubkey: bytes[48], withdrawal_credentials: bytes[32], signature: bytes[96]` corresponding to `DepositData`.
2019-04-22 13:29:19 +00:00
2019-04-25 07:06:21 +00:00
#### Withdrawal credentials
2019-04-22 13:29:19 +00:00
2019-05-06 15:30:32 +00:00
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:
2019-04-22 13:29:19 +00:00
* `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.
2019-04-25 07:06:21 +00:00
#### Amount
2019-04-25 07:02:14 +00:00
* A valid deposit amount should be at least `MIN_DEPOSIT_AMOUNT` in Gwei.
* A deposit with an amount greater than or equal to `FULL_DEPOSIT_AMOUNT` in Gwei is considered as a full deposit.
2019-04-25 07:06:21 +00:00
## Event logs
2019-04-22 13:29:19 +00:00
### `Deposit` logs
2019-04-25 06:47:44 +00:00
Every Ethereum 1.0 deposit, of size at least `MIN_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-381 signature) is not verified by the deposit contract.
2019-04-22 13:29:19 +00:00
### `Eth2Genesis` log
When `CHAIN_START_FULL_DEPOSIT_THRESHOLD` 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 [here](./0_beacon-chain.md#genesis-state)) where:
2019-04-22 13:29:19 +00:00
* `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)
2019-04-25 07:06:21 +00:00
## Vyper code
2019-04-22 13:29:19 +00:00
2019-06-08 22:48:35 +00:00
The source for the Vyper contract lives [here](./../../deposit_contract/contracts/validator_registration.v.py).
2019-04-22 13:29:19 +00:00
2019-05-06 15:30:32 +00:00
*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.
2019-04-22 13:29:19 +00:00
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
2019-05-06 15:30:32 +00:00
* `deposit(pubkey: bytes[48], withdrawal_credentials: bytes[32], signature: bytes[96])`: adds a deposit instance to the deposit tree, incorporating the input arguments and the value transferred in the given call. *Note*: The amount of value transferred *must* be at least `MIN_DEPOSIT_AMOUNT`. Each of these constants are specified in units of Gwei.