cardano-rpc
Safe HaskellNone
LanguageHaskell2010

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

Access handle

data NodeKernelAccess Source #

In-process access to the node kernel. Constructed by cardano-node once consensus initialisation completes.

Instances

Instances details
Has (IORef (Maybe NodeKernelAccess)) RpcEnv Source # 
Instance details

Defined in Cardano.Rpc.Server.Internal.Monad

mkNodeKernelAccess Source #

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

  • byronConfig :: !Config

    The Byron genesis configuration, which bundles the genesis data with the hash the Byron ledger computed when it parsed the file.

  • shelleyGenesisHash :: !GenesisHashShelley

    Blake2b-256 hash of the raw Shelley genesis file bytes.

  • shelleyGenesis :: !(ShelleyGenesisFile 'In, TimedCache ShelleyGenesis)

    The Shelley genesis file the node booted from, and a cache of that file parsed in full, with the initial funds resolved. The two belong together: the path is what the cache loads from. The cache starts empty, is filled by the first request that needs the genesis, and empties itself once five minutes have passed without another one. A node whose genesis nobody asks about therefore keeps none of it in memory (issue #1314).

  • alonzoGenesis :: !AlonzoGenesis

    The Alonzo genesis, which the ledger keeps as the Alonzo translation context.

  • conwayGenesis :: !ConwayGenesis

    The Conway genesis, which the ledger keeps as the Conway translation context.

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.

fetchBlock Source #

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 Nothing if not found

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.

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.