devnet-builder

module
v1.0.0-rc0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 20, 2026 License: MIT

README

devnet-builder

Build and manage local blockchain development networks with production state

TL;DR

git clone https://github.com/altuslabsxyz/devnet-builder.git && cd devnet-builder
make build
./build/devnet-builder deploy

After ~2 minutes, you'll have a running local blockchain network with:

Table of Contents

Prerequisites

  • Docker (for docker mode - recommended)
  • curl (for network operations)
  • jq (for JSON processing)
  • zstd or lz4 (for snapshot decompression)
Verify Prerequisites
docker --version
curl --version
jq --version
zstd --version || lz4 --version

Quick Start

Build from Source
git clone https://github.com/altuslabsxyz/devnet-builder.git
cd devnet-builder
make build

# Binary will be at ./build/devnet-builder
Deploy Your First Devnet
# Deploy with default settings (4 validators, mainnet data, docker mode)
./build/devnet-builder deploy

# Check status
./build/devnet-builder status

# View logs
./build/devnet-builder logs -f

# Stop when done
./build/devnet-builder stop
Common Variations
# Single validator (fastest startup)
devnet-builder deploy --validators 1

# With test accounts
devnet-builder deploy --accounts 5

# Use testnet data instead of mainnet
devnet-builder deploy --network testnet

# Local binary mode (advanced)
devnet-builder deploy --mode local

Basic Commands

Command Description
devnet-builder deploy Deploy a new devnet
devnet-builder status Show devnet status
devnet-builder logs View node logs
devnet-builder stop Stop running nodes
devnet-builder start Restart stopped nodes
devnet-builder export Export blockchain state at current height
devnet-builder destroy Remove all devnet data

For complete command reference, see docs/commands.md.

Documentation

For detailed documentation, see the docs/ directory:

Test Accounts

Devnet creates pre-funded test accounts for development.

Export Keys
# View all test accounts
devnet-builder export-keys

# JSON format for scripts
devnet-builder export-keys --json

# Export only accounts (not validators)
devnet-builder export-keys --type accounts
State Export

Export blockchain state at any height for testing upgrades, snapshots, or state analysis:

# Export current state
devnet-builder export

# List all exports
devnet-builder export list

# Inspect export details
devnet-builder export inspect <export-path>

# Custom output directory
devnet-builder export --output-dir /path/to/exports

# Force overwrite existing export
devnet-builder export --force

Upgrade workflow with automatic exports:

# Export state before and after upgrade
devnet-builder upgrade --version v2.0.0 --with-export

# This creates:
# - Pre-upgrade export at current height
# - Post-upgrade export after chain resumes

Export directory structure:

~/.stable-devnet/exports/
└── mainnet-a1b2c3d4-1000000-20240115120000/
    ├── genesis-1000000-a1b2c3d4.json  # Exported state
    └── metadata.json                   # Export metadata

Use cases:

  • Upgrade testing: Verify state before/after upgrades
  • State snapshots: Create backups at critical heights
  • Chain forking: Bootstrap new chains from production state
  • Debugging: Analyze state at specific heights
Network Configuration

Configure your tools to connect to the local devnet:

Parameter Value
Network Name Local Devnet
RPC URL http://localhost:26657
EVM JSON-RPC http://localhost:8545
WebSocket ws://localhost:8546

Plugin System

devnet-builder supports multiple blockchain networks through a plugin architecture. Create custom plugins for any Cosmos SDK-based chain.

# List available networks
devnet-builder networks

# Deploy specific network
devnet-builder --network <network-name> deploy

See docs/PLUGIN_DEVELOPMENT.md for creating custom network plugins.

Troubleshooting

Quick Fixes

Docker not running:

sudo systemctl start docker
# or on macOS
open -a Docker

Port already in use:

lsof -i :26657

Previous devnet exists:

devnet-builder destroy --force
devnet-builder deploy

For more troubleshooting help, see docs/troubleshooting.md.

License

This project is licensed under the MIT License.

Directories

Path Synopsis
cmd
devnet-builder command
Package main provides the CLI entry point for devnet-builder.
 Package main provides the CLI entry point for devnet-builder.
devnet-builder/commands
Package commands provides the CLI command implementations for devnet-builder.
 Package commands provides the CLI command implementations for devnet-builder.
devnet-builder/commands/cache
Package cache provides binary cache management commands for devnet-builder.
 Package cache provides binary cache management commands for devnet-builder.
devnet-builder/commands/config
Package config provides configuration management commands for devnet-builder.
 Package config provides configuration management commands for devnet-builder.
devnet-builder/commands/core
Package core provides core CLI commands for devnet-builder.
 Package core provides core CLI commands for devnet-builder.
devnet-builder/commands/export
Package export provides export-related commands for devnet-builder.
 Package export provides export-related commands for devnet-builder.
devnet-builder/commands/manage
Package manage provides devnet lifecycle management commands.
 Package manage provides devnet lifecycle management commands.
devnet-builder/shared
Package shared provides shared state and utilities for devnet-builder commands.
 Package shared provides shared state and utilities for devnet-builder commands.
examples
cosmos-plugin command
Example plugin for devnet-builder demonstrating how to create a custom network module for your own Cosmos SDK-based blockchain.
 Example plugin for devnet-builder demonstrating how to create a custom network module for your own Cosmos SDK-based blockchain.
application
application/binary
application/build
Package build contains UseCases for building binaries from source.
 Package build contains UseCases for building binaries from source.
application/devnet
Package devnet contains UseCases for devnet lifecycle management.
 Package devnet contains UseCases for devnet lifecycle management.
application/dto
application/ports
Package ports defines the interfaces (ports) that the application layer requires from the infrastructure layer.
 Package ports defines the interfaces (ports) that the application layer requires from the infrastructure layer.
application/upgrade
Package upgrade contains UseCases for chain upgrade operations.
 Package upgrade contains UseCases for chain upgrade operations.
application/version
Package version provides use cases for version management.
 Package version provides use cases for version management.
config
di
Package di provides dependency injection container for the application.
 Package di provides dependency injection container for the application.
domain
domain/credential
Package credential provides secure credential management interfaces.
 Package credential provides secure credential management interfaces.
domain/export
domain/ports
domain/version
Package version provides domain entities for version management.
 Package version provides domain entities for version management.
infrastructure/binary
infrastructure/builder
Package builder provides builder implementations.
 Package builder provides builder implementations.
infrastructure/cache
Package cache provides cache implementations.
 Package cache provides cache implementations.
infrastructure/credential
Package credential provides credential storage implementations.
 Package credential provides credential storage implementations.
infrastructure/docker
infrastructure/evm
Package evm provides EVM RPC client implementations.
 Package evm provides EVM RPC client implementations.
infrastructure/executor
infrastructure/export
Package export provides infrastructure implementations for state export operations.
 Package export provides infrastructure implementations for state export operations.
infrastructure/filesystem
infrastructure/genesis
Package genesis provides genesis fetching and export implementations.
 Package genesis provides genesis fetching and export implementations.
infrastructure/github
Package github provides infrastructure adapter for GitHub API operations.
 Package github provides infrastructure adapter for GitHub API operations.
infrastructure/helpers
Package helpers provides shared utility functions for the devnet-builder CLI.
 Package helpers provides shared utility functions for the devnet-builder CLI.
infrastructure/interactive
Package interactive provides infrastructure adapter for interactive prompts.
 Package interactive provides infrastructure adapter for interactive prompts.
infrastructure/keyring
Package keyring provides key management implementations.
 Package keyring provides key management implementations.
infrastructure/network
Package network provides the network module abstraction for supporting multiple Cosmos SDK networks in devnet-builder.
 Package network provides the network module abstraction for supporting multiple Cosmos SDK networks in devnet-builder.
infrastructure/node
Package node provides node management implementations.
 Package node provides node management implementations.
infrastructure/nodeconfig
infrastructure/persistence
Package persistence provides file-based storage implementations.
 Package persistence provides file-based storage implementations.
infrastructure/plugin
Package plugin provides HashiCorp go-plugin based network module plugin system.
 Package plugin provides HashiCorp go-plugin based network module plugin system.
infrastructure/prereq
infrastructure/process
Package process provides process execution implementations.
 Package process provides process execution implementations.
infrastructure/rpc
Package rpc provides RPC client implementations.
 Package rpc provides RPC client implementations.
infrastructure/snapshot
Package snapshot provides snapshot fetching and extraction implementations.
 Package snapshot provides snapshot fetching and extraction implementations.
infrastructure/stateexport
Package stateexport provides state export implementations for snapshot-based genesis.
 Package stateexport provides state export implementations for snapshot-based genesis.
infrastructure/tomlutil
Package tomlutil provides utilities for TOML file manipulation.
 Package tomlutil provides utilities for TOML file manipulation.
infrastructure/version
Package version provides infrastructure implementations for version management.
 Package version provides infrastructure implementations for version management.
infrastructure/version/migrations
Package migrations contains all version migrations.
 Package migrations contains all version migrations.
output
paths
Package paths provides centralized path management for devnet-builder.
 Package paths provides centralized path management for devnet-builder.
pkg
network
Package network provides the public SDK for developing devnet-builder network plugins.
 Package network provides the public SDK for developing devnet-builder network plugins.
network/plugin
Package plugin provides helpers for developing devnet-builder network plugins.
 Package plugin provides helpers for developing devnet-builder network plugins.
tests
e2e/helpers
Package common provides shared domain types and value objects.
 Package common provides shared domain types and value objects.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.