API reference

This page is the contract implemented in this repository. Request and response fields are the serde names on the Rust structs. Nothing here adds a route, a field, or a header that the code does not set.

The crate depends on axum 0.8.9. Where a failure comes from axum’s Json extractor rather than this crate’s AppError, the status below is the one axum’s own tests assert for that version.

HTTP

build_router registers four routes and no middleware:

Handlers that return AppError respond with JSON:

{"error":"<Display of the AppError>"}

GET /health returns Database when the metadata query fails. POST /payment-session returns InvalidRequest for a bad payment_source, and Wallet or Database when minting an address fails. Identity failures are returned by PaymentService::initialize and run() before the socket listens. They use the same AppError display text, as a process error.

GET /health

Returns 200 and HealthResponse:

The row inserted at first startup has current_sync_state "starting" and both heights 0, so both JSON heights are null.

The sync worker later writes one of these states:

record_sync_status stores whatever string it is given. Those four, plus the initial starting, are the ones the running service writes.

The unit test health_response_reports_persisted_sync_heights records state catching_up with tip 321 and scanned height 300, and the handler returns:

{
  "ok": true,
  "current_sync_state": "catching_up",
  "detected_tip_height": 321,
  "last_scanned_height": 300
}

POST /payment-session

Body JSON, content type application/json (a subtype with a +json suffix is also accepted by axum). PaymentSessionRequest:

Unknown JSON fields are ignored. A missing payment_source, or a value of the wrong JSON type, never reaches the handler.

Success is 200 and PaymentSessionResponse:

Query construction in build_qr_text, covered by tests in src/service.rs:

zcash:uaddr
zcash:uaddr?amount=0.12345678&memo=SW52b2ljZSBJTlYtMTAwMQ&message=Thanks%20for%20your%20purchase.

Order is amount, then memo, then message. A missing or whitespace-only field is omitted. The value that is encoded is the original string, not a trimmed copy. As ZIP-321 requires, memo is the unpadded base64url encoding of its UTF-8 bytes. For amount and message, unreserved characters stay as themselves (A-Z a-z 0-9 - _ . ~). Every other byte becomes % plus two uppercase hex digits.

The address is derived from the canonical UIVK with Orchard required, Sapling required, and the transparent receiver omitted. The app database also stores an Ironwood receiver whose bytes equal the Orchard receiver.

GET /payments/{payment_id} and GET /pay/{payment_id}

GET /payments/{payment_id} returns PaymentStatusResponse as JSON. GET /pay/{payment_id} returns the hosted pay page as HTML. Both return 404 NotFound for an id that isn’t 32 lowercase hex characters or isn’t known. Fields, statuses, and how to expose them are in Payment links and the pay page.

POST /dev/simulate-payment (testnet test hook)

Off unless ZCASH_DEV_SIMULATED_PAYMENTS=true on testnet with no LIGHTWALLETD_URL; otherwise 404. Body {"address": "<issued address>", "amount": "0.2"}. Records a fake mined receipt of amount ZEC for that address, then queues the normal webhook. Returns {"txid": "...", "total_received": "0.20000000"}. Two optional fields drive confirmation depth deterministically: confirmations (0 records a mempool receipt, n a receipt with n confirmations; omitted means fully confirmed) and txid (re-reports an earlier simulated transaction, for example at a deeper confirmations, instead of adding a new one; the same txid at another address is a separate receipt there, like another output of one transaction). An explicit confirmations below WEBHOOK_REPORT_CONFIRMATIONS is recorded but not counted or reported yet, like a scanned receipt. It exists so store plugins can be tested end to end without a chain or funds. Never enable it on a service that takes real orders: anyone who can reach it can mark an address paid.

Webhook

This is a request the service sends, not a route it serves. spawn_webhook_delivery_worker starts the loop only when both webhook_url and webhook_secret are set.

• Method: POST
• URL: ZCASH_WEBHOOK_URL
• Header Content-Type: application/json
• Header X-Signature: lowercase hex HMAC-SHA256
• Body: the exact request_body_json stored when the delivery was queued

The HMAC key is ZCASH_WEBHOOK_SECRET as UTF-8 bytes. The message is the raw body. sign_body uses hmac with sha2::Sha256 and encodes the digest with hex::encode.

The stored JSON is serde_json::to_string of these fields, in this order:

format_zat_as_zec divides the absolute zatoshis by 100_000_000 and prints the remainder in 8 digits. 12345678 zatoshis become 0.12345678. 100000000 become 1.00000000. A negative i64 gets a leading -.

received_by_confirmations element i sums the same active, eligible receipts that have a confirmation depth of at least i at the tip the address was last computed for (mempool receipts have depth 0). Element 0 therefore always equals total_received, and the array never increases from left to right. It is stored as address_totals.received_by_confirmations and copied into the delivery row, so retries resend the exact signed body.

state_version increments by one when current_total_zat changes, or when received_by_confirmations changes (a new block deepening a receipt, a reorg, or a mempool expiry). current_total_zat is the sum of value_zat over receipts for that address that are active and eligible_for_webhook. A delivery is inserted when dirty_state is dirty and the current total, or the current received_by_confirmations, differs from the newest outstanding or acknowledged one. Once every element equals element 0 the array stops changing, so no further deliveries are queued for that address until funds arrive or a reorg undoes a block. event_id is unique, and the insert is INSERT OR IGNORE.

claim_ready_webhook_delivery takes the oldest row that is queued, or retry_wait with next_attempt_at already due, ordered by observed_at then delivery_id. A newer queued delivery can be sent while an older one is still in retry_wait. Receivers should keep the highest state_version they have applied for an address. A later delivery of a lower version is an older total, including after a reorg where the newer total is smaller.

Eligibility:

• Mined receipt: confirmation depth is tip_height - mined_height + 1 when tip_height >= mined_height, else 0. Eligible when the depth is >= webhook_report_confirmations.
• Mempool receipt: eligible when webhook_report_confirmations == 0 and first_observed_at is strictly later than 24 hours before the check. The sync loop reconciles mempool receipts only in that zero-confirmation mode.

Delivery outcomes are in the integration guide. On startup, run() moves rows left in sending back to retry_wait with next_attempt_at set to the current time, then queues addresses whose dirty_state is still dirty.

Configuration

Config::from_env reads the process environment. Strings are trimmed. An empty string is treated as unset for ZCASH_UIVK, LIGHTWALLETD_URL, ZCASH_WEBHOOK_URL, and ZCASH_WEBHOOK_SECRET.

A value that fails its parse or range check returns InvalidConfig and the process does not listen. The error strings include:

• ZCASH_NETWORK must be 'testnet' or 'mainnet'
• ZCASH_BIRTHDAY_HEIGHT must be a positive integer (the parse failed; a numeric u32, including 0, is accepted)
• CATCH_UP_THRESHOLD_BLOCKS must be a non-negative integer
• CATCH_UP_BATCH_SIZE must be a positive integer or CATCH_UP_BATCH_SIZE must be greater than zero
• SCAN_PARALLELISM must be a positive integer or SCAN_PARALLELISM must be greater than zero
• the same pair of messages for SYNC_POLL_INTERVAL_SECONDS, WEBHOOK_POLL_INTERVAL_SECONDS, WEBHOOK_RETRY_DELAY_SECONDS, WEBHOOK_RETRY_MAX_DELAY_SECONDS, and WEBHOOK_MAX_ATTEMPTS
• WEBHOOK_REPORT_CONFIRMATIONS must be a non-negative integer
• FINALITY_CONFIRMATIONS must be a non-negative integer
• REQUIRED_CONFIRMATIONS must be a non-negative integer
• REQUIRED_CONFIRMATIONS needs WEBHOOK_REPORT_CONFIRMATIONS=0, because received_by_confirmations[0] includes mempool receipts
• REQUIRED_CONFIRMATIONS must be at most 100
• REQUIRED_CONFIRMATIONS must not exceed FINALITY_CONFIRMATIONS
• APP_DB_PATH and WALLET_DB_PATH must point to different files
• ZCASH_WEBHOOK_URL must be a valid absolute http(s) URL; got ...
• ZCASH_WEBHOOK_URL must be an absolute http(s) URL; got ...
• ZCASH_WEBHOOK_URL must use http or https; got ...
• ZCASH_WEBHOOK_URL must include a host; got ...
• the same four messages for PUBLIC_BASE_URL, plus PUBLIC_BASE_URL must not include a query or fragment; got ...
• ZCASH_DEV_SIMULATED_PAYMENTS must be 'true' or 'false'
• ZCASH_DEV_SIMULATED_PAYMENTS is only allowed with ZCASH_NETWORK=testnet
• ZCASH_DEV_SIMULATED_PAYMENTS cannot be combined with LIGHTWALLETD_URL

Setting the URL without the secret, or the secret without the URL, is allowed. The webhook worker stays off.

Named defaults live in src/constants.rs:

WEBHOOK_REPORT_CONFIRMATIONS and FINALITY_CONFIRMATIONS in that table are the defaults. The environment variables of the same names override them for a new database. Once service_metadata exists, a later start whose values differ from the stored row fails. See the next section.

Startup rules

PaymentService::initialize and each sync iteration call ensure_wallet_identity.

On a database with no wallet identity yet:

• The UIVK is ZCASH_UIVK, or, if that is unset, the UIVK read from the wallet database accounts table. If neither exists, startup fails with first startup requires ZCASH_UIVK unless the wallet DB already contains a canonical account.
• The birthday is ZCASH_BIRTHDAY_HEIGHT, or the wallet database birthday. If neither exists, startup fails with first startup requires ZCASH_BIRTHDAY_HEIGHT unless the wallet DB already contains a canonical account.
• When both the environment and the wallet database supply a UIVK, they must be equal (provided ZCASH_UIVK does not match the existing wallet DB identity).
• The UIVK is stored as canonical_uivk.

On a later start:

• A provided ZCASH_UIVK must equal canonical_uivk.
• ZCASH_NETWORK must equal the stored network.
• A provided ZCASH_BIRTHDAY_HEIGHT must equal the stored birthday. Omitting it is allowed.
• A UIVK and birthday read from the wallet database must match the stored identity.

WalletView::decode then requires the canonical UIVK to decode for that network and to contain Orchard and Sapling (configured UIVK must contain Orchard and Sapling receivers). If the wallet database UIVK does not match the decoded canonical form, startup fails with wallet DB UIVK does not match the decoded canonical wallet view.

ensure_service_metadata inserts the confirmation settings on first start. A later start fails with stored service metadata confirmation settings do not match the configured constants when WEBHOOK_REPORT_CONFIRMATIONS or FINALITY_CONFIRMATIONS differs from that row.

REQUIRED_CONFIRMATIONS is deliberately not fixed at database creation. The array is derived from stored receipt heights rather than accumulated, so it can be rebuilt at any time. The setting is stored in service_metadata.required_confirmations (a nullable column added to existing databases on startup, NULL meaning off). When a start’s value differs from the stored one, every address’s array is rebuilt from its receipts in one transaction. That rebuild is silent: it does not bump state_version or queue webhooks, so changing the setting does not flood your endpoint. The next real change for an address (new funds, a new block deepening a receipt, a reorg) carries the new shape. Turning it off makes the field disappear from later events.

The scan loop builds keys from the environment variable ZCASH_UIVK on every iteration, not from the stored identity alone. Lightwalletd calls in src/scanner.rs request blocks by height, the latest block, tree state, the mempool stream, mempool transaction ids, and raw transactions by id. Those requests do not send the UIVK. Decryption uses scanning keys built locally from that UIVK.

The service keeps one shared connection to lightwalletd. It sends HTTP/2 and TCP keepalives on it, bounds connect and unary requests with timeouts, and polls the chain tip every 15 seconds while it waits on the mempool stream. A connection that drops silently is replaced within about half a minute instead of stalling block and mempool scanning until the operating system gives up on it.

Crate entry points

src/lib.rs exports these modules: config, constants, db, error, logging, receipt_ingest, scanner, service, wallet_db, wallet_runtime, webhook_delivery, zcash.

The binary and an embedded host call the items below. Signatures match the source.

pub struct AppState {
    pub service: Arc<PaymentService>,
}

pub fn build_router(state: AppState) -> Router;
pub async fn run() -> Result<(), AppError>;

impl Config {
    pub fn from_env() -> Result<Self, AppError>;
}

impl PaymentService {
    pub fn initialize(config: Config) -> Result<Self, AppError>;
    pub fn issue_payment_session(
        &self,
        request: PaymentSessionRequest,
    ) -> Result<PaymentSessionResponse, AppError>;
    pub fn health_response(&self) -> Result<HealthResponse, AppError>;
}

pub fn build_qr_text(
    address: &str,
    amount: Option<&str>,
    memo: Option<&str>,
    message: Option<&str>,
) -> String;

pub fn spawn_wallet_sync_worker(config: Config);
pub fn spawn_webhook_delivery_worker(config: Config);
pub fn init_logging(config: &Config) -> Result<WorkerGuard, AppError>;

run is the path main uses. It calls Config::from_env, init_logging, PaymentService::initialize, the private webhook recovery, both spawn_* workers, build_router, and axum::serve with shutdown on Ctrl-C.

PaymentService’s fields are private. Config’s fields are public and match the environment table: listen_addr, network, startup_uivk, lightwalletd_url, birthday_height, wallet_db_path, app_db_path, log_dir, catch_up_threshold_blocks, catch_up_batch_size, sync_poll_interval_seconds, webhook_url, webhook_secret, webhook_poll_interval_seconds, webhook_retry_delay_seconds, webhook_retry_max_delay_seconds, webhook_max_attempts, webhook_report_confirmations, finality_confirmations, public_base_url, return_url_allowed_origins.

db, scanner, receipt_ingest, wallet_db, and zcash are public as well. They are the storage and scan implementation behind the HTTP routes. Their types and function signatures are the pub items in those files. This guide does not add behavior on top of them.