diff --git a/cardano-cli/README.md b/cardano-cli/README.md index 0fe2d734339..0792a5c996d 100644 --- a/cardano-cli/README.md +++ b/cardano-cli/README.md @@ -4,18 +4,20 @@ A CLI utility to support a variety of key material operations (genesis, migration, pretty-printing..) for different system generations. The general synopsis is as follows: - ``` + +``` Usage: cardano-cli (Genesis related CMDs | Key related CMDs | Delegation related CMDs | Transaction related CMDs | Local node related CMDs) ``` The top-level commands are as shown below. -``` +```bash $ cardano-cli --help cardano-cli - utility to support a variety of key operations (genesis generation, migration, pretty-printing..) for different system generations. -Usage: cardano-cli (Era based commands | Byron specific commands | Miscellaneous commands) +Usage: cardano-cli (Era based commands | Byron specific commands | + Miscellaneous commands) Available options: --version Show the cardano-cli version @@ -44,12 +46,10 @@ Miscellaneous commands version Show the cardano-cli version ``` -``` - Byron-specific commands -``` -cardano-cli byron --help +```bash +$ cardano-cli byron --help Usage: cardano-cli byron (key | transaction | query | genesis | governance | miscellaneous) Byron specific commands diff --git a/doc/reference/building-and-signing-tx.md b/doc/reference/building-and-signing-tx.md index 707d82d5b28..4fe250f75cd 100644 --- a/doc/reference/building-and-signing-tx.md +++ b/doc/reference/building-and-signing-tx.md @@ -67,15 +67,16 @@ When building and submitting a transaction in the shelley era you need to check Look for the value of `SlotNo` { - "blockNo": 16829, - "headerHash": "3e6f59b10d605e7f59ba8383cb0ddcd42480ddcc0a85d41bad1e4648eb5465ad", - "slotNo": 369200 + "epoch": 259, + "hash": "dbf5104ab91a7a0b405353ad31760b52b2703098ec17185bdd7ff1800bb61aca", + "slot": 26633911, + "block": 5580350 } Therefore, if N = 200 slots - invalid-hereafter = 369200 + 200 - invalid-hereafter = 369400 + invalid-hereafter = 26633911 + 200 + invalid-hereafter = 26634111 **Build the transaction** @@ -85,7 +86,7 @@ This time we include all the paramenters: --tx-in 4e3a6e7fdcb0d0efa17bf79c13aed2b4cb9baf37fb1aa2e39553d5bd720c5c99#4 \ --tx-out $(cat payment2.addr)+100000000 \ --tx-out $(cat payment.addr)+999899832035 \ - --invalid-hereafter 369400 \ + --invalid-hereafter 26634111 \ --fee 167965 \ --out-file tx.raw diff --git a/doc/reference/cardano-node-cli-reference.md b/doc/reference/cardano-node-cli-reference.md index 3246b55b58e..bef26665c95 100644 --- a/doc/reference/cardano-node-cli-reference.md +++ b/doc/reference/cardano-node-cli-reference.md @@ -34,11 +34,11 @@ The `stake-address` command contains the following sub commands: *cardano-cli transaction* The `transaction` command contains the following sub commands: -* `build-raw`: builds a low-level transaction (uses the --cardano-mode, --byron-mode, --shelley mode flags) +* `build-raw`: builds a low-level transaction (uses the `--cardano-mode`, `--byron-mode`, `--shelley-mode` flags) * `sign`: signs the transaction * `assemble` : combines and assembles the transaction witness(es) with a transaction body to create a transaction * `witness`: witnesses a transaction -* `submit`: submits the transaction to the local node whose Unix domain socket is obtained from the CARANO_NODE_SOCKET_PATH environment variable (uses the --cardano-mode, --byron-mode, --shelley mode flags) +* `submit`: submits the transaction to the local node whose Unix domain socket is obtained from the CARANO_NODE_SOCKET_PATH environment variable (uses the `--cardano-mode`, `--byron-mode`, `--shelley-mode` flags) * `calculate-min-fee`: calculates the minimum fee for the transaction * `txid`: retrieves the transaction ID * `policyid`: retrieves the transaction ID diff --git a/doc/reference/shelley-genesis.md b/doc/reference/shelley-genesis.md index 246b5a9a842..d6e2d5f7dcd 100644 --- a/doc/reference/shelley-genesis.md +++ b/doc/reference/shelley-genesis.md @@ -18,6 +18,9 @@ Everything will be done in the Shelley era. ```bash $ cardano-cli +cardano-cli - utility to support a variety of key operations (genesis +generation, migration, pretty-printing..) for different system generations. + Usage: cardano-cli (Era based commands | Byron specific commands | Miscellaneous commands) @@ -105,15 +108,15 @@ So the first step will be to make the genesis keys. ```bash $ cardano-cli genesis key-gen-genesis -Usage: cardano-cli genesis key-gen-genesis --verification-key-file FILEPATH - --signing-key-file FILEPATH +Usage: cardano-cli genesis key-gen-genesis --verification-key-file FILE + --signing-key-file FILE Create a Shelley genesis key pair Available options: - --verification-key-file FILEPATH + --verification-key-file FILE Output filepath of the verification key. - --signing-key-file FILEPATH - Output filepath of the signing key. + --signing-key-file FILE Output filepath of the signing key. + -h,--help Show this help text ``` So let's make two example genesis key pairs @@ -149,14 +152,14 @@ can inspect it using any CBOR tool, e.g. [cbor.me] or the `cardano-cli` itself: ```bash -cardano-cli text-view decode-cbor -Usage: cardano-cli text-view decode-cbor --in-file FILE - [--out-file FILE] +$ cardano-cli text-view decode-cbor +Usage: cardano-cli text-view decode-cbor --in-file FILE [--out-file FILE] Print a TextView file as decoded CBOR. Available options: --in-file FILE CBOR input file. --out-file FILE Optional output file. Default is to write to stdout. + -h,--help Show this help text ``` Like so @@ -189,19 +192,19 @@ So we need to make genesis delegate keys, as many as you made genesis keys ```bash $ cardano-cli genesis key-gen-delegate -Usage: cardano-cli genesis key-gen-delegate --verification-key-file FILEPATH - --signing-key-file FILEPATH - --operational-certificate-issue-counter FILE +Usage: cardano-cli genesis key-gen-delegate --verification-key-file FILE + --signing-key-file FILE + --operational-certificate-issue-counter-file FILE Create a Shelley genesis delegate key pair Available options: - --verification-key-file FILEPATH + --verification-key-file FILE Output filepath of the verification key. - --signing-key-file FILEPATH - Output filepath of the signing key. - --operational-certificate-issue-counter FILE + --signing-key-file FILE Output filepath of the signing key. + --operational-certificate-issue-counter-file FILE The file with the issue counter for the operational certificate. + -h,--help Show this help text ``` Much the same as for genesis keys, but there is an additional output, the @@ -245,15 +248,15 @@ So we need to make genesis initial UTxO keys. ```bash $ cardano-cli genesis key-gen-utxo -Usage: cardano-cli genesis key-gen-utxo --verification-key-file FILEPATH - --signing-key-file FILEPATH +Usage: cardano-cli genesis key-gen-utxo --verification-key-file FILE + --signing-key-file FILE Create a Shelley genesis UTxO key pair Available options: - --verification-key-file FILEPATH + --verification-key-file FILE Output filepath of the verification key. - --signing-key-file FILEPATH - Output filepath of the signing key. + --signing-key-file FILE Output filepath of the signing key. + -h,--help Show this help text ``` We can make as many as is useful. Let's make two. @@ -420,12 +423,13 @@ get the key hash for each key: ```bash $ cardano-cli genesis key-hash -Usage: cardano-cli genesis key-hash --verification-key-file FILEPATH +Usage: cardano-cli genesis key-hash --verification-key-file FILE Print the identifier (hash) of a public key Available options: - --verification-key-file FILEPATH + --verification-key-file FILE Input filepath of the verification key. + -h,--help Show this help text ``` Let's do that for our genesis key and genesis delegate key @@ -459,10 +463,10 @@ initial _addresses_ to the initial values at those address. So we need a command to get the address corresponding to an initial UTxO verification key: ```bash -$ Usage: cardano-cli genesis initial-addr --verification-key-file FILE - (--mainnet | - --testnet-magic NATURAL) - [--out-file FILE] +$ cardano-cli genesis initial-addr +Usage: cardano-cli genesis initial-addr --verification-key-file FILE + (--mainnet | --testnet-magic NATURAL) + [--out-file FILE] Get the address for an initial UTxO based on the verification key Available options: @@ -471,6 +475,7 @@ Available options: --mainnet Use the mainnet magic id. --testnet-magic NATURAL Specify a testnet magic id. --out-file FILE Optional output file. Default is to write to stdout. + -h,--help Show this help text ``` So let's do that for the UTxO key @@ -579,12 +584,10 @@ are for the manual method. ```bash $ cardano-cli genesis create -Usage: cardano-cli genesis create --genesis-dir DIR - [--gen-genesis-keys INT] - [--gen-utxo-keys INT] - [--start-time UTC-TIME] - [--supply LOVELACE] - (--mainnet | --testnet-magic NATURAL) +Usage: cardano-cli genesis create --genesis-dir DIR [--gen-genesis-keys INT] + [--gen-utxo-keys INT] [--start-time UTC-TIME] + [--supply LOVELACE] + (--mainnet | --testnet-magic NATURAL) Create a Shelley genesis file from a genesis template and genesis/delegation/spending keys. @@ -597,9 +600,11 @@ Available options: format. If unspecified, will be the current time +30 seconds. --supply LOVELACE The initial coin supply in Lovelace which will be - evenly distributed across initial stake holders. + evenly distributed across initial, non-delegating + stake holders. --mainnet Use the mainnet magic id. --testnet-magic NATURAL Specify a testnet magic id. + -h,--help Show this help text ``` This command will generate a genesis file. It can also generate all the keys, @@ -867,8 +872,8 @@ We can create stake pool operator keys using: ```bash $ cardano-cli node key-gen Usage: cardano-cli node key-gen --cold-verification-key-file FILE - --cold-signing-key-file FILE - --operational-certificate-issue-counter-file FILE + --cold-signing-key-file FILE + --operational-certificate-issue-counter-file FILE Create a key pair for a node operator's offline key and a new certificate issue counter @@ -880,6 +885,7 @@ Available options: --operational-certificate-issue-counter-file FILE The file with the issue counter for the operational certificate. + -h,--help Show this help text ``` For now we will ignore stake pools however since we need to get the system @@ -890,16 +896,16 @@ bootstrapped with the BFT overlay. There's a command to generate new KES keys ```bash -cardano-cli node key-gen-KES -Usage: cardano-cli node key-gen-KES --verification-key-file FILEPATH - --signing-key-file FILEPATH +$ cardano-cli node key-gen-KES +Usage: cardano-cli node key-gen-KES --verification-key-file FILE + --signing-key-file FILE Create a key pair for a node KES operational key Available options: - --verification-key-file FILEPATH + --verification-key-file FILE Output filepath of the verification key. - --signing-key-file FILEPATH - Output filepath of the signing key. + --signing-key-file FILE Output filepath of the signing key. + -h,--help Show this help text ``` So let's go ahead and create a KES key for our first two nodes @@ -924,15 +930,15 @@ And there's a command to generate new VRF keys ```bash $ cardano-cli node key-gen-VRF -Usage: cardano-cli node key-gen-VRF --verification-key-file FILEPATH - --signing-key-file FILEPATH +Usage: cardano-cli node key-gen-VRF --verification-key-file FILE + --signing-key-file FILE Create a key pair for a node VRF operational key Available options: - --verification-key-file FILEPATH + --verification-key-file FILE Output filepath of the verification key. - --signing-key-file FILEPATH - Output filepath of the signing key. + --signing-key-file FILE Output filepath of the signing key. + -h,--help Show this help text ``` However, the `genesis create` command has already generated VRF keys for you at: `example/delegate-keys/delegate{1,2}.vrf.{vkey,skey}` @@ -949,11 +955,10 @@ the offline key, and copy the resulting certificate to the operational machine. ```bash $ cardano-cli node issue-op-cert Usage: cardano-cli node issue-op-cert (--kes-verification-key STRING | - --kes-verification-key-file FILE) - --cold-signing-key-file FILE - --operational-certificate-issue-counter-file FILE - --kes-period NATURAL - --out-file FILE + --kes-verification-key-file FILE) + --cold-signing-key-file FILE + --operational-certificate-issue-counter-file FILE + --kes-period NATURAL --out-file FILE Issue a node operational certificate Available options: @@ -968,6 +973,7 @@ Available options: certificate. --kes-period NATURAL The start of the KES key validity period. --out-file FILE The output file. + -h,--help Show this help text ``` There's a few things here to understand. @@ -1310,9 +1316,8 @@ command ```bash $ cardano-cli genesis initial-txin Usage: cardano-cli genesis initial-txin --verification-key-file FILE - (--mainnet | - --testnet-magic NATURAL) - [--out-file FILE] + (--mainnet | --testnet-magic NATURAL) + [--out-file FILE] Get the TxIn for an initial UTxO based on the verification key Available options: @@ -1321,6 +1326,7 @@ Available options: --mainnet Use the mainnet magic id. --testnet-magic NATURAL Specify a testnet magic id. --out-file FILE Optional output file. Default is to write to stdout. + -h,--help Show this help text ``` Which we can use with our `example/utxo-keys/utxo1.vkey` @@ -1341,10 +1347,9 @@ the keypair. ```bash $ cardano-cli address key-gen -Usage: cardano-cli address key-gen [--normal-key | --extended-key | - --byron-key] - --verification-key-file FILE - --signing-key-file FILE +Usage: cardano-cli address key-gen [--normal-key | --extended-key | --byron-key] + --verification-key-file FILE + --signing-key-file FILE Create an address key pair. Available options: @@ -1354,6 +1359,7 @@ Available options: --verification-key-file FILE Output filepath of the verification key. --signing-key-file FILE Output filepath of the signing key. + -h,--help Show this help text ``` So let's do it @@ -1368,11 +1374,11 @@ We can now build an address from our key. ```bash $ cardano-cli address build Usage: cardano-cli address build (--payment-verification-key STRING | - --payment-verification-key-file FILE) - [--stake-verification-key STRING | - --stake-verification-key-file FILE] - (--mainnet | --testnet-magic NATURAL) - [--out-file FILE] + --payment-verification-key-file FILE) + [--stake-verification-key STRING | + --stake-verification-key-file FILE] + (--mainnet | --testnet-magic NATURAL) + [--out-file FILE] Build a Shelley payment address, with optional delegation to a stake address. Available options: @@ -1387,6 +1393,7 @@ Available options: --mainnet Use the mainnet magic id. --testnet-magic NATURAL Specify a testnet magic id. --out-file FILE Optional output file. Default is to write to stdout. + -h,--help Show this help text ``` This command can also build payment addresses that are associated with stake @@ -1430,9 +1437,9 @@ Usage: cardano-cli transaction build-raw [--byron-era | --shelley-era | Available options: --byron-era Specify the Byron era - --shelley-era Specify the Shelley era (default) + --shelley-era Specify the Shelley era --allegra-era Specify the Allegra era - --mary-era Specify the Mary era + --mary-era Specify the Mary era (default) --tx-in TX-IN The input transaction as TxId#TxIx where TxId is the transaction hash and TxIx is the index. --tx-out TX-OUT The transaction output as Address+Lovelace where @@ -1462,7 +1469,8 @@ Available options: Filepath of the metadata, in raw CBOR format. --update-proposal-file FILE Filepath of the update proposal. - --out-file FILE Output filepath of the TxBody. + --out-file FILE Output filepath of the JSON TxBody. + -h,--help Show this help text ``` Yes, this is a very inconvenient way to build transactions, but at least you'll @@ -1513,22 +1521,22 @@ inputs from the same address). ```bash $ cardano-cli transaction sign Usage: cardano-cli transaction sign --tx-body-file FILE - (--signing-key-file FILE - [--address STRING] | - --script-file FILE) - [--mainnet | - --testnet-magic NATURAL] - --out-file FILE + (--signing-key-file FILE + [--address STRING] | + --script-file FILE) + [--mainnet | --testnet-magic NATURAL] + --out-file FILE Sign a transaction Available options: - --tx-body-file FILE Input filepath of the TxBody. + --tx-body-file FILE Input filepath of the JSON TxBody. --signing-key-file FILE Input filepath of the signing key (one or more). --address STRING Byron address (Base58-encoded). --script-file FILE Filepath of the script. --mainnet Use the mainnet magic id. --testnet-magic NATURAL Specify a testnet magic id. - --out-file FILE Output filepath of the Tx. + --out-file FILE Output filepath of the JSON Tx. + -h,--help Show this help text ``` In our example we need just the one signature, using the `utxo1.skey`. @@ -1547,24 +1555,22 @@ Finally we need to submit the signed transaction ```bash $ cardano-cli transaction submit Usage: cardano-cli transaction submit [--shelley-mode | --byron-mode - [--epoch-slots NATURAL] | - --cardano-mode - [--epoch-slots NATURAL]] - (--mainnet | - --testnet-magic NATURAL) - --tx-file FILE + [--epoch-slots NATURAL] | + --cardano-mode [--epoch-slots NATURAL]] + (--mainnet | --testnet-magic NATURAL) + --tx-file FILE Submit a transaction to the local node whose Unix domain socket is obtained from the CARDANO_NODE_SOCKET_PATH enviromnent variable. Available options: --shelley-mode For talking to a node running in Shelley-only mode. --byron-mode For talking to a node running in Byron-only mode. - --epoch-slots NATURAL The number of slots per epoch for the Byron - era. (default: 21600) + --epoch-slots NATURAL The number of slots per epoch for the Byron era. + (default: 21600) --cardano-mode For talking to a node running in full Cardano mode (default). - --epoch-slots NATURAL The number of slots per epoch for the Byron - era. (default: 21600) + --epoch-slots NATURAL The number of slots per epoch for the Byron era. + (default: 21600) --mainnet Use the mainnet magic id. --testnet-magic NATURAL Specify a testnet magic id. --tx-file FILE Filepath of the transaction you intend to submit. @@ -1581,8 +1587,7 @@ CARDANO_NODE_SOCKET_PATH=example/node1/node.sock \ cardano-cli transaction submit \ --shelley-mode \ --tx-file example/tx1.tx \ - --testnet-magic 42 \ - --shelley-mode + --testnet-magic 42 ``` If we now go look at the node logs (or stdout) for node1 we should see that @@ -1596,7 +1601,6 @@ CARDANO_NODE_SOCKET_PATH=example/node1/node.sock \ cardano-cli query utxo \ --shelley-mode \ --testnet-magic 42 \ - --shelley-mode \ --address addr_test1vzrqr58zm3un86sfeze6039gj8v406p3zt4su0qkemc5vyqrs09az TxHash TxIx Lovelace diff --git a/doc/stake-pool-operations/KES_period.md b/doc/stake-pool-operations/KES_period.md index d2f25a7fb91..e79c40b7110 100644 --- a/doc/stake-pool-operations/KES_period.md +++ b/doc/stake-pool-operations/KES_period.md @@ -25,15 +25,16 @@ We check the current tip of the blockchain: cardano-cli query tip --mainnet { - "blockNo": 36914, - "headerHash": "58df595137e71c0fa65edc99add11704b00e5f163475bd804e4bd59c126bfc9b", - "slotNo": 8520857 + "epoch": 259, + "hash": "dbf5104ab91a7a0b405353ad31760b52b2703098ec17185bdd7ff1800bb61aca", + "slot": 26633911, + "block": 5580350 } -In this example, we are currently in slot 8520857, and we know from the genesis file that one period lasts for 129600 slots. So we calculate the current period by +In this example, we are currently in slot 26633911, and we know from the genesis file that one period lasts for 129600 slots. So we calculate the current period by - expr 8520857 / 129600 - > 65 + expr 26633911 / 129600 + > 205 With this we are able to generate an operational certificate for our stake pool: @@ -41,5 +42,5 @@ With this we are able to generate an operational certificate for our stake pool: --kes-verification-key-file kes.vkey \ --cold-signing-key-file cold.skey \ --operational-certificate-issue-counter cold.counter \ - --kes-period 65 \ + --kes-period 205 \ --out-file node.cert diff --git a/doc/stake-pool-operations/getConfigFiles_AND_Connect.md b/doc/stake-pool-operations/getConfigFiles_AND_Connect.md index 559a52682f5..7704cce442a 100644 --- a/doc/stake-pool-operations/getConfigFiles_AND_Connect.md +++ b/doc/stake-pool-operations/getConfigFiles_AND_Connect.md @@ -56,18 +56,19 @@ To start a passive node: **Replace x.x.x.x with your public IP and indicate the correct paths to the required files.** -Many commands relay on the environment variable CARDANO_NODE_SOCKET_PATH: +Many commands rely on the environment variable CARDANO_NODE_SOCKET_PATH: export CARDANO_NODE_SOCKET_PATH=path/to/db/node.socket -Check that the node is syncing by fetching the current tip. When syncing slotNo should be increasing. +Check that the node is syncing by fetching the current tip. When syncing `slot` should be increasing. - cardano-cli query tip --mainnet + cardano-cli query tip --mainnet - { - "blockNo": 36322, - "headerHash": "3f1bea22be21452415851ae670f4bac9340471cb7f2f6a664fac56d7f60dbaad", - "slotNo": 888561 - } + { + "epoch": 259, + "hash": "dbf5104ab91a7a0b405353ad31760b52b2703098ec17185bdd7ff1800bb61aca", + "slot": 26633911, + "block": 5580350 + } **Note**`--mainnet` identifies the Cardano mainnet, for testnets use `--testnet-magic 1097911063` instead. diff --git a/doc/stake-pool-operations/node_keys.md b/doc/stake-pool-operations/node_keys.md index dcfe49f3fd1..c9334243095 100644 --- a/doc/stake-pool-operations/node_keys.md +++ b/doc/stake-pool-operations/node_keys.md @@ -69,15 +69,16 @@ Then we need the current tip of the blockchain: cardano-cli query tip --mainnet { - "blockNo": 36929, - "headerHash": "44c2a2be237ea485c15bf2a50c12b4d2aabe6d4233cb1b2131efc080615a17d0", - "slotNo": 906528 + "epoch": 259, + "hash": "dbf5104ab91a7a0b405353ad31760b52b2703098ec17185bdd7ff1800bb61aca", + "slot": 26633911, + "block": 5580350 } -Look for Tip `slotNo` value. In this example we are on slot 906528. So we have KES period is 251: +Look for tip `slot` value. In this example we are on slot `26633911`. So we have KES period is `7398`: - expr 906528 / 3600 - > 251 + expr 26633911 / 3600 + > 7398 To generate the certificate: @@ -85,7 +86,7 @@ To generate the certificate: --kes-verification-key-file kes.vkey \ --cold-signing-key-file cold.skey \ --operational-certificate-issue-counter cold.counter \ - --kes-period 251 \ + --kes-period 7398 \ --out-file node.cert #### Move the cold keys to secure storage and remove them from your local machine. diff --git a/doc/stake-pool-operations/simple_transaction.md b/doc/stake-pool-operations/simple_transaction.md index 3bec526c44b..c068447e2fb 100644 --- a/doc/stake-pool-operations/simple_transaction.md +++ b/doc/stake-pool-operations/simple_transaction.md @@ -86,15 +86,16 @@ Query the tip of the blockchain: cardano-cli query tip --mainnet -Look for the value of `slotNo` +Look for the value of `slot` { - "blockNo": 16829, - "headerHash": "3e6f59b10d605e7f59ba8383cb0ddcd42480ddcc0a85d41bad1e4648eb5465ad", - "slotNo": 369200 + "epoch": 259, + "hash": "dbf5104ab91a7a0b405353ad31760b52b2703098ec17185bdd7ff1800bb61aca", + "slot": 26633911, + "block": 5580350 } -Calculate your TTL, for example: 369200 + 200 slots = 369400 +Calculate your `invalid-hereafter`, for example: 26633911 + 200 slots = 26634111 #### Build the transaction @@ -104,7 +105,7 @@ We write the transaction in a file, we will name it `tx.raw`. --tx-in 4e3a6e7fdcb0d0efa17bf79c13aed2b4cb9baf37fb1aa2e39553d5bd720c5c99#4 \ --tx-out $(cat payment2.addr)+10000000 \ --tx-out $(cat payment.addr)+9832035 \ - --invalid-hereafter 369400 \ + --invalid-hereafter 26634111 \ --fee 167965 \ --out-file tx.raw