api-log.yaml

---
"$schema": http://json-schema.org/draft/2020-12/schema
"$id": https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/docs/api-log.json
"$comment": A description of the log items produced by a Hydra node
title: Hydra Log API
description: >
  This schema documents the structure of the Log items produced by a Hydra node
  via its standard output stream. Items are emitted as individual JSON objects,
  separated by a newline which makes it easy to ingest by thirdparty tools and
  services.

required:
- namespace
- timestamp
- thread
- message
properties:
  namespace:
    type: string
    description: >-
      An arbitrary string identifying the tracer generating this entry. For a
      node, this is always 'HydraNode'.

  timestamp:
    type: string
    format: "date-time"
    description: >-
      Timestamp denoting the wall-clock time at which this log entry was
      recorded.

  thread:
    type: integer
    description: >-
      The id of the thread which produced the log entry.

  message:
    oneOf:
      - title: APIServer
        type: object
        required:
        - tag
        - api
        description: >-
          A log entry produced by the API server.
        properties:
          tag:
            type: string
            enum: ["APIServer"]
          api:
            $ref: "#/definitions/APIServer"
      - title: Node
        type: object
        required:
        - tag
        - node
        description: >-
          A log entry denoting events and effects processed by the Node as part
          of the Head protocol.
        properties:
          tag:
            type: string
            enum: ["Node"]
          node:
            $ref: "#/definitions/Node"

definitions:
  Node:
    oneOf:
    - title: ErrorHandlingEvent
      # This should be removed from the Log's description as soon as we have some proper
      # error handling strategy in place, be it simply "Close the head" and bail out.
      description: >-
        Some error happened while processing an event, provides enough context
        information to troubleshoot the origin of the error.
      type: object
      required:
      - by
      - event
      - reason
      properties:
        by:
          description: >-
            The Party emitting the log entry.
          $ref: "#/definitions/Party"
        event:
          description: >-
            The event causing the error.
          $ref: "#/definitions/Event"
        reason:
          description: >-
            Structured description of the cause of the error.
          $ref: "#/definitions/LogicError"
    - title: ProcessingEvent
      description: >-
        Head has started processing an event drawn from some pool or queue of
        events to process.
      type: object
      required:
      - by
      - event
      properties:
        by:
          description: >-
            The Party emitting the log entry.
          $ref: "#/definitions/Party"
        event:
          $ref: "#/definitions/Event"
    - title: ProcessedEvent
      description: >-
        Head has succesfully finished processing an event.
      type: object
      required:
      - by
      - event
      properties:
        by:
          description: >-
            The Party emitting the log entry.
          $ref: "#/definitions/Party"
        event:
          $ref: "#/definitions/Event"
    - title: ProcessingEffect
      description: >-
        Head has started processing an effect produced by some transition in the
        protocol.
      type: object
      required:
      - by
      - effect
      properties:
        by:
          description: >-
            The Party emitting the log entry.
          $ref: "#/definitions/Party"
        event:
          $ref: "#/definitions/Effect"

  APIServer:
    oneOf:
    - title: APIServerStarted
      description: >-
        API Server has started and is ready, listening for incoming client
        connections on given port.
      type: object
      required:
      - tag
      - listeningPort
      properties:
        tag:
          type: string
          enum: ["APIServerStarted"]
        listeningPort:
          type: integer
          minimum: 0
          maximum: 65535
    - title: NewAPIConnection
      description: >-
        A new client has connected to the API Server.
      required:
      - tag
      properties:
        tag:
          type: string
          enum: ["NewAPIConnection"]
    - title: APIOutputSent
      description: >-
        Some output has been sent to a client.
      required:
      - tag
      - sentOutput
      properties:
        tag:
          type: string
          enum: ["APIOutputSent"]
        sentOutput:
          type: object
    - title: APIInputReceived
      description: >-
        Some input has been received from a client.
      required:
      - tag
      - receivedInput
      properties:
        tag:
          type: string
          enum: ["APIInputReceived"]
        receivedInput:
          type: object
    - title: APIInvalidInput
      description: >-
        Some input sent by a client is invalid.
      required:
      - tag
      - reason
      - inputReceived
      properties:
        tag:
          type: string
          enum: ["APIInvalidInput"]
        reason:
          type: string
          description: >-
            A textual description of the reason why this input is invalid.
        inputReceived:
          type: string
          description: >-
            A rendering in text of the input received. This input is invalid
            hence it's potentially invalid JSON so we just encode it as a proper
            JSON string. Note that if the input contained invalid UTF-8
            characters they will be ignored.
  Party:
    type: integer
    # Signing is currently implemented using mock crypto hence party is just an integer
    description: >-
      The verification key for some Party in the Head protocol, uniquely
      identifying it.
    examples:
      - 10
      - 20
      - 30

  Event:
    description: >-
      Events (with Effects) are the atomic elements of the Hydra Head protocol
      which is basically a state-machine consuming events and producing effects.
      Events can come from different sources representing the various components
      a Head needs to interact with: Clients, other peers through the Network,
      main Chain.
    oneOf:
    - title: ClientEvent
      type: object
      required:
      - tag
      - clientInput
      description: >-
        An event representing some input from a client.
      properties:
        tag:
          type: string
          enum: ["ClientEvent"]
        clientInput:
          $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/ClientInput"
    - title: NetworkEvent
      type: object
      required:
      - tag
      - message
      description: >-
        An event representing some message received from peers in the network.
      properties:
        tag:
          type: string
          enum: ["NetworkEvent"]
        message:
          $ref: "#/definitions/Message"
    - title: OnChainEvent
      type: object
      required:
      - tag
      - onChainTx
      description: >-
        An event representing the confirmation that some transaction part of the
        Head protocol has been confirmed on the main chain.
      properties:
        tag:
          type: string
          enum: ["OnChainEvent"]
        onChainTx:
          $ref: "#/definitions/OnChainTx"
    - title: ShouldPostFanout
      type: object
      required:
      - tag
      description: >-
        An placeholder event denoting the Head should post a Fanout transaction
        to finalize the head.
      properties:
        tag:
          type: string
          enum: ["ShouldPostFanout"]

  Message:
    description: >-
      Messages exchanged by Hydra network peers over a broadcasting network.
    oneOf:
      - title: ReqTx
        type: object
        required:
        - tag
        - party
        - transaction
        description: >-
          Request to sign some transaction and add it to the confirmed Head
          ledger.
        properties:
          tag:
            type: string
            enum: ["ReqTx"]
          party:
            $ref: "#/definitions/Party"
          transaction:
            $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/Transaction"
      - title: ReqSn
        type: object
        required:
        - tag
        - party
        - snapshotNumber
        - transactions
        description: >-
          Request from the current snapshot leader to sign some snapshot, eg. a
          bunch of transactions.
        properties:
          tag:
            type: string
            enum: ["ReqSn"]
          party:
            $ref: "#/definitions/Party"
          snapshotNumber:
            type: integer
            minimum: 0
          transactions:
            type: array
            items:
              $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/Transaction"
      - title: AckSn
        type: object
        required:
        - tag
        - party
        - signed
        - snapshotNumber
        description: >-
          Signature of a snapshot by a party.
        properties:
          tag:
            type: string
            enum: ["AckSn"]
          party:
            $ref: "#/definitions/Party"
          snapshotNumber:
            type: integer
            minimum: 0
          signed:
            type: string
            contentEncoding: base16
            description: >-
              Signature from given party of the snapshot. The bytes representing
              the signature are hex-encoded.
      - title: Connected
        type: object
        required:
        - tag
        - party
        description: >-
          Given party is known to be connected to the network.
        properties:
          tag:
            type: string
            enum: ["Connected"]
          party:
            $ref: "#/definitions/Party"
      - title: Disconnected
        type: object
        required:
        - tag
        - party
        description: >-
          Given party is probably disconnected from the network.
        properties:
          tag:
            type: string
            enum: ["Disconnected"]
          party:
            $ref: "#/definitions/Party"
  OnChainTx:
    description: >-
      On-Chain transactions for the Head protocol. These data structures
      completely abstract away the actual structure of the transaction and only
      represent the data relevant for the protocol to make some progress.
    oneOf:
      - title: OnInitTx
        type: object
        required:
        - tag
        - contestationPeriod
        - parties
        description: >-
          The initial transaction of the Head, announcing various parameters and
          the parties, has been posted on-chain.
        properties:
          tag:
            type: string
            enum: ["OnInitTx"]
          contestationPeriod:
            type: number
            description: >-
              The length of the contestaion period, in seconds, represented as a
              decimal number.
          parties:
            type: array
            items:
              $ref: "#/definitions/Party"
      - title: OnCommitTx
        type: object
        required:
        - tag
        - party
        - committed
        description: >-
          The commit transaction from a party, committing some UTxO set to the
          Head.
        properties:
          tag:
            type: string
            enum: ["OnCommitTx"]
          party:
            $ref: "#/definitions/Party"
          committed:
            $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.ya
ml#/definitions/Utxo"
      - title: OnAbortTx
        type: object
        required:
        - tag
        properties:
          tag:
            type: string
            enum: ["OnAbortTx"]
      - title: OnCollectComTx
        type: object
        required:
        - tag
        properties:
          tag:
            type: string
            enum: ["OnCollectComTx"]
      - title: OnCloseTx
        type: object
        required:
        - tag
        - snapshotNumber
        properties:
          tag:
            type: string
            enum: ["OnCloseTx"]
          snapshotNumber:
            type: integer
            minimum: 0
      - title: OnContestTx
        type: object
        required:
        - tag
        properties:
          tag:
            type: string
            enum: ["OnContestTx"]
      - title: OnFanoutTx
        type: object
        required:
        - tag
        properties:
          tag:
            type: string
            enum: ["OnFanoutTx"]

  Effect:
    description: >-
      Effects are the outcome of Head protocol processing Events. Each Effect
      represents a message that needs to be sent somewhere, either to clients
      for notification purpose, to other heads, or to the chain as part of the
      protocol.
    oneOf:
    - title: ClientEffect
      type: object
      required:
      - tag
      - serverOutput
      description: >-
        An effect representing some output to send to the client.
      properties:
        tag:
          type: string
          enum: ["ClientEffect"]
        clientInput:
          $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/ServerOutput"
    - title: NetworkEffect
      type: object
      required:
      - tag
      - message
      description: >-
        An effect representing some message to broadcast to other parties in the
        Head.
      properties:
        tag:
          type: string
          enum: ["NetworkEffect"]
        message:
          $ref: "#/definitions/Message"
    - title: OnChainEffect
      type: object
      required:
      - tag
      - onChainTx
      description: >-
        An effect representing some transaction must be posted on-chain. Note
        that incoming transactions are represented by OnChainEvent which can be
        different from outgoing transactions.
      properties:
        tag:
          type: string
          enum: ["OnChainEffect"]
        onChainTx:
          $ref: "#/definitions/PostChainTx"
    - title: Delay
      type: object
      required:
      - tag
      - delay
      - event
      description: >-
        A special effect requesting the given event to be delayed from
        processing for some amount of time. Delays can happen in the protocol
        because messages can be received out-of-order due to the asynchronous
        nature of the network, hence an otherwise invalid event could become
        invalid in the future.
      properties:
        tag:
          type: string
          enum: ["Delay"]
        delay:
          type: number
          minimum: 0
          description: >-
            The length of the delay, in seconds.
        event:
          $ref: "#/definitions/Event"

  PostChainTx:
    description: >-
      Description of outgoing On-Chain transactions for the Head protocol. As is
      the case for OnChainTx, these data structures completely abstract away the
      actual details of the transaction and only represent data relevant for the
      protocol to make some progress.
    oneOf:
      - title: InitTx
        type: object
        required:
        - tag
        - headParameters
        description: >-
          The initial transaction of the Head defining its parameters.
        properties:
          tag:
            type: string
            enum: ["InitTx"]
          headParameters:
            $ref: "#/definitions/HeadParameters"
      - title: CommitTx
        type: object
        required:
        - tag
        - party
        - committed
        description: >-
          Commit some UTxO set to the opening Head, signed by this party.
        properties:
          tag:
            type: string
            enum: ["CommitTx"]
          party:
            $ref: "#/definitions/Party"
          committed:
            $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/Utxo"
      - title: AbortTx
        type: object
        required:
        - tag
        - utxos
        description: >-
          Abort the opening of the Head process.
        properties:
          tag:
            type: string
            enum: ["AbortTx"]
          committed:
            $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/Utxo"
      - title: CollectComTx
        type: object
        required:
        - tag
        - utxos
        description: >-
          Confirm the opening of the Head collecting the committed UTxO set
          combined from all individual commits.
        properties:
          tag:
            type: string
            enum: ["CollectComTx"]
          utxos:
            $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/Utxo"
      - title: CloseTx
        type: object
        required:
        - tag
        - snapshot
        description: >-
          Close the currently open Head with the given snapshot.
        properties:
          tag:
            type: string
            enum: ["CloseTx"]
          snapshot:
            $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/Snapshot"
      - title: ContestTx
        type: object
        required:
        - tag
        - snapshot
        description: >-
          Contest a previously posted snapshot (from a Close or Contest
          transaction) with a newer snapshot.
        properties:
          tag:
            type: string
            enum: ["ContestTx"]
          snapshot:
            $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/Snapshot"
      - title: FanoutTx
        type: object
        required:
        - tag
        - utxos
        description: >-
          Finalise the Head posting all UTxO from the Head on-chain.
        properties:
          tag:
            type: string
            enum: ["FanoutTx"]
          utxos:
            $ref: "https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/hydra-node/api.yaml#/definitions/Utxo"