Appendix B: Develop from source
The teaching chapters use an installed ths launcher. For changes to this
repository, the crucial rule is that ths starts Docker images. Editing
Rust or React source does not change a running container or an already-built
image.
web/andcrates/ths-server/go into the app image. The app serves both the built React dashboard and HTTP API.- The build command also prepares the lightwalletd runtime image and ensures the pinned Zakura image is present.
startcreates a fresh instance from those images. A source edit needs another image build and a new instance before the normal dashboard shows it.
Build and start
Use Rust 1.98, Node 24, and a running Docker daemon. Run these from the repository root of the recorded main checkout:
npm ci --prefix web
cargo run -p thus-spoke-zakura -- build --dev
cargo run -p thus-spoke-zakura -- start
The Cargo package is thus-spoke-zakura; ths is its binary name. The
first command installs the dashboard’s locked dependencies. The second
builds runtime images, keeping workspace Rust code unoptimized for faster
development builds. The last launches the default instance in the
foreground. With no subcommand, the source launcher starts the same
environment.
Keep the launch terminal open. Ctrl+C triggers instance-scoped cleanup,
as explained in Chapter 1. After changing
crates/ths-server or web/, rerun:
cargo run -p thus-spoke-zakura -- build --dev
Then start a new instance. build without --dev produces
release-optimized images. start requires the matching images already
present; it does not fetch or rebuild them.
Run a test against a disposable instance
Once the matching runtime images exist, the source launcher can run a child command against a settled, fresh environment:
cargo run -p thus-spoke-zakura -- run --timeout 180 -- sh -c 'curl -fsS "$THS_API_URL/api/v1/accounts"'
The child receives the instance’s THS_* endpoint variables, and the launcher
attempts instance-scoped cleanup after it exits. The timeout covers startup
and settlement, not the child runtime. Use non-interactive commands. The
CLI reference covers collision rules, interruption, and retained
recovery metadata. To wait for an instance already started in another terminal,
use cargo run -p thus-spoke-zakura -- --name alice wait --timeout 180.
Native runtime (no Docker)
The Rust launcher runs Zakura, lightwalletd, and ths-server as local processes.
The installed native bundle contains compatible pinned binaries and the built
web dashboard; Python and Docker are not runtime dependencies. Native support
covers macOS and Linux on x86_64 and aarch64. macOS uses its system
/usr/sbin/lsof to prove listener ownership; Linux reads procfs directly.
For source development, build a matching bundle using the release packaging
instructions in RELEASING.md. Pass the bundle directory with
--runtime-dir or THS_RUNTIME_DIR. The directory must contain manifest.json,
bin/zakurad, bin/lightwalletd, bin/ths-server, and web/index.html.
The launcher checks the manifest’s platform, launcher version and component pins
before creating an instance. Rebuild ths-server and the dashboard when changing
those sources, then recreate the bundle.
cargo run -p thus-spoke-zakura -- doctor --native --runtime-dir /path/to/ths-runtime
cargo run -p thus-spoke-zakura -- --name native start --native --runtime-dir /path/to/ths-runtime --no-open
cargo run -p thus-spoke-zakura -- run --native --runtime-dir /path/to/ths-runtime --timeout 180 -- node tests/native_smoke.mjs
cargo test -p thus-spoke-zakura --test native_runtime
The Rust lifecycle regressions use compiled disposable service fixtures and run on Linux and macOS in CI without Docker or a real node. The Node smoke test uses real services and checks funding, mining, a shielded payment, idempotent replay, reorganization and rollback. It uses the runner’s default automatic mining.
Each start reserves a fresh name under the usual launcher ownership lock and
creates private instance state. Ports are reserved on loopback during
initialization. The node uses the legacy TCP peer stack, disabling its separate
QUIC listener; lightwalletd metrics bind to 127.0.0.1:0. Services receive a
minimal environment, with no inherited proxies, backend addresses or config.
The native initializer emits loopback addresses directly from typed port/path
options. After each port handoff, the launcher verifies that the actual child
owns the listener before contacting it, checks the exact Regtest genesis, and
checks the server’s instance identity and Regtest network before reporting ready.
Native startup includes wallet settlement. Its timeout is one absolute budget,
including HTTP bodies that arrive slowly. The normal endpoints, status,
list, wait, logs, stop, reset, mine, rpc, and wallet commands work
with native instances. Native state explicitly records its backend; old state
without a backend remains Docker state. Services exiting unexpectedly stop the
application, and cancellation, partial startup, and normal application exit
clean up owned process groups, including initializer/application descendants.
SIGINT, SIGTERM, and SIGHUP delete instance state once cleanup is verified,
including interruption during initialization, so the same name can be reused.
Other failures retain state and logs for inspection; stop deletes that state
after cleanup has been verified. The lifecycle regressions check signal cleanup,
closed listeners, name reuse, and preservation of another running instance.
A launcher killed with SIGKILL cannot verify cleanup. stop then retains its
state and reports uncertainty rather than signaling possibly reused persisted
PIDs. Inspect and stop the abandoned processes manually before removing that
instance directory. A child that deliberately leaves its process group escapes
group cleanup; native services must remain foreground processes. Native run
forwards interruption to the application group and returns a failure, including
when another shell requests stop. No other instance’s directory or process
is removed.
Find the part you need to change
| Need | Start reading |
|---|---|
| Launcher commands and flags | crates/ths-cli/src/args.rs and commands.rs |
| Docker ports, instance startup and cleanup | crates/ths-cli/src/runtime/, starting with instance.rs, startup.rs, and cleanup.rs |
| Server routes | crates/ths-server/src/api.rs |
| Payment and mine handlers | crates/ths-server/src/api/payments.rs and api/mining.rs |
| Payment progression, confirmation, and treasury replenishment | crates/ths-server/src/payments/ |
| Wallet snapshot and sync status | crates/ths-server/src/state.rs and sync.rs |
| User accounts, treasury boundary, activity and keys | crates/ths-server/src/db.rs and db/ |
| Wallet scan, transaction construction, spendability | crates/ths-server/src/wallet.rs and wallet/payments.rs |
| Canonical checkpoint and reorganization handling | crates/ths-server/src/reconcile.rs |
| Dashboard requests, schemas, and query invalidation | web/src/lib/api/ and web/src/hooks/ |
Follow one request across boundaries before changing behavior: a
dashboard action calls an API route, the server may change wallet or
chain state, then events trigger query refetches. Chapters 2–6
explain why these owners are separate. Keep host-published ports on
127.0.0.1 and Account 6 out of user-facing lists.
Iterate on the frontend
For a React-only change, build and start the runtime once. In a second terminal, start Vite:
npm run dev --prefix web
Vite proxies to the default dashboard port, 32805. For a
--port-offset instance, set THS_DEV_API to its URL (here alice):
THS_DEV_API="$(cargo run -q -p thus-spoke-zakura -- --name alice endpoints --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["dashboard"])')" npm run dev --prefix web
Vite proxies API calls to that running app. A frontend edit appears in
the Vite page immediately. Rebuild the app image before checking it in
the normal ths dashboard.
Run the relevant checks
The public website and this book deploy together on pushes to main, at
https://ths.zypherpunk.xyz/ and https://ths.zypherpunk.xyz/book/.
The Deploy website and book workflow also builds pull requests without
deploying them. Automatic runs are limited to changes in the website, book,
theme, and their build, validation, and deployment files; manual runs remain
available. For the Vercel project settings, GitHub Actions credentials,
and a local preview of the combined site, see the
website deployment instructions.
After changing crates/:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
cargo test -p thus-spoke-zakura --features release-distribution
After changing web/ (with Node 24):
npm run lint --prefix web
npm run format:check --prefix web
npm test --prefix web
npm run build --prefix web
The normal cargo test --workspace run needs no Docker. Ignored live
regressions use the Docker lifecycle and
activity-recovery setups below.
For contribution and pull-request policy, see
CONTRIBUTING.md.
For release images and publication, see
RELEASING.md.
For operational symptoms, turn to Appendix C:
Troubleshooting.
Docker lifecycle regressions
These ignored launcher tests need a disposable Docker daemon. The lost-create
and lost-start cases also need prepared runtime images. List the cases, then
run the one you need with --ignored --exact:
cargo test -p thus-spoke-zakura runtime::docker_lifecycle_tests:: -- --ignored --list
cargo test -p thus-spoke-zakura runtime::docker_lifecycle_tests::lost_start_reply_is_cleaned_up_and_can_be_retried -- --ignored --exact
The launcher allows 120 seconds per readiness phase, 30 seconds for ordinary
Docker startup commands, 120 seconds for attached initialization, and a separate
120 seconds for cleanup. A killed Docker client may leave a mutation running in
the daemon. Cleanup checks resource identity and never adopts a same-name
replacement or removes another instance’s resources. Only one start or run
owns a name at a time; stop and reset --force ask that launcher to shut down
and wait for verified cleanup. Shutdown requests are tied to its session, so an
old request cannot stop a later launch.
Activity-recovery integration test
Run from the repository root with Rust 1.98.0, Docker, network access, and enough resources for the pinned images and real Ironwood proofs. The first two Cargo commands compile the test and run its Docker-free helpers. List the ignored cases, then run one at a time:
cargo test --locked --profile dev-runtime -p ths-server --test activity_recovery --no-run
cargo test --locked --profile dev-runtime -p ths-server --test activity_recovery
docker pull zakuracore/zakura:1.7.0
docker build -f docker/lightwalletd.Dockerfile -t ths-recovery-lightwalletd:local .
cargo test --locked --profile dev-runtime -p ths-server --test activity_recovery -- --ignored --list
cargo test --locked --profile dev-runtime -p ths-server --test activity_recovery -- --ignored --exact broadcast_recovers_after_auto_mine_failure
cargo test --locked --profile dev-runtime -p ths-server --test activity_recovery -- --ignored --exact reorg_and_rollback_preserve_canonical_wallet_and_payment_state
cargo test --locked --profile dev-runtime -p ths-server --test activity_recovery -- --ignored --exact dependent_payments_resume_in_admission_order_after_restart --nocapture
cargo test --locked --profile dev-runtime -p ths-server --test activity_recovery -- --ignored --exact external_transparent_spend_reconciles_after_restart
Linux CI runs reorg/rollback, broadcast recovery, concurrent sends, address-faucet restart
recovery, and queued-response cases on every push and PR. The other cases in
tests/activity_recovery.rs cover startup funding, pool transfers, and
external faucets. The fixture owns and cleans up only its own Docker resources;
it fails on a timeout or incomplete cleanup.
The dependent-payment case seeds a retained Faucet→Send→Send chain while the server is stopped, with reversed IDs and tied timestamps. Restart must confirm all three original operations without another submission. Controlled automatic mining failures first keep the funder in the mempool; both dependents must attempt preparation and remain pending for insufficient funds. The fixture restarts, mines the original funder, and allows progression again. It checks actual chain inclusion and wallet balances, then restarts again and replays each key to verify unchanged identities, journals, balances, and chain tip.
The reorg/rollback regression observes the server’s SendTransaction calls
through the existing gRPC proxy to check that rollback, idempotent replay, and
restart do not rebroadcast orphaned payments. Mempool absence is not that proof:
Zakura’s own RPC retry queue can re-admit an earlier submission even while the
server is stopped. Canonical inclusion, balances, signed bytes, payment identity,
and the reconciled wallet checkpoint are checked separately.