observer-api.yaml

openapi: 3.0.3

info:
  title: Hydra Explorer - Observer API
  version: 1.1.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
      required:
        - point
        - blockNo
      properties:
        point:
          $ref: "https://raw.githubusercontent.com/cardano-scaling/hydra/master/hydra-node/json-schemas/common.yaml#definitions/ChainPoint"
        blockNo:
          type: integer
        observed:
          $ref: "#/components/schemas/HeadObservation"
        observedTx:
          description: "DEPRECATED: Legacy field for observations"
          nullable: true
          allOf:
          - $ref: "#/components/schemas/OnChainTx"

    HeadObservation:
      description: >-
        Hydra protocol transaction as observed by hydra-chain-observer.
      # TODO detail this
      type: object

    OnChainTx:
      description: >-
        Hydra protocol transaction as observed by the hydra-node.
      oneOf:
        - title: OnInitTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - headSeed
            - headParameters
            - participants
          description: >-
            The initial transaction of the Head, announcing various parameters and
            the parties, has been posted on-chain.
          properties:
            tag:
              type: string
              enum: ["OnInitTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            headSeed:
              $ref: "api.yaml#/components/schemas/HeadSeed"
            headParameters:
              $ref: "api.yaml#/components/schemas/HeadParameters"
            participants:
              type: array
              items:
                $ref: "api.yaml#/components/schemas/OnChainId"
        - title: OnDepositTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - deposited
            - depositTxId
            - deadline
          description: >-
            The deposit transaction locking some UTxO to a deposit script.
          properties:
            tag:
              type: string
              enum: ["OnDepositTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            deposited:
              $ref: "api.yaml#/components/schemas/UTxO"
            depositTxId:
              type: string
            deadline:
              $ref: "api.yaml#/components/schemas/UTCTime"
        - title: OnRecoverTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - recoveredTxId
            - recoveredUTxO
          description: >-
            The recover transaction unlocking the deposited UTxO.
          properties:
            tag:
              type: string
              enum: ["OnRecoverTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            recoveredTxId:
              $ref: "api.yaml#/components/schemas/TxId"
            recoveredUTxO:
              $ref: "api.yaml#/components/schemas/UTxO"
        - title: OnIncrementTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - newVersion
            - depositTxId
          description: >-
            The increment transaction adding some UTxO from L1 into the Head.
          properties:
            tag:
              type: string
              enum: ["OnIncrementTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            newVersion:
              $ref: "api.yaml#/components/schemas/SnapshotVersion"
            depositTxId:
              type: string
        - title: OnCommitTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - party
            - committed
          description: >-
            The commit transaction from a party, committing some UTxO set to the
            Head.
          properties:
            tag:
              type: string
              enum: ["OnCommitTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            party:
              $ref: "api.yaml#/components/schemas/Party"
            committed:
              $ref: "api.yaml#/components/schemas/UTxO"
        - title: OnAbortTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
          properties:
            tag:
              type: string
              enum: ["OnAbortTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
        - title: OnIncrementTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - newVersion
            - committedUTxO
            - depositScriptUTxO
          properties:
            tag:
              type: string
              enum: ["OnIncrementTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            newVersion:
              $ref: "api.yaml#/components/schemas/SnapshotVersion"
            committedUTxO:
              $ref: "api.yaml#/components/schemas/UTxO"
            depositScriptUTxO:
              $ref: "api.yaml#/components/schemas/UTxO"
        - title: OnDecrementTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - newVersion
            - distributedUTxO
          properties:
            tag:
              type: string
              enum: ["OnDecrementTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            newVersion:
              $ref: "api.yaml#/components/schemas/SnapshotVersion"
            distributedUTxO:
              $ref: "api.yaml#/components/schemas/UTxO"
        - title: OnCollectComTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
          properties:
            tag:
              type: string
              enum: ["OnCollectComTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
        - title: OnCloseTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - snapshotNumber
            - contestationDeadline
          properties:
            tag:
              type: string
              enum: ["OnCloseTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            snapshotNumber:
              type: integer
              minimum: 0
            contestationDeadline:
              $ref: "api.yaml#/components/schemas/UTCTime"
        - title: OnContestTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - snapshotNumber
            - contestationDeadline
          properties:
            tag:
              type: string
              enum: ["OnContestTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            snapshotNumber:
              type: integer
              minimum: 0
            contestationDeadline:
              $ref: "api.yaml#/components/schemas/UTCTime"
        - title: OnFanoutTx
          type: object
          additionalProperties: false
          required:
            - tag
            - headId
            - fanoutUTxO
          properties:
            tag:
              type: string
              enum: ["OnFanoutTx"]
            headId:
              $ref: "api.yaml#/components/schemas/HeadId"
            fanoutUTxO:
              $ref: "api.yaml#/components/schemas/UTxO"