Skip to content

README.md

Latest commit

 

History

History
237 lines (182 loc) · 6.73 KB

README.md

File metadata and controls

237 lines (182 loc) · 6.73 KB
Raw

Monad Docker Solonet Logo

Monad Solonet

Run a full Monad network, locally.

Quick Start

Bootstrap a complete Monad network and run your own blockchain locally, fully containerized and reproducible.

On macOS (Apple Silicon), prepare the Linux VM:

# Install Linux virtual machine manager
brew install lima colima lima-additional-guestagents

# Start a Docker host on a Linux VM
colima start \
  --arch x86_64 \
  --cpu-type max \
  --cpu 8 \
  --memory 16 \
  --disk 300 \
  --foreground

Start a Monad Solonet on a Linux Docker host, using the prebuild monadcrypto/monad-solonet Docker image:

docker run --rm -it \
  --name solonet \
  --privileged \
  --network host \
  --ulimit nofile=16384:16384 \
  --pull always \
  monadcrypto/monad-solonet

Features

  • Uses monad official package and binaries
  • Supports single-validator, multi-validators, and custom network setups
  • Runs natively on Linux with Docker or on macOS via an x86_64 Linux VM
  • Uses the official devnet genesis allocation configuration
  • Exposes RPC endpoint at http://localhost:8080
  • Automatic node configuration and validator staking
  • Pre-installed tooling: forge, cast, staking-cli, monad-status
  • Configurable CPU execution policies (throttling, native mode, CPU pinning)
demo.mov

Runtime notes:

  • Epoch duration set to 10_000 blocks, about 1 hour
  • By default, Monad processes are limited to 0.5 CPU to reduce host resource usage
  • CPU limits can be customized or disabled via environment variables
  • Native performance mode with CPU pinning is supported
  • TrieDB runs on a loopback disk stored inside the container
  • Restarting containers preserves TrieDB data. Recreating containers resets TrieDB state.
  • Static IP assignment is used to avoid DHCP drift and maintain stable node record signatures

Disclaimer: This project is intended for development and testing purposes only. Do not use in production.

Monitoring

Solonet includes an optional monitoring stack based on Prometheus, Grafana and Node Exporter.

Start monitoring:

cd addons/monitoring
docker compose up -d

Available endpoints:

Service URL
Grafana http://localhost:3000
Prometheus http://localhost:9090
Node Exporter http://localhost:9100

Default Grafana credentials:

admin
admin

The monitoring stack provides:

  • Monad consensus metrics
  • Execution metrics
  • RPC metrics
  • System CPU usage
  • Memory usage
  • Disk usage
  • Network traffic

Metrics Endpoints

The default Prometheus configuration supports both deployment modes:

Compose-based Solonet

host.docker.internal:48089
host.docker.internal:48189
host.docker.internal:48289

Default port mapping:

48080 -> RPC
48081 -> WebSocket RPC
48082 -> Engine API
48089 -> Metrics (node-1)
48189 -> Metrics (node-2)
48289 -> Metrics (node-3)

Host network mode

When Solonet is started using the Quick Start command with:

--network host

metrics are exposed on:

host.docker.internal:8889

If you are using a custom port_base in network.toml, update the Prometheus targets in addons/monitoring/prometheus.yml accordingly.

Solonet versus other tools

Category Solonet Public Full node (docs)
Concept Spin up a NETWORK Spin up a NODE
Purpose Local isolated network Join mainnet/testnet
Topology n validators, m fullnodes Single node
Use case Functional testing, dev Production-like usage
State New chain, from genesis Existing network, real chain state
Network type devnet mainnet/testnet
Control Full control Limited (network rules)
Tokens Unlimited Limited (MON, faucet)
Protocol version monad_dev (latest features) Current MONAD_REVISION/EVM_REVISION
Perf realism ❌ Not realistic ✅ Realistic
Storage Loopback (TrieDB) Real disk
CPU Throttled by default, optional native mode and CPU pinning No artificial limits
Binary Dev/custom setup Official/supported binaries
Env Docker Host
Setup style Flexible, dev-focused Follows official docs
Best machine Linux bare metal Linux bare metal
VM support ✅ Yes ✅ Partially
macOS ARM ✅ QEMU VM ❌ Not supported

Run Monad Solonet networks

Requirements:

  • Linux on x86_64 machine (see instructions below for macOS)
  • docker installed
  • 4 CPU and 16GB memory
  • Tested on Amazon EC2 instance m8a.xlarge.
  1. Clone the repository
git clone https://github.com/monad-developers/monad-docker-solonet.git
cd monad-docker-solonet
  1. Start the network

Start a single-validator network:

docker compose up --build

Reset and teardown

Stop and remove containers, including volumes:

docker compose -f NETWORK_FILE down --volumes

Prepare Docker Linux VM on macOS (Apple Silicon)

Since Monad binaries target x86_64, macOS ARM requires a Linux x86_64 virtual machine running Docker.

Requirements:

  • Apple macOS
  • Homebrew installed
  • Tested on MacBook Pro, M4 Max, 48 GB memory
  1. Install Lima and Colima:
brew install lima colima lima-additional-guestagents
  1. Start the virtual machine with:
colima start --arch x86_64 --cpu-type max --cpu 8 --memory 16 --disk 300 --foreground
  1. Verify the docker context:
docker info

Expected output should include:

 Architecture: x86_64
 CPUs: 8
 Total Memory: 15.61GiB
 Name: colima

Reset and teardown

To completely remove the VM and all associated data:

colima delete --data