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.

Prerequisites

You must have Alphabill CLI wallet set up in your system.

Build Alphabill CLI Binary

  1. Clone the remote alphabill repository:

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

    This tutorial is based on the 0.4.0 branch of the code:

    cd alphabill
    git checkout -t origin/0.4.0

    To work with the CLI wallet, 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 and checked out the desired branch, run the make build command in the new alphabill directory:

    make build

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

Alphabill CLI Usage

To access the top-level help menu to see what Alphabill CLI commands and options are available, go to the alphabill/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.

Usage:
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-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-genesis Generates a genesis file for the User-Defined Token partition

Flags:
--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)
--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 "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 set up configuration details, for example, helper functions that can be used for generating genesis configurations.

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 and EVM partitions, and a root chain.

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

    ./setup-testab.sh

    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:

    ./start.sh -r -p money -p tokens -p evm

    The script starts root and all partition nodes.

    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 3 root nodes, 3 money nodes, 3 tokens nodes, and 3 evm nodes.

    tip

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

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

    ./stop.sh -a

Start the Indexing Backends

  1. Go to the alphabill-wallet directory and run the following script to start both money and tokens indexing backends:

    ./start.sh -b money -b tokens
    info

    EVM partition does not have an indexing backend.

    To shut down backend services, run the following script:

    ./stop.sh -a
  2. For the next step, you need your wallet's public key where the local devnet funds will be transferred. You can list your public keys with the following command:

    cd build
    ./abwallet wallet get-pubkeys
    Example response:

    #1 0x029871a8fbc1844d41ddd7cf0ceb292dbe33b8c29694c9675d13f8926f5deeb00b
    #2 0x02e320ab869c7e7267b88ccb0b89c8265a29c2e58459e519d59f978b6d7193f978

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 \
    --pubkey INSERT_YOUR_WALLET_DEFAULT_PUBKEY \
    --alphabill-uri localhost:26766 \
    --bill-id 1 \
    --bill-value 1000000000000000000 \
    --timeout 10
    important

    Remember to replace INSERT_YOUR_WALLET_DEFAULT_PUBKEY with your actual wallet public key.

    If the transaction succeeds, the following messages are returned:

    2024/02/28 13:19:28 sent transferFC transaction
    2024/02/28 13:19:30 confirmed transferFC transaction
    2024/02/28 13:19:30 sent addFC transaction
    2024/02/28 13:19:32 confirmed addFC transaction
    2024/02/28 13:19:32 successfully sent initial bill transfer transaction
  2. Go to the alphabill-wallet/build directory and check your wallet balance using the wallet get-balance command:

    ./abwallet 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. Go to the alphabill-wallet/build director and add 1 ALPHA to your fee credit balance to cover transaction costs from your default account:

    • Money Partition

      ./abwallet wallet fees add
    • User Token Partition

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

      ./abwallet wallet fees add \
      --partition evm
    tip

    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:

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

    ./abwallet wallet get-balance
    Example response:

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

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

    • Money Partition

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

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

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

    • Money Partition

      ./abwallet wallet fees list
      Example response:

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

    • User Token Partition

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

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

    • EVM Partition

      ./abwallet 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/
important

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.