Documentation

Signature of the Block

We use a heavyweight delegation scheme, so the signature has two parts:

1. A delegation certificate from a genesis key to the block signer
2. The actual signature over ToSign

Proof of everything contained in the payload

Body consists of payloads of all block components

Constructor for Body

Decode a Block accounting for deprecated epoch boundary blocks

Previous versions of Cardano had an explicit boundary block between epochs. A Block was then represented as 'Either BoundaryBlock MainBlock'. We have now deprecated these explicit boundary blocks, but we still need to decode blocks in the old format. In the case that we find a boundary block, we drop it using dropBoundaryBlock and return a Nothing.

Produces the ByteString that was signed in the block

Indicates what sort of block validation should be performed.

Translate a BlockValidationMode to an appropriate TxValidationMode.

Smart constructor for Block

Smart constructor for Block, without requiring the entire previous Header. Instead, you give its hash and the difficulty of this block. These are derived from the previous header in mkBlock so if you have the previous header, consider using that one.

Encode a block, given a number of slots-per-epoch.

Unlike encCBORABOBBlock, this function does not take the deprecated epoch boundary blocks into account.

Encode a Block accounting for deprecated epoch boundary blocks

Decode a Block accounting for deprecated epoch boundary blocks

For a boundary block, we keep the header, body, and an annotation for the whole thing (commonly the bytes from which it was decoded).

Extract the hash of a boundary block from its annotation.

See note on encCBORABoundaryHeader. This as well does not necessarily invert the decoder decCBORABoundaryBlock.

encCBORABoundaryBlock but with the list length and tag discriminator bytes.

Compute the slot number assigned to a boundary block

For boundary body data, we only keep an annotation. It's the body and extra body data.

The analogue of either

Encoder for ABlockOrBoundaryHdr which is using the annotation. It is right inverse of decCBORAblockOrBoundaryHdr.

TODO: add a round trip test, e.g.

decCBORABlockOrBoundaryHdr . encCBORABlockOrBoundaryHdr = id

which does not type check, but convey the meaning.

The size computation is compatible with encCBORABlockOrBoundaryHdr

Slot number of the header

NOTE: Epoch slot number calculation must match the one in applyBoundary.

Body consists of payloads of all block components

Hash of block header

Data to be signed in Block

Compute the hash of a boundary block header from its annotation. It uses wrapBoundaryBytes, for the hash must be computed on the header bytes tagged with the CBOR list length and tag discriminator, which is the encoding chosen by cardano-sl.

Encode from a boundary header with any annotation. This does not necessarily invert decCBORBoundaryHeader, because that decoder drops information that this encoder replaces, such as the body proof (assumes the body is empty) and the extra header data (sets it to empty map).

Encode a header, without taking in to account deprecated epoch boundary blocks.

Extract the genesis hash and cast it into a header hash.

Hash the serialised representation of a Header

For backwards compatibility we have to take the hash of the header serialised with encCBORHeaderToHash

Make a Header for a given slot, with a given body, parent hash, and difficulty. This takes care of some signing and consensus data.

When starting a new chain in ourorobos-consensus, we often start from a non-zero epoch. This is done in order to ensure synchronisation between nodes - we assume that the chain started at some fixed point in the past (e.g. midnight) which all nodes can agree on despite different node start times. However, the standard deserialisation assumes that the genesis EBB is precisely that in epoch zero.

In order to successfully round-trip a genesis EBB in a non-zero epoch, then, we add a "magic" tag which indicates the presense of the genesis hash. The choice of 255 and the word Genesis is completely arbitrary, and only done to correspond with the matching encoder. This encoding will only ever be seen when processing blocks from a demo.

Smart constructor for Header

Encode a Header accounting for deprecated epoch boundary blocks

This encoding is only used when hashing the header for backwards compatibility, but should not be used when serializing a header within a block

These bytes must be prepended when hashing raw boundary header data

In the Byron release, hashes were taken over a data type that was never directly serialized to the blockchain, so these magic bytes cannot be determined from the raw header data.

These bytes are from `encodeListLen 2 <> encCBOR (1 :: Word8)`

Smart constructor for ABoundaryHeader

Makes sure that the hash is forced.

These bytes must be prepended when hashing raw boundary header data

In the Byron release, hashes were taken over a data type that was never directly serialized to the blockchain, so these magic bytes cannot be determined from the raw header data.

Specialized formatter for HeaderHash

Error which can result from attempting to validate an invalid payload proof.