Update aws hydra head opening instructions (#2163)

<!-- Describe your change here -->

---

<!-- Consider each and tick it off one way or the other -->
* [x] CHANGELOG updated or not needed
* [x] Documentation updated or not needed
* [x] Haddocks updated or not needed
* [ ] No new TODOs introduced or explained herafter

Author: vrom911

sample-node-config/aws/README.md

@@ -8,46 +8,54 @@
 This directory contains some [Terraform](https://www.hashicorp.com/products/terraform) and AWS based infrastructure code to setup a single [Hydra node](https://hydra.family/head-protocol/docs/getting-started/installation) connected to a [Cardano node](https://docs.cardano.org/getting-started/installing-the-cardano-node) running on `preview` testnet. It's not a complete turnkey solution and requires some tweaking and parameterisation to be completely usable but we thought it would be good starting point for new Hydra users.
 
 ### Pre-requisites
-- you have access to an aws account with root privileges.
-- you have configured your local aws credentials.
-for this example in `~/.aws/credentials` we have:
+1.  **AWS Account**: You need access to an AWS account with privileges to create EC2 instances and related resources.
+2.  **AWS CLI & Terraform**: You must have the [AWS CLI](https://aws.amazon.com/cli/) and [Terraform](https://developer.hashicorp.com/terraform/downloads) installed and configured on your local machine.
+3.  **AWS Credentials File**: Your local AWS credentials should be configured. For this example, we assume a profile in `~/.aws/credentials`:
     ```
     [personal]
     aws_access_key_id=???
     aws_secret_access_key=???
     region=eu-west-3
     ```
-> **personal** will be your AWS_PROFILE
-> so whenever you see _personal_ in the rest of the file you need to replace it with your own aws profile name.
+4.  **EC2 Key Pair**: You must create an EC2 Key Pair in the AWS region you intend to use. When you create it, AWS will provide a `.pem` file. **Download and save this file securely.** You will need its name for the configuration.
+> Here and later we refer to your `AWS_PROFILE` name as **personal**.
+> Whenever you see _personal_ in the rest of the file you need to replace it with your own aws profile name.
 > Also you need to make sure to create a new key pair in the region eu-west-3 (TODO: abstract the region away?)
 > TODO: it would be cool to use aws_ssm to connect to the EC2 so that we don't depend on extra ssh keys manipulations.
 
-- you have terraform and aws installed on your system.
-- you have built the required 2 folder structures under aws folder:
-    + credentials.
-    + aws.
+### Project Setup
+Before running Terraform, you need to create a specific directory and file structure within the `sample-node-config/aws/` directory.
 
-## Project structure to build
+1.  **Create Directories**:
+    - `credentials/`: This will store your Cardano-related keys.
+    - `aws/`: This will store your EC2 `.pem` file.
+
+2.  **Place Your Key**: Copy the `.pem` file you downloaded from AWS into the `aws/` directory. For example: `aws/my-key.pem`.
+
+3.  **Generate Cardano Keys**: Create your Cardano keys and place them in the `credentials/` directory. You should have at least `cardano.addr`, `cardano-key.sk`, and `hydra-key.sk`.
+
+The final structure should look like this:
 ```
 .
-+-- credentials
-|   +-- arnaud.cardano.vk
-|   +-- arnaud.hydra.vk
++-- credentials/
+|   +-- cardano.addr
 |   +-- cardano-key.sk
 |   +-- cardano-key.vk
-|   +-- cardano.addr
 |   +-- hydra-key.sk
 |   +-- hydra-key.vk
 +-- aws
 |   +-- personal.pem
 +-- terraform.tfvars
++-- (other *.tf files)
 ```
 
 This should only be done once, when starting afresh.
 
-These are folders you must create yourself:
-- ***credentials*** to store all blockchain related credential files.
-- ***aws*** to store your personal aws credentials.
+TODO: refer to how to generate addresses and .sk, .vk files.
+
+### Terraform Configuration
+
+Instead of altering `variables.tf`, you should specify your custom values in a `terraform.tfvars` file at the root of the `sample-node-config/aws/` directory.
 
 At the root of the `aws` project, execute:
 ```sh
@@ -56,21 +64,45 @@ $ ./setup/setup.sh
 [Note] all scripts inside the `/setup` folder are expected to be executed at the root of the `aws` project.
 
 This will create a file called `terraform.tfvars`, used to complete the `variables.tf` definitions. For this example it would be defined as:
-```
+```toml
+# The AWS profile name from your ~/.aws/credentials file.
 profile    = "iog"
+# The name of the EC2 Key Pair you created in the AWS console.
+# This must match the name of the key pair, not the filename.
 key_name   = "personal"
 ```
 
 ## Initialise Terraform
+
 This should only be done once, when starting afresh.
 At the root of `aws` project execute:
+
 ```sh
-$ terraform init
+terraform init
 ```
 
 ### Alter terraform variables
+
+Instead of altering `variables.tf`, you should specify your custom values in a `terraform.tfvars` file at the root of the `sample-node-config/aws/` directory.
 Alter the file `variables.tf` found in `sample-node-config/aws/` to reflect your ami, region and instance_type. Defaults are already provided.
 
+Example 
+```toml
+# The AWS profile from your `~/.aws/credentials` file.
+profile       = "default"
+# The name of the EC2 Key Pair you created in the AWS Console for your chosen region.
+key_name      = "hydra-node-key"
+# The hydra network environment to use. Can be "preview", "preprod", or "mainnet".
+env           = "preview"
+# The AWS region where you created your key pair and want to deploy resources.
+region        = "eu-central-1"
+# The Amazon Machine Image (AMI) ID for a recent Ubuntu release in your chosen region.
+# You can find this in the AWS EC2 Console when launching a new instance.
+ami           = "ami-012345fxxxxxxxx"
+# The type of EC2 instance to launch.
+instance_type = "r5a.xlarge"
+```
+
 ### Deploying the VM
 Then create a deployment plan and apply it:
 ```sh
@@ -129,26 +161,38 @@ $ scripts/login.sh
 - ctrl B + D: detach session
 - tmux a: attach the detached-session
 
+```shell
+source ~/.bash_env
+```
+
 ## Create marker utxo: get fuel from testnet
 Now that you are logged in to your VM, first thing we need is to spin up your `cardano-node` and create the marker utxo.
-For that we will need to execute:
+
+
+For that we will need to executea docker command. First, go to the `docker folder:
+```shell
+cd docker
 ```
+
+and then:
+```shell
 $ docker-compose up -d cardano-node
 $ fuel
 ```
 
 ## Configuring Hydra Node
+
 We need to make sure some files, which are not provided by default and which are required for starting the `hydra-node`, are in place at the home folder of your VM:
 * A Hydra signing key file `hydra-key.sk` which will be used in the Head to sign snapshots.
-  This can be generated using [hydra-node](https://hydra.family/head-protocol/docs/getting-started/quickstart#hydra-keys),
+  This can be generated using [hydra-node](https://hydra.family/head-protocol/docs/configuration#hydra-keys),
 * A cardano signing key file  `cardano-key.sk` which is required to identify the parties on-chain and sign transactions.
-  This is a standard Cardano key so one can reuse an existing key or [generate a new one](https://hydra.family/head-protocol/docs/getting-started/quickstart#cardano-keys),
+  This is a standard Cardano key so one can reuse an existing key or [generate a new one](https://hydra.family/head-protocol/docs/configuration#cardano-keys),
 * 0 or more hydra verification keys and cardano verification keys for the other Head parties,
 * The IP addresses and ports of _peer_ nodes,
 * Configuration files for [promtail](https://grafana.com/docs/loki/latest/clients/promtail/) and [prometheus](https://prometheus.io/) which are run as part of the stack,
 * Configuration files for the off-chain ledger.
 
-Then the [docker-compose.yaml](./docker/docker-compose.yaml) should be edited to reflect the above parameters as [command-line arguments](https://hydra.family/head-protocol/docs/getting-started/quickstart) to the `hydra-node` container.
+Then the [docker-compose.yaml](./docker/docker-compose.yaml) should be edited to reflect the above parameters as [command-line arguments](https://hydra.family/head-protocol/docs/configuration) to the `hydra-node` container.
 
 i.e.:
 ```
@@ -162,23 +206,26 @@ The [promtail-config.yml](./docker/promtail-config.yml) should be edited to poin
 For `cardano-node` and `hydra-node` services, make sure the `logging` options for `awslogs` are properly aligned with what is defined in your `cloudwatch.tf` and `variables.tf` files.
 
 ## Running the hydraw instance
+
 Next, to run hydraw, execute:
-```
-$ up
+
+```sh
+up
 ```
 
 > execute `down` to take it down
 
 ## Opening the Head
 Finally, execute the hydra-tui and open the head:
-```
-$ tui
+
+```sh
+tui
 ```
 
 > If you take down your hydra-node instance once the head is open. you will loose access to your funds committed to the head.
-To get them back, currently you need to start the head from a point time in the past.
-For that you must run hydra-node the using parameter `--start-chain-from`.
-i.e.: --start-chain-from 2730515.c7a3629911ef004c873ef07313842df5d1331f61e0eb632432ac8c0636dfd391
+> To get them back, currently you need to start the head from a point time in the past.
+> For that you must run hydra-node the using parameter `--start-chain-from`.
+> i.e.: `-start-chain-from 2730515.c7a3629911ef004c873ef07313842df5d1331f61e0eb632432ac8c0636dfd391`
 
 ## Using Hydraw
 
@@ -199,8 +246,9 @@ Terraform relies on plain SSH to connect to the VM, so this can be caused by the
 > Peers cannot see you connected
 Perhaps your node is out of sync with the L1.
 Check sync progress by running a `cardano-cli` query tip on your cardano node:
-```
-$ sync
+
+```sh
+sync
 ```
 
 But others may come from the containers itself.

sample-node-config/aws/docker/docker-compose.yaml

@@ -2,8 +2,9 @@
 
 services:
   cardano-node:
-    image: inputoutput/cardano-node:8.7.3
+    image: ghcr.io/intersectmbo/cardano-node:10.4.1
     restart: always
+    container_name: cardano-node
     logging:
       driver: "awslogs"
       options:
@@ -28,6 +29,7 @@ services:
   hydra-node:
     image: ghcr.io/input-output-hk/hydra-node@sha256:3b7f78962ff8fc212644e1ef4faf8742ead6f7c31353cdf5cc251d4d825edac7
     restart: always
+    container_name: hydra-node
     logging:
       driver: "journald"
       # driver: "awslogs"
@@ -84,6 +86,7 @@ services:
 
   hydra-tui:
     image: ghcr.io/cardano-scaling/hydra-tui:unstable
+    container_name: hydra-tui
     profiles:
       - tui
     command:
@@ -99,6 +102,7 @@ services:
 
   hydraw:
     image: ghcr.io/cardano-scaling/hydraw:latest
+    container_name: hydraw
     profiles:
       - hydraw
     environment:

sample-node-config/aws/scripts/.bash_profile

@@ -50,7 +50,7 @@ function dcfile() {
 }
 
 function ccli() {
-    dc -f ~/docker/docker-compose.yaml exec cardano-node cardano-cli ${@}
+    docker exec -it cardano-node cardano-cli ${@}
 }
 
 function balance() {
@@ -60,3 +60,5 @@ function balance() {
 function xbalance() {
     ccli query utxo $(ctag) --address $(cat ~/credentials/external.addr)
 }
+
+alias fuel='~/scripts/create-fuel.sh'

sample-node-config/aws/scripts/configure-testnet.sh

@@ -22,7 +22,7 @@ echo "export NETWORK_MAGIC=$NETWORK_MAGIC" >> ~/.bash_env
 
 # this is manually hardcoded from https://github.com/cardano-scaling/hydra/releases/tag/0.10.0
 # perhaps there would be a way to look those up in the Chain?
-export HYDRA_SCRIPTS_TX_ID=$(jq -r .$NETWORK.hydraScriptsTxId ~/scripts/configure.json)
+export HYDRA_SCRIPTS_TX_ID=$(jq -r '."'$NETWORK'".hydraScriptsTxId' ~/scripts/configure.json)
 echo "export HYDRA_SCRIPTS_TX_ID=$HYDRA_SCRIPTS_TX_ID" >> ~/.bash_env
 
 # Mithril stuff
@@ -33,16 +33,16 @@ echo "export MITHRIL_IMAGE_ID=$MITHRIL_IMAGE_ID" >> ~/.bash_env
 
 docker pull ghcr.io/input-output-hk/mithril-client:$MITHRIL_IMAGE_ID
 
-export AGGREGATOR_ENDPOINT=$(jq -r .$NETWORK.mithril.aggregatorEndpoint ~/scripts/configure.json)
+export AGGREGATOR_ENDPOINT=$(jq -r '."'$NETWORK'".mithril.aggregatorEndpoint' ~/scripts/configure.json)
 echo "export AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT" >> ~/.bash_env
 
-export GENESIS_VERIFICATION_KEY_URL=$(jq -r .$NETWORK.mithril.genesisVerificationKeyURL ~/scripts/configure.json)
+export GENESIS_VERIFICATION_KEY_URL=$(jq -r '."'$NETWORK'".mithril.genesisVerificationKeyURL' ~/scripts/configure.json)
 echo "export GENESIS_VERIFICATION_KEY_URL=$GENESIS_VERIFICATION_KEY_URL" >> ~/.bash_env
 
 export GENESIS_VERIFICATION_KEY=$(wget -q -O - $GENESIS_VERIFICATION_KEY_URL)
 echo "export GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY" >> ~/.bash_env
 
-export ANCILLARY_VERIFICATION_KEY_URL=$(jq -r .$NETWORK.mithril.ancillaryVerificationKeyURL ~/scripts/configure.json)
+export ANCILLARY_VERIFICATION_KEY_URL=$(jq -r '."'$NETWORK'".mithril.ancillaryVerificationKeyURL' ~/scripts/configure.json)
 echo "export GENESIS_VERIFICATION_KEY_URL=$GENESIS_VERIFICATION_KEY_URL" >> ~/.bash_env
 
 export ANCILLARY_VERIFICATION_KEY=$(wget -q -O - $ANCILLARY_VERIFICATION_KEY_URL)
@@ -52,16 +52,16 @@ export SNAPSHOT_DIGEST=$(curl -s $AGGREGATOR_ENDPOINT/artifact/snapshots | jq -r
 echo "export SNAPSHOT_DIGEST=$SNAPSHOT_DIGEST" >> ~/.bash_env
 
 mithril_client () {
-  docker run --rm -e NETWORK=$NETWORK -e GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY -e ANCILLARY_VERIFICATION_KEY=$ANCILLARY_VERIFICATION_KEY -e AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT --name='mithril-client' -v $(pwd):/app/data -u $(id -u) ghcr.io/input-output-hk/mithril-client:$MITHRIL_IMAGE_ID $@
+  docker run --rm --workdir /app/data -e NETWORK=$NETWORK -e GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY -e ANCILLARY_VERIFICATION_KEY=$ANCILLARY_VERIFICATION_KEY -e AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT --name='mithril-client' -v $(pwd):/app/data -u $(id -u) ghcr.io/input-output-hk/mithril-client:$MITHRIL_IMAGE_ID $@
 }
 
 echo "Restoring snapshot $SNAPSHOT_DIGEST"
 # Show detailed information about a snapshot
-mithril_client --origin-tag HYDRA snapshot show $SNAPSHOT_DIGEST
+mithril_client cardano-db snapshot show $SNAPSHOT_DIGEST
 # Download the given snapshot and verify the certificate
 # This downloads and restores a snapshot
-mithril_client --origin-tag HYDRA snapshot download $SNAPSHOT_DIGEST
+mithril_client cardano-db download $SNAPSHOT_DIGEST
 
 # FIXME
-# mv -f ./$NETWORK/${SNAPSHOT_DIGEST}/db network/
+mv -f ./db network/
 

sample-node-config/aws/scripts/configure.json

@@ -26,4 +26,4 @@
     },
     "tag": "--mainnet"
   }
-}
+}

sample-node-config/aws/scripts/create-fuel.sh

@@ -0,0 +1,75 @@
+    #!/usr/bin/env bash
+    #
+    # Creates a "fuel" UTxO for a Hydra Head from the largest UTxO in the wallet.
+    # This script is an adaptation of the one found in the gcp/scripts directory.
+
+    set -e
+
+    source ~/.bash_profile
+
+    # --- Configuration ---
+    # The signing key for the wallet.
+    SK_FILE=~/credentials/cardano-key.sk
+
+    # The address of the wallet.
+    ADDR=$(cat ~/credentials/cardano.addr)
+
+    # The amount of lovelace to place in the fuel UTxO.
+    # We'll use 10 ADA here. The rest will be returned as change.
+    FUEL_AMOUNT=10000000
+
+    # The required datum hash for a fuel UTxO.
+    FUEL_DATUM_HASH="a654fb60d21c1fed48db2c320aa6df9737ec0204c0ba53b9b94a09fb40e757f3"
+
+    echo "- Using address: ${ADDR}"
+    echo "- Using signing key: ${SK_FILE}"
+
+    # --- Find largest UTxO to use as input ---
+    echo ""
+    echo "- Querying wallet UTxOs..."
+    UTXO_JSON=$(ccli query utxo $(ctag) --address ${ADDR} --out-file /dev/stdout)
+
+    if [ -z "$UTXO_JSON" ] || [ "$UTXO_JSON" == "{}" ]; then
+      echo "!! ERROR: No UTxOs found at address ${ADDR}."
+      echo "!! Please use the faucet to fund this address first."
+      exit 1
+    fi
+
+    # Find the UTxO with the most lovelace to use as input
+    TX_IN=$(echo "${UTXO_JSON}" | jq -r 'to_entries | max_by(.value.value.lovelace) | .key')
+    TOTAL_LOVELACE=$(echo "${UTXO_JSON}" | jq -r ".\"${TX_IN}\".value.lovelace")
+
+    echo "- Found largest UTxO:"
+    echo "  - TxIn: ${TX_IN}"
+    echo "  - Lovelace: ${TOTAL_LOVELACE}"
+
+    if [ "${TOTAL_LOVELACE}" -lt "${FUEL_AMOUNT}" ]; then
+        echo "!! ERROR: Insufficient funds. Largest UTxO has ${TOTAL_LOVELACE} lovelace, but need at least ${FUEL_AMOUNT}."
+        exit 1
+    fi
+
+    # --- Build, Sign, and Submit Transaction ---
+    TMP_TX_FILE=$(mktemp)
+
+    echo ""
+    echo "- Building transaction..."
+    ccli transaction build \
+      --babbage-era \
+      --tx-in "${TX_IN}" \
+      --tx-out "${ADDR}+${FUEL_AMOUNT}" \
+      --tx-out-datum-hash "${FUEL_DATUM_HASH}" \
+      --change-address "${ADDR}" \
+      --out-file "${TMP_TX_FILE}.raw"
+
+    echo "- Signing transaction..."
+    ccli transaction sign \
+      --tx-body-file "${TMP_TX_FILE}.raw" \
+      --signing-key-file "${SK_FILE}" \
+      --out-file "${TMP_TX_FILE}.signed"
+
+    echo "- Submitting transaction..."
+    ccli transaction submit --tx-file "${TMP_TX_FILE}.signed"
+
+    echo ""
+    echo "✔ Transaction submitted successfully!"
+    echo "Wait a minute and check your new balance with the 'balance' command."