Safe Haskell	None
Language	Haskell2010

Cardano.Api.LedgerState

Contents

Initialization / Accumulation
Traversing the block chain
Errors
Leadership schedule

Synopsis

data Env = Env {
- envLedgerConfig ∷ HardForkLedgerConfig (CardanoEras StandardCrypto)
- envProtocolConfig ∷ ConsensusConfig (HardForkProtocol (CardanoEras StandardCrypto))
}
envSecurityParam ∷ Env → Word64
newtype LedgerState where
- LedgerState {
  - clsState ∷ LedgerState (HardForkBlock (CardanoEras StandardCrypto))
  }
- pattern LedgerStateByron ∷ LedgerState ByronBlock → LedgerState
- pattern LedgerStateShelley ∷ LedgerState (ShelleyBlock protocol (ShelleyEra StandardCrypto)) → LedgerState
- pattern LedgerStateAllegra ∷ LedgerState (ShelleyBlock protocol (AllegraEra StandardCrypto)) → LedgerState
- pattern LedgerStateMary ∷ LedgerState (ShelleyBlock protocol (MaryEra StandardCrypto)) → LedgerState
- pattern LedgerStateAlonzo ∷ LedgerState (ShelleyBlock protocol (AlonzoEra StandardCrypto)) → LedgerState
initialLedgerState ∷ FilePath → ExceptT InitialLedgerStateError IO (Env, LedgerState)
applyBlock ∷ Env → LedgerState → ValidationMode → Block era → Either LedgerStateError (LedgerState, [LedgerEvent])
data ValidationMode
- = FullValidation
- | QuickValidation
applyBlockWithEvents ∷ Env → LedgerState → Bool → HardForkBlock (CardanoEras StandardCrypto) → Either LedgerStateError LedgerStateEvents
foldBlocks ∷ ∀ a. FilePath → FilePath → ValidationMode → a → (Env → LedgerState → [LedgerEvent] → BlockInMode CardanoMode → a → IO a) → ExceptT FoldBlocksError IO a
chainSyncClientWithLedgerState ∷ ∀ m a. Monad m ⇒ Env → LedgerState → ValidationMode → ChainSyncClient (BlockInMode CardanoMode, Either LedgerStateError (LedgerState, [LedgerEvent])) ChainPoint ChainTip m a → ChainSyncClient (BlockInMode CardanoMode) ChainPoint ChainTip m a
chainSyncClientPipelinedWithLedgerState ∷ ∀ m a. Monad m ⇒ Env → LedgerState → ValidationMode → ChainSyncClientPipelined (BlockInMode CardanoMode, Either LedgerStateError (LedgerState, [LedgerEvent])) ChainPoint ChainTip m a → ChainSyncClientPipelined (BlockInMode CardanoMode) ChainPoint ChainTip m a
data LedgerStateError
- = ApplyBlockHashMismatch Text
- | ApplyBlockError (HardForkLedgerError (CardanoEras StandardCrypto))
- | InvalidRollback SlotNo ChainPoint
data FoldBlocksError
- = FoldBlocksInitialLedgerStateError InitialLedgerStateError
- | FoldBlocksApplyBlockError LedgerStateError
data GenesisConfigError
- = NEError !Text
- | NEByronConfig !FilePath !ConfigurationError
- | NEShelleyConfig !FilePath !Text
- | NEAlonzoConfig !FilePath !Text
- | NECardanoConfig !Text
data InitialLedgerStateError
- = ILSEConfigFile Text
- | ILSEGenesisFile GenesisConfigError
- | ILSELedgerConsensusConfig GenesisConfigError
renderLedgerStateError ∷ LedgerStateError → Text
renderFoldBlocksError ∷ FoldBlocksError → Text
renderGenesisConfigError ∷ GenesisConfigError → Text
renderInitialLedgerStateError ∷ InitialLedgerStateError → Text
data LeadershipError
- = LeaderErrDecodeLedgerStateFailure
- | LeaderErrDecodeProtocolStateFailure (ByteString, DecoderError)
- | LeaderErrDecodeProtocolEpochStateFailure DecoderError
- | LeaderErrGenesisSlot
- | LeaderErrStakePoolHasNoStake PoolId
- | LeaderErrStakeDistribUnstable SlotNo SlotNo SlotNo SlotNo
- | LeaderErrSlotRangeCalculationFailure Text
- | LeaderErrCandidateNonceStillEvolving
constructGlobals ∷ ShelleyGenesis StandardShelley → EpochInfo (Either Text) → ProtocolParameters → Globals
currentEpochEligibleLeadershipSlots ∷ ∀ era ledgerera. ShelleyLedgerEra era ~ ledgerera ⇒ Era ledgerera ⇒ PraosProtocolSupportsNode (ConsensusProtocol era) ⇒ HasField "_d" (PParams ledgerera) UnitInterval ⇒ Share (TxOut (ShelleyLedgerEra era)) ~ Interns (Credential 'Staking (Crypto (ShelleyLedgerEra era))) ⇒ FromCBOR (ChainDepState (ConsensusProtocol era)) ⇒ ShelleyBasedEra era → ShelleyGenesis StandardShelley → EpochInfo (Either Text) → ProtocolParameters → ProtocolState era → PoolId → SigningKey VrfKey → SerialisedCurrentEpochState era → EpochNo → Either LeadershipError (Set SlotNo)
nextEpochEligibleLeadershipSlots ∷ ∀ era. HasField "_d" (PParams (ShelleyLedgerEra era)) UnitInterval ⇒ Era (ShelleyLedgerEra era) ⇒ Share (TxOut (ShelleyLedgerEra era)) ~ Interns (Credential 'Staking (Crypto (ShelleyLedgerEra era))) ⇒ FromCBOR (ChainDepState (ConsensusProtocol era)) ⇒ PraosProtocolSupportsNode (ConsensusProtocol era) ⇒ ShelleyBasedEra era → ShelleyGenesis StandardShelley → SerialisedCurrentEpochState era → ProtocolState era → PoolId → SigningKey VrfKey → ProtocolParameters → EpochInfo (Either Text) → (ChainTip, EpochNo) → Either LeadershipError (Set SlotNo)

Initialization / Accumulation

data Env Source #

Constructors

Env
Fields envLedgerConfig ∷ HardForkLedgerConfig (CardanoEras StandardCrypto) envProtocolConfig ∷ ConsensusConfig (HardForkProtocol (CardanoEras StandardCrypto))

envSecurityParam ∷ Env → Word64 Source #

newtype LedgerState Source #

Constructors

LedgerState
Fields clsState ∷ LedgerState (HardForkBlock (CardanoEras StandardCrypto))

Bundled Patterns

pattern LedgerStateByron ∷ LedgerState ByronBlock → LedgerState
pattern LedgerStateShelley ∷ LedgerState (ShelleyBlock protocol (ShelleyEra StandardCrypto)) → LedgerState
pattern LedgerStateAllegra ∷ LedgerState (ShelleyBlock protocol (AllegraEra StandardCrypto)) → LedgerState
pattern LedgerStateMary ∷ LedgerState (ShelleyBlock protocol (MaryEra StandardCrypto)) → LedgerState
pattern LedgerStateAlonzo ∷ LedgerState (ShelleyBlock protocol (AlonzoEra StandardCrypto)) → LedgerState

initialLedgerState Source #

Arguments

∷ FilePath	Path to the cardano-node config file (e.g. to cardano-node projectconfigurationcardano/mainnet-config.json)
→ ExceptT InitialLedgerStateError IO (Env, LedgerState)	The environment and initial ledger state

Get the environment and initial ledger state.

applyBlock Source #

Arguments

∷ Env	The environment returned by `initialLedgerState`
→ LedgerState	The current ledger state
→ ValidationMode
→ Block era	Some block to apply
→ Either LedgerStateError (LedgerState, [LedgerEvent])	The new ledger state (or an error).

Apply a single block to the current ledger state.

data ValidationMode Source #

How to do validation when applying a block to a ledger state.

Constructors

FullValidation	Do all validation implied by the ledger layer's `applyBlock`.
QuickValidation	Only check that the previous hash from the block matches the head hash of the ledger state.

applyBlockWithEvents Source #

Arguments

∷ Env
→ LedgerState
→ Bool	True to validate
→ HardForkBlock (CardanoEras StandardCrypto)
→ Either LedgerStateError LedgerStateEvents

Traversing the block chain

foldBlocks Source #

Arguments

∷ ∀ a. FilePath	Path to the cardano-node config file (e.g. to cardano-node projectconfigurationcardano/mainnet-config.json)
→ FilePath	Path to local cardano-node socket. This is the path specified by the `--socket-path` command line option when running the node.
→ ValidationMode
→ a	The initial accumulator state.
→ (Env → LedgerState → [LedgerEvent] → BlockInMode CardanoMode → a → IO a)	Accumulator function Takes: Environment (this is a constant over the whole fold). The Ledger state (with block `i` applied) at block `i`. The Ledger events resulting from applying block `i`. Block `i`. The accumulator state at block `i - 1`. And returns: The accumulator state at block `i` Note: This function can safely assume no rollback will occur even though internally this is implemented with a client protocol that may require rollback. This is achieved by only calling the accumulator on states/blocks that are older than the security parameter, k. This has the side effect of truncating the last k blocks before the node's tip.
→ ExceptT FoldBlocksError IO a	The final state

Monadic fold over all blocks and ledger states. Stopping k blocks before the node's tip where k is the security parameter.

chainSyncClientWithLedgerState Source #

Arguments

∷ ∀ m a. Monad m
⇒ Env
→ LedgerState	Initial ledger state
→ ValidationMode
→ ChainSyncClient (BlockInMode CardanoMode, Either LedgerStateError (LedgerState, [LedgerEvent])) ChainPoint ChainTip m a	A client to wrap. The block is annotated with a 'Either LedgerStateError LedgerState'. This is either an error from validating a block or the current `LedgerState` from applying the current block. If we trust the node, then we generally expect blocks to validate. Also note that after a block fails to validate we may still roll back to a validated block, in which case the valid `LedgerState` will be passed here again.
→ ChainSyncClient (BlockInMode CardanoMode) ChainPoint ChainTip m a	A client that acts just like the wrapped client but doesn't require the `LedgerState` annotation on the block type.

Wrap a ChainSyncClient with logic that tracks the ledger state.

chainSyncClientPipelinedWithLedgerState ∷ ∀ m a. Monad m ⇒ Env → LedgerState → ValidationMode → ChainSyncClientPipelined (BlockInMode CardanoMode, Either LedgerStateError (LedgerState, [LedgerEvent])) ChainPoint ChainTip m a → ChainSyncClientPipelined (BlockInMode CardanoMode) ChainPoint ChainTip m a Source #

See chainSyncClientWithLedgerState.

Errors

data LedgerStateError Source #

Constructors

ApplyBlockHashMismatch Text	When using QuickValidation, the block hash did not match the expected block hash after applying a new block to the current ledger state.
ApplyBlockError (HardForkLedgerError (CardanoEras StandardCrypto))	When using FullValidation, an error occurred when applying a new block to the current ledger state.
InvalidRollback	Encountered a rollback larger than the security parameter.
Fields SlotNo Oldest known slot number that we can roll back to. ChainPoint Rollback was attempted to this point.

Instances

Instances details

Show LedgerStateError Source #
Instance details Defined in Cardano.Api.LedgerState Methods showsPrec ∷ Int → LedgerStateError → ShowS Source # show ∷ LedgerStateError → String Source # showList ∷ [LedgerStateError] → ShowS Source #

data FoldBlocksError Source #

Constructors

FoldBlocksInitialLedgerStateError InitialLedgerStateError
FoldBlocksApplyBlockError LedgerStateError

data GenesisConfigError Source #

Constructors

NEError !Text
NEByronConfig !FilePath !ConfigurationError
NEShelleyConfig !FilePath !Text
NEAlonzoConfig !FilePath !Text
NECardanoConfig !Text

data InitialLedgerStateError Source #

Constructors

ILSEConfigFile Text	Failed to read or parse the network config file.
ILSEGenesisFile GenesisConfigError	Failed to read or parse a genesis file linked from the network config file.
ILSELedgerConsensusConfig GenesisConfigError	Failed to derive the Ledger or Consensus config.

renderLedgerStateError ∷ LedgerStateError → Text Source #

renderFoldBlocksError ∷ FoldBlocksError → Text Source #

renderGenesisConfigError ∷ GenesisConfigError → Text Source #

renderInitialLedgerStateError ∷ InitialLedgerStateError → Text Source #

Leadership schedule

data LeadershipError Source #

Constructors

LeaderErrDecodeLedgerStateFailure
LeaderErrDecodeProtocolStateFailure (ByteString, DecoderError)
LeaderErrDecodeProtocolEpochStateFailure DecoderError
LeaderErrGenesisSlot
LeaderErrStakePoolHasNoStake PoolId
LeaderErrStakeDistribUnstable
Fields SlotNo Current slot SlotNo Stable after SlotNo Stability window size SlotNo Predicted last slot of the epoch
LeaderErrSlotRangeCalculationFailure Text
LeaderErrCandidateNonceStillEvolving

Instances

Instances details

Show LeadershipError Source #
Instance details Defined in Cardano.Api.LedgerState Methods showsPrec ∷ Int → LeadershipError → ShowS Source # show ∷ LeadershipError → String Source # showList ∷ [LeadershipError] → ShowS Source #
Error LeadershipError Source #
Instance details Defined in Cardano.Api.LedgerState Methods displayError ∷ LeadershipError → String Source #

constructGlobals ∷ ShelleyGenesis StandardShelley → EpochInfo (Either Text) → ProtocolParameters → Globals Source #

currentEpochEligibleLeadershipSlots Source #

Arguments

∷ ∀ era ledgerera. ShelleyLedgerEra era ~ ledgerera
⇒ Era ledgerera
⇒ PraosProtocolSupportsNode (ConsensusProtocol era)
⇒ HasField "_d" (PParams ledgerera) UnitInterval
⇒ Share (TxOut (ShelleyLedgerEra era)) ~ Interns (Credential 'Staking (Crypto (ShelleyLedgerEra era)))
⇒ FromCBOR (ChainDepState (ConsensusProtocol era))
⇒ ShelleyBasedEra era
→ ShelleyGenesis StandardShelley
→ EpochInfo (Either Text)
→ ProtocolParameters
→ ProtocolState era
→ PoolId
→ SigningKey VrfKey
→ SerialisedCurrentEpochState era
→ EpochNo	Current EpochInfo
→ Either LeadershipError (Set SlotNo)

Return the slots at which a particular stake pool operator is expected to mint a block.

nextEpochEligibleLeadershipSlots Source #

Arguments

∷ ∀ era. HasField "_d" (PParams (ShelleyLedgerEra era)) UnitInterval
⇒ Era (ShelleyLedgerEra era)
⇒ Share (TxOut (ShelleyLedgerEra era)) ~ Interns (Credential 'Staking (Crypto (ShelleyLedgerEra era)))
⇒ FromCBOR (ChainDepState (ConsensusProtocol era))
⇒ PraosProtocolSupportsNode (ConsensusProtocol era)
⇒ ShelleyBasedEra era
→ ShelleyGenesis StandardShelley
→ SerialisedCurrentEpochState era	We need the mark stake distribution in order to predict the following epoch's leadership schedule
→ ProtocolState era
→ PoolId	Potential slot leading stake pool
→ SigningKey VrfKey	VRF signing key of the stake pool
→ ProtocolParameters
→ EpochInfo (Either Text)
→ (ChainTip, EpochNo)
→ Either LeadershipError (Set SlotNo)