From 4c75cd0db29ec81ed685316c150f1cf49c03349c Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Mon, 24 Sep 2018 09:52:38 +1000 Subject: [PATCH 01/36] Initial SimpleSerialize spec --- specs/simpleserialize.md | 225 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 specs/simpleserialize.md diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md new file mode 100644 index 000000000..ef2bcf33f --- /dev/null +++ b/specs/simpleserialize.md @@ -0,0 +1,225 @@ +# SimpleSerialize (SSZ) Spec + +***Work In Progress*** + +This is the work in progress document to describe `simpleserialize`, the +current selected serialization method for Ethereum 2.0 using the Beacon Chain. + +This document specifies the general information for serializing and +deserializing objects and data types. + +## ToC + +* [About](#about) +* [Terminology](#terminology) +* [Constants](#constants) +* [Overview](#overview) + + [Serialize/Encode](#serializeencode) + - [int/uint: 8/16/24/32/64/256](#intuint-816243264256) + - [Address](#address) + - [Hash32](#hash32) + - [Bytes](#bytes) + - [List](#list) + + [Deserialize/Decode](#deserializedecode) + - [int/uint: 8/16/24/32/64/256](#intuint-816243264256-1) + - [Address](#address-1) + - [Hash32](#hash32-1) + - [Bytes](#bytes-1) + - [List](#list-1) +* [Implementations](#implementations) + +## About + +`SimpleSerialize` was first proposed by Vitalik Buterin as the serializaiton +protocol for use in the Ethereum 2.0 Beacon Chain. + +The core feature of `ssz` is the simplicity of the serialization with low +overhead. + +## Terminology + +| Term | Definition | +|:-------------|:-----------------------------------------------------------------------------------------------| +| `big` | Big Endian | +| `byte_order` | Specifies [endianness:](https://en.wikipedia.org/wiki/Endianness) Big Endian or Little Endian. | +| `len` | Length/Number of Bytes. | +| `to_bytes` | Convert to bytes. Should take parameters ``size`` and ``byte_order``. | +| `from_bytes` | Convert form bytes to object. Should take ``bytes`` and ``byte_order``. | +| `value` | The value to serialize. | +| `rawbytes` | Raw serialized bytes. | + +## Constants + +| Constant | Value | Definition | +|:---------------|:-----:|:------------------------------------------------------------------------| +| `LENGTH_BYTES` | 4 | Number of bytes used for the length added before the serialized object. | + + +## Overview + +### Serialize/Encode + +#### int/uint: 8/16/24/32/64/256 + +Convert directly to bytes the size of the int. (e.g. ``uint16 = 2 bytes``) + +All integers are serialized as **big endian**. + +| Check to perform | Code | +|:---------------------------------|:------------------------| +| Size is a byte integer | ``int_size % 8 == 0`` | +| Value is less than max | ``2**int_size > value`` | + +```python +buffer_size = int_size / 8 +return value.to_bytes(buffer_size, 'big') +``` + +#### Address + +The address should already come as a hash/byte format. Ensure that length is +**20**. + +| Check to perform | Code | +|:-----------------------|:---------------------| +| Length is correct (20) | ``len(value) == 20`` | + +```python +assert( len(value) == 20 ) +return value +``` + +#### Hash32 + +The hash32 should already be a 32 byte length serialized data format. The safety +check ensures the 32 byte length is satisfied. + +| Check to perform | Code | +|:-----------------------|:---------------------| +| Length is correct (32) | ``len(value) == 32`` | + +```python +assert( len(value) == 32 ) +return value +``` + +#### Bytes + +For general `byte` type: +1. Get the length/number of bytes; Encode into a 4 byte integer. +2. Append the value to the length and return: ``[ length_bytes ] + [ + value_bytes ]`` + +```python +byte_length = (len(value)).to_bytes(4, 'big') +return byte_length + value +``` + +#### List + +For lists of values, get the length of the list and then serialize the value +of each item in the list: +1. For each item in list: + 1. serialize. + 2. append to string. +2. Get size of serialized string. Encode into a 4 byte integer. + +```python +serialized_list_string = '' + +for item in value: + serialized_list_string += serialize(item) + +serialized_len = len(serialized_list_string) + +return serialized_len + serialized_list_string +``` + +### Deserialize/Decode + +The decoding requires knowledge of the type of the item to be decoded. When +performing decoding on an entire serialized string, it also requires knowledge +of what order the objects have been serialized in. + +Note: Each return will provide ``deserialized_object, new_index`` keeping track +of the new index. + +At each step, the following checks should be made: + +| Check Type | Check | +|:-------------------------|:----------------------------------------------------------| +| Ensure sufficient length | ``length(rawbytes) > current_index + deserialize_length`` | + +#### int/uint: 8/16/24/32/64/256 + +Convert directly from bytes into integer utilising the number of bytes the same +size as the integer length. (e.g. ``uint16 == 2 bytes``) + +All integers are interpreted as **big endian**. + +```python +byte_length = int_size / 8 +new_index = current_index + int_size +return int.from_bytes(rawbytes[current_index:current_index+int_size], 'big'), new_index +``` + +#### Address + +Return the 20 bytes. + +```python +new_index = current_index + 20 +return rawbytes[current_index:current_index+20], new_index +``` + +#### Hash32 + +Return the 32 bytes. + +```python +new_index = current_index + 32 +return rawbytes[current_index:current_index+32], new_index +``` + +#### Bytes + +Get the length of the bytes, return the bytes. + +```python +bytes_length = int.from_bytes(rawbytes[current_index:current_index+4], 'big') +new_index = current_index + 4 + bytes_lenth +return rawbytes[current_index+4:current_index+4+bytes_length], new_index +``` + +#### List + +Deserailize each object in the list. +1. Get the length of the serialized list. +2. Loop through deseralizing each item in the list until you reach the +entire length of the list. + + +| Check type | code | +|:------------------------------------|:--------------------------------------| +| rawbytes has enough left for length | ``len(rawbytes) > current_index + 4`` | + +```python +total_length = int.from_bytes(rawbytes[current_index:current_index+4], 'big') +new_index = current_index + 4 + total_length +item_index = current_index + 4 +deserialized_list = [] + +while item_index < new_index: + object, item_index = deserialize(rawbytes, item_index, item_type) + deserialized_list.append(object) + +return deserialized_list, new_index +``` + +## Implementations + +| Language | Implementation | Description | +|:--------:|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| +| Python | [ https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py ](https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py) | Beacon chain reference implementation written in Python. | +| Rust | [ https://github.com/sigp/lighthouse/tree/master/ssz ](https://github.com/sigp/lighthouse/tree/master/ssz) | Lighthouse (Rust Ethereum 2.0 Node) maintained SimpleSerialize. | + From b1c873c8f601dc53f2f01ef839cafc48063791a8 Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Tue, 2 Oct 2018 09:41:18 +1000 Subject: [PATCH 02/36] Remove int as per discussions, update implementations --- specs/simpleserialize.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md index ef2bcf33f..c6a4796be 100644 --- a/specs/simpleserialize.md +++ b/specs/simpleserialize.md @@ -15,13 +15,13 @@ deserializing objects and data types. * [Constants](#constants) * [Overview](#overview) + [Serialize/Encode](#serializeencode) - - [int/uint: 8/16/24/32/64/256](#intuint-816243264256) + - [uint: 8/16/24/32/64/256](#uint-816243264256) - [Address](#address) - [Hash32](#hash32) - [Bytes](#bytes) - [List](#list) + [Deserialize/Decode](#deserializedecode) - - [int/uint: 8/16/24/32/64/256](#intuint-816243264256-1) + - [uint: 8/16/24/32/64/256](#uint-816243264256-1) - [Address](#address-1) - [Hash32](#hash32-1) - [Bytes](#bytes-1) @@ -59,7 +59,7 @@ overhead. ### Serialize/Encode -#### int/uint: 8/16/24/32/64/256 +#### uint: 8/16/24/32/64/256 Convert directly to bytes the size of the int. (e.g. ``uint16 = 2 bytes``) @@ -150,7 +150,7 @@ At each step, the following checks should be made: |:-------------------------|:----------------------------------------------------------| | Ensure sufficient length | ``length(rawbytes) > current_index + deserialize_length`` | -#### int/uint: 8/16/24/32/64/256 +#### uint: 8/16/24/32/64/256 Convert directly from bytes into integer utilising the number of bytes the same size as the integer length. (e.g. ``uint16 == 2 bytes``) @@ -193,9 +193,9 @@ return rawbytes[current_index+4:current_index+4+bytes_length], new_index #### List -Deserailize each object in the list. +Deserialize each object in the list. 1. Get the length of the serialized list. -2. Loop through deseralizing each item in the list until you reach the +2. Loop through deserializing each item in the list until you reach the entire length of the list. @@ -218,8 +218,9 @@ return deserialized_list, new_index ## Implementations -| Language | Implementation | Description | -|:--------:|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| -| Python | [ https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py ](https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py) | Beacon chain reference implementation written in Python. | -| Rust | [ https://github.com/sigp/lighthouse/tree/master/ssz ](https://github.com/sigp/lighthouse/tree/master/ssz) | Lighthouse (Rust Ethereum 2.0 Node) maintained SimpleSerialize. | - +| Language | Implementation | Description | +|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| +| Python | [ https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py ](https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py) | Beacon chain reference implementation written in Python. | +| Rust | [ https://github.com/sigp/lighthouse/tree/master/ssz ](https://github.com/sigp/lighthouse/tree/master/ssz) | Lighthouse (Rust Ethereum 2.0 Node) maintained SimpleSerialize. | +| Nim | [ https://github.com/status-im/nim-beacon-chain/blob/master/beacon_chain/ssz.nim ](https://github.com/status-im/nim-beacon-chain/blob/master/beacon_chain/ssz.nim) | Nim Implemetnation maintained SimpleSerialize. | +| Rust | [ https://github.com/paritytech/shasper/tree/master/util/ssz ](https://github.com/paritytech/shasper/tree/master/util/ssz) | Shasper implementation of SSZ maintained by ParityTech. | From 0b0f618c61bd2790e7594816b1b2f69166a98056 Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Tue, 2 Oct 2018 10:36:58 +1000 Subject: [PATCH 03/36] Add check for byte serialization --- specs/simpleserialize.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md index c6a4796be..68d29d93d 100644 --- a/specs/simpleserialize.md +++ b/specs/simpleserialize.md @@ -110,6 +110,10 @@ For general `byte` type: 2. Append the value to the length and return: ``[ length_bytes ] + [ value_bytes ]`` +| Check to perform | Code | +|:-------------------------------------|:-----------------------| +| Length of bytes can fit into 4 bytes | ``len(value) < 2**32`` | + ```python byte_length = (len(value)).to_bytes(4, 'big') return byte_length + value @@ -218,9 +222,9 @@ return deserialized_list, new_index ## Implementations -| Language | Implementation | Description | -|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| -| Python | [ https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py ](https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py) | Beacon chain reference implementation written in Python. | -| Rust | [ https://github.com/sigp/lighthouse/tree/master/ssz ](https://github.com/sigp/lighthouse/tree/master/ssz) | Lighthouse (Rust Ethereum 2.0 Node) maintained SimpleSerialize. | -| Nim | [ https://github.com/status-im/nim-beacon-chain/blob/master/beacon_chain/ssz.nim ](https://github.com/status-im/nim-beacon-chain/blob/master/beacon_chain/ssz.nim) | Nim Implemetnation maintained SimpleSerialize. | -| Rust | [ https://github.com/paritytech/shasper/tree/master/util/ssz ](https://github.com/paritytech/shasper/tree/master/util/ssz) | Shasper implementation of SSZ maintained by ParityTech. | +| Language | Implementation | Description | +|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------| +| Python | [ https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py ](https://github.com/ethereum/beacon_chain/blob/master/ssz/ssz.py) | Beacon chain reference implementation written in Python. | +| Rust | [ https://github.com/sigp/lighthouse/tree/master/ssz ](https://github.com/sigp/lighthouse/tree/master/ssz) | Lighthouse (Rust Ethereum 2.0 Node) maintained SSZ. | +| Nim | [ https://github.com/status-im/nim-beacon-chain/blob/master/beacon_chain/ssz.nim ](https://github.com/status-im/nim-beacon-chain/blob/master/beacon_chain/ssz.nim) | Nim Implementation maintained SSZ. | +| Rust | [ https://github.com/paritytech/shasper/tree/master/util/ssz ](https://github.com/paritytech/shasper/tree/master/util/ssz) | Shasper implementation of SSZ maintained by ParityTech. | From 6287573adc58c3b999d5c33900c49d605a65830a Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Tue, 2 Oct 2018 12:34:20 +1000 Subject: [PATCH 04/36] Update misspelling; Use `LENGTH_BYTES` variable; Update for comments --- specs/simpleserialize.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md index 68d29d93d..147f55796 100644 --- a/specs/simpleserialize.md +++ b/specs/simpleserialize.md @@ -30,7 +30,7 @@ deserializing objects and data types. ## About -`SimpleSerialize` was first proposed by Vitalik Buterin as the serializaiton +`SimpleSerialize` was first proposed by Vitalik Buterin as the serialization protocol for use in the Ethereum 2.0 Beacon Chain. The core feature of `ssz` is the simplicity of the serialization with low @@ -115,7 +115,7 @@ For general `byte` type: | Length of bytes can fit into 4 bytes | ``len(value) < 2**32`` | ```python -byte_length = (len(value)).to_bytes(4, 'big') +byte_length = (len(value)).to_bytes(LENGTH_BYTES, 'big') return byte_length + value ``` @@ -134,7 +134,7 @@ serialized_list_string = '' for item in value: serialized_list_string += serialize(item) -serialized_len = len(serialized_list_string) +serialized_len = (len(serialized_list_string).to_bytes(LENGTH_BYTES, 'big')) return serialized_len + serialized_list_string ``` @@ -190,9 +190,9 @@ return rawbytes[current_index:current_index+32], new_index Get the length of the bytes, return the bytes. ```python -bytes_length = int.from_bytes(rawbytes[current_index:current_index+4], 'big') -new_index = current_index + 4 + bytes_lenth -return rawbytes[current_index+4:current_index+4+bytes_length], new_index +bytes_length = int.from_bytes(rawbytes[current_index:current_index + LENGTH_BYTES], 'big') +new_index = current_index + LENGTH_BYTES + bytes_lenth +return rawbytes[current_index + LENGTH_BYTES:current_index+ LENGTH_BYTES +bytes_length], new_index ``` #### List @@ -208,9 +208,9 @@ entire length of the list. | rawbytes has enough left for length | ``len(rawbytes) > current_index + 4`` | ```python -total_length = int.from_bytes(rawbytes[current_index:current_index+4], 'big') -new_index = current_index + 4 + total_length -item_index = current_index + 4 +total_length = int.from_bytes(rawbytes[current_index:current_index + LENGTH_BYTES], 'big') +new_index = current_index + LENGTH_BYTES + total_length +item_index = current_index + LENGTH_BYTES deserialized_list = [] while item_index < new_index: From 78a830da278cf9488f1278d6ad8dbdf65b145766 Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Tue, 2 Oct 2018 23:33:11 +1000 Subject: [PATCH 05/36] Update Hash Types as per @mratsim's comments on #18 --- specs/simpleserialize.md | 111 ++++++++++++++++++++++++++++++++------- 1 file changed, 91 insertions(+), 20 deletions(-) diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md index 147f55796..11c1843ed 100644 --- a/specs/simpleserialize.md +++ b/specs/simpleserialize.md @@ -14,18 +14,24 @@ deserializing objects and data types. * [Terminology](#terminology) * [Constants](#constants) * [Overview](#overview) - + [Serialize/Encode](#serializeencode) - - [uint: 8/16/24/32/64/256](#uint-816243264256) - - [Address](#address) - - [Hash32](#hash32) - - [Bytes](#bytes) - - [List](#list) - + [Deserialize/Decode](#deserializedecode) - - [uint: 8/16/24/32/64/256](#uint-816243264256-1) - - [Address](#address-1) - - [Hash32](#hash32-1) - - [Bytes](#bytes-1) - - [List](#list-1) + + [Serialize/Encode](#serializeencode) + - [uint: 8/16/24/32/64/256](#uint-816243264256) + - [Address](#address) + - [Hash](#hash) + * [Hash32](#hash32) + * [Hash96](#hash96) + * [Hash97](#hash97) + - [Bytes](#bytes) + - [List](#list) + + [Deserialize/Decode](#deserializedecode) + - [uint: 8/16/24/32/64/256](#uint-816243264256-1) + - [Address](#address-1) + - [Hash](#hash-1) + * [Hash32](#hash32-1) + * [Hash96](#hash96-1) + * [Hash97](#hash97-1) + - [Bytes](#bytes-1) + - [List](#list-1) * [Implementations](#implementations) ## About @@ -89,17 +95,61 @@ assert( len(value) == 20 ) return value ``` -#### Hash32 +#### Hash -The hash32 should already be a 32 byte length serialized data format. The safety -check ensures the 32 byte length is satisfied. +| Hash Type | Usage | +|:---------:|:------------------------------------------------| +| `hash32` | Hash size of ``keccak`` or `blake2b[0.. < 32]`. | +| `hash96` | BLS Public Key Size. | +| `hash97` | BLS Public Key Size with recovery bit. | -| Check to perform | Code | -|:-----------------------|:---------------------| -| Length is correct (32) | ``len(value) == 32`` | + +| Checks to perform | Code | +|:-----------------------------------|:---------------------| +| Length is correct (32) if `hash32` | ``len(value) == 32`` | +| Length is correct (96) if `hash96` | ``len(value) == 96`` | +| Length is correct (97) if `hash97` | ``len(value) == 97`` | + + +**Example all together** ```python -assert( len(value) == 32 ) +if (type(value) == 'hash32'): + assert(len(value) == 32) +elif (type(value) == 'hash96'): + assert(len(value) == 96) +elif (type(value) == 'hash97'): + assert(len(value) == 97) +else: + raise TypeError('Invalid hash type supplied') + +return value +``` + +##### Hash32 + +Ensure 32 byte length and return the bytes. + +```python +assert(len(value) == 32) +return value +``` + +##### Hash96 + +Ensure 96 byte length and return the bytes. + +```python +assert(len(value) == 96) +return value +``` + +##### Hash97 + +Ensure 97 byte length and return the bytes. + +```python +assert(len(value) == 97) return value ``` @@ -176,7 +226,9 @@ new_index = current_index + 20 return rawbytes[current_index:current_index+20], new_index ``` -#### Hash32 +#### Hash + +##### Hash32 Return the 32 bytes. @@ -185,6 +237,25 @@ new_index = current_index + 32 return rawbytes[current_index:current_index+32], new_index ``` +##### Hash96 + +Return the 96 bytes. + +```python +new_index = current_index + 96 +return rawbytes[current_index:current_index+96], new_index +``` + +##### Hash97 + +Return the 97 bytes. + +```python +new_index = current_index + 97 +return rawbytes[current_index:current_index+97], new_index +``` + + #### Bytes Get the length of the bytes, return the bytes. From 8521bd93ade2f2e88029979515a9c036e9fb85fc Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Tue, 2 Oct 2018 23:42:25 +1000 Subject: [PATCH 06/36] Update List/Vectors with comments on #18 --- specs/simpleserialize.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md index 11c1843ed..238d7699a 100644 --- a/specs/simpleserialize.md +++ b/specs/simpleserialize.md @@ -22,7 +22,7 @@ deserializing objects and data types. * [Hash96](#hash96) * [Hash97](#hash97) - [Bytes](#bytes) - - [List](#list) + - [List/Vectors](#listvectors) + [Deserialize/Decode](#deserializedecode) - [uint: 8/16/24/32/64/256](#uint-816243264256-1) - [Address](#address-1) @@ -31,7 +31,7 @@ deserializing objects and data types. * [Hash96](#hash96-1) * [Hash97](#hash97-1) - [Bytes](#bytes-1) - - [List](#list-1) + - [List/Vectors](#listvectors-1) * [Implementations](#implementations) ## About @@ -169,14 +169,15 @@ byte_length = (len(value)).to_bytes(LENGTH_BYTES, 'big') return byte_length + value ``` -#### List +#### List/Vectors -For lists of values, get the length of the list and then serialize the value -of each item in the list: -1. For each item in list: - 1. serialize. - 2. append to string. -2. Get size of serialized string. Encode into a 4 byte integer. +1. Get the number of raw bytes to serialize: it is `len(list) * sizeof(element)`. + * Encode that as a `4-byte` **big endian** `uint32`. +2. Append your elements in a packed manner. + +* *Note on efficiency*: consider using a container that does not need to iterate over all elements to get its length. For example Python lists, C++ vectors or Rust Vec. + +**Example in Python** ```python serialized_list_string = '' @@ -266,7 +267,7 @@ new_index = current_index + LENGTH_BYTES + bytes_lenth return rawbytes[current_index + LENGTH_BYTES:current_index+ LENGTH_BYTES +bytes_length], new_index ``` -#### List +#### List/Vectors Deserialize each object in the list. 1. Get the length of the serialized list. From cd71c223d1dfb63ae7293ab7c1275e146af397df Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Tue, 2 Oct 2018 23:46:22 +1000 Subject: [PATCH 07/36] Add "WIP" to title to make it clear; @djrtwo's comment in #18 --- specs/simpleserialize.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md index 238d7699a..12d0c8dd4 100644 --- a/specs/simpleserialize.md +++ b/specs/simpleserialize.md @@ -1,4 +1,4 @@ -# SimpleSerialize (SSZ) Spec +# [WIP] SimpleSerialize (SSZ) Spec ***Work In Progress*** From a2ad4bf6d5916b37e53dd2e7e65cdbb199f333f3 Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Wed, 3 Oct 2018 08:17:29 +1000 Subject: [PATCH 08/36] Add assertions in examples; Update checks from @djrtwo's comments --- specs/simpleserialize.md | 71 ++++++++++++++++++++++++++++------------ 1 file changed, 50 insertions(+), 21 deletions(-) diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md index 12d0c8dd4..bba02cec8 100644 --- a/specs/simpleserialize.md +++ b/specs/simpleserialize.md @@ -50,15 +50,15 @@ overhead. | `byte_order` | Specifies [endianness:](https://en.wikipedia.org/wiki/Endianness) Big Endian or Little Endian. | | `len` | Length/Number of Bytes. | | `to_bytes` | Convert to bytes. Should take parameters ``size`` and ``byte_order``. | -| `from_bytes` | Convert form bytes to object. Should take ``bytes`` and ``byte_order``. | +| `from_bytes` | Convert from bytes to object. Should take ``bytes`` and ``byte_order``. | | `value` | The value to serialize. | | `rawbytes` | Raw serialized bytes. | ## Constants -| Constant | Value | Definition | -|:---------------|:-----:|:------------------------------------------------------------------------| -| `LENGTH_BYTES` | 4 | Number of bytes used for the length added before the serialized object. | +| Constant | Value | Definition | +|:---------------|:-----:|:--------------------------------------------------------------------------------------| +| `LENGTH_BYTES` | 4 | Number of bytes used for the length added before a variable-length serialized object. | ## Overview @@ -71,12 +71,12 @@ Convert directly to bytes the size of the int. (e.g. ``uint16 = 2 bytes``) All integers are serialized as **big endian**. -| Check to perform | Code | -|:---------------------------------|:------------------------| -| Size is a byte integer | ``int_size % 8 == 0`` | -| Value is less than max | ``2**int_size > value`` | +| Check to perform | Code | +|:-----------------------|:----------------------| +| Size is a byte integer | ``int_size % 8 == 0`` | ```python +assert(int_size % 8 == 0) buffer_size = int_size / 8 return value.to_bytes(buffer_size, 'big') ``` @@ -156,7 +156,7 @@ return value #### Bytes For general `byte` type: -1. Get the length/number of bytes; Encode into a 4 byte integer. +1. Get the length/number of bytes; Encode into a `4-byte` integer. 2. Append the value to the length and return: ``[ length_bytes ] + [ value_bytes ]`` @@ -165,26 +165,35 @@ For general `byte` type: | Length of bytes can fit into 4 bytes | ``len(value) < 2**32`` | ```python +assert(len(value) < 2**32) byte_length = (len(value)).to_bytes(LENGTH_BYTES, 'big') return byte_length + value ``` #### List/Vectors -1. Get the number of raw bytes to serialize: it is `len(list) * sizeof(element)`. +| Check to perform | Code | +|:--------------------------------------------|:----------------------------| +| Length of serialized list fits into 4 bytes | ``len(serialized) < 2**32`` | + + +1. Get the number of raw bytes to serialize: it is ``len(list) * sizeof(element)``. * Encode that as a `4-byte` **big endian** `uint32`. -2. Append your elements in a packed manner. +2. Append the elements in a packed manner. * *Note on efficiency*: consider using a container that does not need to iterate over all elements to get its length. For example Python lists, C++ vectors or Rust Vec. **Example in Python** ```python -serialized_list_string = '' + +serialized_list_string = b'' for item in value: serialized_list_string += serialize(item) +assert(len(serialized_list_string) < 2**32) + serialized_len = (len(serialized_list_string).to_bytes(LENGTH_BYTES, 'big')) return serialized_len + serialized_list_string @@ -194,16 +203,16 @@ return serialized_len + serialized_list_string The decoding requires knowledge of the type of the item to be decoded. When performing decoding on an entire serialized string, it also requires knowledge -of what order the objects have been serialized in. +of the order in which the objects have been serialized. Note: Each return will provide ``deserialized_object, new_index`` keeping track of the new index. At each step, the following checks should be made: -| Check Type | Check | -|:-------------------------|:----------------------------------------------------------| -| Ensure sufficient length | ``length(rawbytes) > current_index + deserialize_length`` | +| Check to perform | Check | +|:-------------------------|:-----------------------------------------------------------| +| Ensure sufficient length | ``length(rawbytes) >= current_index + deserialize_length`` | #### uint: 8/16/24/32/64/256 @@ -213,6 +222,7 @@ size as the integer length. (e.g. ``uint16 == 2 bytes``) All integers are interpreted as **big endian**. ```python +assert(len(rawbytes) >= current_index + int_size) byte_length = int_size / 8 new_index = current_index + int_size return int.from_bytes(rawbytes[current_index:current_index+int_size], 'big'), new_index @@ -223,6 +233,7 @@ return int.from_bytes(rawbytes[current_index:current_index+int_size], 'big'), ne Return the 20 bytes. ```python +assert(len(rawbytes) >= current_index + 20) new_index = current_index + 20 return rawbytes[current_index:current_index+20], new_index ``` @@ -234,6 +245,7 @@ return rawbytes[current_index:current_index+20], new_index Return the 32 bytes. ```python +assert(len(rawbytes) >= current_index + 32) new_index = current_index + 32 return rawbytes[current_index:current_index+32], new_index ``` @@ -243,6 +255,7 @@ return rawbytes[current_index:current_index+32], new_index Return the 96 bytes. ```python +assert(len(rawbytes) >= current_index + 96) new_index = current_index + 96 return rawbytes[current_index:current_index+96], new_index ``` @@ -252,6 +265,7 @@ return rawbytes[current_index:current_index+96], new_index Return the 97 bytes. ```python +assert(len(rawbytes) >= current_index + 97) new_index = current_index + 97 return rawbytes[current_index:current_index+97], new_index ``` @@ -261,10 +275,22 @@ return rawbytes[current_index:current_index+97], new_index Get the length of the bytes, return the bytes. +| Check to perform | code | +|:--------------------------------------------------|:-------------------------------------------------| +| rawbytes has enough left for length | ``len(rawbytes) > current_index + LENGTH_BYTES`` | +| bytes to return not greater than serialized bytes | ``len(rawbytes) > bytes_end `` | + ```python +assert(len(rawbytes) > current_index + LENGTH_BYTES) bytes_length = int.from_bytes(rawbytes[current_index:current_index + LENGTH_BYTES], 'big') -new_index = current_index + LENGTH_BYTES + bytes_lenth -return rawbytes[current_index + LENGTH_BYTES:current_index+ LENGTH_BYTES +bytes_length], new_index + +bytes_start = current_index + LENGTH_BYTES +bytes_end = bytes_start + bytes_length +new_index = bytes_end + +assert(len(rawbytes) >= bytes_end) + +return rawbytes[bytes_start:bytes_end], new_index ``` #### List/Vectors @@ -275,13 +301,16 @@ Deserialize each object in the list. entire length of the list. -| Check type | code | -|:------------------------------------|:--------------------------------------| -| rawbytes has enough left for length | ``len(rawbytes) > current_index + 4`` | +| Check to perform | code | +|:------------------------------------------|:----------------------------------------------------------------| +| rawbytes has enough left for length | ``len(rawbytes) > current_index + LENGTH_BYTES`` | +| list is not greater than serialized bytes | ``len(rawbytes) > current_index + LENGTH_BYTES + total_length`` | ```python +assert(len(rawbytes) > current_index + LENGTH_BYTES) total_length = int.from_bytes(rawbytes[current_index:current_index + LENGTH_BYTES], 'big') new_index = current_index + LENGTH_BYTES + total_length +assert(len(rawbytes) >= new_index) item_index = current_index + LENGTH_BYTES deserialized_list = [] From 86ea004ea6273840059e14983f1b9a98839d9c93 Mon Sep 17 00:00:00 2001 From: Vitalik Buterin Date: Tue, 2 Oct 2018 19:05:30 -0400 Subject: [PATCH 09/36] Added hash chain for light clients --- specs/casper_sharding_v2.1.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index af4793862..8bcc85f26 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -55,6 +55,8 @@ Note: the python code at https://github.com/ethereum/beacon_chain and [an ethres * **PENDING\_WITHDRAW** = 3 (status code) * **PENALIZED** = 128 (status code) * **WITHDRAWN** = 4 (status code) +* **ENTRY** = 1 (flag) +* **EXIT** = 2 (flag) ### PoW chain changes @@ -163,7 +165,9 @@ fields = { # Start of the current dynasty 'dynasty_start': 'int64', # Total deposits penalized in the given withdrawal period - 'deposits_penalized_in_period': ['int32'] + 'deposits_penalized_in_period': ['int32'], + # Hash chain of validator set changes, allows light clients to track deltas more easily + 'validator_set_delta_hash_chain': 'hash32' } ``` @@ -345,6 +349,15 @@ def get_block_hash(active_state, curblock, slot): `get_block_hash(_, _, h)` should always return the block in the chain at slot `h`, and `get_shards_and_committees_for_slot(_, h)` should not change unless the dynasty changes. +We define a function to "add a link" to the validator hash chain, used when a validator is added or removed: + +```python +def add_validator_set_change_record(crystallized_state, index, pubkey, flag): + crystallized_state.validator_set_delta_hash_chain = \ + hash(crystallized_state.validator_set_delta_hash_chain + + bytes1(flag) + bytes3(index) + bytes32(pubkey)) +``` + Finally, we abstractly define `int_sqrt(n)` for use in reward/penalty calculations as the largest integer `k` such that `k**2 <= n`. Here is one possible implementation, though clients are free to use their own including standard libraries for [integer square root](https://en.wikipedia.org/wiki/Integer_square_root) if available and meet the specification. ```python @@ -504,7 +517,12 @@ Let `committees` be the set of committees processed and `time_since_last_confirm For each `SpecialObject` `obj` in `active_state.pending_specials`: * **[coverts logouts]**: If `obj.type == 0`, interpret `data[0]` as a validator index as an `int32` and `data[1]` as a signature. If `BLSVerify(pubkey=validators[data[0]].pubkey, msg=hash("bye bye"), sig=data[1])`, and `validators[i].status == LOGGED_IN`, set `validators[i].status = PENDING_EXIT` and `validators[i].exit_slot = current_slot` -* **[covers NO\_DBL\_VOTE, NO\_SURROUND, NO\_DBL\_PROPOSE slashing conditions]:** If `obj.type == 1`, interpret `data[0]` as a list of concatenated `int32` values where each value represents an index into `validators`, `data[1]` as the data being signed and `data[2]` as an aggregate signature. Interpret `data[3:6]` similarly. Verify that both signatures are valid, that the two signatures are signing distinct data, and that they are either signing the same slot number, or that one surrounds the other (ie. `source1 < source2 < target2 < target1`). Let `inds` be the list of indices in both signatures; verify that its length is at least 1. For each validator index `v` in `inds`, set their end dynasty to equal the current dynasty + 1, and if its `status` does not equal `PENALIZED`, then (i) set its `exit_slot` to equal the current `slot`, (ii) set its `status` to `PENALIZED`, and (iii) set `crystallized_state.deposits_penalized_in_period[slot // WITHDRAWAL_PERIOD] += validators[v].balance`, extending the array if needed. +* **[covers NO\_DBL\_VOTE, NO\_SURROUND, NO\_DBL\_PROPOSE slashing conditions]:** If `obj.type == 1`, interpret `data[0]` as a list of concatenated `int32` values where each value represents an index into `validators`, `data[1]` as the data being signed and `data[2]` as an aggregate signature. Interpret `data[3:6]` similarly. Verify that both signatures are valid, that the two signatures are signing distinct data, and that they are either signing the same slot number, or that one surrounds the other (ie. `source1 < source2 < target2 < target1`). Let `inds` be the list of indices in both signatures; verify that its length is at least 1. For each validator index `v` in `inds`, set their end dynasty to equal the current dynasty + 1, and if its `status` does not equal `PENALIZED`, then: + +1. Set its `exit_slot` to equal the current `slot` +2. Set its `status` to `PENALIZED` +3. Set `crystallized_state.deposits_penalized_in_period[slot // WITHDRAWAL_PERIOD] += validators[v].balance`, extending the array if needed +4. Run `add_validator_set_change_record(crystallized_state, v, validators[v].pubkey, EXIT)` #### Finally... @@ -540,10 +558,12 @@ def change_validators(validators): if validators[i].status == PENDING_LOG_IN: validators[i].status = LOGGED_IN total_changed += DEPOSIT_SIZE + add_validator_set_change_record(crystallized_state, i, validators[i].pubkey, ENTRY) if validators[i].status == PENDING_EXIT: validators[i].status = PENDING_WITHDRAW validators[i].exit_slot = current_slot total_changed += validators[i].balance + add_validator_set_change_record(crystallized_state, i, validators[i].pubkey, EXIT) if total_changed >= max_allowable_change: break From 03252637cbfc045fd82c30f1dc1fb56b8a9d9ceb Mon Sep 17 00:00:00 2001 From: NatoliChris Date: Wed, 3 Oct 2018 15:08:20 +1000 Subject: [PATCH 10/36] Add container todo stubs --- specs/simpleserialize.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/specs/simpleserialize.md b/specs/simpleserialize.md index bba02cec8..82b8a5e9a 100644 --- a/specs/simpleserialize.md +++ b/specs/simpleserialize.md @@ -1,8 +1,6 @@ # [WIP] SimpleSerialize (SSZ) Spec -***Work In Progress*** - -This is the work in progress document to describe `simpleserialize`, the +This is the **work in progress** document to describe `simpleserialize`, the current selected serialization method for Ethereum 2.0 using the Beacon Chain. This document specifies the general information for serializing and @@ -23,6 +21,7 @@ deserializing objects and data types. * [Hash97](#hash97) - [Bytes](#bytes) - [List/Vectors](#listvectors) + - [Container (TODO)](#container) + [Deserialize/Decode](#deserializedecode) - [uint: 8/16/24/32/64/256](#uint-816243264256-1) - [Address](#address-1) @@ -32,6 +31,7 @@ deserializing objects and data types. * [Hash97](#hash97-1) - [Bytes](#bytes-1) - [List/Vectors](#listvectors-1) + - [Container (TODO)](#container-1) * [Implementations](#implementations) ## About @@ -199,6 +199,15 @@ serialized_len = (len(serialized_list_string).to_bytes(LENGTH_BYTES, 'big')) return serialized_len + serialized_list_string ``` +#### Container + +``` +######################################## + TODO +######################################## +``` + + ### Deserialize/Decode The decoding requires knowledge of the type of the item to be decoded. When @@ -321,6 +330,14 @@ while item_index < new_index: return deserialized_list, new_index ``` +#### Container + +``` +######################################## + TODO +######################################## +``` + ## Implementations | Language | Implementation | Description | From 8648f4800e5484b5cd4e107e93cc7dd4b897f882 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 08:27:39 +0100 Subject: [PATCH 11/36] Rework the constants for readability --- specs/casper_sharding_v2.1.md | 56 ++++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index af4793862..457fb8a62 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -34,27 +34,43 @@ Note: the python code at https://github.com/ethereum/beacon_chain and [an ethres * **Dynasty** - the number of dynasty transitions that have happened in a given chain since genesis * **Cycle** - a span of blocks during which all validators get exactly one chance to make an attestation (unless a dynasty transition happens inside of one) * **Finalized**, **justified** - see Casper FFG finalization here: https://arxiv.org/abs/1710.09437 +* **Withdrawal period** - number of slots between a validator exit and the validator slot being withdrawable +* **Genesis time** - the Unix time of the genesis beacon chain block at slot 0 ### Constants -* **SHARD_COUNT** - a constant referring to the number of shards. Currently set to 1024. -* **DEPOSIT_SIZE** - 32 ETH, or 32 * 10\*\*18 wei -* **MAX_VALIDATOR_COUNT** - 222 = 4194304 # Note: this means that up to ~134 million ETH can stake at the same time -* **GENESIS_TIME** - time of beacon chain startup (slot 0) in seconds since the Unix epoch -* **SLOT_DURATION** - 16 seconds -* **CYCLE_LENGTH** - 64 slots -* **MIN_DYNASTY_LENGTH** - 256 slots -* **MIN_COMMITTEE_SIZE** - 128 (rationale: see recommended minimum 111 here https://vitalik.ca/files/Ithaca201807_Sharding.pdf) -* **SQRT\_E\_DROP\_TIME** - a constant set to reflect the amount of time it will take for the quadratic leak to cut nonparticipating validators' deposits by ~39.4%. Currently set to 2**20 seconds (~12 days). -* **BASE\_REWARD\_QUOTIENT** - 1/this is the per-slot interest rate assuming all validators are participating, assuming total deposits of 1 ETH. Currently set to `2**15 = 32768`, corresponding to ~3.88% annual interest assuming 10 million participating ETH. -* **WITHDRAWAL_PERIOD** - number of slots between a validator exit and the validator slot being withdrawable. Currently set to `2**19 = 524288` slots, or `2**23` seconds ~= 97 days. -* **MAX\_VALIDATOR\_CHANGE\_QUOTIENT** - a maximum of 1/x validators can change during each dynasty. Currently set to 32. -* **PENDING\_LOG\_IN** = 0 (status code) -* **LOGGED\_IN** = 1 (status code) -* **PENDING\_EXIT** = 2 (status code) -* **PENDING\_WITHDRAW** = 3 (status code) -* **PENALIZED** = 128 (status code) -* **WITHDRAWN** = 4 (status code) +| Constant | Value | Unit | Approximation | +| --- | --- | :---: | - | +| `SHARD_COUNT` | 2**10 (= 1,024)| shards | +| `DEPOSIT_SIZE` | 2**5 (= 32) | ETH | +| `MIN_COMMITTEE_SIZE` | 2**7 (= 128) | validators | +| `MAX_VALIDATOR_COUNT` | 2**22 ( = 4,194,304) | validators | +| `GENESIS_TIME` | **TBD** | seconds | +| `SLOT_DURATION` | 2**4 (= 16) | seconds | +| `CYCLE_LENGTH` | 2**6 (= 64) | slots | ~17 minutes | +| `MIN_DYNASTY_LENGTH` | 2**8 (= 256) | slots | ~1.1 hours | +| `SQRT_E_DROP_TIME` | 2**16 (= 65,536) | slots | ~12 days | +| `WITHDRAWAL_PERIOD` | 2**19 (= 524,288) | slots | ~97 days | +| `BASE_REWARD_QUOTIENT` | 2**15 (= 32,76) | — | +| `MAX_VALIDATOR_CHURN_QUOTIENT` | 2**5 (= 32) | — | + +**Notes** + +* At most `MAX_VALIDATOR_COUNT * DEPOSIT_SIZE` (~134 million ETH) can be staked. +* The `SQRT_E_DROP_TIME` constant is the amount of time it takes for the quadratic leak to cut deposits of non-participating validators by ~39.4%. +* The `BASE_REWARD_QUOTIENT` constant is the per-slot interest rate assuming all validators are participating, assuming total deposits of 1 ETH. It corresponds to ~3.88% annual interest assuming 10 million participating ETH. +* At most `1/MAX_VALIDATOR_CHURN_QUOTIENT` of the validators can change during each dynasty. + +**Status codes** + +| Status code | Value | +| - | :-: | +| `PENDING_LOG_IN` | `0` | +| `LOGGED_IN` | `1` | +| `PENDING_EXIT` | `2` | +| `PENDING_WITHDRAW` | `3` | +| `WITHDRAWN` | `4` | +| `PENALIZED` | `128` | ### PoW chain changes @@ -474,7 +490,7 @@ Let `time_since_finality = block.slot - last_finalized_slot`, and let `B` be the * `total_deposits = sum([v.balance for i, v in enumerate(validators) if i in get_active_validator_indices(validators, current_dynasty)])` and `total_deposits_in_ETH = total_deposits // 10**18` * `reward_quotient = BASE_REWARD_QUOTIENT * int_sqrt(total_deposits_in_ETH)` (1/this is the per-slot max interest rate) -* `quadratic_penalty_quotient = (SQRT_E_DROP_TIME / SLOT_DURATION)**2` (after D slots, ~D2/2 divided by this is the portion lost by offline validators) +* `quadratic_penalty_quotient = SQRT_E_DROP_TIME**2` (after D slots, ~D2/2 divided by this is the portion lost by offline validators) For each slot `S` in the range `last_state_recalculation - CYCLE_LENGTH ... last_state_recalculation - 1`: @@ -532,7 +548,7 @@ def change_validators(validators): # The maximum total wei that can deposit+withdraw max_allowable_change = max( DEPOSIT_SIZE * 2, - total_deposits // MAX_VALIDATOR_CHANGE_QUOTIENT + total_deposits // MAX_VALIDATOR_CHURN_QUOTIENT ) # Go through the list start to end depositing+withdrawing as many as possible total_changed = 0 From 52ca90a7eef63a602073950cc5683f1273fb76e7 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 08:30:42 +0100 Subject: [PATCH 12/36] Remove version number in file name Putting the version number in the file name is not future proof --- specs/{casper_sharding_v2.1.md => spec.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename specs/{casper_sharding_v2.1.md => spec.md} (100%) diff --git a/specs/casper_sharding_v2.1.md b/specs/spec.md similarity index 100% rename from specs/casper_sharding_v2.1.md rename to specs/spec.md From be385b4c57a336db5527c9ead0ae97b49e4a7457 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 10:24:31 +0100 Subject: [PATCH 13/36] Clean up header and intro --- specs/casper_sharding_v2.1.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index af4793862..d830c36df 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -1,23 +1,15 @@ -# Casper+Sharding chain v2.1 +# Ethereum 2.0 spec—Casper and sharding ###### tags: `spec`, `eth2.0`, `casper`, `sharding` +###### spec version: 2.2 (October 2018) -## WORK IN PROGRESS!!!!!!! +**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](https://github.com/ethereum/beacon_chain). -This is the work-in-progress document describing the specification for the Casper+Sharding (shasper) chain, version 2.1. +### Introduction -In this protocol, there is a central PoS "beacon chain" which stores and manages the current set of active PoS validators. The only mechanism available to become a validator initially is to send a transaction on the existing PoW chain containing 32 ETH. When you do so, as soon as the beacon chain processes that block, you will be queued, and eventually inducted as an active validator until you either voluntarily deregister or you are forcibly deregistered as a penalty for misbehavior. +At the center of Ethereum 2.0 is a system chain called the "beacon chain". The beacon chain stores and manages the set of active proof-of-stake validators. In the initial deployment phases of Ethereum 2.0 the only mechanism to become a validator is to make a fixed-size one-way ETH deposit to a registration contract on the Ethereum 1.0 PoW chain. Induction as a validator happens after registration transactions are processed by the beacon chain and after a queuing process. Deregistration is either voluntary or done forcibly as a penalty for misbehavior. -The primary source of load on the beacon chain is **attestations**. An attestation has a double role: - -1. It attests to some parent block in the beacon chain -2. It attests to a block hash in a shard (a sufficient number of such attestations create a "crosslink", confirming that shard block into the beacon chain). - -Every shard (e.g. there might be 1024 shards in total) is itself a PoS chain, and the shard chains are where the transactions and accounts will be stored. The crosslinks serve to "confirm" segments of the shard chains into the beacon chain, and are also the primary way through which the different shards will be able to talk to each other. - -Note that one can also consider a simpler "minimal sharding algorithm" where crosslinks are simply hashes of proposed blocks of data that are not themselves chained to each other in any way. - -Note: the python code at https://github.com/ethereum/beacon_chain and [an ethresear.ch post](https://ethresear.ch/t/convenience-link-to-full-casper-chain-v2-spec/2332) do not reflect all of the latest changes. If there is a discrepancy, this document is likely to reflect the more recent changes. +The primary source of load on the beacon chain are "attestations". Attestations simultaneously attest to a shard block and a corresponding beacon chain block. A sufficient number of attestations for the same shard block create a "crosslink", confirming the shard segment up to that shard block into the beacon chain. Crosslinks also serve as infrastructure for asynchronous cross-shard communication. ### Terminology From e5f94eae07f144334d3360aaeba23f9e6218ac53 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 11:24:07 +0100 Subject: [PATCH 14/36] Fix typo --- specs/casper_sharding_v2.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index 457fb8a62..3220a348e 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -51,7 +51,7 @@ Note: the python code at https://github.com/ethereum/beacon_chain and [an ethres | `MIN_DYNASTY_LENGTH` | 2**8 (= 256) | slots | ~1.1 hours | | `SQRT_E_DROP_TIME` | 2**16 (= 65,536) | slots | ~12 days | | `WITHDRAWAL_PERIOD` | 2**19 (= 524,288) | slots | ~97 days | -| `BASE_REWARD_QUOTIENT` | 2**15 (= 32,76) | — | +| `BASE_REWARD_QUOTIENT` | 2**15 (= 32,768) | — | | `MAX_VALIDATOR_CHURN_QUOTIENT` | 2**5 (= 32) | — | **Notes** From afea8a10a5f0e1ba3b2e0035a8e40325b0df0de2 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 11:59:59 +0100 Subject: [PATCH 15/36] Rework the TODO Probably missed a few. Will try to keep up to date. --- specs/casper_sharding_v2.1.md | 40 ++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index c0d2c231c..04c7a2312 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -581,27 +581,33 @@ Finally: * Let `next_start_shard = (shard_and_committee_for_slots[-1][-1].shard_id + 1) % SHARD_COUNT` * Set `shard_and_committee_for_slots[CYCLE_LENGTH:] = get_new_shuffling(block.ancestor_hashes[0], validators, next_start_shard)` -------- +### TODO -Note: this is ~80% complete. The main sections that are missing are: +Note: This spec is ~60% complete. -* Logic for the formats of shard chains, who proposes shard blocks, etc. (in an initial release, if desired we could make crosslinks just be Merkle roots of blobs of data; in any case, one can philosophically view the whole point of the shard chains as being a coordination device for choosing what blobs of data to propose as crosslinks) -* Logic for inducting queued validators from the PoW chain -* Penalties for signing or attesting to non-canonical-chain blocks (update: may not be necessary, see https://ethresear.ch/t/attestation-committee-based-full-pos-chains/2259) -* Per-validator proofs of custody, and associated slashing conditions -* Versioning and upgrades +* [ ] Specify how `crystallized_state_root` and `active_state_root` are constructed +* [ ] Specify the shard chain blocks, proposers, etc. +* [ ] Fully specify the registration contract on the PoW chain +* [ ] Flesh out RANDAO, including the hardening against orphaned reveals +* [ ] Add per-validator proofs of custody, including slashing conditions +* [ ] Clearly define all the terms in the glossary +* [ ] Add an appendix for BLS12-381 +* [ ] Add an appendix for the offchain signature aggregation logic +* [ ] Rework the document for readability +* [ ] Undergo peer review, security audits and formal verification -Slashing conditions may include: +**Possible changes and additions** - - Casper FFG slot equivocation [done] - Casper FFG surround [done] - Beacon chain proposal equivocation [done] - Shard chain proposal equivocation - Proof of custody secret leak - Proof of custody wrong custody bit - Proof of custody no secret reveal - RANDAO leak +* [ ] Replace Blake with a STARK-friendly hash function +* [ ] Replacing the IMD fork choice rule with LMD +* [ ] Merge `crystallized_state_root` and `active_state_root` into a single root +* [ ] Add Merklelisation of the state root(s) for light clients +* [ ] Add logic for versioning and upgrades +* [ ] Get rid of dynasties +* [ ] Add a RANDAO slashing condition for early leakage +* [ ] Reworking the `ShardAndCommittee` data structures +* [ ] Reduce the slot duration to 8 seconds +* [ ] Allow for the delayed inclusion of aggregated signatures # Appendix ## Appendix A - Hash function From 21da063d3cc0c543f79fadab2e0395c54c2b16c8 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 12:04:17 +0100 Subject: [PATCH 16/36] Update casper_sharding_v2.1.md --- specs/casper_sharding_v2.1.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index 04c7a2312..117b670f7 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -586,28 +586,29 @@ Finally: Note: This spec is ~60% complete. * [ ] Specify how `crystallized_state_root` and `active_state_root` are constructed -* [ ] Specify the shard chain blocks, proposers, etc. +* [ ] Specify the shard chain blocks, blobs, proposers, etc. * [ ] Fully specify the registration contract on the PoW chain * [ ] Flesh out RANDAO, including the hardening against orphaned reveals * [ ] Add per-validator proofs of custody, including slashing conditions -* [ ] Clearly define all the terms in the glossary * [ ] Add an appendix for BLS12-381 -* [ ] Add an appendix for the offchain signature aggregation logic +* [ ] Add an appendix on gossip networks and the offchain signature aggregation logic +* [ ] Clearly define all the terms in the glossary * [ ] Rework the document for readability * [ ] Undergo peer review, security audits and formal verification **Possible changes and additions** * [ ] Replace Blake with a STARK-friendly hash function -* [ ] Replacing the IMD fork choice rule with LMD +* [ ] Replace the IMD fork choice rule with LMD * [ ] Merge `crystallized_state_root` and `active_state_root` into a single root * [ ] Add Merklelisation of the state root(s) for light clients * [ ] Add logic for versioning and upgrades * [ ] Get rid of dynasties * [ ] Add a RANDAO slashing condition for early leakage -* [ ] Reworking the `ShardAndCommittee` data structures +* [ ] Reworke the `ShardAndCommittee` data structures * [ ] Reduce the slot duration to 8 seconds * [ ] Allow for the delayed inclusion of aggregated signatures +* [ ] Consider separate networking-optimised serialisation formats # Appendix ## Appendix A - Hash function From 1c3b38a7496319d90920b8331b74975496ed4ed4 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 12:10:52 +0100 Subject: [PATCH 17/36] Update casper_sharding_v2.1.md --- specs/casper_sharding_v2.1.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index 117b670f7..d072a804e 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -587,17 +587,24 @@ Note: This spec is ~60% complete. * [ ] Specify how `crystallized_state_root` and `active_state_root` are constructed * [ ] Specify the shard chain blocks, blobs, proposers, etc. +* [ ] Add a double-batched Merkle accumulator for beacon chain blocks +* [ ] Specify the various assumptions (global clock, validator honesty, validator liveness, etc.) * [ ] Fully specify the registration contract on the PoW chain * [ ] Flesh out RANDAO, including the hardening against orphaned reveals * [ ] Add per-validator proofs of custody, including slashing conditions +* [ ] Use a separate hash function for the proof of possession * [ ] Add an appendix for BLS12-381 * [ ] Add an appendix on gossip networks and the offchain signature aggregation logic -* [ ] Clearly define all the terms in the glossary +* [ ] Comprehensively and clearly define all the terms in the glossary * [ ] Rework the document for readability * [ ] Undergo peer review, security audits and formal verification **Possible changes and additions** +* [ ] Deprecate Wei and use 64-bit balances, consistent with a 64-bit EVM2.0 +* [ ] Allow for deposits larger than 32 ETH, as well as deposit top ups +* [ ] Having penalties for having a deposit below 32 ETH +* [ ] Add a `SpecialObject` to change the `withdrawal_shard_id`, `withdrawal_address` or `randao_commitment` * [ ] Replace Blake with a STARK-friendly hash function * [ ] Replace the IMD fork choice rule with LMD * [ ] Merge `crystallized_state_root` and `active_state_root` into a single root @@ -605,7 +612,7 @@ Note: This spec is ~60% complete. * [ ] Add logic for versioning and upgrades * [ ] Get rid of dynasties * [ ] Add a RANDAO slashing condition for early leakage -* [ ] Reworke the `ShardAndCommittee` data structures +* [ ] Rework the `ShardAndCommittee` data structures * [ ] Reduce the slot duration to 8 seconds * [ ] Allow for the delayed inclusion of aggregated signatures * [ ] Consider separate networking-optimised serialisation formats From ca7bb7426e4adc05f3a7ec8e1c56127caff71895 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 12:32:16 +0100 Subject: [PATCH 18/36] Update casper_sharding_v2.1.md --- specs/casper_sharding_v2.1.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index d072a804e..453537cb0 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -587,15 +587,17 @@ Note: This spec is ~60% complete. * [ ] Specify how `crystallized_state_root` and `active_state_root` are constructed * [ ] Specify the shard chain blocks, blobs, proposers, etc. -* [ ] Add a double-batched Merkle accumulator for beacon chain blocks +* [ ] Specify the rules for forced deregistrations +* [ ] Add a double-batched Merkle accumulator for historical beacon chain blocks * [ ] Specify the various assumptions (global clock, validator honesty, validator liveness, etc.) -* [ ] Fully specify the registration contract on the PoW chain -* [ ] Flesh out RANDAO, including the hardening against orphaned reveals +* [ ] Specify in Solidity the registration contract on the PoW chain +* [ ] Specify the RANDAO logic, including the hardening against orphaned reveals * [ ] Add per-validator proofs of custody, including slashing conditions * [ ] Use a separate hash function for the proof of possession * [ ] Add an appendix for BLS12-381 * [ ] Add an appendix on gossip networks and the offchain signature aggregation logic * [ ] Comprehensively and clearly define all the terms in the glossary +* [ ] Clearly document the various edge cases, e.g. with committee sizing * [ ] Rework the document for readability * [ ] Undergo peer review, security audits and formal verification @@ -603,7 +605,7 @@ Note: This spec is ~60% complete. * [ ] Deprecate Wei and use 64-bit balances, consistent with a 64-bit EVM2.0 * [ ] Allow for deposits larger than 32 ETH, as well as deposit top ups -* [ ] Having penalties for having a deposit below 32 ETH +* [ ] Add penalties for a deposit below 32 ETH (or some other threshold) * [ ] Add a `SpecialObject` to change the `withdrawal_shard_id`, `withdrawal_address` or `randao_commitment` * [ ] Replace Blake with a STARK-friendly hash function * [ ] Replace the IMD fork choice rule with LMD From 24c8a53b5c7be0248015413b6c0f8586e79d6b67 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 14:29:56 +0100 Subject: [PATCH 19/36] Update casper_sharding_v2.1.md --- specs/casper_sharding_v2.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index 453537cb0..f7ab010bb 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -590,7 +590,7 @@ Note: This spec is ~60% complete. * [ ] Specify the rules for forced deregistrations * [ ] Add a double-batched Merkle accumulator for historical beacon chain blocks * [ ] Specify the various assumptions (global clock, validator honesty, validator liveness, etc.) -* [ ] Specify in Solidity the registration contract on the PoW chain +* [ ] Specify in Vyper the registration contract on the PoW chain * [ ] Specify the RANDAO logic, including the hardening against orphaned reveals * [ ] Add per-validator proofs of custody, including slashing conditions * [ ] Use a separate hash function for the proof of possession From cf7552ee31bb6be22a7c0d4cf50fd718e528f6b8 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 14:35:11 +0100 Subject: [PATCH 20/36] Rename spec.md to beacon-chain.md --- specs/{spec.md => beacon-chain.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename specs/{spec.md => beacon-chain.md} (100%) diff --git a/specs/spec.md b/specs/beacon-chain.md similarity index 100% rename from specs/spec.md rename to specs/beacon-chain.md From d8c681b695cc88612e87abfe3c93dbb6ed0b1a36 Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Wed, 3 Oct 2018 08:45:28 -0500 Subject: [PATCH 21/36] add 'receipts' when discussion registration txs --- specs/casper_sharding_v2.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index d830c36df..3ac846504 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -7,7 +7,7 @@ ### Introduction -At the center of Ethereum 2.0 is a system chain called the "beacon chain". The beacon chain stores and manages the set of active proof-of-stake validators. In the initial deployment phases of Ethereum 2.0 the only mechanism to become a validator is to make a fixed-size one-way ETH deposit to a registration contract on the Ethereum 1.0 PoW chain. Induction as a validator happens after registration transactions are processed by the beacon chain and after a queuing process. Deregistration is either voluntary or done forcibly as a penalty for misbehavior. +At the center of Ethereum 2.0 is a system chain called the "beacon chain". The beacon chain stores and manages the set of active proof-of-stake validators. In the initial deployment phases of Ethereum 2.0 the only mechanism to become a validator is to make a fixed-size one-way ETH deposit to a registration contract on the Ethereum 1.0 PoW chain. Induction as a validator happens after registration transaction receipts are processed by the beacon chain and after a queuing process. Deregistration is either voluntary or done forcibly as a penalty for misbehavior. The primary source of load on the beacon chain are "attestations". Attestations simultaneously attest to a shard block and a corresponding beacon chain block. A sufficient number of attestations for the same shard block create a "crosslink", confirming the shard segment up to that shard block into the beacon chain. Crosslinks also serve as infrastructure for asynchronous cross-shard communication. From f271d8b35856dcea8db8b3f52eede402e5fd312a Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 14:45:33 +0100 Subject: [PATCH 22/36] Cleanups in get_active_validator_indices and shuffle --- specs/casper_sharding_v2.1.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index e19ef1e0c..7c0d7231e 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -290,29 +290,25 @@ We start off by defining some helper algorithms. First, the function that select ```python def get_active_validator_indices(validators): - o = [] - for i in range(len(validators)): - if validators[i].status == LOGGED_IN: - o.append(i) - return o + return [i for i, v in enumerate(validators) if v.status == LOGGED_IN] ``` Now, a function that shuffles this list: ```python def shuffle(lst, seed): - assert len(lst) <= 16777216 + assert len(lst) <= MAX_VALIDATOR_COUNT o = [x for x in lst] source = seed i = 0 while i < len(lst): - source = blake(source) + source = hash(source) for pos in range(0, 30, 3): m = int.from_bytes(source[pos:pos+3], 'big') remaining = len(lst) - i if remaining == 0: break - rand_max = 16777216 - 16777216 % remaining + rand_max = MAX_VALIDATOR_COUNT - MAX_VALIDATOR_COUNT % remaining if m < rand_max: replacement_pos = (m % remaining) + i o[i], o[replacement_pos] = o[replacement_pos], o[i] From 038db57b9d31be5864c63425cb352da1dea84e7e Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 15:02:58 +0100 Subject: [PATCH 23/36] Minor fixes --- specs/beacon-chain.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index 41e29a09f..546f7c607 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -174,7 +174,7 @@ fields = { 'last_finalized_slot': 'int64', # The current dynasty 'current_dynasty': 'int64', - # Records about the most recent crosslink `for each shard + # Records about the most recent crosslink for each shard 'crosslink_records': [CrosslinkRecord], # Used to select the committees for each shard 'dynasty_seed': 'hash32', @@ -502,8 +502,8 @@ For all (`shard_id`, `shard_block_hash`) tuples, compute the total deposit size Let `time_since_finality = block.slot - last_finalized_slot`, and let `B` be the balance of any given validator whose balance we are adjusting, not including any balance changes from this round of state recalculation. Let: * `total_deposits = sum([v.balance for i, v in enumerate(validators) if i in get_active_validator_indices(validators, current_dynasty)])` and `total_deposits_in_ETH = total_deposits // 10**18` -* `reward_quotient = BASE_REWARD_QUOTIENT * int_sqrt(total_deposits_in_ETH)` (1/this is the per-slot max interest rate) -* `quadratic_penalty_quotient = SQRT_E_DROP_TIME**2` (after D slots, ~D2/2 divided by this is the portion lost by offline validators) +* `reward_quotient = BASE_REWARD_QUOTIENT * int_sqrt(total_deposits_in_ETH)` (this is the per-slot max interest rate) +* `quadratic_penalty_quotient = SQRT_E_DROP_TIME**2` (after `D` slots about `D*D/2/quadratic_penalty_quotient` is the portion lost by offline validators) For each slot `S` in the range `last_state_recalculation - CYCLE_LENGTH ... last_state_recalculation - 1`: @@ -518,13 +518,14 @@ Validators with `status == PENALIZED` also lose `B // reward_quotient + B * time #### Balance recalculations related to crosslink rewards -For each shard S for which a crosslink committee exists in the cycle prior to the most recent cycle (`last_state_recalculation - CYCLE_LENGTH ... last_state_recalculation - 1`), let V be the corresponding validator set. Let `B` be the balance of any given validator whose balance we are adjusting, not including any balance changes from this round of state recalculation. For each S, V do the following: +For each shard `S` for which a crosslink committee exists in the cycle prior to the most recent cycle (`last_state_recalculation - CYCLE_LENGTH ... last_state_recalculation - 1`), let `V` be the corresponding validator set. Let `B` be the balance of any given validator whose balance we are adjusting, not including any balance changes from this round of state recalculation. For each `S`, `V`: -* Let `total_v_deposits` be the total balance of V, and `total_participated_v_deposits` be the total balance of the subset of V that participated (note: it's always true that `total_participated_v_deposits <= total_v_deposits`) +* Let `total_v_deposits` be the total balance of `V` +* Let `total_participated_v_deposits` be the total balance of the subset of `V` that participated (note that `total_participated_v_deposits <= total_v_deposits`) * Let `time_since_last_confirmation` be `block.slot - crosslink_records[S].slot` * Adjust balances as follows: * If `crosslink_records[S].dynasty == current_dynasty`, no reward adjustments - * Otherwise, participating validators' balances are increased by `B // reward_quotient * (2 * total_participated_v_deposits - total_v_deposits) // total_v_deposits`, and non-participating validators' balances are decreased by `B // reward_quotient + B * time_since_last_confirmation // quadratic_penalty_quotient` + * Otherwise, participating validators' balances are increased by `B // reward_quotient * (2 * total_participated_v_deposits - total_v_deposits) // total_v_deposits`, and the balances of non-participating validators are decreased by `B // reward_quotient + B * time_since_last_confirmation // quadratic_penalty_quotient` Let `committees` be the set of committees processed and `time_since_last_confirmation(c)` be the value of `time_since_last_confirmation` in that committee. Validators with `status == PENALIZED` lose `B // reward_quotient + B * sum([time_since_last_confirmation(c) for c in committees]) // len(committees) // quadratic_penalty_quotient`. @@ -532,8 +533,8 @@ Let `committees` be the set of committees processed and `time_since_last_confirm For each `SpecialObject` `obj` in `active_state.pending_specials`: -* **[coverts logouts]**: If `obj.type == 0`, interpret `data[0]` as a validator index as an `int32` and `data[1]` as a signature. If `BLSVerify(pubkey=validators[data[0]].pubkey, msg=hash("bye bye"), sig=data[1])`, and `validators[i].status == LOGGED_IN`, set `validators[i].status = PENDING_EXIT` and `validators[i].exit_slot = current_slot` -* **[covers NO\_DBL\_VOTE, NO\_SURROUND, NO\_DBL\_PROPOSE slashing conditions]:** If `obj.type == 1`, interpret `data[0]` as a list of concatenated `int32` values where each value represents an index into `validators`, `data[1]` as the data being signed and `data[2]` as an aggregate signature. Interpret `data[3:6]` similarly. Verify that both signatures are valid, that the two signatures are signing distinct data, and that they are either signing the same slot number, or that one surrounds the other (ie. `source1 < source2 < target2 < target1`). Let `inds` be the list of indices in both signatures; verify that its length is at least 1. For each validator index `v` in `inds`, set their end dynasty to equal the current dynasty + 1, and if its `status` does not equal `PENALIZED`, then: +* **[covers logouts]**: If `obj.type == 0`, interpret `data[0]` as a validator index as an `int32` and `data[1]` as a signature. If `BLSVerify(pubkey=validators[data[0]].pubkey, msg=hash("bye bye"), sig=data[1])`, and `validators[i].status == LOGGED_IN`, set `validators[i].status = PENDING_EXIT` and `validators[i].exit_slot = current_slot` +* **[covers `NO_DBL_VOTE`, `NO_SURROUND`, `NO_DBL_PROPOSE` slashing conditions]:** If `obj.type == 1`, interpret `data[0]` as a list of concatenated `int32` values where each value represents an index into `validators`, `data[1]` as the data being signed and `data[2]` as an aggregate signature. Interpret `data[3:6]` similarly. Verify that both signatures are valid, that the two signatures are signing distinct data, and that they are either signing the same slot number, or that one surrounds the other (ie. `source1 < source2 < target2 < target1`). Let `inds` be the list of indices in both signatures; verify that its length is at least 1. For each validator index `v` in `inds`, set their end dynasty to equal the current dynasty plus 1, and if its `status` does not equal `PENALIZED`, then: 1. Set its `exit_slot` to equal the current `slot` 2. Set its `status` to `PENALIZED` From 4076804d2ba55db8ab817a890275b548ffd5562f Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 15:13:29 +0100 Subject: [PATCH 24/36] Rework Appendix A on hash functions --- specs/beacon-chain.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index 41e29a09f..651ab2771 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -634,12 +634,8 @@ Slashing conditions may include: # Appendix ## Appendix A - Hash function -The general hash function `hash(x)` in this specification is defined as: -`hash(x) := BLAKE2b-512(x)[0:32]`, where `BLAKE2b-512` (`blake2b512`) algorithm is defined in [RFC 7693](https://tools.ietf.org/html/rfc7693) and input `x` is bytes type. - -* `BLAKE2b-512` is the *default* `BLAKE2b` algorithm with 64-byte digest size. To get a 32-byte result, the general hash function output is defined as the leftmost `32` bytes of `BLAKE2b-512` hash output. -* The design rationale is keeping using the default algorithm and avoiding too much dependency on external hash function libraries. +We aim to have a STARK-friendly hash function `hash(x)` for the production launch of the beacon chain. While the standardisation process for a STARK-friendly hash function takes place—led by STARKware, who will produce a detailed report with recommendations—we use `BLAKE2b-512` as a placeholder. Specifically, we set `hash(x) := BLAKE2b-512(x)[0:32]` where the `BLAKE2b-512` algorithm is defined in [RFC 7693](https://tools.ietf.org/html/rfc7693) and the input `x` is of type `bytes`. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 48c2643f47d9ddf14d7fbd3605177111f24f3238 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 15:16:38 +0100 Subject: [PATCH 25/36] Update beacon-chain.md --- specs/beacon-chain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index 546f7c607..48bbf2301 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -502,7 +502,7 @@ For all (`shard_id`, `shard_block_hash`) tuples, compute the total deposit size Let `time_since_finality = block.slot - last_finalized_slot`, and let `B` be the balance of any given validator whose balance we are adjusting, not including any balance changes from this round of state recalculation. Let: * `total_deposits = sum([v.balance for i, v in enumerate(validators) if i in get_active_validator_indices(validators, current_dynasty)])` and `total_deposits_in_ETH = total_deposits // 10**18` -* `reward_quotient = BASE_REWARD_QUOTIENT * int_sqrt(total_deposits_in_ETH)` (this is the per-slot max interest rate) +* `reward_quotient = BASE_REWARD_QUOTIENT * int_sqrt(total_deposits_in_ETH)` (`1/reward_quotient` is the per-slot max interest rate) * `quadratic_penalty_quotient = SQRT_E_DROP_TIME**2` (after `D` slots about `D*D/2/quadratic_penalty_quotient` is the portion lost by offline validators) For each slot `S` in the range `last_state_recalculation - CYCLE_LENGTH ... last_state_recalculation - 1`: From 86d0c209b78f2a02b46cfd7e411c90beee107a04 Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Wed, 3 Oct 2018 09:28:42 -0500 Subject: [PATCH 26/36] fix rand_max in shuffle alg. add note about usage --- specs/beacon-chain.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index 1b8fa4c41..ddea00e70 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -289,7 +289,11 @@ Now, a function that shuffles this list: ```python def shuffle(lst, seed): - assert len(lst) <= MAX_VALIDATOR_COUNT + # entropy is consumed in 3 byte chunks + # rand_max is defined to remove the modulo bias from this entropy source + rand_max = 2**24 + assert len(lst) <= rand_max + o = [x for x in lst] source = seed i = 0 @@ -300,7 +304,7 @@ def shuffle(lst, seed): remaining = len(lst) - i if remaining == 0: break - rand_max = MAX_VALIDATOR_COUNT - MAX_VALIDATOR_COUNT % remaining + rand_max = rand_max - rand_max % remaining if m < rand_max: replacement_pos = (m % remaining) + i o[i], o[replacement_pos] = o[replacement_pos], o[i] From e7ff5ad5e7abc949f0854ef6f975dfb68128b64d Mon Sep 17 00:00:00 2001 From: Vitalik Buterin Date: Wed, 3 Oct 2018 10:29:00 -0400 Subject: [PATCH 27/36] Added RANDAO support (without multi-skip mechanism) --- specs/casper_sharding_v2.1.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index c0d2c231c..ec590d361 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -90,7 +90,7 @@ fields = { # Hash of the crystallized state 'crystallized_state_root': 'hash32', # Logouts, penalties, etc etc - 'specials': [SpecialObject] + 'specials': [SpecialObject], } ``` @@ -139,7 +139,9 @@ fields = { # Special objects that have not yet been processed 'pending_specials': [SpecialObject], # Most recent 2 * CYCLE_LENGTH block hashes, older to newer - 'recent_block_hashes': ['hash32'] + 'recent_block_hashes': ['hash32'], + # RANDAO state + 'randao_mix': 'hash32' } ``` @@ -459,7 +461,9 @@ For each one of these attestations: Extend the list of `AttestationRecord` objects in the `active_state` with those included in the block, ordering the new additions in the same order as they came in the block. Similarly extend the list of `SpecialObject` objects in the `active_state` with those included in the block. -Verify that the `parent.slot % len(get_shards_and_committees_for_slot(crystallized_state, parent.slot)[0].committee)`'th attester in `get_shards_and_committees_for_slot(crystallized_state, parent.slot)[0]` is part of the first (ie. item 0 in the array) `AttestationRecord` object; this attester can be considered to be the proposer of the parent block. In general, when a block is produced, it is broadcasted at the network layer along with the attestation from its proposer. +Let `proposer_index` be the validator index of the `parent.slot % len(get_shards_and_committees_for_slot(crystallized_state, parent.slot)[0].committee)`'th attester in `get_shards_and_committees_for_slot(crystallized_state, parent.slot)[0]`. Verify that an attestation from this validator is part of the first (ie. item 0 in the array) `AttestationRecord` object; this attester can be considered to be the proposer of the parent block. In general, when a block is produced, it is broadcasted at the network layer along with the attestation from its proposer. + +Additionally, verify that `hash(block.randao_reveal) == crystallized_state.validators[proposer_index].randao_commitment`, and set `active_state.randao_mix = xor(active_state.randao_mix, block.randao_reveal)` and `crystallized_state.validators[proposer_index].randao_commitment = block.randao_reveal`. ### State recalculations (every `CYCLE_LENGTH` slots) @@ -579,7 +583,7 @@ Finally: * Set `last_dynasty_start = crystallized_state.last_state_recalculation` * Set `crystallized_state.current_dynasty += 1` * Let `next_start_shard = (shard_and_committee_for_slots[-1][-1].shard_id + 1) % SHARD_COUNT` -* Set `shard_and_committee_for_slots[CYCLE_LENGTH:] = get_new_shuffling(block.ancestor_hashes[0], validators, next_start_shard)` +* Set `shard_and_committee_for_slots[CYCLE_LENGTH:] = get_new_shuffling(active_state.randao_mix, validators, next_start_shard)` ------- From 8dffb4e32b23ebc32829957553b4b2d383d88ef2 Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Wed, 3 Oct 2018 09:37:21 -0500 Subject: [PATCH 28/36] remove extra comma from spec --- specs/beacon-chain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index 05d7849cd..ef71bff70 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -101,7 +101,7 @@ fields = { # Hash of the crystallized state 'crystallized_state_root': 'hash32', # Logouts, penalties, etc etc - 'specials': [SpecialObject], + 'specials': [SpecialObject] } ``` From 538e4e1f887e39ecdf44ee583d1ce3d1c84d1f00 Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 21:35:47 +0100 Subject: [PATCH 29/36] Rename simpleserialize.md to simple-serialize.md For consistency with beacon-chain.md --- specs/{simpleserialize.md => simple-serialize.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename specs/{simpleserialize.md => simple-serialize.md} (100%) diff --git a/specs/simpleserialize.md b/specs/simple-serialize.md similarity index 100% rename from specs/simpleserialize.md rename to specs/simple-serialize.md From 2f3469161544335ad82b423d4dbb235519af72ff Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 22:00:05 +0100 Subject: [PATCH 30/36] Minor cleanups --- specs/beacon-chain.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index a7de5e8cd..53e97814c 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -36,7 +36,6 @@ The primary source of load on the beacon chain are "attestations". Attestations | `SHARD_COUNT` | 2**10 (= 1,024)| shards | | `DEPOSIT_SIZE` | 2**5 (= 32) | ETH | | `MIN_COMMITTEE_SIZE` | 2**7 (= 128) | validators | -| `MAX_VALIDATOR_COUNT` | 2**22 ( = 4,194,304) | validators | | `GENESIS_TIME` | **TBD** | seconds | | `SLOT_DURATION` | 2**4 (= 16) | seconds | | `CYCLE_LENGTH` | 2**6 (= 64) | slots | ~17 minutes | @@ -48,7 +47,6 @@ The primary source of load on the beacon chain are "attestations". Attestations **Notes** -* At most `MAX_VALIDATOR_COUNT * DEPOSIT_SIZE` (~134 million ETH) can be staked. * The `SQRT_E_DROP_TIME` constant is the amount of time it takes for the quadratic leak to cut deposits of non-participating validators by ~39.4%. * The `BASE_REWARD_QUOTIENT` constant is the per-slot interest rate assuming all validators are participating, assuming total deposits of 1 ETH. It corresponds to ~3.88% annual interest assuming 10 million participating ETH. * At most `1/MAX_VALIDATOR_CHURN_QUOTIENT` of the validators can change during each dynasty. @@ -68,15 +66,9 @@ The primary source of load on the beacon chain are "attestations". Attestations ### PoW chain registration contract -The initial deployment phases of Ethereum 2.0 are implemented without consensus changes to the PoW chain. A registration contract is added to the PoW chain to deposit ETH. This contract has a `registration` function which takes the following arguments: +The initial deployment phases of Ethereum 2.0 are implemented without consensus changes to the PoW chain. A registration contract is added to the PoW chain to deposit ETH. This contract has a `registration` function which takes as arguments `pubkey`, `withdrawal_shard`, `withdrawal_address`, `randao_commitment` as defined in a `ValidatorRecord` below. A BLS `proof_of_possession` of types `bytes` is given as a final argument. -1) `pubkey` (bytes) -2) `withdrawal_shard_id` (int) -3) `withdrawal_address` (address) -4) `randao_commitment` (bytes32) -5) `bls_proof_of_possession` (bytes) - -The registration contract does minimal validation, pushing most of the registration logic to the beacon chain. In particular, the BLS proof of possession (based on the BLS12-381 curve) is not verified by the registration contract. +The registration contract emits a log with the various arguments for consumption by the beacon chain. It does not do validation, pushing the registration logic to the beacon chain. In particular, the proof of possession (based on the BLS12-381 curve) is not verified by the registration contract. ## Data Structures @@ -86,11 +78,11 @@ Beacon chain block structure: ```python fields = { - # Hash of ancestor blocks (32 items, i'th is 2**i'th ancestor or zero bytes) + # Skip list of ancestor block hashes. The i'th item is 2**i'th ancestor (or zero bytes) for i = 0, ..., 31 'ancestor_hashes': ['hash32'], - # Slot number (for the PoS mechanism) + # Slot number 'slot': 'int64', - # Randao commitment reveal + # RANDAO commitment reveal 'randao_reveal': 'hash32', # Attestations 'attestations': [AttestationRecord], @@ -363,7 +355,7 @@ def get_block_hash(active_state, curblock, slot): return active_state.recent_block_hashes[slot - earliest_slot_in_array] ``` -`get_block_hash(_, _, h)` should always return the block in the chain at slot `h`, and `get_shards_and_committees_for_slot(_, h)` should not change unless the dynasty changes. +`get_block_hash(_, _, s)` should always return the block in the chain at slot `s`, and `get_shards_and_committees_for_slot(_, s)` should not change unless the dynasty changes. We define a function to "add a link" to the validator hash chain, used when a validator is added or removed: From 9a05c79e3ecf1fafe2ceeb71bee0ff1207dc458f Mon Sep 17 00:00:00 2001 From: Justin Date: Wed, 3 Oct 2018 22:15:43 +0100 Subject: [PATCH 31/36] Update casper_sharding_v2.1.md --- specs/casper_sharding_v2.1.md | 47 ++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/specs/casper_sharding_v2.1.md b/specs/casper_sharding_v2.1.md index f7ab010bb..5c4106cbf 100644 --- a/specs/casper_sharding_v2.1.md +++ b/specs/casper_sharding_v2.1.md @@ -585,39 +585,40 @@ Finally: Note: This spec is ~60% complete. -* [ ] Specify how `crystallized_state_root` and `active_state_root` are constructed +**Missing** + +* [ ] Specify how `crystallized_state_root` and `active_state_root` are constructed, including Merklelisation logic for light clients +* [ ] Specify the rules around acceptable values for `pow_chain_ref` * [ ] Specify the shard chain blocks, blobs, proposers, etc. * [ ] Specify the rules for forced deregistrations -* [ ] Add a double-batched Merkle accumulator for historical beacon chain blocks -* [ ] Specify the various assumptions (global clock, validator honesty, validator liveness, etc.) -* [ ] Specify in Vyper the registration contract on the PoW chain -* [ ] Specify the RANDAO logic, including the hardening against orphaned reveals -* [ ] Add per-validator proofs of custody, including slashing conditions -* [ ] Use a separate hash function for the proof of possession -* [ ] Add an appendix for BLS12-381 +* [ ] Specify the various assumptions (global clock, networking latency, validator honesty, validator liveness, etc.) +* [ ] Specify (in a separate Vyper file) the registration contract on the PoW chain +* [ ] Specify the bootstrapping logic for the beacon chain genesis (e.g. specify a minimum number validators before the genesis block) +* [ ] Specify the logic for proofs of custody, including slashing conditions +* [ ] Add an appendix about the BLS12-381 curve * [ ] Add an appendix on gossip networks and the offchain signature aggregation logic -* [ ] Comprehensively and clearly define all the terms in the glossary -* [ ] Clearly document the various edge cases, e.g. with committee sizing -* [ ] Rework the document for readability +* [ ] Add a glossary (in a separate `glossary.md`) to comprehensively and precisely define all the terms * [ ] Undergo peer review, security audits and formal verification -**Possible changes and additions** +**Possible rework/additions** -* [ ] Deprecate Wei and use 64-bit balances, consistent with a 64-bit EVM2.0 -* [ ] Allow for deposits larger than 32 ETH, as well as deposit top ups -* [ ] Add penalties for a deposit below 32 ETH (or some other threshold) -* [ ] Add a `SpecialObject` to change the `withdrawal_shard_id`, `withdrawal_address` or `randao_commitment` -* [ ] Replace Blake with a STARK-friendly hash function * [ ] Replace the IMD fork choice rule with LMD -* [ ] Merge `crystallized_state_root` and `active_state_root` into a single root -* [ ] Add Merklelisation of the state root(s) for light clients -* [ ] Add logic for versioning and upgrades +* [ ] Merklelise `crystallized_state_root` and `active_state_root` into a single root +* [ ] Replace Blake with a STARK-friendly hash function * [ ] Get rid of dynasties -* [ ] Add a RANDAO slashing condition for early leakage -* [ ] Rework the `ShardAndCommittee` data structures * [ ] Reduce the slot duration to 8 seconds * [ ] Allow for the delayed inclusion of aggregated signatures -* [ ] Consider separate networking-optimised serialisation formats +* [ ] Use a separate networking-optimised serialisation format for networking +* [ ] Harden RANDAO against orphaned reveals +* [ ] Introduce a RANDAO slashing condition for early leakage +* [ ] Use a separate hash function for the proof of possession +* [ ] Rework the `ShardAndCommittee` data structures +* [ ] Add a double-batched Merkle accumulator for historical beacon chain blocks +* [ ] Allow for deposits larger than 32 ETH, as well as deposit top-ups +* [ ] Add penalties for a deposit below 32 ETH (or some other threshold) +* [ ] Add a `SpecialObject` to (re)register +* [ ] Rework the document for readability +* [ ] Clearly document the various edge cases, e.g. with committee sizing # Appendix ## Appendix A - Hash function From a85f59779a7c44d4456fcee7ed7cf3280b106235 Mon Sep 17 00:00:00 2001 From: Justin Date: Thu, 4 Oct 2018 11:09:39 +0100 Subject: [PATCH 32/36] Clean up data structures This includes: * Giving every data structure a name (e.g. `BeaconChainBlock`) * Making data structure names consistent (e.g. `SpecialObject` => `SpecialRecord`) * Arranging the fields within the data structures in a more logical/consistent manner * Reworking the comments to be more concise and to the point * Rename some fields for consistency: * `shard_id` => `shard` (for consistency with `withdrawal_shard`) * `last_state_recalculation` => `last_state_recalculation_slot` (for consistency with `last_finalized_slot`, `last_justified_slot`, etc.) * `current_dynasty` => `dynasty` (for consistency with `slot`, `shard`) * `pow_chain_ref` => `pow_chain_reference` (abbreviations are avoided throughout) * Various other cleanups --- specs/beacon-chain.md | 236 +++++++++++++++++++++--------------------- 1 file changed, 117 insertions(+), 119 deletions(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index 5437e32ad..16233c8dd 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -70,162 +70,160 @@ The initial deployment phases of Ethereum 2.0 are implemented without consensus The registration contract emits a log with the various arguments for consumption by the beacon chain. It does not do validation, pushing the registration logic to the beacon chain. In particular, the proof of possession (based on the BLS12-381 curve) is not verified by the registration contract. -## Data Structures +## Data structures +### Beacon chain blocks -#### Beacon chain blocks - -Beacon chain block structure: +A `BeaconChainBlock` has the following fields: ```python -fields = { - # Skip list of ancestor block hashes. The i'th item is 2**i'th ancestor (or zero bytes) for i = 0, ..., 31 - 'ancestor_hashes': ['hash32'], +{ # Slot number 'slot': 'int64', - # RANDAO commitment reveal + # Proposer RANDAO reveal 'randao_reveal': 'hash32', + # Recent PoW chain reference (block hash) + 'pow_chain_reference': 'hash32', + # Skip list of ancestor block hashes (i'th item is 2**i'th ancestor (or zero) for i = 0, ..., 31) + 'ancestor_hashes': ['hash32'], + # Active state root + 'active_state_root': 'hash32', + # Crystallized state root + 'crystallized_state_root': 'hash32', # Attestations 'attestations': [AttestationRecord], - # Reference to PoW chain block - 'pow_chain_ref': 'hash32', - # Hash of the active state - 'active_state_root': 'hash32', - # Hash of the crystallized state - 'crystallized_state_root': 'hash32', - # Logouts, penalties, etc etc - 'specials': [SpecialObject] + # Specials (e.g. logouts, penalties) + 'specials': [SpecialRecord] } ``` -A `SpecialObject` looks as follows: +An `AttestationRecord` has the following fields: ```python -fields = { - 'type': 'int8', - 'data': ['bytes'] -} -``` - -An `AttestationRecord` looks as follows: - -```python -fields = { +{ # Slot number 'slot': 'int64', - # Shard ID - 'shard_id': 'int16', - # List of block hashes that this signature is signing over that - # are NOT part of the current chain, in order of oldest to newest + # Shard number + 'shard': 'int16', + # Block hashes not part of the current chain, oldest to newest 'oblique_parent_hashes': ['hash32'], - # Block hash in the shard that we are attesting to + # Shard block hash being attested to 'shard_block_hash': 'hash32', - # Who is participating + # Attester participation bitfield (1 bit per attester) 'attester_bitfield': 'bytes', - # Last justified block + # Slot of last justified block 'justified_slot': 'int64', + # Hash of last justified block 'justified_block_hash': 'hash32', - # The actual signature + # BLS aggregate signature 'aggregate_sig': ['int256'] } ``` -#### Beacon chain state - -The beacon chain state is split into two parts, _active state_ and _crystallized state_. - -Here's the `ActiveState`: +A `SpecialRecord` has the following fields: ```python fields = { - # Attestations that have not yet been processed - 'pending_attestations': [AttestationRecord], - # Special objects that have not yet been processed - 'pending_specials': [SpecialObject], - # Most recent 2 * CYCLE_LENGTH block hashes, older to newer - 'recent_block_hashes': ['hash32'] + # Type + 'type': 'int8', + # Data + 'data': ['bytes'] } ``` -Here's the `CrystallizedState`: +### Beacon chain state + +For convenience we define the beacon chain state in two parts: "active state" and "crystallized state". + +The `ActiveState` has the following fields: ```python -fields = { +{ + # Most recent 2 * CYCLE_LENGTH block hashes, oldest to newest + 'recent_block_hashes': ['hash32'], + # Attestations not yet processed + 'pending_attestations': [AttestationRecord], + # Specials not yet been processed + 'pending_specials': [SpecialRecord] +} +``` + +The `CrystallizedState` has the following fields: + +```python +{ + # Dynasty number + 'dynasty': 'int64', + # Dynasty seed (from randomness beacon) + 'dynasty_seed': 'hash32', + # Dynasty start + 'dynasty_start_slot': 'int64', # List of validators 'validators': [ValidatorRecord], - # Last CrystallizedState recalculation - 'last_state_recalculation': 'int64', - # What active validators are part of the attester set - # at what slot, and in what shard. Starts at slot - # last_state_recalculation - CYCLE_LENGTH - 'shard_and_committee_for_slots': [[ShardAndCommittee]], - # The last justified slot - 'last_justified_slot': 'int64', - # Number of consecutive justified slots ending at this one - 'justified_streak': 'int64', - # The last finalized slot + # Most recent crosslink for each shard + 'crosslinks': [CrosslinkRecord], + # Last crystallized state recalculation + 'last_state_recalculation_slot': 'int64', + # Last finalized slot 'last_finalized_slot': 'int64', - # The current dynasty - 'current_dynasty': 'int64', - # Records about the most recent crosslink for each shard - 'crosslink_records': [CrosslinkRecord], - # Used to select the committees for each shard - 'dynasty_seed': 'hash32', - # Start of the current dynasty - 'dynasty_start': 'int64', + # Last justified slot + 'last_justified_slot': 'int64', + # Number of consecutive justified slots + 'justified_streak': 'int64', + # Committee members and their assigned shard, per slot + 'shard_and_committee_for_slots': [[ShardAndCommittee]], # Total deposits penalized in the given withdrawal period 'deposits_penalized_in_period': ['int32'], - # Hash chain of validator set changes, allows light clients to track deltas more easily + # Hash chain of validator set changes (for light clients to easily track deltas) 'validator_set_delta_hash_chain': 'hash32' } ``` -Each `ValidatorRecord` is an object containing information about a validator: +A `ValidatorRecord` has the following fields: ```python -fields = { - # The validator's public key +{ + # BLS public key 'pubkey': 'int256', - # What shard the validator's balance will be sent to - # after withdrawal + # Withdrawal shard number 'withdrawal_shard': 'int16', - # And what address + # Withdrawal address 'withdrawal_address': 'address', - # The validator's current RANDAO beacon commitment + # RANDAO commitment 'randao_commitment': 'hash32', - # Current balance + # Balance 'balance': 'int128', - # Status (see status codes in constants above) + # Status code 'status': 'int8', - # Slot where this validator leaves + # Slot when validator exited (or 0) 'exit_slot': 'int64' } ``` -A `ShardAndCommittee` object is of the form: +A `ShardAndCommittee` object has the following fields: ```python -fields = { - # The shard ID - 'shard_id': 'int16', +{ + # Shard number + 'shard': 'int16', # Validator indices 'committee': ['int24'] } ``` -And a `CrosslinkRecord` contains information about the last fully formed crosslink to be submitted into the chain: +A `CrosslinkRecord` has the following fields: ```python -fields = { - # What dynasty the crosslink was submitted in +{ + # Dynasty number 'dynasty': 'int64', - # What slot + # Slot number 'slot': 'int64', - # The block hash + # Beacon chain block hash 'hash': 'hash32' } ``` -### Beacon chain processing +## Beacon chain processing The beacon chain is the "main chain" of the PoS system. The beacon chain's main responsibilities are: @@ -239,7 +237,7 @@ For a block on the beacon chain to be processed by a node, four conditions have * The parent pointed to by the `ancestor_hashes[0]` has already been processed and accepted * An attestation from the _proposer_ of the block (see later for definition) is included along with the block in the network message object -* The PoW chain block pointed to by the `pow_chain_ref` has already been processed and accepted +* The PoW chain block pointed to by the `pow_chain_reference` has already been processed and accepted * The node's local clock time is greater than or equal to the minimum timestamp as computed by `GENESIS_TIME + block.slot * SLOT_DURATION` If these conditions are not met, the client should delay processing the block until the conditions are all satisfied. @@ -263,7 +261,7 @@ Here's an example of its working (green is finalized blocks, yellow is justified We now define the state transition function. At the high level, the state transition is made up of two parts: 1. The per-block processing, which happens every block, and affects the `ActiveState` only -2. The crystallized state recalculation, which happens only if `block.slot >= last_state_recalculation + CYCLE_LENGTH`, and affects the `CrystallizedState` and `ActiveState` +2. The crystallized state recalculation, which happens only if `block.slot >= last_state_recalculation_slot + CYCLE_LENGTH`, and affects the `CrystallizedState` and `ActiveState` The crystallized state recalculation generally focuses on changes to the validator set, including adjusting balances and adding and removing validators, as well as processing crosslinks and managing block justification, and the per-block processing generally focuses on verifying aggregate signatures and saving temporary records relating to the in-block activity in the `ActiveState`. @@ -328,10 +326,10 @@ def get_new_shuffling(seed, validators, crosslinking_start_shard): o = [] for i, slot_indices in enumerate(split(shuffle(active_validators, seed), CYCLE_LENGTH)): shard_indices = split(slot_indices, committees_per_slot) - shard_id_start = crosslinking_start_shard + \ + shard_start = crosslinking_start_shard + \ i * committees_per_slot // slots_per_committee o.append([ShardAndCommittee( - shard_id = (shard_id_start + j) % SHARD_COUNT, + shard = (shard_start + j) % SHARD_COUNT, committee = indices ) for j, indices in enumerate(shard_indices)]) return o @@ -345,7 +343,7 @@ We also define two functions for retrieving data from the state: ```python def get_shards_and_committees_for_slot(crystallized_state, slot): - earliest_slot_in_array = crystallized_state.last_state_recalculation - CYCLE_LENGTH + earliest_slot_in_array = crystallized_state.last_state_recalculation_slot - CYCLE_LENGTH assert earliest_slot_in_array <= slot < earliest_slot_in_array + CYCLE_LENGTH * 2 return crystallized_state.shard_and_committee_for_slots[slot - earliest_slot_in_array] @@ -395,15 +393,15 @@ def on_startup(initial_validator_entries): cs = CrystallizedState() x = get_new_shuffling(bytes([0] * 32), validators, 0) cs.shard_and_committee_for_slots = x + x - cs.current_dynasty = 1 - cs.crosslink_records = [CrosslinkRecord(dynasty=0, slot=0, hash=bytes([0] * 32)) + cs.dynasty = 1 + cs.crosslinks = [CrosslinkRecord(dynasty=0, slot=0, hash=bytes([0] * 32)) for i in range(SHARD_COUNT)] # Setup active state as = ActiveState() as.recent_block_hashes = [bytes([0] * 32) for _ in range(CYCLE_LENGTH * 2)] ``` -The `CrystallizedState()` and `ActiveState()` constructors should initialize all values to zero byes, an empty value or an empty array depending on context. The `add_validator` routine is defined below. +The `CrystallizedState()` and `ActiveState()` constructors should initialize all values to zero bytes, an empty value or an empty array depending on context. The `add_validator` routine is defined below. ### Routine for adding a validator @@ -466,38 +464,38 @@ For each one of these attestations: * Verify that `slot <= parent.slot` and `slot >= max(parent.slot - CYCLE_LENGTH + 1, 0)` * Verify that the `justified_slot` and `justified_block_hash` given are in the chain and are equal to or earlier than the `last_justified_slot` in the crystallized state. * Compute `parent_hashes` = `[get_block_hash(active_state, block, slot - CYCLE_LENGTH + i) for i in range(1, CYCLE_LENGTH - len(oblique_parent_hashes) + 1)] + oblique_parent_hashes` (eg, if `CYCLE_LENGTH = 4`, `slot = 5`, the actual block hashes starting from slot 0 are `Z A B C D E F G H I J`, and `oblique_parent_hashes = [D', E']` then `parent_hashes = [B, C, D' E']`). Note that when *creating* an attestation for a block, the hash of that block itself won't yet be in the `active_state`, so you would need to add it explicitly. -* Let `attestation_indices` be `get_shards_and_committees_for_slot(crystallized_state, slot)[x]`, choosing `x` so that `attestation_indices.shard_id` equals the `shard_id` value provided to find the set of validators that is creating this attestation record. +* Let `attestation_indices` be `get_shards_and_committees_for_slot(crystallized_state, slot)[x]`, choosing `x` so that `attestation_indices.shard` equals the `shard` value provided to find the set of validators that is creating this attestation record. * Verify that `len(attester_bitfield) == ceil_div8(len(attestation_indices))`, where `ceil_div8 = (x + 7) // 8`. Verify that bits `len(attestation_indices)....` and higher, if present (i.e. `len(attestation_indices)` is not a multiple of 8), are all zero * Derive a group public key by adding the public keys of all of the attesters in `attestation_indices` for whom the corresponding bit in `attester_bitfield` (the ith bit is `(attester_bitfield[i // 8] >> (7 - (i %8))) % 2`) equals 1 -* Verify that `aggregate_sig` verifies using the group pubkey generated and `hash(slot.to_bytes(8, 'big') + parent_hashes + shard_id + shard_block_hash + justified_slot.to_bytes(8, 'big'))` as the message. +* Verify that `aggregate_sig` verifies using the group pubkey generated and `hash(slot.to_bytes(8, 'big') + parent_hashes + shard + shard_block_hash + justified_slot.to_bytes(8, 'big'))` as the message. -Extend the list of `AttestationRecord` objects in the `active_state` with those included in the block, ordering the new additions in the same order as they came in the block. Similarly extend the list of `SpecialObject` objects in the `active_state` with those included in the block. +Extend the list of `AttestationRecord` objects in the `active_state` with those included in the block, ordering the new additions in the same order as they came in the block. Similarly extend the list of `SpecialRecord` objects in the `active_state` with those included in the block. Verify that the `parent.slot % len(get_shards_and_committees_for_slot(crystallized_state, parent.slot)[0].committee)`'th attester in `get_shards_and_committees_for_slot(crystallized_state, parent.slot)[0]` is part of the first (ie. item 0 in the array) `AttestationRecord` object; this attester can be considered to be the proposer of the parent block. In general, when a block is produced, it is broadcasted at the network layer along with the attestation from its proposer. ### State recalculations (every `CYCLE_LENGTH` slots) -Repeat while `slot - last_state_recalculation >= CYCLE_LENGTH`: +Repeat while `slot - last_state_recalculation_slot >= CYCLE_LENGTH`: #### Adjust justified slots and crosslink status -For all slots `s` in `last_state_recalculation - CYCLE_LENGTH ... last_state_recalculation - 1`: +For all slots `s` in `last_state_recalculation_slot - CYCLE_LENGTH ... last_state_recalculation_slot - 1`: * Determine the total set of validators that attested to that block at least once * Determine the total balance of these validators. If this value times three equals or exceeds the total balance of all active validators times two, set `last_justified_slot = max(last_justified_slot, s)` and `justified_streak += 1`. Otherwise, set `justified_streak = 0` * If `justified_streak >= CYCLE_LENGTH + 1`, set `last_finalized_slot = max(last_finalized_slot, s - CYCLE_LENGTH - 1)` -For all (`shard_id`, `shard_block_hash`) tuples, compute the total deposit size of validators that attested to that block hash for that shard. If this value times three equals or exceeds the total balance of all validators in the committee times two, and the current dynasty exceeds `crosslink_records[shard_id].dynasty`, set `crosslink_records[shard_id] = CrosslinkRecord(dynasty=current_dynasty, slot=block.last_state_recalculation + CYCLE_LENGTH, hash=shard_block_hash)`. +For all (`shard`, `shard_block_hash`) tuples, compute the total deposit size of validators that attested to that block hash for that shard. If this value times three equals or exceeds the total balance of all validators in the committee times two, and the current dynasty exceeds `crosslinks[shard].dynasty`, set `crosslinks[shard] = CrosslinkRecord(dynasty=dynasty, slot=block.last_state_recalculation_slot + CYCLE_LENGTH, hash=shard_block_hash)`. #### Balance recalculations related to FFG rewards Let `time_since_finality = block.slot - last_finalized_slot`, and let `B` be the balance of any given validator whose balance we are adjusting, not including any balance changes from this round of state recalculation. Let: -* `total_deposits = sum([v.balance for i, v in enumerate(validators) if i in get_active_validator_indices(validators, current_dynasty)])` and `total_deposits_in_ETH = total_deposits // 10**18` +* `total_deposits = sum([v.balance for i, v in enumerate(validators) if i in get_active_validator_indices(validators, dynasty)])` and `total_deposits_in_ETH = total_deposits // 10**18` * `reward_quotient = BASE_REWARD_QUOTIENT * int_sqrt(total_deposits_in_ETH)` (`1/reward_quotient` is the per-slot max interest rate) * `quadratic_penalty_quotient = SQRT_E_DROP_TIME**2` (after `D` slots about `D*D/2/quadratic_penalty_quotient` is the portion lost by offline validators) -For each slot `S` in the range `last_state_recalculation - CYCLE_LENGTH ... last_state_recalculation - 1`: +For each slot `S` in the range `last_state_recalculation_slot - CYCLE_LENGTH ... last_state_recalculation_slot - 1`: * Let `total_participated_deposits` be the total balance of validators that voted for the correct hash in slot `S` (ie. the hash that actually is the hash of the block at that slot in the current chain); note that in the normal case, every validator will be in one of the `CYCLE_LENGTH` slots following the slot and so can vote for a hash in slot `S`. If `time_since_finality <= 3 * CYCLE_LENGTH`, then adjust participating and non-participating validators' balances as follows: * Participating validators gain `B // reward_quotient * (2 * total_participated_deposits - total_deposits) // total_deposits` (note: this may be negative) @@ -510,20 +508,20 @@ Validators with `status == PENALIZED` also lose `B // reward_quotient + B * time #### Balance recalculations related to crosslink rewards -For each shard `S` for which a crosslink committee exists in the cycle prior to the most recent cycle (`last_state_recalculation - CYCLE_LENGTH ... last_state_recalculation - 1`), let `V` be the corresponding validator set. Let `B` be the balance of any given validator whose balance we are adjusting, not including any balance changes from this round of state recalculation. For each `S`, `V`: +For each shard `S` for which a crosslink committee exists in the cycle prior to the most recent cycle (`last_state_recalculation_slot - CYCLE_LENGTH ... last_state_recalculation_slot - 1`), let `V` be the corresponding validator set. Let `B` be the balance of any given validator whose balance we are adjusting, not including any balance changes from this round of state recalculation. For each `S`, `V`: * Let `total_v_deposits` be the total balance of `V` * Let `total_participated_v_deposits` be the total balance of the subset of `V` that participated (note that `total_participated_v_deposits <= total_v_deposits`) -* Let `time_since_last_confirmation` be `block.slot - crosslink_records[S].slot` +* Let `time_since_last_confirmation` be `block.slot - crosslinks[S].slot` * Adjust balances as follows: - * If `crosslink_records[S].dynasty == current_dynasty`, no reward adjustments + * If `crosslinks[S].dynasty == dynasty`, no reward adjustments * Otherwise, participating validators' balances are increased by `B // reward_quotient * (2 * total_participated_v_deposits - total_v_deposits) // total_v_deposits`, and the balances of non-participating validators are decreased by `B // reward_quotient + B * time_since_last_confirmation // quadratic_penalty_quotient` Let `committees` be the set of committees processed and `time_since_last_confirmation(c)` be the value of `time_since_last_confirmation` in that committee. Validators with `status == PENALIZED` lose `B // reward_quotient + B * sum([time_since_last_confirmation(c) for c in committees]) // len(committees) // quadratic_penalty_quotient`. #### Process penalties, logouts and other special objects -For each `SpecialObject` `obj` in `active_state.pending_specials`: +For each `SpecialRecord` `obj` in `active_state.pending_specials`: * **[covers logouts]**: If `obj.type == 0`, interpret `data[0]` as a validator index as an `int32` and `data[1]` as a signature. If `BLSVerify(pubkey=validators[data[0]].pubkey, msg=hash("bye bye"), sig=data[1])`, and `validators[i].status == LOGGED_IN`, set `validators[i].status = PENDING_EXIT` and `validators[i].exit_slot = current_slot` * **[covers `NO_DBL_VOTE`, `NO_SURROUND`, `NO_DBL_PROPOSE` slashing conditions]:** If `obj.type == 1`, interpret `data[0]` as a list of concatenated `int32` values where each value represents an index into `validators`, `data[1]` as the data being signed and `data[2]` as an aggregate signature. Interpret `data[3:6]` similarly. Verify that both signatures are valid, that the two signatures are signing distinct data, and that they are either signing the same slot number, or that one surrounds the other (ie. `source1 < source2 < target2 < target1`). Let `inds` be the list of indices in both signatures; verify that its length is at least 1. For each validator index `v` in `inds`, set their end dynasty to equal the current dynasty plus 1, and if its `status` does not equal `PENALIZED`, then: @@ -535,8 +533,8 @@ For each `SpecialObject` `obj` in `active_state.pending_specials`: #### Finally... -* Set `crystallized_state.last_state_recalculation += CYCLE_LENGTH` -* Remove all attestation records older than slot `crystallized_state.last_state_recalculation` +* Set `crystallized_state.last_state_recalculation_slot += CYCLE_LENGTH` +* Remove all attestation records older than slot `crystallized_state.last_state_recalculation_slot` * Empty the `active_state.pending_specials` list * Set `shard_and_committee_for_slots[:CYCLE_LENGTH] = shard_and_committee_for_slots[CYCLE_LENGTH:]` @@ -544,16 +542,16 @@ For each `SpecialObject` `obj` in `active_state.pending_specials`: A dynasty transition can happen after a state recalculation if all of the following criteria are satisfied: -* `block.slot - crystallized_state.dynasty_start >= MIN_DYNASTY_LENGTH` -* `last_finalized_slot > dynasty_start` -* For every shard `S` in `shard_and_committee_for_slots`, `crosslink_records[S].slot > dynasty_start` +* `block.slot - crystallized_state.dynasty_start_slot >= MIN_DYNASTY_LENGTH` +* `last_finalized_slot > dynasty_start_slot` +* For every shard `S` in `shard_and_committee_for_slots`, `crosslinks[S].slot > dynasty_start_slot` Then, run the following algorithm to update the validator set: ```python def change_validators(validators): # The active validator set - active_validators = get_active_validator_indices(validators, current_dynasty) + active_validators = get_active_validator_indices(validators, dynasty) # The total size of active deposits total_deposits = sum([v.balance for i, v in enumerate(validators) if i in active_validators]) # The maximum total wei that can deposit+withdraw @@ -598,9 +596,9 @@ def change_validators(validators): Finally: -* Set `last_dynasty_start = crystallized_state.last_state_recalculation` -* Set `crystallized_state.current_dynasty += 1` -* Let `next_start_shard = (shard_and_committee_for_slots[-1][-1].shard_id + 1) % SHARD_COUNT` +* Set `last_dynasty_start_slot = crystallized_state.last_state_recalculation_slot` +* Set `crystallized_state.dynasty += 1` +* Let `next_start_shard = (shard_and_committee_for_slots[-1][-1].shard + 1) % SHARD_COUNT` * Set `shard_and_committee_for_slots[CYCLE_LENGTH:] = get_new_shuffling(block.ancestor_hashes[0], validators, next_start_shard)` ### TODO @@ -610,7 +608,7 @@ Note: This spec is ~60% complete. **Missing** * [ ] Specify how `crystallized_state_root` and `active_state_root` are constructed, including Merklelisation logic for light clients -* [ ] Specify the rules around acceptable values for `pow_chain_ref` +* [ ] Specify the rules around acceptable values for `pow_chain_reference` * [ ] Specify the shard chain blocks, blobs, proposers, etc. * [ ] Specify the rules for forced deregistrations * [ ] Specify the various assumptions (global clock, networking latency, validator honesty, validator liveness, etc.) @@ -638,7 +636,7 @@ Note: This spec is ~60% complete. * [ ] Add a double-batched Merkle accumulator for historical beacon chain blocks * [ ] Allow for deposits larger than 32 ETH, as well as deposit top-ups * [ ] Add penalties for a deposit below 32 ETH (or some other threshold) -* [ ] Add a `SpecialObject` to (re)register +* [ ] Add a `SpecialRecord` to (re)register * [ ] Rework the document for readability * [ ] Clearly document the various edge cases, e.g. with committee sizing From 7749c28bd92231c3da8237c9f811b2bf44822e15 Mon Sep 17 00:00:00 2001 From: Justin Date: Thu, 4 Oct 2018 11:22:50 +0100 Subject: [PATCH 33/36] Update beacon-chain.md --- specs/beacon-chain.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index 16233c8dd..f27a8e6a8 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -73,7 +73,7 @@ The registration contract emits a log with the various arguments for consumption ## Data structures ### Beacon chain blocks -A `BeaconChainBlock` has the following fields: +A `BeaconBlock` has the following fields: ```python { @@ -122,7 +122,7 @@ An `AttestationRecord` has the following fields: A `SpecialRecord` has the following fields: ```python -fields = { +{ # Type 'type': 'int8', # Data From b60cbd9c339eead7552cc9c0f4b92918268ecad3 Mon Sep 17 00:00:00 2001 From: Justin Date: Thu, 4 Oct 2018 14:26:13 +0100 Subject: [PATCH 34/36] Update beacon-chain.md --- specs/beacon-chain.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index f27a8e6a8..fb34848dd 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -199,17 +199,6 @@ A `ValidatorRecord` has the following fields: } ``` -A `ShardAndCommittee` object has the following fields: - -```python -{ - # Shard number - 'shard': 'int16', - # Validator indices - 'committee': ['int24'] -} -``` - A `CrosslinkRecord` has the following fields: ```python @@ -223,6 +212,17 @@ A `CrosslinkRecord` has the following fields: } ``` +A `ShardAndCommittee` object has the following fields: + +```python +{ + # Shard number + 'shard': 'int16', + # Validator indices + 'committee': ['int24'] +} +``` + ## Beacon chain processing The beacon chain is the "main chain" of the PoS system. The beacon chain's main responsibilities are: From 5f40856606a748b699a8d2f496f9c62c9dca358d Mon Sep 17 00:00:00 2001 From: Justin Date: Thu, 4 Oct 2018 14:39:56 +0100 Subject: [PATCH 35/36] Update beacon-chain.md --- specs/beacon-chain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index fb34848dd..37314e5f0 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -208,7 +208,7 @@ A `CrosslinkRecord` has the following fields: # Slot number 'slot': 'int64', # Beacon chain block hash - 'hash': 'hash32' + 'shard_block_hash': 'hash32' } ``` From b4f2317692a6c8c13e1ec71d9323159c14ce0289 Mon Sep 17 00:00:00 2001 From: Justin Date: Thu, 4 Oct 2018 21:59:36 +0100 Subject: [PATCH 36/36] Update beacon-chain.md --- specs/beacon-chain.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/beacon-chain.md b/specs/beacon-chain.md index 37314e5f0..6ceb74bb8 100644 --- a/specs/beacon-chain.md +++ b/specs/beacon-chain.md @@ -123,8 +123,8 @@ A `SpecialRecord` has the following fields: ```python { - # Type - 'type': 'int8', + # Kind + 'kind': 'int8', # Data 'data': ['bytes'] } @@ -523,8 +523,8 @@ Let `committees` be the set of committees processed and `time_since_last_confirm For each `SpecialRecord` `obj` in `active_state.pending_specials`: -* **[covers logouts]**: If `obj.type == 0`, interpret `data[0]` as a validator index as an `int32` and `data[1]` as a signature. If `BLSVerify(pubkey=validators[data[0]].pubkey, msg=hash("bye bye"), sig=data[1])`, and `validators[i].status == LOGGED_IN`, set `validators[i].status = PENDING_EXIT` and `validators[i].exit_slot = current_slot` -* **[covers `NO_DBL_VOTE`, `NO_SURROUND`, `NO_DBL_PROPOSE` slashing conditions]:** If `obj.type == 1`, interpret `data[0]` as a list of concatenated `int32` values where each value represents an index into `validators`, `data[1]` as the data being signed and `data[2]` as an aggregate signature. Interpret `data[3:6]` similarly. Verify that both signatures are valid, that the two signatures are signing distinct data, and that they are either signing the same slot number, or that one surrounds the other (ie. `source1 < source2 < target2 < target1`). Let `inds` be the list of indices in both signatures; verify that its length is at least 1. For each validator index `v` in `inds`, set their end dynasty to equal the current dynasty plus 1, and if its `status` does not equal `PENALIZED`, then: +* **[covers logouts]**: If `obj.kind == 0`, interpret `data[0]` as a validator index as an `int32` and `data[1]` as a signature. If `BLSVerify(pubkey=validators[data[0]].pubkey, msg=hash("bye bye"), sig=data[1])`, and `validators[i].status == LOGGED_IN`, set `validators[i].status = PENDING_EXIT` and `validators[i].exit_slot = current_slot` +* **[covers `NO_DBL_VOTE`, `NO_SURROUND`, `NO_DBL_PROPOSE` slashing conditions]:** If `obj.kind == 1`, interpret `data[0]` as a list of concatenated `int32` values where each value represents an index into `validators`, `data[1]` as the data being signed and `data[2]` as an aggregate signature. Interpret `data[3:6]` similarly. Verify that both signatures are valid, that the two signatures are signing distinct data, and that they are either signing the same slot number, or that one surrounds the other (ie. `source1 < source2 < target2 < target1`). Let `inds` be the list of indices in both signatures; verify that its length is at least 1. For each validator index `v` in `inds`, set their end dynasty to equal the current dynasty plus 1, and if its `status` does not equal `PENALIZED`, then: 1. Set its `exit_slot` to equal the current `slot` 2. Set its `status` to `PENALIZED`