From dc099b14591c4c7a4a6aa85fd9b458fd756d8c82 Mon Sep 17 00:00:00 2001 From: KOVACS Krisztian Date: Wed, 3 Jun 2026 12:13:50 +0200 Subject: [PATCH 1/3] feat(docker-compose): allow using custom genesis config file for local setup --- Makefile | 4 ++++ compose/bootstrap-genesis-config.yml | 18 ++++++++++++++++++ docker-compose.yml | 15 ++++++++++++++- 3 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 compose/bootstrap-genesis-config.yml diff --git a/Makefile b/Makefile index 941d19924..3fcbab66f 100644 --- a/Makefile +++ b/Makefile @@ -177,6 +177,10 @@ local-network-build: docker-build ## Builds Docker images used by the local deve local-network-up: ## Starts the local development network docker compose $(COMPOSE_FILES) up -d +.PHONY: local-network-up-with-custom-genesis-config +local-network-up-with-custom-genesis-config: ## Starts the local development network with a custom genesis config file + docker compose $(COMPOSE_FILES) -f compose/bootstrap-genesis-config.yml up -d + .PHONY: local-network-down local-network-down: ## Stops the local development network, preserving volumes docker compose $(COMPOSE_FILES) down --remove-orphans diff --git a/compose/bootstrap-genesis-config.yml b/compose/bootstrap-genesis-config.yml new file mode 100644 index 000000000..2b16cfda7 --- /dev/null +++ b/compose/bootstrap-genesis-config.yml @@ -0,0 +1,18 @@ +# Optional override for bootstrapping the validator from a host genesis config file. +# +# Usage: +# MIDEN_GENESIS_CONFIG_FILE=/absolute/path/to/genesis.toml \ +# make local-network-up-with-custom-genesis-config +# +# The file is mounted at a fixed in-container path so the bootstrap command never +# receives a host path. + +services: + bootstrap-validator: + volumes: + - type: bind + source: ${MIDEN_GENESIS_CONFIG_FILE:?Set MIDEN_GENESIS_CONFIG_FILE to the genesis config file path} + target: /genesis.toml + read_only: true + environment: + MIDEN_NODE_VALIDATOR_USE_GENESIS_CONFIG: "1" diff --git a/docker-compose.yml b/docker-compose.yml index 4cde0e11d..9a17be8cc 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,8 @@ # Environment variables: # - MIDEN_REMOTE_PROVER_URL: remote transaction prover URL. Defaults to the # bundled miden-remote-prover service at http://tx-prover:50051. +# - MIDEN_NODE_VALIDATOR_USE_GENESIS_CONFIG: set by compose/bootstrap-genesis-config.yml +# to pass /genesis.toml to `miden-validator bootstrap`. services: bootstrap-validator: @@ -21,11 +23,22 @@ services: rm -rf /data/genesis /data/validator /data/accounts mkdir -p /data/genesis /data/validator /data/accounts + GENESIS_CONFIG_ARGS="" + if [ -n "$${MIDEN_NODE_VALIDATOR_USE_GENESIS_CONFIG:-}" ]; then + if [ ! -f /genesis.toml ]; then + echo "Genesis config requested but /genesis.toml is not mounted." + exit 1 + fi + + GENESIS_CONFIG_ARGS="--genesis-config-file /genesis.toml" + fi + echo "Bootstrapping validator..." miden-validator bootstrap \ --data-directory /data/validator \ --genesis-block-directory /data/genesis \ - --accounts-directory /data/accounts + --accounts-directory /data/accounts \ + $$GENESIS_CONFIG_ARGS touch /data/validator/.bootstrapped From f6f2beb6eabcc49a9b5badf646bdaeff84773d15 Mon Sep 17 00:00:00 2001 From: KOVACS Krisztian Date: Wed, 3 Jun 2026 12:21:00 +0200 Subject: [PATCH 2/3] chore(docs/external): update local network documentation --- .../external/src/local-network-development.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/external/src/local-network-development.md b/docs/external/src/local-network-development.md index ddca71b45..a2192832f 100644 --- a/docs/external/src/local-network-development.md +++ b/docs/external/src/local-network-development.md @@ -86,6 +86,26 @@ The network monitor at `http://localhost:3001` provides a compact health view fo The default stack spins up an internal prover instance which means proving will happen locally. This can be overridden to use an external prover by setting `MIDEN_REMOTE_PROVER_URL` when starting the stack. +## Genesis Config Override + +By default, the local network bootstraps from the validator's built-in genesis configuration. To bootstrap from a custom +genesis configuration file, use `make local-network-up-with-custom-genesis-config` and set `MIDEN_GENESIS_CONFIG_FILE` +to the host path of the TOML file: + +```bash +MIDEN_GENESIS_CONFIG_FILE=/absolute/path/to/genesis.toml make local-network-up-with-custom-genesis-config +``` + +The override bind mounts the host file into the bootstrap validator container as `/genesis.toml` and passes that +in-container path to `miden-validator bootstrap --genesis-config-file`. + +This only affects validator bootstrap. If the local network has already been bootstrapped, delete the existing local +chain data before starting with a different genesis configuration: + +```bash +make local-network-delete +``` + ## Check the RPC API The RPC server exposes gRPC reflection. With `grpcurl` installed, a basic status check looks like: From 6045639685c5861750561b07e9abadfd6560a5f1 Mon Sep 17 00:00:00 2001 From: KOVACS Krisztian Date: Wed, 3 Jun 2026 14:16:01 +0200 Subject: [PATCH 3/3] refactor(docker-compose): use a dummy file to avoid adding an extra override The bind mount cannot be conditional on the environment variable, so we now always mount the dummy file if the genesis configuration file was not specified. --- Makefile | 4 ---- compose/bootstrap-genesis-config.yml | 18 ------------------ compose/genesis/dummy.toml | 4 ++++ docker-compose.yml | 12 ++++++++++-- docs/external/src/local-network-development.md | 5 ++--- 5 files changed, 16 insertions(+), 27 deletions(-) delete mode 100644 compose/bootstrap-genesis-config.yml create mode 100644 compose/genesis/dummy.toml diff --git a/Makefile b/Makefile index 3fcbab66f..941d19924 100644 --- a/Makefile +++ b/Makefile @@ -177,10 +177,6 @@ local-network-build: docker-build ## Builds Docker images used by the local deve local-network-up: ## Starts the local development network docker compose $(COMPOSE_FILES) up -d -.PHONY: local-network-up-with-custom-genesis-config -local-network-up-with-custom-genesis-config: ## Starts the local development network with a custom genesis config file - docker compose $(COMPOSE_FILES) -f compose/bootstrap-genesis-config.yml up -d - .PHONY: local-network-down local-network-down: ## Stops the local development network, preserving volumes docker compose $(COMPOSE_FILES) down --remove-orphans diff --git a/compose/bootstrap-genesis-config.yml b/compose/bootstrap-genesis-config.yml deleted file mode 100644 index 2b16cfda7..000000000 --- a/compose/bootstrap-genesis-config.yml +++ /dev/null @@ -1,18 +0,0 @@ -# Optional override for bootstrapping the validator from a host genesis config file. -# -# Usage: -# MIDEN_GENESIS_CONFIG_FILE=/absolute/path/to/genesis.toml \ -# make local-network-up-with-custom-genesis-config -# -# The file is mounted at a fixed in-container path so the bootstrap command never -# receives a host path. - -services: - bootstrap-validator: - volumes: - - type: bind - source: ${MIDEN_GENESIS_CONFIG_FILE:?Set MIDEN_GENESIS_CONFIG_FILE to the genesis config file path} - target: /genesis.toml - read_only: true - environment: - MIDEN_NODE_VALIDATOR_USE_GENESIS_CONFIG: "1" diff --git a/compose/genesis/dummy.toml b/compose/genesis/dummy.toml new file mode 100644 index 000000000..78165b928 --- /dev/null +++ b/compose/genesis/dummy.toml @@ -0,0 +1,4 @@ +# Placeholder bind-mount target used when MIDEN_GENESIS_CONFIG_FILE is not set. +# +# This file is not passed to `miden-validator bootstrap`; omitting the +# --genesis-config-file flag preserves the validator's built-in default genesis config. diff --git a/docker-compose.yml b/docker-compose.yml index 9a17be8cc..7c27db28f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,8 +1,10 @@ # Environment variables: # - MIDEN_REMOTE_PROVER_URL: remote transaction prover URL. Defaults to the # bundled miden-remote-prover service at http://tx-prover:50051. -# - MIDEN_NODE_VALIDATOR_USE_GENESIS_CONFIG: set by compose/bootstrap-genesis-config.yml -# to pass /genesis.toml to `miden-validator bootstrap`. +# - MIDEN_GENESIS_CONFIG_FILE: path to the genesis configuration file. +# By default, the local network bootstraps from the validator's built-in +# genesis configuration. Use this environment variable to override the +# built-in configuration. services: bootstrap-validator: @@ -10,6 +12,12 @@ services: pull_policy: if_not_present volumes: - node-data:/data + - type: bind + source: ${MIDEN_GENESIS_CONFIG_FILE:-./compose/genesis/dummy.toml} + target: /genesis.toml + read_only: true + environment: + MIDEN_NODE_VALIDATOR_USE_GENESIS_CONFIG: ${MIDEN_GENESIS_CONFIG_FILE:-} entrypoint: ["/bin/sh", "-c"] command: - | diff --git a/docs/external/src/local-network-development.md b/docs/external/src/local-network-development.md index a2192832f..29ef2a24f 100644 --- a/docs/external/src/local-network-development.md +++ b/docs/external/src/local-network-development.md @@ -89,11 +89,10 @@ to use an external prover by setting `MIDEN_REMOTE_PROVER_URL` when starting the ## Genesis Config Override By default, the local network bootstraps from the validator's built-in genesis configuration. To bootstrap from a custom -genesis configuration file, use `make local-network-up-with-custom-genesis-config` and set `MIDEN_GENESIS_CONFIG_FILE` -to the host path of the TOML file: +genesis configuration file, set `MIDEN_GENESIS_CONFIG_FILE` to the host path of the TOML file: ```bash -MIDEN_GENESIS_CONFIG_FILE=/absolute/path/to/genesis.toml make local-network-up-with-custom-genesis-config +MIDEN_GENESIS_CONFIG_FILE=/absolute/path/to/genesis.toml make local-network-up ``` The override bind mounts the host file into the bootstrap validator container as `/genesis.toml` and passes that