Skip to content

Commit

Permalink
Add tutorial on blueprint transactions
Browse files Browse the repository at this point in the history
  • Loading branch information
@v0d1ch
v0d1ch committed Apr 16, 2024
1 parent 3a9fc2c commit 32f9b27
Show file tree
Hide file tree
Showing 2 changed files with 199 additions and 37 deletions.
193 changes: 193 additions & 0 deletions docs/docs/blueprint_transaction.md
View file
@@ -0,0 +1,193 @@
---
sidebar_position: 99
---

### Commit using blueprint transaction

This is a small walk-through on how to use `cardano-cli` to assemble everything needed to commit funds to a `Head` using blueprint transaction.

Example assumes you have the hydra-node repo at your disposal together with `hydra-node`, `hydra-tui`, `cardano-cli` and `curl` binaries.

We can use `cardano-cli` to create a _blueprint_ transaction from some `UTxO` we own.

First we need a running cardano-node so let's spin one on the preprod 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:

```shell
cardano-cli address build \
--payment-verification-key-file hydra-cluster/config/credentials/alice-funds.vk \
--testnet-magic 1

addr_test1vp5cxztpc6hep9ds7fjgmle3l225tk8ske3rmwr9adu0m6qchmx5z
```

and query to see what `UTxO` Alice has:

```shell
cardano-cli query utxo \
--socket-path testnets/preprod/node.socket \
--address addr_test1vp5cxztpc6hep9ds7fjgmle3l225tk8ske3rmwr9adu0m6qchmx5z \
--testnet-magic 1 \
--output-json

{
"14ab373afb1112d925b0f6a84518ac26d4a8cfcc99231e1f47e6996182e843a9#0": {
"address": "addr_test1vp5cxztpc6hep9ds7fjgmle3l225tk8ske3rmwr9adu0m6qchmx5z",
"datum": null,
"datumhash": null,
"inlineDatum": null,
"referenceScript": null,
"value": {
"lovelace": 8000000
}
},
"14ab373afb1112d925b0f6a84518ac26d4a8cfcc99231e1f47e6996182e843a9#1": {
"address": "addr_test1vp5cxztpc6hep9ds7fjgmle3l225tk8ske3rmwr9adu0m6qchmx5z",
"datum": null,
"datumhash": null,
"inlineDatum": null,
"referenceScript": null,
"value": {
"lovelace": 1828427
}
},
}
```

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.

```shell
cardano-cli transaction build-raw \
--babbage-era \
--tx-in 14ab373afb1112d925b0f6a84518ac26d4a8cfcc99231e1f47e6996182e843a9#0 \
--tx-out addr_test1vp5cxztpc6hep9ds7fjgmle3l225tk8ske3rmwr9adu0m6qchmx5z+5000000 \
--fee 0 \
--out-file tx.json
```

We will also need pre-calculated tx-id:

```shell
cardano-cli transaction txid --tx-body-file tx.json

3e94dc4236b76cfc543e662e80b93adfa11aa9b75535dad2d0c8d59963b52f9c
```

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:

- 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.


Query the preview protocol-parameters:

```shell
cardano-cli query protocol-parameters \
--testnet-magic 1 \
--socket-path testnets/preprod/node.socket \
--out-file pp-preprod.json

```

Start the `hydra-node` in 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)

```shell
hydra-node \
--node-id 1 --port 5001 --api-port 4001 \
--hydra-signing-key demo/alice.sk \
--hydra-scripts-tx-id 6264cee4d5eab3fb58ab67f3899ecbcc0d7e72732a2d9c1c5d638115db6ca711 \
--cardano-signing-key hydra-cluster/config/credentials/alice.sk \
--ledger-protocol-parameters pp-preprod.json \
--testnet-magic 1 \
--node-socket testnets/preprod/node.socket \
--persistence-dir .
```

Now we can start `hydra-tui` and initialize the `Head`:

```shell
hydra-tui \
--connect 0.0.0.0:4001 \
--cardano-signing-key hydra-cluster/config/credentials/alice-funds.sk \
--testnet-magic 1 \
--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.

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:

```shell
{
"blueprintTx": {
"cborHex": "84a3008182582014ab373afb1112d925b0f6a84518ac26d4a8cfcc99231e1f47e6996182e843a900018182581d6069830961c6af9095b0f2648dff31fa9545d8f0b6623db865eb78fde81a007a12000200a0f5f6",
"description": "",
"txId": "3e94dc4236b76cfc543e662e80b93adfa11aa9b75535dad2d0c8d59963b52f9c",
"type": "Tx BabbageEra"
},
"utxo": {
"14ab373afb1112d925b0f6a84518ac26d4a8cfcc99231e1f47e6996182e843a9#0": {
"address": "addr_test1vp5cxztpc6hep9ds7fjgmle3l225tk8ske3rmwr9adu0m6qchmx5z",
"datum": null,
"datumhash": null,
"inlineDatum": null,
"referenceScript": null,
"value": {
"lovelace": 8000000
}
}
}
}
```

Let's save this json to commit-request.json file.

Now, it is time to ask the running `hydra-node` to draft a commit transaction for us:


```
curl -X POST 127.0.0.1:4001/commit \
--data @commit-request.json
```

This yields a large cbor blob which we can save to `commit-tx.json` file.

Now we need to sign and submit the draft commit transaction.

```shell

cardano-cli transaction sign \
--tx-file commit-tx.json \
--signing-key-file hydra-cluster/config/credentials/alice-funds.sk \
--out-file signed-tx.json


cardano-cli transaction submit \
--tx-file signed-tx.json \
--socket-path testnets/preprod/node.socket \
--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.

43 changes: 6 additions & 37 deletions docs/docs/getting-started/quickstart.md
View file
Expand Up @@ -251,52 +251,21 @@ cardano-cli address build --verification-key-file cardano.vk --mainnet
## External commits

While the `hydra-node` holds funds to fuel 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:
- UTxO (belonging to public key or script address) (`SimpleCommitRequest`) OR
- a _blueprint_ transaction together with the `UTxO` which resolves it (`FullCommitRequest`).
- UTxO (belonging to public key or script address) OR
- a _blueprint_ transaction together with the `UTxO` which resolves it.

and eventually returns a draft 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.

Accepting a _blueprint_ transaction gives `hydra-node` users more flexibility since `hydra-node` only adds needed commit transaction data without removing any additional information specified in the _blueprint_ transaction.
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.

## Generating transactions for the WebSocket API
Accepting a _blueprint_ transaction gives dApp builders and other users more flexibility since `hydra-node` only adds needed commit transaction data without removing any additional information specified in the _blueprint_ transaction.

To perform a transaction within an initialized Head via the WebSocket API of Hydra Node, use the commands below and send the output to the node:
> 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`.
```bash title="Transaction building"
cardano-cli transaction build-raw \
--babbage-era \
--tx-in 09d34606abdcd0b10ebc89307cbfa0b469f9144194137b45b7a04b273961add8#687 \
--tx-out addr1vx8apm8x8rla2w6tk7dxnwrlxkmeuera4x4tw5j695xhxeq4wawpz+7620669 \
--fee 0 \
--out-file tx.json
You can take a look at the small example on how to commit to a `Head` using blueprint transaction [here](/docs/blueprint_transaction.md)

cardano-cli transaction sign \
--tx-body-file tx.json \
--signing-key-file cardano.sk \
--out-file signed-tx.json

echo "{ \"tag\": \"NewTx\", \"transaction\": $(cat signed-tx.json | jq ".cborHex") }"
{ "tag": "NewTx", "transaction": "84a3008182582009d34606abdcd0b10ebc89307cbfa0b469f9144194137b45b7a04b273961add81902af0181a200581d618fd0ece638ffd53b4bb79a69b87f35b79e647da9aab7525a2d0d7364011a0074483d0200a10081825820c736d40ee64c031851af26007c00a3b6fcbebccfd333a8ee6f14983f9be5331c58404bae506f5235778ec65eca6fdfcf6ec61ab93420b91e0b71ca82d437904f860e999372cf00252246ca77012e19c344b3af60df9f853af53fc86835f95a119609f5f6" }
```
The `--tx-in` value is a UTxO obtained from the reply to the `{ "tag": "GetUTxO" }` message.
E.g.:
```json title="GetUTxOResponse"
{
"tag": "GetUTxOResponse",
"utxo": {
"09d34606abdcd0b10ebc89307cbfa0b469f9144194137b45b7a04b273961add8#687": {
"address": "addr1w9htvds89a78ex2uls5y969ttry9s3k9etww0staxzndwlgmzuul5",
"value": {
"lovelace": 7620669
}
}
}
}
```

## Example Setup

Expand Down

0 comments on commit 32f9b27

Please sign in to comment.