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​

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.

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-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

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)
      --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:

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

    tip

    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:

    ./stop.sh -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 \
    --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:

    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
    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:

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