Building the Node

Building the Node

Integration of the ledger, consensus, networking and node shell repositories.

Logging is provided as a feature by the node shell to the other packages.

The cardano-node is the top level for the node and aggregates the other components from other packages: consensus, ledger and networking, with configuration, CLI, logging and monitoring. The node no longer incorporates wallet or explorer functionality. The wallet backend and explorer backend are separate components that run in separate external processes that communicate with the node via local IPC.

Network Configuration, Genesis and Topology Files

Keep in mind that the latest supported networks can be found at https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/index.html

How to build

Documentation for building the node can be found at the following link

(https://docs.cardano.org/getting-started/installing-the-cardano-node)

Make sure that you download the latest version of cardano-node and cardano-cli.

https://hydra.iohk.io/build/7760210 (Linux) https://hydra.iohk.io/build/7760171 (Win64) https://hydra.iohk.io/build/7760341 (Macos)

Windows Executable

This can be downloaded from the following link. https://hydra.iohk.io/build/7760171

The download includes cardano-node.exe and a.dll. to run the node with cardano-node run you need to reference a few files and directories as arguments. You can just copy these directly from the cardano-node repo into the executables directory. The command to run the node on mainnet looks like this.

cardano-node.exe run --topology ./mainnet-topology.json --database-path ./state --port 3001 --config ./configuration-mainnet.yaml --socket-path \\.\pipe\cardano-node

Docker image

The docker image with the latest version of cardano-node is availible at the link below https://hub.docker.com/r/inputoutput/cardano-node

cardano-node

This refers to the client being used when running a node.

The general synopsis is as follows

Usage: cardano-node run [--topology FILEPATH] [--database-path FILEPATH]
                        [--socket-path FILEPATH]
                        [--byron-delegation-certificate FILEPATH]
                        [--byron-signing-key FILEPATH]
                        [--shelley-kes-key FILEPATH]
                        [--shelley-vrf-key FILEPATH]
                        [--shelley-operational-certificate FILEPATH]
                        [--host-addr IPV4-ADDRESS]
                        [--host-ipv6-addr IPV6-ADDRESS]
                        [--port PORT]
                        [--config NODE-CONFIGURATION] [--validate-db]
  Run the node.

• --topology - Filepath to a topology file describing which peers the node should connect to. • --database-path - path to the blockchain database.

• --byron-delegation-certificate - An optional path to the Byron delegation certificate. The certificate allows the delegator (The user of the certificate) to give his/her own block signing rights to somebody else (the delegatee). The delegatee can then sign blocks of behalf of the delegator

• --byron-signing-key - Optional path to the Byron signing key.

• --shelly-signing-key - Optional path to the Shelly signing key.

• --shelly-kes-key - Optional path to the shelly KES signing key.

• --shelly-vrf-key - Optional path to the Shelly VRF signing key.

• --shelly-operational-certificate - Optional path to the Shelly operation certificate. • --socket-path - Path to the socket file.

• --host-addr - Optionally specify your node's IPv4 address.

• --host-ipv6-addr - Optionally specify your node's IPv4 address.

• --port - Specify the filepath to the config .ymal file. This is the file that's responsible for all the other node's required settings. You can find examples in configuration (e.g. https://github.com/input-output-hk/cardano-node/blob/master/configuration/defaults/simpleview/config-0.yaml).

• --Validate-db - Flag to revalidate all on-disk database files

Configuration .ymal files

The --config flag points to a .ymal file which is responsible to configurig the logging & other important settings for your node. E.g. see the Byron mainnet configuration in the following link. Some of the more important settings will be below the link.

https://github.com/input-output-hk/cardano-node/blob/master/configuration/defaults/byron-mainnet/configuration.yaml

• Protocol: RealPBFT -- The protocol the node will execute

• RequiresNetworkMagic: RequiresNoMagic -- Used to distinquish between the mainnet (RequiresNoMagic) and the testnets (RequiresMagic)

Logging

Logs are output to the logs/ dir.

Ptofiling & statistics

Make sure you see scripts/README.md for how to obtain profiling information using the scripts.

Scripts

Be sure you've seen scripts/README.md for information on the various scripts.

Cardano-cli

A CLI utility to support a variety of key material operations (genesis, migration, pretty-printing) for different system generations. Usage documentation can be found at the following link.

cardano-cli/README.md

The general synopsis is on the following line of code.

Usage: cardano-cli (Era based commands | Byron specific commands | Miscellaneous commands)

Keep in mind that the exact invocation command depends on the enviornment. If you only have cardano-cli bult, without installing it, then you have to prepend cabal run -- before cardano-cli. From now on we'll just assume that the necessary enviornment-specific adjustment has been made. Now you'll only have to mention cardano-cli.

The subcommands are subdivided in groups and their full name list is visible in the output of cardano-cli --help.

Remember that all the subcommands have help availible. An example is visible below.

cabal run -- cardano-cli -- byron key migrate-delegate-key-from --help

cardano-cli -- byron key migrate-delegate-key-from
Usage: cardano-cli byron key migrate-delegate-key-from --from FILEPATH
                                                       --to FILEPATH
  Migrate a delegate key from an older version.


Available options:
  --byron-legacy-formats   Byron/cardano-sl formats and compatibility
  --byron-formats          Byron era formats and compatibility
  --from FILEPATH          Signing key file to migrate.
  --to FILEPATH            Non-existent file to write the signing key to.
  -h,--help                Show this help text

Genesis operations

The Byron genesis operations will create a directory that contains all the following bullet points.

• genesis.json: The genesis JSON file itself.

• avvm-seed.*.seed: Ada Voucher Vending Machine seeds (secret). Affected by --avvm-entry-count and --avvm-entry-balance.

• delegate-keys.*.key: Delegate private keys. Affected by: --n-delegate-addresses.

• delegation-cert.*.json: Delegation certificates. Affected by: --n-delegate-addresses.

• genesis-keys.*.key: Genesis stake private keys. Affected by: --n-delegate-addresses, --total-balance.

• poor-keys.*.key: Non-delegate private keys with genesis UTxO. Affected by: --n-poor-addresses, --total-balance.

More details on the Byron Genesis JSON file can be found in the following link

docs/reference/byron-genesis.md

Byron genesis delegation and related concepts are also described in detail in the link below

https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/byronLedgerSpec/latest/download-by-type/doc-pdf/ledger-spec

Key operations

Note that key operations don't support password-protected keys.

Signing key generation & verification key extraction

Signing kets can be generated using the keygen subcommand.

Extracting a verification key out of the signing key is preformed by the to verification subcommand.

Delegate key migration.

In order to continue using a delegate key from the Byron legacy era in the new implementation, it needs to be migrated over. That is done by the migrate-delegate-key-from the follwing subcommand.

$ cabal v2-run -- cardano-cli byron key migrate-delegate-key-from
        --from key0.sk --to key0Converted.sk

Signing key queries

One can gather information about signing key's properties through the signing-key-public and signing-key-address subcommands. The latter of the two commands requires network magic.

$ cabal v2-run -- cardano-cli byron key signing-key-public --byron-formats --secret key0.sk

public key hash: a2b1af0df8ca764876a45608fae36cf04400ed9f413de2e37d92ce04
public key: sc4pa1pAriXO7IzMpByKo4cG90HCFD465Iad284uDYz06dHCqBwMHRukReQ90+TA/vQpj4L1YNaLHI7DS0Z2Vg==

$ cabal v2-run -- cardano-cli signing-key-address --byron-formats --secret key0.pbft --testnet-magic 42

2cWKMJemoBakxhXgZSsMteLP9TUvz7owHyEYbUDwKRLsw2UGDrG93gPqmpv1D9ohWNddx
VerKey address with root e5a3807d99a1807c3f161a1558bcbc45de8392e049682df01809c488, attributes: AddrAttributes { derivation path: {} }

Transactions

Creation

Transactions can be created via the issue-genesis-utxo-expenditure and issue-utxo-expenditure commands.

The easiest way way to create a transactionis by using the scripts/benchmarking/issue-genesis-utxo-expenditure.sh script as follows.

./scripts/benchmarking/issue-genesis-utxo-expenditure.sh transaction_file

NB: This by efault creates transactions based on configuration/defaults/liveview/config-0.yaml

If you don't have a genesis_file you can run scripts/benchmarking/genesis.sh to create an example genesis file for you. The script scripts/benchmarking/issue-genesis-utxo-expenditure.sh has defaults for every requirement of the issue-genesis-utxo-expenditure command.

Submission

The submit-tx subcommand gives you the option of submitting a pre-signed transaction in its war wire format. (See GenTx for Byron transactions)

The canned scripts/benchmarking/submit-tx.sh script submits the supplied transaction as a testnet launched by scripts/benchmarking/shelly-testnet-liveview.sh script.

Issuing UTxO expenditure (genesis and regular)

If you plan to make a transaction using UTxO, you can either the following subcommands directly ot you can use one of the canned scripts that make transactions tailored for the testnet cluster. Keep in mind that the first two commands are the directly used subcommands and the next two commands use the canned scripts.

• issue-genesis-utxo-expenditure (genesis UTxO) • issue-utxo-expenditure (normal UTxO)

• scripts/benchmarking/issue-genesis-utxo-expenditure.sh. • scripts/benchmarking/issue-utxo-expenditure.sh.

Keep in mind that the script requires the target file name so it can write the transaction to it input Txld (If you're using normal UTxO), as well as optionally allows specifying the source txin output index, source and target signing keys and lovelace value to send.

The target adress defaults to the 1-st richman key (configuration/delegate-keys.001.key) of the testnet, and lovelace amount is almost the entirety of its funds.

Local node queries

You can query the tip of your local node with the get-tip command. The instructions are listed below.

  1. Open tmux

  2. Run cabal build cardano-nano

  3. Run ./scripts/lite/shelly-testnet.sh example

  4. Run export CARDANO_NODE_SOCKET_PATH=/cardano-node/example/socket/node-1-socket 4. cabal exec cardano-cli -- get-tip --testnet-magic 42

You should then see the output from the stdout in the format below.

Current tip:
Block hash: 4ab21a10e1b25e39
Slot: 6
Block number: 5

Update proposals

A byron update proposal can be created with the command below

cardano-cli -- byron governance
               create-update-proposal
                 (--mainnet | --testnet-magic NATURAL)
                 --signing-key FILEPATH
                 --protocol-version-major WORD16
                 --protocol-version-minor WORD16
                 --protocol-version-alt WORD8
                 --application-name STRING
                 --software-version-num WORD32
                 --system-tag STRING
                 --installer-hash HASH
                 --filepath FILEPATH
               ..

The mandatory arguments for this to work are --mainnet | --testnet-magic, signing-key, protocol-version-major, protocol-version-minor, protocol-version-alt, application-name, software-version-num, system-tag, installer-hash and filepath.

Any remaining argument is an optional parameter you want to update in your update proposal.

You can also check your proposal's validity using the validate-cbor command. (Follow the link below) https://github.com/input-output-hk/cardano-node#validate-cbor-files

Look at the the following link for more details on update proposals.

https://hydra.iohk.io/build/5737190/download/1/ledger-spec.pdf

Update proposal submission

You can submit your proposal using the submit-upadte-proposal command. An example is listed below

cardano-cli -- byron governance
            submit-update-proposal
            --config configuration/defaults/mainnet/configuration.yaml
            (--mainnet | --testnet-magic NATURAL)
            --filepath my-update-proposal

See the following link for more details on update proposals

https://hydra.iohk.io/build/5737190/download/1/ledger-spec.pdf

Update proposal voting

You can create and submit byron update proposal votes woth the create-proposal-vote & submit-proposal-vote commands. Below are two examples of the commands.

Byron vote creation:

cabal exec cardano-cli -- byron governance create-proposal-vote
                       (--mainnet | --testnet-magic NATURAL)
                       --signing-key configuration/defaults/liveview/genesis/delegate-keys.000.key
                       --proposal-filepath ProtocolUpdateProposalFile
                       --vote-yes
                       --output-filepath UpdateProposalVoteFile

Byron vote submission:

cabal exec cardano-cli -- byron governance submit-proposal-vote
                       (--mainnet | --testnet-magic NATURAL)
                       --filepath UpdateProposalVoteFile

Development

GHCID

You can run ghcid with: ghcid -c "cabal repl exe:cardano-node --reorder-goals"

Haskell Language Server

When using Haskell Language Server with Visual Studio code, you may find HLINT annotations ate ignorehttps://github.com/haskell/haskell-language-server/issues/638.

To work around this, you can run the script ./scripts/reconfigure-hlint.sh which will generate a .hlint.yaml file with HLINT ignore rules derived from the source code.

Testing

Cardano-node is basically a container which implements several components such as networking, consensus, and storage. All of these components have individual test coverage. The node goes through integration and release testing by Devops/QA while automated CLI tests are ongoing alongside development.

Remember that developers on cardano-node can launch their own testnets (https://github.com/input-output-hk/cardano-node/blob/master/doc/getting-started/launching-a-testnet.md) or run the chairman tests (https://github.com/input-output-hk/cardano-node/blob/master/doc/getting-started/running-chairman-tests.md) locally.

Debugging

Pretty printing CBOR encoded files

It may be useful if you print the on chain. representations of blocks, delegation certificates, txs and update proposals. There are two commands that do this (for any cbor encoded file.), though only one is listed directly below this line.

To pretty print as CBOR: cabal exec cardano-cli -- pretty-print-cbor --filepath CBOREncodedFile

Validate CBOR files

You can validate Byron era blocks, delegation certificates, txs and update proposals with the validate-cbor command.

cabal exec cardano-cli -- validate-cbor --byron-block 21600 --filepath CBOREncodedByronBlockFile

Native Tokens

Native tokens is a new feature that enables the transacting of multi-assets on Cardano. Native tokens are now supported on mainnet and users can transact with ada, and an unlimited number of user-defined (custom) tokens natively.

Below is a compiled list of resources which can help you get started.

https://forum.cardano.org/c/developers/cardano-tokens/150

https://docs.cardano.org/native-tokens/learn

additionally to that, you can read more about native token and how they compare to things like ada and ERC20 with the link below. Browse native tokens made on the Cardano blockchain itself as well as see their transactions in an interactive dashboard which allows filtering and searching: nativetokens.da.iogservices.io.

(https://github.com/input-output-hk/cardano-ledger-specs/blob/master/doc/explanations/features.rst)

API Documentation

The API documentation is published at the link below.

https://input-output-hk.github.io/cardano-node/

The documentation is built with each push, but is only published from the master branch. If you want to test if the documentation is working, you can build the documentation loccaly with ./scripts/haddocs.sh and ipen haddocs/index.html in the browser.

This guide takes heavy inspiration and much of it's information from the following guide. (https://github.com/input-output-hk/cardano-node}

Last updated