more documentation updates

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_<index>.yaml`
+### `deposits_<index>.yaml`
+
+A series of files, with `<index>` 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 `<index>` ranging `[0, deposit_count)`.
 Each deposit is also available as `deposits_<index>.ssz`
 
 ###  `state.yaml`
 
-The expected genesis state.
+The expected genesis state. A YAML-encoded `BeaconState` object.
 
 Also available as `state.ssz`.
 

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_<index>.yaml`
+
+A series of files, with `<index>` 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_<index>.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,

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).
 

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).