Skip to main content

Set Up Alphabill CLI Wallet

This tutorial covers necessary steps to set up Alphabill command-line interface (CLI) wallet. The CLI wallet can do everything the browser wallet can, and then some more:

  • Manage more than one wallet (could be useful to test out various interactions and workflows from the comfort of your own workstation and primary user account).
  • Define your own custom token types, both fungible and non-fungible, and mint tokens of those custom types.

You can use the CLI wallet to access either the local Alphabill instance or the public Alphabill testnet.

Prerequisites​

To build Alphabill CLI wallet binary, you must have following build dependencies installed on your system:

  • Go (version 1.21 and later). For installation instructions, see Go's installation guide.
  • C compiler, recent versions of GCC are recommended. In Debian and Ubuntu repositories, GCC is part of the build-essential package. If you are on macOS, you can install GCC with Homebrew.

Build CLI Wallet Binary​

  1. Clone the remote alphabill-wallet repository:

    git clone https://github.com/alphabill-org/alphabill-wallet.git

  2. By default, git clone checks out the main development branch. To work with the code at version 0.4.0, create a new branch from the v0.4.0 tag and switch to that branch:

    cd alphabill-wallet
    git checkout -b 0.4.0 tags/v0.4.0
    Important

    To work with the local devnet, make sure both the alphabill-wallet and alphabill repositories use the same version of the code.

  3. Once you have cloned the repository and checked out the desired branch, run the make build command in the new alphabill-wallet directory:

    make build

    This command will download all necessary build dependencies, run the tests, and build the abwallet binary. The output directory for the binary is alphabill-wallet/build.

CLI Wallet Usage​

The CLI wallet includes multiple commands for various operations. Each command-line option has a help file available to assist you. To view the most recent in-program documentation for any command, simply add the -h flag at the end of the command.

cd build
./abwallet wallet -h
cli for managing alphabill wallet

Usage:
  abwallet wallet [command]

Available Commands:
  add-key      adds the next key in the series to the wallet
  bills        cli for managing alphabill wallet bills and proofs
  collect-dust consolidates bills
  create
  evm          interact with alphabill EVM partition
  fees         cli for managing alphabill wallet fees
  get-balance
  get-pubkeys
  send
  token        create and manage fungible and non-fungible tokens

Flags:
  -h, --help                     help for wallet
  -p, --password                 password (interactive from prompt)
      --pn string                password (non-interactive from args)
  -l, --wallet-location string   wallet home directory (default $AB_HOME/wallet)

Global Flags:
      --config string          config file URL (default is $AB_HOME/config.props)
      --home string            set the AB_HOME for this invocation (default is /home/toomas/.alphabill)
      --log-file string        log file path or one of the special values: stdout, stderr, discard
      --log-format string      log format, one of: text, json, console, ecs
      --log-level string       logging level, one of: DEBUG, INFO, WARN, ERROR
      --logger-config string   logger config file URL. Considered absolute if starts with '/'. Otherwise relative from $AB_HOME. (default "logger-config.yaml")
      --metrics string         metrics exporter, disabled when not set. One of: stdout, prometheus
      --tracing string         traces exporter, disabled when not set. One of: stdout, otlptracehttp, otlptracegrpc, zipkin

Use "abwallet wallet [command] --help" for more information about a command.

Wallet Setup​

Create a New Wallet​

  1. To create a new wallet, use the following command:

    ./abwallet wallet create
    Example response:
    The following mnemonic key can be used to recover your wallet. Please write it down now, and keep it in a safe, offline place.
    mnemonic key: ....

    This command returns mnemonic key you can use to recover your wallet. The mnemonic key, also known as a recovery phrase or a seed phrase, is a unique 12-word phrase that is generated when you create a new wallet. This phrase is the key to your wallet and controls access to all your funds.

    warning

    Write down the phrase in the exact order in which you receive it, and keep it in a safe, offline place. You will only see this phrase once during the wallet creation. Never give your wallet's seed phrase to anyone, as it can be used to steal your wallet funds.

    The wallet create command creates a database for keys that will be used by the wallet, located at ~/.alphabill/wallet/accounts.db.

  2. For testing purposes, it's useful to create a second wallet in addition to your default wallet. You can do this by specifying an alternative wallet location using the --wallet-location flag.

    ./abwallet wallet create \
    --wallet-location ~/.alphabill/wallet2

    This wallet will be created at ~/.alphabill/wallet2.

Recover an Existing Wallet​

In case you have forgotten the password for your wallet, the secret recovery phrase allows you to restore access. Without this phrase, it is impossible to recover your wallet and its contents. Additionally, when you want to import an existing wallet to a new device, you can use the secret recovery phrase to recreate the wallet on the new device.

Use the wallet create command followed by the --seed flag and wallet's 12-word recovery phrase:

./abwallet wallet create \
--seed "WALLET_MNEMONIC_KEY"
tip

If the account.db file already exists, use the --wallet-location flag and specify new location for the wallet you want to recover.

info

Alphabill wallet is a hierarchical deterministic (HD) wallet, so all keys are recoverable using the master seed phrase. If you lose your wallet data, you can recover all your public and private keys–you just need to re-add all the other keys after re-generating the first key.

Add a New Public Key​

A single wallet can contain multiple public keys, each associated with different accounts. This allows you to segregate and manage different types of assets or test transactions between your own accounts. You can add as many public keys to your wallet as needed.

To add a second public key to your wallet, use the wallet add-key command:

./abwallet wallet add-key
Example response:
Added key #2 0x03ddeb805aba6bb56b5f6351d51f44d11a374070032f95be5841e9b6420099a00a

List Wallet Public Keys​

  1. To list all public keys stored in your default wallet, use the wallet get-pubkeys command:

    ./abwallet wallet get-pubkeys
    Example response:
    #1 0x029871a8fbc1844d41ddd7cf0ceb292dbe33b8c29694c9675d13f8926f5deeb00b
    #2 0x03ddeb805aba6bb56b5f6351d51f44d11a374070032f95be5841e9b6420099a00a

  2. To list public keys stored in your second wallet, use the --wallet-location flag followed by the path to the wallet location, for example:

    ./abwallet wallet get-pubkeys \
    --wallet-location ~/.alphabill/wallet2

Logging Configuration​

The CLI wallet logging configuration can be managed through CLI parameters, for example:

./abwallet wallet fees add \
--log-file ~/.alphabill/wallet.log \
--log-format json \
--log-level DEBUG

The default log file output is stderr, the default log format is esc, and the default log level is INFO. For more information on flags and their options available for customizing logging behavior, run ./abwallet wallet -h.