diff --git a/docs/docs/how-to/commit-blueprint.md b/docs/docs/how-to/commit-blueprint.md index 9161794fd86..81bcbc6f8ab 100644 --- a/docs/docs/how-to/commit-blueprint.md +++ b/docs/docs/how-to/commit-blueprint.md @@ -4,22 +4,26 @@ sidebar_position: 1 # Commit using a blueprint - This is a small walk-through on how to use `cardano-cli` to assemble everything needed to commit funds to a `Head` using a so-called blueprint transaction. +This guide provides a walkthrough on using `cardano-cli` to assemble the necessary components for committing funds to a `head` using a blueprint transaction. - Example assumes you have the hydra-node repo at your disposal together with `hydra-node`, `hydra-tui`, `cardano-cli` and `curl` binaries. +**Prerequisites** - We can use `cardano-cli` to create a _blueprint_ transaction from some `UTxO` we own. +You should have access to the following repositories: - First we need a running cardano-node so let's spin one on the preprod network: +- `hydra-node` +- `hydra-tui` +- `cardano-cli`, and +- `curl` binaries. +## Step 1 +You can use `cardano-cli` to create a _blueprint_ transaction from some `UTXO` you own. First, initiate a Cardano node on the pre-production network: ```shell ./testnets/cardano-node.sh ~/code/hydra/testnets/preprod ``` - Now we need to find the `UTxO` you want to commit to the `Head` - - In this example we will use Alice and her external wallet key so first let's find out the address: +## Step 2 +Determine which `UTXO` you intend to commit to the `head`. This example uses Alice's external wallet key to identify her address: ```shell cardano-cli address build \ @@ -29,7 +33,7 @@ sidebar_position: 1 addr_test1vp5cxztpc6hep9ds7fjgmle3l225tk8ske3rmwr9adu0m6qchmx5z ``` -and query to see what `UTxO` Alice has: +Next, query to see what `UTXO` Alice has: ```shell cardano-cli query utxo \ @@ -62,7 +66,8 @@ cardano-cli query utxo \ } ``` -Let's pick the first `UTxO` which has total of 8 ADA available. Let's use 5 ADA to commit and rely on `hydra-node` to balance the commit transaction. +## Step 3 +Select the first `UTXO`, which has eight ada available. Use five ada to commit and rely on `hydra-node` to balance the commit transaction: ```shell cardano-cli transaction build-raw \ @@ -73,17 +78,16 @@ cardano-cli transaction build-raw \ --out-file tx.json ``` -So now we have the _blueprint_ transaction present in the `tx.json` file. - -In order to have `hydra-node` give us a draft commit transaction we need to: +## Step 4 +You should now have the _blueprint_ transaction in the `tx.json` file. For `hydra-node` to provide a draft commit transaction, you need to: -- Obtain protocol-parameters needed to run the `hydra-node` -- Have the `hydra-node` up and running -- Have the `Head` in the initializing state -- Submit the http request to the `hydra-node` api server using the _blueprint_ transaction we just created and the `UTxO` used for it's input. +- Obtain the protocol parameters needed to run the `hydra-node` +- Ensure the `hydra-node` is up and running +- Have the `head` in the initializing state +- Submit the HTTP request to the `hydra-node` API server using the _blueprint_ transaction you just created and the `UTXO` used for its input. -Query the preview protocol-parameters: +Query the protocol parameters: ```shell cardano-cli query protocol-parameters \ @@ -93,9 +97,10 @@ cardano-cli query protocol-parameters \ ``` -Start the `hydra-node` in as a _single_ party Head instance. +## Step 5 +Start the `hydra-node` as a _single_ party head instance. -Note: The value `6264cee4d5eab3fb58ab67f3899ecbcc0d7e72732a2d9c1c5d638115db6ca711` comes from `hydra-node` release [0.16.0](https://github.com/input-output-hk/hydra/releases/tag/0.16.0) +Note: The value `6264cee4d5eab3fb58ab67f3899ecbcc0d7e72732a2d9c1c5d638115db6ca711` comes from the `hydra-node` release [0.16.0](https://github.com/input-output-hk/hydra/releases/tag/0.16.0). ```shell hydra-node \ @@ -109,7 +114,7 @@ hydra-node \ --persistence-dir . ``` -Now we can start `hydra-tui` and initialize the `Head`: +Now you can start `hydra-tui` and initialize the `head`: ```shell hydra-tui \ @@ -119,15 +124,9 @@ hydra-tui \ --node-socket testnets/preprod/node.socket ``` -Now press `i` to initialize the `Head`. - -Once we see that the head is in the `Initializing` state we are ready to send the HTTP request to the `/commit` API path. +Press `i` to initialize the `head`. Once the head is in the `Initializing` state, you can send the HTTP request to the `/commit` API path. Assemble the request body using the `cborHex` field from the tx-body file `tx.json` and the JSON representation of the `UTXO` you used as input. -To assemble the request body we will use the `cborHex` field from the tx-body file `tx.json`. - -To get the json representation of the `UTxO` we used as the input we can just copy/paste the output we got from cardano-cli when we did a `UTxO` query: - -This is the valid json request: +This is the valid JSON request: ```shell { @@ -151,9 +150,9 @@ This is the valid json request: } ``` -Let's save this json to commit-request.json file. +Save this JSON to a `commit-request.json` file. -Now, it is time to ask the running `hydra-node` to draft a commit transaction for us: +You can now prompt the running `hydra-node` to draft a commit transaction: ``` @@ -162,9 +161,9 @@ curl -X POST 127.0.0.1:4001/commit \ ``` -This yields a large cbor blob which we can save to `commit-tx.json` file. +This yields a large CBOR blob, which you can save to the `commit-tx.json` file. -Now we need to sign and submit the draft commit transaction. +Next, sign and submit the draft of the commit transaction: ```shell @@ -180,5 +179,4 @@ cardano-cli transaction submit \ --testnet-magic 1 ``` -If we start the `hydra-tui` and wait a bit until the transaction we just sent is re-observed by the `hydra-node` we should see that the `Head` is now open. - +If you start the `hydra-tui` and wait until the transaction you just sent is re-observed by the `hydra-node`, you should see that the head is now open. diff --git a/docs/docs/how-to/operating-hydra.md b/docs/docs/how-to/operating-hydra.md index d1817e51139..0bbc59462fd 100644 --- a/docs/docs/how-to/operating-hydra.md +++ b/docs/docs/how-to/operating-hydra.md @@ -2,31 +2,33 @@ sidebar_position: 3 --- -# Operate a Hydra Node +# Operate a Hydra node ```mdx-code-block import TerminalWindow from '@site/src/components/TerminalWindow'; ``` -This page aims at helping Hydra users troubleshoot issues when running their own instances of `hydra-node` and participate in a Hydra Head. +This page guides Hydra users on troubleshooting issues when running their instances of `hydra-node` and participating in a Hydra head. -## Example Setup +## Example setup -We provide sample node configurations that will help you get started hosting a Hydra node on virtual machines in the Cloud in the [`sample-node-config/` directory](https://github.com/input-output-hk/hydra/tree/master/sample-node-config/). +We offer sample node configurations that will help you get started with hosting a Hydra node on virtual machines in the cloud. These configurations are available in the [`sample-node-config/` directory](https://github.com/input-output-hk/hydra/tree/master/sample-node-config/). -### Google Cloud w/ Terraform -This setup contains a [docker-compose.yaml](https://github.com/input-output-hk/hydra/blob/master/sample-node-config/gcp/docker-compose.yaml) which gives a good template for configuring cardano-node + hydra-node services. It also offers various useful scripts to setup your cluster. +### Google Cloud with Terraform + +This setup includes a [docker-compose.yaml](https://github.com/input-output-hk/hydra/blob/master/sample-node-config/gcp/docker-compose.yaml) file, which serves as a robust template for configuring `cardano-node` and `hydra-node` services. Also, various scripts are provided to help you set up your cluster. ## Logs -Following [ADR-9](/adr/9) design principles, the `hydra-node` provides [JSON](https://json.org) formatted logs on the `stdout` stream, one line per log item. The log items follow a [JSON schema](https://github.com/input-output-hk/hydra/blob/master/hydra-node/json-schemas/logs.yaml). This logging capability is kept voluntarily simple and non configurable in order to ease integration of Hydra logging into more general log analysis infrastructure, whether a custom ELK stack, third-party services, docker sidecars... +Following the principles outlined in [ADR-9](/adr/9), the `hydra-node` emits [JSON](https://json.org) formatted logs to the `stdout` stream, with one log item per line. These log entries conform to a specific [JSON schema](https://github.com/input-output-hk/hydra/blob/master/hydra-node/json-schemas/logs.yaml). We deliberately maintain the logging mechanism simple and non-configurable to facilitate the integration of Hydra logs into broader log analysis infrastructures, including custom ELK stacks, third-party services, or Docker sidecars. ## Monitoring -When given `--monitoring-port PORT` argument, the hydra-node executable will expose a [Prometheus](https://prometheus.io) compatible HTTP `/metrics` endpoint on the given port to enable _scraping_ of exposed metrics. +When the `--monitoring-port PORT` argument is provided, the `hydra-node` executable will expose a [Prometheus](https://prometheus.io) compatible HTTP `/metrics` endpoint on the specified port to enable metrics scraping. + +For instance, if a `hydra-node` is initiated with `--monitoring-port 6001`, the following command: -For example, assuming a hydra-node was started with `--monitoring-port 6001`, this command ```mdx-code-block @@ -34,7 +36,7 @@ curl http://localhost:6001/metrics ``` -will output +will output: ``` # TYPE hydra_head_confirmed_tx counter @@ -54,37 +56,17 @@ hydra_head_tx_confirmation_time_ms_sum 0.0 hydra_head_tx_confirmation_time_ms_count 0 ``` -## Common Issues - -### No Head is observed from the chain - -* `hydra-node` is connected to a `cardano-node` that's on the wrong - network. Check the `--network` command-line argument and the - `cardano-node` configuration -* Note that the `hydra-node` cannot start if it cannot connect to the - `cardano-node`, which might require some time as the `cardano-node` - needs to revalidate its database and possibly even reconstruct its - ledger state when it starts and its connections are not open until - it's ready. If running as a service or a container, make sure the orchestrator restarts the process when it crashes -* The _Scripts_ transaction identifier is invalid. This transaction id - is available in the - [release](https://github.com/input-output-hk/hydra/releases/tag/0.10.0) - page for the 3 major networks (`preview`, `preprod`, `mainnet`) -* The `hydra-node`'s _Cardano signing key_ is inconsistent with the - _Verification key_ from the `Init` transaction. Check the - `--cardano-signing-key` parameter points to the right key, and that - peers have the correct `--cardano-verification-key` for your host. -* The peers' _Cardano verification keys_ are incorrect. This is - mirroring the above issue, check parameters on all peers. +## Common issues + +### No head is observed from the chain + +* Ensure the `hydra-node` is connected to a `cardano-node` operating on the correct network. Verify the `--network` command-line argument and the `cardano-node` configuration. +* Remember, the `hydra-node` cannot start if it cannot connect to the `cardano-node`, which might require time as the `cardano-node` must revalidate its database and potentially reconstruct its ledger state upon startup. Its connections are not open until it is fully prepared. If running as a service or a container, ensure that the orchestrator restarts the process when it crashes. +* Check that the _Scripts_ transaction identifier is valid. This identifier is provided on the [release](https://github.com/input-output-hk/hydra/releases/tag/0.10.0) page for the three major networks (`preview`, `pre-production`, `mainnet`). +* Verify that the `hydra-node`'s _Cardano signing key_ is consistent with the _Verification key_ from the `Init` transaction. Ensure the `--cardano-signing-key` parameter points to the correct key, and that peers have the accurate `--cardano-verification-key` for your node. +* Confirm that peers' _Cardano verification keys_ are accurate. This mirrors the above issue; check parameters on all peers. ### Head does not make progress -* Peers are not correctly connected to each others'. Check the - `--peer` arguments point to the right `host:port` for each - peer. `PeerConnected` message should be sent to the client (or - appears in the logs) and be consistent for all peers involved in a - Head. -* The _Hydra signing key_ for our node or the _Hydra verification - keys_ for peers do not match what's expected by each node. Check - that `AckSn` messages are received by all parties and that the - `LogicOutcome` log does not contain any `Error` +* Confirm peers are properly connected to each other. Verify the `--peer` arguments point to the correct `host:port` for each peer. The `PeerConnected` message should be observed by the client or appear in the logs and be consistent across all peers involved in a head. +* Ensure the _Hydra signing key_ for your node or the _Hydra verification keys_ for peers match each node's expectations. Verify that `AckSn` messages are received by all parties and that the `LogicOutcome` log contains no errors. diff --git a/docs/docs/how-to/submit-transaction.md b/docs/docs/how-to/submit-transaction.md index 947aa2e379f..dc905d3bc03 100644 --- a/docs/docs/how-to/submit-transaction.md +++ b/docs/docs/how-to/submit-transaction.md @@ -4,15 +4,15 @@ sidebar_position: 2 # Submit a transaction -To submit a transaction to an already open Head, you need to use `NewTx` command of the WebSocket API. +This section describes how to submit a transaction to an already open head using the `NewTx` command of the WebSocket API. -First, let's query the UTxO available in the head: +First, query the UTXO available in the head: ``` curl localhost:4001/snapshot/utxo | jq ``` -An example response could look like: +Below is an example response: ```json title="Example response of GET /snapshot/utxo" { @@ -29,7 +29,7 @@ An example response could look like: } ``` -Assuming the single utxo is owned by `some-payment-key.sk` and we want to send all of it to some other address, we can use the `cardano-cli` (or your favorite transaction builder) to construct and sign a transaction: +Assuming the single UTXO is owned by `some-payment-key.sk` and you want to send all of it to another address, you can use `cardano-cli` (or your preferred transaction builder) to construct and sign a transaction: ```shell title="Transaction building" cardano-cli transaction build-raw \ @@ -47,10 +47,10 @@ cardano-cli transaction sign \ cat tx-signed.json | jq -c '{tag: "NewTx", transaction: .}' ``` -This will output a message that can be submitted to a websocket connection to `hydra-node`. Using `websocat` and assuming the `hydra-node` runs on the default port `4001` we can submit with: +This command generates a message suitable for submission to the `hydra-node` via a WebSocket connection. If `hydra-node` operates on the default port `4001`, the message can be submitted using `websocat`: ```shell cat tx-signed.json | jq -c '{tag: "NewTx", transaction: .}' | websocat "ws://127.0.0.1:4001?history=no" ``` -The transation will now be validated by all connected `hydra-node`s and either result in a `TxInvalid` message with a reason, or a `TxValid` message and a `SnapshotConfirmed` with the new UTxO available in the head shortly after. +The transaction will be validated by all connected `hydra-node` instances. It will result in either a `TxInvalid` message, providing a reason for rejection, or a `TxValid` message followed by a `SnapshotConfirmed`, updating the UTXO available in the head shortly after that.