From ff72844cc54bc60db0b0a379fabdb2d1bdd031f3 Mon Sep 17 00:00:00 2001 From: Emmanuel Ameh Date: Wed, 26 Jun 2024 20:33:43 +0100 Subject: [PATCH] FIrst draft of MK-5055 (#1470) --- * [ ] CHANGELOG updated or not needed * [ ] Documentation updated or not needed * [ ] Haddocks updated or not needed * [ ] No new TODOs introduced or explained herafter --------- Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> --- docs/docs/configuration.md | 121 +++++++++++++++++-------------------- docs/docs/installation.md | 9 ++- 2 files changed, 60 insertions(+), 70 deletions(-) diff --git a/docs/docs/configuration.md b/docs/docs/configuration.md index ea2d43115fe..cb3adadc025 100644 --- a/docs/docs/configuration.md +++ b/docs/docs/configuration.md @@ -1,20 +1,18 @@ # Configuration -Running a Hydra head means running a Hydra node connected to some other Hydra nodes and connected to a Cardano node. - -The entire configuration of the `hydra-node` is provided through command-line options. Options are used to configure various elements of the network, API, chain connection and used ledger. You can use `--help` to get a description of all options: +Running a Hydra head involves operating a Hydra node connected to other Hydra nodes and a Cardano node. The entire configuration of the `hydra-node` is managed through command-line options. Use the `--help` option to see a full list of available commands: ```shell hydra-node --help ``` -Below we document selected aspects of the configuration. See the [tutorial](./tutorial) for an end-to-end guide or individual _How to_ articles for more details. +Below, we document selected aspects of the configuration. For a comprehensive guide, refer to the [tutorial](./tutorial) or specific _how to_ articles. -### Cardano Keys +### Cardano keys -In a head, every participant is authenticated by two sets of keys. The first are used to identify a participant on the Cardano L1 and hold ADA to pay fees. Every `hydra-node` needs to be given a `--cardano-signing-key` and for each other participant of the head, we need to provide their `--cardano-verification-key`. +In a Hydra head, each participant is authenticated using two sets of keys. The first set identifies a participant on the Cardano layer 1 and is used to hold ada for paying fees. Each `hydra-node` requires a `--cardano-signing-key`, and you must provide the `--cardano-verification-key` for each participant. -Such a key pair can be generated using the `cardano-cli` as follows: +Generate a Cardano key pair using the `cardano-cli`: ```shell cardano-cli address key-gen \ @@ -22,82 +20,72 @@ cardano-cli address key-gen \ --signing-key-file cardano.sk ``` -These keys are currently used to authenticate on-chain transactions which drives the execution of the Hydra protocol. They prevent unsolicited actors to fiddle with the head life-cycle (for instance, someone external to the head could otherwise _abort_ an initialised head). While this wouldn't put head participants' funds at risk, it is still an annoyance that one wants to prevent. +These keys authenticate on-chain transactions and ensure that only authorized participants can control the head's lifecycle, preventing unauthorized actors from interfering (eg, aborting an initialized head). While this issue does not put participants' funds at risk, it is still inconvenient and can be avoided. ### Hydra keys -The second set of keys are the so-called Hydra keys, which are used for multi-signing snapshots within a Head. While in the long-run, those keys may be used in an aggregated multi-signature scheme. At present however, Hydra keys are also Ed25519 keys. +The second set of keys are Hydra keys, used for multi-signing snapshots within a head. Although these keys may eventually support an aggregated multi-signature scheme, they currently use the Ed25519 format. -These are similar to cardano keys but are only on the layer 2. New keys can be generated using `hydra-node`: +Generate new Hydra keys using the `hydra-node`: ``` hydra-node gen-hydra-key --output-file my-key ``` -This will create two files, `my-key.sk` and `my-key.vk` containing Hydra keys suitable for use inside a head. - -Alternatively, we provide demo key pairs as `alice.{vk,sk}`, `bob.{vk,sk}` and `carol.{vk,sk}` in our [demo folder](https://github.com/input-output-hk/hydra/tree/master/demo). These should obviously not be used in production. +This command creates two files: `my-key.sk` and `my-key.vk` containing Hydra keys suitable for use inside a head. +For demonstration purposes, we also provide demo key pairs (`alice.{vk,sk}`, `bob.{vk,sk}`, and `carol.{vk,sk}`) in our [demo folder](https://github.com/input-output-hk/hydra/tree/master/demo). These demo keys should not be used in production. -### Contestation Period +### Contestation period -The contestation period is a protocol parameter and given as a number of seconds, for example: +The contestation period is a critical protocol parameter, defined in seconds, for example: ``` hydra-node --contestation-period 120s ``` -Contestation period is used in: +The contestation period is used in: -- Constructing the upper validity bound for `Close` and `Contest` transactions, -- Computing the contestation deadline and therefore the lower validity - bound for `FanOut` transaction. +- Constructing the upper validity bound for `Close` and `Contest` transactions +- Computing the contestation deadline, which defines the lower validity + bound for the `FanOut` transaction. -This parameter has a default value of _60 seconds_, which should be -enough under normal circumstances, but it needs to be tailored to the -condition of network we are running on since slot lengths and block -production rates are different on different networks. +The default contestation period is _60 seconds_, but it should be tailored to the network conditions, as different networks have varying slot lengths and block production rates. :::info Consistent contestation period -All parties in the hydra head protocol need to configure the same -value for `--contestation-period` otherwise the `Init` transaction -will be ignored. This prevents certain party from stalling/DoS-ing -the head by setting contestation period to unreasonably large values. +All parties in the Hydra head protocol must configure the same `--contestation-period` value. Otherwise, the `Init` transaction will be ignored, preventing any participant from stalling or causing a denial-of-service (DoS) attack by setting an unreasonably large contestation period. ::: -:::warning Invalid Close and Contest Transactions +:::warning Invalid `Close` and `Contest` transactions Depending on the contestation period value and the network conditions, `Close` and `Contest` transactions could become invalid and be -silently rejected by the cardano-node to which they have been +silently rejected by the `cardano-node` to which they have been submitted. This can happen, for example, if: -* The network is congested, with lot of transactions waiting to be - included in a block, +* The network is congested with many transactions waiting to be + included in a block * The node's connectivity to the network drops and the transaction is not propagated to block producers fast enough. -The hydra-node itself does not currently handle this situation and -therefore each client application needs to put in place some retry -mechanism depending on the time it should "normally" take to have the -transaction. +Currently, the `hydra-node` does not handle this situation. Each client application should implement a retry mechanism based on the expected time for transaction inclusion. ::: -### Reference Scripts +### Reference scripts -The `hydra-node` makes use of reference scripts to reduce the size of transactions driving the Head's lifecycle. To reference the right scripts, the `--hydra-scripts-tx-id` needs to be provided. When provided, the `hydra-node` checks whether the right scripts are available at this transaction on-chain. +The `hydra-node` uses reference scripts to reduce transaction sizes driving the head's lifecycle. Specify the `--hydra-scripts-tx-id` to reference the correct scripts. The `hydra-node` will verify the availability of these scripts on-chain. -You can also check against which scripts a hydra-node was compiled using: +Check the scripts against which a hydra-node was compiled using: ```shell hydra-node --script-info ``` -For public [(test) networks](https://book.world.dev.cardano.org/environments.html), we publish the hydra scripts on each new release and advertise transaction ids on the [release notes](https://github.com/input-output-hk/hydra/releases) and on the repository in [`networks.json`](https://github.com/input-output-hk/hydra/blob/master/networks.json). +For public [(test) networks](https://book.world.dev.cardano.org/environments.html), we publish Hydra scripts with each new release, listing transaction IDs in the [release notes](https://github.com/input-output-hk/hydra/releases) and [`networks.json`](https://github.com/input-output-hk/hydra/blob/master/networks.json). -If you want to publish the scripts yourself, you can do so using the `publish-scripts` command: +To publish scripts yourself, use the `publish-scripts` command: ```shell hydra-node publish-scripts \ @@ -106,52 +94,51 @@ hydra-node publish-scripts \ --cardano-signing-key cardano.sk ``` -On success, this commands outputs a transaction id ready to be used. The provided key is expected to hold funds (> 50 ADA), and will be used to create multiple **UNSPENDABLE** UTxO entries on-chain, each carrying a script that can be later referenced by the Hydra node. +This command outputs a transaction ID upon success. The provided key should hold sufficient funds (> 50 ada) to create multiple **UNSPENDABLE** UTXO entries on-chain, each carrying a script referenced by the Hydra node. + +### Ledger parameters -### Ledger Parameters +The ledger is at the core of a Hydra head. Hydra is currently integrated with Cardano and assumes a ledger configuration similar to layer 1. This translates as a command-line option `--ledger-protocol-parameters`. This defines the updatable protocol parameters such as fees or transaction sizes. These parameters follow the same format as the `cardano-cli query protocol-parameters` output. -At the core of a Hydra head, there's a ledger. At the moment, Hydra is wired only to Cardano and assumes a ledger configuration similar to the one used on the layer 1. This translates as a command-line option `--ledger-protocol-parameters`. This defines the updatable protocol parameters such as fees or transaction sizes. They use the same format as the one used by the cardano-cli (e.g. `cardano-cli query protocol-parameters`'s output). +We provide existing files in [hydra-cluster/config](https://github.com/input-output-hk/hydra/blob/master/hydra-cluster/config) which can be used as the basis. In particular, the protocol parameters nullify costs inside a head. Apart from that, they are the direct copy of the current mainnet parameters. An interesting point about Hydra's ledger is that while it re-uses the same rules and code as layer 1 (isomorphic), some parameters can be altered. For example, fees can be adjusted, but not parameters controlling maximum value sizes or minimum ada values, as altering these could make a head unclosable. -We provide existing files in [hydra-cluster/config](https://github.com/input-output-hk/hydra/blob/master/hydra-cluster/config) which can be used as basis. In particular, the protocol parameters are defined to nullify costs inside a head. Apart from that, they are the direct copy the current mainnet parameters. An interesting point about the Hydra's ledger is that, while it re-uses the same rules and code as the layer 1 (a.k.a. isomorphic), parameters may also be altered to slightly differ from the layer 1. This is the case for fees, but could also be done for script maximum execution budget for instance. However, not all parameters are safe to alter! Changing parameters that control the maximum size of a value (carrying native assets), or the minimum Ada value for a UTxO may render a head "unclosable"! A good rule thumb is that anything that applies strictly to transactions (fees, execution units, max tx size...) is safe to change. But anything that could be reflected in the UTxO is not. +A good rule thumb is that anything that applies strictly to transactions (fees, execution units, max tx size...) is safe to change. But anything that could be reflected in the UTXO is not. -:::info About Protocol Parameters -Note that many of protocol-parameters are actually irrelevant in the context of Hydra (for example, there's no treasury or stake pool inside a head; consequently, parameters configuring the reward incentive or delegation rules are pointless and unused). +:::info About protocol parameters +Many protocol parameters are irrelevant in the Hydra context (eg, there is no treasury or stake pools within a head). Parameters related to reward incentives or delegation rules are therefore unused. ::: -### Fuel vs. Funds +### Fuel v funds -All the transactions driving the Head lifecycle (Init, Abort, Close, ...) need to be submitted to the layer 1, and hence they cost money! For that, any UTxO owned by the `--cardano-signing-key` given to the `--hydra-node` will be considered spendable to pay fees or use as collateral for these Hydra protocol transactions. We sometimes this **fuel**. +Transactions driving the head lifecycle (`Init`, `Abort`, `Close`, etc) must be submitted to layer 1 and hence incur costs. Any UTXO owned by the `--cardano-signing-key` provided to the `--hydra-node` can be used to pay fees or serve as collateral for these transactions. We refer to this as **fuel**. -Consequently, sending some ADA to the address of this "internal wallet" is required. To get the address for the cardano keys as generated above, one can use for example the cardano-cli: +Consequently, sending some ada to the address of this 'internal wallet' is required. To get the address for the Cardano keys as generated above, one can use, for example, the `cardano-cli`: ```shell cardano-cli address build --verification-key-file cardano.vk --mainnet # addr1v92l229athdj05l20ggnqz24p4ltlj55e7n4xplt2mxw8tqsehqnt ``` - - -While the `hydra-node` needs to pay fees for protocol transactions, any wallet can be used to commit **funds** into an `initializing` Hydra head. The `hydra-node` provides an HTTP endpoint at `/commit`, which allows to specify either: - - a `UTxO` set of outputs to commit (belonging to public keys) or - - a _blueprint_ transaction together with the `UTxO` which resolves it. - -and eventually returns a commit transaction. + -This transaction is already balanced and all fees are paid by the funds held by the `hydra-node`. Hence, an integrated wallet would need to sign this transaction and submit it to the Cardano network. See the [api documentation](pathname:///api-reference/#operation-publish-/commit) for details. +While the `hydra-node` needs to pay fees for protocol transactions, any wallet can be used to commit **funds** into an `initializing` Hydra head. The `hydra-node` provides an HTTP endpoint at `/commit`, allowing you to specify either: + - A set of `UTXO` outputs to commit (belonging to public keys), or + - A _blueprint_ transaction along with the `UTXO` that resolves it. -If the user wants to use some `UTxO` they own and commit it to a `Head` then they need to send the appropriate JSON representation of said `UTxO` to the `/commit` API endpoint. +This endpoint returns a commit transaction, which is balanced, and all fees are paid by the `hydra-node`. The integrated wallet must sign and submit this transaction to the Cardano network. See the [API documentation](pathname:///api-reference/#operation-publish-/commit) for details. -Using a _blueprint_ transaction with `/commit` allows for more flexibility since `hydra-node` only adds needed commit transaction data without removing any additional information specified in the _blueprint_ transaction. For example, any present reference inputs, redeemers or validity ranges will be kept. +If using your own UTXO to commit to a head, send the appropriate JSON representation of the said UTXO to the `/commit` API endpoint. +Using a _blueprint_ transaction with `/commit` offers flexibility, as `hydra-node` adds necessary commit transaction data without removing additional information specified in the blueprint transaction (eg, reference inputs, redeemers, validity ranges). -> Note: It is important to note that any **outputs** of a blueprint transaction will not be considered, only inputs are used to commit funds to the `Head`. `hydra-node` will also **ignore** any minting or burning specified in the blueprint transaction. +> Note: Outputs of a blueprint transaction are not considered — only inputs are used to commit funds to the head. The `hydra-node` will also **ignore** any minting or burning specified in the blueprint transaction. -For more details refere to the [how to](./how-to/commit-blueprint) about committing to a `Head` using blueprint transaction. +For more details, refer to this [how to](./how-to/commit-blueprint) guide on committing to a head using a blueprint transaction. ## Connect to Cardano -The `hydra-node` needs to be connected to the cardano network (unless it runs in [offline mode](./configuration.md#offline-mode)). +The `hydra-node` must be connected to the Cardano network, unless running in [offline mode](./configuration.md#offline-mode). -Currently a direct connection to a [`cardano-node`](https://github.com/input-output-hk/cardano-node/) is a pre-requisite and please refer to existing documentation on starting a node, e.g. on [developers.cardano.org](https://developers.cardano.org/docs/get-started/running-cardano) or [use mithril](https://mithril.network/doc/manual/getting-started/bootstrap-cardano-node) to bootstrap the local node. +A direct connection to a [`cardano-node`](https://github.com/input-output-hk/cardano-node/) is a pre-requisite. Please refer to existing documentation on starting a node, for example on [developers.cardano.org](https://developers.cardano.org/docs/get-started/running-cardano), or [use Mithril](https://mithril.network/doc/manual/getting-started/bootstrap-cardano-node) to bootstrap the local node. To specify how to connect to the local cardano-node, use `--node-socket` and `--testnet-magic`: @@ -184,12 +171,12 @@ If the `hydra-node` already tracks a head in its `state` and `--start-chain-from ## Offline mode -Hydra supports an offline mode, which allows for disabling the Layer 1 interface (that is, the underlying Cardano blockchain which Hydra heads use to seed funds and ultimately funds are withdrawn to). Disabling Layer 1 interactions allows use-cases which would otherwise require running and configuring an entire Layer 1 private devnet. For example, the offline mode can be used to quickly validate a series of transactions against a UTxO, without having to spin up an entire Layer 1 Cardano node. +Hydra supports an offline mode, which allows for disabling the layer 1 interface (that is, the underlying Cardano blockchain which Hydra heads use to seed funds and ultimately funds are withdrawn to). Disabling layer 1 interactions allows use cases that would otherwise require running and configuring an entire layer 1 private devnet. For example, the offline mode can be used to quickly validate a series of transactions against a UTXO, without having to spin up an entire layer 1 Cardano node. -In this offline mode, only the Layer 2 ledger is run, along with the Hydra API and persistence, to support interacting with the offline Hydra. Therefore, ledger genesis parameters that normally influence things like time-based transaction validation, may be set to defaults that aren't reflective of mainnet. To set this, set --ledger-protocol-parameters to a non-zero file, as described [here](https://hydra.family/head-protocol/unstable/docs/configuration/#ledger-parameters). -Depending on your use case, you can [configure your node's event source and sinks](./how-to/event-sinks-and-sources.md) to better suite your needs. +In this offline mode, only the layer 2 ledger is run, along with the Hydra API and persistence, to support interacting with Hydra offline. Therefore, ledger genesis parameters that normally influence things like time-based transaction validation, may be set to defaults that aren't reflective of mainnet. To do this, set `--ledger-protocol-parameters` to a non-zero file, as described [here](https://hydra.family/head-protocol/unstable/docs/configuration/#ledger-parameters). +Depending on your use case, you can [configure your node's event source and sinks](./how-to/event-sinks-and-sources.md) to better suit your needs. -To initialize the Layer 2 ledger's UTXO state, offline mode takes an obligatory --initial-utxo parameter, which points to a JSON encoded UTXO file. This UTXO is independent of Event Source loaded events, and the latter are validated against this UTXO. The UTXO follows the following schema `{ txout : {address, value : {asset : quantity}, datum, datumhash, inlinedatum, referenceScript }` +To initialize the layer 2 ledger's UTXO state, offline mode takes an obligatory `--initial-utxo` parameter, which points to a JSON-encoded UTXO file. This UTXO is independent of event source loaded events, and the latter are validated against this UTXO. The UTXO follows the following schema `{ txout : {address, value : {asset : quantity}, datum, datumhash, inlinedatum, referenceScript }` An example UTXO: ```json diff --git a/docs/docs/installation.md b/docs/docs/installation.md index df81be60b1b..73aa7e07e08 100644 --- a/docs/docs/installation.md +++ b/docs/docs/installation.md @@ -4,9 +4,11 @@ sidebar_position: 2 # Installation +Selecting the right installation method for the `hydra-node` depends on your requirements and technical preferences. Below are the primary methods to get started quickly and efficiently. + ### Docker -The quickest way to get a `hydra-node` installed and running is to use our Docker images: +The quickest way to install and run a `hydra-node` is by using Docker images: ```shell docker pull ghcr.io/input-output-hk/hydra-node @@ -15,8 +17,9 @@ docker run --rm ghcr.io/input-output-hk/hydra-node --help ### Prebuilt binaries -We provide statically linked (as much as possible) binaries of `hydra-node` and `hydra-tui` for x86_64 Linux and ARM64 MacOS platforms as attachment of our [github releases](https://github.com/input-output-hk/hydra/releases). +We provide statically linked binaries of `hydra-node` and `hydra-tui` for x86_64 Linux and ARM64 MacOS platforms. These binaries are available as attachments in our [github releases](https://github.com/input-output-hk/hydra/releases). + ### Build from source -While using docker is the recommended way to _use_ Hydra, you can also build the `hydra-node` from source. We do recommend using [nix](https://nixos.org/download.html) for this and the instructions can be found in our [Contributing Guidelines](https://github.com/input-output-hk/hydra/blob/master/CONTRIBUTING.md). +While using Docker is the recommended way to _use_ Hydra, you can also build the `hydra-node` from source. We recommend using [Nix](https://nixos.org/download.html) for this and you can find instructions in our [contributing guidelines](https://github.com/input-output-hk/hydra/blob/master/CONTRIBUTING.md).