Most developers should use the CLI to run a local development network. It is simpler and more fully featured than just a single node localnet + faucet. If you want a local stack that works just like a production network (Node API + Transaction Stream + Indexer API + Faucet), this is the option for you.
Run a Local Development Network
If you're developing the core endless node software itself or have complex testing needs, consider these guides.
Run a Localnet with Validator
Run a Local Multi-node Network
You can run a localnet of the Endless blockchain. This localnet will not be connected to the Endless devnet. It will run on your local machine, independent of other Endless networks. You can use this localnet for testing and development purposes.
The rest of this document describes:
How to start your localnet with a single validator node, and
How to start a Faucet service and attach it to your localnet.
Follow steps in
With your development environment ready, now you can start your testnet network. Before you proceed, make a note of the following:
To start your testnet locally, run the following command:
See below for an example of the partial output. Make a note of the Test dir from the output.
NOTE: The above command starts a localnet with a single validator node. The command runs endless-node from a genesis-only ledger state. If you want to reuse the ledger state produced by a previous run of endless-node, then use:
After starting your localnet, you will see the following:
Use the Endless CLI tool to interact with your localnet. The above output contains information you will use for starting the Endless CLI tool:
Endless root key path: The root key (also known as the mint or faucet key) controls the account that can mint tokens. Available in the docker compose folder under Endless_root_key.
Waypoint: A verifiable checkpoint of the blockchain (available in the docker compose folder under waypoint.txt)
REST API endpoint: The endpoint for the REST service, e.g., http://127.0.0.1:8080
At this point, you will have a special root account at 0x1 that can perform the mint operation. Follow up with:
Your first transaction to learn how to submit transactions.
Your first Move module to learn how to create Move modules.
Interacting with the Endless Blockchain to learn how to mint coins.
Local networks can be helpful when testing your code. They are not connected to any production Endless networks like mainnet, but they are useful for three main reasons:
No rate limits: You can interact with hosted services like the Node API, Indexer API, and faucet with no rate-limits to speed up testing.
ChainId: The chain ID uniquely distinguishes this network from other blockchain networks.
Reproducibility: You can set up specific on-chain scenarios and restart the network from scratch at any point to return to a clean slate.
High availability: The Endless devnet and testnet networks are periodically upgraded, during which time they can be unavailable. Local development networks are also always available even if you have no internet access.
Ensure you have the Endless CLI installed.
Run the following command in a new terminal to start the private network:
You should expect to see an output similar to this:
Wait for the final line Setup is complete, you can now use the localnet!
As you can see from the above example output, once the local network is running, you have access to the following services:
Node API: This is a REST API that runs directly on the node. It enables core write functionality such as transaction submission and a limited set of read functionality, such as reading account resources or Move module information.
Transaction Stream Service: This is a gRPC stream of transactions used by the Indexer API. This is only relevant to you if you are developing a custom processor.
If you do not want to run Transaction Stream Service, there is a --no-txn-stream flag to disable it.
If you are writing a script and would like to wait for the local network to come up with all services, you can make a GET request to http://127.0.0.1:8070. At first this will return http code 503. When it returns 200 it means all the services are ready.
For more information on different flags you can pass when starting your local network, or configuration settings such as changing which port certain services run on, run the help command:
This means one of the ports needed by the local network is already in use by another process.
To fix this on Unix systems, you can:
Identify the name and PID of the process by running lsof -i :8080.
Run kill <pid> once you know the PID to free up that port.
This means there were too many open files on your system. On many Unix systems you can increase the maximum number of open files by adding something like this to your .zshrc:
Now that the network is running, you can use it like you would any other network.
So, you can create a local profile like this:
You can then use that profile for any commands you want to use going forward. For example, if you wanted to publish a Move module like the hello_blockchain package to your local network you could run:
If you want to use the local network with the TypeScript SDK, you can use local network URLs when initializing the client object (Endless):
Sometimes while developing it is helpful to reset the local network back to its initial state, for example:
You made backwards incompatible changes to a Move module, and you'd like to redeploy it without renaming it or using a new account.
You want to clear all on chain state, e.g. accounts, objects, etc.
To start with a brand new local network, use the --force-restart flag:
It will then prompt you if you really want to restart the chain, to ensure that you do not delete your work by accident.
If you do not want to be prompted, include --assume-yes as well:
endless node run-local-testnet...
...
...
Completed generating configuration:
Log file: "/private/var/folders/gn/m74t8ylx55z935q8wx035qn80000gn/T/b3adc18c144bfcc78a1541953893bc1c/validator.log"
Test dir: "/private/var/folders/gn/m74t8ylx55z935q8wx035qn80000gn/T/b3adc18c144bfcc78a1541953893bc1c/0/node.yaml"
Endless root key path: "/private/var/folders/gn/m74t8ylx55z935q8wx035qn80000gn/T/b3adc18c144bfcc78a1541953893bc1c/mint.key"
Waypoint: 0:47e676b5fe38ebe2aec6053db7b3daa0b805693d6422e3475e46e89499464ecf
ChainId: 223
REST API endpoint: 0.0.0.0:8080
Fullnode network: /ip4/0.0.0.0/tcp/7180
Endless is running, press ctrl-c to exitendless node run-local-testnet --config <config-path>Completed generating configuration:
Log file: "/tmp/694173aa3bbe019499bbd5cf3fe0e2fc/validator.log"
Test dir: "/tmp/694173aa3bbe019499bbd5cf3fe0e2fc/0/node.yaml"
Endless root key path: "/tmp/694173aa3bbe019499bbd5cf3fe0e2fc/mint.key"
Waypoint: 0:197bc8b76761622c2d2054d8bf93c1802fa0eb4bc55f0f3d4442878fdecc297f
ChainId: 223
REST API endpoint: 0.0.0.0:8080
Fullnode network: /ip4/0.0.0.0/tcp/7180
Endless is running, press ctrl-c to exitendless node run-local-testnetReadiness endpoint: http://0.0.0.0:8070/
Transaction stream is starting, please wait...
Node API is starting, please wait...
Completed generating configuration:
Log file: "/Users/dport/.endless/testnet/validator.log"
Test dir: "/Users/dport/.endless/testnet"
Endless root key path: "/Users/dport/.endless/testnet/mint.key"
Waypoint: 0:397412c0f96b10fa3daa24bfda962671c3c3ae484e2d67ed60534750e2311f3d
ChainId: 4
REST API endpoint: http://0.0.0.0:8080
Metrics endpoint: http://0.0.0.0:9101/metrics
Endlessnet fullnode network endpoint: /ip4/0.0.0.0/tcp/6181
Indexer gRPC node stream endpoint: 0.0.0.0:50051
Endless is running, press ctrl-c to exit
Node API is ready. Endpoint: http://0.0.0.0:8080/
Transaction stream is ready. Endpoint: http://0.0.0.0:50051/
Applying post startup steps...
Setup is complete, you can now use the local testnet!endless node run-local-testnet --helppanicked at 'error binding to 0.0.0.0:8080: error creating server listener: Address already in use (os error 48)panicked at crates/endless/src/node/local_testnet/logging.rs:64:10:
called `Result::unwrap()` on an `Err` value: Os { code: 24, kind: Uncategorized, message: \"Too many open files\" }"""ulimit -n 32768endless init --profile <your-profile-name> --network localendless move publish --profile <your-profile-name> --package-dir /opt/git/endless-core/endless-move/move-examples/hello_blockchain --named-addresses hello_blockchain=<your-profile-name>import { Endless, EndlessConfig, Network } from "@endless-labs/ts-sdk";
const network = Network.LOCAL;
const config = new EndlessConfig({ network });
const client = new Endless(config);endless node run-local-testnet --force-restartAre you sure you want to delete the existing chain? [yes/no]
> yesendless node run-local-testnet --force-restart --assume-yes