Skip to content

Commit

Permalink
Re-flow api-log.yaml text blocks
Browse files Browse the repository at this point in the history
  • Loading branch information
@ch1bo
ch1bo committed Sep 24, 2021
1 parent 5770c15 commit cce9188
Showing 1 changed file with 68 additions and 49 deletions.
117 changes: 68 additions & 49 deletions hydra-node/api-log.yaml
View file
Expand Up @@ -2,11 +2,12 @@
"$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 Logs API
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.
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
Expand All @@ -17,14 +18,15 @@ properties:
namespace:
type: string
description: >-
An arbitrary string identifying the tracer generating this entry. For a node, this
is always 'HydraNode'.
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.
Timestamp denoting the wall-clock time at which this log entry was
recorded.
thread:
type: integer
Expand Down Expand Up @@ -52,8 +54,8 @@ properties:
- tag
- node
description: >-
A log entry denoting events and effects processed by the Node as part of the
Head protocol.
A log entry denoting events and effects processed by the Node as part
of the Head protocol.
properties:
tag:
type: string
Expand All @@ -68,8 +70,8 @@ definitions:
# 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.
Some error happened while processing an event, provides enough context
information to troubleshoot the origin of the error.
type: object
required:
- by
Expand All @@ -90,8 +92,8 @@ definitions:
$ref: "#/definitions/LogicError"
- title: ProcessingEvent
description: >-
Head has started processing an event drawn from some pool or queue of events to
process.
Head has started processing an event drawn from some pool or queue of
events to process.
type: object
required:
- by
Expand Down Expand Up @@ -137,8 +139,8 @@ definitions:
oneOf:
- title: APIServerStarted
description: >-
API Server has started and is ready, listening for incoming client connections
on given port.
API Server has started and is ready, listening for incoming client
connections on given port.
type: object
required:
- tag
Expand Down Expand Up @@ -202,24 +204,28 @@ definitions:
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.
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.
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.
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
Expand Down Expand Up @@ -253,8 +259,8 @@ definitions:
- tag
- onChainTx
description: >-
An event representing the confirmation that some transaction part of the Head protocol
has been confirmed on the main chain.
An event representing the confirmation that some transaction part of the
Head protocol has been confirmed on the main chain.
properties:
tag:
type: string
Expand All @@ -266,7 +272,8 @@ definitions:
required:
- tag
description: >-
An placeholder event denoting the Head should post a Fanout transaction to finalize the head.
An placeholder event denoting the Head should post a Fanout transaction
to finalize the head.
properties:
tag:
type: string
Expand All @@ -283,7 +290,8 @@ definitions:
- party
- transaction
description: >-
Request to sign some transaction and add it to the confirmed Head ledger.
Request to sign some transaction and add it to the confirmed Head
ledger.
properties:
tag:
type: string
Expand All @@ -300,7 +308,8 @@ definitions:
- snapshotNumber
- transactions
description: >-
Request from the current snapshot leader to sign some snapshot, eg. a bunch of transactions.
Request from the current snapshot leader to sign some snapshot, eg. a
bunch of transactions.
properties:
tag:
type: string
Expand Down Expand Up @@ -336,7 +345,8 @@ definitions:
type: string
contentEncoding: base16
description: >-
Signature from given party of the snapshot. The bytes representing the signature are hex-encoded.
Signature from given party of the snapshot. The bytes representing
the signature are hex-encoded.
- title: Connected
type: object
required:
Expand Down Expand Up @@ -365,9 +375,9 @@ definitions:
$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.
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
Expand All @@ -376,16 +386,17 @@ definitions:
- contestationPeriod
- parties
description: >-
The initial transaction of the Head, announcing various parameters and the parties, has been
posted on-chain.
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.
The length of the contestaion period, in seconds, represented as a
decimal number.
parties:
type: array
items:
Expand All @@ -397,7 +408,8 @@ definitions:
- party
- committed
description: >-
The commit transaction from a party, committing some UTxO set to the Head.
The commit transaction from a party, committing some UTxO set to the
Head.
properties:
tag:
type: string
Expand Down Expand Up @@ -454,9 +466,10 @@ ml#/definitions/Utxo"

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.
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
Expand All @@ -477,7 +490,8 @@ ml#/definitions/Utxo"
- tag
- message
description: >-
An effect representing some message to broadcast to other parties in the Head.
An effect representing some message to broadcast to other parties in the
Head.
properties:
tag:
type: string
Expand All @@ -490,8 +504,9 @@ ml#/definitions/Utxo"
- 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.
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
Expand All @@ -505,10 +520,11 @@ ml#/definitions/Utxo"
- 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.
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
Expand All @@ -523,9 +539,10 @@ ml#/definitions/Utxo"

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.
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
Expand Down Expand Up @@ -575,7 +592,8 @@ ml#/definitions/Utxo"
- tag
- utxos
description: >-
Confirm the opening of the Head collecting the committed UTxO set combined from all individual commits.
Confirm the opening of the Head collecting the committed UTxO set
combined from all individual commits.
properties:
tag:
type: string
Expand All @@ -601,7 +619,8 @@ ml#/definitions/Utxo"
- tag
- snapshot
description: >-
Contest a previously posted snapshot (from a Close or Contest transaction) with a newer snapshot.
Contest a previously posted snapshot (from a Close or Contest
transaction) with a newer snapshot.
properties:
tag:
type: string
Expand Down

0 comments on commit cce9188

Please sign in to comment.