You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+12-5Lines changed: 12 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,15 +10,22 @@ This repo hosts the current eth2.0 specifications. Discussions about design rati
10
10
## Specs
11
11
12
12
Core specifications for eth2.0 client validation can be found in [specs/core](specs/core). These are divided into phases. Each subsequent phase depends upon the prior. The current phases specified are:
13
-
*[Phase 0 -- The Beacon Chain](specs/core/0_beacon-chain.md)
Copy file name to clipboardExpand all lines: specs/core/0_beacon-chain.md
+1-128Lines changed: 1 addition & 128 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Ethereum 2.0 Phase 0 -- The Beacon Chain
2
2
3
-
**NOTICE**: This document is a work in progress for researchers and implementers. It reflects recent spec changes and takes precedence over the Python proof-of-concept implementation [[python-poc]](https://github.com/ethereum/beacon_chain).
3
+
**NOTICE**: This document is a work in progress for researchers and implementers.
4
4
5
5
## Table of contents
6
6
<!-- TOC -->
@@ -94,15 +94,7 @@
94
94
-[Routines for updating validator status](#routines-for-updating-validator-status)
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.
1239
-
1240
-
### Deposit arguments
1241
-
1242
-
The deposit contract has a single `deposit` function which takes as argument the `DepositData` elements.
1243
-
1244
-
### Withdrawal credentials
1245
-
1246
-
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:] == hash(withdrawal_pubkey)[1:]` where `withdrawal_pubkey` is a BLS pubkey
1250
-
1251
-
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.
1252
-
1253
-
### `Deposit` logs
1254
-
1255
-
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.
1256
-
1257
-
### `Eth2Genesis` log
1258
-
1259
-
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:
1260
-
1261
-
*`genesis_time` equals `time` in the `Eth2Genesis` log
1262
-
*`latest_eth1_data.deposit_root` equals `deposit_root` in the `Eth2Genesis` log
1263
-
*`latest_eth1_data.deposit_count` equals `deposit_count` in the `Eth2Genesis` log
1264
-
*`latest_eth1_data.block_hash` equals the hash of the block that included the log
1265
-
*`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)
1266
-
1267
-
### Vyper code
1268
-
1269
-
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).
1270
-
1271
-
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.
1272
-
1273
-
For convenience, we provide the interface to the contract here:
1274
-
1275
-
*`__init__()`: initializes the contract
1276
-
*`get_deposit_root() -> bytes32`: returns the current root of the deposit tree
1277
-
*`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.
1278
-
1279
1226
## On genesis
1280
1227
1281
1228
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:
The beacon chain is the system chain for Ethereum 2.0. The main responsibilities of the beacon chain are as follows:
1321
-
1322
-
* Store and maintain the registry of [validators](#dfn-validator)
1323
-
* Process crosslinks (see above)
1324
-
* Process its per-block consensus, as well as the finality gadget
1325
-
1326
-
Processing the beacon chain is similar to processing the Ethereum 1.0 chain. Clients download and process blocks and maintain a view of what is the current "canonical chain", terminating at the current "head". However, because of the beacon chain's relationship with Ethereum 1.0, and because it is a proof-of-stake chain, there are differences.
1327
-
1328
-
For a beacon chain block, `block`, to be processed by a node, the following conditions must be met:
1329
-
1330
-
* The parent block with root `block.previous_block_root` has been processed and accepted.
1331
-
* An Ethereum 1.0 block pointed to by the `state.latest_eth1_data.block_hash` has been processed and accepted.
1332
-
* The node's Unix time is greater than or equal to `state.genesis_time + block.slot * SECONDS_PER_SLOT`. (Note that leap seconds mean that slots will occasionally last `SECONDS_PER_SLOT + 1` or `SECONDS_PER_SLOT - 1` seconds, possibly several times a year.)
1333
-
1334
-
If these conditions are not met, the client should delay processing the beacon block until the conditions are all satisfied.
1335
-
1336
-
Beacon block production is significantly different because of the proof-of-stake mechanism. A client simply checks what it thinks is the canonical chain when it should create a block and looks up what its slot number is; when the slot arrives, it either proposes or attests to a block as required. Note that this requires each node to have a clock that is roughly (i.e. within `SECONDS_PER_SLOT` seconds) synchronized with the other nodes.
1337
-
1338
-
### Beacon chain fork choice rule
1339
-
1340
-
The beacon chain fork choice rule is a hybrid that combines justification and finality with Latest Message Driven (LMD) Greediest Heaviest Observed SubTree (GHOST). At any point in time a [validator](#dfn-validator)`v` subjectively calculates the beacon chain head as follows.
1341
-
1342
-
* Abstractly define `Store` as the type of storage object for the chain data and `store` be the set of attestations and blocks that the [validator](#dfn-validator)`v` has observed and verified (in particular, block ancestors must be recursively verified). Attestations not yet included in any chain are still included in `store`.
1343
-
* Let `finalized_head` be the finalized block with the highest epoch. (A block `B` is finalized if there is a descendant of `B` in `store` the processing of which sets `B` as finalized.)
1344
-
* Let `justified_head` be the descendant of `finalized_head` with the highest epoch that has been justified for at least 1 epoch. (A block `B` is justified if there is a descendant of `B` in `store` the processing of which sets `B` as justified.) If no such descendant exists set `justified_head` to `finalized_head`.
1345
-
* Let `get_ancestor(store: Store, block: BeaconBlock, slot: Slot) -> BeaconBlock` be the ancestor of `block` with slot number `slot`. The `get_ancestor` function can be defined recursively as:
* Let `get_latest_attestation(store: Store, index: ValidatorIndex) -> Attestation` be the attestation with the highest slot number in `store` from the validator with the given `index`. If several such attestations exist, use the one the [validator](#dfn-validator)`v` observed first.
1361
-
* Let `get_latest_attestation_target(store: Store, index: ValidatorIndex) -> BeaconBlock` be the target block in the attestation `get_latest_attestation(store, index)`.
1362
-
* Let `get_children(store: Store, block: BeaconBlock) -> List[BeaconBlock]` returns the child blocks of the given `block`.
1363
-
* Let `justified_head_state` be the resulting `BeaconState` object from processing the chain up to the `justified_head`.
1364
-
* The `head` is `lmd_ghost(store, justified_head_state, justified_head)` where the function `lmd_ghost` is defined below. Note that the implementation below is suboptimal; there are implementations that compute the head in time logarithmic in slot count.
This document represents is the specification for the beacon chain deposit contract, part of Ethereum 2.0 phase 0.
25
+
26
+
## Constants
27
+
28
+
### Deposit contract
29
+
30
+
| Name | Value |
31
+
| - | - |
32
+
|`DEPOSIT_CONTRACT_ADDRESS`|**TBD**|
33
+
|`DEPOSIT_CONTRACT_TREE_DEPTH`|`2**5` (= 32) |
34
+
35
+
## Ethereum 1.0 deposit contract
36
+
37
+
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.
38
+
39
+
### Deposit arguments
40
+
41
+
The deposit contract has a single `deposit` function which takes as argument a SimpleSerialize'd `DepositData`.
42
+
43
+
### Withdrawal credentials
44
+
45
+
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:] == hash(withdrawal_pubkey)[1:]` where `withdrawal_pubkey` is a BLS pubkey
49
+
50
+
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.
51
+
52
+
### `Deposit` logs
53
+
54
+
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.
55
+
56
+
### `Eth2Genesis` log
57
+
58
+
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:
59
+
60
+
*`genesis_time` equals `time` in the `Eth2Genesis` log
61
+
*`latest_eth1_data.deposit_root` equals `deposit_root` in the `Eth2Genesis` log
62
+
*`latest_eth1_data.deposit_count` equals `deposit_count` in the `Eth2Genesis` log
63
+
*`latest_eth1_data.block_hash` equals the hash of the block that included the log
64
+
*`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)
65
+
66
+
### Vyper code
67
+
68
+
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).
69
+
70
+
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.
71
+
72
+
For convenience, we provide the interface to the contract here:
73
+
74
+
*`__init__()`: initializes the contract
75
+
*`get_deposit_root() -> bytes32`: returns the current root of the deposit tree
76
+
*`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.
0 commit comments