Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

The web and server sources build the app image, the lightwalletd Dockerfile builds the lightwalletd image, and Zakura is pinned and pulled. ths start refuses to run until all three exist. Editing source changes neither a running container nor an existing image.

  1. web/ and crates/ths-server/ go into the app image. The app serves both the built React dashboard and HTTP API.
  2. The build command also prepares the lightwalletd runtime image and ensures the pinned Zakura image is present.
  3. start creates 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

NeedStart reading
Launcher commands and flagscrates/ths-cli/src/args.rs and commands.rs
Docker ports, instance startup and cleanupcrates/ths-cli/src/runtime/, starting with instance.rs, startup.rs, and cleanup.rs
Server routescrates/ths-server/src/api.rs
Payment and mine handlerscrates/ths-server/src/api/payments.rs and api/mining.rs
Payment progression, confirmation, and treasury replenishmentcrates/ths-server/src/payments/
Wallet snapshot and sync statuscrates/ths-server/src/state.rs and sync.rs
User accounts, treasury boundary, activity and keyscrates/ths-server/src/db.rs and db/
Wallet scan, transaction construction, spendabilitycrates/ths-server/src/wallet.rs and wallet/payments.rs
Canonical checkpoint and reorganization handlingcrates/ths-server/src/reconcile.rs
Dashboard requests, schemas, and query invalidationweb/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.