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

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 optional block_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

A validated payment is durably claimed as preparing, and the POST returns that stored claim. Background work saves prepared transaction bytes before broadcast, then checks confirmation. An identical key returns the recorded outcome and leaves confirmation to background work; changed details or memo conflict.

  1. POST /api/v1/send validates user account IDs (1–5), source and destination pools, amount, memo rules, and an idempotency_key of 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.
  2. POST /api/v1/faucet validates its user account, pool, amount greater than zero and at most 5 ZEC, and key. Validation happens before the recorded-key lookup.
  3. 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 preparing and returned in the same way. This response admits the claim. Preparation, broadcast, and confirmation continue in the background.
  4. Pending statuses preparing, prepared, and broadcast return HTTP 202 with a relative Location header. 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 is preparing, so txid is empty. A later replay whose stored status is confirmed or failed returns HTTP 200. That code covers both outcomes; read status.
  5. 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 prepared before broadcast. For faucet payments, the source is hidden treasury Account 6; it may replenish itself first.
  6. 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 stores confirmed activity with a block hash. If auto-mining fails, the activity can remain broadcast, 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:

FieldMeaning
idThe activity row’s own UUID. Not the idempotency key and not the txid.
kindsend or faucet.
from_accountSource account 1–5, or null for a faucet payment out of the hidden treasury.
to_accountDestination account 1–5, or null for an external send.
to_addressExternal send destination, or null for an account recipient.
source_poolironwood or transparent.
destination_poolironwood or transparent.
amount_zatoshiInteger zatoshi paid to the destination. It does not include the fee.
txidThe prepared transaction’s ID; empty while status is preparing.
block_hashThe confirming block’s hash, or null before confirmation.
statuspreparing, prepared, broadcast, confirmed, unconfirmed after a deliberate reorg/rollback, or a stored terminal failed result.
created_atWhen the row was inserted, as YYYY-MM-DD HH:MM:SS UTC, including in the initial accepted response.
last_errorStored 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

  1. 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"}'
    
  2. If the response is lost, repeat that same request against the same instance. The key identifies this payment; a new key requests another one.

  3. GET the returned Location until the stored status is confirmed or failed. 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?

CallerHow to recover the same payment
Direct APIRepeat 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 FaucetPending 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 faucetRerun 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

After a lost payment response, direct API callers reuse their saved key and read the recorded outcome, dashboard callers resume retained payments, and CLI callers rerun the same command and instance. A new key requests a new payment. A replay returns that outcome. Activity omits keys; a stored row is not proof nothing happened.

  1. 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 [].
  2. If the matching activity is recorded, use its status. Background work moves an unresolved payment through preparation, broadcast, and confirmation. A broadcast activity may become confirmed after another block and those checks. Repeating the same POST returns the outcome already recorded. HTTP 200 on that terminal replay covers both confirmed and failed; inspect status. The replay does not need to drive confirmation.
  3. 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.
  4. ths faucet <ADDRESS> calls POST /api/v1/faucet/address with 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, read GET /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.

Next: choose an interface for your own application.