| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Cardano.Rpc.Server.NodeKernelAccess
Description
In-process access to the node kernel. The RPC server reads chain state, genesis and mempool straight from the running node, with no Node-to-Client round trip.
Synopsis
- data NodeKernelAccess
- mkNodeKernelAccess :: MonadIO m => Tracer m TraceRpc -> GenesisHashShelley -> ShelleyGenesisFile 'In -> BlockType blk -> NodeKernel IO addrNTN addrNTC blk -> m (Maybe NodeKernelAccess)
- grabNodeKernelAccess :: MonadRpc e m => m NodeKernelAccess
- nodeKernelSystemStart :: NodeKernelAccess -> SystemStart
- securityParam :: NodeKernelAccess -> SecurityParam
- genesisConfig :: NodeKernelAccess -> GenesisBundle
- data GenesisBundle = GenesisBundle {}
- readHardForkSummary :: MonadIO m => NodeKernelAccess -> m (Summary (CardanoEras StandardCrypto))
- readEraHistory :: MonadIO m => NodeKernelAccess -> m EraHistory
- readCurrentEra :: NodeKernelAccess -> STM AnyCardanoEra
- readChainTipHeader :: MonadIO m => NodeKernelAccess -> m (Maybe (Header (CardanoBlock StandardCrypto)))
- readChainTipPoint :: NodeKernelAccess -> STM ChainPoint
- fetchBlock :: MonadIO m => NodeKernelAccess -> SlotNo -> Hash BlockHeader -> m (Maybe (ByteString, BlockInMode))
- readMempoolTxs :: MonadIO m => NodeKernelAccess -> m [GenTx (CardanoBlock StandardCrypto)]
- readMempoolSnapshot :: NodeKernelAccess -> STM (MempoolSnapshot (CardanoBlock StandardCrypto))
- newtype MempoolWatchSnapshot = MempoolWatchSnapshot {
- mempoolWatchTxsAfter :: TicketNo -> [(TxInMode, TicketNo)]
- watchMempoolSnapshot :: MonadIO m => NodeKernelAccess -> m MempoolWatchSnapshot
- nextMempoolWatchSnapshot :: MonadIO m => NodeKernelAccess -> TicketNo -> m MempoolWatchSnapshot
- data ChainChange a
- data ChainFollower a = ChainFollower {
- nextChange :: forall (m :: Type -> Type). MonadIO m => m (ChainChange a)
- tryNextChange :: forall (m :: Type -> Type). MonadIO m => m (Maybe (ChainChange a))
- findIntersect :: forall (m :: Type -> Type). MonadIO m => [ChainPoint] -> m (Maybe ChainPoint)
- withFollower :: MonadUnliftIO m => NodeKernelAccess -> (ChainFollower (ByteString, BlockInMode) -> m a) -> m a
- withBlockFollower :: MonadUnliftIO m => NodeKernelAccess -> (ChainFollower BlockInMode -> m a) -> m a
- positionFollowerAtCurrentTip :: MonadIO m => NodeKernelAccess -> ChainFollower a -> m ChainPoint
Access handle
data NodeKernelAccess Source #
In-process access to the node kernel. Constructed by cardano-node once consensus initialisation completes.
Instances
| Has (IORef (Maybe NodeKernelAccess)) RpcEnv Source # | |
Defined in Cardano.Rpc.Server.Internal.Monad | |
Arguments
| :: MonadIO m | |
| => Tracer m TraceRpc | Tracer for RPC events |
| -> GenesisHashShelley | Boot-time Shelley genesis hash |
| -> ShelleyGenesisFile 'In | Path to the Shelley genesis file the node was configured with |
| -> BlockType blk | Block type witness |
| -> NodeKernel IO addrNTN addrNTC blk | Consensus node kernel |
| -> m (Maybe NodeKernelAccess) |
Construct NodeKernelAccess from a consensus NodeKernel.
Returns Nothing and traces the block type for non-Cardano block types.
grabNodeKernelAccess :: MonadRpc e m => m NodeKernelAccess Source #
Grab the current NodeKernelAccess from the environment, or throw
gRPC UNAVAILABLE if the node kernel has not yet initialised.
Values fixed at startup
nodeKernelSystemStart :: NodeKernelAccess -> SystemStart Source #
The network's system start time, extracted from genesis config.
Used together with readEraHistory to convert slots to wall-clock time.
securityParam :: NodeKernelAccess -> SecurityParam Source #
The protocol security parameter k: consensus never rolls back more than k blocks.
genesisConfig :: NodeKernelAccess -> GenesisBundle Source #
The network's genesis configuration.
data GenesisBundle Source #
The per-era genesis configuration of the network the node is running on.
Gathered once, when the node kernel hook fires, by walking the per-era ledger
configs of the node kernel's TopLevelConfig. The Byron, Alonzo and
Conway genesis values are the ones the running node holds, shared with it
rather than copied. Nothing is kept from cardano-node's boot-time
ProtocolInfoArgs, whose Shelley genesis reaches gigabytes on
networks with large initial fund sets.
The Shelley genesis is not kept here at all. All the node has is a compacted
copy with the initial funds erased, which is no use to a caller, so
shelleyGenesis holds the file and a cache instead and the genesis is read
from disk when someone asks for it.
The Shelley genesis hash and file path come from cardano-node's own boot-time
genesis parsing, because the ledger config carries neither (see
mkNodeKernelAccess).
Constructors
| GenesisBundle | |
Fields
| |
Era history
readHardForkSummary :: MonadIO m => NodeKernelAccess -> m (Summary (CardanoEras StandardCrypto)) Source #
Read the raw hard-fork era summary from the current ledger state, with the era boundaries directly accessible.
readEraHistory :: MonadIO m => NodeKernelAccess -> m EraHistory Source #
Read current era history from the ledger state: the hard-fork era summary wrapped into the opaque interpreter used for slot/time conversion queries.
readCurrentEra :: NodeKernelAccess -> STM AnyCardanoEra Source #
Read the era of the current ledger state, the era the mempool stores transactions in. An STM read, so a caller can combine it with others.
Chain reads
readChainTipHeader :: MonadIO m => NodeKernelAccess -> m (Maybe (Header (CardanoBlock StandardCrypto))) Source #
Read the current chain tip header from ChainDB, or Nothing at origin.
readChainTipPoint :: NodeKernelAccess -> STM ChainPoint Source #
Read the current chain tip point from ChainDB, or ChainPointAtGenesis
at origin. An STM read, so a caller can wait for the tip to move.
Arguments
| :: MonadIO m | |
| => NodeKernelAccess | Node kernel access handle |
| -> SlotNo | Block slot number |
| -> Hash BlockHeader | Block header hash |
| -> m (Maybe (ByteString, BlockInMode)) | Raw CBOR bytes and the block in era context, or |
Fetch a raw block and its parsed era-contextualised form from ChainDB by slot and header hash.
Mempool
readMempoolTxs :: MonadIO m => NodeKernelAccess -> m [GenTx (CardanoBlock StandardCrypto)] Source #
Read the current mempool contents as a point-in-time snapshot:
transactions added or removed after the read are not reflected.
Ticket numbers and mempool capacity accounting are dropped here, since
readMempoolTxs only serves the one-shot ReadMempool method.
readMempoolSnapshot :: NodeKernelAccess -> STM (MempoolSnapshot (CardanoBlock StandardCrypto)) Source #
Read the current mempool snapshot. An STM read, so a caller can wait for the mempool to change.
newtype MempoolWatchSnapshot Source #
A point-in-time view of the mempool for WatchMempool: a pure projection
of the entries newer than a given ticket, already unwrapped into TxInMode
so tests can build one from TxInMode fixtures without a real mempool.
Constructors
| MempoolWatchSnapshot | |
Fields
| |
watchMempoolSnapshot :: MonadIO m => NodeKernelAccess -> m MempoolWatchSnapshot Source #
Read the current mempool watch snapshot, without blocking.
nextMempoolWatchSnapshot :: MonadIO m => NodeKernelAccess -> TicketNo -> m MempoolWatchSnapshot Source #
Block until the mempool holds an entry newer than the given ticket, then return the snapshot. Tickets are never reused, so this sees every addition; removals and slot changes do not wake the caller.
Chain follower
data ChainChange a Source #
A single instruction produced by a chain follower.
ChainApply carries the per-block payload the follower was opened for
(see withFollower and withBlockFollower).
Consensus rollbacks are point-only: ChainRollBack never carries the
blocks being rolled back, only the point to roll back to.
Constructors
| ChainApply a | |
| ChainRollBack ChainPoint |
data ChainFollower a Source #
A handle to a running chain follower. The payload is selectable because consensus reads each requested block component separately.
Constructors
| ChainFollower | |
Fields
| |
withFollower :: MonadUnliftIO m => NodeKernelAccess -> (ChainFollower (ByteString, BlockInMode) -> m a) -> m a Source #
Run an action with a ChainFollower tracking the selected chain, whose
ChainApply payload is the raw CBOR block bytes together with the same
block parsed into its era context - exactly the pair fetchBlock returns.
The follower and the resource registry backing it are closed on every
exit path, including exceptions. The follower itself runs in IO,
because the ChainDB handle is monomorphic, so the bracket runs there and
the action is unlifted into it.
Creating a follower is cheap: a few in-memory STM operations, nothing proportional to chain length. The costs are steady-state instead. A caught-up follower receives an O(1) notification per adopted block. A follower catching up streams blocks from the ImmutableDB, paying a disk read and a deserialisation per block, with file handles owned by the registry. The node already runs one such follower per connected N2C ChainSync client, so one follower per stream scales the same way.
withBlockFollower :: MonadUnliftIO m => NodeKernelAccess -> (ChainFollower BlockInMode -> m a) -> m a Source #
withFollower with the parsed block alone as the ChainApply payload,
reading each block once instead of twice.
positionFollowerAtCurrentTip :: MonadIO m => NodeKernelAccess -> ChainFollower a -> m ChainPoint Source #
Position a freshly opened chain follower at the current tip (origin, at genesis), so it reports only blocks applied from now on, and return that point. A fork switch between the tip read and the intersection takes the old tip off the chain; then read the new tip and try again, rather than fall back to origin and replay the whole chain on the first drain.