ouroboros-consensus-0.26.0.0: Consensus layer for the Ouroboros blockchain protocol
Safe HaskellNone
LanguageHaskell2010

Ouroboros.Consensus.Ledger.Query

Synopsis

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 QueryVersions. The BlockQuery argument is versioned by the BlockNodeToClientVersion blk.

GetSystemStart ∷ ∀ blk. Query blk SystemStart

Get the SystemStart time.

Supported by QueryVersion >= QueryVersion1.

GetChainBlockNo ∷ ∀ blk. Query blk (WithOrigin BlockNo)

Get the GetChainBlockNo time.

Supported by QueryVersion >= QueryVersion2.

GetChainPoint ∷ ∀ blk. Query blk (Point blk)

Get the GetChainPoint time.

Supported by QueryVersion >= QueryVersion2.

GetLedgerConfig ∷ ∀ blk. Query blk (LedgerCfg (LedgerState blk))

Get the ledger config.

This constructor is supported by QueryVersion >= QueryVersion3. Serialisation of the LedgerConfig blk result is versioned by the BlockNodeToClientVersion blk.

Instances

Instances details
(SerialiseBlockQueryResult blk BlockQuery, Serialise (HeaderHash blk), SerialiseNodeToClient blk (LedgerConfig blk)) ⇒ SerialiseResult blk Query Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

encodeResultCodecConfig blk → BlockNodeToClientVersion blk → Query blk result → result → Encoding Source #

decodeResultCodecConfig blk → BlockNodeToClientVersion blk → Query blk result → ∀ s. Decoder s result Source #

SameDepIndex2 (BlockQuery blk) ⇒ SameDepIndex (Query blk ∷ TypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

sameDepIndexQuery blk a → Query blk b → Maybe (a :~: b) Source #

(∀ (footprint ∷ QueryFootprint). ShowQuery (BlockQuery blk footprint), StandardHash blk) ⇒ ShowQuery (Query blk) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

showResultQuery blk result → result → String Source #

(∀ (footprint ∷ QueryFootprint). Show (BlockQuery blk footprint result)) ⇒ Show (Query blk result) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

showsPrecIntQuery blk result → ShowS #

showQuery blk result → String #

showList ∷ [Query blk result] → ShowS #

ShowProxy (BlockQuery blk) ⇒ ShowProxy (Query blk ∷ TypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

showProxyProxy (Query blk) → String Source #

Show (SomeBlockQuery (BlockQuery blk)) ⇒ Show (SomeSecond Query blk) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

showsPrecIntSomeSecond Query blk → ShowS #

showSomeSecond Query blk → String #

showList ∷ [SomeSecond Query blk] → ShowS #

SameDepIndex (Query blk) ⇒ Eq (SomeSecond Query blk) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

(==)SomeSecond Query blk → SomeSecond Query blk → Bool #

(/=)SomeSecond Query blk → SomeSecond Query blk → Bool #

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 BlockQueryTypeQueryFootprintTypeType Source #

Different queries supported by the ledger, indexed by the result type.

Instances

Instances details
All SingleEraBlock xs ⇒ SameDepIndex2 (BlockQuery (HardForkBlock xs) ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

sameDepIndex2 ∷ ∀ (x ∷ QueryFootprint) a (y ∷ QueryFootprint) b. BlockQuery (HardForkBlock xs) x a → BlockQuery (HardForkBlock xs) y b → Maybe ('(x, a) :~: '(y, b)) Source #

SameDepIndex2 (BlockQuery (DualBlock m a) ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

Methods

sameDepIndex2 ∷ ∀ (x ∷ QueryFootprint) a0 (y ∷ QueryFootprint) b. BlockQuery (DualBlock m a) x a0 → BlockQuery (DualBlock m a) y b → Maybe ('(x, a0) :~: '(y, b)) Source #

SerialiseHFC xs ⇒ SerialiseBlockQueryResult (HardForkBlock xs) BlockQuery Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Serialisation.SerialiseNodeToClient

(∀ (footprint ∷ QueryFootprint) result. Show (BlockQuery blk footprint result)) ⇒ Show (SomeBlockQuery (BlockQuery blk)) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

SerialiseHFC xs ⇒ SerialiseNodeToClient (HardForkBlock xs) (SomeBlockQuery (BlockQuery (HardForkBlock xs))) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Serialisation.SerialiseNodeToClient

All SingleEraBlock xs ⇒ ShowQuery (BlockQuery (HardForkBlock xs) footprint) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

showResultBlockQuery (HardForkBlock xs) footprint result → result → String Source #

ShowQuery (BlockQuery (DualBlock m a) footprint) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

Methods

showResultBlockQuery (DualBlock m a) footprint result → result → String Source #

Typeable xs ⇒ ShowProxy (BlockQuery (HardForkBlock xs) ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

(Typeable m, Typeable a) ⇒ ShowProxy (BlockQuery (DualBlock m a) ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

All SingleEraBlock xs ⇒ Show (BlockQuery (HardForkBlock xs) footprint result) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

showsPrecIntBlockQuery (HardForkBlock xs) footprint result → ShowS #

showBlockQuery (HardForkBlock xs) footprint result → String #

showList ∷ [BlockQuery (HardForkBlock xs) footprint result] → ShowS #

Show (BlockQuery (DualBlock m a) footprint result) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

Methods

showsPrecIntBlockQuery (DualBlock m a) footprint result → ShowS #

showBlockQuery (DualBlock m a) footprint result → String #

showList ∷ [BlockQuery (DualBlock m a) footprint result] → ShowS #

Inject (SomeBlockQuery :.: BlockQuery) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Embed.Nary

data BlockQuery (HardForkBlock xs) footprint result Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

data BlockQuery (HardForkBlock xs) footprint result where
data BlockQuery (DualBlock m a) footprint result Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

data BlockQuery (DualBlock m a) footprint result

class (∀ (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

answerPureBlockQueryExtLedgerCfg 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.

answerBlockQueryLookupMonadSTM 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.

answerBlockQueryTraverseMonadSTM 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

Instances details
(All SingleEraBlock xs, BlockSupportsHFLedgerQuery xs, All BlockSupportsLedgerQuery xs, CanHardFork xs) ⇒ BlockSupportsLedgerQuery (HardForkBlock xs) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Bridge m a ⇒ BlockSupportsLedgerQuery (DualBlock m a) Source #

Not used in the tests: no constructors

Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

class (∀ result. Show (query result)) ⇒ ShowQuery (query ∷ TypeType) 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

Instances details
ShowQuery QueryAnytime Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

showResultQueryAnytime result → result → String Source #

All SingleEraBlock xs ⇒ ShowQuery (QueryHardFork xs) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

showResultQueryHardFork xs result → result → String Source #

(∀ (footprint ∷ QueryFootprint). ShowQuery (BlockQuery blk footprint), StandardHash blk) ⇒ ShowQuery (Query blk) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

showResultQuery blk result → result → String Source #

All SingleEraBlock xs ⇒ ShowQuery (QueryIfCurrent xs footprint) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

showResultQueryIfCurrent xs footprint result → result → String Source #

All SingleEraBlock xs ⇒ ShowQuery (BlockQuery (HardForkBlock xs) footprint) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

showResultBlockQuery (HardForkBlock xs) footprint result → result → String Source #

ShowQuery (BlockQuery (DualBlock m a) footprint) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

Methods

showResultBlockQuery (DualBlock m a) footprint result → result → String Source #

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.

Instances

Instances details
Bounded QueryVersion Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query.Version

Enum QueryVersion Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query.Version

Show QueryVersion Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query.Version

Eq QueryVersion Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query.Version

Ord QueryVersion Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query.Version

nodeToClientVersionToQueryVersionNodeToClientVersionQueryVersion Source #

Get the QueryVersion supported by this NodeToClientVersion.

Serialization

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

Instances details
SingI 'QFLookupTables Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

SingI 'QFNoTables Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

SingI 'QFTraverseTables Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

All SingleEraBlock xs ⇒ SameDepIndex2 (QueryIfCurrent xs ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

sameDepIndex2 ∷ ∀ (x ∷ QueryFootprint) a (y ∷ QueryFootprint) b. QueryIfCurrent xs x a → QueryIfCurrent xs y b → Maybe ('(x, a) :~: '(y, b)) Source #

All SingleEraBlock xs ⇒ SameDepIndex2 (BlockQuery (HardForkBlock xs) ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

Methods

sameDepIndex2 ∷ ∀ (x ∷ QueryFootprint) a (y ∷ QueryFootprint) b. BlockQuery (HardForkBlock xs) x a → BlockQuery (HardForkBlock xs) y b → Maybe ('(x, a) :~: '(y, b)) Source #

SameDepIndex2 (BlockQuery (DualBlock m a) ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

Methods

sameDepIndex2 ∷ ∀ (x ∷ QueryFootprint) a0 (y ∷ QueryFootprint) b. BlockQuery (DualBlock m a) x a0 → BlockQuery (DualBlock m a) y b → Maybe ('(x, a0) :~: '(y, b)) Source #

SerialiseHFC xs ⇒ SerialiseBlockQueryResult (HardForkBlock xs) BlockQuery Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Serialisation.SerialiseNodeToClient

SerialiseNodeToClient blk (SomeBlockQuery (query blk)) ⇒ SerialiseNodeToClient blk ((SomeBlockQuery :.: query) blk) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Typeable xs ⇒ ShowProxy (BlockQuery (HardForkBlock xs) ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger.Query

(Typeable m, Typeable a) ⇒ ShowProxy (BlockQuery (DualBlock m a) ∷ QueryFootprintTypeType) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Dual

Inject (SomeBlockQuery :.: BlockQuery) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Embed.Nary

type Sing Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

data SomeBlockQuery (q ∷ QueryFootprintTypeType) Source #

Constructors

SingI footprint ⇒ SomeBlockQuery !(q footprint result) 

Instances

Instances details
SerialiseNodeToClient blk (SomeBlockQuery (query blk)) ⇒ SerialiseNodeToClient blk ((SomeBlockQuery :.: query) blk) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

(∀ (footprint ∷ QueryFootprint) result. Show (BlockQuery blk footprint result)) ⇒ Show (SomeBlockQuery (BlockQuery blk)) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

SameDepIndex2 query ⇒ Eq (SomeBlockQuery query) Source # 
Instance details

Defined in Ouroboros.Consensus.Ledger.Query

Methods

(==)SomeBlockQuery query → SomeBlockQuery query → Bool #

(/=)SomeBlockQuery query → SomeBlockQuery query → Bool #

SerialiseHFC xs ⇒ SerialiseNodeToClient (HardForkBlock xs) (SomeBlockQuery (BlockQuery (HardForkBlock xs))) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Serialisation.SerialiseNodeToClient

Inject (SomeBlockQuery :.: BlockQuery) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Embed.Nary