You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
21
22
22
-
###Compatibility
23
+
## Compatibility
23
24
24
25
| hydra-sdk | hydra-node | cardano-node |
25
26
| ----------- | ------------ | ------------ |
26
27
|**`0.1.0`**|**`0.19.0`**|**`10.1.2`**|
27
28
28
-
### Applications
29
-
30
-
Please refer to [hydra-auction-offchain](https://github.com/mlabs-haskell/hydra-auction-offchain)
31
-
for a full-fledged example that utilizes this SDK.
32
29
33
-
###Preliminaries
30
+
## Preliminaries
34
31
35
32
Since using this SDK implies a certain degree of understanding of the Hydra
36
33
protocol, it is advisable to get familiar with the ["Hydra: Fast Isomorphic State Channels" paper](https://iohk.io/en/research/library/papers/hydra-fast-isomorphic-state-channels/)
37
34
and the [Hydra Head protocol documentation](https://hydra.family/head-protocol/docs/)
38
35
before proceeding with the **Getting Started** guide below.
39
36
40
-
### Getting Started
37
+
## Development Workflows
38
+
39
+
Before executing most of the commands listed below, first enter the Nix
40
+
development shell by running `nix develop`.
41
+
42
+
***Build docs and open them in the browser**: `make docs`
43
+
***Build the project**: `make build`
44
+
***Format code**: `make format`
45
+
46
+
## Getting Started with Example
41
47
42
48
The simplest way to get a sense of how this SDK can help build Hydra-based
43
49
applications is to run our minimal example and then adapt or extend it to suit
44
-
your specific requirements. Follow the step-by-step guide below to spin up
50
+
your specific requirements.
51
+
52
+
Go to `example/minimal` and follow the step-by-step guide below to spin up
45
53
a cluster of two nodes, with each node running the minimal example logic.
46
54
47
55
1. Enter the Nix development environment by running `nix develop` from the root
@@ -51,38 +59,45 @@ necessary executables required to continue with the setup procedure.
51
59
2. In [example/minimal/docker/cluster/](example/minimal/docker/cluster/) you
52
60
can find configuration files for both nodes. The only field that needs to be
53
61
updated here is the `blockfrostApiKey`, which should be set to a valid
54
-
Blockfrost API key **for preprod**. Visit the [Blockfrost website](https://blockfrost.io/)
55
-
to generate a fresh API key.
62
+
Blockfrost API key **for preprod**.
63
+
Visit the [Blockfrost website](https://blockfrost.io/)to generate a fresh API key.
56
64
57
65
3. Execute `make gen-keys` to generate the necessary Cardano and Hydra keys
58
66
required by the underlying Hydra nodes. Cardano keys are used to authenticate
59
67
on-chain transactions, while the Hydra keys are used for multi-signing snapshots
60
68
within a Hydra Head. This command will output two Cardano preprod addresses
61
69
that must be pre-funded with sufficient tADA to run properly functioning Hydra
62
-
nodes. Use the [Testnets faucet](https://docs.cardano.org/cardano-testnets/tools/faucet/)
70
+
nodes.
71
+
Use the [Testnets faucet](https://docs.cardano.org/cardano-testnets/tools/faucet/)
63
72
to request tADA.
64
73
65
-
4. Finally, execute `make run-example` to launch a Hydra Head with two
66
-
participants running the minimal example logic.
74
+
4. Finally, execute `make run-example` to launch a Hydra Head
75
+
with two participants both running the minimal example logic.
67
76
68
-
NOTE: Hydra nodes require a fully-synchronized Cardano node to operate
77
+
NOTE: Hydra nodes require a fullysynchronized Cardano node to operate
69
78
correctly. No additional setup actions need to be performed to
70
79
configure the Cardano node as it is already included in the Docker
71
-
Compose configuration. However it may take several hours on the first
72
-
run to synchronize the node. Keep in mind that Hydra nodes
73
-
are configured to run only once the Cardano node is fully
74
-
synchronized, and the `cardano-node` output is suppressed to not
75
-
interfere with useful Hydra Head logs. As a result, there will be no
76
-
output during synchronization. Instead, use `docker logs` or run
77
-
`cardano-cli query tip` from within the `cardano-node` Docker
78
-
container to track the synchronization progress.
79
-
80
-
### Functionality
81
-
82
-
The `HydraSdk.Process` module provides an interface for spinning up a hydra-node
80
+
Compose configuration.
81
+
However, node synchronization may take several hours on the first run.
82
+
Keep in mind that Hydra nodes are configured to run only once
83
+
the Cardano node is fully synchronized,
84
+
and the `cardano-node` output is suppressed to not
85
+
interfere with useful Hydra Head logs.
86
+
As a result, there will be no output during synchronization.
87
+
Instead, use `docker logs` or run `cardano-cli query tip`
88
+
from within the `cardano-node` Docker container
89
+
to track the synchronization progress.
90
+
91
+
## SDK Core Functionality
92
+
93
+
The SDK exposes the following top-level modules which constitus it API which
94
+
is considered to be relatvely stable. You also can use `Internal` modules
95
+
at yor own risk.
96
+
97
+
*`HydraSdk.Process` module provides an interface for spinning up a hydra-node
83
98
as a Node.js subprocess.
84
99
85
-
The`HydraSdk.NodeApi` module exports functions for connecting to the Hydra Node
100
+
*`HydraSdk.NodeApi` module exports functions for connecting to the Hydra Node
86
101
WebSocket API and sending HTTP requests. The primary function provided by this
87
102
module is `mkHydraNodeApiWebSocket`, which establishes a WebSocket connection to
88
103
the hydra-node, attaches specified handlers for incoming messages, and returns a
@@ -91,21 +106,65 @@ Hydra Node API. It also allows to specify retry strategies for Hydra
91
106
transactions that may be silently dropped by cardano-node, particularly for
92
107
Close and Contest transactions.
93
108
94
-
The`HydraSdk.Types` module re-exports various Hydra domain-specific types
109
+
*`HydraSdk.Types` module re-exports various Hydra domain-specific types
95
110
(such as `HydraHeadStatus` and `HydraNodeApi_InMessage`), along with other
96
111
utility types (e.g., `HostPort` and `Network`) used by the components of this
97
112
library.
98
113
99
-
`HydraSdk.Extra.AppManager` provides an opinionated interface for managing
100
-
multiple Hydra application instances, with each instance running a separate
101
-
hydra-node process, as implemented in [hydra-auction-offchain](https://github.com/mlabs-haskell/hydra-auction-offchain).
102
-
For more information, refer to the [AppManager README](src/Extra/README.md).
114
+
* Lastly, `HydraSdk.Lib` module contains useful helpers like codecs for many types,
115
+
logging action and some others.
116
+
117
+
## SDK Additionals: AppManager
118
+
119
+
Under `Extra` folder, modules with additional functionality are located,
120
+
currently being the only one for managing multiple app instances.
121
+
122
+
Originally the SDK was designed for Hydra applications, where Hydra Heads were
123
+
operated by designated delegates. In that model a delegate can be anyone who wants
124
+
to participate as a provider of computational resources to host Hydra
125
+
nodes. Delegates must form a group upfront to maintain Hydra
126
+
consensus. Upon forming a group, all members need to specify
127
+
information about their peers - such as Hydra node addresses, public
128
+
keys, etc. That way there exists a strict correspondence between
129
+
delegate configurations to start a functioning Hydra Head.
130
+
131
+
Each application instance should monitor its underlying Hydra node and
132
+
have access to information about other Hydra Head participants.
133
+
AppManager is an opinionated interface for managing multiple app
134
+
instances within a delegate group. This interface is utilized by
135
+
applications like `hydra-auction-offchain`, enabling delegates to host
136
+
multiple Layer-2 auctions simultaneously.
137
+
138
+
At the core of AppManager is the concept of slots. When delegates
139
+
decide to form a group, they agree on the configurations for their
140
+
future Hydra nodes. Since each delegate have to specify information
141
+
about their peers (hydra-node address, public keys, etc.), there must
142
+
be strict correspondence between delegate configurations to start
143
+
a working Hydra Head. This is where slots come into play. Each slot
144
+
represents a set of delegate configurations sufficient to spin up a
145
+
properly configured Hydra Head. In hydra-auction-offchain, slot
146
+
numbers are implicitly derived from the configurations provided to
147
+
the delegate-server, with the first configuration corresponding to
148
+
slot 0, the second to slot 1, and so forth. Users are expected to
149
+
reserve slots before making an initial Layer-1 commitment, such as
150
+
announcing an auction. Upon reservation, they receive secrets from
151
+
each delegate, which can later be provided to host a Layer-2
152
+
application in the reserved slot.
153
+
154
+
One clear drawback of this approach is the potential for malicious
155
+
actors to reserve all available slots within a delegate group,
156
+
effectively paralyzing its operations. In real-world applications, a
157
+
flooding detection mechanism should be implemented to prevent this
158
+
scenario, although there seems to be no obvious incentive for anyone
159
+
to carry out such an attack.
160
+
161
+
Coming with the limitations mentioned, this approach simplifies things
162
+
since it neither requires communication and synchronization between
163
+
delegates during runtime nor does it rely on a central server to
164
+
orchestrate the initialization of Hydra Heads, making it a great fit
165
+
for hydra-auction-offchain and hopefully other Hydra applications.
166
+
167
+
## Applications
103
168
104
-
### Development Workflows
105
-
106
-
Before executing most of the commands listed below, first enter the Nix
107
-
development shell by running `nix develop`.
108
-
109
-
**Build the project** (requires Nix shell): `make build`
0 commit comments