Merge pull request #18 from cardano-scaling/observer-backend

Observer API backend

.github/workflows/ci-nix.yaml

@@ -41,7 +41,7 @@ jobs:
       run: |
         nix run .#apps.x86_64-linux.hydra-explorer -- --help
 
-        # Note: The tests need to find `json-schemas/hydra-explorer-api.yaml`;
+        # Note: The tests need to find `json-schemas/client-api.yaml`;
         # so they need to be run in this specific folder.
         cd hydra-explorer
 

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+As a minor extension, we also keep a semantic version for the `UNRELEASED`
+changes.
+
+## [1.0.0] - UNRELEASED
+
+- Create a [client](api/client-api.yaml) and [observer](api/observer-api.yaml) API specification.
+
+- Listen for observations on the observer API and aggregate them into the client API.

README.md

@@ -1,6 +1,79 @@
 # hydra-explorer
 
-This is the system image repository for the hydra-explorer service.
+Contains the backend and frontend serving https://explorer.hydra.family, as well as a NixOS-based system image to deploy the service.
+
+The backend `hydra-explorer` service aggregates data from multiple `hydra-chain-observer` instances - of different hydra versions and from different cardano networks - into a single REST API.
+
+## Getting started
+
+```shell
+hydra-explorer
+```
+
+By default, hydra-explorer will bind onto all interfaces using hostname `0.0.0.0` and uses port `8080` for the **observer API** and port `9090` for the **client API**. To configure:
+
+```shell
+hydra-explorer \
+  --observer-port 8000
+  --client-port 9000
+```
+
+
+## Architecture
+
+Multiple instances of `hydra-chain-observer`, each built against a specific version of the `hydra-plutus` scripts and `hydra-tx` off-chain (transaction structure), is reporting its observations to a single `hydra-explorer` instance via an [HTTP REST api](./api/observer-api.yaml).
+
+``` mermaid
+flowchart LR
+
+  subgraph hydra 0.19.0
+    plutus-19[hydra-plutus]
+    tx-19[hydra-tx]
+    node-19[hydra-node]
+    observer-19-preview[hydra-chain-observer 0.19.0]
+    plutus-19 --> tx-19
+    tx-19 --> observer-19-preview
+    tx-19 --> node-19
+    node-19 --> observer-19-preview
+  end
+  preview -. chain sync .-> observer-19-preview
+
+  subgraph hydra 0.20.0
+    plutus-20[hydra-plutus]
+    tx-20[hydra-tx]
+    node-20[hydra-node]
+    observer-20[hydra-chain-observer 0.20.0]
+    plutus-20 --> tx-20
+    tx-20 --> observer-20
+    tx-20 --> node-20
+    node-20 --> observer-20
+  end
+  mainnet -. chain sync .-> observer-20
+
+  observer-19[hydra-chain-observer 0.19.0]
+  mainnet -. chain sync .-> observer-19
+
+  subgraph hydra-explorer 1.0.0
+    explorer[hydra-explorer]
+    explorer -. GET /heads .-> hydra-explorer-web
+  end
+
+  observer-19-preview -. POST /v1/observations/preview/19 .-> explorer
+  observer-19 -. POST /v1/observations/mainnet/19 .-> explorer
+  observer-20 -. POST /v1/observations/mainnet/20 .-> explorer
+```
+
+Clients to the explorer can then use the [Client REST API](../api/client-api.yaml) to query `/heads` for example.
+
+## Build & test
+
+In the `nix develop` shell or with `cabal` and `ghc` installed:
+
+``` sh
+cabal update
+cabal build
+cabal test
+```
 
 ## Deployment
 

hydra-explorer/json-schemas/hydra-explorer-api.yaml → api/client-api.yaml

@@ -1,26 +1,28 @@
 openapi: 3.0.0
 info:
-  title: Head Explorer API
+  title: Head Explorer Client API
   version: 1.0.0
+  description: |-
+    API to be used by clients to query information from a hydra-explorer instance.
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+externalDocs:
+  description: More information about the Hydra protocol
+  url: http://hydra.family
 paths:
-  /tick:
+  /ticks:
     get:
-      summary: Get the latest point in time obseverd on chain by the explorer
+      summary: Get a list of points in time obseverd on chain by the explorer
       responses:
         '200':
           description: Successful response
           content:
             application/json:
               schema:
-                type: object
-                required:
-                  - point
-                  - blockNo
-                properties:
-                  point:
-                    $ref: '#/components/schemas/ChainPoint'
-                  blockNo:
-                    type: integer
+                type: array
+                items:
+                  $ref: '#/components/schemas/TickState'
   /heads:
     get:
       summary: Get a list of head states
@@ -217,14 +219,29 @@ components:
               type: integer
             blockHash:
               type: string
+    Network:
+      $ref: "https://raw.githubusercontent.com/CardanoSolutions/cardanonical/refs/heads/main/cardano.json#definitions/Network"
+    NetworkMagic:
+      $ref: "https://raw.githubusercontent.com/CardanoSolutions/cardanonical/refs/heads/main/cardano.json#definitions/NetworkMagic"
+    HydraVersion:
+      $ref: "https://raw.githubusercontent.com/cardano-scaling/hydra/master/hydra-node/json-schemas/common.yaml#definitions/HydraVersion"
     HeadState:
       type: object
       required:
+        - network
+        - networkMagic
+        - version
         - headId
         - status
         - point
         - blockNo
       properties:
+        network:
+          $ref: "#/components/schemas/Network"
+        networkMagic:
+          $ref: "#/components/schemas/NetworkMagic"
+        version:
+          $ref: "#/components/schemas/HydraVersion"
         headId:
           $ref: '#/components/schemas/HeadId'
         seedTxIn:
@@ -250,3 +267,19 @@ components:
           $ref: '#/components/schemas/ChainPoint'
         blockNo:
           type: integer
+    TickState:
+      type: object
+      required:
+        - network
+        - networkMagic
+        - point
+        - blockNo
+      properties:
+        network:
+          $ref: "#/components/schemas/Network"
+        networkMagic:
+          $ref: "#/components/schemas/NetworkMagic"
+        point:
+          $ref: '#/components/schemas/ChainPoint'
+        blockNo:
+          type: integer

api/observer-api.yaml

@@ -0,0 +1,74 @@
+openapi: 3.0.3
+
+info:
+  title: Hydra Explorer - Observer API
+  version: 1.0.0
+  description: |-
+    API to be used by hydra-chain-observer instances to report observations of Hydra Head transactions to a hydra-explorer instance.
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+
+externalDocs:
+  url: http://hydra.family
+  description: More information about the Hydra protocol
+
+servers:
+  - url: "http://{host}:{port}"
+    variables:
+      host:
+        default: "localhost"
+      port:
+        default: "8080"
+
+paths:
+  /observations/{network}/{version}:
+    post:
+      summary: Submit a new Hydra Head protocol observation from given network and protocol version
+      operationId: postObservations
+      parameters:
+        - in: path
+          name: network
+          schema:
+            oneof:
+              - title: Mainnet
+                type: string
+                enum: ["mainnet"]
+              - title: Network magic
+                $ref: "#/components/schemas/NetworkMagic"
+          required: true
+          description: |
+            Cardano network on which the observation was made. Identified by the string "mainnet" or the network magic number. For example 764824073 for mainnet or 1 for preprod.
+        - in: path
+          name: version
+          schema:
+            $ref: "#/components/schemas/HydraVersion"
+          required: true
+          description: Semantic version of the observer, currently corresponding to hydra protocol version.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Observation"
+        required: true
+      responses:
+        "200":
+          description: Successful reported observation
+        "400":
+          description: Invalid observation
+
+components:
+  schemas:
+    NetworkMagic:
+      $ref: "https://raw.githubusercontent.com/CardanoSolutions/cardanonical/refs/heads/main/cardano.json#definitions/NetworkMagic"
+    HydraVersion:
+      $ref: "https://raw.githubusercontent.com/cardano-scaling/hydra/master/hydra-node/json-schemas/common.yaml#definitions/HydraVersion"
+    Observation:
+      type: object
+      properties:
+        point:
+          $ref: "https://raw.githubusercontent.com/cardano-scaling/hydra/master/hydra-node/json-schemas/common.yaml#definitions/ChainPoint"
+        blockNo:
+          type: integer
+        observedTx:
+          $ref: "https://raw.githubusercontent.com/cardano-scaling/hydra/master/hydra-node/json-schemas/common.yaml#definitions/OnChainTx"

cabal.project

@@ -9,25 +9,29 @@ repository cardano-haskell-packages
     c00aae8461a256275598500ea0e187588c35a5d5d7454fb57eac18d9edb86a56
     d4a35cd3121aa00d18544bb0ac01c3e1691d618f462c46129271bccf39f7e8ee
 
+-- Using same index-state as hydra (as packages are lacking upper bounds)
 index-state:
-  , hackage.haskell.org 2024-10-14T02:12:15Z
-  , cardano-haskell-packages 2024-10-14T23:19:53Z
+  , hackage.haskell.org 2025-01-15T13:32:16Z
+  , cardano-haskell-packages 2025-01-15T09:59:24Z
 
 packages:
   hydra-explorer
 
+-- XXX: We could avoid the s-r-p by publishing these to chap. However, not all
+-- of them should be needed (e.g. hydra-plutus, hydra-tx and hydra-node)
 source-repository-package
   type: git
   location: https://github.com/cardano-scaling/hydra
-  tag: d55c4efb896273dc39d4bdc4fc83ec361de55f73
-  --sha256: sha256-LziIjrdjMA8dVPKMwKskLyjlnx5HhpDwTjC9sek5Bfo=
+  -- 0.20.0 + http-chain-observer work
+  tag: cf09cb053a29800779f8024e9eaec7d88a3dfc7c
+  --sha256: sha256-2v7K8il2Nq1MCeHpjkURp0uKSWFsUBnKOdMdrWZGkkw=
   subdir:
-    hydra-cardano-api
-    hydra-chain-observer
-    hydra-cluster
-    hydra-node 
-    hydra-plutus
-    hydra-plutus-extras
     hydra-prelude
     hydra-test-utils
+    hydra-cardano-api
+    hydra-plutus-extras
+    hydra-plutus
     hydra-tx
+    hydra-node
+    -- Needed for integration tests
+    hydra-cluster