| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Ouroboros.Consensus.Ledger.Query
Synopsis
- data Query blk result where
- BlockQuery ∷ ∀ (footprint ∷ QueryFootprint) blk result. SingI footprint ⇒ BlockQuery blk footprint result → Query blk result
- GetSystemStart ∷ ∀ blk. Query blk SystemStart
- GetChainBlockNo ∷ ∀ blk. Query blk (WithOrigin BlockNo)
- GetChainPoint ∷ ∀ blk. Query blk (Point blk)
- DebugLedgerConfig ∷ ∀ blk. Query blk (LedgerCfg (LedgerState blk))
- answerQuery ∷ (BlockSupportsLedgerQuery blk, ConfigSupportsNode blk, HasAnnTip blk, MonadSTM m) ⇒ ExtLedgerCfg blk → ReadOnlyForker' m blk → Query blk result → m result
- data family BlockQuery ∷ Type → QueryFootprint → Type → Type
- class (∀ (fp ∷ QueryFootprint) result. Show (BlockQuery blk fp result), ∀ (fp ∷ QueryFootprint). ShowQuery (BlockQuery blk fp), SameDepIndex2 (BlockQuery blk)) ⇒ BlockSupportsLedgerQuery blk where
- answerPureBlockQuery ∷ ExtLedgerCfg blk → BlockQuery blk 'QFNoTables result → ExtLedgerState blk EmptyMK → result
- answerBlockQueryLookup ∷ MonadSTM m ⇒ ExtLedgerCfg blk → BlockQuery blk 'QFLookupTables result → ReadOnlyForker' m blk → m result
- answerBlockQueryTraverse ∷ MonadSTM m ⇒ ExtLedgerCfg blk → BlockQuery blk 'QFTraverseTables result → ReadOnlyForker' m blk → m result
- blockQueryIsSupportedOnVersion ∷ ∀ (fp ∷ QueryFootprint) result. BlockQuery blk fp result → BlockNodeToClientVersion blk → Bool
- class ConfigSupportsNode blk where
- getSystemStart ∷ BlockConfig blk → SystemStart
- getNetworkMagic ∷ BlockConfig blk → NetworkMagic
- class (∀ result. Show (query result)) ⇒ ShowQuery (query ∷ Type → Type) where
- showResult ∷ query result → result → String
- data QueryVersion
- nodeToClientVersionToQueryVersion ∷ NodeToClientVersion → QueryVersion
- queryDecodeNodeToClient ∷ SerialiseNodeToClient blk (SomeBlockQuery (BlockQuery blk)) ⇒ CodecConfig blk → QueryVersion → BlockNodeToClientVersion blk → ∀ s. Decoder s (SomeSecond Query blk)
- queryEncodeNodeToClient ∷ (SerialiseNodeToClient blk (SomeBlockQuery (BlockQuery blk)), Show (SomeSecond Query blk), BlockSupportsLedgerQuery blk, Show (BlockNodeToClientVersion blk), Typeable blk) ⇒ CodecConfig blk → QueryVersion → BlockNodeToClientVersion blk → SomeSecond Query blk → Encoding
- queryIsSupportedOnNodeToClientVersion ∷ (SupportedNetworkProtocolVersion blk, BlockSupportsLedgerQuery blk) ⇒ Query blk result → NodeToClientVersion → Bool
- querySupportedVersions ∷ (SupportedNetworkProtocolVersion blk, BlockSupportsLedgerQuery blk) ⇒ Query blk result → [NodeToClientVersion]
- data QueryFootprint
- data SQueryFootprint (a ∷ QueryFootprint) where
- data SomeBlockQuery (q ∷ QueryFootprint → Type → Type) = SingI footprint ⇒ SomeBlockQuery !(q footprint result)
Queries that can be answered by the Consensus layer
data Query blk result where Source #
Different queries supported by the ledger for all block types, indexed by the result type.
Additions to the set of queries is versioned by QueryVersion
Constructors
| BlockQuery ∷ ∀ (footprint ∷ QueryFootprint) blk result. SingI footprint ⇒ BlockQuery blk footprint result → Query blk result | This constructor is supported by all |
| GetSystemStart ∷ ∀ blk. Query blk SystemStart | Get the Supported by |
| GetChainBlockNo ∷ ∀ blk. Query blk (WithOrigin BlockNo) | Get the Supported by |
| GetChainPoint ∷ ∀ blk. Query blk (Point blk) | Get the Supported by |
| DebugLedgerConfig ∷ ∀ blk. Query blk (LedgerCfg (LedgerState blk)) | Get the ledger config. Note that this is a debug query, so we are not (yet) guaranteeing stability across node versions. This constructor is supported by |
Instances
answerQuery ∷ (BlockSupportsLedgerQuery blk, ConfigSupportsNode blk, HasAnnTip blk, MonadSTM m) ⇒ ExtLedgerCfg blk → ReadOnlyForker' m blk → Query blk result → m result Source #
Answer the given query about the extended ledger state.
How to answer specific queries
data family BlockQuery ∷ Type → QueryFootprint → Type → Type Source #
Different queries supported by the ledger, indexed by the result type.
Instances
class (∀ (fp ∷ QueryFootprint) result. Show (BlockQuery blk fp result), ∀ (fp ∷ QueryFootprint). ShowQuery (BlockQuery blk fp), SameDepIndex2 (BlockQuery blk)) ⇒ BlockSupportsLedgerQuery blk where Source #
Query the ledger extended state.
Used by the LocalStateQuery protocol to allow clients to query the extended ledger state.
Methods
answerPureBlockQuery ∷ ExtLedgerCfg blk → BlockQuery blk 'QFNoTables result → ExtLedgerState blk EmptyMK → result Source #
Answer the given query about the extended ledger state, without reading ledger tables from the disk.
answerBlockQueryLookup ∷ MonadSTM m ⇒ ExtLedgerCfg blk → BlockQuery blk 'QFLookupTables result → ReadOnlyForker' m blk → m result Source #
Answer a query that requires to perform a lookup on the ledger tables. As consensus always runs with a HardForkBlock, this might result in a different code path to answer a query compared to the one that a single block would take, one that is aware of the fact that the ledger tables might be HF ledger tables thus making use of some utilities to make these queries faster.
For the hard fork block this will be instantiated to
answerBlockQueryHFLookup.
answerBlockQueryTraverse ∷ MonadSTM m ⇒ ExtLedgerCfg blk → BlockQuery blk 'QFTraverseTables result → ReadOnlyForker' m blk → m result Source #
Answer a query that requires to traverse the ledger tables. As consensus always runs with a HardForkBlock, this might result in a different code path to answer a query compared to the one that a single block would take, one that is aware of the fact that the ledger tables might be HF ledger tables thus making use of some utilities to make these queries faster.
For the hard fork block this will be instantiated to
answerBlockQueryHFTraverse.
blockQueryIsSupportedOnVersion ∷ ∀ (fp ∷ QueryFootprint) result. BlockQuery blk fp result → BlockNodeToClientVersion blk → Bool Source #
Is the given query supported in this NTC version?
Encoders for queries should call this function before attempting to send a query. The node will still try to answer block queries it knows about even if they are not guaranteed to be supported on the negotiated version, but clients can benefit of knowing beforehand whether the query is expected to not work, even if it decides to send it anyways.
More reasoning on how queries are versioned in Consensus can be seen in https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/QueryVersioning/. In particular this function implements the check described in https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/QueryVersioning/#checks.
Instances
class ConfigSupportsNode blk where Source #
The BlockConfig needs to contain some information in order to support
running a node.
Methods
getSystemStart ∷ BlockConfig blk → SystemStart Source #
getNetworkMagic ∷ BlockConfig blk → NetworkMagic Source #
Instances
| CanHardFork xs ⇒ ConfigSupportsNode (HardForkBlock xs) Source # | |
Defined in Ouroboros.Consensus.HardFork.Combinator.Node Methods getSystemStart ∷ BlockConfig (HardForkBlock xs) → SystemStart Source # getNetworkMagic ∷ BlockConfig (HardForkBlock xs) → NetworkMagic Source # | |
| ConfigSupportsNode m ⇒ ConfigSupportsNode (DualBlock m a) Source # | |
Defined in Ouroboros.Consensus.Ledger.Dual Methods getSystemStart ∷ BlockConfig (DualBlock m a) → SystemStart Source # getNetworkMagic ∷ BlockConfig (DualBlock m a) → NetworkMagic Source # | |
class (∀ result. Show (query result)) ⇒ ShowQuery (query ∷ Type → Type) where Source #
To implement Show for:
('Message' ('LocalStateQuery' block query) st st')we need a way to print the query GADT and its type index, result. This
class contain the method we need to provide this Show instance.
We use a type class for this, as this Show constraint propagates to a lot
of places.
Methods
showResult ∷ query result → result → String Source #
Instances
Version
data QueryVersion Source #
Version of the `Query blk` type.
Multiple top level queries are now supported. The encoding now has constructor tags for the different top level queries for QueryVersion1 onwards.
Constructors
| QueryVersion1 | |
| QueryVersion2 | |
| QueryVersion3 |
Instances
nodeToClientVersionToQueryVersion ∷ NodeToClientVersion → QueryVersion Source #
Get the QueryVersion supported by this NodeToClientVersion.
Serialization
queryDecodeNodeToClient ∷ SerialiseNodeToClient blk (SomeBlockQuery (BlockQuery blk)) ⇒ CodecConfig blk → QueryVersion → BlockNodeToClientVersion blk → ∀ s. Decoder s (SomeSecond Query blk) Source #
queryEncodeNodeToClient ∷ (SerialiseNodeToClient blk (SomeBlockQuery (BlockQuery blk)), Show (SomeSecond Query blk), BlockSupportsLedgerQuery blk, Show (BlockNodeToClientVersion blk), Typeable blk) ⇒ CodecConfig blk → QueryVersion → BlockNodeToClientVersion blk → SomeSecond Query blk → Encoding Source #
queryIsSupportedOnNodeToClientVersion ∷ (SupportedNetworkProtocolVersion blk, BlockSupportsLedgerQuery blk) ⇒ Query blk result → NodeToClientVersion → Bool Source #
querySupportedVersions ∷ (SupportedNetworkProtocolVersion blk, BlockSupportsLedgerQuery blk) ⇒ Query blk result → [NodeToClientVersion] Source #
Footprints
data QueryFootprint Source #
Queries on the local state might require reading ledger tables from disk.
This datatype (which will sometimes be concretized via sing) allows
Consensus to categorize the queries.
Constructors
| QFNoTables | The query doesn't need ledger tables, thus can be answered only with the ledger state. |
| QFLookupTables | The query needs some tables, but doesn't need to traverse the whole backing store. |
| QFTraverseTables | The query needs to traverse the whole backing store. |
Instances
data SQueryFootprint (a ∷ QueryFootprint) where Source #
data SomeBlockQuery (q ∷ QueryFootprint → Type → Type) Source #
Constructors
| SingI footprint ⇒ SomeBlockQuery !(q footprint result) |