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.
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
• --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.
• 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.
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.
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
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.
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.
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.
Open tmux
Run cabal build cardano-nano
Run ./scripts/lite/shelly-testnet.sh example
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.
Update proposals
A byron update proposal can be created with the command below
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
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:
Byron vote submission:
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