Skip to content

feat: local spark regtest network - #37

Merged
ovitrif merged 6 commits into
mainfrom
feat/spark-regtest-stack
Nov 9, 2026
Merged

ovitrif merged 6 commits into
mainfrom
feat/spark-regtest-stack

Conversation

@ovitrif

@ovitrif ovitrif commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Refs:

Description

  • Adds an optional spark compose profile, so a local Spark regtest network runs on bitkit-docker's chain for local development, offline E2E runs and emergency-exit tests. Shared CI stays on Lightspark's hosted regtest.
  • Runs three Spark operators, the Spark service provider (SSP) with its Lightning node and a second node (Alice) holding a channel with it, the Breez LNURL and data-sync servers, and mempool.space (frontend and backend) as explorer and chain API.
  • Pins the operators to breez/spark@b54845c, the last public operator, since Breez's current operator image is private. A small patch makes it skip the RETURNED tree node status newer SDKs ask for, without which wallet sync fails.
  • Pins the SSP, Lightning nodes and LNURL server to breez/spark-sdk@7b6124227, the last commit built on that operator (newer SSPs cannot talk to it), with upstream's ce29ca045 backported so the SSP accepts silent_payment_proof, which Spark SDK 0.28 asks for.
  • Adds spark-bitcoind (Bitcoin Core 31.0), peered with the existing bitcoind, since Core 26.0 relays none of Spark's v3 packages with P2A anchors. Both nodes stay on one chain; its miner waits for that chain before mining and tops its wallet up from bitcoind's. The wallet's keys are fixed, so it keeps its coins across ./spark reset.
  • Adds a ./spark CLI: up, down, reset, config, mine, mine-to, mature, send, tx, address, mempool, invoice, pay, and operators stop|start for uncooperative-operator exits.
  • Documents in docs/spark-regtest.md and the README how to start the profile, point Android and iOS dev builds at it, fund wallets and run an exit test.
  • The app build settings it documents, SPARK_LOCAL_CONFIG_B64 and SPARK_LOCAL_CHAIN_URL (dev and regtest builds only), land as small PRs stacked on the Spark PRs above. Until then a dev build needs those two values patched in.
  • The keys in spark-regtest/spark.env and the fixed seeds in compose.yml are upstream's public regtest fixtures from breez/spark-sdk regtest/local (MIT, attributed in spark-regtest/README.md). They hold no value outside this network.

Out of Scope

  • CI: shared CI and staging keep using Lightspark's hosted regtest.
  • Apps: the build settings are separate PRs in bitkit-android and bitkit-ios.
  • Operators: no newer operator until Breez publishes one; newer SDK asks get backported to the SSP as patches.

Design

N/A — no UI changes.

Preview

A Bitkit dev build on Spark SDK 0.28.0, connected to this stack.

Receive over Lightning Pay an invoice Exit, operators stopped
1-receive2x.mp4
2-app-pays2x.mp4
3-exit-operators-down2x.mp4

QA Notes

Journeys

N/A

Manual Tests

  • ./spark up on a fresh project → ready in about 10 minutes: 12,000 keyshares per operator, the SSP's leaf pool stocked, Alice's channel open.
  • Receive over Lightning: ./spark pay <invoice> 100000 to the app's Spending invoice → "Received Instant Bitcoin", 100,000 sats.
  • Pay out of Spark: the app pays ./spark invoice 10000 → "Bitcoin Sent"; Alice lists the payment INBOUND SUCCEEDED, 10,000,000 msat.
  • The operator proxy logs the app's calls with user agent breez-sdk-spark/0.28.0.
  • Emergency exit with all three operators stopped (./spark operators stop, the proxy answers 502):
    • the quote shows 86,016 sats to exit, 8,717 in fees, 15,853 to fund;
    • ./spark send pays the funding address, confirmed in one block;
    • Swipe to exit broadcasts the fan-out (v2), confirmed by ./spark mine;
    • the next block puts 6 node packages in the mempool (v3, zero fee, P2A anchor), read with ./spark mempool and ./spark tx;
    • one more block and the app shows 4/27 steps, "Ready in 13d".
  • spark-bitcoind and bitcoind report the same best block after Spark's blocks.
  • SSP schema check: SDK 0.28's coop-exit query passes with the patch and fails without it (Unknown field "silent_payment_proof").

Automated Checks

N/A

@ovitrif ovitrif self-assigned this Nov 9, 2026
@ovitrif
ovitrif requested review from a team, ben-kaufman and coreyphillips and removed request for a team November 9, 2026 14:32

@talosmachina talosmachina left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 finding (1 P2). Adds an opt-in spark profile: three Spark operators, the SSP with two LDK nodes, LNURL, data-sync, mempool.space and a Core 31 node peered with bitcoind, driven by ./spark. Reviewed 1ec24b9, full tier, static: this PR was not built or run here, since the sandboxed runner could not confirm the author's permission and failed closed.

What I checked, and 4 candidates I ruled out

Read in full: spark, spark-regtest/compose.yml, every script under spark-regtest/scripts/, all four dockerfiles, both patches, both nginx configs, spark.env, docs/spark-regtest.md, the README and docker-compose.yml hunks.
Ran: docker compose config --services with and without --profile spark (the default stack gains no service), and the bind-mount ownership probe behind the finding.
CI: no checks on this branch.

Ruled out

  • Host port collisions: 23049, 23081-23083, 23090 and 23535-23537 are unused by every other service in docker-compose.yml; 60401 and the ZMQ ports stay unpublished.
  • Unauthenticated SSP internal API: 59050 is not published, only 59049.
  • Fork of the shared chain: miner.sh waits in wait_for_chain_sync for a peer and for bitcoind's height before mining.
  • bitcoind RPC from spark containers: polaruser/polarpass match the rpcauth line and ./bitcoin-cli.
  • Cold reader: a second model tried to refute the finding and reproduced it instead (rootful Docker, Compose v5.6.1).

Merge confidence: 4/5, one P2 on Linux hosts only, and the stack was not exercised here.

Comment thread spark Resolved

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two independent reviews.

needs changing before merge

  • Reset eventually exhausts funding on the retained chain (spark:89-90)

worth doing, does not block

  • Underfunded miner wallet stalls setup silently, and the suggested fix fails (spark-regtest/scripts/miner.sh:42-58)
  • ./spark up shows no progress while the operators generate keys (spark:66-75)
  • The chain API wait bypasses the startup timeout (spark-regtest/scripts/ready.sh:91-92)
  • App setup omits the required companion patches (README.md:692)

nits

  • Docs say ./spark reset issues a new config, but the config is fixed (docs/spark-regtest.md:75)
  • spark.env keeps upstream's nix comment and an unused DATA_SYNC_VERSION (spark-regtest/spark.env:4-6)

Comment thread spark-regtest/scripts/miner.sh Resolved
Comment thread spark Resolved
Comment thread docs/spark-regtest.md Resolved
Comment thread spark-regtest/spark.env Resolved
Comment thread spark Resolved
Comment thread spark-regtest/scripts/ready.sh Resolved
Comment thread README.md Resolved

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rechecked after 1 new commit (7c57263). Nothing blocking remains.

addressed

  • Underfunded miner wallet stalls setup silently, and the suggested fix fails (spark-regtest/scripts/miner.sh:42-58). Fixed: ready.sh:48-52 now reports when the wallet holds under 1 BTC. A stubbed run printed it at 0.5 BTC and showed the pool count at 5 BTC. miner.sh:56-58 now gives a recovery that works instead of ./bitcoin-cli fund, and the fixed keys in lib.sh:58-73 keep the early coinbases across a reset.
  • ./spark up shows no progress while the operators generate keys (spark:66-75). Fixed: spark:67-78 now builds, starts spark-ready alone, follows its log, then runs up -d for the rest. I replayed that order in a scratch project where a dependency turns healthy after 12 s. The progress lines streamed during the 15 s that up -d blocked.
  • Docs say ./spark reset issues a new config, but the config is fixed (docs/spark-regtest.md:75). Fixed: docs/spark-regtest.md:82-83 now says the config is built from fixed keys and stays the same across ./spark reset unless SPARK_PUBLIC_HOST changes, which matches init.sh.
  • spark.env keeps upstream's nix comment and an unused DATA_SYNC_VERSION (spark-regtest/spark.env:4-6). Fixed: The nix comment and DATA_SYNC_VERSION are gone (grep finds neither), and spark.env:4 now says the keys are repeated in compose.yml. If you want one copy later, an include: entry in docker-compose.yml can take env_file: spark-regtest/spark.env for interpolation, so the inline keys could become ${...} references.
  • Reset eventually exhausts funding on the retained chain (spark:89-90). Fixed: lib.sh:58-73 imports fixed descriptors from SPARK_WALLET_TPRV (spark.env:8) with timestamp: 0. The tprv's checksum is valid and it derives from 32 bytes of 0x07. On a scratch Core 31 node I ran ensure_wallet, mined 200 blocks to it and spent 4,000 BTC, then deleted the wallet directory and ran ensure_wallet again. The balance came back the same, change included: 1049.99994439 BTC.
  • The chain API wait bypasses the startup timeout (spark-regtest/scripts/ready.sh:91-92). Fixed: ready.sh:97-103 now checks the readiness deadline inside the chain API wait. A stubbed run with both markers present, a failing chain-tip endpoint and READY_TIMEOUT_SECONDS=2 exited 1 after 3 s with "the chain API (...) is behind the chain".
  • App setup omits the required companion patches (README.md:692). Fixed: README.md:692 and docs/spark-regtest.md:67-72 now say the apps read these settings only once the settings changes land on bitkit-android#1697 and bitkit-ios#1128. They also say what a dev build needs patched in until then. This comes before the funding and exit steps, and the README anchor resolves to that section.

new since the last review

worth doing, does not block

  • An interrupted key import leaves a blank wallet that crash-loops spark-miner (spark-regtest/scripts/lib.sh:60-72)

Comment thread spark-regtest/scripts/lib.sh Resolved
@ovitrif
ovitrif requested a review from coreyphillips November 9, 2026 15:54

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rechecked after 1 new commit (27153f8). Nothing blocking remains.

addressed

  • An interrupted key import leaves a blank wallet that crash-loops spark-miner (spark-regtest/scripts/lib.sh:60-72). Fixed: spark-regtest/scripts/lib.sh:60-64 now creates or loads default, then skips the import only when listdescriptors returns descriptors. I tested it on a scratch Core 31 regtest node. With a blank default either loaded or only on disk, ensure_wallet imported both descriptors, the 2,500 BTC balance came back, and getnewaddress worked. A rerun skipped the import. The crash loop is gone. The rescan-phase gap is filed separately as a new finding.

new since the last review

worth doing, does not block

  • A rescan cut short after the import leaves the wallet permanently short of coins (spark-regtest/scripts/lib.sh:63-64)

Comment thread spark-regtest/scripts/lib.sh Resolved
@ovitrif
ovitrif requested a review from coreyphillips November 9, 2026 16:07

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rechecked after 1 new commit (5ef4f09). Nothing blocking remains.

addressed

  • A rescan cut short after the import leaves the wallet permanently short of coins (spark-regtest/scripts/lib.sh:63-64). Fixed: spark-regtest/scripts/lib.sh:76-77 now runs rescanblockchain 0 on every start, whether or not the descriptors already exist. I ran the branch's ensure_wallet against a scratch Core 31 node with 3,150 blocks paying the fixed keys (14,949.98 BTC). After a docker stop during the import's scan, the reloaded wallet held 1,850 BTC, and the next ensure_wallet brought it back to 14,949.98 BTC. A stop during rescanblockchain, and an abortrescan, both made the call fail with Rescan aborted. and exit 1, so under set -e the miner exits and its restart rescans. With the tip three days past the coinbases, rescanblockchain 0 still found them, even though the import timestamp is now.

new since the last review

nits

  • The import with timestamp "now" still scans the chain before the full rescan (spark-regtest/scripts/lib.sh:71)

Comment thread spark-regtest/scripts/lib.sh Resolved
@ovitrif

ovitrif commented Nov 9, 2026

Copy link
Copy Markdown
Collaborator Author

Merged: approved by @coreyphillips on 5ef4f09, every review thread answered, no required checks on this repository.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants