Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs review: Developer documentation #1492

Merged
merged 5 commits into from
Jul 22, 2024
+103 −118
Merged

Docs review: Developer documentation #1492

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4794ab9
Revision of 'Developer documentation'
olgahryniuk Jul 10, 2024
0c216f3
Update index.md (architecture)
olgahryniuk Jul 10, 2024
78f2978
Update networking.md
olgahryniuk Jul 10, 2024
8b55fb8
Update index.md (handling rollbacks)
olgahryniuk Jul 10, 2024
1f9ae2c
Update haskell-packages.md
olgahryniuk Jul 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 20 additions & 36 deletions docs/docs/dev/architecture/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Architecture

This document describes the architecture of the current implementation
of a `hydra-node`. The following picture represents the main
of a `hydra-node`. The following diagram represents the main
components of a Hydra node using the [C4 Component
Diagram](https://c4model.com/#ComponentDiagram) notation.

Expand All @@ -13,7 +13,7 @@ import ArchitectureSvg from './hydra-components.svg';

:::info

This diagram is manually produced using [PlantUML](https://plantuml.com) graphing tool with [C4 extensions](https://github.com/plantuml-stdlib/C4-PlantUML).
This diagram is manually produced using the [PlantUML](https://plantuml.com) graphing tool with [C4 extensions](https://github.com/plantuml-stdlib/C4-PlantUML).

```
$ plantuml -Tsvg architecture-c4.puml
Expand All @@ -23,67 +23,51 @@ $ plantuml -Tsvg architecture-c4.puml

### Network

_Network_ component is responsible for all of the communications related to the off-chain part of the Hydra protocol between hydra-nodes. The [current implementation](./networking) is based on the [Typed Protocols](https://github.com/input-output-hk/typed-protocols) library which is also at the heart of the Cardano node's networking. It's asynchronous by nature and is using a push based protocol with a uniform _broadcast_ abstraction.
The _network_ component is responsible for all communications between Hydra nodes related to the off-chain part of the Hydra protocol. The [current implementation](./networking) is based on the [typed protocols](https://github.com/input-output-hk/typed-protocols) library, which is also used by the Cardano networking. It is asynchronous by nature and uses a push-based protocol with a uniform _broadcast_ abstraction.

Messages are exchanged between nodes on different internal transitions and are authenticated using each peer _Hydra Key_: Each message sent is signed by the emitter and the signature is verified by the transmitter.
Messages are exchanged between nodes during different internal transitions and are authenticated using each peer's _Hydra key_. Each message sent is signed by the sender, and the signature is verified by the receiver.

##### Authentication & Authorization
#### Authentication and authorization

The messages exchanged through the _Hydra Network_ layer between
participants are authenticated: Each message is
[signed](https://github.com/cardano-scaling/hydra/issues/727) using
the Hydra signing key of the emitting party which is identified by
the corresponding verification key. When a message with an unknown
or incorrect signature is received, it is dropped and a notification
is logged.
The messages exchanged through the _Hydra networking_ layer between participants are authenticated. Each message is [signed](https://github.com/input-output-hk/hydra/issues/727) using the Hydra signing key of the emitting party, which is identified by the corresponding verification key. When a message with an unknown or incorrect signature is received, it is dropped, and a notification is logged.

Messages are however not encrypted and therefore, if confidentiality is
required, some external mechanism needs to be put in place to prevent
other parties from observing the messages exchanged within a Head.
However, messages are not encrypted. If confidentiality is required, an external mechanism must be implemented to prevent other parties from observing the messages exchanged within a head.

##### Fault tolerance
#### Fault tolerance

The Hydra Head protocol guarantees safety of all (honest)
participants' funds, but does not in itself guarantee liveness, hence
all parties involved in a Hydra Head must be online and reactive for
the protocol to make progress.
The Hydra Head protocol guarantees the safety of all honest participants' funds but does not inherently guarantee liveness. Therefore, for the protocol to progress, all parties involved in a head must be online and reactive.

This implies that, should one or several participants' hydra-node
become _permanently_ unreachable from the others, through a crash, or
a network partition, no more transactions can happen in the Head and
it must be closed. However, the [Hydra network
layer](https://hydra.family/head-protocol/unstable/haddock/hydra-node/Hydra-Node-Network.html)
is tolerant to _transient_ disconnections and (non-Byzantine) crashes.
This means that if one or more participants' Hydra nodes become permanently unreachable due to a crash or network partition, no further transactions can occur in the head, and it must be closed. However, the [Hydra networking layer](https://hydra.family/head-protocol/unstable/haddock/hydra-node/Hydra-Node-Network.html) is tolerant to transient disconnections and (non-Byzantine) crashes.

### Chain Interaction
### Chain interaction

#### Chain

The _Chain_ component is responsible for interfacing the Hydra node with the Cardano (aka. Layer 1) chain. The current, so-called `Direct`, implementation uses the `Node-to-Client` protocol to both "follow the chain" and observe new blocks and transactions which can change the state of the head, and submit transactions in response to client's requests or as needed to advance the protocol's state. It connects to a locally spun cardano-node using the _local socket_and contains the \_off-chain_ logic, based on cardano-api, that knows how to observe and build transactions relevant to the Hydra protocol. See [ADR-10](/adr/10) for more details.
The _chain_ component interfaces the Hydra node with the Cardano (layer 1) chain. The current implementation, called `Direct`, uses the `node-to-client` protocol to both 'follow the chain' and observe new blocks and transactions that can change the state of the head. It also submits transactions in response to client requests or as needed to advance the protocol's state. This component connects to a locally spun `cardano-node` using the _local socket_ and contains the _off-chain_ logic, based on `cardano-api`, which knows how to observe and build transactions relevant to the Hydra protocol. For more details, see [ADR-10](/adr/10).

#### Wallet

The Hydra node maintains an internal wallet using the Cardano signing key provided to the `hydra-node`. This is used to handle the payment of transaction fees and signing transactions.
The Hydra node maintains an internal wallet using the Cardano signing key provided to the `hydra-node`. This wallet is used to handle the payment of transaction fees and to sign transactions.

### Head Logic
### Head logic

This is the component which is the heart of the Hydra node, implementing the protocol's _state machine_. It is structured around the concepts of `Input`s and `Effect`s: `Input`s from the outside world are interpreted against the current state, this may result in internal `Event`s, which are aggregated into an updated state, and `Effect`s which result in "side-effects" on the outside world. The state available to the _Head Logic_ consists of both, the content of the Head itself (eg. current Ledger, transactions pending) _and_ the data from the Layer 1 that's needed to observe and trigger on-chain transitions.
This component is at the core of the Hydra node, implementing the protocol's _state machine_. It is structured around the concepts of `Input`s and `Effect`s. `Input`s from the outside world are interpreted against the current state, potentially resulting in internal `Event`s, which are aggregated into an updated state. This can then produce `Effect`s, leading to 'side effects' on the outside world. The state available to the _head logic_ consists of the head's content (eg, current ledger, pending transactions) _and_ the data from layer 1 needed to observe and trigger on-chain transitions.

### Hydra Smart Contracts
### Hydra smart contracts

This "component" represents all of the Hydra smart contracts needed for Head protocol operation. Currently the contracts are written using `Plutus-Tx`. The scripts are optimized using custom `ScriptContext` and error codes for now.
This component represents all the Hydra smart contracts needed for the Hydra Head protocol operation. Currently, the contracts are written using `Plutus-Tx`. The scripts are optimized using a custom `ScriptContext` and specific error codes.

### API

`hydra-node` exposes an [Asynchronous API](https://hydra.family/head-protocol/unstable/api-reference) through a Websocket server. This API is available to _Hydra Client_ to send commands and observe changes in the state of the Hydra head. Upon startup, the API server loads all historical messages from persistence layer and serves them to clients in case they are interested in observing them.
The `hydra-node` component exposes an [asynchronous API](https://hydra.family/head-protocol/unstable/api-reference) through a WebSocket server. This API is available to the _Hydra client_ for sending commands and observing changes in the state of the Hydra head. Upon startup, the API server loads all historical messages from the persistence layer and serves them to clients interested in observing them.

### Persistence

All API server outputs and the `hydra-node` state is preserved on disk. The persistence layer is responsible for loading the historical messages/hydra state from disk and also storing them. For the time being there was no need to make this layer more complex or use a database.
All API server outputs and the `hydra-node` state are preserved on disk. The persistence layer is responsible for loading historical messages and the Hydra state from disk, as well as storing them. Currently, there hasn't been a need to increase the complexity of this layer or use a database.

### Logging

The Hydra node logs all side-effects occurring internally as JSON-formatted messages to the _standard output_ stream attached to its process. The format of the logs is documented as a [JSON schema](https://raw.githubusercontent.com/input-output-hk/hydra/master/hydra-node/json-schemas/logs.yaml), and follows the principles outlined in [ADR-9](/adr/9).
The Hydra node logs all internal side effects as JSON-formatted messages to its _standard output_ stream. The log format adheres to a documented [JSON schema](https://raw.githubusercontent.com/input-output-hk/hydra/master/hydra-node/json-schemas/logs.yaml), following the principles outlined in [ADR-9](/adr/9).

### Monitoring

Expand Down
Loading