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