Building and signing transactions

Transactions vary in complexity, depending on their intended outcomes, but all transactions share the following attributes:
  • Input (tx-in) - The UTXO's we are trying to spend. It is simply the output of an earlier transaction. A transaction can have multiple inputs.
  • Output (tx-out)- Determines where the funds go to. An output is given by a payment address and an amount. A transaction can have multiple outputs. For a transaction to be well balanced outputs + transaction fees = inputs
Building a raw transaction
Before submitting a transaction, it must be built and signed. Create a raw file that contains all relevant data for the transaction.
$ cardano-cli transaction build-raw
Usage: cardano-cli transaction build-raw
[ --byron-era
| --shelley-era
| --allegra-era
| --mary-era
| --alonzo-era
| --babbage-era
]
[--script-valid | --script-invalid]
(--tx-in TX-IN
[ --spending-tx-in-reference TX-IN
--spending-plutus-script-v2
( --spending-reference-tx-in-datum-cbor-file CBOR FILE
| --spending-reference-tx-in-datum-file JSON FILE
| --spending-reference-tx-in-datum-value JSON VALUE
| --spending-reference-tx-in-inline-datum-present
)
( --spending-reference-tx-in-redeemer-cbor-file CBOR FILE
| --spending-reference-tx-in-redeemer-file JSON FILE
| --spending-reference-tx-in-redeemer-value JSON VALUE
)
--spending-reference-tx-in-execution-units (INT, INT)
| --simple-script-tx-in-reference TX-IN
| --tx-in-script-file FILE
[
( --tx-in-datum-cbor-file CBOR FILE
| --tx-in-datum-file JSON FILE
| --tx-in-datum-value JSON VALUE
| --tx-in-inline-datum-present
)
( --tx-in-redeemer-cbor-file CBOR FILE
| --tx-in-redeemer-file JSON FILE
| --tx-in-redeemer-value JSON VALUE
)
--tx-in-execution-units (INT, INT)]
])
[--read-only-tx-in-reference TX-IN]
[--tx-in-collateral TX-IN]
[--tx-out-return-collateral ADDRESS VALUE]
[--tx-total-collateral INTEGER]
[--required-signer FILE | --required-signer-hash HASH]
[--tx-out ADDRESS VALUE
[ --tx-out-datum-hash HASH
| --tx-out-datum-hash-cbor-file CBOR FILE
| --tx-out-datum-hash-file JSON FILE
| --tx-out-datum-hash-value JSON VALUE
| --tx-out-datum-embed-cbor-file CBOR FILE
| --tx-out-datum-embed-file JSON FILE
| --tx-out-datum-embed-value JSON VALUE
| --tx-out-inline-datum-cbor-file CBOR FILE
| --tx-out-inline-datum-file JSON FILE
| --tx-out-inline-datum-value JSON VALUE
]
[--tx-out-reference-script-file FILE]]
[--mint VALUE
( --mint-script-file FILE
[
( --mint-redeemer-cbor-file CBOR FILE
| --mint-redeemer-file JSON FILE
| --mint-redeemer-value JSON VALUE
)
--mint-execution-units (INT, INT)]
| --simple-minting-script-tx-in-reference TX-IN --policy-id HASH
| --mint-tx-in-reference TX-IN
--mint-plutus-script-v2
( --mint-reference-tx-in-redeemer-cbor-file CBOR FILE
| --mint-reference-tx-in-redeemer-file JSON FILE
| --mint-reference-tx-in-redeemer-value JSON VALUE
)
--mint-reference-tx-in-execution-units (INT, INT)
--policy-id HASH
)]
[--invalid-before SLOT]
[--invalid-hereafter SLOT]
[--fee LOVELACE]
[--certificate-file CERTIFICATEFILE
[ --certificate-script-file FILE
[
( --certificate-redeemer-cbor-file CBOR FILE
| --certificate-redeemer-file JSON FILE
| --certificate-redeemer-value JSON VALUE
)
--certificate-execution-units (INT, INT)]
| --certificate-tx-in-reference TX-IN
--certificate-plutus-script-v2
( --certificate-reference-tx-in-redeemer-cbor-file CBOR FILE
| --certificate-reference-tx-in-redeemer-file JSON FILE
| --certificate-reference-tx-in-redeemer-value JSON VALUE
)
--certificate-reference-tx-in-execution-units (INT, INT)
]]
[--withdrawal WITHDRAWAL
[ --withdrawal-script-file FILE
[
( --withdrawal-redeemer-cbor-file CBOR FILE
| --withdrawal-redeemer-file JSON FILE
| --withdrawal-redeemer-value JSON VALUE
)
--withdrawal-execution-units (INT, INT)]
| --withdrawal-tx-in-reference TX-IN
--withdrawal-plutus-script-v2
( --withdrawal-reference-tx-in-redeemer-cbor-file CBOR FILE
| --withdrawal-reference-tx-in-redeemer-file JSON FILE
| --withdrawal-reference-tx-in-redeemer-value JSON VALUE
)
--withdrawal-reference-tx-in-execution-units (INT, INT)
]]
[--json-metadata-no-schema | --json-metadata-detailed-schema]
[--auxiliary-script-file FILE]
[--metadata-json-file FILE | --metadata-cbor-file FILE]
[--genesis FILE | --protocol-params-file FILE]
[--update-proposal-file FILE]
[--cddl-format | --cli-format]
--out-file FILE
Build a transaction (low-level, inconvenient)
Please note the order of some cmd options is crucial. If used incorrectly may produce undesired tx body. See nested [] notation above for details.
Fee calculation
Every transaction on the blockchain carries a fee, which needs to be calculated each time. This fee calculation requires protocol parameters.
cardano-cli query protocol-parameters
Usage: cardano-cli query protocol-parameters
[ --shelley-mode
| --byron-mode [--epoch-slots NATURAL]
| --cardano-mode [--epoch-slots NATURAL]
]
(--mainnet | --testnet-magic NATURAL)
[--out-file FILE]
Get the node's current protocol parameters
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)
--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)
--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
cardano-cli transaction calculate-min-fee
Usage: cardano-cli transaction calculate-min-fee --tx-body-file FILE
[--mainnet | --testnet-magic NATURAL]
(--genesis FILE | --protocol-params-file FILE)
--tx-in-count NATURAL
--tx-out-count NATURAL
--witness-count NATURAL
[--byron-witness-count NATURAL]
Calculate the minimum fee for a transaction.
Available options:
--tx-body-file FILE Input filepath of the JSON TxBody.
--mainnet Use the mainnet magic id.
--testnet-magic NATURAL Specify a testnet magic id.
--genesis FILE [TESTING] The genesis file to take initial protocol
parameters from. For test clusters only, since the
parameters are going to be obsolete for production
clusters.
--protocol-params-file FILE
Filepath of the JSON-encoded protocol parameters file
--tx-in-count NATURAL The number of transaction inputs.
--tx-out-count NATURAL The number of transaction outputs.
--witness-count NATURAL The number of Shelley key witnesses.
--byron-witness-count NATURAL
The number of Byron key witnesses (default is 0).
-h,--help Show this help text
Signing a transaction
A transaction must prove that it has the right to spend its inputs. Most commonly, this means that a transaction must be signed by the signing keys belonging to the payment addresses of the inputs. If a transaction contains certificates, it must additionally be signed by somebody with the right to issue those certificates. For example, a stake address registration certificate must be signed by the signing key of the corresponding stake key pair.
cardano-cli transaction sign
Usage: cardano-cli transaction sign (--tx-body-file FILE | --tx-file FILE)
(--signing-key-file FILE [--address STRING])
[--mainnet | --testnet-magic NATURAL]
--out-file FILE
Sign a transaction
Available options:
--tx-body-file FILE Input filepath of the JSON TxBody.
--tx-file FILE Input filepath of the JSON Tx.
--signing-key-file FILE Input filepath of the signing key (one or more).
--address STRING Byron address (Base58-encoded).
--mainnet Use the mainnet magic id.
--testnet-magic NATURAL Specify a testnet magic id.
--out-file FILE Output filepath of the JSON Tx.
-h,--help Show this help text
Submit a transaction
Submitting a transaction means sending the signed transaction through the local node whose Unix domain socket is obtained from the CARDANO_NODE_SOCKET_PATH enviromnent variable.
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
Submit a transaction to the local node whose Unix domain socket is obtained
from the CARDANO_NODE_SOCKET_PATH environment 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)
--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)
--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.
-h,--help Show this help text
QUESTIONS AND FEEDBACK
If you have any questions and suggestions while taking the lessons please feel free to ask in the forum and we will respond as soon as possible.