Skip to main content

Set Up Local Alphabill Devnet

The local devnet provides safe playground to run a local instance of the whole Alphabill platform without the need to interact with the public Alphabill testnet. Because devnet is running locally, you can reset or re-configure the network at any time.

This tutorial shows you how to set up a personal Alphabill devnet on your machine, claim local devnet funds, and add funds to the fee credit balance in your wallet.


Before you begin, you must have Alphabill CLI wallet set up in your system.

Alphabill CLI Usage

To access the top-level help menu to see what Alphabill CLI commands and options are available, go to the build directory and enter the following command:

./alphabill -h
The alphabill CLI includes commands for all different parts of the system: shard, core, wallet etc.

alphabill [command]

Available Commands:
completion Generate the autocompletion script for the specified shell
evm Starts an evm partition node
evm-genesis Generates a genesis file for the evm partition
help Help about any command
identifier Returns the ID of the node
money Starts a money node
money-backend Starts money backend service
money-genesis Generates a genesis file for the Alphabill Money partition
root Starts a root chain node
root-genesis Generates root chain genesis files
tokens Starts a User-Defined Token partition's node
tokens-backend Starts tokens backend service
tokens-genesis Generates a genesis file for the User-Defined Token partition
wallet cli for managing alphabill wallet

--config string config file URL (default is $AB_HOME/config.props)
-h, --help help for alphabill
--home string set the AB_HOME for this invocation (default is /home/user/.alphabill)
--logger-config string logger config file URL. Considered absolute if starts with '/'. Otherwise relative from $AB_HOME. (default "logger-config.yaml")
--metrics Enables metrics collection.

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

The Alphabill CLI functions in two main modes:

Server modes enable to launch different parts of the Alphabill network using the following commands:

  • As a local Money Partition using the alphabill money command.
  • As a local User Token Partition using the alphabill tokens command.
  • As a local EVM Partition using the alphabill evm command.
  • As a local root chain using the alphabill root command.

Client modes enable to interact with the network or set up configuration details:

  • As a wallet using the alphabill wallet command. This subcommand can also be used to interact with the User Token Partition and EVM Partition.
  • Other helper functions, used for generating genesis configurations, etc.

Run Local Devnet

  1. The full network setup includes a cluster of Alphabill Money Partition validators, a separate cluster of validators for the User Token Partition, and a root chain.

    Go to the alphabill directory and run the following script to generate root chain, partition node keys, and genesis files:


    Node configuration files are located in testab directory.

  2. To start up the local devnet, you need to launch several nodes of different types. Run the following script, which configures and launches the necessary processes:

    ./ -r -p money -p tokens -p evm -b money -b tokens

    The script starts root and all partition nodes, and money and tokens backend services that will be used by the wallet.

    You can check the backend Swagger documentation from the following addresses:

    Once the local devnet is running, you can issue the pidof alphabill command in your shell, and you should see 12 process ID numbers returned:

    pidof alphabill
    Example response:

    3614 3590 3570 3569 3568 3489 3488 3487 3406 3405 3404 3345

    These represent money and token backend services, 3 money node validators, 3 user token partition nodes, 3 evm nodes, and a single root node process.


    If you are on macOS, the utility pidof does not come installed with your operating system, but you can install it with Homebrew.

  3. To stop the local devnet, run the following script to safely shut down root chain and all partition nodes:

    ./ -a

Claim Local Devnet Funds

When you start the local devnet, the initial value of the entire network is contained in a single bill worth of 10 billion ALPHA.

  1. To claim local devnet funds to your public key, a specific script is available in the alphabill directory:

    go run scripts/money/spend_initial_bill.go \
    --alphabill-uri localhost:26766 \
    --bill-id 1 \
    --bill-value 1000000000000000000 \
    --timeout 10

    Remember to replace INSERT_YOUR_WALLET_DEFAULT_PUBKEY with your actual wallet public key.

    If the transaction succeeds, the following messages are returned:

    2023/08/29 13:12:23 sent transferFC transaction
    2023/08/29 13:12:24 confirmed transferFC transaction
    2023/08/29 13:12:24 sent addFC transaction
    2023/08/29 13:12:25 confirmed addFC transaction
    2023/08/29 13:12:25 successfully sent initial bill transfer transaction
  2. Go to the build directory and check your wallet balance using the wallet get-balance command:

    ./alphabill wallet get-balance
    Example response:

    #1 9'999'999'999.999'999'97
    #2 0.000'000'00
    Total 9'999'999'999.999'999'97

    You should see that after the transaction your wallet's balance is actually smaller than the original bill. This is because with every transaction, a small fee will be charged to cover the cost of recording the transaction onto the blockchain.

Add Fee Credits

Before you can make any transaction from your wallet, you need to have enough funds on your fee credit balance to cover the associated transaction costs. Each wallet account (public key) has its own fee credit balance for every partition.

Transaction fees are paid in Alphabill native currency ALPHA, and the fee per transaction is 0.000'000'01 ALPHA. Actions that consist of two transactions (2 x 0.000'000'01 ALPHA): adding fee credits, reclaiming fee credits, and consolidating bills.

The CLI wallet has a separate command for managing Alphabill wallet fees.

  1. Add 1 ALPHA to your fee credit balance to cover transaction costs from your default account:

    • Money Partition

      ./alphabill wallet fees add
    • User Token Partition

      ./alphabill wallet fees add \
      --partition tokens
    • EVM Partition

      ./alphabill wallet fees add \
      --partition evm

    If you want to add more funds to your fee credit balance than the default 1 ALPHA, use the --amount flag at the end of the command and specify the amount.

  2. Transfer 10 ALPHA to your second account:

    ./alphabill wallet send \
    --address INSERT_WALLET_PUBKEY2 \
    --amount 10
  3. Check your wallet balance:

    ./alphabill wallet get-balance
    Example response:

    #1 9'999'999'987.999'999'97
    #2 8.000'000'00
    Total 9'999'999'995.999'999'97

  4. Add 1 ALPHA to the fee credit balance to cover transaction costs from your second account:

    • Money Partition

      ./alphabill wallet fees add \
      --key 2
    • User Token Partition

      ./alphabill wallet fees add \
      --partition tokens \
      --key 2
    • EVM Partition

      ./alphabill wallet fees add \
      --partition evm \
      --key 2
  5. Check your wallet fee credit balance:

    • Money Partition

      ./alphabill wallet fees list
      Example response:

      Partition: money
      Account #1 0.999'999'97
      Account #2 0.999'999'98

    • User Token Partition

      ./alphabill wallet fees list \
      --partition tokens
      Example response:

      Partition: tokens
      Account #1 0.999'999'98
      Account #2 0.999'999'98

    • EVM Partition

      ./alphabill wallet fees list \
      --partition evm
      Example response:

      Partition: evm
      Account #1 0.999'999'98
      Account #2 0.999'999'98

Logging Configuration

You can use a YAML config file to configure Alphabill logging. Use the following commands to set configuration and logging defaults for your local devnet:

cp ../cli/alphabill/config/config.props.example ~/.alphabill/config.props
cp ../cli/alphabill/config/logger-config.yaml ~/.alphabill/

These commands will work only if you have already set up a wallet, or the ~/.alphabill directory is present.

Next Steps

Now that you have a private devnet running, initial value of the entire network deposited in your wallet, and enough fee credit, you have a safe playground to start developing and testing Alphabill locally.