Node-To-Client (N2C)

A cardano node may offer a client-facing API using the network protocols. This interface is slightly different than the Node-to-Node (N2N) style of communication as there is trust between peers and consequently behaves more like traditional client/server APIs.

This document serves as concrete API reference for the various N2C protocols and currently only covers the local state query API.

note

The way to establish connections to an N2C server may differ from one implementation to another. The following sections assume that you have an established connection and negotiated a protocol version possibly through the handshake protocol.

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
1

Derived from ogmios’ great ascii art description.

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