Skip to content

Commit

Permalink
Mk 5060: How to content final PR (#1478)
Browse files Browse the repository at this point in the history 
<!-- Describe your change here -->

---

<!-- Consider each and tick it off one way or the other -->
* [ ] 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 <[email protected]>
  • Loading branch information
@oduameh @olgahryniuk
oduameh and olgahryniuk committed Jun 26, 2024
1 parent 4af74cf commit bf0ec23
Show file tree
Hide file tree
Showing 3 changed files with 61 additions and 81 deletions.
66 changes: 32 additions & 34 deletions docs/docs/how-to/commit-blueprint.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand All @@ -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 \
Expand Down Expand Up @@ -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 \
Expand All @@ -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 \
Expand All @@ -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 \
Expand All @@ -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 \
Expand All @@ -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
{
Expand All @@ -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:


```
Expand All @@ -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

Expand All @@ -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.
64 changes: 23 additions & 41 deletions docs/docs/how-to/operating-hydra.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,39 +2,41 @@
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
<TerminalWindow>
curl http://localhost:6001/metrics
</TerminalWindow>
```

will output
will output:

```
# TYPE hydra_head_confirmed_tx counter
Expand All @@ -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.
12 changes: 6 additions & 6 deletions docs/docs/how-to/submit-transaction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
{
Expand All @@ -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 \
Expand All @@ -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.

0 comments on commit bf0ec23

Please sign in to comment.