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

Thus Spoke Zakura

Thus Spoke Zakura (ths) gives you a disposable Zcash Regtest network on your own machine. You can mine blocks, fund development accounts, send test ZEC, inspect transactions, and connect another application. The launcher runs Zakura, lightwalletd, and a wallet-backed dashboard in Docker. Every host-published endpoint stays on 127.0.0.1.

This book teaches why each part exists and what happens when you use it. The chapters build on one another. The ths CLI reference, development guide, and troubleshooting guide are there when you need a particular command or diagnosis.

Who this book is for

You should be comfortable running terminal commands and reading a small HTTP example. You do not need prior Zcash knowledge. We define Regtest, blocks, accounts, pools, notes, and wallet synchronization before relying on them.

Everything here is local development infrastructure. Regtest coins and keys have no value on mainnet or testnet — and the keys are not secret either. The seed is a fixed constant in the source, so every instance on every machine derives the same accounts, and anyone who knows this project can derive them too. That reproducibility is the point; it is also why nothing of value may ever touch an address shown by this environment.

Use the installer as the default setup path. The installer downloads a published release. Use the source build instructions to run the recorded source baseline.

One experiment, several chapters

We will start the default instance, look at its five user accounts, fund Account 2, send from Account 1 to Account 2, mine another block, and read the result through the API. Along the way, we will answer three questions:

  1. Who owns this fact? Zakura owns the chain, lightwalletd indexes it, the wallet owns spendable balances, and SQLite records development activity.
  2. When is it true? A block can exist before lightwalletd indexes it, and the index can advance before the wallet publishes a fresh balance snapshot.
  3. What can be retried? The caller and operation determine which identity to retain and which state to inspect after an uncertain response. Chapter 6 traces those boundaries.

Those distinctions explain most surprising behavior in the dashboard.

How to read

Read Chapter 1: Your first instance if you want to work along. Chapter 2 defines the components; Chapter 3 defines wallet state; Chapter 4 moves funds; Chapter 5 follows a block into the wallet; Chapter 6 deals with uncertain responses; and Chapter 7 connects your code.

A chapter starts with the idea, traces the flow, then gives a concrete action and what you should observe. Diagrams have text explanations beside them so the sequence still works without images.

Four terms to keep separate

TermIn this book
InstanceOne named set of Regtest containers, network, volumes, ports, and disposable data controlled by ths.
Node tipZakura’s latest block height and hash. A height alone does not identify a block after a reorganization.
Wallet snapshotThe server’s last reconciled view of user-account balances. The dashboard reads this through the accounts API.
ActivityA SQLite record of a faucet or send request, its transaction ID, and its confirmation status. It is not a balance ledger.

Next: start a fresh instance.