HTTP chain observer (#1815)

Extends `hydra-chain-observer` to submit observations to a
`hydra-explorer` instance with the new observer API.

See
https://github.com/cardano-scaling/hydra-explorer/blob/observer-backend/README.md#architecture
for an architectural overview.

* 🔍 Adds `--explorer` option to `hydra-chain-observer` which submits
observations using HTTP. This uses the `OnChainTx` type, so there are
new roundtrip tests and golden files.
* 🔍 Make `hydra-chain-observer` aware of its `--version` (also via
embedding git revs using nix).
* 🔍 Switch on `--node-socket` or `--blockfrost-project-path` in
`hydra-chain-observer` instead of subcommands. This allows us to re-use
more code and the help text becomes easier to understand. See
hydra-chain-observer/README.md for how to invoke the binary now.

* 🔍 Extracts a `common.yaml` from API definitions so we can
reference it from `hydra-explorer` API specs / schemas
* 🔍 Moves observation code from `hydra-node` to `hydra-tx`, this
improves dependency closure for `hydra-explorer`, especially once we
move `Hydra.Chain` out of `hydra-node` (e.g. by inverting the dependency
of `hydra-chain-observer`?)
  - This requires
* Adds orphan instances to `hydra-cardano-api` as needed by the
`hydra-explorer`, see
cardano-scaling/hydra-explorer#18

TODO:
- [x] Client-side serialization tests against observer openapi

---

* [x] CHANGELOG updated
* [x] Documentation updated (README, no user guide)
* [x] Haddocks updated
* [x] No new TODOs

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 As a minor extension, we also keep a semantic version for the `UNRELEASED`
 changes.
 
+## [0.20.1] - UNRELEASED
+
+- Submit observations to a `hydra-explorer` via optional `--explorer` option.
+
 ## [0.20.0] - 2025-02-04
 
 - **BETA** hydra-node now supports incremental commits in beta mode. We would like to test out this feature

hydra-cardano-api/hydra-cardano-api.cabal

@@ -51,6 +51,7 @@ library
     Hydra.Cardano.Api.Hash
     Hydra.Cardano.Api.Network
     Hydra.Cardano.Api.NetworkId
+    Hydra.Cardano.Api.NetworkMagic
     Hydra.Cardano.Api.PolicyId
     Hydra.Cardano.Api.Prelude
     Hydra.Cardano.Api.Pretty

hydra-cardano-api/src/Hydra/Cardano/Api.hs

@@ -129,6 +129,7 @@ import Hydra.Cardano.Api.CtxTx as Extras
 import Hydra.Cardano.Api.ExecutionUnits as Extras
 import Hydra.Cardano.Api.Hash as Extras
 import Hydra.Cardano.Api.NetworkId ()
+import Hydra.Cardano.Api.NetworkMagic ()
 import Hydra.Cardano.Api.PolicyId as Extras
 import Hydra.Cardano.Api.ReferenceScript as Extras
 import Hydra.Cardano.Api.ScriptData as Extras

hydra-cardano-api/src/Hydra/Cardano/Api/NetworkId.hs

@@ -4,7 +4,9 @@ module Hydra.Cardano.Api.NetworkId where
 
 import Hydra.Cardano.Api.Prelude
 
-import Data.Aeson (Value (Number, String), object, withObject, (.:), (.=))
+import Data.Aeson (Value (String), object, withObject, (.:), (.=))
+import Hydra.Cardano.Api.NetworkMagic ()
+import Test.QuickCheck (oneof)
 
 -- * Orphans
 
@@ -14,13 +16,19 @@ instance ToJSON NetworkId where
     Testnet magic ->
       object
         [ "tag" .= String "Testnet"
-        , "magic" .= Number (fromIntegral $ unNetworkMagic magic)
+        , "magic" .= toJSON magic
         ]
 
 instance FromJSON NetworkId where
   parseJSON = withObject "NetworkId" $ \o -> do
     tag <- o .: "tag"
     case tag :: Text of
       "Mainnet" -> pure Mainnet
-      "Testnet" -> Testnet . NetworkMagic <$> o .: "magic"
+      "Testnet" -> Testnet <$> o .: "magic"
       _ -> fail "Expected tag to be Mainnet | Testnet"
+
+instance Arbitrary NetworkId where
+  arbitrary = oneof [pure Mainnet, Testnet <$> arbitrary]
+  shrink = \case
+    Mainnet -> []
+    Testnet magic -> Testnet <$> shrink magic

hydra-cardano-api/src/Hydra/Cardano/Api/NetworkMagic.hs

@@ -0,0 +1,19 @@
+{-# OPTIONS_GHC -Wno-orphans #-}
+
+module Hydra.Cardano.Api.NetworkMagic where
+
+import Cardano.Api (NetworkMagic (..))
+import Data.Aeson (FromJSON (..), ToJSON (..))
+import Test.QuickCheck (Arbitrary (..))
+
+-- * Orphans
+
+instance ToJSON NetworkMagic where
+  toJSON (NetworkMagic magic) = toJSON magic
+
+instance FromJSON NetworkMagic where
+  parseJSON = fmap NetworkMagic . parseJSON
+
+instance Arbitrary NetworkMagic where
+  arbitrary = NetworkMagic <$> arbitrary
+  shrink (NetworkMagic x) = NetworkMagic <$> shrink x

hydra-chain-observer/README.md

@@ -1,37 +1,40 @@
 # Hydra Chain Observer
 
 A lightweight executable designed to connect to a blockchain, such as the `hydra-node`, and streams chain observations as traces to `stdout`.
+
 It supports two modes of operation: **Direct** connection to a node via socket, and connection through **Blockfrost** API.
 
-## Direct Mode
+In both modes, reporting observations to a [`hydra-explorer`](https://github.com/cardano-scaling/hydra-explorer) can be enabled.
 
-To run the observer in Direct Mode, provide the following arguments:
-- `--node-socket`: path to the node socket file.
-- network id: `--testnet-magic` (with magic number) for the testnet or `--mainnet` for the mainnet.
-- (optional) `--start-chain-from`: specify a chain point (SLOT.HEADER_HASH) to start observing from.
+## Direct Mode
 
-For example:
+To run the observer directly connected to a `cardano-node`, use the `--node-socket` option and specify the network id via `--mainnet` or `--testnet-magic`. Optionally, you can specify a starting point to observe usin `--start-chain-from`:
 
 ``` shell
-hydra-chain-observer direct \
+hydra-chain-observer \
   --node-socket testnets/preprod/node.socket \
   --testnet-magic 1 \
   --start-chain-from "41948777.5d34af0f42be9823ebd35c2d83d5d879c5615ac17f7158bb9aa4ef89072455a7"
 ```
 
-
 ## Blockfrost Mode
 
-To run the observer in Blockfrost Mode, provide the following arguments:
-- `--project-path`: file path to your Blockfrost project API token hash.
-> expected to be prefixed with environment (e.g. testnetA3C2E...)
-- (optional) `--start-chain-from`: specify a chain point (SLOT.HEADER_HASH) to start observing from.
-
-For example:
+To run a chain observer using [blockfrost](blockfrost.io), use the `--blockfrost-project-path` option to point to a file containing your Blockfrost project API token (e.g. testnetA3C2E...). Optionally, you can specify a starting point to observe usin `--start-chain-from`:
 
 ``` shell
 hydra-chain-observer blockfrost \
-  --project-path $PROJECT_TOKEN_HASH_PATH \
+  --blockfrost-project-path $PROJECT_TOKEN_PATH \
   --start-chain-from "41948777.5d34af0f42be9823ebd35c2d83d5d879c5615ac17f7158bb9aa4ef89072455a7"
 ```
 
+## Report to hydra-explorer
+
+Using the `--explorer` argument we can specify a hostname / port for a `hydra-explorer` instance to report observations to. For example using a `direct` observer:
+
+``` shell
+hydra-chain-observer \
+  --node-socket testnets/preview/node.socket \
+  --testnet-magic 2 \
+  --start-chain-from "49533501.e364500a42220ea47314215679b7e42e9bbb81fa69d1366fe738d8aef900f7ee" \
+  --explorer http://0.0.0.0:8080
+```

hydra-chain-observer/exe/Main.hs

@@ -1,8 +1,8 @@
 module Main where
 
-import Hydra.ChainObserver qualified
-import Hydra.ChainObserver.NodeClient (defaultObserverHandler)
 import Hydra.Prelude
 
+import Hydra.ChainObserver qualified
+
 main :: IO ()
-main = Hydra.ChainObserver.main defaultObserverHandler
+main = Hydra.ChainObserver.main