"""

    Obtain the epoch number to which the block identified by `block_number`

    belongs. The first epoch is numbered zero.

    An Ethash epoch is a fixed number of blocks ([`EPOCH_SIZE`]) long, during

    which the dataset remains constant. At the end of each epoch, the dataset

    is generated anew. See [`generate_dataset`].

    [`EPOCH_SIZE`]: ref:ethereum.ethash.EPOCH_SIZE

    [`generate_dataset`]: ref:ethereum.ethash.generate_dataset

    """

    return block_number // EPOCH_SIZE

    """

    Obtain the cache size (in bytes) of the epoch to which `block_number`

    belongs.

    See [`INITIAL_CACHE_SIZE`] and [`CACHE_EPOCH_GROWTH_SIZE`] for the initial

    size and linear growth rate, respectively. The cache is generated in

    [`generate_cache`].

    The actual cache size is smaller than simply multiplying

    `CACHE_EPOCH_GROWTH_SIZE` by the epoch number to minimize the risk of

    unintended cyclic behavior. It is defined as the highest prime number below

    what linear growth would calculate.

    [`INITIAL_CACHE_SIZE`]: ref:ethereum.ethash.INITIAL_CACHE_SIZE

    [`CACHE_EPOCH_GROWTH_SIZE`]: ref:ethereum.ethash.CACHE_EPOCH_GROWTH_SIZE

    [`generate_cache`]: ref:ethereum.ethash.generate_cache

    """

    size = INITIAL_CACHE_SIZE + (CACHE_EPOCH_GROWTH_SIZE * epoch(block_number))

    size -= HASH_BYTES

    while not is_prime(size // HASH_BYTES):

        size -= 2 * HASH_BYTES

    return size

    """

    Obtain the dataset size (in bytes) of the epoch to which `block_number`

    belongs.

    See [`INITIAL_DATASET_SIZE`] and [`DATASET_EPOCH_GROWTH_SIZE`][ds] for the

    initial size and linear growth rate, respectively. The complete dataset is

    generated in [`generate_dataset`], while the slices used in verification

    are generated in [`generate_dataset_item`].

    The actual dataset size is smaller than simply multiplying

    `DATASET_EPOCH_GROWTH_SIZE` by the epoch number to minimize the risk of

    unintended cyclic behavior. It is defined as the highest prime number below

    what linear growth would calculate.

    [`INITIAL_DATASET_SIZE`]: ref:ethereum.ethash.INITIAL_DATASET_SIZE

    [ds]: ref:ethereum.ethash.DATASET_EPOCH_GROWTH_SIZE

    [`generate_dataset`]: ref:ethereum.ethash.generate_dataset

    [`generate_dataset_item`]: ref:ethereum.ethash.generate_dataset_item

    """

    size = INITIAL_DATASET_SIZE + (

        DATASET_EPOCH_GROWTH_SIZE * epoch(block_number)

    )

    size -= MIX_BYTES

    while not is_prime(size // MIX_BYTES):

        size -= 2 * MIX_BYTES

    return size

    """

    Obtain the cache generation seed for the block identified by

    `block_number`. See [`generate_cache`].

    [`generate_cache`]: ref:ethereum.ethash.generate_cache

    """

    epoch_number = epoch(block_number)

    seed = b"\x00" * 32

    while epoch_number != 0:

        seed = keccak256(seed)

        epoch_number -= 1

    return Hash32(seed)

    """

    Generate the cache for the block identified by `block_number`. See

    [`generate_dataset`] for how the cache is used.

    The cache is generated in two steps: filling the array with a chain of

    [`keccak512`] hashes, then running two rounds of Sergio Demian Lerner's

    [RandMemoHash] on those bytes.

    [`keccak512`]: ref:ethereum.crypto.hash.keccak512

    [`generate_dataset`]: ref:ethereum.ethash.generate_dataset

    [RandMemoHash]: http://www.hashcash.org/papers/memohash.pdf

    """

    seed = generate_seed(block_number)

    cache_size_bytes = cache_size(block_number)

    cache_size_words = cache_size_bytes // HASH_BYTES

    cache = [keccak512(seed)]

    for index in range(1, cache_size_words):

        cache_item = keccak512(cache[index - 1])

        cache.append(cache_item)

    for _ in range(CACHE_ROUNDS):

        for index in range(cache_size_words):

            # Converting `cache_size_words` to int as `-1 + Uint(5)` is an

            # error.

            first_cache_item = cache[

                (index - 1 + int(cache_size_words)) % cache_size_words

            ]

            second_cache_item = cache[

                U32.from_le_bytes(cache[index][0:4]) % cache_size_words

            ]

            result = bytes(

                [a ^ b for a, b in zip(first_cache_item, second_cache_item)]

            )

            cache[index] = keccak512(result)

    return tuple(

        le_bytes_to_uint32_sequence(cache_item) for cache_item in cache

    )

    """

    A non-associative substitute for XOR, inspired by the [FNV] hash by Fowler,

    Noll, and Vo. See [`fnv_hash`], [`generate_dataset_item`], and

    [`hashimoto`].

    Note that here we multiply the prime with the full 32-bit input, in

    contrast with the [FNV-1] spec which multiplies the prime with one byte

    (octet) in turn.

    [`hashimoto`]: ref:ethereum.ethash.hashimoto

    [`generate_dataset_item`]: ref:ethereum.ethash.generate_dataset_item

    [`fnv_hash`]: ref:ethereum.ethash.fnv_hash

    [FNV]: https://w.wiki/XKZ

    [FNV-1]: http://www.isthe.com/chongo/tech/comp/fnv/#FNV-1

    """

    # This is a faster way of doing `number % (2 ** 32)`.

    result = ((Uint(a) * 0x01000193) ^ Uint(b)) & U32.MAX_VALUE

    return U32(result)

    """

    Combines `data` into `mix_integers` using [`fnv`]. See [`hashimoto`] and

    [`generate_dataset_item`].

    [`hashimoto`]: ref:ethereum.ethash.hashimoto

    [`generate_dataset_item`]: ref:ethereum.ethash.generate_dataset_item

    [`fnv`]: ref:ethereum.ethash.fnv

    """

    return tuple(

        fnv(mix_integers[i], data[i]) for i in range(len(mix_integers))

    )

    """

    Generate a particular dataset item 0-indexed by `index` by hashing

    pseudorandomly-selected entries from `cache` together. See [`fnv`] and

    [`fnv_hash`] for the digest function, [`generate_cache`] for generating

    `cache`, and [`generate_dataset`] for the full dataset generation

    algorithm.

    [`fnv`]: ref:ethereum.ethash.fnv

    [`fnv_hash`]: ref:ethereum.ethash.fnv_hash

    [`generate_dataset`]: ref:ethereum.ethash.generate_dataset

    [`generate_cache`]: ref:ethereum.ethash.generate_cache

    """

    mix = keccak512(

        (

            le_uint32_sequence_to_uint(cache[index % len(cache)]) ^ index

        ).to_le_bytes(number_bytes=HASH_BYTES)

    )

    mix_integers = le_bytes_to_uint32_sequence(mix)

    for j in range(DATASET_PARENTS):

        mix_word: U32 = mix_integers[j % 16]

        cache_index = fnv(index ^ j, mix_word) % len(cache)

        parent = cache[cache_index]

        mix_integers = fnv_hash(mix_integers, parent)

    mix = Hash64(le_uint32_sequence_to_bytes(mix_integers))

    return keccak512(mix)

    """

    Generate the full dataset for the block identified by `block_number`.

    This function is present only for demonstration purposes. It is not used

    while validating blocks.

    """

    dataset_size_bytes: Uint = dataset_size(block_number)

    cache: Tuple[Tuple[U32, ...], ...] = generate_cache(block_number)

    # TODO: Parallelize this later on if it adds value

    return tuple(

        generate_dataset_item(cache, Uint(index))

        for index in range(dataset_size_bytes // HASH_BYTES)

    )

    """

    Obtain the mix digest and the final value for a header, by aggregating

    data from the full dataset.

    #### Parameters

    - `header_hash` is a valid [RLP hash] of a block header.

    - `nonce` is the propagated nonce for the given block.

    - `dataset_size` is the size of the dataset. See [`dataset_size`].

    - `fetch_dataset_item` is a function that retrieves a specific dataset item

      based on its index.

    #### Returns

    - The mix digest generated from the header hash and propagated nonce.

    - The final result obtained which will be checked for leading zeros (in

      byte representation) in correspondence with the block difficulty.

    [RLP hash]: ref:ethereum.rlp.rlp_hash

    [`dataset_size`]: ref:ethereum.ethash.dataset_size

    """

    nonce_le = bytes(reversed(nonce))

    seed_hash = keccak512(header_hash + nonce_le)

    seed_head = U32.from_le_bytes(seed_hash[:4])

    rows = dataset_size // 128

    mix = le_bytes_to_uint32_sequence(seed_hash) * (MIX_BYTES // HASH_BYTES)

    for i in range(HASHIMOTO_ACCESSES):

        new_data: Tuple[U32, ...] = ()

        parent = fnv(i ^ seed_head, mix[i % len(mix)]) % rows

        for j in range(MIX_BYTES // HASH_BYTES):

            # Typecasting `parent` from U32 to Uint as 2*parent + j may

            # overflow U32.

            new_data += fetch_dataset_item(2 * Uint(parent) + j)

        mix = fnv_hash(mix, new_data)

    compressed_mix = []

    for i in range(0, len(mix), 4):

        compressed_mix.append(

            fnv(fnv(fnv(mix[i], mix[i + 1]), mix[i + 2]), mix[i + 3])

        )

    mix_digest = le_uint32_sequence_to_bytes(compressed_mix)

    result = keccak256(seed_hash + mix_digest)

    return mix_digest, result

    """

    Run the [`hashimoto`] algorithm by generating dataset item using the cache

    instead of loading the full dataset into main memory.

    #### Parameters

    - `header_hash` is a valid [RLP hash] of a block header.

    - `nonce` is the propagated nonce for the given block.

    - `cache` is the cache generated by [`generate_cache`].

    - `dataset_size` is the size of the dataset. See [`dataset_size`].

    #### Returns

    - The mix digest generated from the header hash and propagated nonce.

    - The final result obtained which will be checked for leading zeros (in

      byte representation) in correspondence with the block difficulty.

    [RLP hash]: ref:ethereum.rlp.rlp_hash

    [`dataset_size`]: ref:ethereum.ethash.dataset_size

    [`generate_cache`]: ref:ethereum.ethash.generate_cache

    [`hashimoto`]: ref:ethereum.ethash.hashimoto

    """

    def fetch_dataset_item(index: Uint) -> Tuple[U32, ...]:

        item: Hash64 = generate_dataset_item(cache, index)

        return le_bytes_to_uint32_sequence(item)

    return hashimoto(header_hash, nonce, dataset_size, fetch_dataset_item)