| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Ouroboros.Consensus.HeaderValidation
Description
Header validation
Synopsis
- validateHeader :: (BlockSupportsProtocol blk, ValidateEnvelope blk) => TopLevelConfig blk -> Ticked (LedgerView (BlockProtocol blk)) -> Header blk -> Ticked (HeaderState blk) -> Except (HeaderError blk) (HeaderState blk)
- revalidateHeader :: forall blk. (BlockSupportsProtocol blk, ValidateEnvelope blk, HasCallStack) => TopLevelConfig blk -> Ticked (LedgerView (BlockProtocol blk)) -> Header blk -> Ticked (HeaderState blk) -> HeaderState blk
- data AnnTip blk = AnnTip {
- annTipSlotNo :: !SlotNo
- annTipBlockNo :: !BlockNo
- annTipInfo :: !(TipInfo blk)
- annTipHash :: forall blk. HasAnnTip blk => AnnTip blk -> HeaderHash blk
- annTipPoint :: forall blk. HasAnnTip blk => AnnTip blk -> Point blk
- annTipRealPoint :: forall blk. HasAnnTip blk => AnnTip blk -> RealPoint blk
- castAnnTip :: TipInfo blk ~ TipInfo blk' => AnnTip blk -> AnnTip blk'
- mapAnnTip :: (TipInfo blk -> TipInfo blk') -> AnnTip blk -> AnnTip blk'
- class (StandardHash blk, Show (TipInfo blk), Eq (TipInfo blk), NoThunks (TipInfo blk)) => HasAnnTip blk where
- type TipInfo blk :: Type
- getTipInfo :: Header blk -> TipInfo blk
- tipInfoHash :: proxy blk -> TipInfo blk -> HeaderHash blk
- getAnnTip :: (HasHeader (Header blk), HasAnnTip blk) => Header blk -> AnnTip blk
- data HeaderState blk = HeaderState {
- headerStateTip :: !(WithOrigin (AnnTip blk))
- headerStateChainDep :: !(ChainDepState (BlockProtocol blk))
- castHeaderState :: (Coercible (ChainDepState (BlockProtocol blk)) (ChainDepState (BlockProtocol blk')), TipInfo blk ~ TipInfo blk') => HeaderState blk -> HeaderState blk'
- tickHeaderState :: ConsensusProtocol (BlockProtocol blk) => ConsensusConfig (BlockProtocol blk) -> Ticked (LedgerView (BlockProtocol blk)) -> SlotNo -> HeaderState blk -> Ticked (HeaderState blk)
- genesisHeaderState :: ChainDepState (BlockProtocol blk) -> HeaderState blk
- headerStatePoint :: HasAnnTip blk => HeaderState blk -> Point blk
- class (HasHeader (Header blk), HasAnnTip blk) => BasicEnvelopeValidation blk where
- expectedFirstBlockNo :: proxy blk -> BlockNo
- expectedNextBlockNo :: proxy blk -> TipInfo blk -> TipInfo blk -> BlockNo -> BlockNo
- minimumPossibleSlotNo :: Proxy blk -> SlotNo
- minimumNextSlotNo :: proxy blk -> TipInfo blk -> TipInfo blk -> SlotNo -> SlotNo
- data HeaderEnvelopeError blk
- = UnexpectedBlockNo !BlockNo !BlockNo
- | UnexpectedSlotNo !SlotNo !SlotNo
- | UnexpectedPrevHash !(WithOrigin (HeaderHash blk)) !(ChainHash blk)
- | OtherHeaderEnvelopeError !(OtherHeaderEnvelopeError blk)
- castHeaderEnvelopeError :: (HeaderHash blk ~ HeaderHash blk', OtherHeaderEnvelopeError blk ~ OtherHeaderEnvelopeError blk') => HeaderEnvelopeError blk -> HeaderEnvelopeError blk'
- class (BasicEnvelopeValidation blk, GetPrevHash blk, Eq (OtherHeaderEnvelopeError blk), Show (OtherHeaderEnvelopeError blk), NoThunks (OtherHeaderEnvelopeError blk)) => ValidateEnvelope blk where
- type OtherHeaderEnvelopeError blk :: Type
- additionalEnvelopeChecks :: TopLevelConfig blk -> Ticked (LedgerView (BlockProtocol blk)) -> Header blk -> Except (OtherHeaderEnvelopeError blk) ()
- data HeaderError blk
- = HeaderProtocolError !(ValidationErr (BlockProtocol blk))
- | HeaderEnvelopeError !(HeaderEnvelopeError blk)
- castHeaderError :: (ValidationErr (BlockProtocol blk) ~ ValidationErr (BlockProtocol blk'), HeaderHash blk ~ HeaderHash blk', OtherHeaderEnvelopeError blk ~ OtherHeaderEnvelopeError blk') => HeaderError blk -> HeaderError blk'
- data TipInfoIsEBB blk = TipInfoIsEBB !(HeaderHash blk) !IsEBB
- defaultEncodeAnnTip :: TipInfo blk ~ HeaderHash blk => (HeaderHash blk -> Encoding) -> AnnTip blk -> Encoding
- defaultDecodeAnnTip :: TipInfo blk ~ HeaderHash blk => (forall s. Decoder s (HeaderHash blk)) -> forall s. Decoder s (AnnTip blk)
- encodeAnnTipIsEBB :: TipInfo blk ~ TipInfoIsEBB blk => (HeaderHash blk -> Encoding) -> AnnTip blk -> Encoding
- decodeAnnTipIsEBB :: TipInfo blk ~ TipInfoIsEBB blk => (forall s. Decoder s (HeaderHash blk)) -> forall s. Decoder s (AnnTip blk)
- encodeHeaderState :: (ChainDepState (BlockProtocol blk) -> Encoding) -> (AnnTip blk -> Encoding) -> HeaderState blk -> Encoding
- decodeHeaderState :: (forall s. Decoder s (ChainDepState (BlockProtocol blk))) -> (forall s. Decoder s (AnnTip blk)) -> forall s. Decoder s (HeaderState blk)
- data family Ticked st :: Type
Documentation
validateHeader :: (BlockSupportsProtocol blk, ValidateEnvelope blk) => TopLevelConfig blk -> Ticked (LedgerView (BlockProtocol blk)) -> Header blk -> Ticked (HeaderState blk) -> Except (HeaderError blk) (HeaderState blk) Source #
Header validation
Header validation (as opposed to block validation) is done by the chain sync client: as we download headers from other network nodes, we validate those headers before deciding whether or not to download the corresponding blocks.
Before we adopt any blocks we have downloaded, however, we will do a full block validation. As such, the header validation check can omit some checks (provided that we do those checks when we do the full validation); at worst, this would mean we might download some blocks that we will reject as being invalid where we could have detected that sooner.
For this reason, the header validation currently only checks two things:
o It verifies the consensus part of the header.
For example, for Praos this means checking the VRF proofs.
o It verifies the HasHeader part of the header.
By default, we verify that
x Block numbers are consecutive
x The block number of the first block is firstBlockNo
x Slot numbers are strictly increasing
x The slot number of the first block is at least minimumPossibleSlotNo
x Hashes line up
If a particular ledger wants to verify additional fields in the header,
it will get the chance to do so in applyLedgerBlock, which is passed the
entire block (not just the block body).
revalidateHeader :: forall blk. (BlockSupportsProtocol blk, ValidateEnvelope blk, HasCallStack) => TopLevelConfig blk -> Ticked (LedgerView (BlockProtocol blk)) -> Header blk -> Ticked (HeaderState blk) -> HeaderState blk Source #
Header revalidation
Same as validateHeader but used when the header has been validated before
w.r.t. the same exact HeaderState.
Expensive validation checks are skipped (reupdateChainDepState vs.
updateChainDepState).
Annotated tips
Annotated information about the tip of the chain
The annotation is the additional information we need to validate the header envelope. Under normal circumstances no additional information is required, but for instance for Byron we need to know if the previous header was an EBB.
Constructors
| AnnTip | |
Fields
| |
Instances
annTipHash :: forall blk. HasAnnTip blk => AnnTip blk -> HeaderHash blk Source #
class (StandardHash blk, Show (TipInfo blk), Eq (TipInfo blk), NoThunks (TipInfo blk)) => HasAnnTip blk where Source #
Minimal complete definition
Nothing
Methods
getTipInfo :: Header blk -> TipInfo blk Source #
Extract TipInfo from a block header
default getTipInfo :: (TipInfo blk ~ HeaderHash blk, HasHeader (Header blk)) => Header blk -> TipInfo blk Source #
tipInfoHash :: proxy blk -> TipInfo blk -> HeaderHash blk Source #
The tip info must at least include the hash
default tipInfoHash :: TipInfo blk ~ HeaderHash blk => proxy blk -> TipInfo blk -> HeaderHash blk Source #
Instances
| CanHardFork xs => HasAnnTip (HardForkBlock xs) Source # | |
Defined in Ouroboros.Consensus.HardFork.Combinator.Block Associated Types type TipInfo (HardForkBlock xs) Source # Methods getTipInfo :: Header (HardForkBlock xs) -> TipInfo (HardForkBlock xs) Source # tipInfoHash :: proxy (HardForkBlock xs) -> TipInfo (HardForkBlock xs) -> HeaderHash (HardForkBlock xs) Source # | |
| Bridge m a => HasAnnTip (DualBlock m a) Source # | |
Defined in Ouroboros.Consensus.Ledger.Dual Methods getTipInfo :: Header (DualBlock m a) -> TipInfo (DualBlock m a) Source # tipInfoHash :: proxy (DualBlock m a) -> TipInfo (DualBlock m a) -> HeaderHash (DualBlock m a) Source # | |
Header state
data HeaderState blk Source #
State required to validate the header
See validateHeader for details
Constructors
| HeaderState | |
Fields
| |
Instances
castHeaderState :: (Coercible (ChainDepState (BlockProtocol blk)) (ChainDepState (BlockProtocol blk')), TipInfo blk ~ TipInfo blk') => HeaderState blk -> HeaderState blk' Source #
tickHeaderState :: ConsensusProtocol (BlockProtocol blk) => ConsensusConfig (BlockProtocol blk) -> Ticked (LedgerView (BlockProtocol blk)) -> SlotNo -> HeaderState blk -> Ticked (HeaderState blk) Source #
Tick the ChainDepState inside the HeaderState
genesisHeaderState :: ChainDepState (BlockProtocol blk) -> HeaderState blk Source #
headerStatePoint :: HasAnnTip blk => HeaderState blk -> Point blk Source #
Validate header envelope
class (HasHeader (Header blk), HasAnnTip blk) => BasicEnvelopeValidation blk where Source #
Ledger-independent envelope validation (block, slot, hash)
Minimal complete definition
Nothing
Methods
expectedFirstBlockNo :: proxy blk -> BlockNo Source #
The block number of the first block on the chain
Next block number
minimumPossibleSlotNo :: Proxy blk -> SlotNo Source #
The smallest possible SlotNo
NOTE: This does not affect the translation between SlotNo and EpochNo.
Ouroboros.Consensus.HardFork.History for details.
Minimum next slot number
Instances
data HeaderEnvelopeError blk Source #
Constructors
| UnexpectedBlockNo !BlockNo !BlockNo | Invalid block number We record both the expected and actual block number |
| UnexpectedSlotNo !SlotNo !SlotNo | Invalid slot number We record both the expected (minimum) and actual slot number |
| UnexpectedPrevHash !(WithOrigin (HeaderHash blk)) !(ChainHash blk) | Invalid hash (in the reference to the previous block) We record the current tip as well as the prev hash of the new block. |
| OtherHeaderEnvelopeError !(OtherHeaderEnvelopeError blk) | Block specific envelope error |
Instances
castHeaderEnvelopeError :: (HeaderHash blk ~ HeaderHash blk', OtherHeaderEnvelopeError blk ~ OtherHeaderEnvelopeError blk') => HeaderEnvelopeError blk -> HeaderEnvelopeError blk' Source #
class (BasicEnvelopeValidation blk, GetPrevHash blk, Eq (OtherHeaderEnvelopeError blk), Show (OtherHeaderEnvelopeError blk), NoThunks (OtherHeaderEnvelopeError blk)) => ValidateEnvelope blk where Source #
Validate header envelope
Minimal complete definition
Nothing
Associated Types
type OtherHeaderEnvelopeError blk :: Type Source #
A block-specific error that validateEnvelope can return.
type OtherHeaderEnvelopeError blk = Void
Methods
additionalEnvelopeChecks :: TopLevelConfig blk -> Ticked (LedgerView (BlockProtocol blk)) -> Header blk -> Except (OtherHeaderEnvelopeError blk) () Source #
Do additional envelope checks
Instances
| CanHardFork xs => ValidateEnvelope (HardForkBlock xs) Source # | |
Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger Associated Types type OtherHeaderEnvelopeError (HardForkBlock xs) Source # Methods additionalEnvelopeChecks :: TopLevelConfig (HardForkBlock xs) -> Ticked (LedgerView (BlockProtocol (HardForkBlock xs))) -> Header (HardForkBlock xs) -> Except (OtherHeaderEnvelopeError (HardForkBlock xs)) () Source # | |
| Bridge m a => ValidateEnvelope (DualBlock m a) Source # | |
Defined in Ouroboros.Consensus.Ledger.Dual Associated Types type OtherHeaderEnvelopeError (DualBlock m a) Source # Methods additionalEnvelopeChecks :: TopLevelConfig (DualBlock m a) -> Ticked (LedgerView (BlockProtocol (DualBlock m a))) -> Header (DualBlock m a) -> Except (OtherHeaderEnvelopeError (DualBlock m a)) () Source # | |
Errors
data HeaderError blk Source #
Invalid header
Constructors
| HeaderProtocolError !(ValidationErr (BlockProtocol blk)) | Invalid consensus protocol fields |
| HeaderEnvelopeError !(HeaderEnvelopeError blk) | Failed to validate the envelope |
Instances
castHeaderError :: (ValidationErr (BlockProtocol blk) ~ ValidationErr (BlockProtocol blk'), HeaderHash blk ~ HeaderHash blk', OtherHeaderEnvelopeError blk ~ OtherHeaderEnvelopeError blk') => HeaderError blk -> HeaderError blk' Source #
TipInfoIsEBB
data TipInfoIsEBB blk Source #
Reusable strict data type for TipInfo in case the TipInfo should
contain IsEBB in addition to the HeaderHash.
Constructors
| TipInfoIsEBB !(HeaderHash blk) !IsEBB |
Instances
Serialization
defaultEncodeAnnTip :: TipInfo blk ~ HeaderHash blk => (HeaderHash blk -> Encoding) -> AnnTip blk -> Encoding Source #
defaultDecodeAnnTip :: TipInfo blk ~ HeaderHash blk => (forall s. Decoder s (HeaderHash blk)) -> forall s. Decoder s (AnnTip blk) Source #
encodeAnnTipIsEBB :: TipInfo blk ~ TipInfoIsEBB blk => (HeaderHash blk -> Encoding) -> AnnTip blk -> Encoding Source #
decodeAnnTipIsEBB :: TipInfo blk ~ TipInfoIsEBB blk => (forall s. Decoder s (HeaderHash blk)) -> forall s. Decoder s (AnnTip blk) Source #
encodeHeaderState :: (ChainDepState (BlockProtocol blk) -> Encoding) -> (AnnTip blk -> Encoding) -> HeaderState blk -> Encoding Source #
decodeHeaderState :: (forall s. Decoder s (ChainDepState (BlockProtocol blk))) -> (forall s. Decoder s (AnnTip blk)) -> forall s. Decoder s (HeaderState blk) Source #
Type family instances
data family Ticked st :: Type Source #
" Ticked " piece of state (LedgerState, LedgerView, ChainIndepState)
Ticking refers to the passage of time (the ticking of the clock). When a piece of state is marked as ticked, it means that time-related changes have been applied to the state (or forecast).
Some examples of time related changes:
- Scheduled delegations might have been applied in Byron
- New leader schedule computed for Shelley
- Transition from Byron to Shelley activated in the hard fork combinator.
- Nonces switched out at the start of a new epoch.