diff --git a/specs/test_formats/genesis/initialization.md b/specs/test_formats/genesis/initialization.md index b80729859..585a6f566 100644 --- a/specs/test_formats/genesis/initialization.md +++ b/specs/test_formats/genesis/initialization.md @@ -18,18 +18,20 @@ An integer. The timestamp of the block, in seconds. A yaml file to help read the deposit count: -``` +```yaml deposits_count: int -- Amount of deposits. ``` -## `deposits_.yaml` +### `deposits_.yaml` + +A series of files, with `` in range `[0, deposits_count)`. Deposits need to be processed in order. +Each file is a YAML-encoded `Deposit` object. -A series of files, with `` ranging `[0, deposit_count)`. Each deposit is also available as `deposits_.ssz` ### `state.yaml` -The expected genesis state. +The expected genesis state. A YAML-encoded `BeaconState` object. Also available as `state.ssz`. diff --git a/specs/test_formats/sanity/blocks.md b/specs/test_formats/sanity/blocks.md index 3004a6de7..1a32105a3 100644 --- a/specs/test_formats/sanity/blocks.md +++ b/specs/test_formats/sanity/blocks.md @@ -4,14 +4,38 @@ Sanity tests to cover a series of one or more blocks being processed, aiming to ## Test case format +### `meta.yaml` + ```yaml -description: string -- description of test case, purely for debugging purposes +description: string -- Optional. Description of test case, purely for debugging purposes. bls_setting: int -- see general test-format spec. -pre: BeaconState -- state before running through the transitions triggered by the blocks. -blocks: [BeaconBlock] -- blocks to process, in given order, following the main transition function (i.e. process slot and epoch transitions in between blocks as normal) -post: BeaconState -- state after applying all the transitions triggered by the blocks. +blocks_count: int -- the number of blocks processed in this test. ``` + +### `pre.yaml` + +A YAML-encoded `BeaconState`, the state before running the block transitions. + +A `pre.ssz` is also available as substitute. + + +### `blocks_.yaml` + +A series of files, with `` in range `[0, blocks_count)`. Blocks need to be processed in order, + following the main transition function (i.e. process slot and epoch transitions in between blocks as normal) + +Each file is a YAML-encoded `BeaconBlock`. + +Each block is also available as `blocks_.ssz` + +### `post.yaml` + +A YAML-encoded `BeaconState`, the state after applying the block transitions. + +A `post.ssz` is also available as substitute. + + ## Condition The resulting state should match the expected `post` state, or if the `post` state is left blank, diff --git a/specs/test_formats/sanity/slots.md b/specs/test_formats/sanity/slots.md index 04fecd186..c41a56c49 100644 --- a/specs/test_formats/sanity/slots.md +++ b/specs/test_formats/sanity/slots.md @@ -4,14 +4,34 @@ Sanity tests to cover a series of one or more empty-slot transitions being proce ## Test case format +### `meta.yaml` + ```yaml -description: string -- description of test case, purely for debugging purposes +description: string -- Optional. Description of test case, purely for debugging purposes. bls_setting: int -- see general test-format spec. -pre: BeaconState -- state before running through the transitions. -slots: N -- amount of slots to process, N being a positive number. -post: BeaconState -- state after applying all the transitions. ``` + +### `pre.yaml` + +A YAML-encoded `BeaconState`, the state before running the transitions. + +A `pre.ssz` is also available as substitute. + + +### `slots.yaml` + +An integer. The amount of slots to process (i.e. the difference in slots between pre and post), always a positive number. + +### `post.yaml` + +A YAML-encoded `BeaconState`, the state after applying the transitions. + +A `post.ssz` is also available as substitute. + + +### Processing + The transition with pure time, no blocks, is known as `process_slots(state, slot)` in the spec. This runs state-caching (pure slot transition) and epoch processing (every E slots). diff --git a/specs/test_formats/shuffling/README.md b/specs/test_formats/shuffling/README.md index 25074742d..24ec8c568 100644 --- a/specs/test_formats/shuffling/README.md +++ b/specs/test_formats/shuffling/README.md @@ -7,26 +7,32 @@ Clients may take different approaches to shuffling, for optimizing, and supporting advanced lookup behavior back in older history. For implementers, possible test runners implementing testing can include: -1) Just test permute-index, run it for each index `i` in `range(count)`, and check against expected `output[i]` (default spec implementation). +1) Just test permute-index, run it for each index `i` in `range(count)`, and check against expected `mapping[i]` (default spec implementation). 2) Test un-permute-index (the reverse lookup; implemented by running the shuffling rounds in reverse, from `round_count-1` to `0`). 3) Test the optimized complete shuffle, where all indices are shuffled at once; test output in one go. 4) Test complete shuffle in reverse (reverse rounds, same as #2). ## Test case format +### `mapping.yaml` + ```yaml seed: bytes32 count: int -shuffled: List[int] +mapping: List[int] ``` - The `bytes32` is encoded a string, hexadecimal encoding, prefixed with `0x`. - Integers are validator indices. These are `uint64`, but realistically they are not as big. The `count` specifies the validator registry size. One should compute the shuffling for indices `0, 1, 2, 3, ..., count (exclusive)`. -Seed is the raw shuffling seed, passed to permute-index (or optimized shuffling approach). + +The `seed` is the raw shuffling seed, passed to permute-index (or optimized shuffling approach). + +The `mapping` is a look up array, constructed as `[spec.compute_shuffled_index(i, count, seed) for i in range(count)]` +I.e. `mapping[i]` is the shuffled location of `i`. ## Condition -The resulting list should match the expected output `shuffled` after shuffling the implied input, using the given `seed`. - +The resulting list should match the expected output after shuffling the implied input, using the given `seed`. +The output is checked using the `mapping`, based on the shuffling test type (e.g. can be backwards shuffling).