Run a Local Network
libra-swarm
is used to start a local network of validator nodes and a local blockchain on your computer. Running a local network makes it easier to test and debug your code changes. To view the logs generated by your local nodes, use the instructions in How Do I Access The Logs? You can use the CLI command dev
to compile, publish, and execute Move Intermediate Representation (IR) programs on your local cluster of nodes. Refer to Run Move Programs Locally for further details.
libra-swarm
package is located in the root directory of the libra
repository.
Usage
libra-swarm [FLAGS] [OPTIONS]
FLAGS:
-l | --enable_logging
— Enables logging.-h | --help
— Prints help information.-s | --start_client
— Starts Libra CLI client.-v | --version
— Prints version information.
OPTIONS:
-n | --num_nodes <num_nodes>
— Number of local nodes to start (1 is the default).-c | --config_dir <config_dir>
— The directory used bylibra-swarm
to save the config files, logs, libradb, etc. for the nodes. The user can inspect the information saved in the<config_dir>
even afterlibra-swarm
exits. If this directory is unspecified, a temporary directory is used to save this information. The files in<config_dir>
are automatically deleted whenlibra-swarm
exits.
Prerequisites
To install all the required dependencies, run the build script as described in Clone and Build Libra Core.
Ensure your command line is in the root directory of the cloned Libra GitHub repo.
Run a local network
Note: The local network of validator nodes will not be connected to the testnet; currently, it is not possible to connect the local validator network to the testnet.
To run a network with one or more validator nodes and to create a local blockchain, run libra-swarm
with the -n
option, as shown below. If the -n
option is not specified, libra-swarm
will spawn a network with one node.
The following example starts a network with 4 nodes:
cargo run -p libra-swarm -- -s -n 4
The cargo run -p libra-swarm -- -s
command does the following:
- Spawns a network of validator nodes locally on your computer.
- Performs configuration management of the validator network.
- Starts an instance of the Libra CLI client; the client is connected to the local network.
The configuration management of the validator network generates:
- A genesis transaction.
- Mint key — Key for the account that's allowed to perform the mint operation.
- Bootstrap configuration of each validator in the local network — Ports to listen to, system limits, etc.
The cargo run
command may take some time to run. If you have started libra-swarm
using the -s
option, upon successful execution of the command, an instance of the Libra CLI client will be running on your system. You will see the CLI client menu and the libra%
prompt. This instance of the client is connected to the local network of nodes you just spawned. You can now enter CLI commands to interact with the local network.
libra-swarm
Run Libra CLI client in a Separate Process From In the previous section, we ran libra-swarm
using the -s
option. This automatically starts the Libra CLI client and libra-swarm
in the same process. If you would like to run the CLI client in a separate process from libra-swarm
, use the following steps:
libra-swarm
Step 1: Run Run libra-swarm
without the -s
option as shown below:
cargo run -p libra-swarm
You will see the following information in the output.
To run the Libra CLI client in a separate process and connect to the local cluster of nodes you just spawned, use this command:
cargo run --bin cli -- -a localhost -p 57149 -s "/var/folders/xd/sfg4x6713w350lq73kgfc7qxnq5swl/T/.tmpmSSKk9/trusted_peers.config.toml" -m "/var/folders/xd/sfg4x6713w350lq73kgfc7qxnq5swl/T/keypair.ATvJWTliQf0a/temp_faucet_keys"
Step 2: Start an Instance of the CLI Client
To start an instance of the CLI client and connect to the local network you spawned in step 1:
- In a new terminal window, change to the directory where you cloned the Libra GitHub repo, normally named
libra
. - Run the entire command you see in your output from step 1, as shown below:
cargo run --bin cli -- -a localhost -p 57149 -s "/var/folders/xd/sfg4x6713w350lq73kgfc7qxnq5swl/T/.tmpmSSKk9/trusted_peers.config.toml" -m "/var/folders/xd/sfg4x6713w350lq73kgfc7qxnq5swl/T/keypair.ATvJWTliQf0a/temp_faucet_keys"
This will spawn an instance of the CLI client in a separate process, and you will see the libra%
prompt.
A sample output from running this command is shown below:
Finished dev [unoptimized + debuginfo] target(s) in 0.72s
Running `target/debug/client -a localhost -p 57149 -s "/var/folders/xd/sfg4x6713w350lq73kgfc7qxnq5swl/T/.tmpmSSKk9/trusted_peers.config.toml" -m "/var/folders/xd/sfg4x6713w350lq73kgfc7qxnq5swl/T/keypair.ATvJWTliQf0a/temp_faucet_keys"
Connected to validator at: localhost:57149
usage: <command> <args>
Use the following commands:
account | a
Account operations
query | q
Query operations
transfer | transferb | t | tb
<sender_account_address>|<sender_account_ref_id> <receiver_account_address>|<receiver_account_ref_id> <number_of_coins> [gas_unit_price_in_micro_libras (default=0)] [max_gas_amount_in_micro_libras (default 100000)] Suffix 'b' is for blocking.
Transfer coins (in libra) from account to another.
dev
Local move development
help | h
Prints this help
quit | q!
Exit this client
Please, input commands:
libra%
You can now enter CLI commands to interact with the local network. Refer to the Libra CLI Guide for command usage information. Refer to My First Transaction for guidance on creating accounts and running transactions on your local blockchain.
Troubleshooting FAQ
To see usage options for libra-swarm
, run:
cargo run -p libra-swarm -- -h
How Do I Enable Logging?
By default, logging is disabled in libra-swarm
. If you would like to enable logging, run libra-swarm
with the -l
option as shown below:
cargo run -p libra-swarm -- -s -l
How Do I Access the Logs?
When you run the cargo run -p libra-swarm -- -s -l
command you will see the following in your output:
Base directory containing logs and configs: Temporary(TempDir { path:"/var/folders/tq/8gxrrmhx16376zxd5r4h9hhn_x1zq3/T/.tmpzeOPC0"})
In a different terminal window, you can use the tail
command to access the logs:
tail -f <generated_path>/logs/*
The <generated_path>
in the above example is:
/var/folders/tq/8gxrrmhx16376zxd5r4h9hhn_x1zq3/T/.tmpzeOPC0
How Do I Persist the Logs?
The local validator nodes use a temporary directory to generate the logs and the database. This temporary directory is deleted when the libra-swarm
process exits. To persist the logs after the termination of libra-swarm
, run libra-swarm
using the --c
option as specified in libra-swarm usage.
Reference
- CLI Guide — Lists the commands of the Libra CLI client.
- My First Transaction — Provides step-by-step guidance on creating new accounts on the Libra Blockchain and running transactions.