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

67 lines
3.6 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 -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
2019-04-22 13:29:19 +00:00
- [Introduction](#introduction)
- [Constants](#constants)
- [Contract](#contract)
- [Ethereum 1.0 deposit contract](#ethereum-10-deposit-contract)
- [`deposit` function](#deposit-function)
- [Deposit amount](#deposit-amount)
- [Withdrawal credentials](#withdrawal-credentials)
- [`DepositEvent` log](#depositevent-log)
- [Vyper code](#vyper-code)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
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: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) |
## Ethereum 1.0 deposit contract
2019-09-03 17:59:18 +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.
2019-04-22 13:29:19 +00:00
2019-06-09 10:03:38 +00:00
### `deposit` function
2019-04-22 13:29:19 +00:00
2019-09-03 17:59:18 +00:00
The deposit contract has a public `deposit` function to make deposits. It takes as arguments `pubkey: bytes[48], withdrawal_credentials: bytes[32], signature: bytes[96], deposit_data_root: bytes32`. The first three arguments populate a [`DepositData`](./0_beacon-chain.md#depositdata) object, and `deposit_data_root` is the expected `DepositData` root as a protection against malformatted calldata.
2019-06-09 10:03:38 +00:00
#### Deposit amount
2019-06-10 14:55:08 +00:00
The amount of ETH (rounded down to the closest Gwei) sent to the deposit contract is the deposit amount, which must be of size at least `MIN_DEPOSIT_AMOUNT` Gwei. Note that ETH consumed by the deposit contract is no longer usable on Ethereum 1.0.
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-06-09 10:03:38 +00:00
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:
2019-04-22 13:29:19 +00:00
2019-06-30 19:51:10 +00:00
* `withdrawal_credentials[:1] == BLS_WITHDRAWAL_PREFIX`
2019-04-22 13:29:19 +00:00
* `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.
#### `DepositEvent` log
2019-04-25 07:06:21 +00:00
Every Ethereum 1.0 deposit emits a `DepositEvent` 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
2019-04-25 07:06:21 +00:00
## Vyper code
2019-04-22 13:29:19 +00:00
2019-07-01 03:22:18 +00:00
The deposit contract source code, written in Vyper, is available [here](../../deposit_contract/contracts/validator_registration.v.py).
2019-04-22 13:29:19 +00:00
*Note*: To save on gas, the deposit contract uses a progressive Merkle root calculation algorithm that requires only O(log(n)) storage. See [here](https://github.com/ethereum/research/blob/master/beacon_chain_impl/progressive_merkle_tree.py) for a Python implementation, and [here](https://github.com/runtimeverification/verified-smart-contracts/blob/master/deposit/formal-incremental-merkle-tree-algorithm.pdf) for a formal correctness proof.