GET /head api to query the full head state (#2049)

<!-- Describe your change here -->

Closes #1957

This also refactors some of the other HTTP queries (and Greetings) in
terms of a single 'aggregate'-reusing projection.

This PR revives #2002.

---

<!-- Consider each and tick it off one way or the other -->
* [X] CHANGELOG updated or not needed
* [X] Documentation updated or not needed
* [X] Haddocks updated or not needed
* [X] No new TODOs introduced or explained herafter

---------

Co-authored-by: Sebastian Nagel <[email protected]>
Co-authored-by: Sasha Bogicevic <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -46,6 +46,8 @@ changes.
 - Enhanced the error message for `etcd` cluster ID mismatches by including detailed information about
   the expected peers versus peers loaded from the `hydra-node` arguments.
 
+- Add API query (GET /head) to fetch the latest head state by a node and help introspecting the whole internal state.
+
 ## [0.21.0] - 2025-04-28
 
 - New metric for counting the number of active peers: `hydra_head_peers_connected`

hydra-node/golden/ReasonablySized (HeadState (Tx ConwayEra)).json

@@ -118,6 +118,34 @@ channels:
           - $ref: "api.yaml#/components/messages/Contest"
           - $ref: "api.yaml#/components/messages/Fanout"
           - $ref: "api.yaml#/components/messages/SideLoadSnapshot"
+  
+  /head:
+    servers:
+      - localhost-http
+    publish:
+      description: Get latest head state.
+      operationId: getHeadState
+      message:
+        payload:
+          type: "null"
+      bindings:
+        http:
+          type: request
+          method: GET
+          bindingVersion: '0.1.0'
+    subscribe:
+      operationId: headStateResponse
+      description: |
+        Possible responses of this endpoint are:
+          * 200 OK
+      message:
+        payload:
+          $ref: "api.yaml#/components/schemas/HeadState"
+      bindings:
+        http:
+          type: response
+          method: GET
+          bindingVersion: '0.1.0'
 
   /commit:
     servers:
@@ -2964,3 +2992,241 @@ components:
       description: Hydra network protocol version
       type: integer
       minimum: 0
+
+    HeadState:
+      oneOf:
+        - title: "Idle"
+          additionalProperties: false
+          required:
+            - tag
+            - contents
+          properties:
+            tag:
+              type: string
+              enum: ["Idle"]
+            contents:
+              $ref: "api.yaml#/components/schemas/IdleState"
+        - title: "Initial"
+          additionalProperties: false
+          required:
+            - tag
+            - contents
+          properties:
+            tag:
+              type: string
+              enum: ["Initial"]
+            contents:
+              $ref: "api.yaml#/components/schemas/InitialState"
+        - title: "Open"
+          additionalProperties: false
+          required:
+            - tag
+            - contents
+          properties:
+            tag:
+              type: string
+              enum: ["Open"]
+            contents:
+              $ref: "api.yaml#/components/schemas/OpenState"
+        - title: "Closed"
+          additionalProperties: false
+          required:
+            - tag
+            - contents
+          properties:
+            tag:
+              type: string
+              enum: ["Closed"]
+            contents:
+              $ref: "api.yaml#/components/schemas/ClosedState"
+
+    IdleState:
+      type: object
+      additionalProperties: false
+      required:
+        - chainState
+      properties:
+        chainState:
+          $ref: "api.yaml#/components/schemas/ChainState"
+
+    InitialState:
+      type: object
+      additionalProperties: false
+      required:
+        - parameters
+        - pendingCommits
+        - committed
+        - chainState
+        - headId
+        - headSeed
+      properties:
+        parameters:
+          $ref: "api.yaml#/components/schemas/HeadParameters"
+        pendingCommits:
+          type: array
+          items:
+            $ref: "api.yaml#/components/schemas/Party"
+        committed:
+          type: object
+          propertyNames:
+            $ref: "api.yaml#/components/schemas/Party"
+          items:
+            $ref: "api.yaml#/components/schemas/UTxO"
+        chainState:
+          $ref: "api.yaml#/components/schemas/ChainState"
+        headId:
+          $ref: "api.yaml#/components/schemas/HeadId"
+        headSeed:
+          $ref: "api.yaml#/components/schemas/HeadSeed"
+
+    OpenState:
+      type: object
+      additionalProperties: false
+      required:
+        - parameters
+        - coordinatedHeadState
+        - chainState
+        - headId
+        - currentSlot
+        - headSeed
+      properties:
+        parameters:
+          $ref: "api.yaml#/components/schemas/HeadParameters"
+        coordinatedHeadState:
+          $ref: "api.yaml#/components/schemas/CoordinatedHeadState"
+        chainState:
+          $ref: "api.yaml#/components/schemas/ChainState"
+        headId:
+          $ref: "api.yaml#/components/schemas/HeadId"
+        currentSlot:
+          $ref: "api.yaml#/components/schemas/ChainSlot"
+        headSeed:
+          $ref: "api.yaml#/components/schemas/HeadSeed"
+
+    ClosedState:
+      type: object
+      additionalProperties: false
+      required:
+        - parameters
+        - confirmedSnapshot
+        - contestationDeadline
+        - readyToFanoutSent
+        - chainState
+        - headId
+        - headSeed
+        - version
+      properties:
+        parameters:
+          $ref: "api.yaml#/components/schemas/HeadParameters"
+        confirmedSnapshot:
+          $ref: "api.yaml#/components/schemas/ConfirmedSnapshot"
+        contestationDeadline:
+          $ref: "api.yaml#/components/schemas/UTCTime"
+        readyToFanoutSent:
+          type: boolean
+        chainState:
+          $ref: "api.yaml#/components/schemas/ChainState"
+        headId:
+          $ref: "api.yaml#/components/schemas/HeadId"
+        headSeed:
+          $ref: "api.yaml#/components/schemas/HeadSeed"
+        version:
+          $ref: "api.yaml#/components/schemas/SnapshotVersion"
+
+    CoordinatedHeadState:
+      type: object
+      additionalProperties: false
+      required:
+        - localUTxO
+        - localTxs
+        - allTxs
+        - confirmedSnapshot
+        - seenSnapshot
+        - pendingDeposits
+        - currentDepositTxId
+        - decommitTx
+        - version
+      properties:
+        localUTxO:
+          $ref: "api.yaml#/components/schemas/UTxO"
+        localTxs:
+          type: array
+          items:
+            $ref: "api.yaml#/components/schemas/Transaction"
+        allTxs:
+          type: object
+          propertyNames:
+            $ref: "api.yaml#/components/schemas/TxId"
+          items:
+            $ref: "api.yaml#/components/schemas/Transaction"
+        confirmedSnapshot:
+          $ref: "api.yaml#/components/schemas/ConfirmedSnapshot"
+        seenSnapshot:
+          $ref: "api.yaml#/components/schemas/SeenSnapshot"
+        pendingDeposits:
+          type: object
+          propertyNames:
+            $ref: "api.yaml#/components/schemas/TxId"
+          items:
+            $ref: "api.yaml#/components/schemas/Deposit"
+        currentDepositTxId:
+          oneOf:
+            - type: "null"
+            - $ref: "api.yaml#/components/schemas/TxId"
+        decommitTx:
+          oneOf:
+            - type: "null"
+            - $ref: "api.yaml#/components/schemas/Transaction"
+        version:
+          $ref: "api.yaml#/components/schemas/SnapshotVersion"
+
+    Deposit:
+      type: object
+      additionalProperties: false
+      required:
+        - headId
+        - deposited
+        - created
+        - deadline
+        - status
+      properties:
+        headId:
+          $ref: "api.yaml#/components/schemas/HeadId"
+        deposited:
+          $ref: "api.yaml#/components/schemas/UTxO"
+        created:
+          $ref: "api.yaml#/components/schemas/UTCTime"
+        deadline:
+          $ref: "api.yaml#/components/schemas/UTCTime"
+        status:
+          $ref: "api.yaml#/components/schemas/DepositStatus"
+
+    DepositStatus:
+      oneOf:
+        - title: Unknown
+          type: object
+          additionalProperties: false
+          required:
+            - tag
+          properties:
+            tag:
+              type: string
+              enum: ["Unknown"]
+        - title: Active
+          type: object
+          additionalProperties: false
+          required:
+            - tag
+          properties:
+            tag:
+              type: string
+              enum: ["Active"]
+        - title: Expired
+          type: object
+          additionalProperties: false
+          required:
+            - tag
+          properties:
+            tag:
+              type: string
+              enum: ["Expired"]

hydra-node/json-schemas/api.yaml

@@ -12,7 +12,7 @@ import Data.ByteString.Short ()
 import Data.Text (pack)
 import Hydra.API.APIServerLog (APIServerLog (..), Method (..), PathInfo (..))
 import Hydra.API.ClientInput (ClientInput (..))
-import Hydra.API.ServerOutput (CommitInfo (..))
+import Hydra.API.ServerOutput (CommitInfo (..), getConfirmedSnapshot, getSeenSnapshot, getSnapshotUtxo)
 import Hydra.Cardano.Api (
   LedgerEra,
   Tx,
@@ -22,7 +22,9 @@ import Hydra.Chain.ChainState (
   IsChainState,
  )
 import Hydra.Chain.Direct.State ()
-import Hydra.HeadLogic.State (SeenSnapshot (..))
+import Hydra.HeadLogic.State (
+  HeadState (..),
+ )
 import Hydra.Logging (Tracer, traceWith)
 import Hydra.Node.DepositPeriod (toNominalDiffTime)
 import Hydra.Node.Environment (Environment (..))
@@ -147,43 +149,41 @@ httpApp ::
   Chain tx IO ->
   Environment ->
   PParams LedgerEra ->
+  -- | Get latest 'HeadState'.
+  IO (HeadState tx) ->
   -- | A means to get commit info.
   IO CommitInfo ->
-  -- | Get latest confirmed UTxO snapshot.
-  IO (Maybe (UTxOType tx)) ->
-  -- | Get latest seen snapshot.
-  IO (SeenSnapshot tx) ->
-  -- | Get latest confirmed snapshot.
-  IO (Maybe (ConfirmedSnapshot tx)) ->
   -- | Get the pending commits (deposits)
   IO [TxIdType tx] ->
   -- | Callback to yield a 'ClientInput' to the main event loop.
   (ClientInput tx -> IO ()) ->
   Application
-httpApp tracer directChain env pparams getCommitInfo getConfirmedUTxO getSeenSnapshot getConfirmedSnapshot getPendingDeposits putClientInput request respond = do
+httpApp tracer directChain env pparams getHeadState getCommitInfo getPendingDeposits putClientInput request respond = do
   traceWith tracer $
     APIHTTPRequestReceived
       { method = Method $ requestMethod request
       , path = PathInfo $ rawPathInfo request
       }
   case (requestMethod request, pathInfo request) of
-    ("GET", ["snapshot", "last-seen"]) ->
-      getSeenSnapshot >>= respond . okJSON
-    ("GET", ["snapshot"]) ->
-      getConfirmedSnapshot >>= \case
+    ("GET", ["head"]) ->
+      getHeadState >>= respond . okJSON
+    ("GET", ["snapshot"]) -> do
+      hs <- getHeadState
+      case getConfirmedSnapshot hs of
+        Just confirmedSnapshot -> respond $ okJSON confirmedSnapshot
         Nothing -> respond notFound
-        Just snapshot -> respond $ okJSON snapshot
+    ("GET", ["snapshot", "utxo"]) -> do
+      hs <- getHeadState
+      case getSnapshotUtxo hs of
+        Just utxo -> respond $ okJSON utxo
+        _ -> respond notFound
+    ("GET", ["snapshot", "last-seen"]) -> do
+      hs <- getHeadState
+      respond . okJSON $ getSeenSnapshot hs
     ("POST", ["snapshot"]) ->
       consumeRequestBodyStrict request
         >>= handleSideLoadSnapshot putClientInput
         >>= respond
-    ("GET", ["snapshot", "utxo"]) ->
-      -- XXX: Should ensure the UTxO is of the right head and the head is still
-      -- open. This is something we should fix on the "read model" side of the
-      -- server.
-      getConfirmedUTxO >>= \case
-        Nothing -> respond notFound
-        Just utxo -> respond $ okJSON utxo
     ("POST", ["commit"]) ->
       consumeRequestBodyStrict request
         >>= handleDraftCommitUtxo env directChain getCommitInfo