aleo-devnode

A standalone Aleo development node for local testing and development.

Build

cargo build --release

Usage

Start the devnode

aleo-devnode start --private-key APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH

The private key above is the standard Aleo testnet development key — safe to use locally, never use it in production.

The node starts a REST API on http://127.0.0.1:3030 by default and automatically advances the ledger to the latest consensus version.

Options

Flag	Default	Description
--private-key	$PRIVATE_KEY env var	Private key for block creation
-a, --socket-addr	127.0.0.1:3030	REST API bind address
-v, --verbosity	2	Log verbosity: 0 = info, 1 = debug, 2 = trace
-g, --genesis-path	built-in	Path to a custom genesis block file
-m, --manual-block-creation	off	Disable automatic block creation on broadcast
-s, --storage [DIR]	in-memory	Persist the ledger to disk at DIR (default: devnode/)
-c, --clear-storage	off	Clear the storage directory before starting (requires -s)

Advance the ledger manually

When running with --manual-block-creation, use advance to create blocks explicitly:

aleo-devnode advance

Advance by a specific number of blocks:

aleo-devnode advance 5

By default this targets 127.0.0.1:3030. Use --socket-addr to point at a different instance.

Persistent storage

aleo-devnode start --private-key APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH --storage

This persists the ledger to a devnode/ directory. To start fresh:

aleo-devnode start --private-key APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH --storage --clear-storage

Snapshots

Snapshots capture the ledger state at a specific block height and can be restored later. They require persistent storage (--storage).

Snapshots are saved alongside the storage directory — e.g. if storage is devnode/, snapshots are written to devnode-snapshots/.

Take a snapshot

curl -X POST http://127.0.0.1:3030/testnet/snapshot \
     -H "Content-Type: application/json" \
     -d '{"name": "before-deploy"}'

If no name is provided, the snapshot is named automatically using the current block height (e.g. snapshot-42):

curl -X POST http://127.0.0.1:3030/testnet/snapshot \
     -H "Content-Type: application/json" \
     -d '{}'

Response: {"name": "before-deploy", "height": 42}

List snapshots

curl http://127.0.0.1:3030/testnet/snapshots

Response: ["before-deploy", "snapshot-42"]

Restore a snapshot

The devnode must not be running when restoring. Stop it first, then run:

aleo-devnode restore --snapshot before-deploy --storage devnode

The original snapshot directory is left untouched, so the same snapshot can be restored multiple times.

Restore and restart in one step

aleo-devnode restore \
    --snapshot before-deploy \
    --storage devnode \
    --restart \
    --private-key APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH

If PRIVATE_KEY is set in the environment, --private-key can be omitted.

Restore options

Flag	Default	Description
--snapshot	required	Name of the snapshot to restore
--storage	devnode	Ledger storage directory to restore into
--restart	off	Restart the devnode after restoring
--private-key	$PRIVATE_KEY env var	Private key (forwarded to start when --restart is set)
-a, --socket-addr	127.0.0.1:3030	REST API address (forwarded to start when --restart is set)
-v, --verbosity	2	Log verbosity (forwarded to start when --restart is set)
-m, --manual-block-creation	off	Disable auto block creation (forwarded to start when --restart is set)

REST API

The node exposes the standard Aleo REST API under /<network>/ (e.g. /testnet/), with versioned prefixes /v1/testnet/ and /v2/testnet/ also available.

Key endpoints:

Method	Path	Description
GET	/testnet/block/height/latest	Latest block height
GET	/testnet/block/latest	Latest block
GET	/testnet/block/{height_or_hash}	Block by height or hash
POST	/testnet/transaction/broadcast	Broadcast a transaction
POST	/testnet/block/create	Create blocks (body: {"num_blocks": N}, optional)
GET	/testnet/program/{id}	Get a deployed program
GET	/testnet/program/{id}/mapping/{name}/{key}	Get a mapping value
POST	/testnet/snapshot	Take a snapshot (body: {"name": "optional"})
GET	/testnet/snapshots	List available snapshots
POST	/testnet/shutdown	Gracefully shut down the node

Shutdown

To stop the node gracefully (draining any in-flight requests before exiting):

curl -X POST http://127.0.0.1:3030/testnet/shutdown

Ctrl+C and SIGTERM also trigger graceful shutdown.