2. Components and state
Chapter 1 started an instance and printed four endpoints. Now we will follow those endpoints inward. Each component owns a different answer.
ths start --native runs Zakura, lightwalletd, and ths-server directly from
a versioned runtime bundle. The same server serves the dashboard and wallet
API. Every native listener binds to 127.0.0.1, and each instance has its own
data directory. The foreground launcher owns the child processes and cleans up
their process groups on exit. Docker startup, described in the diagram below,
uses containers and volumes for those same components.
A block is a unit of chain history. The node tip is Zakura’s latest block height and hash. The mempool holds transactions the node knows about before they are included in a block. A wallet scans chain data for funds it can spend. A wallet can lag the node even when both services are healthy.
thssupervises a Zakura container, a lightwalletd container, and an app container on an instance-specific Docker network.- Zakura owns Regtest blocks, mempool, and JSON-RPC. lightwalletd follows Zakura and serves compact blocks to wallet clients over gRPC.
- The app runs
ths-server. It serves both/api/v1/and the built React dashboard, owns the wallet databases, and uses lightwalletd to scan and broadcast. - A browser or local program reaches only the loopback-published ports.
Internal container listeners can use
0.0.0.0inside the private network; every host-published service binds to127.0.0.1.
The five owners of information
| Component | Owns | Read it through |
|---|---|---|
| Zakura | Canonical chain, block height and hash, mempool, transaction lookup | JSON-RPC or the server’s explorer API |
| lightwalletd | Compact-block index and gRPC stream over the node’s chain | A lightwalletd-compatible wallet client |
Wallet SDK in ths-server | Scanned notes, transparent outputs, and spendable balances in wallet.db | The server’s wallet snapshot and accounts API |
| Server SQLite store | Seed, derived account records, activity, and idempotency keys in ths.db | Server API and local development commands |
| Browser | UI state and a query cache of server responses | Wallet, Explorer, and Network pages |
The app’s wallet and SQLite files share the instance’s wallet volume, but
they answer different questions. wallet.db tells the wallet what it has
scanned and can spend. ths.db records which development request produced a
transaction ID. Activity cannot reconstruct a balance.
- Zakura advances the node tip. lightwalletd indexes compact blocks from that chain.
- The server wallet scans through lightwalletd and compares its checkpoint height and hash with Zakura before publishing a fresh account snapshot. If the chain reorganizes, it rewinds to a common block and scans again.
GET /api/v1/accountsreads the server snapshot. The dashboard’s query hooks fetch that endpoint. Server-sentwallet,chain, andsyncevents tell the hooks to refetch, rather than carrying balances themselves.- SQLite activity records a send or faucet request’s transaction ID and
confirmation status.
GET /api/v1/activityreads it separately.
This ordering explains a common observation: the Network page may show a new
node height while Wallet still shows the last known balances. The wallet must
wait for indexing and scanning, and the server must validate the chain
checkpoint. GET /api/v1/status reports wallet_sync.state as syncing,
ready, or error, along with observed and scanned heights and hashes.
When synchronization fails, the last snapshot may remain visible. Treat it as
stale until the server reaches ready.
Startup and data ownership
The app image first runs init. It creates ths.db, wallet.db, the seed,
six derived account records, and a Regtest Zakura configuration.
- Account 6 is the hidden mining and faucet treasury.
- Accounts 1–5 are exposed as user accounts.
The node mines to the treasury’s transparent address. Normal transparent-output queries cover user accounts; treasury rewards are discovered when a faucet payment needs replenishment.
The instance also has separate chain, lightwalletd, and config
volumes. ths attempts instance-scoped cleanup on shutdown, interruption,
or startup failure. It reports success only after verifying cleanup.
Zakura runs with ZAKURA_STATE__CACHE_DIR=/data, so its state uses the chain
volume mounted at /data instead of the image’s default cache directory.
Recovery records allocation identities as well as resource names. A known original container ID can be checked and removed without adopting a same-name replacement.
For the exact container and endpoint lifecycle, revisit Chapter 1. For the meaning of an account balance, continue to Chapter 3.
Source map: launcher runtime, server startup, wallet snapshot, reconciliation, and dashboard queries.