Detailed information about the time bounds of an era

Compute upper bound given just the epoch number and era parameters

Exclusive upper bound on the era

Information about a specific era

The eraEnd of the final era in the summary will be determined by the safe zone considerations discussed above.

Let the start of the summary be (t, s, e) (time, slot epoch), and the end of the summary be (t', s', e'). We have one invariant relating epochs and slots:

INV-1a  e' == e + ((s' - s) / epochSize)
INV-1b: s' == s + ((e' - e) * epochSize)

And another invariant relating time and slots:

INV-2a: s' == s + ((t' - t) / slotLen)
INV-2b: t' == t + ((s' - s) * slotLen)

Note that these aren't really two sets of independent invariants. INV-1a follows from INV-1b:

      s'                   == s + ((e' - e) * epochSize)
      s' - s               ==     ((e' - e) * epochSize)
     (s' - s) / epochSize  ==       e' - e
e + ((s' - s) / epochSize) ==       e'

Similarly, INV-2a follows from INV-2b:

      t'                 == t + ((s' - s) * slotLen)
      t' - t             ==     ((s' - s) * slotLen)
     (t' - t) / slotLen  ==       s' - s
s + ((t' - t) / slotLen) ==       s'

Ouroboros Peras adds an invariant relating epoch size and Peras voting round lengths: > epochSize % perasRoundLength == 0 i.e. the round length should divide the epoch size

Version of mkUpperBound when the upper bound may not be known

If passed Nothing, assumes EraUnbounded. This is NOT suitable for eras where the transition is simply unknown.

Convert EraEnd to 'Maybe Bound'

Summary of the confirmed part of the ledger

The summary zips Shape with Forks, and provides detailed information about the start and end of each era.

We have at most one summary for each era, and at least one

Summary for a ledger that never forks

Construct Summary with an exact number of EraSummary

Primarily useful for tests.

The shape of the chain (old to new)

The shape determines how many hard forks we expect as well as the parameters for each era. The type argument is a type-level list containing one entry per era, emphasizing that this information is statically known.

The entry indices themselves are not used here, but the idea is that they look something like '[ByronBlock, ShelleyBlock, GoguenBlock] and do affect the hard fork combinator. So far this is a list of block types, since most of consensus is indexed by block types.

The exact point of each confirmed hard fork transition (old to new)

Unlike the Shape of the chain, which is statically known, the Transitions are derived from the state of the ledger (hard fork transition points only become known after a voting procedure).

Any transition listed here must be "certain". How certainty is established is ledger dependent, but it should imply that this is no longer subject to rollback.

Check Shape invariants

The only part of the Shape that must make sense is the safeBeforeEpoch values (they must be strictly increasing).

NOTE: We assume eras cannot be empty. This will be satisfied by any ledger we are interested in since transitions must be voted on (safe zones will be non-empty).

Check Summary invariants

There is only one era

Construct hard fork Summary

NOTE (on epoch to slot translation). In order to translate SlotNo to EpochNo, we simply "line up" all slots. For example, suppose we have an initial EpochSize of 10, and then an EpochSize of 20 from EpochNo 3 onwards. We end up with something like

Epoch | 0      | 1        | 2        | 3        | 4        | ..
Slot  | 0 .. 9 | 10 .. 19 | 20 .. 29 | 30 .. 49 | 50 .. 69 | ..

We do this translation independent from the minimumPossibleSlotNo for a particular ledger. This means that for ledgers where the minimumPossibleSlotNo is not zero (e.g., some ledgers might set it to 1), the maximum number of blocks (aka filled slots) in an epoch is just 1 (or more) less than the other epochs.

No known transitions yet

Outer bounds of the summary

Outer bounds of the summary for PerasRoundNo specifically.

Returns NoPerasEnabled if no era in the summary has Peras enabled.

Returns 'PerasEnabled (lo, mbHi)' if at least one era in the summary has Peras enabled, where: - lo is the lower bound of the first era with Peras enabled - mbHi is the upper bound of the last era with Peras enabled, or Nothing if the last era with PerasEnabled is unbounded.

Analogue of init for Summary (i.e., split off the final era)

This is primarily useful for tests.