Cardano 911 — Wallet Command Line Interface (Part One).

Published in

Geek Culture

8 min readOct 8, 2021

The target audience of the Cardano Wallet CLI is generally tech-savvy users who run a wallet’s Application Programming Interface (API) outside of Daedalus and work with the advanced API features directly. This audience includes app developers, stake pool operators and exchanges’ staff. Many CLI commands must be run “online” and “in-sync” only, but some of them don’t require an active server and synced DB, and can be run “offline” and/or “out-of-sync”. This story is dedicated to those ADA holders who would like to have a more flexible and powerful Cardano wallet, as opposed to Daedalus and Yoroi.

Installation

Before proceeding we have to install two libraries. I’m a Mac user, so I’ll show you how to install it on macOS Monterey with ZSH default shell. Before the installation, please get acquainted with mac’s Gatekeeper.

TIP: Cardano CLI supports Linux, Mac and Windows operating systems.

If you do not want to compile binaries yourself you can merely download cardano-node-1.30.1-macos and cardano-wallet-2021–09–29-macos.

Unzip both libraries, and rename the first folder as cardano-node, and the second one as cardano-wallet. Create cardano directory and put it inside /Users/<userName>/ (Home directory):

/Users/swift/cardano/

Put cardano-wallet and cardano-node folders inside parent cardano folder. Then in Home directory create a hidden .zshrc Shell Resource file:

touch ~/.zshrc

Open it in TextEdit app with the following command:

open ~/.zshrc

Setup a path for Wallet CLI tools in .zshrc file and save it:

export PATH="/Users/swift/cardano/cardano-wallet:$PATH"
export PATH="/Users/swift/cardano/cardano-node:$PATH"tilde=~
export CARDANO_NODE_SOCKET_PATH="${tilde}/cardano/db/node.socket"echo "Cardano CLI tools are installed..."

TIP: Cardano node.socket is automatically created when starting a cardano-node and it exists so long as the node remains running.

Then in Terminal make them executable:

chmod +x ~/cardano/cardano-wallet
chmod +x ~/cardano/cardano-node

The final touch to the whole picture will be a downloading of JSON files with network configurations.

Warning: If you are new to Cardano, please consider experimenting on the testnet first. Do not overload the mainnet unnecessarily.

Go to https://hydra.iohk.io and copy 5 main config files:

mainnet-config.json
mainnet-byron-genesis.json
mainnet-shelley-genesis.json
mainnet-alonzo-genesis.json
mainnet-topology.json

Create config folder inside cardano directory and put there these five JSONs. Log out your mac account, and then log in again. After that create three more empty folders: /db, /keys, and /wallets.

Now we are ready to jive.

Running node and server

In part One of my story I will explore only offline commands, so there’s no need for complete syncing with ledger. Nevertheless, there are two important commands I must execute before I start working with the wallet.

Open a FIRST session in Terminal app and execute the command that helps downloading a Cardano ledger into ~/cardano/db/ folder:

arch -x86_64 cardano-node run \
    --topology ~/cardano/config/mainnet-topology.json \
    --database-path ~/cardano/db/ \
    --socket-path ~/cardano/db/node.socket \
    --host-addr 127.0.0.1 \
    --port 1225 \
    --config ~/cardano/config/mainnet-config.json

If there are no errors, you’ll see it running:

TIP: Remember, downloading a complete ledger’s database on your comp takes a full day on average.

Open a SECOND session in Terminal and execute a next command that helps listening to a server:

arch -x86_64 cardano-wallet serve \
    --port 8090 \
    --mainnet \
    --database ~/cardano/wallets/db \
    --node-socket $CARDANO_NODE_SOCKET_PATH

If everything’s OK, in a second terminal’s window you’ll see this:

Checking a version

Let’s check all the versions out. Run a THIRD session in Terminal and firstly check a cardano-wallet utility version:

cardano-wallet version

If everything’s fine, you’ll see a result like this:

In addition to that we should find out what cardano-node and cardano-address versions are:

cardano-node version

and, at last, for a complete satisfaction of curiosity:

cardano-address version

Querying blockchain and network parameters

Running cardano-cli query command, it’s easy enough to find out how the synchronization process is going on and how many blocks have already been loaded into your local database.

cardano-cli query tip --mainnet

Another useful layer of information that you can get, is available to you when you employ cardano-wallet commands.

cardano-wallet network information

cardano-wallet network parameters

Of course, we can query any single parameter, for instance, max size of Tx:

cardano-cli query protocol-parameters --mainnet | jq .maxTxSize

At the moment maxTxSize = 16 KB.

Offline and out-of-sync commands

Truly, IOHK engineers have been producing the developer-friendly tools. Despite the fact that we work with a command-line, nothing could be simpler than creating/managing a wallet using the cardano-wallet API.

The generation of a private key or a seed phrase should undoubtedly be done offline — away from strangers’ eyes.

For generating a new wallet, the only thing we have to know is the right length of a BIP39 primary recovery phrase — in Cardano CLI it can be 15-, 18-, 21-, or 24-word.

TIP: Read about the recovery phrase architecture here.

I have chosen 21-word, that is 2048²¹ possible combinations for hackers.

cardano-wallet recovery-phrase generate --size 21 > primary

All my 21 words were written into a file called primary (you can find it in cardano folder). I used a redirect operator “>” to redirect command output to a file.

This is a seed (a.k.a. recovery or mnemonic) phrase that is able to spawn a private key after applying a special math. Nobody must get access to seed/privkey except you — always keep it a secret.

Additional protection for your funds can be provided with a BIP39 second-factor 9- or 12-word optional seed-phrase. I choose 9, let’s generate it too.

cardano-wallet recovery-phrase generate --size 9 > second-factor

Online commands

Now I’m capable of creating a wallet named AndyJazz based on my 2 seeds.

cardano-wallet wallet create from-recovery-phrase AndyJazz
    --port 8090 /
    --address-pool-gap 20

Execute a command, copy-paste the 21-word phrase, then feed the optional 9-word phrase, and a 10-character password, at last. I entered the worst password (passphrase) ever — 0123456789 — a holiday for hackers.

Your password can be 10 to 255 characters long.

Woo-hoo! Feel like Dr. Evil. :))

The only thing I would like to see now is an information about my brand-new wallet. It’s easy as pie.

cardano-wallet wallet list

TIP: This command requires you to be on the Cardano network.

As you can imagine every wallet in Cardano network has not only its name but also its own ID in hex.

0aa0cb917989f070c1ce97ba0f78004e4e93231a

Having this ID you can get, update and delete your wallet. When you feed this identifier to the address command, you will see all used and/or unused addresses encoded with the Bech32 scheme:

cardano-wallet address list --state unused 
                            0aa0cb917989f070c1ce97ba0f78004e4e93231a

As you can see, the first unused address with index=0 and addr1 prefix is:

addr1q8ldyj7v9dx8vxd355lv6cu8lwvwd8frtduf7q3ks0l7tl586rsljqxmhzes8qxcu6sh79dpqe8pqmcpqm99c43extrs2fw3m2

and the last one with index=19 is:

addr1qyvx0lf6fdech3xwknkq47zaksddyu0ca90e20nry9p22wy86rsljqxmhzes8qxcu6sh79dpqe8pqmcpqm99c43extrsx4t3y0

TIP: If the synchronization process is over, you can stop running a node. For that press <CTRL><C> shortcut for the FIRST Terminal session.

IMPORTANT: Before making transactions in the mainnet, practice in testnet using tADA. Otherwise, with an incorrectly executed transaction, you risk losing your funds.

Using Daedalus socket for cardano-wallet

If you have previously installed the Daedalus wallet, then of course you can use the wallet’s node socket for command-line tools. As I wrote earlier, the socket only exists when the node is running. Daedalus is a good example of what a passive node is. Well, now it’s the moment to launch and sync Daedalus — it will take some time.

Since Daedalus is fully in sync with the network, let’s change the path in ~/.zshrc file for our global variable CARDANO_NODE_SOCKET_PATH.

export CARDANO_NODE_SOCKET_PATH=$(ps ax | grep -v grep | grep cardano-wallet | grep mainnet | sed -E 's/(.*)node-socket //')

Global Regular Expression Print, or grep, is a small family of commands that search input files for a search string, and print the lines that match it. Although this may not seem like a terribly useful command at first, grep is considered one of the most useful commands in any Unix system.

To check that everything is in order, type in the command line:

echo $CARDANO_NODE_SOCKET_PATH

Terminal will print the path to the location of the socket file. If the wallet was installed in the default directory, then the path will be like this:

/Users/<userName>/Library/Application Support/Daedalus Mainnet/cardano-node.socket

Now if we create a query — whether we are synced with ledger or not,

cardano-cli query tip — mainnet

we’ll receive the expected response:

What’s next

In the next story, we are going to find out what a derivation_path is and how to generate private keys and public keys. Read more about it in the story:

Cardano 911 — Wallet Command Line Interface (Part Two).

That’s all for now.

If this post is useful for you, please press the Clap button and hold it.

Happy staking!