Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

LocalStateQuery

Protocol version: V19

warning

TODO: Explain how to use and relate state diagram to full protocol in network chapter?

Full mini-protocol state diagram
stateDiagram
    direction LR
    [*] --> StIdle
    StIdle --> [*]: MsgDone
    StIdle --> Acquiring: MsgAcquire
    Acquiring --> Acquired: MsgAcquired
    Acquired --> Querying: MsgQuery
    Querying --> Acquired: MsgResult
    Acquired --> Acquiring: MsgReAcquire
    Acquiring --> StIdle: MsgFailure
    Acquired --> StIdle: MsgRelease

See also definition in network spec.

Client-side view on the protocol1:

                      ●
                      │
                      ▼
              ┌───────────────┐ MsgDone
       ╭─────▶│     Idle      ├────────▶ ○
       │      └───────┬───────┘
       │   MsgAcquire │
       │              ▼  ╭────────╮
       │      ┌──────────┴────┐   │ MsgReAcquire
       ╰──────┤   Acquired    │◀──╯
  MsgRelease  └───┬───────────┘
                  │       ▲
                  ╰───────╯
                   MsgQuery
Broken mermaid rendering
stateDiagram
    direction LR
    [*] --> StIdle
    StIdle --> Acquired: MsgAcquire
    Acquired --> Acquired: MsgQuery, MsgReAcquire, MsgFailure
    StIdle --> StIdle: MsgFailure
    Acquired --> StIdle: MsgRelease
    StIdle --> [*]: MsgDone

Acquire a state

To use the ledger state query API, a client needs to first specify at which point on the chain the query should be executed. Depending on the server implementation, this point may only be within the “volatile” recent part of the chain. A typical practice is to acquire the tip of the chain, perform one or more queries and close the connection again.

warning

TODO: show how to acquire a point with an example CBOR message

Queries

warning

TODO: Explain distinction between consensus and block queries here

getSystemStart

Since: v9

Query the chain’s start time as a UTCTime.

msgQuery     = [3, query]
msgResult    = [4, result]
query = 1
result = [year, dayOfYear, timeOfDayPico]
year = bigint
dayOfYear = int
timeOfDayPico = bigint

Example query:

82038101

Example response:

820483c2581e65fea62360470c59141d0ba6cc897f99e050184606937264a1f8c5026abc3b3a5d754770442481c3581e50670ee65e805e3cc5aadf6619e791db8b1c2237dd918ba3b6818e7c258a

caution

FIXME: While I experimented in using the network / consensus cddl parts above, time would be defined in the CDDL prelude (a number, assuming seconds since epoch), but is actually incorrect and the result is serialized using ToCBOR UTCTime following this cddl:

time = [year, dayOfYear, timeOfDayPico]
year = bigint
dayOfYear = int
timeOfDayPico = bigint

getCurrentPParams

warning

TODO: Era-specific query with an involved answer


  1. Derived from ogmios’ great ascii art description.