## **Overview**

**What is Cardano?**

Cardano is a collection of [open-source](https://en.wikipedia.org/wiki/Open_source), patent-free protocols. It's a platform that enables you to store, transform, and manage value, identity, and governance. Cardano follows research not opinions or bias.

**How did it start?**

Cardano started as a significant research and development project in 2015, and it took almost two years of research to get to a position to start writing code.

The purpose of Cardano was to ask: How can we build a sustainable financial and social operating system for billions of people? What collections of technologies do we need to bring together to get everything at an affordable cost?

Besides cryptographic research, there was game-theoretic research, identity-management research, and programming-language research. This academic rigor process produced more than 100 academic papers. Most were accepted in cryptography conferences like Eurocrypt and Asiacrypt and went through the standard peer-review process. For example, the paper “[Ouroboros: A Provably Secure Proof-of-Stake Blockchain Protocol”](https://eprint.iacr.org/2016/889.pdf) was one of the most [cited security papers from 2015-2019.](https://sweis.medium.com/most-cited-security-papers-from-2015-2019-d21515db3681)

**What you need to bring**

To get the most out of the Cardano Developer Portal, you should have programming experience and a basic understanding of blockchain concepts of Cardano such as [UTxO](https://developers.cardano.org/docs/get-started/technical-concepts#unspent-transaction-output-utxo), transactions, addresses, key derivation, and networking.

If you are unfamiliar with these terms, start with technical concepts, and you can complete the stake pool course afterward. It will also help you understand basic concepts, even if you don't want to run a stake pool.

**Cardano is different**

If you have experience with other smart contract platforms and want to start building on Cardano, it is vital to know its differences:

It makes sense to get your head around the concept of UTxO and later the extended UTxO model.
Tokens on Cardano are not built with smart contracts. Instead, tokens are native and live on the ledger. The protocol treats them as first-class citizens, like ada. It is quite different from our peers that don’t have native tokens and need to use a smart contract to send tokens.
Native tokens use the core infrastructure, and the network has to do everything else instead of running a smart contract and calling a method called 'transfer'. On Cardano, you are sending a standard transaction. This removes a layer of extra complexity and the risk of human mistakes, as the ledger handles all token-related functions.
Smart contracts work different on Cardano because of the eUTxO model. Misconceptions were floating around suggesting that Cardano only supports one transaction per block.

**What you can do on Cardano today**

You can send and receive native tokens, including ada.

You can delegate your ada to one of the existing pools and earn rewards.

You can vote with your ada to distribute over a billion dollars worth of ada from the treasury to fund community-driven proposals on Project Catalyst.

You can earn ada rewards by voting on proposals.

You can participate in the Cardano Improvement Proposals (CIP) process.

You can interact with smart contracts.

**Why build on Cardano?**

Cardano offers a better infrastructure to build products because it is faster, more secure, and cost-effective.

Cardano offers accurate cost predictability when it comes to transactions. There are no auctions for transaction fees.

Cardano has an energetic community and more than two million wallets. If you stick to specific standards, we are keen to try out and engage with new products. Participating now makes you a first mover.

Cardano brings its venture fund. If you build on Cardano you can get your project funded. Every 6 to 8 weeks, projects can be proposed, discussed, and voted on by the Cardano community.

Cardano is a proof-of-stake blockchain. By design, it consumes much less energy and computational power.

Cardano is built with the rigor of high-assurance formal development methods. The consensus mechanism Ouroboros was delivered with several peer-reviewed papers presented in top-tier conferences and publications in cybersecurity and cryptography. If you build on Cardano, you build on this foundation.

**What you can build on Cardano today**

You can integrate Cardano into existing websites and services.

You can issue native tokens and NFTs.

You can add metadata to transactions to give transactions a story, a background or even an identity.

You can prove the existence of a file, text or any other data at a specific point in time with transaction metadata. You can even use transaction metadata to validate and verify external physical products and genuine articles.

You can setup, manage and maintain a stake pool on Cardano.

You can create smart contracts.

Overview

## **Cardano Components**

The Cardano blockchain is powered by a flock of inter-connected nodes. The [cardano-node](https://github.com/IntersectMBO/cardano-node) is the software capable of running as a core block producer, as a relay or as a local entry-point to the network. The node itself is made out of several inter-connected component parts:

**[The settlement layer](https://github.com/IntersectMBO/cardano-ledger#cardano-ledger)**: a multi-era ledger implementation derived from a set of formal specifications. This is where the core Cardano entities are defined as well as the rules for using them. This is the bedrock on top of which all other components build upon.

**[The consensus layer:](https://github.com/IntersectMBO/ouroboros-consensus#ouroboros-consensus)** an implementation of the consensus layer of the Ouroboros family of protocols. If you've heard about "The Hard-Fork Combinator", this is where you can find it. For a high-level − albeit technical − introduction, have a look at [The Abstract Nature of The Consensus Layer.](https://iohk.io/en/blog/posts/2020/05/28/the-abstract-nature-of-the-consensus-layer/)

**[The networking layer](https://github.com/IntersectMBO/ouroboros-network/#ouroboros-network)**: a peer-to-peer networking stack geared towards Proof-of-Stake systems. This includes a framework for writing typed protocols with supports for pipelining, multiplexing and various protections against adversarial peers.

**[The scripting layer](https://github.com/IntersectMBO/plutus#plutus-core)**: also known as Plutus, it is a scripting language embedded in the Cardano ledger to provide smart-contract capabilities to the network. At its core, it is a typed Lambda-Calculus which acts as low-level interpreted assembly code.

Cardano Components

## **Installing the node from source**

**Prerequisites**

To set up your platform, you will need:

![](https://media.discordapp.net/attachments/980490396356476938/1334986565692293171/image.png?ex=679e86a0&is=679d3520&hm=b1015be035f8546ae95cc5c76ef21f8e6d3895bfdbe96d9d6687486d2cc54b87&=&format=webp&quality=lossless&width=1445&height=399)


**Note** If you are building on Windows, we recommend using WSL2 under Windows 10 as this provides a development and execution environment that is very similar to Ubuntu.

**System dependencies installation**

To download the source code and build it, you need the following packages and tools on your Linux system:

the version control system git,

the gcc C-compiler,

C++ support for gcc,

developer libraries for the arbitrary precision library gmp,

developer libraries for the compression library zlib,

developer libraries for systemd,

developer libraries for ncurses,

ncurses compatibility libraries,

the Haskell build tool cabal,

the GHC Haskell compiler (version 8.10.7 or above).

In Redhat, Fedora, and Centos:

`sudo yum update -y
sudo yum install git gcc gcc-c++ tmux gmp-devel make tar xz wget zlib-devel libtool autoconf -y
sudo yum install systemd-devel ncurses-devel ncurses-compat-libs which jq openssl-devel lmdb-devel -y`

For Debian/Ubuntu:

`sudo apt-get update -y
sudo apt-get install automake build-essential pkg-config libffi-dev libgmp-dev libssl-dev libtinfo-dev libsystemd-dev zlib1g-dev make g++ tmux git jq wget libncursesw5 libtool autoconf liblmdb-dev -y`

Possible issue with pkg-config:

pkgconf 1.9.5 (which is default in Fedora 39 and Rawhide) produces output unreadable by cabal, which results in an errors like:

`conflict: pkg-config package libsodium-any, not found in the pkg-config database`


despite having libsodium installed in the system.

The possible solutions to this problem are:

to upgrade pkgconf to version 2 by building it from source:

`yum update -y && \
yum install git diffutils gcc gcc-c++ tmux gmp-devel make tar xz wget zlib-devel libtool autoconf -y && \
mkdir -p /root/src/ && cd /root/src && \
curl -O https://distfiles.ariadne.space/pkgconf/pkgconf-2.0.3.tar.xz && \
tar -xvf pkgconf-2.0.3.tar.xz && \
cd pkgconf-2.0.3 && \
./configure && make && make install && \`

to use cabal version (higher than 3.10.2.0) that have these changes already integrated:

[Try each pkg-config query separatedly](https://github.com/haskell/cabal/pull/9134)

[fix pkgconf 1.9 --modversion regression](https://github.com/haskell/cabal/pull/9391)

Optional dependencies that may be required: llvm libnuma-dev

If you are using a different flavor of Linux, you will need to use the correct package manager for your platform instead of yum or apt-get, and the names of the packages you need to install might differ.

For MacOS:

You'll need the following packages and tools on your MacOS system:

[Xcode ](https://developer.apple.com/xcode)- The Apple Development IDE and SDK/Tools

[Xcode Command Line Tools](https://developer.apple.com/xcode/features/), you can install it by typing xcode-select --install in the terminal.

[Homebrew ](https://brew.sh/)- The Missing Package Manager for MacOS (or Linux)

Then using homebrew install the following:

`brew install jq libtool autoconf automake pkg-config openssl`

**You will need to install llvm in case you are using M1**

`brew install llvm@13`


**Installing the Haskell environment**

The recommended way to install the Haskell tools is via GHCup. Its installation script will guide you through the installation, and warn you about packages that you have to make sure are installed in the system (the ones described on the step above). Check this page for further explanation on the installation process.

Once GHCup is installed, open a new terminal (to get an updated environment) and run:

`ghcup install ghc 8.10.7
ghcup install cabal 3.8.1.0
ghcup set ghc 8.10.7
ghcup set cabal 3.8.1.0`

Alternatively, with ghcup tui you can pick the specific versions of the tools that you want to install, in particular you should have installed and set:

cabal >= 3.8.1.0

GHC >= 8.10.7

To check that you will use the GHCup tools (and not any other installation on the system), you can execute

`which cabal`

and it should return a path of this shape: /home/<user>/.ghcup/bin/cabal.

**Installing dependencies**

Decide which version of Cardano Node you will be installing. A list of available tags is available at: https://github.com/IntersectMBO/cardano-node/tags. Set the environment variable to the tag you selected (or use master for the latest unstable version):

`CARDANO_NODE_VERSION='9.2.1'
IOHKNIX_VERSION=$(curl https://raw.githubusercontent.com/IntersectMBO/cardano-node/$CARDANO_NODE_VERSION/flake.lock | jq -r '.nodes.iohkNix.locked.rev')
echo "iohk-nix version: $IOHKNIX_VERSION"`


The variable IOHKNIX_VERSION is used to retrieve the correct versions of sodium, secp256k1 and blst.

caution
Make sure that secp256k1, sodium and blst versions match flake input version in iohkNix for a particular node version used.

**Installing "sodium"**

Cardano uses a custom fork of sodium which exposes some internal functions and adds some other new functions. This fork lives in https://github.com/intersectmbo/libsodium. Users need to install that custom version of sodium with the following steps.

Create a working directory for your builds:

`mkdir -p ~/src
cd ~/src`

Find out the correct sodium version for your build:

`SODIUM_VERSION=$(curl https://raw.githubusercontent.com/input-output-hk/iohk-nix/$IOHKNIX_VERSION/flake.lock | jq -r '.nodes.sodium.original.rev')
echo "Using sodium version: $SODIUM_VERSION"`

Download and install sodium:

`: ${SODIUM_VERSION:='dbb48cc'}
git clone https://github.com/intersectmbo/libsodium
cd libsodium
git checkout $SODIUM_VERSION
./autogen.sh
./configure
make
make check
sudo make install`

Add the following to your ~/.bashrc file and source it (or re-open the terminal):

`export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"`


For some distributions you will also need to configure the dynamic linker. If the executable is linked with the right libsodium.so file (which you can check by running ldd), the running binary might still use the wrong library. You can check this by running pldd. If the pldd shows that the running executable is using the wrong library, run ldconfig.

**Using the ported c code for development
caution**

The ported c code should not be used to run the node, and should only be used for development purposes.

In order to avoid having to install the custom version of libsodium for development purposes, cardano-crypto-praos defines a cabal flag that makes use of C code located here.

The C code is merely a port of the bits missing in a normal libsodium installation. To enable this code, one has to add the following code in the cabal.project.local file:

`package cardano-crypto-praos
  flags: -external-libsodium-vrf`

For this to work, libsodium has to be in the system. For Ubuntu, this is achieved by:

`sudo apt install libsodium-dev`

**Installing secp256k1**

Find out the correct secp256k1 version:

`SECP256K1_VERSION=$(curl https://raw.githubusercontent.com/input-output-hk/iohk-nix/$IOHKNIX_VERSION/flake.lock | jq -r '.nodes.secp256k1.original.ref')
echo "Using secp256k1 version: ${SECP256K1_VERSION}"`

Download and install secp256k1:

`: ${SECP256K1_VERSION:='v0.3.2'}
git clone --depth 1 --branch ${SECP256K1_VERSION} https://github.com/bitcoin-core/secp256k1
cd secp256k1
./autogen.sh
./configure --enable-module-schnorrsig --enable-experimental
make
make check
sudo make install`

**Installing blst**

Find out the correct blst version:

`BLST_VERSION=$(curl https://raw.githubusercontent.com/input-output-hk/iohk-nix/master/flake.lock | jq -r '.nodes.blst.original.ref')
echo "Using blst version: ${BLST_VERSION}"`

Download and install blst so that cardano-base can pick it up (assuming that pkg-config is installed):

`: ${BLST_VERSION:='v0.3.11'}
git clone --depth 1 --branch ${BLST_VERSION} https://github.com/supranational/blst
cd blst
./build.sh
cat > libblst.pc << EOF
prefix=/usr/local
exec_prefix=\${prefix}
libdir=\${exec_prefix}/lib
includedir=\${prefix}/include

Name: libblst
Description: Multilingual BLS12-381 signature library
URL: https://github.com/supranational/blst
Version: ${BLST_VERSION#v}
Cflags: -I\${includedir}
Libs: -L\${libdir} -lblst
EOF
sudo cp libblst.pc /usr/local/lib/pkgconfig/
sudo cp bindings/blst_aux.h bindings/blst.h bindings/blst.hpp  /usr/local/include/
sudo cp libblst.a /usr/local/lib
sudo chmod u=rw,go=r /usr/local/{lib/{libblst.a,pkgconfig/libblst.pc},include/{blst.{h,hpp},blst_aux.h}}`

Installing the node
Downloading the source code for cardano-node
Create a working directory for your builds:

`mkdir -p ~/src
cd ~/src`

Download the Cardano node sources:

`git clone https://github.com/intersectmbo/cardano-node.git`

Change the working directory to the downloaded source code folder:

`cd cardano-node`

Check out the latest version of cardano-node (choose the tag with the highest version number: TAGGED-VERSION):

`git fetch --all --recurse-submodules --tags
git tag | sort -V
git checkout tags/<TAGGED VERSION>`

**Configuring the build options**

We explicitly use the GHC version that we installed earlier. This avoids defaulting to a system version of GHC that might be different than the one you have installed.

`You will need to run following commands on M1, those commands will set some cabal related options before building`

`echo "package trace-dispatcher" >> cabal.project.local
echo "  ghc-options: -Wwarn" >> cabal.project.local
echo "" >> cabal.project.local

echo "package HsOpenSSL" >> cabal.project.local
echo "  flags: -homebrew-openssl" >> cabal.project.local
echo "" >> cabal.project.local`

More recent versions of MacOS seems to install openssl in a different location than expected by default. If you have installed openssl via homebrew and encounter the following build error:

`Failed to build HsOpenSSL-0.11.7.2. The failure occurred during the configure
step.
[1 of 1] Compiling Main (...)
Linking .../dist-newstyle/tmp/src-75805/HsOpenSSL-0.11.7.2/dist/setup/setup ...
Configuring HsOpenSSL-0.11.7.2...
setup: Can’t find OpenSSL library`

You'll most likely need to add relevant symlinks as follows:

`sudo mkdir -p /usr/local/opt/openssl
sudo ln -s /opt/homebrew/opt/openssl@3/lib /usr/local/opt/openssl/lib
sudo ln -s /opt/homebrew/opt/openssl@3/include /usr/local/opt/openssl/include`

This is a wart of the HsOpenSSL library wrapper, and using classic methods such as setting LDFLAGS & CPPFLAGS, or using --extra-include-dirs and --extra-lib-dirs won't work properly.

**Building and installing the node**

Build the node and CLI with cabal:

`cabal update
cabal build all
cabal build cardano-cli`

Install the newly built node and CLI commands to the ~/.local/bin directory:

`mkdir -p ~/.local/bin
cp -p "$(./scripts/bin-path.sh cardano-node)" ~/.local/bin/
cp -p "$(./scripts/bin-path.sh cardano-cli)" ~/.local/bin/`

Note: If cardano-cli does not build with 'cabal build all', run 'cabal build cardano-cli'. Note: ~/.local/bin should be in the $PATH.

Note, we avoid using cabal install because that method prevents the installed binaries from reporting the git revision with the --version switch.

Check the version that has been `installed:`

`cardano-cli --version`

Repeat the above process when you need to update to a new version.

Note: It might be necessary to delete the db-folder (the database-folder) before running an updated version of the node.


Installing the node from source

## **Querying the Cardano Blockchain**

Now that we have cardano-node running and syncing, we can test it out by querying the blockchain tip data; which is the current point your local node is synced. To do this, we use the cardano-cli command-line application.

But before we can do that, cardano-cli and other Cardano software components need to know where the node socket file is located. We saved it to the path $HOME/cardano/db/node.socket in the previous example. The components read the shell environment variable CARDANO_NODE_SOCKET_PATH to find this.

So we will set that in $HOME/.bashrc or $HOME/.zshrc, depending on which shell application that you use. In Windows, you can follow this guide: How to Set Environment Variable in Windows.

Add this line to the bottom of your shell profile (MacOS and Linux):

`export CARDANO_NODE_SOCKET_PATH="$HOME/cardano/testnet/db/node.socket"`

Once saved, reload your shell/terminal for changes to take effect.

Finally, we can now test querying the blockchain tip of our cardano-node:

First, run cardano-node in a separate terminal for it to start syncing (if not already).

Open another terminal and run the following command cardano-cli query tip --testnet-magic 1.

You should see something like this:

`{
    "block": 2598870,
    "epoch": 133,
    "era": "Shelley",
    "hash": "7b5633590bf8924d8fce5b6515f34fga0c712f64e9b7d273f915656f88fba872",
    "slot": 27149964,
    "syncProgress": "57.09"
    "block": 2598870,
    "epoch": 133,
    "era": "Shelley",
    "hash": "7b5633590bf8924d8fce5b6515f34fga0c712f64e9b7d273f915656f88fba872",
    "slot": 27149964,
    "syncProgress": "57.09"
}`

We include --testnet-magic <NetworkMagic> in the parameter for cardano-cli query tip because we are using a testnet node. If you intend to query mainnet instead, please use the --mainnet parameter and make sure your node is connected to the mainnet network.

What you see here is the local tip data of your node. This case, means that you are synced up to block: 2598870 and slot: 27149964.

syncProgress is the percentage your node that has been synced. 100 meaning it is fully synced.

To know whether you are fully synced or not, you can check the Cardano Blockchain Explorer of the relevant network:

Mainnet Explorer
https://explorer.cardano.org

**Testnet Explorer**

https://preprod.cardanoscan.io/ https://preview.cardanoscan.io/

Scroll down to the Latest Blocks section, and you can find the latest network tip.

![](https://developers.cardano.org/assets/images/latest-block-eb6d30aa2616b95b4038d3e027297adf.png)

Congratulations, you are now ready to explore the world of Cardano! 🎉🎉🎉




Querying the Cardano Blockchain

## **Dynamic block forging**

**Peer-to-Peer Block Production and Block Forging Configuration**

For redundancy purposes, Stake Pool Operators (SPOs) often operate backup block production nodes. However, with the introduction of peer-to-peer (P2P) nodes, the previous approach of using firewall rules to prevent relays from connecting to the backup node, and thus stop duplicate blocks from being propagated, will no longer be effective.

In the P2P environment, relays can repurpose inbound connections from the block producer, leading to potential complications. To address this issue, we've introduced a way for a block producing node to be started (and stopped) without immediately producing blocks. It will only begin (or stop) block production when it receives a SIGHUP signal.

**Enabling and Disabling Block Forging**

Block Forging can be toggled on and off using the SIGHUP signal. Sending such a signal triggers the node to read the block forging credential files. Note that this will also trigger the re-reading of the topology configuration file, so connections might be lost.

As these credential files are provided through CLI flags, they cannot be removed without restarting the node. To disable block forging, you need to move, rename, or delete the file at the specified path (for the credential flags), and then send the SIGHUP signal. The code will then recognize that the specified files are missing and disable block forging, recording the appropriate log messages.

**Starting as a Non-Producing Node**

If you wish to start a block producing node (i.e., passing the credentials in the respective flags) without it acting as a block producer immediately, you can use the --start-as-non-producing-node flag. This will run the node with credentials as a standard node. However, upon receiving the SIGHUP signal, it will read the credential files and start block forging.

This configuration allows for safer management of block production in a P2P environment, reducing the risk of duplicate blocks and improving overall network stability.



Dynamic block forging

## **Runtime system options for Cardano Node**

The Haskell runtime system (RTS) is a software layer that provides a set of services that enable Haskell programs to execute. At a high level, the Haskell runtime system provides the following services:

**Memory management:** the Haskell runtime system manages the allocation and deallocation of memory used by the program. This includes allocating memory for data structures, managing the stack and heap, and freeing memory that is no longer in use.

**Garbage collection**: the Haskell runtime system automatically collects and frees memory that is no longer being used by the program. This ensures that memory is used efficiently and helps to prevent memory leaks.

**Concurrency and parallelism**: the Haskell runtime system provides support for concurrency and parallelism through features like lightweight threads, software transactional memory, and parallel arrays. This enables Haskell programs to take advantage of modern multicore processors and to execute computations in parallel.

**Exception handling**: the Haskell runtime system provides a mechanism for handling exceptions that occur during program execution. This includes both synchronous exceptions, which occur as a result of a program error, and asynchronous exceptions, which occur as a result of external events such as signals.

IOG-released binaries are built with the following RTS options -T -I0 -A16m -N2 --disable-delayed-os-memory-return . This means that the node uses these options at runtime by default. You can check it with:

`cardano-node +RTS --info`

` [("GHC RTS", "YES")
 ,("GHC version", "8.10.7")
 ,("RTS way", "rts_thr")
 ,("Build platform", "x86_64-unknown-linux")
 ,("Build architecture", "x86_64")
 ,("Build OS", "linux")
 ,("Build vendor", "unknown")
 ,("Host platform", "x86_64-unknown-linux")
 ,("Host architecture", "x86_64")
 ,("Host OS", "linux")
 ,("Host vendor", "unknown")
 ,("Target platform", "x86_64-unknown-linux")
 ,("Target architecture", "x86_64")
 ,("Target OS", "linux")
 ,("Target vendor", "unknown")
 ,("Word size", "64")
 ,("Compiler unregisterised", "NO")
 ,("Tables next to code", "YES")
 ,("Flag -with-rtsopts", "-T -I0 -A16m -N2 --disable-delayed-os-memory-return")
 ]`

**Customized RTS options**

Users have the option to select different configurations by adjusting the -with-rtsopts in the node's Cabal file and then building the node with the updated settings:

`ghc-options:    "-with-rtsopts=-T -I0 -A16m -N2 --disable-delayed-os-memory-return"`

Users can also extend and override options in -with-rtsopts by running cardano-node with command-line RTS options. For example, this extends the compilation options with +RTS -B, to sounds the bell at the start of each garbage collection.


`cardano-node run +RTS -B -RTS --topology topology.json \
--database-path db \
--socket-path node.socket \
--port 3001 \
--config config/config.json `

Together with the options set in the .cabal file, the above example uses:

-T: produces runtime-system statistics, such as the amount of time spent executing the program and in the garbage collector, the amount of memory allocated, the maximum size of the heap, and so on. The three variants provide 
different levels of detail: -T collects the data but produces no output. Access the statistics using GHC.Stats.

-N2: specifies the number of threads to use for parallel execution. The -N2 flag indicates that the Haskell runtime system should use two parallel threads.

-A16m: sets the maximum heap size for the generational garbage collector to 16 megabytes.

-I0: specifies the amount of idle time that must pass before an idle GC is performed. Setting -I0 disables the idle GC.

--disable-delayed-os-memory-return: this option is used for accurate resident memory usage of the program, as shown in memory usage reporting tools (eg, the RSS column in top and htop). It makes it easier to verify the real memory usage.

-B: sound the bell at the start of each garbage collection. Curious about why you would use this flag? Read RTS options for hackers, debuggers, and over-interested souls

Discover the available options for cardano-node with:

`cardano-node +RTS -?`

`cardano-node:
cardano-node: Usage: <prog> <args> [+RTS <rtsopts> | -RTS <args>] ... --RTS <args>
cardano-node:
cardano-node:    +RTS    Indicates run time system options follow
cardano-node:    -RTS    Indicates program arguments to follow
cardano-node:   --RTS    Indicates that ALL subsequent arguments will be given to the
cardano-node:            program (including any of these RTS flags)
cardano-node:
cardano-node: The following run time system options are available:
cardano-node:
cardano-node:   -?       Prints this message and exits; the program is not executed
cardano-node:   --info   Print information about the RTS used by this program
cardano-node:
cardano-node:   --nonmoving-gc
cardano-node:             Selects the non-moving mark-and-sweep garbage collector to
cardano-node:             manage the oldest generation.
cardano-node:   --copying-gc
cardano-node:             Selects the copying garbage collector to manage all generations.
cardano-node:
cardano-node:   -K<size>  Sets the maximum stack size (default: 80% of the heap)
cardano-node:             Egs: -K32k -K512k -K8M
cardano-node:   -ki<size> Sets the initial thread stack size (default 1k)  Egs: -ki4k -ki2m
cardano-node:   -kc<size> Sets the stack chunk size (default 32k)
cardano-node:   -kb<size> Sets the stack chunk buffer size (default 1k)
cardano-node:
cardano-node:   -A<size>  Sets the minimum allocation area size (default 1m) Egs: -A20m -A10k
cardano-node:   -AL<size> Sets the amount of large-object memory that can be allocated
cardano-node:             before a GC is triggered (default: the value of -A)
cardano-node:   -F<n>     Sets the collecting threshold for old generations as a factor of
cardano-node:             the live data in that generation the last time it was collected
cardano-node:             (default: 2.0)
cardano-node:   -n<size>  Allocation area chunk size (0 = disabled, default: 0)
cardano-node:   -O<size>  Sets the minimum size of the old generation (default 1M)
cardano-node:   -M<size>  Sets the maximum heap size (default unlimited)  Egs: -M256k -M1G
cardano-node:   -H<size>  Sets the minimum heap size (default 0M)   Egs: -H24m  -H1G
cardano-node:   -xb<addr> Sets the address from which a suitable start for the heap memory
cardano-node:             will be searched from. This is useful if the default address
cardano-node:             clashes with some third-party library.
cardano-node:   -xn       Use the non-moving collector for the old generation.
cardano-node:   -m<n>     Minimum % of heap which must be available (default 3%)
cardano-node:   -G<n>     Number of generations (default: 2)
cardano-node:   -c<n>     Use in-place compaction instead of copying in the oldest generation
cardano-node:            when live data is at least <n>% of the maximum heap size set with
cardano-node:            -M (default: 30%)
cardano-node:   -c       Use in-place compaction for all oldest generation collections
cardano-node:            (the default is to use copying)
cardano-node:   -w       Use mark-region for the oldest generation (experimental)
cardano-node:   -I<sec>  Perform full GC after <sec> idle time (default: 0.3, 0 == off)
cardano-node:
cardano-node:   -T         Collect GC statistics (useful for in-program statistics access)
cardano-node:   -t[<file>] One-line GC statistics (if <file> omitted, uses stderr)
cardano-node:   -s[<file>] Summary  GC statistics (if <file> omitted, uses stderr)
cardano-node:   -S[<file>] Detailed GC statistics (if <file> omitted, uses stderr)
cardano-node:
cardano-node:
cardano-node:   -Z         Don't squeeze out update frames on stack overflow
cardano-node:   -B         Sound the bell at the start of each garbage collection
cardano-node:   -h       Heap residency profile (output file <program>.hp)
cardano-node:   -hT      Produce a heap profile grouped by closure type
cardano-node:   -i<sec>  Time between heap profile samples (seconds, default: 0.1)
cardano-node:
cardano-node:   -C<secs>  Context-switch interval in seconds.
cardano-node:             0 or no argument means switch as often as possible.
cardano-node:             Default: 0.02 sec.
cardano-node:   -V<secs>  Master tick interval in seconds (0 == disable timer).
cardano-node:             This sets the resolution for -C and the heap profile timer -i,
cardano-node:             and is the frequency of time profile samples.
cardano-node:             Default: 0.01 sec.
cardano-node:
cardano-node:   -N[<n>]    Use <n> processors (default: 1, -N alone determines
cardano-node:              the number of processors to use automatically)
cardano-node:   -maxN[<n>] Use up to <n> processors automatically
cardano-node:   -qg[<n>]  Use parallel GC only for generations >= <n>
cardano-node:             (default: 0, -qg alone turns off parallel GC)
cardano-node:   -qb[<n>]  Use load-balancing in the parallel GC only for generations >= <n>
cardano-node:             (default: 1 for -A < 32M, 0 otherwise;
cardano-node:              -qb alone turns off load-balancing)
cardano-node:   -qn<n>    Use <n> threads for parallel GC (defaults to value of -N)
cardano-node:   -qa       Use the OS to set thread affinity (experimental)
cardano-node:   -qm       Don't automatically migrate threads between CPUs
cardano-node:   -qi<n>    If a processor has been idle for the last <n> GCs, do not
cardano-node:             wake it up for a non-load-balancing parallel GC.
cardano-node:             (0 disables,  default: 0)
cardano-node:   --numa[=<node_mask>]
cardano-node:             Use NUMA, nodes given by <node_mask> (default: off)
cardano-node:   --install-signal-handlers=<yes|no>
cardano-node:             Install signal handlers (default: yes)
cardano-node:   -e<n>     Maximum number of outstanding local sparks (default: 4096)
cardano-node:   -xp       Assume that all object files were compiled with -fPIC
cardano-node:             -fexternal-dynamic-refs and load them anywhere in the address
cardano-node:             space
cardano-node:   -xm       Base address to mmap memory in the GHCi linker
cardano-node:             (hex; must be <80000000)
cardano-node:   -xq       The allocation limit given to a thread after it receives
cardano-node:             an AllocationLimitExceeded exception. (default: 100k)
cardano-node:
cardano-node:   -Mgrace=<n>
cardano-node:             The amount of allocation after the program receives a
cardano-node:             HeapOverflow exception before the exception is thrown again, if
cardano-node:             the program is still exceeding the heap limit.
cardano-node:
cardano-node: RTS options may also be specified using the GHCRTS environment variable.
cardano-node:
cardano-node: Other RTS options may be available for programs compiled a different way.
cardano-node: The GHC User's Guide has full details.`



Runtime system options for Cardano Node

## **Topology**

The P2P topology file specifies how to obtain the root peers.

The term local roots refers to a group of peer nodes with which a node will aim to maintain a specific number of active, or 'hot' connections. These hot connections are those that play an active role in the consensus algorithm. Conversely, 'warm' connections refer to those not yet actively participating in the consensus algorithm. Local roots should comprise local relays or a local block-producing node, and any other peers that the node needs to maintain a connection with. These connections are typically kept private.

public roots: publicly known nodes (e.g. IOG relays, or ledger nodes). They are either read from the configuration file directly or from the chain. The configured ones will be used to pass a recent snapshot of peers needed before the node caches up with the recent enough chain to construct root peers by itself.

The node does not guarantee a connection with every public root, unlike local ones. However, by being present in the set, it gets an opportunity to establish an outbound connection with that peer.

A minimal version of this file looks like this:

`{
  "bootstrapPeers": [
    {
      "address": "backbone.cardano.iog.io",
      "port": 3001
    },
    {
      "address": "backbone.mainnet.emurgornd.com",
      "port": 3001
    },
    {
      "address": "backbone.mainnet.cardanofoundation.org",
      "port": 3001
    }
  ],
  "localRoots": [
      { "accessPoints": [
            {
              "address": "x.x.x.x",
              "port": 3001
            }
          ],
        "advertise": false,
        "valency": 1,
        "warmValency": 2,
        "trustable": true
      }
  ],
  "publicRoots": [
    { "accessPoints": [
        {
          "address": "y.y.y.y",
          "port": 3002
        }
        ],
      "advertise": false
    }
  ],
  "useLedgerAfterSlot": 128908821,
}`

The main difference between LocalRoots and PublicRoots is the ability to specify various groups with varying valencies in the former. This can be valuable for informing your node about different targets within a group to achieve. LocalRoots is designed for peers that the node should always keep as hot or warm, such as its own block producer. On the other hand, PublicRoots serves as a source of fallback peers, to be used if we are before the configured useLedgerAfterSlot slot.

This means that your node will initiate contact with the node at IP x.x.x.x on port 3001 and resolve the DNS domain y.y.y.y (provided it exists). It will then make efforts to establish a connection with at least one of the resolved IPs.

hotValency tells the node the number of connections it should attempt to select from the specified group. When a DNS address is provided, valency determines the count of resolved IP addresses for which the node should maintain an active (hot) connection. Note: one can also use the deprecated now valency field for hotValency.

warmValency is an optional field, similar to hotValency, that informs the node about the number of peers it should maintain as warm. This field is optional and defaults to the value set in the valency or hotValency field. If a value is specified for warmValency, it should be greater than or equal to the one defined in hotValency; otherwise, or hotValency will be adjusted to match this value. We recommend users set the warmValency value to hotValency + 1 to ensure at least one backup peer is available to be promoted to a hot connection in case of unexpected events. Check this issue for more context on this WarmValency option.
Local root groups shall be non-overlapping.

The advertise parameter instructs a node about the acceptability of sharing its address through peer sharing (which we'll explain in more detail in a subsequent section). In essence, if a node has activated peer sharing, it can receive requests from other nodes seeking peers. However, it will only disclose those peers for which it has both local and remote permissions.

Local permission corresponds to the value of the advertise parameter. On the other hand, 'remote permission' is tied to the PeerSharing value associated with the remote address, which is ascertained after the initial handshake between nodes.

Local roots should not be greater than the TargetNumberOfKnownPeers. If they are, they will get clamped to the limit.

For trustablePeers and bootstrapPeers read the next section.
Your block-producing node must ONLY talk to your relay nodes, and the relay node should talk to other relay nodes in the network.

You have the option to notify the node of any changes to the topology configuration file by sending a SIGHUP signal to the cardano-node process. This can be done, for example, with the command pkill -HUP cardano-node. Upon receiving the signal, the cardano-node will re-read the configuration file and restart all DNS resolutions.

Please be aware that this procedure is specific to the topology configuration file, not the node configuration file. Additionally, the SIGHUP signal will prompt the system to re-read the block forging credentials file paths and attempt to fetch them to initiate block forging. If this process fails, block forging will be disabled. To re-enable block forging, ensure that the necessary files are present.

You can disable ledger peers by setting the useLedgerAfterSlot to a negative value.

Genesis lite a.k.a Bootstrap Peers
Bootstrap Peers is a pre-Genesis feature that means to provide a way for a node to connect to a trustable set of peers when the its chain falls behind.

Bootstrap peers can be disabled by setting bootstrapPeers: null. They are enabled by providing a list of addresses. By default bootstrap peers are disabled.

Trustable peers are composed by the bootstrap peers (see bootstrapPeers option in the example topology file above) and the trustable local root peers (see trustable option in the example topology file above). By default local root peers are not trustable.

In order for the node to be able to start and make progress, when bootstrap peers are enabled, the user must provide a trustable source of peers via topology file. This means that the node will only start if either the bootstrap peers list is non-empty or there's a local root group that is trustable. Failing to configure the node with trustable peer sources will make it so that the node crashes with an exception. Please note that if the only source of trustable peers is a DNS name, the node might not be able to make progress once in fallback state, if DNS is not providing any addresses.

With bootstrap peers enabled the node will trace:

TraceLedgerStateJudgmentChanged {TooOld,YoungEnoug}: If it has changed to any of these states.

TooOld state means that the information the node is getting from its peers is outdated and behind at least 20 min. This means there's something wrong and that the node should only connect to trusted peers (trusted peers are bootstrap peers and trustable local root peers) in order to sync.

YoungEnough state means that the node is caught up and that it can now connect to non-trusted peers.

**TraceOnlyBootstrap:** Once the node transitions to TooOld the node will disconnect from all non-trusted peers and reconnect to only trusted ones in order to sync from trusted sources only. This tracing message means that the node has successfully purged all non-trusted connections and is only going to connect to trusted peers.

**Configuring the node to use P2P**

You can enable P2P from the configuration file, the field EnableP2P can be set to either false or true. When setting it to true, you will also need to configure the target number of active, established and known peers, together with the target number of root peers, for example:

`{
  ...
  "EnableP2P": true,
  "TargetNumberOfActivePeers": 20,
  "TargetNumberOfEstablishedPeers": 40,
  "TargetNumberOfKnownPeers": 100,
  "TargetNumberOfRootPeers": 10,
}`

Topology

## **Quick start**

[Introduction](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#introduction)

[Configuration and use of Cardano Tracer](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#configuration-and-use-of-cardano-tracer)

[Advanced Configuration](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#advanced-configuration)

[Node-side configuration of new tracing](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#node-side-configuration-of-new-tracing)

[Node-side configuration of new tracing: TraceOptions](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#node-side-configuration-of-new-tracing-traceoptions)

[Node-side configuration of new tracing: other fields](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#node-side-configuration-of-new-tracing-other-fields)

[Configuration formats and fallback](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#configuration-formats-and-fallback)

[Old Tracing and New Tracing](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#old-tracing-and-new-tracing)

[You're set!](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#youre-set)

[Feedback and Reporting
](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#feedback-and-reporting)

[Developers only: developing new tracers during transition time](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#developers-only-developing-new-tracers-during-transition-time)

[Documentation and References](https://developers.cardano.org/docs/get-started/cardano-node/new-tracing-system/new-tracing-system#documentation-and-references)


**Introduction**

This document provides an overview of the New Tracing System's functionality, configuration, and modes of operation. The system has been designed to offer flexible and efficient monitoring of Cardano nodes through trace forwarding and hierarchical trace message handling.

**Functionality Split between Node and Tracer**

The new system separates monitoring responsibilities between the Cardano Node and the Cardano Tracer services. This modular approach ensures the node focuses on core operations, while cardano-tracer manages logging, monitoring, and external communication.

**Introducing Trace Forwarding**

Trace forwarding enables seamless transmission of trace data and metrics from nodes to a centralized tracer service. This feature simplifies remote monitoring and supports scenarios where multiple nodes are monitored by a single cardano-tracer instance.

Hierarchical Namespaces for Trace Messages

To streamline configuration, the system now uses hierarchical namespaces for trace messages instead of directly referencing tracers. This change improves manageability and aligns trace configuration with logical groupings.

**Modes of Operation**

The new tracing system supports several modes of operation to suit different deployment scenarios:

Without Forwarding (No Metrics): The node operates independently and writes trace messages to stdout. Metrics are not provided and would have to be built manually from observing stdout.

One Node, One Cardano Tracer (Local Socket): The tracer connects to a single node over a local socket. Trace output and metrics are forwarded to the tracer, and are available according to its configuration.

One Tracer, Many Nodes (Socket Connection, possibly via SSH Tunnel): A single tracer connects to multiple nodes over socket connections, either locally on the same host, or remotely through secure SSH tunnels.

Two-Part Configuration

The configuration for the new tracing system is distributed across two key components:

Node Configuration File

Specifies the settings required to enable and manage trace forwarding from the node to the tracer.
Includes parameters such as:
Enabling the new tracing system.
Defining trace message filtering and granularity.
Additional details about trace forwarding.
Cardano Tracer Configuration File

Configures the tracer service itself with settings such as:
Communication endpoints (e.g., socket paths).
Logging formats and destinations.
Metrics, and where to query them (e.g., HTTP ports for EKG or Prometheus).
Directories for log storage and rotation.
These configurations work together to ensure efficient communication between the node and the tracer, providing a flexible and robust monitoring setup.

**Configuration and use of Cardano Tracer**

cardano-tracer is a key component of the new tracing infrastructure. It operates as a standalone service that consumes trace messages from cardano-node, processes them, and provides outputs for monitoring and analysis.

**Key Features:**

Logging to File or System Services: Write logs in JSON format for machine processing or as text for human readability.

Metrics Exposure: Provides EKG and Prometheus metrics endpoints for system monitoring.

Below is an example of configuring a simple use case: a node and cardano-tracer running on the same machine.

Step 1: Transport from Node to Tracer
Add the following option to the Cardano node's CLI arguments:

`--tracer-socket-path-connect /tmp/forwarder.sock`

This instructs the node to forward trace messages to cardano-tracer via the specified socket path. The system only supports its own transport layer, the 'forwarding protocol'.

Step 2: Build and Run cardano-tracer
Build and run cardano-tracer using either cabal or nix. Below are examples for both methods.

Using Cabal:

`cabal build cardano-tracer && cabal install cardano-tracer --installdir=PATH_TO_DIR --overwrite-policy=always
cd PATH_TO_DIR
./cardano-tracer --config PATH_TO_CONFIG`

Using Nix:

`nix build github://github.com/IntersectMBO/cardano-node#cardano-tracer
./result/bin/cardano-tracer --config PATH_TO_CONFIG`

Replace PATH_TO_CONFIG with the path to your cardano-tracer configuration file (see next step).

**Step 3: Minimal Example Configuration**

Below is an example configuration for a single-node-to-single-tracer setup. The system's forwarding protocol encodes the network magic, so it is mandatory to provide one. Both ends of trace forwarding require the same magic; the example uses the one for mainnet:

**Minimal Example:**

`networkMagic: 764824073
network:
  tag: AcceptAt
  contents: "/tmp/forwarder.sock"
logging:
- logRoot: "/tmp/cardano-tracer-logs"
  logMode: FileMode
  logFormat: ForMachine`

network: Specifies the socket path for communication between the node and the tracer.

logging: Configures logs to be written to the /tmp/cardano-tracer-logs directory in JSON format.

Step 4: Running the Setup
Starting with Node 10.2, the new tracing system is chosen by default. On previous versions, it can be explicitly enabled in the config by setting UseTraceDispatcher: true.

Go through the adjustments for your Node configuration file (next chapter). When this is done, and cardano-tracer is running, start the Node. It will establish a connection to cardano-tracer and begin forwarding trace messages. The tracer will process these messages and generate logs in the specified directory (/tmp/cardano-tracer-logs).

**Advanced Configuration**

For more complex setups, such as monitoring multiple nodes or exposing metrics via Prometheus, additional configuration examples are available. Please refer to the Cardano Tracer Documentation for detailed guidance on advanced setups and use cases.


**Node-side configuration of new tracing**

Node-side configuration of new tracing: TraceOptions
The new tracing system uses namespaces for configuration values, enabling fine-grained control down to individual messages. More specific configuration values will override general ones, allowing for a flexible hierarchical setup. The values are provided in the new TraceOptions object in the node configuration file, which we'll further inspect here:

**1. Specify Message Severity Filter**

Define the severity level of messages you want to be included in trace output. More specific namespaces override general ones.

**Example:**

`# Default: show messages of severity Notice or higher
"":
  severity: Notice

# ChainDB messages: show starting from severity Info
ChainDB:
  severity: Info`

To suppress all messages pertaining to a namespace, use the severity level Silence.

For a map of the entire namespace of trace messages, please refer to the Cardano Trace Documentation.

**2. Specify Message Detail Level**

Configure the detail level for the messages to control the amount of information rendered for each message.

**Example:**

`"":
  severity: Notice
  detail: DNormal`

Supported detail levels:

DMinimal: minimal message verbosity

DNormal: default verbosity

DDetailed: extended message verbosity

DMaximum: be extremely verbose - only recommended for development or debugging

Note: Trace messages might choose to not support every detail level in their implementation - or only one; the highest matching detail level will then be chosen for rendering.

**3. Specify Message Frequency Limiters**

Use frequency limiters to control how often messages are displayed. This replaces the old 'eliding tracers' functionality.

**Example:**

`ChainDB.AddBlockEvent.AddedBlockToQueue:
  # Show a maximum of 2 messages per second
  maxFrequency: 2.0`

Setting maxFrequency: 0.0 disables frequency limiting - which is the default.

**4. Specify backends for trace data**

Define the backends that will be enabled inside the Node to process trace data.

**Example:**

`"":
  severity: Notice
  detail: DNormal
  backends:
    - Stdout MachineFormat
    - EKGBackend
    - Forwarder`

Writing to standard output (only one can be used):
Stdout MachineFormat: in JSON format
Stdout HumanFormatColoured: in color-coded text format
Stdout HumanFormatUncoloured: in plain text format
EKGBackend: Forwards metrics to cardano-tracer
Forwarder: Forwards trace messages to cardano-tracer
Note: For standard output, trace messages that do not implement a text format might be displayed as JSON.

Note: Please make sure to enable the Forwarder backend if and only if you intend to consume the trace ouput with a running cardano-tracer instance. In case of unreliable forwarding connections, the Node generously buffers traces that have not been consumed; and though the buffer is bounded, you will experience permanently increased RAM usage if traces are never consumed at all.

Note: Metrics, although being based on trace data, are independent of trace messages. This means, you can receive all metrics with cardano-tracer even when you don't forward the corresponding trace messages. This also means, all metrics will be available even if their corresponding trace messages are filtered out or silenced in your configuration.


Node-side configuration of new tracing: other fields
In addition to providing a TraceOptions entry, the new tracing system introduces additional configuration values in the node configuration file:

TraceOptionNodeName: (string) This is used by cardano-tracer as the base for creating logging subdirectories and URL paths to query metrics. By default, the hostname is chosen.
TraceOptionMetricsPrefix: (string) Adds a prefix to all metrics names. For increased compatibility with names in the old system, you could use "cardano.node.metrics.".
UseTraceDispatcher: (boolean) Enables / disables the new tracing system
Configuration formats and fallback
Configurations can be written in both JSON and YAML. The examples in this document are provided in YAML for readability.

A full example of a mainnet node config file utilizing various settings for the new tracing system can be found here: mainnet-config-new-tracing.json

There's a sensible fallback configuration hard-coded inside a Haskell module of the Node: Cardano.Node.Tracing.DefaultTraceConfig. It is important to state the TraceOptions from this fallback will be used if and only if the TraceOptions object in your Node configuration is empty.

Old Tracing and New Tracing
The old tracing system is slated for decommissioning but will coexist with the new tracing system during a transitional grace period of approximately 3 to 6 months. During this time, both systems will remain part of the default cardano-node build, ensuring compatibility and easing the migration process.

Switching Between Tracing Systems
To enable the new tracing system, set the Node's configuration value UseTraceDispatcher: true.
To continue using the old tracing system, you need to explicitly set UseTraceDispatcher: false on Node 10.2 and onwards.
Deprecation of the kind field in trace messages
Certain legacy features will be deprecated to simplify and unify the tracing infrastructure. Specifically:

The kind field will be deprecated and removed when decomissioning the old tracing system.
We strongly recommend using namespaces (provided in the new ns field; see below) instead for any analysis tools or automations involving traces.
You're set!
Feedback and Reporting
Your feedback is invaluable during this transition. Please help us improve the system by reporting any regressions, issues or difficulties integrating with existing automations while using the new tracing infrastructure.

Developers only: developing new tracers during transition time
During the transition from old to new tracing system, we recommend the following best practices for developing tracers:

Avoid Using Strictness Annotations for Trace types Trace messages are either discarded immediately or quickly converted into another format for processing. They are never stored for long durations. Using strictness annotations can make the code less efficient without adding any tangible benefits. Additionally, strictness annotations do not align well with the prototype requirements for messages in the new framework.

Prioritize Developing New Tracers Focus on developing new tracers first and then map them to the old tracers. This approach ensures compatibility while future-proofing your work, as the new tracers will remain in use after the old system is decommissioned. You can find numerous examples in cardano-nodes source code in module Cardano.Node.Tracing.Tracers.

Leverage Expertise If you have questions or need reviews for your tracers, reach out to the Performance & Tracing Team.

kind Fields As described above, keep in mind the kind field will be removed eventually; please rely on namespaces when analysing trace messages.

Node-side configuration of new tracing: other fields
In addition to providing a TraceOptions entry, the new tracing system introduces additional configuration values in the node configuration file:

TraceOptionNodeName: (string) This is used by cardano-tracer as the base for creating logging subdirectories and URL paths to query metrics. By default, the hostname is chosen.
TraceOptionMetricsPrefix: (string) Adds a prefix to all metrics names. For increased compatibility with names in the old system, you could use "cardano.node.metrics.".
UseTraceDispatcher: (boolean) Enables / disables the new tracing system

**Configuration formats and fallback**

Configurations can be written in both JSON and YAML. The examples in this document are provided in YAML for readability.

A full example of a mainnet node config file utilizing various settings for the new tracing system can be found here: mainnet-config-new-tracing.json

There's a sensible fallback configuration hard-coded inside a Haskell module of the Node: 

Cardano.Node.Tracing.DefaultTraceConfig. It is important to state the TraceOptions from this fallback will be used if and only if the TraceOptions object in your Node configuration is empty.

**Old Tracing and New Tracing**

The old tracing system is slated for decommissioning but will coexist with the new tracing system during a transitional grace period of approximately 3 to 6 months. During this time, both systems will remain part of the default cardano-node build, ensuring compatibility and easing the migration process.

Switching Between Tracing Systems
To enable the new tracing system, set the Node's configuration value UseTraceDispatcher: true.
To continue using the old tracing system, you need to explicitly set UseTraceDispatcher: false on Node 10.2 and onwards.
Deprecation of the kind field in trace messages
Certain legacy features will be deprecated to simplify and unify the tracing infrastructure. Specifically:

The kind field will be deprecated and removed when decomissioning the old tracing system.
We strongly recommend using namespaces (provided in the new ns field; see below) instead for any analysis tools or automations involving traces.

You're set!

**Feedback and Reporting**

Your feedback is invaluable during this transition. Please help us improve the system by reporting any regressions, issues or difficulties integrating with existing automations while using the new tracing infrastructure.

**Developers only:** developing new tracers during transition time

During the transition from old to new tracing system, we recommend the following best practices for developing tracers:

Avoid Using Strictness Annotations for Trace types Trace messages are either discarded immediately or quickly converted into another format for processing. They are never stored for long durations. Using strictness annotations can make the code less efficient without adding any tangible benefits. Additionally, strictness annotations do not align well with the prototype requirements for messages in the new framework.

Prioritize Developing New Tracers Focus on developing new tracers first and then map them to the old tracers. This approach ensures compatibility while future-proofing your work, as the new tracers will remain in use after the old system is decommissioned. You can find numerous examples in cardano-nodes source code in module Cardano.Node.Tracing.Tracers.

Leverage Expertise If you have questions or need reviews for your tracers, reach out to the Performance & Tracing Team.

kind Fields As described above, keep in mind the kind field will be removed eventually; please rely on namespaces when analysing trace messages.

**Documentation and References**

To support users, administrators and developers, the following documentation provides comprehensive insights into trace messages, metrics, and data points:

**Trace Messages and Default Configuration**: This periodically regenerated document catalogs all trace messages, metrics, and data points in cardano-node. It also illustrates how these messages are handled with the current default configuration: Cardano Trace Documentation

**Trace-Dispatcher Library:** This document describes the underlying library powering the new tracing system. It provides details about its design, flexibility, and efficiency: trace-dispatcher: Efficient, Simple, and Flexible Program Tracing

**Cardano Tracer**: For information about the cardano-tracer service, which facilitates logging and monitoring, refer to its dedicated documentation: Cardano Tracer Documentation

Quick start

Cardano Tracer

## **Get started with Cardano CLI**

**Setting up environment variables**

**CARDANO_NODE_SOCKET_PATH**

Cardano CLI uses the node-to-client protocol to communicate with the node. This requires setting an environment variable for the node socket path. Ensure you use the path declared when starting the node.

`export CARDANO_NODE_SOCKET_PATH=~/node.socket`

**CARDANO_NODE_NETWORK_ID**

Each network has a unique identifier (--mainnet or --testnet-magic NATURAL). This is used by the node-to-client protocol to ensure communication with a node on the desired network. It is useful to set up an environment variable for the network ID. Alternatively, you can provide the flag --testnet-magic <network-id> with each command that interacts with the node.

**Mainnet**

`export CARDANO_NODE_NETWORK_ID=mainnet `

**Pre-production testnet**

`export CARDANO_NODE_NETWORK_ID=1`

**Preview testnet**

`export CARDANO_NODE_NETWORK_ID=2`

**SanchoNet testnet**

`export CARDANO_NODE_NETWORK_ID=4
`

**Generating keys and addresses**

info

For a complete overview of Cardano address types, read CIP-19.

**Generate a payment key pair and an address**

To generate a key pair, run:

cardano-cli address key-gen \
--verification-key-file payment.vkey \
--signing-key-file payment.skey

**Build an address**

This address will not have staking rights. It cannot delegate or receive rewards because it does not have a stake part associated with it, only a payment part (see CIP-19).

`cardano-cli address build \
--payment-verification-key-file payment.vkey \
--out-file paymentNoStake.addr`

`cat paymentNoStake.addr
addr_test1vzdtyyt48yrn2fa3wvh939rat0gyv6ly0ljt449sw8tppzq84xstz`

**Generate a stake key pair**

`cardano-cli stake-address key-gen \
--verification-key-file stake.vkey \
--signing-key-file stake.skey`

**Build the address with payment and stake parts**

The resulting address will be associated with the payment and stake credentials:

`cardano-cli address build \
--payment-verification-key-file payment.vkey \
--stake-verification-key-file stake.vkey \
--out-file payment.addr`

`cat payment.addr
addr_test1qzdtyyt48yrn2fa3wvh939rat0gyv6ly0ljt449sw8tppzrcc3g0zu63cp6rnjumfcadft63x3w8ds4u28z6zlvra4fqy2sm8n`

Query the balance of an address

`cardano-cli query utxo --address $(< paymentNoStake.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
262c7891f932cde390bcc04c25805f3f422c1a5687d5d47f6681e68bb384fe6d     0        10000000000 lovelace + TxOutDatumNone`


[Simple transactions](https://developers.cardano.org/docs/get-started/cardano-cli/get-started/simple-transactions)

[Stake address registration](https://developers.cardano.org/docs/get-started/cardano-cli/get-started/stake-address-registration/)

[Delegating stake to a stake pool](https://developers.cardano.org/docs/get-started/cardano-cli/get-started/delegate-to-stake-pool)

[Withdraw rewards](https://developers.cardano.org/docs/get-started/cardano-cli/get-started/withdraw-rewards)

[Deregister stake address](https://developers.cardano.org/docs/get-started/cardano-cli/get-started/deregister-stake-addreess)

[Treasury donation](https://developers.cardano.org/docs/get-started/cardano-cli/get-started/treasury-donation)



Get started with Cardano CLI

Simple scripts

## **Native assets**

From the Mary ledger upgrade and onwards, Cardano supports multi-assets, also referred to as a native tokens feature. This feature extends the ledger’s accounting infrastructure (originally designed for processing ada-only transactions) to accommodate transactions using a range of assets. These assets include ada and a variety of user-defined token types, the mixture of which can be transacted in a single tx output. Note that native tokens cannot exist on its own at a UTXO, a minimum number of lovelace is required at the UTXO to support the native tokens.

**What are Native assets?**

Native assets are user-defined, custom tokens. They are supported natively, which means that the ledger handles the accounting and tracking of token-related activities. This offers distinct advantages for developers as there is no need to create smart contracts to mint or burn custom tokens, removing a layer of added complexity and potential for manual errors.

An asset is uniquely identified by an asset ID, which is a pair of both the policy ID and an asset name:

PolicyID - the unique identifier that is associated with a minting policy (hash of the minting policy).
Asset name - an (immutable) property of an asset that is used to distinguish different assets within the same policy. Unlike the policyID, the asset name does not refer to any code or set of rules. It is a hex encoded arbitrary sequence of bytes. For example, hex("couttscoin") = "636f75747473636f696e".

`echo -n "couttscoin" | xxd -ps
636f75747473636f696e`


Tokens that have the same asset ID have the property of being fungible with each other, and are not fungible with tokens that have a different asset ID.

Further reading:

Native token explainers
Before you start, you should:

have the latest version of the node
configure the node to communicate with the testnet environment
A running cardano-node on the desired network.
Cardano-cli installed
Syntax for expressing values in a transaction output
Lovelace values can be specified in two ways:

${quantity} lovelace (where quantity is a signed integer)
${quantity} (where quantity is a signed integer)
${assetName} (where assetName is hex-encoded 61737365744e616d65)
Values for other assets can be specified as:

${quantity} ${policyId}.${assetName}
${quantity} ${policyId}
Where quantity is a signed integer and policyId is a hex-encoded policy ID [a script hash], and assetName is a hex-encoded assetName.

Syntax of native asset values
The cardano-cli can specify native asset values in transaction outputs and when minting or burning tokens. The syntax for these values has been designed to be backwards-compatible with the previous ada-only syntax (address+lovelace):

ada values are defined as integer (INT) lovelace, e.g. 42 lovelace
native asset values can be defined as:
INT policyid.assetName, e.g. 42 $MYPOLICY.61737365744e616d65
INT policyid, e.g. 42 $MYPOLICY (No assetName specified)
policyid.assetName, e.g $MYPOLICY.61737365744e616d65 (This will mint only one of assetName)
Multiple assets can be combined in the same transaction output using the + operator, e.g:
100 lovelace + 42 $MYPOLICY.666f6f + -2 $MYPOLICY.626172 + 10 lovelace

Negating individual values

Any individual value can be negated using the - prefix operator. For example:

-42 $MYPOLICY
-72191 $MYPOLICY.666f6f
-100
-920 lovelace
Combining individual values

Values can be combined using the binary operator +. For example:

42 lovelace + -1 (this would result in a Value of 41 lovelace)
20 $MYPOLICY + 12 $MYPOLICY.666f6f + -2 $MYPOLICY.626172
201 4$MYPOLICY.666f6f + 12 + -1 + 9 lovelace + 10 $MYPOLICY
Creating a transaction
The native tokens syntax can be used in the following contexts:

cardano-cli conway transaction build-raw --tx-out="..."
cardano-cli conway transaction build-raw --mint="..."
The CLI command cardano-cli conway transaction build-raw creates the transaction body. The --tx-out option specifies the transaction output in the usual way (This is expressed as address+lovelace, where address is a Bech32-encoded address, and lovelace is the amount in lovelace), and the --mint option specifies the value to be minted or burnt.

Transaction outputs (TxOuts)
The syntax for TxOut values has been extended to include multi-asset tokens. These values can be specified in two different ways:

$address $value
${address}+${value}
(where address is a Cardano address and value is a value). The second form is provided for backwards compatibility with earlier versions of the node.

To receive tokens, you just need to specify any address. It is not necessary to use special addresses to hold multi-asset tokens.

To inspect the values in an address, you need to query your node for the UTXOs associated to that address using:

cardano-cli query utxo --address "$ADDRESS" 

Token minting policies
Token minting policies are written using multi-signature scripts. This allows the asset controller to express conditions such as the need for specific token issuers to agree to mint new tokens, or to forbid minting tokens after a certain slot if token locking is also used.

Here’s an example of a very simple minting policy, which grants the right to mint tokens to a single key:

{
  "keyHash": "fe38d7...599",
  "type": "sig"
}

This minting policy requires any transaction that mints tokens to be witnessed by the key with the hash fe38d7...599. More involved examples can be found in the multi-signature simple scripts documentation.

Minting a new native token
Overview
This section describes how to manually mint a new native token ('customcoin') using cardano-cli, and send a transaction of this newly minted token to a new address.

Pre-requisites
Download the latest version of cardano-node from the releases page and config files for the public testnet from the Cardano World

Run the cardano-node:

cardano-node run --topology topology.json --database-path db --port 3001 --config config.json --socket-path node.socket

export CARDANO_NODE_SOCKET_PATH=~/node.socket


Generate a verification key and a signing key:
cardano-cli address key-gen \
    --verification-key-file payment.vkey \
    --signing-key-file payment.skey

The code should output something similar to this:

$ cat payment.skey 
{
    "type": "PaymentSigningKeyShelley_ed25519",
    "description": "Payment Signing Key",
    "cborHex": "58206c7c578e06f9175e20e63353b9beac984183f47ea7778960def47974435829f3"
}
$ cat payment.vkey 
{
    "type": "PaymentVerificationKeyShelley_ed25519",
    "description": "Payment Verification Key",
    "cborHex": "5820e70b3f8c2c18cdacc46efee076963029ca22c853d58e99cbe78f9a8e64c8c85f"
}

Generate the payment address:
cardano-cli address build \
--payment-verification-key-file payment.vkey \
--out-file payment.addr

This code produces the following payment address:

$ cat payment.addr
addr_test1vp6jzppqqegyvjnwc25dg853eam2xmxvydjntfw6d8x4p7qrnsnj9

Check the balance of the payment address:
cardano-cli query utxo --address

The response should show no funds:

                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------

Fund the address:
Use the testnet faucet to fund your address,

and check again:

cardano-cli query utxo --address $(< payment.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
503c699e81d4abc3f8a1d2681425aee1e2ac5770a5be5b9314339591a7158f34     0        10000000000 lovelace + TxOutDatumNone


Start the minting process
Create a policy script:
mkdir policy

cardano-cli address key-gen \
    --verification-key-file policy.vkey \
    --signing-key-file policy.skey


touch policy.script && echo "" > policy.script 


echo "{" >> policy.script 
echo "  \"keyHash\": \"$(cardano-cli address key-hash --payment-verification-key-file policy.vkey)\"," >> policy.script 
echo "  \"type\": \"sig\"" >> policy.script 
echo "}" >> policy.script 

cat policy.script 
{
  "keyHash": "3c293ef7fa09577e8a656016d59abe042ed9fe38cdfd9d81568450c6",
  "type": "sig"
}


Generate the policy ID and the hex encoded asset name.
The policyID is the script hash of the policy.script:

cardano-cli hash script --script-file policy.script 

11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74

get the asset name in hex, our token will be named "melcoin":

echo -n "customcoin" | xxd -ps 

637573746f6d636f696e

Build the asset-minting transaction
Query the protocol parameters:
cardano-cli query protocol-parameters --out-file pparams.json

Calculate the minimum utxo size required to hold the desired number of native assets. Let's mint 1000 customcoin:
cardano-cli conway transaction calculate-min-required-utxo \
--protocol-params-file pparams.json \
--tx-out addr_test1vp6jzppqqegyvjnwc25dg853eam2xmxvydjntfw6d8x4p7qrnsnj9+"1000 11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74.637573746f6d636f696e"
Coin 1051640


This means that we need at least 1051640 lovelace at the utxo to support the 1000 customcoin. To give ourselves some room for future transactions where we might send custocoin to different addresses we will send 10 ada on the minting transaction.

This transaction will mint 1000 "customcoin", with asset id 11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74.637573746f6d636f696e
cardano-cli conway transaction build \
--tx-in 503c699e81d4abc3f8a1d2681425aee1e2ac5770a5be5b9314339591a7158f34#0 \
--tx-out $(< payment.addr)+10000000+"1000 11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74.637573746f6d636f696e" \
--mint="1000 11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74.637573746f6d636f696e" \
--mint-script-file policy.script \
--change-address $(< payment.addr) \
--out-file mint-tx.raw

Estimated transaction fee: Coin 175621


Sign the transaction:
cardano-cli conway transaction sign \
--tx-file mint-tx.raw \
--signing-key-file policy.skey \
--signing-key-file payment.skey \
--out-file mint-tx.signed


Submit the transaction:
cardano-cli conway transaction submit --tx-file mint-tx.signed
Transaction successfully submitted.

cardano-cli query utxo --address $(< payment.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
d4b158e58cb58da28b25837300f6ef8f9f7d67fd5a5ce07648d17a6fae31b88a     0        10000000 lovelace + 1000 11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74.637573746f6d636f696e + TxOutDatumNone
d4b158e58cb58da28b25837300f6ef8f9f7d67fd5a5ce07648d17a6fae31b88a     1        9989824379 lovelace + TxOutDatumNone



Transferring tokens
Tokens can be sent just like ada by any token holder, just remember that it is not possible to send only native-assets in a transaction, some ada always needs to be included in each output. The minimum amount is determined by the utxoCostPerByte protocol parameter. Also note that, currently, the build command cannot automatically balance native assets. This is, we need to manually balance native assets with --tx-out flags and use --change-address to automatically balance ada-only utxos.

For example, to send 1 customcoin to the address addr_test1vp9khgeajxw8snjjvaaule727hpytrvpsnq8z7h9t3zeuegh55grh we do:

cardano-cli conway transaction calculate-min-required-utxo \
--protocol-params-file pparams.json \
--tx-out addr_test1vp9khgeajxw8snjjvaaule727hpytrvpsnq8z7h9t3zeuegh55grh+"1 11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74.637573746f6d636f696e"
Coin 1043020


and build the transaction with:

cardano-cli conway transaction build \
--tx-in d4b158e58cb58da28b25837300f6ef8f9f7d67fd5a5ce07648d17a6fae31b88a#0 \
--tx-in d4b158e58cb58da28b25837300f6ef8f9f7d67fd5a5ce07648d17a6fae31b88a#1 \
--tx-out addr_test1vp9khgeajxw8snjjvaaule727hpytrvpsnq8z7h9t3zeuegh55grh+1043020+"1 11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74.637573746f6d636f696e" \
--tx-out $(< payment.addr)+8956980+"999 11375f8ee31c280e1f2ec6fe11a73bca79d7a6a64f18e1e6980f0c74.637573746f6d636f696e" \
--change-address $(< payment.addr) \
--out-file tx.raw


cardano-cli conway transaction sign --tx-file tx.raw --signing-key-file policy.skey --signing-key-file payment.skey --out-file tx.signed


cardano-cli conway transaction submit --tx-file tx.signedTransaction successfully submitted.

Buying and spending tokens
Token holders “buy” tokens from a token issuer. This will usually involve sending some ada to a specific address that has been set up by the token issuer and informing the token issuer about the address where the tokens should be sent. The token issuer will then set up a transaction that will transfer a multi-asset token to the specified address.

Tokens that have been issued to a token holder can be “spent” by returning them to a token issuer (i.e. by redeeming the tokens). This is done using a normal transaction. The token issuer will then provide the token holder with the agreed object in return (which may be an item of value, a service, a different kind of token, some ada, etc).

cardano-cli conway transaction build-raw ... --out-file txbody
 
cardano-cli conway transaction sign ... --tx-body-file txbody --out-file tx

cardano-cli conway transaction submit ... --tx-file tx 

Destroying (burning) tokens
Tokens can be destroyed by a token issuer according to the token policy by supplying a negative value in the --mint field. That allows acquiring tokens in the UTXO entry in the input of a transaction, without adding them to one of the outputs, effectively destroying them. For example, tokens created in the previous section can be destroyed as follows:

TXID1=$(cardano-cli conway transaction txid --tx-body-file "$TX_BODY_FILE_1")
TX_BODY_FILE_2=...
TX_FILE_2=...
 
cardano-cli conway transaction build-raw \
--fee 0 \
--tx-in "$TXID1"#0 \
--tx-out="$ADDR+$LOVELACE" \
--mint="-5 $POLICYID.637573746f6d636f696e" \
--out-file "$TX_BODY_FILE_2"
 
cardano-cli conway transaction sign \
--signing-key-file "$SPENDING_KEY" \
--signing-key-file "$MINTING_KEY" \
--script-file "$SCRIPT" \
--tx-body-file  "$TX_BODY_FILE_2" \
--out-file  	"TX_FILE_2"
 
cardano-cli conway transaction submit --tx-file  "$TX_FILE_2" 

Note: Destroying tokens requires both the payment credential for using the UTXO entry with the tokens, and a credential for the minting policy script.

Native assets

## **Plutus scripts**

This tutorial covers the basics of using the Cardano CLI to create transactions that involve executing Plutus scripts. Please checkout Plutus user guide to learn how to write Plutus scrtipts.

**Basic validator plutus script**

For this tutorial we borrowed a simple validator script from the Plutus Pioneer Program. We will use the FortyTwoTyped.hs script. You can download the serialized script form this link.

FortyTwoTyped.hs
The relevant part of this Plutus script is:

-- This validator succeeds only if the redeemer is 42
--              Datum  Redeemer        ScriptContext
mk42Validator :: () -> Integer -> PlutusV2.ScriptContext -> Bool
mk42Validator _ r _ = traceIfFalse "expected 42" $ r == 42

The type signature of mk42Validator tells us that it takes three arguments and returns a Bool:

mk42Validator :: () -> Integer -> PlutusV2.ScriptContext -> Bool

As hinted by the comment line, these three arguments correspond to Datum, Redeemer and Script Context.

On the function definition we see that it does not care about the Datum and the Script Context and only cares about the redeemer.

mk42Validator _ r _ = traceIfFalse "expected 42" $ r == 42

The underscores (_) in the datum and script context positions mean that the function will accept anything for these values and completely ignore them in the function body. The function does not use these values. In the end, the result only depends on the redeemer value r. The script succeeds when the correct redeemer is provided (r == 42) and fails with any other redeemer value.

So, the general plan for using this script is:

Lock some funds in the script address.
Attempt to spend the locked funds. The script will only permit the spending if the correct redeemer is provided.
Get the compiled script.
Compiling the script is out of the scope of this tutorial, we can get the compiled version with:

wget https://raw.githubusercontent.com/input-output-hk/plutus-pioneer-program/fourth-iteration/code/Week02/assets/fortytwotyped.plutus


{
    "type": "PlutusScriptV2",
    "description": "",
    "cborHex": "5907ac5907a901000032323322323232323232323232323233223232323232222323253353232325335333573466e1c009205401c01b101c13357389210b65787065637465642034320001b3333573466e1cd55cea80224000466442466002006004646464646464646464646464646666ae68cdc39aab9d500c480008cccccccccccc88888888888848cccccccccccc00403403002c02802402001c01801401000c008cd405c060d5d0a80619a80b80c1aba1500b33501701935742a014666aa036eb94068d5d0a804999aa80dbae501a35742a01066a02e0446ae85401cccd5406c08dd69aba150063232323333573466e1cd55cea801240004664424660020060046464646666ae68cdc39aab9d5002480008cc8848cc00400c008cd40b5d69aba15002302e357426ae8940088c98c80c0cd5ce01981801709aab9e5001137540026ae854008c8c8c8cccd5cd19b8735573aa004900011991091980080180119a816bad35742a004605c6ae84d5d1280111931901819ab9c03303002e135573ca00226ea8004d5d09aba2500223263202c33573805e05805426aae7940044dd50009aba1500533501775c6ae854010ccd5406c07c8004d5d0a801999aa80dbae200135742a00460426ae84d5d1280111931901419ab9c02b028026135744a00226ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135744a00226ae8940044d55cf280089baa00135742a00860226ae84d5d1280211931900d19ab9c01d01a018375a00a6666ae68cdc39aab9d375400a9000100c11931900c19ab9c01b018016101713263201733573892010350543500017135573ca00226ea800448c88c008dd6000990009aa80b111999aab9f0012500a233500930043574200460066ae880080508c8c8cccd5cd19b8735573aa004900011991091980080180118061aba150023005357426ae8940088c98c8050cd5ce00b80a00909aab9e5001137540024646464646666ae68cdc39aab9d5004480008cccc888848cccc00401401000c008c8c8c8cccd5cd19b8735573aa0049000119910919800801801180a9aba1500233500f014357426ae8940088c98c8064cd5ce00e00c80b89aab9e5001137540026ae854010ccd54021d728039aba150033232323333573466e1d4005200423212223002004357426aae79400c8cccd5cd19b875002480088c84888c004010dd71aba135573ca00846666ae68cdc3a801a400042444006464c6403666ae7007806c06406005c4d55cea80089baa00135742a00466a016eb8d5d09aba2500223263201533573803002a02626ae8940044d5d1280089aab9e500113754002266aa002eb9d6889119118011bab00132001355013223233335573e0044a010466a00e66442466002006004600c6aae754008c014d55cf280118021aba200301213574200222440042442446600200800624464646666ae68cdc3a800a40004642446004006600a6ae84d55cf280191999ab9a3370ea0049001109100091931900819ab9c01301000e00d135573aa00226ea80048c8c8cccd5cd19b875001480188c848888c010014c01cd5d09aab9e500323333573466e1d400920042321222230020053009357426aae7940108cccd5cd19b875003480088c848888c004014c01cd5d09aab9e500523333573466e1d40112000232122223003005375c6ae84d55cf280311931900819ab9c01301000e00d00c00b135573aa00226ea80048c8c8cccd5cd19b8735573aa004900011991091980080180118029aba15002375a6ae84d5d1280111931900619ab9c00f00c00a135573ca00226ea80048c8cccd5cd19b8735573aa002900011bae357426aae7940088c98c8028cd5ce00680500409baa001232323232323333573466e1d4005200c21222222200323333573466e1d4009200a21222222200423333573466e1d400d2008233221222222233001009008375c6ae854014dd69aba135744a00a46666ae68cdc3a8022400c4664424444444660040120106eb8d5d0a8039bae357426ae89401c8cccd5cd19b875005480108cc8848888888cc018024020c030d5d0a8049bae357426ae8940248cccd5cd19b875006480088c848888888c01c020c034d5d09aab9e500b23333573466e1d401d2000232122222223005008300e357426aae7940308c98c804ccd5ce00b00980880800780700680600589aab9d5004135573ca00626aae7940084d55cf280089baa0012323232323333573466e1d400520022333222122333001005004003375a6ae854010dd69aba15003375a6ae84d5d1280191999ab9a3370ea0049000119091180100198041aba135573ca00c464c6401866ae7003c0300280244d55cea80189aba25001135573ca00226ea80048c8c8cccd5cd19b875001480088c8488c00400cdd71aba135573ca00646666ae68cdc3a8012400046424460040066eb8d5d09aab9e500423263200933573801801200e00c26aae7540044dd500089119191999ab9a3370ea00290021091100091999ab9a3370ea00490011190911180180218031aba135573ca00846666ae68cdc3a801a400042444004464c6401466ae7003402802001c0184d55cea80089baa0012323333573466e1d40052002200723333573466e1d40092000200723263200633573801200c00800626aae74dd5000a4c240022440042440029210350543100112323001001223300330020020011"
}


Build the script address:
cardano-cli address build \
--payment-script-file fortytwotyped.plutus \
--out-file script.addr

cat script.addr
addr_test1wzqvkn6myu8ay080wdsju4s4mzuzgwwv9rxsz2xuc8ycaus9zk46q

Lock funds in the script address
Let's lock 10 ADA in the script.

Prepare the Datum:
To do this, we must create a transaction that sends 10 ADA to the script address and attach a datum. This particular script does not care about the content of the Datum, so we will use Haskell's unit data type.

The unit data type is represented by (). It is a special type that has only one value, also written as (). This type is analogous to void in other programming languages, but it is a proper type with a single value.

We can create the file datum.json with the following content:

{"constructor":0,"fields":[]}

Submit the the transaction to lock the funds:
When building the transaction, it is important to use the --tx-out-inline-datum-file flag immediately after the --tx-out option to which the datum should be attached. The order of these options matters.

cardano-cli conway transaction build \
--tx-in $(cardano-cli conway query utxo --address $(< payment.addr) --output-json | jq -r 'keys[0]') \
--tx-out $(< script.addr)+10000000 \
--tx-out-inline-datum-file datum.json \
--change-address $(< payment.addr) \
--out-file lock.tx

>Estimated transaction fee: Coin 171969


Sign the transaction with the payment.skey

cardano-cli conway transaction sign \
--tx-file lock.tx `\
-signing-key-file payment.skey \
--out-file lock.tx.signed

Submit the transaction

cardano-cli conway transaction submit \
--tx-file lock.tx.signed 

>Transaction successfully submitted.

Query the utxos in the script address
cardano-cli query utxo --address $(< script.addr) --output-json
{
    "4c31734468d4f5957328f8fcbb612201c2f774b4ef2bde09b0c6e12cb7ce3f10#0": {
        "address": "addr_test1wzqvkn6myu8ay080wdsju4s4mzuzgwwv9rxsz2xuc8ycaus9zk46q",
        "datum": null,
        "inlineDatum": {
            "constructor": 0,
            "fields": []
        },
        "inlineDatumhash": "923918e403bf43c34b4ef6b48eb2ee04babed17320d8d1b9ff9ad086e86f44ec",
        "referenceScript": null,
        "value": {
            "lovelace": 10000000
        }
    }
}

Perfect, we have locked 10 ada on the script address, the only way to spend it is by executing the script providing the correct redeeemer.

Attempt to spend the funds passing the wrong redeemer:
We could say that failing is the primarily duty of a Plutus script. Let's check that our script fails if we pass the wrong redeemer.

cardano-cli conway transaction build \
--tx-in $(cardano-cli conway query utxo --address $(< script.addr) --output-json | jq -r 'keys[0]') \
--tx-in-collateral $(cardano-cli conway query utxo --address $(< payment.addr) --output-json | jq -r 'keys[0]') \
--tx-in-script-file fortytwotyped.plutus \
--tx-in-inline-datum-present \
--tx-in-redeemer-value 57 \
--change-address $(< payment.addr) \
--out-file unlock.tx


We will explain this command in detail below, for now lets focus on the fact that we are passing the Integer 57 as redeemer using the flag --tx-in-redeemer-value 57. When we hit Enter, the build command will try to construct the transaction body, running the script in the process.

Command failed: transaction build  Error: The following scripts have execution failures:
the script for transaction input 0 (in ascending order of the TxIds) failed with: 
The Plutus script evaluation failed: An error has occurred:
The machine terminated because of an error, either from a built-in function or from an explicit use of 'error'.
Script debugging logs: expected 42
PT5


The script failed to run. It threw the programmed error message "expected 42" and the error code (PT5) at build time. This indicates that the script failed because we passed the wrong redeemer.

If we really wanted, we could use build-raw to construct the same transaction and bypass this failure on build. However, we would get the same error on submit. This transaction can never make it to the chain because it is being rejected by the local node.

Attempt to spend the funds passing the correct redeemer:
Let's re-use the build command from above, this time we pass the correct redeemer value --tx-in-redeemer-value 42.

cardano-cli conway transaction build \
--tx-in $(cardano-cli conway query utxo --address $(< script.addr) --output-json | jq -r 'keys[0]') \
--tx-in-collateral $(cardano-cli conway query utxo --address $(< payment.addr) --output-json | jq -r 'keys[0]') \
--tx-in-script-file fortytwotyped.plutus \
--tx-in-inline-datum-present \
--tx-in-redeemer-value 42 \
--change-address $(< payment.addr) \
--out-file unlock.tx


Lets break down the command:

--tx-in $(cardano-cli conway query utxo --address $(< script.addr) --output-json | jq -r 'keys[0]')
We use the first UTxO on the script address as input for the transaction. So we are trying to spend the locked funds.

--tx-in-collateral $(cardano-cli conway query utxo --address $(< payment.addr)
--output-json | jq -r 'keys[0]')
Since we are running a Plutus script, we must provide a collateral. We use the first utxo of payment address.

--tx-in-script-file fortytwotyped.plutus
We supply the script file.

--tx-in-inline-datum-present
We need to supply a datum. When we locked the funds a few steps above we put the datum inline with --tx-out-inline-datum-file datum.json this allows us to not supply the datum when trying to spend the funds from the script, instead we are telling the node that the utxo on the script address has the inline datum and the node should get the datum from there.

--tx-in-redeemer-value 42
We pass the Integer 42 as redeemer

--change-address $(< payment.addr)
If sucesfull, the 10 ada locked on the script will be sent to payment.addr. Note that we will pay the transactin fee from this UTXO so payment address should receive a little under 10 ada.

--out-file unlock.tx
We save the transaction body as unlock.tx.

When running the command we get

Estimated transaction fee: Coin 300777

This time, the node validated the transaction and successfully ran the script. The transaction should succeed if we provide the correct witness for the collateral. Let's do that.

cardano-cli conway transaction sign \
--tx-file unlock.tx \
--signing-key-file payment.skey \
--out-file unlock.tx.signed 

cardano-cli conway transaction submit -\
-tx-file unlock.tx.signed

> Transaction successfully submitted.

For tracking purposes, lets find our transaction id

cardano-cli conway transaction txid --tx-file unlock.tx.signed 
74c856f90276315a14bd2bd35b3a2f803b763a1bdfa2648ec30a85a129048131

Query the UTXOs on both addresses. The script address is now empty

cardano-cli query utxo --address $(< script.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------

and the payment address shows the expected utxo 74c856f90276315a14bd2bd35b3a2f803b763a1bdfa2648ec30a85a129048131#0 with the funds we unlocked from the script.

`cardano-cli query utxo --address $(< payment.addr)
                           TxHash                                 TxIx        Amount
--------------------------------------------------------------------------------------
4c31734468d4f5957328f8fcbb612201c2f774b4ef2bde09b0c6e12cb7ce3f10     1        89522687 lovelace + TxOutDatumNone
74c856f90276315a14bd2bd35b3a2f803b763a1bdfa2648ec30a85a129048131     0        9699223 lovelace + TxOutDatumNone
c0e5fe9a87290b137d0acc995f13493eb423f831c8edaa54e6c86f381a31caf3     1        5898934190 lovelace + TxOutDatumNone`


Plutus scripts

## **Cardano governance**

**Cardano ledger eras**

Cardano has undergone various ledger era upgrades – Byron, Shelley, Allegra, Mary, Alonzo, and the current Babbage era. Each era has introduced new functionalities to the network. The upcoming era, Conway, is planned to introduce decentralized governance, implementing CIP-1694 functionality.

![](https://media.discordapp.net/attachments/980490396356476938/1335160394557423626/image.png?ex=679f2884&is=679dd704&hm=aab7cfc284b81b27da61456de7da07b56386c7deb25296c5cbb3fc68eabceae5&=&format=webp&quality=lossless&width=942&height=846)

**Byron era update proposals**

![](https://developers.cardano.org/assets/images/upbyron-f2ed5bf108d59bba69571c5fe3b62718.png)

The general mechanism for updating protocol parameters in Byron is as follows:

Update proposal is registered. An update proposal starts with a transaction that proposes new values for some protocol parameters or a new protocol version. This kind of transaction can only be initiated by a genesis key via its delegate.
Accumulating votes. Genesis key delegates vote for or against the proposal. The proposal must accumulate a sufficient number of votes before it can be confirmed. The threshold is determined by the minThd field of the softfork Rule protocol parameter.
Confirmed (enough votes). The system records the 'SlotNo' of the slot in which the required threshold of votes was met. At this point, 2k slots (two times the security parameter k) need to pass before the update is stably confirmed and can be endorsed. Endorsements for proposals that are not yet stably confirmed are not invalid but rather silently ignored.
Stably-confirmed. The last required vote is 2k slots deep. Ready to accumulate endorsements. A block whose header's protocol version number is that of the proposal is interpreted as an endorsement. In other words, the nodes are ready for the upgrade. Once the number of endorsers satisfies a threshold (same as for voting), the confirmed proposal becomes a candidate proposal.
Candidate. Enough nodes have endorsed the proposal. At this point, further 2k slots need to pass before the update becomes a stable candidate and can be adopted.
Stable candidate. The last required endorsement is 2k slots deep.
If there is no stable candidate proposal, then no changes occur. Everything is retained, including a candidate proposal whose threshold-satisfying endorsement was not yet stable and will be adopted in the subsequent epoch unless it gets surpassed in the meantime.

A 'null' update proposal is one that neither increases the protocol version nor the software version. Such update proposals are considered invalid according to the Byron specification.

Update proposals in Shelley and subsequent eras
The update mechanism in Shelley is simpler than in Byron. There is no distinction between votes and proposals. To 'vote' for a proposal, a genesis delegate submits the exact same proposal via a regular transaction signed by the delegate key. Additionally, there is no separate endorsement step:

![](https://developers.cardano.org/assets/images/upshelley-184f27ec16d6bca1caedb3cd1a26bed7.png)

The procedure is as follows:

Register the proposal. During each epoch, a genesis key can submit (via its delegates) zero, one, or many proposals; each submission overrides the previous one. Proposals can be explicitly marked for future epochs; in that case, they are simply not considered until that epoch is reached.
Voting. There is no explicit voting, to vote for a proposal, other delegate key holders must submit the exact same proposal to the chain. The window for submitting proposals ends 6k/f slots before the end of the epoch, where k is the security parameter and f is the active slot coefficient.
Quorum. At the end of the epoch, if the majority of nodes, determined by the Quorum specification constant (which must exceed half the total number of nodes), have most recently submitted the identical proposal, it becomes adopted.
Update. The update is applied at the epoch boundary.
Changing the values of the protocol parameters and global constants was done via an update proposal.

Changing the values of the global constants always requires a software update, including an increase in the protocol version. An increase in the major version indicates a hard fork, while the minor version indicates a soft fork (meaning old software can validate but not produce new blocks).

On the other hand, updating protocol parameters can be done without a software update.

Before the Chang hardfork that brought Cardano to the Conway era, only genesis delegate key holders were able to submit and vote on proposals.

Conway era update proposals
The Conway ledger era introduces a new governance framework to Cardano, marking a significant evolution in how decisions about the protocol are made. Building on the foundations laid in previous eras, Conway empowers Cardano with a decentralized governance model where decision-making is accessible to stakeholders. Key features include the introduction of Delegated Representatives (DReps), the Constitutional Committee, and an decision making role for Stake Pool Operators (SPOs). These entities collaborate through a formalized voting system to vote on governance actions that can be proposed by any ada holder. These governance bodies are in charge of treasury funds, adding or removing members from the constitutional committee, making updates to the Cardano Constitution and changes to protocol parameters. Conway era makes Cardano more resilient and 100% community-driven.

The process for submitting and voting protocol update proposals undergoes significant changes in the Conway era. First, Genesis delegations and MIR certificates are eliminated. In DState, the fields associated with these features are no longer included, and DelegEnv no longer contains the fields it had in the Shelley era, effectively rendering the genesis keys obsolete.

**Governance actions**

In the Conway ledger era, any ada holder can submit a Governance action, which is the on-chain method to put a proposal to the consideration of the three governance bodies. There are 7 types of governance actions:

![](https://media.discordapp.net/attachments/980490396356476938/1335161827956490371/image.png?ex=679f29d9&is=679dd859&hm=6205c3ca0d5a51f18626e8ed8c5c8fb15221f1e9e40b21d2973aff1eb92e21bd&=&format=webp&quality=lossless&width=1409&height=846)

Ratification thresholds
Each type of governance action requires meeting a different mix of voting thresholds to be ratified. The table below depicts the thresholds as set on the Conway genesis file:

![](https://media.discordapp.net/attachments/980490396356476938/1335162211689304115/image.png?ex=679f2a35&is=679dd8b5&hm=170a35ac5e5d0cb210f798368a3ce9fcc62da25eb610fa79cc50d2c724f896da&=&format=webp&quality=lossless&width=794&height=846)

Some parameters (from different groups) are relevant to security properties of the system. Any proposal attempting to change such a parameter requires an additional vote of the SPOs, with the threshold 0.51

maxBlockBodySize
maxTxSize
maxBlockHeaderSize
maxValueSize
maxBlockExecutionUnits
txFeePerByte
txFeeFixed
utxoCostPerByte
govActionDeposit
minFeeRefScriptCostPerByte
Hash Protection
NoConfidence, UpdateCommittee, NewConstitution, TriggerHF, and ChangePParams actions all require a reference to the last enacted governance action that modified the same state in order to be enacted. Among these, NoConfidence and UpdateCommittee modify the same state, while the others—NewConstitution, TriggerHF, and ChangePParams—each modify their own independent states. In contrast, TreasuryWdrl and Info do not require such a reference, as they do not affect the state in conflicting or non-commutative ways. This ensures that the final state after enactment matches the intended state at the time the proposal was submitted, and a proposal's eligibility for enactment may change based on other proposals being enacted.


Votes and Proposals
Proposals
To propose a governance action, a Proposal needs to be submitted in a transaction. Beside the proposed governance action, it requires:

potentially a pointer to the previous action See Hash Protection,
potentially a pointer to the proposal policy (the guardrial script for ChangePParams and TreasuryWdrl),
a deposit, which will be returned to returnAddr, and
an anchor, providing further information about the proposal.
Votes
A vote is Yes, No or Abstain, to be cast, a vote must include additional details such as the voter's role (e.g., CC, DRep, or SPO) and their credential, along with the specific governance action ID being voted on. Optionally, an anchor may be provided to give context or explain the reasoning behind the vote.

Governance Action lifecycle
A proposed governance action has a lifespan of 6 epochs, as defined by the protocol parameter "govActionLifetime": 6 in the Conway genesis file.
During this period, governance bodies can vote on the proposal. If the action reaches the end of its lifespan without being ratified, it automatically expires.

![](https://developers.cardano.org/assets/images/conwayup-6b55549f06309e9b0957a714402db82e.png)

At every epoch boundary within the Governance action lifetime, proposals and votes are snapshotted. The DRepPulserState snapshot includes:
SPOs, DReps, CC members,
their votes (yes, no, abstain),
stake distribution 'Mark'
delegation map.
The system will use the DRepPulserState snapshot to calculate the DReps and SPOs votingStakeDistribution. This computation is expensive to run, therefore it is not executed at the epoch boundary, intead, the DRep Pulser performs this computation gradually with every TICK during the first 4k/f slots.
The Hardfork-combinator requires to "know" about a potential hardfork 6k/f slots before the epoch change. To meet this requiterement, if the votingStakeDistribution is not finished by the time we reach that point, the computation is forced to complete.
On the first TICK that occures within the last 6k/f slots of the epoch (2 stability windows), the system solidifies the next epoch protocol parameters, see solidifyNextEpochPParams. The RATIFY and ENACT rules are executed at this point to deterimne the enactState. If a governance action has enough votes (meets the thresholds for its type), it is said to be Ratified and it is added to the enactState.
At the next epoch boundary, the system applies the enactState.
A governance action Expires if it does not accumulate enough votes during it's lifetime. Its last chance to be ratified is when the DRepPulser talies the votes on the epoch following its expiration.

[Registering as Delegated Representative (DReps)](https://developers.cardano.org/docs/get-started/cardano-cli/governance/register%20drep)

[Delegate votes to a Delegated Representative (DRep)](https://developers.cardano.org/docs/get-started/cardano-cli/governance/delegate%20to%20a%20drep

[Constitutional committee](https://developers.cardano.org/docs/get-started/cardano-cli/governance/constitutional%20committee)

[Submitting governance actions](https://developers.cardano.org/docs/get-started/cardano-cli/governance/create-governance-actions)

[Submitting votes as DRep, Stake pool or Constitutional Committee member
](https://developers.cardano.org/docs/get-started/cardano-cli/governance/submit-votes)

[Governance related queries.](https://developers.cardano.org/docs/get-started/cardano-cli/governance/gov-queries)


Cardano governance

## **Installing cardano-wallet**

**Overview**

In this guide, we will show you how to compile and install cardano-wallet into your operating system of choice, directly from the source-code. This component provides a CLI (Command Line Interface) and Web API for creating multiple Cardano wallets, sending transactions, getting transaction history details, wallet balances and more!

**note**

If you want to avoid compiling the binaries yourself, you can download the latest pre-built binaries from the GitHub repository: cardano-wallet Releases

This guide assumes you have installed cardano-node and cardano-cli into your system. If not you can refer to Installing cardano-node guide for instructions on how to do that.

important
You must connect your cardano-node to a testnet network and make sure it is fully synchronized. If you are not sure how to do that, It is recommended to read Running cardano-node guide before proceeding.

**Choose your Platform**

[MacOS / Linux](https://developers.cardano.org/docs/get-started/cardano-wallet/cardano-wallet#macos--linux)

Windows

MacOS / Linux
In this section, we will walk you through the process of downloading, compiling and installing cardano-wallet into your Linux / MacOS based operating system.

Downloading & Compiling
We need to install cabal, if we don't have it. See the following link for instructions: https://www.haskell.org/cabal/

If you have followed the Installing cardano-node guide, You should have the $HOME/cardano-src directory. If not, let's create a working directory to store the source-code and build for cardano-wallet.

mkdir -p $HOME/cardano-src
cd $HOME/cardano-src

Next we download the cardano-wallet source-code:

git clone https://github.com/cardano-foundation/cardano-wallet.git 
cd ./cardano-wallet/ 

Switch the repository to the latest tagged commit:

TAG=$(git describe --tags --abbrev=0) && echo latest tag $TAG 
git checkout $TAG

important
You can check the latest available version / tag by visiting the cardano-wallet Github Release page. At the time of writing this, the current version is v2021-11-11. You can list all tags also with git tag -l command.

Building and installing the node
We can now build cardano-wallet code to produce executable binaries.

cabal build all

Install the newly built cardano-wallet binary to the $HOME/.local/bin directory:

cabal install cardano-wallet

Check the version that has been installed:

cardano-wallet version

You should see something like this:

v2021-11-11 (git revision: dac16ba7e3bf64bf5474497656932fd342c3b720)

Congratulations, you have successfully installed cardano-wallet into your Linux/MacOS system! 🎉🎉🎉

**Windows**

**important
**
Currently, the Windows installation guide is still in-progress. In the meantime we recommend using WSL (Windows Subsystem for Linux) to get a Linux environment on-top of Windows. Once you have that installed you can use the Linux guide to install and run cardano-node within WSL.

Optionally, you can download the latest precompiled Windows binary from the GitHub repository: cardano-wallet Releases


[Air Gap Environment](https://developers.cardano.org/docs/get-started/air-gap)

[Secure Transaction Workflow](https://developers.cardano.org/docs/get-started/secure-workflow)

[Get Started with Aiken](https://developers.cardano.org/docs/get-started/aiken)

[Overview of the Blockfrost ecosystem](https://developers.cardano.org/docs/get-started/blockfrost/overview)

[Log in / Sign up](https://developers.cardano.org/docs/get-started/blockfrost/get-started)

[Cardano API](https://developers.cardano.org/docs/get-started/blockfrost/cardano-api)

[IPFS and Milkomeda API](IPFS and Milkomeda API)

[Secure Webhooks](https://developers.cardano.org/docs/get-started/blockfrost/secure-webhooks)

[Open Source](https://developers.cardano.org/docs/get-started/blockfrost/open-source)

[cardanocli-js](https://developers.cardano.org/docs/get-started/cardanocli-js)

[cardano-wallet-js](https://developers.cardano.org/docs/get-started/cardano-wallet-js)

[cscli](https://developers.cardano.org/docs/get-started/cscli)

[Dandelion APIs](https://developers.cardano.org/docs/get-started/dandelion-apis)

[Koios](https://developers.cardano.org/docs/get-started/koios)

[Lucid Evolution](https://developers.cardano.org/docs/get-started/lucid-evolution)





Installing cardano-wallet

## **Technical Concepts**

Get started with the technical concepts
To get the most out of the Cardano Developer Portal, you should have programming experience and a basic understanding of blockchain concepts such as UTxO, transactions, addresses, key derivation, and networking.

Introduction to Cardano: the big picture
Learn fundamental terms like blockchain, consensus, decentralization delegation and incentives. Understand the big picture of Cardano and why stake pools are so important.

<iframe width="859" height="325" src="https://www.youtube.com/embed/zJUJG6V0Y1o" title="Cardano stake pool tutorial | Introduction to Cardano" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Unspent Transaction Output (UTxO)**

UTxO or Unspent Transaction Outputs are how ada moves around the Cardano network. Learn how they work in the Cardano ledger.

<iframe width="859" height="325" src="https://www.youtube.com/embed/e4YZkgi4V3U" title="Cardano: NerdOut - UTXOs" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Transactions
Learn what is inside the guts of a Cardano transaction. We show how unsigned and signed transactions look like, and we cover how signing works.

<iframe width="859" height="325" src="https://www.youtube.com/embed/OSNf1MgAbII" title="Cardano: NerdOut - Transactions" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Addresses**

Cardano Addresses are used as destinations to send ada on the blockchain. We break them down into their parts and show how they're created.

<iframe width="859" height="325" src="https://www.youtube.com/embed/NjPf_b9UQNs" title="Cardano: NerdOut - Addresses" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Transaction Fees**

Understand how transaction fees are calculated on Cardano. Brief coverage of the topics reserve and treasury.

<iframe width="859" height="325" src="https://www.youtube.com/embed/lpSIpPWp7H8" title="Cardano: NerdOut - Transaction Fees" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Mnemonic seed phrase (BIP39)
BIP39 is the standard for creating a mnemonic seed phrase for wallets. In this video, we break down how it's created from randomness on Cardano.

<iframe width="859" height="325" src="https://www.youtube.com/embed/5P1jx1ELUHk" title="Cardano: NerdOut - BIP39" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Key Derivation**

Key Derivation is the process a wallet uses to go from a mnemonic phrase to a whole set of keys and addresses that the wallet controls.

<iframe width="859" height="325" src="https://www.youtube.com/embed/4tSQBK75CPU" title="Cardano: NerdOut - Key Derivation" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Block and transaction propagation
Learn how transactions make it from the mempool into blocks and how blocks move around the network.

<iframe width="859" height="325" src="https://www.youtube.com/embed/K7c-5S-23dg" title="Cardano: NerdOut - Block &amp; Tx Propagation" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Networking**

We answer your questions about how nodes on Cardano talk to each other. Learn about TCP Sockets, mini-protocols and the future of P2P.

<iframe width="859" height="325" src="https://www.youtube.com/embed/pyhYtLgn1r0" title="Cardano: NerdOut - Networking" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Slot Lottery**

In this video, we describe exactly how a stake pool on Cardano gets elected to make a block.

<iframe width="859" height="325" src="https://www.youtube.com/embed/M3Xq1qz3ljU" title="NerdOut - Deep Dive: The Slot Lottery" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Slot Battles**

On Cardano, slot battles happen when two pools try to make a block in the same slot (at the same time). We break down how the blockchain determines which block should win and what is the "correct" source of truth on the blockchain.

<iframe width="859" height="325" src="https://www.youtube.com/embed/Cm5pBM7UYa0" title="Cardano: NerdOut Slot Battles" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**Catalyst Voting**

What is Catalyst voting, how to register, how to vote and why you should participate.

<iframe width="859" height="325" src="https://www.youtube.com/embed/OwGdSw1T0aI" title="Cardano: NerdOut - Catalyst Voting" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Franken Addresses

Franken Addresses are a way to register additional pledge to a pool without registering a second owner on the blockchain.

<iframe width="859" height="325" src="https://www.youtube.com/embed/KULzovfWn-M" title="Cardano: NerdOut - Franken Addresses" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

**NFT**

Non-Fungible Tokens on cardano are native assets that represent immutable art or physical things.

<iframe width="859" height="325" src="https://www.youtube.com/embed/P-wQ0VymzKU" title="Cardano: NerdOut - NFTs" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

[more...](https://developers.cardano.org/docs/get-started/technical-concepts)







Technical Concepts

## **Testnets**

Get started with testnets
Cardano testnets
The Cardano testnets are your playgrounds when testing Cardano integration, building with transaction metadata, exploring native tokens or learning how to operate a stake pool.

The testnets are an essential part of the development process for Cardano, as they allow developers to test and refine their code before deploying it on the live network, ultimately improving reliability and security.

What testnet should I use?
Preview Testnet
The Preview Testnet is a testing environment used to showcase new features and functionality to the Cardano community before they are deployed on the Mainnet.
It allows developers and users to test and provide feedback on new features and changes before they are released to the wider community.
The Preview Testnet helps to ensure that new features are user-friendly and meet the needs of the community, ultimately improving the user experience on the Mainnet.
Leads Mainnet hard forks by at least 4 weeks.
You can download the current Cardano blockchain network configuration files for Preview Testnet here: The Cardano Operations Book > Preview Testnet.

Guild Network
Guild Network is a community maintained public testnet network that is primarily useful for 'quick' testing for development/integrations, as it runs short 1-hour epochs.
The primary use case for this network is often short-term scope-specific testing, it has gone through previous forks on the Cardano chain with minimal data to ensure we do have different data objects across older forks. The faucet distribution for this network is manual and available with members across timezones based on request in support channel.
The timeline for forks lead Mainnet but are flexible depending on community needs that could be discussed on github (unless specific conditions require testing beforehand), and is useful for testing data against longer history (over 10K epochs).
You can download the current Cardano blockchain network configuration files for Guild Network here

Pre-Production Testnet
The Pre-Production Testnet is a testing environment used to validate major upgrades and releases before deployment to the Mainnet.
It is a staging area where developers can simulate real-world scenarios and ensure that everything is working as expected before going live.
The preprod testnet helps to minimize the risk of bugs, security issues, and other problems that could negatively impact the Mainnet.
Hard forks at approximately the same time as Mainnet (within an epoch of each other)
You can download the current Cardano blockchain network configuration files for Pre-Production Testnet here: The Cardano Operations Book > Pre-Production Testnet.

Summary
The Pre-Production Testnet is a more comprehensive testing environment used to validate major upgrades, while the Preview Testnet is a more targeted testing environment used to showcase new features and gather feedback from the community.

Where to get a testnet wallet?
Lace Wallet is a lightweight wallet developed by IOG and supports both PreProd, Preview and Sancho testnets.
Eternl Wallet is a another lightweight wallet supporting both with PreProd, Preview and Sancho testnets.
Yoroi Nightly Wallet is a lightweight wallet developed by Emurgo and supports PreProd, PreView and Sancho testnet.
Typhon Wallet is a lightweight wallet developed by StricaHQ and supports PreProd testnet.
Flint Wallet is a lightweight wallet developed by dcSpark and supports PreProd testnet.
Ledger Nano S and Ledger Nano X are hardware wallets that support both PreProd and Preview testnets.
Cardano-wallet is a convenient way of using the cardano-wallet HTTP Application Programming Interface.
It's important to note that while all of these wallets support Cardano testnets, you will need to choose the testnet network option within the wallet when setting it up or switching to testnet, or choose the right version before you install a specific testnet wallet.

In preparation for the Chang Hardfork in the second half of 2024, the so-called Sancho Testnet has been in place since the end of 2023 in which all governance actions, functions and tools are tested. Here is a list of wallets that support Sanchonet.

Where to get test ada?
Because the Cardano testnets are independent networks, separate from the Cardano mainnet, they require their own token: test ada (tAda).

Test ada is worth nothing. With it you can safely perform all tests free of charge - the reason why you want to develop on the testnets.

To get free test ada for Preprod or Preview, you need to visit: Cardano Testnet Faucet.

In depth explanation about Cardano Testnet Faucet can be found here.

Which block explorers can I use for the Cardano testnets?
testnet.cardanoscan.io is a Pre-Production and Preview block explorer by Cardanoscan.
testnet.cexplorer.io is a Pre-Production and Preview block explorer by Cexplorer.
Which metadata explorers can I use for the Cardano testnets?
cardanoscan.io/metadata is a preprod metadata explorer by CardanoScan.io
cexplorer.io/metadata is a preprod metadata explorer by cExplorer.io
What kind of monitoring tools are available for the testnets?
Set up your own node's Grafana/Promtheus monitoring system

[more...](https://developers.cardano.org/docs/get-started/testnets-and-devnets)



Testnets

## **Developer Community**

**Get Started in the Cardano Developer Community**

Apart from the two leading platforms Stack Exchange and Cardano Forum, Cardano developers and stake pool operators spread across different platforms. Each with its niche.

**Cardano developers channels**

**cardano.stackexchange.com**

Stack Exchange communities are democratically created and maintained. It is a question-and-answer website, not meant for extensive discussion or opinions.

**forum.cardano.org**

The developer categories on the Cardano Forum is an excellent place for extensive discussions and opinions, but also to get support.

**[Cardano Community Discord](https://discord.gg/kfATXEENPD)**

Visit the developer categories on the Cardano Community Discord if you prefer chat-style conversations.

**[reddit.com/r/CardanoDevelopers](https://www.reddit.com/r/CardanoDevelopers/)**

A subreddit dedicated to everyone building on the Cardano blockchain.

t.me/CardanoDevelopersOfficial

Chat style conversations on Telegram in one of the oldest Cardano developer groups.

IOG Technical Discord

Head to the IOG Discord if you want to join the Plutus Pioneers.

t.me/IOHK_Marlowe
Dedicated channel for Marlowe developers and users. Marlowe is a specialised domain-specific language for financial smart contracts on Cardano. You can ask questions, participate in discussions and meet the team behind Marlowe.

**Developer Portal Discord**

If you would like to help develop the Developer Portal further, please join our Discord.

**CIPs - biweekly meetings**

CIP meetings discuss Cardano Improvement Proposals every other week. Join Editors and community members in the dedicated discord server to keep up with the ongoing technical discussions regarding standards, processes and ongoing Cardano conversations.

**Stake pool operator channels**

t.me/CardanoStakePoolWorkgroup
Best practice workgroup on Telegram for stake pool operators. This group is hectic. A good resource to search for answers.

**forum.cardano.org**

If you care about well structured, long format discussions, visit the stake pool operator categories on forum.cardano.org.

**Developer Surveys**

**Developer Ecosystem Survey 2022**

For the first time ever, an annual survey to assess the state of the Cardano developer ecosystem was conducted. This survey comes as part of our commitment to both empower the Cardano community and foster the open source maturity of the Cardano ecosystem.

**Developer Ecosystem Survey 2023**

The second edition of the annual survey to assess the state of the Cardano developer ecosystem was conducted.



Developer Community

Welcome to the Cardano Developer Portal. This content is for technical people; if you are looking for a Cardano wallet please head to the showcase section.

It is noteworthy to mention that the Developer Portal covers everything you can do today on the Cardano mainnet.

Welcome to the Cardano Developer Portal. This content is for technical people; if you are looking for a Cardano wallet please head to the showcase section.

Getting Started Developing

Course Details

Level

Ratings

Modules

Lessons

Holder $WORK Price

Contact Us

Documentation

Navigation