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 Alphabill CLI Wallet Binary​

  1. Clone the remote alphabill-wallet repository:

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

    You need to make sure the version of the wallet is compatible with the version of the service you will connect to.

    To work with the public testnet, use the 0.4.0 branch of the code:

    cd alphabill-wallet
    git checkout -t origin/0.4.0

    To work with local devnet, you need to check out matching branches from the main alphabill repository and the alphabill-wallet reposository. By default, git clone checks out the main development branch from each repository.

  2. Once you have cloned the repository, go to the new alphabill-wallet directory and run the make build command:

    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 has multiple commands for different operations. At any time, add the -h flag to the end of any command to see the most recent in-program documentation. All command-line options have a help menu available to assist in the use of the command.

cd build
./abwallet -h
The alphabill wallet CLI

Usage:
  abwallet [command]

Available Commands:
  completion     Generate the autocompletion script for the specified shell
  help           Help about any command
  money-backend  Starts money backend service
  tokens-backend Starts tokens backend service
  wallet         cli for managing alphabill wallet

Flags:
      --config string          config file URL (default is $AB_HOME/config.props)
  -h, --help                   help for abwallet
      --home string            set the AB_HOME for this invocation (default is /home/user/.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 [command] --help" for more information about a command.

Wallet Setup​

Create a New Wallet​

To create a new wallet, use the following command:

./abwallet wallet create

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.

Create a Second Wallet​

For testing purposes, it's useful to create a second wallet in addition to your default wallet by providing an alternative wallet location, using the --wallet-location flag:

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

The command returns a 12-word recovery phrase for your second wallet. This wallet will be created at ~/.alphabill/wallet2.

Recover an Existing Wallet​

In case you have forgotten the password for your wallet or want to import an existing Alphabill wallet to a new device, you must have access to your wallet's 12-word secret recovery phrase.

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

./abwallet wallet create \
--seed "INSERT_YOUR_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 New Public Key​

The public key is the address you can share with others to receive transactions. You can add as many public keys to your wallet as needed. To add a new public key to your wallet, use the wallet add-key command:

./abwallet wallet add-key
Example response:

Added key #2 0x03ddeb805aba6bb56b5f6351d51f44d11a374070032f95be5841e9b6420099a00a

Multiple public keys can be useful if you want to transfer tokens between your own accounts for testing purposes.

List Wallet Public Keys​

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

./abwallet wallet get-pubkeys
Example response:

#1 0x029871a8fbc1844d41ddd7cf0ceb292dbe33b8c29694c9675d13f8926f5deeb00b

To list public keys stored in your other wallet, use the --wallet-location flag followed by the wallet location, for example:

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

Wallet Logging Configuration​

You can configure wallet logging only through CLI parameters, for example:

./abwallet wallet get-pubkeys \
--log-file ~/.alphabill/wallet.log \
--log-level=DEBUG

Default log output is stderr and default log level is INFO. Possible log level values are: ERROR, WARNING, NOTICE, INFO, DEBUG.

Next Steps​

After you have set up Alphabill CLI wallet, you are ready to start testing its functionalities on local devnet or public testnet.