Skip to content

Commit

Permalink
CLI Documentation: Update for Conway ledger era (#1384)
Browse files Browse the repository at this point in the history 
* Update tutorials to use conway era

* Add query proposals
  • Loading branch information
@CarlosLopezDeLara
CarlosLopezDeLara authored Jan 22, 2025
1 parent 866695c commit c7d7995
Show file tree
Hide file tree
Showing 26 changed files with 305 additions and 300 deletions.
39 changes: 19 additions & 20 deletions docs/get-started/cardano-cli/get-started/deregister-stake-address.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,6 @@ description: How to deregister a stake address.
keywords: [cardano-cli, cli, deregistration, deregister, rewards, withdrawal, stake, stake addresses, cardano-node, transactions]
---

:::tip
To integrate the Conway era, which differs significantly from previous eras, `cardano-cli` has introduced `<era>` as a top-level command, replacing the former `<era>` flags. For example, instead of using era-specific flags like `--babbage-era` with commands such as `cardano-cli transaction build --babbage-era`, users must now utilize the syntax `cardano-cli babbage transaction build <options>`.
:::

:::caution
The process outlined below involves transferring funds from the payment address associated with the stake address we plan to deregister. This is followed by withdrawing rewards over several consecutive epochs until the rewards are negligible. Only then do we deregister the stake address. This ensures that all earned rewards are collected.
:::
Expand Down Expand Up @@ -42,7 +38,7 @@ Final step:
Here we only show step 7, previous steps can be performed following the corrsponding tutorial for that particular workflow. To generate the **stake address deregistration certificate** we run:

```
cardano-cli babbage stake-address deregistration-certificate \
cardano-cli conway stake-address deregistration-certificate \
--stake-verification-key-file stake.vkey \
--out-file dereg.cert
```
Expand All @@ -68,18 +64,21 @@ We will submit the deregistration certificate, withdraw the last rewards from th
This is required for withdrawing the rewards still available on `stake.addr`

```
cardano-cli babbage query stake-address-info --address $(< stake.addr)
cardano-cli conway query stake-address-info --address $(< stake.addr)
```
```json
[
{
"address": "stake_test1upfpm2244k8jf00l357t3adp2hzfsuqrwqvleheqjj08uhswme5cn",
"delegation": "pool17navl486tuwjg4t95vwtlqslx9225x5lguwuy6ahc58x5dnm9ma",
"delegationDeposit": 2000000,
"rewardAccountBalance": 291385529
"rewardAccountBalance": 291385529,
"stakeDelegation": "pool1l9u9ss9xtww8qkt4zqda84z945f6tgq4753jqhtdr4r8yaw7d6g",
"voteDelegation": "scriptHash-59aa3f091b3bcef254abfb89aea64973a61b78fdb2ac44839c7ccba8"
}
]

```

and use the syntax `stake_address+balance` with the `--withdrawal` option when building the transaction, for example:
`--withdrawal stake_test1upfpm2244k8jf00l357t3adp2hzfsuqrwqvleheqjj08uhswme5cn+291385529`

Expand All @@ -89,15 +88,15 @@ and use the syntax `stake_address+balance` with the `--withdrawal` option when b
Steps 1 and 2 suggest creating a new payment address and transfer funds to it. On the transaction below, we'll use `new_payment.addr` to pay for the transaction fees.

```
cardano-cli babbage query utxo --address $(< payment.addr)
cardano-cli conway query utxo --address $(< payment.addr)
TxHash TxIx Amount
--------------------------------------------------------------------------------------
77b95d3c0031f918d2dcd796352d123dd3fec9f8599377ef96f1ee0e488f5ec1 0 9997495621 lovelace + TxOutDatumNone
```
#### Get the stake address deposit amount

```
cardano-cli babbage query protocol-parameters | jq .stakeAddressDeposit
cardano-cli conway query protocol-parameters | jq .stakeAddressDeposit
> 2000000
```
Expand All @@ -108,7 +107,7 @@ cardano-cli babbage query protocol-parameters | jq .stakeAddressDeposit
Here we use the information from the above queries to build the transaction:

```
cardano-cli babbage transaction build \
cardano-cli conway transaction build \
--tx-in 77b95d3c0031f918d2dcd796352d123dd3fec9f8599377ef96f1ee0e488f5ec1#0 \
--change-address addr_test1vp9khgeajxw8snjjvaaule727hpytrvpsnq8z7h9t3zeuegh55grh \
--withdrawal stake_test1upfpm2244k8jf00l357t3adp2hzfsuqrwqvleheqjj08uhswme5cn+291385529 \
Expand All @@ -120,10 +119,10 @@ cardano-cli babbage transaction build \
Of course, we could use command substitution and run all the queries within `build`, so this is equivalent:

```
cardano-cli babbage transaction build \
--tx-in "$(cardano-cli babbage query utxo --address "$(< new-payment.addr)" --output-json | jq -r 'keys[0]')" \
cardano-cli conway transaction build \
--tx-in "$(cardano-cli conway query utxo --address "$(< new-payment.addr)" --output-json | jq -r 'keys[0]')" \
--change-address "$(< new-payment.addr)" \
--withdrawal "$(< stake.addr)+$(cardano-cli babbage query stake-address-info --address "$(< stake.addr)" | jq -r .[].rewardAccountBalance)" \
--withdrawal "$(< stake.addr)+$(cardano-cli conway query stake-address-info --address "$(< stake.addr)" | jq -r .[].rewardAccountBalance)" \
--certificate-file dereg.cert \
--witness-override 2 \
--out-file tx.raw
Expand All @@ -135,7 +134,7 @@ Estimated transaction fee: Coin 180505
Inspect the transaction before signing:

```
cardano-cli babbage transaction view --tx-file tx.raw
cardano-cli debug transaction view --tx-file tx.raw
```
```json
{
Expand Down Expand Up @@ -192,13 +191,13 @@ cardano-cli babbage transaction view --tx-file tx.raw
Confirm that the keyHash for the stake address deregistration is correct with:

```
cardano-cli babbage stake-address key-hash --stake-verification-key-file stake.vkey
cardano-cli conway stake-address key-hash --stake-verification-key-file stake.vkey
521da955ad8f24bdff8d3cb8f5a155c49870037019fcdf20949e7e5e
```
All good! Ready to sign the transaction:

```
cardano-cli babbage transaction sign \
cardano-cli conway transaction sign \
--tx-file tx.raw \
--signing-key-file new-payment.skey \
--signing-key-file stake.skey \
Expand All @@ -208,13 +207,13 @@ cardano-cli babbage transaction sign \
And submit it to the chain:

```
cardano-cli babbage transaction submit --tx-file tx.signed
cardano-cli conway transaction submit --tx-file tx.signed
Transaction successfully submitted.
```
To confirm, we query the balance of `new-payment.addr`, rewards are withdrawn and deposit has been returned:

```
cardano-cli babbage query utxo --address $(< new-payment.addr)
cardano-cli conway query utxo --address $(< new-payment.addr)
TxHash TxIx Amount
--------------------------------------------------------------------------------------
c09bf08fdf6ae655d8ba7c5e9f44b5cbe11b6bb9621eabb9b1b08c1b27b987eb 0 10290700645 lovelace + TxOutDatumNone
Expand All @@ -223,6 +222,6 @@ c09bf08fdf6ae655d8ba7c5e9f44b5cbe11b6bb9621eabb9b1b08c1b27b987eb 0 10
If we query the stake address info, we get `[]`, meaning that the deregistration has been sucessful:

```
cardano-cli babbage query stake-address-info --address $(< stake.addr)
cardano-cli conway query stake-address-info --address $(< stake.addr)
[]
```
68 changes: 33 additions & 35 deletions docs/get-started/cardano-cli/get-started/simple-transactions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,6 @@ description: how to create simple transactions with build and build-raw commands
keywords: [cardano-cli, cli, keys, addresses, cardano-node, transactions]
---

:::tip
To integrate the Conway era, which differs significantly from previous eras, `cardano-cli` has introduced `<era>` as a top-level command, replacing the former `<era>` flags. For example, instead of using era-specific flags like `--babbage-era` with commands such as `cardano-cli transaction build --babbage-era`, users now use `cardano-cli babbage transaction build`.
:::

## Simple transactions

Cardano transactions involve consuming one or more Unspent Transaction Outputs (UTXOs) and generating one or more new UTXOs. The most basic transaction type involves transferring ada from one address to another. It is essential to ensure that all transactions are 'well-balanced', meaning that the sum of outputs and transaction fees equals the sum of inputs. This balance ensures the integrity and validity of the transaction. Unbalanced transactions are rejected by the local node.
Expand All @@ -20,24 +16,26 @@ Creating a transaction using the CLI follows a three-step process:
- **Sign:** authenticate the transaction with appropriate signatures
- **Submit:** send the signed transaction to the network for processing.

You'll find commands for these tasks under `cardano-cli babbage transaction`
You'll find commands for these tasks under `cardano-cli conway transaction`

```bash
cardano-cli babbage transaction
Usage: cardano-cli babbage transaction
( build-raw
| build
| sign
| witness
| assemble
| submit
| policyid
| calculate-min-fee
| calculate-min-required-utxo
| hash-script-data
| txid
| view
)
cardano-cli conway transaction
Usage: cardano-cli conway transaction
( build-raw
| build
| build-estimate
| sign
| witness
| assemble
| submit
| policyid
| calculate-min-fee
| calculate-min-required-utxo
| hash-script-data
| txid
)

Transaction commands.
```

`cardano-cli` provides several options for constructing transactions: `transaction build-raw`, `transaction build`, and `build-estimate`. The key difference between these methods lies in their offline and online capabilities, as well as the degree of manual or automatic processing involved.
Expand All @@ -57,15 +55,15 @@ When building a transaction, it's essential to specify the following elements:
To create a transaction using `build-raw`, you will need the protocol parameters. These parameters are necessary for calculating the transaction fee at a later stage. Querying the protocol parameters requires a running node:

```bash
cardano-cli babbage query protocol-parameters --out-file pparams.json
cardano-cli conway query protocol-parameters --out-file pparams.json
```

You also need to know the inputs (UTXOs) you will use. A UTXO is identified by its **transaction hash** (`TxHash`) and **transaction index** (`TxIx`) with the syntax `TxHash#TxIx`. You can only use UTXOs controlled by your `payment.skey`.

To query the UTXOs associated to your `payment.addr`, run:

```bash
cardano-cli babbage query utxo --address $(< payment.addr)
cardano-cli conway query utxo --address $(< payment.addr)

TxHash TxIx Amount
--------------------------------------------------------------------------------------
Expand All @@ -83,7 +81,7 @@ Assume you want to send 1,000,000 lovelace (1,000 ada) from `payment.addr` to a
At this stage, you do not need to worry about the transaction fees. Save the transaction body in the `tx.draft` file:

```shell
cardano-cli babbage transaction build-raw \
cardano-cli conway transaction build-raw \
--tx-in e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \
--tx-out addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30+1000000000 \
--tx-out addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5+8994790937 \
Expand All @@ -96,7 +94,7 @@ cardano-cli babbage transaction build-raw \


```shell
cardano-cli babbage transaction build-raw \
cardano-cli conway transaction build-raw \
--tx-in e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \
--tx-out "$(< payment2.addr)+1000000000" \
--tx-out "$(< payment.addr)+8994790937" \
Expand All @@ -118,7 +116,7 @@ cat tx.draft
Use the `transaction view` command to show the transaction body in a human-readable format:

```shell
cardano-cli babbage transaction view --tx-body-file tx.draft
cardano-cli debug transaction view --tx-body-file tx.draft
```

```json
Expand Down Expand Up @@ -182,7 +180,7 @@ In Cardano, transaction fees are [deterministic](https://iohk.io/en/blog/posts/2
To process a transaction on the network, it must include fees specified within the transaction body. To calculate the exact cost, use the `transaction calculate-min-fee` command, which takes `tx.draft` and `pparams.json` files as inputs. Within this command, specify details like the total number of inputs, outputs, and the required number of signatures. In this case, only one witness, the `payment.skey` signature, is needed:

```shell
cardano-cli babbage transaction calculate-min-fee \
cardano-cli conway transaction calculate-min-fee \
--tx-body-file tx.draft \
--protocol-params-file pparams.json \
--witness-count 1
Expand All @@ -203,7 +201,7 @@ echo $((9994790937 - 1000000000 - 173993))
Re-run `transaction build-raw`, include the fee, and adjust the change (the second tx-out). This completes the transaction body, and conventionally, it is saved into the `tx.raw` file.

```shell
cardano-cli babbage transaction build-raw \
cardano-cli conway transaction build-raw \
--tx-in e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \
--tx-out $(< payment2.addr)+1000000000 \
--tx-out $(< payment.addr)+8994616944 \
Expand All @@ -217,7 +215,7 @@ cardano-cli babbage transaction build-raw \
Sign the transaction with the `transaction sign` command. You must sign with the `payment.skey` that controls the UTXO you are trying to spend. This time, we produce the `tx.signed` file:

```shell
cardano-cli babbage transaction sign \
cardano-cli conway transaction sign \
--tx-body-file tx.raw \
--signing-key-file payment.skey \
--testnet-magic 2 \
Expand All @@ -227,7 +225,7 @@ cardano-cli babbage transaction sign \
Inspecting `tx.signed` with `transaction view` reveals that the `"witnesses"` field is no longer empty; it now contains the signature.

```shell
cardano-cli babbage transaction view --tx-file tx.signed
cardano-cli debug transaction view --tx-file tx.signed
```
```json
{
Expand Down Expand Up @@ -290,7 +288,7 @@ cardano-cli babbage transaction view --tx-file tx.signed
Submitting the transaction means sending it to the blockchain for processing by the stake pools and eventual inclusion in a block. While building and signing a transaction can be done without a running node, submitting the transaction requires an active connection to a running node. Use the `tx.signed` file:

```shell
cardano-cli babbage transaction submit \
cardano-cli conway transaction submit \
--tx-file tx.signed
Transaction successfully submitted.
```
Expand All @@ -313,7 +311,7 @@ c57f25ebf9cf1487b13deeb8449215c499f3d61c2836d84ab92a73b0bbaadd38 1 89
Build the transaction:

```shell
cardano-cli babbage transaction build \
cardano-cli conway transaction build \
--tx-in c57f25ebf9cf1487b13deeb8449215c499f3d61c2836d84ab92a73b0bbaadd38#1 \
--tx-out $(< payment2.addr)+500000000 \
--change-address $(< payment.addr) \
Expand All @@ -328,7 +326,7 @@ Estimated transaction fee: Lovelace 167041
Inspecting `tx.raw` with `transaction view` reveals that the transaction body already includes the fee, and the transaction is already balanced.

```shell
cardano-cli babbage transaction view --tx-file tx.raw
cardano-cli debug transaction view --tx-file tx.raw
```

```json
Expand Down Expand Up @@ -388,15 +386,15 @@ cardano-cli babbage transaction view --tx-file tx.raw
As previously, sign the transaction with the `payment.skey`:

```shell
cardano-cli transaction sign \
cardano-cli conway transaction sign \
--tx-body-file tx.raw \
--signing-key-file payment.skey \
--out-file tx.signed
```
### Submitting the transaction

```shell
cardano-cli transaction submit \
cardano-cli conway transaction submit \
--tx-file tx.signed
Transaction successfully submitted.
```
Expand All @@ -405,7 +403,7 @@ Transaction successfully submitted.
You can parse `cardano-cli` JSON outputs with `jq` to create programmatic workflows. For example, you can parse the output of `query utxo` to obtain the first UTXO associated with the payment address and use it as input (`--tx-in`) in `transaction build`:

```
cardano-cli babbage transaction build \
cardano-cli conway transaction build \
--tx-in $(cardano-cli query utxo --address $(< payment.addr) --output-json | jq -r 'keys[0]') \
--tx-out $(< payment.addr)+500000000 \
--change-address $(< payment.addr) \
Expand Down
Loading

0 comments on commit c7d7995

Please sign in to comment.