Initialization time info (#2320)

fixes #2316 
---

<!-- 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

Author: v0d1ch

CHANGELOG.md

@@ -9,6 +9,11 @@ As a minor extension, we also keep a semantic version for the `UNRELEASED`
 changes.
 
 
+## [1.2.0] - UNRELEASED
+
+- `hydra-node` has a new endpoint `GET /head-initialization` which serves the timestamp of the last Head initialization.
+
+
 ## [1.1.0] - 2025-10-28
 
 - **BREAKING** Partial assets depositing works a bit differently now so you should consult our [API reference](https://hydra.family/head-protocol/api-reference).

hydra-node/json-schemas/api.yaml

@@ -454,6 +454,20 @@ channels:
           type: response
           method: POST
           bindingVersion: '0.1.0'
+  /head-initialization:
+    servers:
+      - localhost-http
+    subscribe:
+      description: Get the last Head initialization time.
+      operationId: getHeadInitialization
+      message:
+        summary: |
+           Timestamp of the last seen Head initialization.
+      bindings:
+        http:
+          type: response
+          method: GET
+          bindingVersion: '0.1.0'
 
 components:
   messages:

hydra-node/src/Hydra/API/HTTPServer.hs

@@ -5,17 +5,31 @@ module Hydra.API.HTTPServer where
 import Hydra.Prelude
 
 import Cardano.Ledger.Core (PParams)
+import Conduit (
+  ConduitT,
+  MonadUnliftIO,
+  concatC,
+  linesUnboundedAsciiC,
+  mapMC,
+  runConduitRes,
+  sinkList,
+  sourceFileBS,
+  (.|),
+ )
 import Control.Concurrent.STM (TChan, dupTChan, readTChan)
-import Data.Aeson (KeyValue ((.=)), object, withObject, (.:), (.:?))
+import Control.Lens ((^?))
+import Data.Aeson (KeyValue ((.=)), Value (String), object, withObject, (.:), (.:?))
 import Data.Aeson qualified as Aeson
+import Data.Aeson.Lens (key, _String)
 import Data.Aeson.Types (Parser)
 import Data.ByteString.Lazy qualified as LBS
 import Data.ByteString.Short ()
+import Data.List qualified as List
 import Data.Text (pack)
 import Hydra.API.APIServerLog (APIServerLog (..), Method (..), PathInfo (..))
 import Hydra.API.ClientInput (ClientInput (..))
 import Hydra.API.ServerOutput (ClientMessage (..), CommitInfo (..), ServerOutput (..), TimedServerOutput (..), getConfirmedSnapshot, getSeenSnapshot, getSnapshotUtxo)
-import Hydra.Cardano.Api (AddressInEra, LedgerEra, Tx)
+import Hydra.Cardano.Api (AddressInEra, LedgerEra, SlotNo, Tx)
 import Hydra.Chain (Chain (..), PostTxError (..), draftCommitTx)
 import Hydra.Chain.ChainState (IsChainState)
 import Hydra.Chain.Direct.State ()
@@ -28,6 +42,7 @@ import Hydra.Node.State (NodeState (..))
 import Hydra.Tx (CommitBlueprintTx (..), ConfirmedSnapshot, IsTx (..), Snapshot (..), UTxOType)
 import Network.HTTP.Types (ResponseHeaders, hContentType, status200, status202, status400, status404, status500)
 import Network.Wai (Application, Request (pathInfo, requestMethod), Response, consumeRequestBodyStrict, rawPathInfo, responseLBS)
+import System.Directory (doesFileExist)
 
 newtype DraftCommitTxResponse tx = DraftCommitTxResponse
   { commitTx :: tx
@@ -179,6 +194,13 @@ instance FromJSON SubmitL2TxResponse where
 instance Arbitrary SubmitL2TxResponse where
   arbitrary = genericArbitrary
 
+data HeadInitializationDetails
+  = HeadInitializationDetails
+  { time :: UTCTime
+  , slot :: SlotNo
+  }
+  deriving (Eq, Show)
+
 jsonContent :: ResponseHeaders
 jsonContent = [(hContentType, "application/json")]
 
@@ -189,6 +211,7 @@ httpApp ::
   Tracer IO APIServerLog ->
   Chain tx IO ->
   Environment ->
+  FilePath ->
   PParams LedgerEra ->
   -- | Get latest 'NodeState'.
   IO (NodeState tx) ->
@@ -203,7 +226,7 @@ httpApp ::
   -- | Channel to listen for events
   TChan (Either (TimedServerOutput tx) (ClientMessage tx)) ->
   Application
-httpApp tracer directChain env pparams getNodeState getCommitInfo getPendingDeposits putClientInput apiTransactionTimeout responseChannel request respond = do
+httpApp tracer directChain env stateFile pparams getNodeState getCommitInfo getPendingDeposits putClientInput apiTransactionTimeout responseChannel request respond = do
   traceWith tracer $
     APIHTTPRequestReceived
       { method = Method $ requestMethod request
@@ -225,6 +248,9 @@ httpApp tracer directChain env pparams getNodeState getCommitInfo getPendingDepo
     ("GET", ["snapshot", "last-seen"]) -> do
       hs <- headState <$> getNodeState
       respond . okJSON $ getSeenSnapshot hs
+    ("GET", ["head-initialization"]) ->
+      handleHeadInitializationTime stateFile
+        >>= respond
     ("POST", ["snapshot"]) ->
       consumeRequestBodyStrict request
         >>= handleSideLoadSnapshot putClientInput apiTransactionTimeout responseChannel
@@ -530,6 +556,33 @@ handleSubmitL2Tx putClientInput apiTransactionTimeout responseChannel body = do
           _ -> go
         Right _ -> go
 
+handleHeadInitializationTime :: MonadUnliftIO m => FilePath -> m Response
+handleHeadInitializationTime stateFile =
+  liftIO (doesFileExist stateFile) >>= \case
+    False -> pure $ responseLBS status400 jsonContent (Aeson.encode $ String $ "Could not read state file at path: " <> show stateFile)
+    True -> do
+      initializations <- runConduitRes $ sourceFileBS stateFile .| parseInitializingTime
+      case initializations of
+        [] -> pure $ responseLBS status400 jsonContent (Aeson.encode $ String "Unable to find Head initialization time in your state file.")
+        as ->
+          pure $ responseLBS status200 jsonContent (Aeson.encode $ List.last as)
+
+parseInitializingTime :: MonadUnliftIO m => ConduitT ByteString Void m [Text]
+parseInitializingTime =
+  linesUnboundedAsciiC
+    .| mapMC maybeDecode
+    .| concatC
+    .| sinkList
+ where
+  maybeDecode :: Monad m => ByteString -> m (Maybe Text)
+  maybeDecode bs =
+    case bs ^? key "stateChanged" . key "tag" . _String of
+      Nothing -> pure Nothing
+      Just tag ->
+        if tag == "HeadInitialized"
+          then pure $ bs ^? key "time" . _String
+          else pure Nothing
+
 badRequest :: IsChainState tx => PostTxError tx -> Response
 badRequest = responseLBS status400 jsonContent . Aeson.encode . toJSON
 

hydra-node/src/Hydra/API/Server.hs

@@ -84,6 +84,7 @@ withAPIServer ::
   IsChainState tx =>
   APIServerConfig ->
   Environment ->
+  FilePath ->
   Party ->
   EventSource (StateEvent tx) IO ->
   Tracer IO APIServerLog ->
@@ -93,7 +94,7 @@ withAPIServer ::
   (ClientInput tx -> IO ()) ->
   ((EventSink (StateEvent tx) IO, Server tx IO) -> IO ()) ->
   IO ()
-withAPIServer config env party eventSource tracer chain pparams serverOutputFilter callback action =
+withAPIServer config env stateFile party eventSource tracer chain pparams serverOutputFilter callback action =
   handle onIOException $ do
     responseChannel <- newBroadcastTChanIO
     -- Initialize our read models from stored events
@@ -138,6 +139,7 @@ withAPIServer config env party eventSource tracer chain pparams serverOutputFilt
                   tracer
                   chain
                   env
+                  stateFile
                   pparams
                   (atomically $ getLatest nodeStateP)
                   (atomically $ getLatest commitInfoP)

hydra-node/src/Hydra/Node/Run.hs

@@ -104,7 +104,7 @@ run opts = do
         withChain (chainStateHistory wetHydraNode) (wireChainInput wetHydraNode) $ \chain -> do
           -- API
           let apiServerConfig = APIServerConfig{host = apiHost, port = apiPort, tlsCertPath, tlsKeyPath, apiTransactionTimeout}
-          withAPIServer apiServerConfig env party eventSource (contramap APIServer tracer) chain pparams serverOutputFilter (wireClientInput wetHydraNode) $ \(apiSink, server) -> do
+          withAPIServer apiServerConfig env stateFile party eventSource (contramap APIServer tracer) chain pparams serverOutputFilter (wireClientInput wetHydraNode) $ \(apiSink, server) -> do
             -- Network
             let networkConfiguration =
                   NetworkConfiguration