Run The Minerva Devnet

Requirements

• Node.js 20+
• PNPM 10+
• Go 1.22+
• Foundry
• CoreGeth-compatible PoW binary, or the local Minerva CoreGeth fork

Build the local Minerva CoreGeth fork:

pnpm coregeth:build

pnpm devnet:start automatically uses:

build/bin/minerva-geth

Set the node binary manually if you want to run a different compatible fork:

export MINERVA_COREGETH_BIN=/path/to/core-geth

Modern stock Geth is not a supported default for Minerva devnet mining because it refuses Ethash sealing on new private networks. A stock-Geth fallback exists only for debugging:

export MINERVA_ALLOW_STOCK_GETH_FALLBACK=1

That fallback does not include the Minerva ML-DSA precompile.

Install

pnpm install

Start

The local services default to:

MINERVA_NETWORK=devnet

pnpm devnet:start
pnpm devnet:health

The node RPC listens on:

http://127.0.0.1:8545

The RPC gateway listens on:

pnpm rpc:start

http://127.0.0.1:18545/rpc

Deploy Contracts

pnpm contracts:deploy:devnet

The deployment script writes:

contracts/deployments/devnet/deployments.json

PQ Account Smoke Test

Run the full local proof with one command:

pnpm devnet:acceptance

pnpm devnet:acceptance starts the devnet if needed, deploys contracts, starts the RPC gateway, faucet, PQ relayer, indexer, and explorer-lite, runs every PQ smoke test below, then stops the processes it started.

It also runs pnpm docs:acceptance and pnpm admin:acceptance, which check that the threat model, quantum-readiness matrix, and admin-control inventory keep the exact claim boundary aligned with the implemented devnet behavior.

With the devnet running and contracts deployed, each smoke can also be run individually:

pnpm devnet:pq-smoke
pnpm devnet:pq-admin-smoke
pnpm devnet:explorer-smoke
pnpm devnet:wallet-pq-smoke
pnpm devnet:wallet-pq-rotate-smoke
pnpm devnet:wallet-pq-backup-smoke
pnpm devnet:wallet-app-acceptance
pnpm devnet:wallet-app-ui-smoke
pnpm docs:acceptance
pnpm admin:acceptance

This command generates a fresh ML-DSA-65 keypair, deploys a deterministic Minerva Account, funds it with MRV, signs executeMessage(...), submits executePQ(...), and confirms the account nonce, PQ Native registry mode, readiness record, and transfer balance.

pnpm devnet:pq-admin-smoke proves the protocol/admin pattern. It deploys a Minerva Account as the PQ controller for MinervaAdminVault, verifies a Legacy EOA cannot record policy directly, then uses ML-DSA-signed executePQ calls to record a policy value and transfer treasury funds. When the faucet service is running, that treasury transfer tops up the faucet hot wallet and then a real faucet claim is exercised.

pnpm devnet:explorer-smoke verifies that explorer-lite, the RPC gateway, and the indexer expose the live security posture: PQ Native default accounts, the ML-DSA precompile, faucet treasury mode, indexed transactions/events, Legacy EOA compatibility labels, and the exact claim boundary.

Explorer-lite also exposes proof views:

http://127.0.0.1:18547/proofs/pq-accounts
http://127.0.0.1:18547/proofs/faucet
http://127.0.0.1:18547/proofs/admin-vaults

Each detail view links to a JSON proof bundle from the indexer. Bundles include chain ID, the exact claim boundary, block hashes, transaction hashes, event topics, decoded event fields, and the indexed evidence used by the page.

Bundles can be verified outside the explorer against live RPC state:

pnpm proofs:verify --rpc http://127.0.0.1:18545/rpc --bundle ./proof.json

pnpm devnet:explorer-smoke exports one PQ account bundle, one faucet claim bundle, and one admin vault bundle, then runs the proof verifier against the gateway RPC. This checks that every referenced block, transaction, receipt, and log exists on-chain and that admin/faucet privileged evidence includes same-receipt ExecutedPQ from the PQ controller.

To keep those artifacts after a run:

pnpm devnet:proof-pack

pnpm devnet:proof-pack writes artifacts/proofs/devnet/<timestamp>/manifest.json, pq-account-proof.json, faucet-claim-proof.json, admin-vault-proof.json, verifier-report.json, indexer-status.json, and acceptance-summary.txt. Full pnpm devnet:acceptance runs this near the end while the RPC gateway, indexer, and explorer are still live.

pnpm devnet:wallet-pq-smoke performs the wallet-owned version of the proof. It runs the mobile wallet acceptance path from the Minerva wallet repo, asks the PQ faucet to fund and deploy the wallet-derived account, then submits a wallet-signed raw MinervaPQTxV1 that calls executePQ. Set MINERVA_WALLET_DIR if the wallet repo is not beside this repo.

pnpm devnet:wallet-pq-rotate-smoke proves PQ key lifecycle. It deploys with wallet key A, rotates account control to wallet key B with an ML-DSA authorization from key A, proves key A can no longer authorize executePQ, then proves key B can move funds while the native gas authorization remains the deployment ML-DSA key.

pnpm devnet:wallet-pq-backup-smoke proves encrypted wallet recovery. It asks the faucet to fund and deploy a wallet-owned account, exports a passcode-encrypted profile, rejects a wrong passcode, restores with the correct passcode, then signs and submits a raw PQ transaction using only the restored ML-DSA key material.

pnpm devnet:wallet-app-acceptance runs the mobile wallet acceptance path from the Minerva wallet repo. It verifies the app-facing chain config, MRV balance label, deployment state, PQ Native readiness, faucet funding, and a PQ transaction submitted through the same transfer helper used by the mobile hook. Set MINERVA_WALLET_DIR if the wallet repo is not beside this repo.

pnpm devnet:wallet-app-ui-smoke starts Expo Web for the mobile wallet and uses a headless browser to click the visible Home screen controls: Get MRV, Deploy PQ Account, and Send PQ Test Transfer. It saves a final screenshot under logs/devnet-acceptance/mobile-ui-smoke/.

Dev PQ Relayer

For wallet development, start the dev-only PQ relayer:

pnpm pq-relayer:start

It listens on:

http://127.0.0.1:18548

The relayer does not own an account-control key or an EOA gas key. The wallet sends its ML-DSA-65 public key to predict the deterministic Minerva Account, the faucet can fund and deploy it through the canonical factory, and the wallet submits raw 0x04 MinervaPQTxV1 bytes through /pq-dev/send-raw.

Start Services

pnpm faucet:start
pnpm rpc:start
pnpm explorer:start
pnpm indexer:start

Persistent Compose Baseline

Phase 6 adds a local persistent compose baseline for testnet-readiness work:

docker compose -f infra/docker-compose.yml --profile all up --build

This targets Minerva Devnet by default. The public testnet runs from infra/docker-compose.minerva-testnet.yml; see docs/testnet/minerva-launch.md.

CoreGeth Precompile

The local CoreGeth fork registers the Minerva ML-DSA-65 verifier at:

0x0000000000000000000000000000000000004D00

The adapter activates at the minervaMLDSA65PrecompileBlock fork in chain config and is covered by:

pnpm coregeth:test