Migrate regtest usage off nigiri (in-house Node CLI)

[Kukks]

Summary

arkade-regtest was rewritten to drop nigiri / chopsticks / esplora in favour of an in-house Docker Compose stack (Bitcoin Core + Fulcrum + mempool + NBXplorer + arkd + …) driven by a zero-dependency Node CLI (regtest.mjs). This migrates the solver's integration test harness off nigiri and onto it.

• Add arkade-regtest as a git submodule at regtest/, pinned to master. NOT bumped to the unmerged denigiri-regtest branch (see "Blocked by" below).
• Makefile: setup-test-env / teardown-test-env now run node regtest/regtest.mjs start / clean instead of nigiri start / nigiri stop --delete. The arkd-funding loop uses node regtest/regtest.mjs faucet <addr> <btc> --confirm.
• test/docker-compose.yml:
  • ARKD_ESPLORA_URL: http://chopsticks:3000 → http://mempool_web/api (esplora REST moved under mempool's /api).
  • External network: nigiri → arkade-regtest_default (the default network of the arkade-regtest compose project).
• test/e2e/utils_test.go: faucet() now invokes the regtest CLI with --confirm. The CLI path is resolved repo-root-relative (via runtime.Caller) so it works regardless of go test's working directory (which is test/e2e, not the repo root).
• CI (.github/workflows/integration.yaml): replace the vulpemventures/nigiri-github-action step with actions/setup-node + node regtest/regtest.mjs start; actions/checkout now uses submodules: recursive; added a teardown node regtest/regtest.mjs clean.
• README: document submodule init, the new commands, the network change, and the mining note below.

⚠ Behavioral change — mining

nigiri auto-mined and nigiri faucet confirmed immediately. arkade-regtest's faucet spends from the Bitcoin Core node wallet and does NOT mine by default — --confirm mines one block right after the send to preserve the old confirm-on-faucet behavior. A background auto-miner also mines every AUTOMINE_INTERVAL seconds (default 600; 0 disables). Every place that faucets and then waits for a confirmation now passes --confirm (Makefile funding loop + faucet() in utils_test.go).

Consumption pattern (note — diverges from the canonical submodule consumer)

The solver does not drive arkade-regtest end-to-end. It runs its own test/docker-compose.yml (its own solverd-arkd / solverd-arkd-wallet / solverd-nbxplorer / solverd-emulator stack) and previously attached to nigiri's external network to reach nigiri's bitcoin node + chopsticks esplora, funding via nigiri faucet. So arkade-regtest here only provides the base chain + indexer/explorer + faucet, not arkd. Consequently:

• The arkd container stays solverd-arkd (the brief's ark→arkd rename applies to arkade-regtest's own arkd container, not the solver's separately-named one), so docker exec solverd-arkd … is left as-is.
• ARKD_* tuning, image pins, and zero-fee settings are kept. There were no NIGIRI_*, BITCOIN_LOW_FEE, or ARK_CONTAINER vars in this repo to remove.

Open questions / manual follow-ups

1. Network name. This assumes the arkade-regtest compose project's default network is arkade-regtest_default (derived from the name: arkade-regtest in docker/compose.base.yml). Confirm once #27 is merged — if the project name or network differs, update networks.default.name in test/docker-compose.yml.
2. Profiles. node regtest/regtest.mjs start brings up the base stack. arkade-regtest also runs the solver as its own solver profile; this PR deliberately does not use that — the solver repo keeps building/running its own solverd for the e2e tests. If only a subset of base services is needed, consider REGTEST_PROFILES.
3. CI port/exposure. Verify mempool's esplora /api and the bitcoin node are reachable from the solverd-arkd container over the shared network in CI once the real stack is up.

Verify after ArkLabsHQ/arkade-regtest#27 merges

The submodule is pinned to arkade-regtest master, which does not yet contain regtest.mjs. Full integration tests cannot run until #27 merges and the submodule is bumped. Do not expect a green integration run before then.

• Bump submodule: git -C regtest fetch && git -C regtest checkout origin/master && git add regtest
• Confirm regtest/regtest.mjs exists and node regtest/regtest.mjs start boots the stack
• Confirm the compose network name matches arkade-regtest_default (open question Update documentation to use "Arkade" terminology consistently #1)
• Run make setup-test-env && make integrationtest && make teardown-test-env locally
• Confirm CI integration job is green

Blocked by ArkLabsHQ/arkade-regtest#27

[arkanaai]

Review: Migrate regtest usage off nigiri — ✅ APPROVE

Clean infrastructure migration. No protocol-critical code touched — this only changes the test harness (CI, Makefile, docker-compose, test utilities). No VTXO, signing, forfeit, round, or exit path changes.

Verified correct

• Network name: arkade-regtest_default matches the name: arkade-regtest project name in docker/compose.base.yml. ✅
• Esplora URL: http://mempool_web/api matches the mempool_web service in compose.base.yml and the pattern used by arkd and fulmine in compose.ark.yml. ✅
• CI workflow ordering: setup-node before start, teardown in if: always() steps, dependent stack torn down before base stack. ✅
• submodules: recursive on checkout — correct for the new git submodule. ✅
• repoRoot() via runtime.Caller(0) — standard Go pattern, never fails for compiled test code. ✅
• Cross-repo impact: None. This PR doesn't change any public API. Other repos (emulator, coinflip, bancod, etc.) still use their own nigiri references independently — they'll migrate separately.

Finding — --confirm is a no-op (low severity)

Makefile:101, test/e2e/utils_test.go:170: Both pass --confirm to regtest.mjs faucet, and the Go code comments say "--confirm mines a block immediately after the send".

However, regtest.mjs's argument parser (parseArgs, line 66) does not recognize --confirm — it falls through to opts.positional.push(a) where it's silently ignored. The faucet() function in lib/chain.mjs:86-93 always calls mine(1) unconditionally.

Net effect: The code works correctly — faucet always confirms. But the --confirm flag does nothing, and the comments claiming it controls mining behavior are misleading. Consider either:

1. Dropping --confirm and updating comments to reflect that faucet always mines, or
2. Adding --confirm support to regtest.mjs if you want opt-in mining in the future.

Not blocking — the behavior is correct as-is.

Note for merge

PR is self-described as blocked on ArkLabsHQ/arkade-regtest#27. The submodule pin (cd47313) must be bumped after that merges. The checklist in the PR description covers this.

---

🤖 Reviewed by Arkana

[arkanaai]

Incremental review (commits 3c9e2ea..027ba72) — ✅ APPROVE

Three new commits since my last review. All infrastructure-only — no protocol-critical changes.

1. Submodule bump to denigiri-regtest (3c9e2ea)

Temporary pin to 20c0851 on the unmerged branch so CI can find regtest.mjs. Fine — this was flagged as a prerequisite in my first review. Remember to re-point to master after ArkLabsHQ/arkade-regtest#27 merges.

2. Startup race fix (a6685b8) ✅

Replaces the fragile sleep 15 with a readiness poll (docker exec solverd-arkd arkd wallet status). Good fix — matches the crash-loop scenario described in the commit message (arkd fatals if arkd-wallet isn't ready).

Also adds REGTEST_PROFILES=base AUTOMINE_INTERVAL=0 to both CI and setup-test-env. Correct — solver runs its own arkd, doesn't need arkade-regtest's ark profile, and wants explicit mining.

Minor nit — Makefile:97-100: The poll loop has no failure path. If all 90 iterations (180s) expire without arkd becoming ready, the script silently falls through to wallet create, which will also fail. Consider adding a timeout exit:

@for i in $$(seq 1 90); do \
    docker exec solverd-arkd arkd wallet status >/dev/null 2>&1 && { echo "solverd-arkd ready"; break; }; \
    [ $$i -eq 90 ] && { echo "ERROR: solverd-arkd not ready after 180s"; exit 1; }; \
    sleep 2; \
done

Not blocking — wallet create failing is a visible enough signal in practice.

3. Version bumps (027ba72) ✅

• nbxplorer 2.5.30 → 2.6.7 — needed for Bitcoin Core 31 compatibility
• arkd/arkd-wallet v0.9.3 → v0.9.6 — aligns with arkade-regtest's base stack

Correct versions. No config schema changes between these versions that would require env var updates.

Previous finding status

My --confirm no-op finding from the first review still applies — low severity, not blocking.

---

🤖 Reviewed by Arkana

[arkanaai]

Incremental review (commits 3c9e2ea..027ba72) — ✅ APPROVE

Three new commits since my last review. All infrastructure-only — no protocol-critical changes.

1. Submodule bump to denigiri-regtest (3c9e2ea)

Temporary pin to 20c0851 on the unmerged branch so CI can find regtest.mjs. Fine — this was flagged as a prerequisite in my first review. Remember to re-point to master after ArkLabsHQ/arkade-regtest#27 merges.

2. Startup race fix (a6685b8) ✅

Replaces the fragile sleep 15 with a readiness poll (docker exec solverd-arkd arkd wallet status). Good fix — matches the crash-loop scenario described in the commit message (arkd fatals if arkd-wallet isn't ready).

Also adds REGTEST_PROFILES=base AUTOMINE_INTERVAL=0 to both CI and setup-test-env. Correct — solver runs its own arkd, doesn't need arkade-regtest's ark profile, and wants explicit mining.

Minor nit — Makefile:97-100: The poll loop has no failure path. If all 90 iterations (180s) expire without arkd becoming ready, the script silently falls through to wallet create, which will also fail. Consider adding a timeout exit:

@for i in $$(seq 1 90); do \
    docker exec solverd-arkd arkd wallet status >/dev/null 2>&1 && { echo "solverd-arkd ready"; break; }; \
    [ $$i -eq 90 ] && { echo "ERROR: solverd-arkd not ready after 180s"; exit 1; }; \
    sleep 2; \
done

Not blocking — wallet create failing is a visible enough signal in practice.

3. Version bumps (027ba72) ✅

• nbxplorer 2.5.30 → 2.6.7 — needed for Bitcoin Core 31 compatibility
• arkd/arkd-wallet v0.9.3 → v0.9.6 — aligns with arkade-regtest's base stack

Correct versions. No config schema changes between these versions that would require env var updates.

Previous finding status

My --confirm no-op finding from the first review still applies — low severity, not blocking.

---

🤖 Reviewed by Arkana