leioskeyepoch

func Registration ¶

func Registration(
	ctx context.Context,
	db Querier,
	poolID int64,
	at Position,
	executionSlot uint64,
	public []byte,
	proof []byte,
) (epoch *uint64, ageUnknown bool, err error)

Registration derives the leios_key_registration_epoch and leios_key_registration_age_unknown columns for the pool registration certificate being written at `at`, which carries the BLS key public/proof.

It follows cardano-ledger's Dijkstra rules (IntersectMBO/cardano-ledger at 9df9f98c; paths below are under eras/dijkstra/impl/src/Cardano/Ledger/ Dijkstra/ unless they name another package). POOL (Rules/Pool.hs:261, the not-registered branch) builds a new pool's state with mkStakePoolState cEpoch SNothing, so a key registered by a first registration is registered in the epoch of the transaction. POOL's re-registration branch only stages the parameters in psFutureStakePoolParams, replacing any earlier staged ones, and cancels a pending retirement. POOLREAP (Rules/PoolReap.hs:130) adopts them at the next epoch boundary through mkStakePoolState e (current BLS state) (libs/cardano-ledger-core/src/Cardano/Ledger/State/ StakePool.hs:288): a key equal to the active one keeps its registration epoch, and any other key, including one added to a pool that had none, is registered in e, the epoch after the transaction's. BlsKey equality covers the public key and the possession proof. A retirement naming epoch e reaps the pool at the boundary into e, after the staged parameters are adopted. Dijkstra has no NEWEPOCH rule of its own: Era.hs:202 sets EraRule "NEWEPOCH" to Conway's, which on an epoch change runs EPOCH (eras/conway/impl/src/Cardano/Ledger/Conway/Rules/NewEpoch.hs:153-165), and Dijkstra's EPOCH calls POOLREAP (Rules/Epoch.hs:171).

Every keyed row already stores the epoch its key holds once the row is in effect, so the result only needs the key state active in the transaction's epoch, which is a stored row: the current parameters of the pool's latest snapshot import in that epoch when there is one, because an import replaces the pool state where it lands, and otherwise the pool's latest registration before that epoch, unless a retirement reaped the pool before it or the pool was registered afresh within it, when it is the epoch's first registration. A constant number of statements finds these rows. Reading the latest registration before the epoch is an index seek bounded by the closure rows of one block (latestRegistrationExecutedBefore). The lookup of the latest snapshot import in the epoch walks the pool's live rows added since the epoch started, and the retirement lookups read all of the pool's retirements, since no index orders either by position. Nothing is kept outside the rows, so a rollback that deletes rows leaves nothing to undo. A snapshot-imported registration is the state the snapshot carried, with its epoch, or without one when the snapshot had none; a key kept from it keeps the absence. A snapshot's staged parameters (registration index above zero) carry no epoch and are adopted against the snapshot's current parameters at the boundary after the import.

Chain validity bounds what the rows can hold: POOL accepts a retirement only for a registered pool and only naming a later epoch, so the latest retirement after a registration is the one pending, and a pool is not registered afresh twice within one epoch.

The returned epoch is nil with ageUnknown set when the registration keeps a key whose epoch is unknown, and nil with ageUnknown clear when an epoch cannot be placed because the epoch table does not cover a slot involved. Zero is never stored for an epoch that is not known.