This guide does not include transactions with smart contracts, it includes essential commands and transactions with native scripts.
In order to run the node we need to run the command:
Every command will have two versions; one for mainnet and one for preprod testnet, magic number for preprod testnet is 1
Running the commands for mainnet and testnet has a difference; on mainnet we use --mainnet and on testnet --testnet-magic <magic-number>. The commands below will be for mainnet but you can also run them on testnets by changing the above.
To run cardano-cli commands, we need to run export CARDANO_NODE_SOCKET_PATH=/path-to-db/db/node.socket
We need to run this command in every new terminal while the node is running.
To check the latest block on we run on:
The output of this command should be like:
The "syncProgress" is important. It should be 100.00 for you to run the commands below, or you will see out of date outputs. If the "syncProgress" does not change for a while(run the command again to check progress), either your network connection or your node have a problem, check for updated node or configuration files.
Wallet generation command will create six files so I strongly suggest you to run the commands below inside a wallet directory you created. To create a wallet, we need to run these command in a directory for our wallet:
Please keep the payment.skey and stake.skey files secure, these should not be accessible or seen by anyone other than you, or your ADA and tokens will be unsafe.
To check UTXOs we need an address, the address can be found in our wallet directory which is created in the previous step. Please check the payment.skey for the address and run the command below with the address:
The output will look like something like this:
TxHash is the hash of the UTXO and TxIX is the index of the UTXO. The example above seems to have two UTXOs with same hash but different index, that means they are different outputs of the same transaction. The Amount in the first UTXO is 9984402693. That is lovelace and 1 ADA is equal to 1 million lovelace so the amount you see is 9984.402693 ADA.
You do not have to be the owner of the address to see what is inside it, you can check whichever address you want.
All transactions on cardano-cli have three steps; build, sign and submit.
Build:
TXIN is the UTXO with its index and example is: a62402c525785be5b4b3ccc2aa693a56605c1217165ac5a02b2225a3a339d161#0
#0 is the index of the utxo.
Number of input and output utxos can be multiple and also the different address outputs are also supported. Input utxos must be higher than the outputs or the tx.raw will not be created with an error.
The change address should be your own address or you will lose the remaining ADA in your UTXO. The idea is; you have 10 ADA in your UTXO and you want to send 2 ADA to someone, remaining 8 ADA will also be an output as a new UTXO and you should specify where you want it to go.
Cost of the transaction in lovelace will be the output.
Signing:
This process is to sign the transaction you built. All transactions need to be signed with your payment.skey or they cannot be submitted.
Submit:
This process is to submit the transaction to the blockchain. This step is irreversible, until this step you can decide not to do the transaction or create a new one instead.
After this command, it will take 1-2 minutes and you can check your wallet to see the new UTXOs created.
A transaction with native assets ie. NFTs or Tokens is similar to the simple transaction with two differences. One is we need a protocol parameters file. In order to obtain the file you need to run the command below and it will generate the protocol.json file:
The other difference is the --tx-out. Assets on Cardano need to be bounded with ADA and minimum amount is 1 ADA. As you can see there are two --tx-in below. That is because one of them have the native asset and probably 1 ADA and the other one has only ADA. We did this because this transaction will have a fee if we tried to pay it with the 1 ADA bounded with the asset, the output would have less ADA and this transaction would give an error.
The signing and submitting steps are identical with the simple transaction.
Minting process is similar to the transaction with native asset with a difference. But first we need policy script.
Creating Policy Script
To create a policy script we need Public Key Hash(PKH)
PKH is generated by our payment.vkey which is inside our wallet directory. To get our PKH we need to run:
The output will be our public key hash, save it.
Now for the policy script, we create a file any-name.script
This is an example time lock policy script that only allows an asset to be minted before slot 1234. When you check the latest block you will see the slot number, each slot takes exactly 1 second. So you should add how much seconds you need to mint o that number. Adding 600 is useful as it gives you 10 second to submit your minting transaction.
Another example with just a PKH is:
Then we need to create a policy id based on our policy script. To do that, we run:
The output of this will be our policy id, save it. The Policy id and Policy script will be necessary for minting NFTs and Tokens.
Metadata
This step is not essential. In Cardano, the metadata cannot be linked to the native asset, it can be linked to transactions. So we need to add it to the minting transaction. The native asset can change hands in the future but the metadata will not follow the asset. To see the asset's metadata wee need a standard and current standard used is CIP-25 which can be found on: https://cips.cardano.org/cips/cip25/. We can add metadata to our transaction. We need to create json file with the CIP-25 standard. This file will be used during the build step.
Build
Building step is very similar to the transaction with native assets. The differences are --mint and --mint-script-file commands.
Example with time lock and metadata:
This example have --invalid-hereafter and --metadata-json-file commands. First one is needed if your policy script has a time lock and the slot number must be the same number you added to the policy script. Metadata command allows you to add the metadata to your minting transaction.
Example without timelock and metadata:
One important note is "<amount of lovelace> + <amount of token> <PolicyId>.<Token name in hex>" in --tx-out and --mint must be the same.
Signing and Submitting steps are identical with the simple transaction.
All the different ways of node setup can be found on https://github.com/input-output-hk/cardano-node. On this documentation installing with executables will be explained on Linux and MacOS, Windows setup will be added in the future.
Downloading the Executables.
Download from the link above the executables for linux and extract the directory in your preferred location.
Adding Path
In order to run the cardano-node and cardano-cli commands you need to add path of your cardano node directory. Edit ~/.bashrc with sudo privileges and append export PATH="$PATH:/path-to/cardano-node and restart your terminal.
Downloading the Executables.
Download from the link above the executables for MacOS(cardano-node 1.35.4 macOS binaries are currently cannot be downloaded, when you try to get it, linux version is downloaded) and extract the directory in your preferred location.
Adding Path
edit /etc/paths with sudo privileges and append /path-to/cardano-node. and restart your terminal.
After these steps on both operating systems run on of the commands:
in order to check if the cardano-node and cardano-cli is installed and also you can see the version you have.
For both operating systems, download the latest cardano-node binaries from https://github.com/input-output-hk/cardano-node/releases and replace the older node with the downloaded one, if the path to the node is unchanged, the adding path step is not needed.
The most up to date configuration files can be found on https://github.com/input-output-hk/cardano-world.
We need to clone this directory to our computer.
If you check the /cardano-world/docs/environments/ directory you can see you can run mainnet or different testnets. Choose which one you want to run and edit the command above accordingly and your node will be running.
Running testnet can be very useful. You can test your apps and smart contracts without the risk of losing real money and running testnet requires much less resources than mainnet. A computer with 4 GB of ram is enough to run it.
There are three different testnets we can run; testnet, preprod and preview. We will have the instructions to run preprod testnet here because it is widespread but you can also setup the other nodes with the instructions.
Running the node
To run the node we need to create a new directory which is usually called db. The command below is used to run the node and we need to add cardano-world and db paths like shown below.
The preferred-node-to-run is what you want to run ie. preprod, preview.
When you run the node, check the db directory and you will see a file called protocolMagicId. There will be a number inside it, that number is essential for us testnet runners because when we use cardano-cli with the testnets that magic number will be used in almost all command.
Running mainnet requires a lot of resources. We need at least 16 GB of ram, and a drive bigger than 100 GB which should be a solid state drive(SSD). This is where you actually interact with the Cardano blockchain.
Running the Node
To run the node we need to create a new directory which is usually called db. The command below is used to run the node and we need to add cardano-world and db paths like shown below. If you also run a testnet on your computer, they all need their own db directories.
If your node has a problem like it does not start or stop sync at some point, firstly try to run git pull command in your cardano-world directory to get any latest change for the configuration files and if it does not fix the issue check if there is an update for cardano-node in https://github.com/input-output-hk/cardano-node.
You can create your wallets, build transactions, mint tokens on your terminal with cardano-cli if you are running your own node. The guide of cardano-cli can be found on: [[Cardano-CLI Guide]]