₿ Simchain — Feature Walkthrough

From the repository root:

./scripts/fresh-chain.sh --profile all-tools

This wipes any previous chain and boots a brand-new one with every optional tool enabled, so nothing later in the walkthrough is missing. The first run also builds the images.

Smaller stacks exist too. You want all-tools today; the others are for CI:

Plain regtest gives you one node that mines whenever you ask. Simchain separates the roles on purpose:

Ask a node who it is connected to:

docker exec btc-simnet-node1 bitcoin-cli -regtest \
  -rpcuser=foo -rpcpassword=rpcpassword getconnectioncount

Open a second terminal pane and leave one of these running. Do not skip it — almost every later step is judged by what this pane does.

# block-by-block feed, prints a banner when the chain reorganises
./scripts/chainwatch.sh

# or: aggregate chain and worker status, refreshed
cargo run -p simchainctl -- status --watch

curl -sS --user foo:rpcpassword \
  --data-binary '{"jsonrpc":"2.0","id":1,"method":"getblockcount","params":[]}' \
  http://127.0.0.1:18443/

curl -i --user foo:rpcpassword \
  --data-binary '{"jsonrpc":"2.0","id":2,"method":"generatetoaddress","params":[1,"bcrt1qexample"]}' \
  http://127.0.0.1:18443/

The same credentials are unrestricted on node2, which is how you will still mine on demand:

docker exec btc-simnet-node2 bitcoin-cli -regtest \
  -rpcuser=foo -rpcpassword=rpcpassword getblockcount

Look at the current settings first:

cargo run -p simchainctl -- config show

Now switch the cadence from evenly spaced to Poisson — the distribution real mining follows:

cargo run -p simchainctl -- config set \
  BLOCK_INTERVAL_MODE=poisson \
  BLOCK_INTERVAL_MIN_SECS=5 \
  BLOCK_INTERVAL_MEAN_SECS=8 \
  BLOCK_INTERVAL_MAX_SECS=12

For runs you need to reproduce exactly, pin miner selection and the RNG:

cargo run -p simchainctl -- config set \
  MINER_WEIGHTS=node2:1,node3:1 \
  MINING_RNG_SEED=42

And take manual control when you want it:

cargo run -p simchainctl -- mining pause
cargo run -p simchainctl -- mine --node node2 --blocks 1 --wait
cargo run -p simchainctl -- mining resume

Empty blocks are the other great regtest lie. Turn the pressure up:

cargo run -p simchainctl -- config set \
  ENABLE_SPAM=true \
  SPAM_FILL_BLOCK_RATIO=3

For a controlled spike instead of steady pressure, provision capacity and then burst:

cargo run -p simchainctl -- mining pause
cargo run -p simchainctl -- spam prepare --node node2 --txs 100 --data-bytes 8000
cargo run -p simchainctl -- spam burst  --node node2 --txs 100 --data-bytes 8000
cargo run -p simchainctl -- mine --node node2 --blocks 1 --wait
cargo run -p simchainctl -- mining resume

You need a regtest address. The quickest source is the dashboard's built-in test wallet (Step 8), but any bcrt1 address works:

cargo run -p simchainctl -- faucet --to bcrt1q...=1.5btc --wait

Pass several --to ADDRESS=AMOUNT pairs to fund a batch. Amounts take decimal BTC (1, 0.25, 1btc) or integer satoshis (25000000sat).

Open http://localhost:8090/. Worth clicking through:

• Status — the same data as status --watch.
• Live retuning — change BLOCK_INTERVAL_MEAN_SECS here and watch the generation bump, exactly as in Step 5.
• Pause / resume workers with a click.
• Faucet — test wallet card — a deterministic BIP84 wallet from a public mnemonic, with reveal and copy buttons. Copy an address, paste it into the faucet form, fund it from the browser. This is the easy way to do Step 7.
• Jobs — every mine, burst and reorg as a durable server-side job with progress and results.

Anything you have run so far, your CI can do with curl:

curl -s localhost:8090/api/v1/status | jq .

token="${SIMCHAIN_CONTROL_TOKEN:-simchain-control-dev-token}"
generation=$(curl -s localhost:8090/api/v1/config | jq .generation)

curl -s -X PATCH localhost:8090/api/v1/config \
  -H "Authorization: Bearer $token" \
  -H 'Content-Type: application/json' \
  -d "{\"settings\":{\"SPAM_FEE\":\"0.0005\"},\"base_generation\":$generation}"

• Reads are open on localhost; mutations need the bearer token.
• base_generation is the same compare-and-swap the CLI used in Step 5.
• Also worth knowing: /api/v1/jobs, /api/v1/faucet, /api/v1/config/schema.

And for coding agents

The same operations are exposed as MCP tools at http://localhost:8090/mcp, behind the same token. Once your editor's agent is connected you can ask in plain language:

"Slow mining to a 20 second mean and tell me the current height."
"Partition node3, mine 5 blocks on it, heal, and report the winning tip."

cargo run -p simchainctl -- reorg start --depth 2 --node node3 \
  --adds-new-txs 1 --double-spend-pct 1 --wait

cargo run -p simchainctl -- jobs watch

Variations worth trying:

• --empty mines empty replacement blocks, so orphaned transactions stay unconfirmed — a chaos reorg.
• --double-spend-pct N permanently drops a share of orphaned wallet transactions by mining conflicting spends.
• Continuous mode re-runs a reorg every N blocks, for sustained instability.

cargo run -p simchainctl -- rewind --blocks 3 --wait

Set up your watchers before splitting, or you will only see the aftermath. node3 has no host RPC port by design, so inject the watcher into the container itself:

./scripts/inject-tools.sh btc-simnet-node3

# Pane A — connected side (node2, host-exposed RPC)
./scripts/chainwatch.sh -P 28443 -i 1

# Pane B — isolated side, watched from inside the container
docker exec -it btc-simnet-node3 chainwatch \
  -H 127.0.0.1 -P 18443 -u foo -p rpcpassword -i 1

Both panes should agree on height and tip. Now cut the mesh:

cargo run -p simchainctl -- partition start --node node3 \
  --main-blocks 3 --isolated-blocks 5 --heal-delay-secs 15

Bitcoin Core remembers the branch that lost. Ask it:

docker exec btc-simnet-node1 bitcoin-cli -regtest \
  -rpcuser=foo -rpcpassword=rpcpassword getchaintips

cargo run -p simchainctl -- degrade start --node node2 \
  --delay-ms 5000 --loss-pct 0 --seconds 30

# while that job reports observing_degraded_network:
cargo run -p simchainctl -- mine --node node2 --blocks 1 --wait

Open scenarios/all-features-live.yml and read it: every action from Acts II and IV as ordered, version-controlled steps with assertions and checkpoints. Then run a small one:

cargo run -p simchainctl -- scenario validate scenarios/pause-then-burst.yml
cargo run -p simchainctl -- scenario explain  scenarios/pause-then-burst.yml
cargo run -p simchainctl -- scenario run      scenarios/pause-then-burst.yml \
  --result results/burst.json

./scripts/snapshot.sh save after-walkthrough
./scripts/snapshot.sh list
./scripts/snapshot.sh restore after-walkthrough --profile all-tools

Four ways in, all pointed at node1 — the node you do not control:

All five ZMQ topics are published — rawblock, rawtx, hashblock, hashtx and sequence. The last is the reorg-aware one: it reports mempool add/remove and block connect/disconnect, so a consumer can follow the events from Act IV correctly.

Compose boot settings live in .env: images, credentials, host ports, node policy, wallet names, and the initial mining and spam policy. Every one has a default, so the stack runs with no .env at all.

# edit .env, then:
docker compose --profile all-tools up -d

If you genuinely want to re-read .env, reset only the control plane's own memory. The chain is untouched:

docker compose stop btc-simnet-control-plane
docker volume rm btc-simnet-control-state
docker compose --profile all-tools up -d btc-simnet-control-plane

You have run every feature Simchain has:

• Act I — three nodes, one of which refuses to help you cheat.
• Act II — a running chain is reshaped through a control surface, never a restart.
• Act III — dashboard, CLI, API and MCP are four doors into one operation set.
• Act IV — reorgs, rewinds, splits and propagation delay, on demand.
• Act V — all of it as checked-in YAML, with snapshots to skip the bootstrap.
• Act VI — your application in the middle of it, and the .env trap behind you.

Tear down when you are finished — the chain survives on named volumes and resumes on the next up:

docker compose --profile "*" down

# or discard the chain too
docker compose --profile "*" down -v