From 32f9b27eb85d2032f4671720145455cac7118405 Mon Sep 17 00:00:00 2001 From: Sasha Bogicevic Date: Tue, 16 Apr 2024 17:24:19 +0200 Subject: [PATCH] Add tutorial on blueprint transactions --- docs/docs/blueprint_transaction.md | 193 ++++++++++++++++++++++++ docs/docs/getting-started/quickstart.md | 43 +----- 2 files changed, 199 insertions(+), 37 deletions(-) create mode 100644 docs/docs/blueprint_transaction.md diff --git a/docs/docs/blueprint_transaction.md b/docs/docs/blueprint_transaction.md new file mode 100644 index 00000000000..ba9cfadaa52 --- /dev/null +++ b/docs/docs/blueprint_transaction.md @@ -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. + diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.md index 4da17d38ff7..28d50d49a8b 100644 --- a/docs/docs/getting-started/quickstart.md +++ b/docs/docs/getting-started/quickstart.md @@ -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