Skip to main content

API Behavior

This page documents the behavior of a hydra-node at the API layer. That is, how the system behaves given ClientInputs and what ServerOutputs are produced in response to it. See also the API reference for more details about individual API messages.

The formalism uses UML statechart language where transitions are labeled: input [condition] / output. When two outputs (e.g. A and B) are expected we write A,B, while {A,B} denotes mutual exclusiveness of outputs.

Edit this diagram

Not pictured is the CommandFailed output, which is implicit emitted whenever an input is used when no transition below applies. Also non-state-changing or life-cycle relevant inputs like GetUTxO are not mentioned, as well as outputs like Greetings, InvalidInput, PeerConnected, PeerDisconnected and GetUTxOResponse.

A special case is the RolledBack output. This means that the chain rolled back, and it includes timestamp and a counter (same as other API client messages) so it is easier to construct the timeline.

Replay of past server outputs

When a hydra-node restarts, it will load it's history from persistence and replay previous server outputs to enable clients to re-establish their state upon re-connection. If that happens, obviously some of these outputs are not relevant anymore. One example of this is the PeerConnected and PeerDisconnected. To make it possible to determine the end of replayed history, client applications can use the Greetings, which will be emitted on every hydra-node start. See the hydra-tui example client for how this is handled.