Running a Local Devnet

A local devnet can be a heavyweight but reliable way to test your application on Aleo.

Setup

To run a local devnet, you'll need to install snarkOS.
Be sure to use the latest release. You'll also need tmux (instructions below) and the devnet.sh script in the snarkOS repository.

macOS

To install tmux on macOS, you can use the Homebrew package manager. If you haven't installed Homebrew yet, you can find instructions at their website.

# Once Homebrew is installed, run:
brew install tmux

Ubuntu

On Ubuntu and other Debian-based systems, you can use the apt package manager:

sudo apt update
sudo apt install tmux

Windows

There are a couple of ways to use tmux on Windows:

Using Windows Subsystem for Linux (WSL)

1. First, install Windows Subsystem for Linux.
2. Once WSL is set up and you have a Linux distribution installed (e.g., Ubuntu), open your WSL terminal and install tmux as you would on a native Linux system:

sudo apt update
sudo apt install tmux

Runing the Devnet

From the root of the SnarkOS repository, run the devnet.sh script and follow the prompts. Alternatively, you can copy the script to your project's directory.

Enter the total number of validators (default: 4): 
Enter the total number of clients (default: 2): 
Enter the network ID (mainnet = 0, testnet = 1, canary = 2) (default: 1): 
Do you want to run 'cargo install --locked --path .' to build the binary? (y/n, default: y): n
Do you want to clear the existing ledger history? (y/n, default: n):

Note: The minimum number of validators to run a local devnet is 4.

If you have already installed the SnarkOS CLI, you do not need to build the binary.

Clearing the ledger history may be useful if you wish to redploy your program without changing the name. However, this will erase all transaction history and start a new instance of the Aleo blockchain from genesis.

tmux allows you to toggle between nodes in your local devnet. Here are some useful (default) commands:

# To toggle to the next node in a local devnet
Ctrl+b n 
# To toggle to the previous node in a local devnet
Ctrl+b p 
# To scroll easily, press q to quit
Ctrl+b [ 
# To select a node in a local devnet
Ctrl+b w 
# To select a node manually in a local devnet
Ctrl+b :select-window -t {NODE_ID}
# To stop a local devnet
Ctrl+b :kill-session

Interacting with your program

Deploy

When deploying programs to a local devnet, make sure that your .env file matches the one below:

NETWORK=testnet
PRIVATE_KEY=APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH
ENDPOINT=http://localhost:3030

The PRIVATE_KEY above is same one that is generated by default when you create a new Leo project using the leo new command. It will be seeded with ample test credits in the devnet. To deploy your program, run the following command:

leo deploy

Executing Transactions

After deploying your program, you can call methods using the following command syntax:

leo execute <method_name> [input_1] [input_2] ... [input_n] --program <program_name>.aleo --broadcast

API endpoints

You can check your transactions by using the following API endpoint:

GET http://localhost:3030/testnet/transaction/{transaction_id}

The transaction API endpoint is instructive in verifying whether a transaction succeeded or failed. Since both successful and failed transaction execute a fee transaction, if only the fee transaction appears, that is a clear indication that the transaction has failed. Note that on the Testnet and on Mainnet, failed transactions still require a fee since the network is performing a computation.

A full list of API endpoints is available here

Record Scanning

You can use the SnarkOS CLI to view your Records using the following command syntax:

snarkos developer scan --endpoint http://localhost:3030 --private-key APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH --start <block_number> --network 1

Setting block_number to 0 will list all of the records from genesis, including your test credit records.

⚠️  Attention - Scanning the entire chain. This may take a while...

Scanning 3 blocks for records (100% complete)...   

[
  "{  owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private,  microcredits: 23437500000000u64.private,  _nonce: 3666670146276262240199958044811329632452609778779651964870759629195088099828group.public}",
  "{  owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private,  microcredits: 23437500000000u64.private,  _nonce: 4536868268814456227312360347031739423312689137706933033938812386306238998060group.public}",
  "{  owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private,  microcredits: 23437500000000u64.private,  _nonce: 205967862164714901379497326815256981526025583494109091059194305832749867953group.public}",
  "{  owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private,  microcredits: 23437500000000u64.private,  _nonce: 4424806931746512507605174575961455750579179367541686805196254590136284583805group.public}"
]

Setting block_number to 1 or higher will exclude the above credit records from the scan.