Building and signing transactions

Transactions vary in complexity, depending on their intended outcomes, but all transactions share a number of attributes:

  • Input - contains funds that are spent by the transaction. It is simply the output of an earlier transaction. A transaction can have multiple inputs.

  • Output - determines where the funds go to. An output is given by a payment address and an amount. A transaction can have multiple outputs.

  • Payment address - an address that can receive payments. This is the only type of address that can be specified in a transaction output.

  • Payment and stake key pairs - sets of files containing a public verification key and a private signing key.

  • Time-to-live (TTL) - represents a slot, or deadline by which a transaction must be submitted. The TTL is an absolute slot number, rather than a relative one, which means that the --ttl value should be greater than the current slot number. A transaction becomes invalid once its ttl expires.

When building and submitting a transaction you need to check the current tip of the blockchain, for example, if the tip is slot 4000, and you want to submit a transaction to send some ADA, you should set the TTL to 4100, so that you have enough time to build and submit a transaction. Submitting a transaction with a TTL set in the past would result in a tx submission error.

Building a raw transaction

Before submitting a transaction, it must be built. Create a raw file that contains all relevant data for the transaction:

cardano-cli transaction build-raw \
--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 ouput transaction as Address+Lovelace where
Address is the Bech32-encoded address followed by the
amount in Lovelace.
--ttl SLOT Time to live (in slots).
--fee LOVELACE The fee amount in Lovelace.
--certificate-file FILE Filepath of the certificate. This encompasses all
types of certificates (stake pool certificates, stake
key certificates etc)
--withdrawal WITHDRAWAL The reward withdrawal as StakeAddress+Lovelace where
StakeAddress is the Bech32-encoded stake address
followed by the amount in Lovelace.
--metadata-json-file FILE
Filepath of the metadata file, in JSON format.
--metadata-cbor-file FILE
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.

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 \
--shelley-mode For talking to a node running in Shelley-only mode
(default).
--byron-mode For talking to a node running in Byron-only mode.
--epoch-slots NATURAL The number of slots per epoch (default is 21600).
--security-param NATURAL The security parameter (default is 2160).
--cardano-mode For talking to a node running in full Cardano mode.
--epoch-slots NATURAL The number of slots per epoch (default is 21600).
--security-param NATURAL The security parameter (default is 2160).
--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.
cardano-cli transaction calculate-min-fee \
--tx-body-file FILE Input filepath of the TxBody.
--mainnet Use the mainnet magic id.
--testnet-magic NATURAL Specify a testnet magic id.
--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.

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 \
--tx-body-file FILE Input filepath of the TxBody.
--signing-key-file FILE Input filepath of the signing key (one or more).
--mainnet Use the mainnet magic id.
--testnet-magic NATURAL Specify a testnet magic id.
--out-file FILE Output filepath of the Tx.

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
--shelley-mode For talking to a node running in Shelley-only mode
(default).
--byron-mode For talking to a node running in Byron-only mode.
--epoch-slots NATURAL The number of slots per epoch (default is 21600).
--security-param NATURAL The security parameter (default is 2160).
--cardano-mode For talking to a node running in full Cardano mode.
--epoch-slots NATURAL The number of slots per epoch (default is 21600).
--security-param NATURAL The security parameter (default is 2160).
--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.

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.