6. Uncertain operations
The previous chapter showed that a block can be generated before the wallet publishes a new snapshot. A payment has a similar boundary: accepting the POST records a claim, and background work later prepares, broadcasts, and confirms it. This chapter names each state and tells you what an HTTP response can and cannot prove.
The terms are deliberately narrow:
- Broadcast means lightwalletd accepted the transaction for submission. It does not mean the transaction is in a block.
- Activity is the server’s SQLite record of a development payment. It
includes a transaction ID (
txid),status, and optionalblock_hash. - Confirmed activity means Zakura reported the transaction in a block when the server last checked it, and SQLite stored that block hash. The status is a record of that check, not a live proof of canonical inclusion.
- An idempotency key is a caller-chosen string used to look up an already-recorded payment. It is not an end-to-end exactly-once guarantee.
Payment submission and confirmation
POST /api/v1/sendvalidates user account IDs (1–5), source and destination pools, amount, memo rules, and anidempotency_keyof 8–128 visible ASCII characters. Same-account sends are allowed when the pools differ. A recipient can also be a Regtest address matching the destination pool.POST /api/v1/faucetvalidates its user account, pool, amount greater than zero and at most 5 ZEC, and key. Validation happens before the recorded-key lookup.- The handler then returns the stored claim. If SQLite already has one for
the key, that recorded payment is the body. The handler compares the
replay’s details, including the memo, with the original intent; changed
valid details return HTTP 409. A new intent and key are inserted as
preparingand returned in the same way. This response admits the claim. Preparation, broadcast, and confirmation continue in the background. - Pending statuses
preparing,prepared, andbroadcastreturn HTTP 202 with a relativeLocationheader. For a send or account faucet the header is/api/v1/activity?idempotency_key=<key>; for an address faucet it is/api/v1/faucet/address?idempotency_key=<key>. Resolve that path and query against the dashboard origin. A new claim ispreparing, sotxidis empty. A later replay whose stored status isconfirmedorfailedreturns HTTP 200. That code covers both outcomes; readstatus. - Background work progresses an unresolved claim. It synchronizes the
wallet. The SDK chooses spendable funds and a fee, constructs the
transaction, and saves it in the wallet. The server saves its txid and
transaction bytes as
preparedbefore broadcast. For faucet payments, the source is hidden treasury Account 6; it may replenish itself first. - Background work submits the saved transaction through lightwalletd and
marks it
broadcast. If the node already knows the txid, it continues with that transaction. It then asks Zakura whether the transaction is confirmed. If needed, it mines one block, waits for wallet reconciliation, and asks again. Success storesconfirmedactivity with a block hash. If auto-mining fails, the activity can remainbroadcast, with the txid and no block hash. Later blocks and background checks can confirm recorded account activity independently of wallet synchronization. Background work moves the payment forward; another POST is not required.
The important ordering is record intent → save transaction → broadcast. The POST returns after the intent is recorded. Send, account faucet, and address faucet reject transparent outputs below 54 zatoshi with HTTP 400 before recording a claim. Smaller positive shielded amounts remain valid. Concurrent requests with the same key share the recorded intent. Background submission of unresolved payments is serialized. Saved payments continue across a server restart while the instance’s databases remain intact. This is not an end-to-end exactly-once guarantee: a fresh key requests a new payment, and deleting the instance deletes its recovery records.
Spending newly confirmed Ironwood
A newly confirmed Ironwood output may need another block before it can be spent.
Automatic Sends mine at most one prerequisite block and retry once. In manual
or mempool mode, use ths mine 1; interval mode supplies the next block on its
schedule. While waiting, the operation stays preparing with its original key.
New ordinary NU7 payments expire 120 blocks after their candidate inclusion height.
HTTP admission and status
POST /api/v1/send, POST /api/v1/faucet, and
POST /api/v1/faucet/address save an intent before processing it. The response
is HTTP 202 while the payment is pending, or 200 when its stored status
is confirmed or failed. Both include the operation and a relative
Location with the encoded idempotency key.
Neither status code alone proves the payment succeeded: inspect the operation’s
status. Follow Location with GET to check a pending payment. The server
keeps working if the caller disconnects and resumes saved payments after a
restart. Status reads do not start payment work.
preparing, prepared, and broadcast are pending. Only confirmed and
failed are terminal. A pending operation can have an empty txid. A
last_error can describe a retryable failure and clears when processing
continues. Keep the same key after a timeout. Reusing it with different
payment details is rejected.
Earlier payments and dependent sends
The worker visits account payments in their stored admission order, including retained legacy transactions. Their random IDs and timestamp ties do not set that order. It keeps its position across bounded passes and alternates with external-address faucets so one slow collection does not always go first.
Admission order is not a promise that every earlier payment has finished. A
pass can stop while an earlier payment is still pending. If a Send then has
insufficient funds, it stays preparing while an earlier active payment
could fund its source account and pool, including Ironwood change from an
earlier spend. It keeps its original key and can progress after that payment
confirms. An unrelated payment, a payment accepted later, or a terminal
payment does not defer this failure. An earlier unconfirmed payment is
observation-only after a deliberate reorg or rollback, so it does not defer
an unfunded Send either, even before its transaction expires. Only
preparing, prepared, and broadcast payments are active funding
dependencies. The orphaned payment keeps its original status and key for
observation; this does not rebroadcast or fail it. Once no earlier funding
dependency remains, the existing transaction-reconciliation checks still decide whether
insufficient funds can safely become terminal failed.
Call the API with a deliberate key
This example uses integer zatoshi. Run it against the live dashboard URL of the same instance you used in earlier chapters:
DASHBOARD_URL="$(ths endpoints --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["dashboard"])')"
curl -fsS "$DASHBOARD_URL/api/v1/send" \
-H 'content-type: application/json' \
--data '{"from_account":1,"to_account":2,"source_pool":"ironwood","destination_pool":"ironwood","amount_zatoshi":100000000,"idempotency_key":"book-account-1-to-2-v1"}'
The response is one payment-journal activity object. A keyed
GET /api/v1/activity?idempotency_key=<key> returns that same object in a
one-item list:
| Field | Meaning |
|---|---|
id | The activity row’s own UUID. Not the idempotency key and not the txid. |
kind | send or faucet. |
from_account | Source account 1–5, or null for a faucet payment out of the hidden treasury. |
to_account | Destination account 1–5, or null for an external send. |
to_address | External send destination, or null for an account recipient. |
source_pool | ironwood or transparent. |
destination_pool | ironwood or transparent. |
amount_zatoshi | Integer zatoshi paid to the destination. It does not include the fee. |
txid | The prepared transaction’s ID; empty while status is preparing. |
block_hash | The confirming block’s hash, or null before confirmation. |
status | preparing, prepared, broadcast, confirmed, unconfirmed after a deliberate reorg/rollback, or a stored terminal failed result. |
created_at | When the row was inserted, as YYYY-MM-DD HH:MM:SS UTC, including in the initial accepted response. |
last_error | Stored diagnostic, or null. |
An unkeyed GET /api/v1/activity returns unified wallet history. It merges
these journal records with transactions observed by the wallet and adds chain
metadata, memos, recipient and pool lists, and from_accounts and
to_accounts. The arrays preserve every affected development account;
from_account and to_account are only populated when their corresponding
array contains exactly one account. A transaction appears once even when it
affects multiple development accounts. Outputs to the hidden treasury account
are excluded from the user-facing amount, recipients, and account lists.
A faucet payment to an address outside accounts 1–5 appears the same way: its
own entry, kind faucet, to_address set, and both account arrays empty.
It carries no idempotency key, so it is not reachable through the keyed
lookup above; read GET /api/v1/faucet/address?idempotency_key=<key> for
that. destination_pool is null for the rare address shape the faucet
accepts but cannot resolve to a pool.
The unkeyed list accepts limit (default 30, maximum 100), account (1–5),
kind (send, faucet, or transaction), and status filters. Filters
combine and are applied before the limit. To read the next older page, pass the
last returned activity’s id as before; for example,
GET /api/v1/activity?account=2&limit=30&before=<activity-id>. The response
remains a JSON array. X-THS-Has-More is true only when an older matching row
exists after the returned page. The server records an immutable first-seen
sequence for each activity identity and orders every later page by that
sequence. Preparation, confirmation, rollback, and reorg therefore cannot move
a row across an existing cursor boundary. If the cursor activity disappears or
no longer belongs to the filtered list, the server returns 409 with activity cursor is stale; reload from the first page. Start again without before. The
keyed idempotency_key lookup remains a separate exact journal lookup and
ignores list filters.
amount_zatoshi remains the value paid to the relevant user or external
recipient. Canonical wallet entries additionally expose the aggregate effects
across development accounts 1–5 as received_zatoshi, spent_zatoshi, and the
signed net_zatoshi. These totals include wallet change and transaction fees,
but exclude treasury account 6. Journal-only pending or failed entries set all
three effect fields to null because their final wallet effects are not yet
known.
When a transaction uses more than one pool, source_pool or
destination_pool is null and the corresponding source_pools or
destination_pools array preserves every known pool.
For external incoming transactions, transparent-source detection requires a Zakura transaction lookup. These lookups run concurrently within one short, shared budget after filtering and pagination, so only entries in the returned page are enriched. They fail open: if Zakura is slow or unavailable, activity still returns and the unknown source pool remains absent.
Activity listing also separates page selection from wallet-detail loading. It
first combines lightweight journal and wallet identities, applies filters and
the stable first-seen cursor, and selects limit + 1 candidates. The extra
candidate determines whether another page exists; full amounts, memos, pools,
and recipients are loaded only for the limit entries returned to the client.
For the keyed payment-journal object, read txid, status, and block_hash
first; do not infer confirmation merely because HTTP returned 200. That object
does not expose a memo field. The supplied memo is stored with the payment
intent to compare replays. Unkeyed unified history exposes decoded received
text memos in its memos array when transaction enhancement recovers them.
Keep this key only for this intended payment. If the server has recorded it,
repeating the same direct API request with the same key retrieves or
finishes that activity.
Resume a faucet payment after a lost response
-
Get the dashboard URL for your instance as shown above. Choose a key for this one-ZEC payment to Account 2 and keep the exact request:
curl -i "$DASHBOARD_URL/api/v1/faucet" \ -H 'content-type: application/json' \ --data '{"account_id":2,"pool":"ironwood","amount_zatoshi":100000000,"idempotency_key":"book-faucet-account-2-v1"}' -
If the response is lost, repeat that same request against the same instance. The key identifies this payment; a new key requests another one.
-
GET the returned
Locationuntil the stored status isconfirmedorfailed. For this example, that is:curl -fsS "$DASHBOARD_URL/api/v1/activity?idempotency_key=book-faucet-account-2-v1"The response is a one-item array. A mined block alone does not prove this payment was confirmed.
Which caller are you retrying?
| Caller | How to recover the same payment |
|---|---|
| Direct API | Repeat the identical request with the saved key and details. The replay returns the recorded outcome and leaves confirmation to background work. A new key requests a new payment. |
| Dashboard Send or Faucet | Pending payments retain their key and exact details across dialog closure, refresh, and browser restart. Use Resume for the saved payment. A broadcast response does not clear it; terminal confirmed or failed results release the retained identity. |
| CLI send, shield, unshield, or faucet | Rerun the same arguments against the same instance. The local payment journal retains keys across errors and pending results; an identical command after successful terminal-result output starts a new payment. |
Send and faucet commands retain their retry keys if a stdout result write returns an error. Fix the output destination and rerun the same arguments against the same instance to recover that payment. For an account faucet batch, every key stays retained until all members are terminal and the batch output succeeds. A successfully reported terminal failure also releases its key; a later invocation may request another payment. This covers reported write errors, not a guarantee that a downstream program consumed buffered output.
The dashboard reads retained payment outcomes separately from wallet balances. A confirmation can appear before the wallet snapshot catches up. A partial CLI account-faucet batch retains its keys until every member has a terminal result; keep the same account selection when retrying it.
Decide what to do after a lost response
- Save any transaction ID or response you did receive. Query Recent
activity or
GET /api/v1/activity, then inspect Zakura’s transaction and chain state if you have a txid. With a saved key,GET /api/v1/activity?idempotency_key=<key>reads that payment’s stored activity, returning a one-item array or[]. - If the matching activity is recorded, use its status. Background work
moves an unresolved payment through preparation, broadcast, and
confirmation. A
broadcastactivity may becomeconfirmedafter another block and those checks. Repeating the same POST returns the outcome already recorded. HTTP 200 on that terminal replay covers bothconfirmedandfailed; inspectstatus. The replay does not need to drive confirmation. - If no matching activity appears, you cannot conclude that nothing was broadcast. Confirm that you are querying the same instance and retain the original key and details. Background work can continue the saved payment even when no transaction ID was returned to you; do not replace the key merely because the response was lost.
ths faucet <ADDRESS>callsPOST /api/v1/faucet/addresswith a journaled idempotency key. A recognized user account appears in activity under that account; an external destination appears as its own faucet entry, with no account and no idempotency key exposed. Either way, readGET /api/v1/faucet/address?idempotency_key=<key>; that lookup is read-only and does not start payment work. Replaying the original request returns that recorded result.
The server validates key syntax and compares recorded payment intents;
those checks are useful, but their boundary matters. Never reuse a key for
a different amount or recipient. Do not reconstruct a balance by summing
activity records; use GET /api/v1/accounts after wallet sync.
ths reorg and ths rollback clear affected confirmations in activity and
external faucet records, marking them unconfirmed while preserving the original
transaction, request, and key. Background handling only observes these payments;
it does not rebroadcast, replace, or auto-mine them. Replays return that same
unconfirmed request. A later canonical confirmation restores confirmed with
its new block hash.
An external chain reorganization can replace the block named by a previously confirmed
activity. The server reconciles wallet balances against the new canonical
chain, but it does not recheck activity already marked confirmed. If
current inclusion matters, query Zakura for the transaction and compare its
block hash with the current chain. Treat the stored activity status as the
result of its earlier confirmation check.
Mining has a different retry boundary
POST /api/v1/mine validates a count of 1–10,000 and starts a server-owned
job. It generates blocks, reads the mined tip, reconciles the wallet, notifies
dashboards, and returns blocks plus hashes. If a later step errors,
blocks may already exist, even though the request has no success response.
A lost connection does not cancel admitted work. Each legacy API request uses
a fresh internal key and can request additional mining.
The dashboard and ths mine use POST /api/v1/mining/jobs with a caller key
and receive an accepted job before completion. Replaying the same accepted
key and count returns that job within the server’s lifetime. After a lost response, read
GET /api/v1/mining/jobs to inspect the latest job before requesting more.
The CLI saves its key before submission and retains it after an uncertain
response, interruption, or polling timeout. Rerun ths mine with the same
block count against the same instance to resume the saved job. After the CLI
observes a finished job, it clears the key; the next invocation starts new
mining. Jobs are not recovered after a server restart.
After a timeout, compare the current node height and tip hash with
what you observed before the request. Use Network, GET /api/v1/status,
or Zakura RPC. Another process can also mine or reorganize a local chain,
so that observation guides a human decision but is not an exactly-once
receipt. Chapter 5 traces the full wallet catch-up.
Source map: API handlers, payment progression, SQLite activity and keys, wallet payments, and chain reconciliation.