Wallets & walletd

Payments are sized in notes, not coins

Almost every surprise operators hit comes from one fact:

Two wallets with the same balance behave completely differently:

A fragmented wallet is slow no matter how small the payment, and consolidating is the only thing that changes the outcome by an order of magnitude. This is why --auto-consolidate is on by default.

Where 38 comes from

It is a bytes limit, not an economic one. Kaspa charges transient mass at 4 per serialized byte and caps a standard transaction at 500,000 mass, so the bundle must fit 500000/4 − 256 = 124,744 bytes.

Plus a 117-byte header and a 2,720-byte proof preamble, so wire_len(n) = 2837 + 3156n: n=38 → 122,765 bytes fits, n=39 → 125,921 does not. Raising it needs a consensus change and would buy nothing — proving cost per spend is flat from 4 to 38.

The three caps, and fees

One transaction can spend 38 notes to pay 1 recipient, or spend 2 notes to pay 37 — same mass ceiling, very different proving cost, because cost tracks spends. Minimum relay fee is charged on size, so on action count: 1–2 actions = 0.0186 ZKAS, 38 actions = 0.2458 ZKAS. The wallet raises any fee you pass to this floor automatically; passing less does not save money.

Running the daemon

zkas-walletd \
  --network mainnet \
  --rpc-server 127.0.0.1:16810 \
  --listen 127.0.0.1:8501 \
  --wallet-dir /var/lib/zkas/wallets \
  --wallet-secret "$ZKAS_WALLET_SECRET"

location /daemon/ {
    proxy_pass http://127.0.0.1:8501/;
    proxy_read_timeout 300s;
    proxy_connect_timeout 5s;
}

Authentication and key material

Every request carries X-Wallet-Token, which selects the wallet. Mint one once and keep it — it is the credential; whoever holds it controls that wallet.

TOK=$(head -c16 /dev/urandom | xxd -p)
curl -X POST -H "X-Wallet-Token: $TOK" http://127.0.0.1:8501/api/wallet/create

birthday is the DAA score to start scanning from. Set it to the tip for a fresh wallet — omitting it scans the whole chain for funds that do not exist.

Wallet daemon endpoints

GET /api/status

the one call a client should poll — see the example below

POST /api/wallet/create

{birthday} → seed returned once, plus address

POST /api/wallet/import

{seed_hex, birthday}

POST /api/wallet/watch

{fvk_hex, birthday} → watch-only. Syncs and builds proofs, holds no spend authority

GET /api/wallet/reveal

seed_hex of a custodial wallet; refused on watch-only

GET /api/wallet/address

this wallet's receive address. Takes no parameters and always returns the same string — see deposit attribution

GET /api/wallet/balance

total / spendable / maturing / pending

POST /api/wallet/send

{to, amount_fc|amount_sompi, memo, fee} → {txid, txids, tx_count, amount_sompi, fee_sompi}. Rejects amount 0. Read txids — a large send splits across transactions

POST /api/wallet/send_many

{payees[], fee} → one proof for the batch, up to 37 payees per transaction

POST /api/wallet/prepare

{fvk_hex, to, amount_*, fee, memo, allow_partial} → {session, sighash, bundle_hex, spend_auth[], disclosure[], remaining_sompi}

POST /api/wallet/submit

{session, sigs:[{index, sig}]} → same shape as send. Sessions are single-use and expire

POST /api/wallet/consolidate

{fee, heal} → merge notes. heal:true takes the oldest notes, advancing the witness base and speeding every later send; default merges smallest-value dust

GET /api/wallet/history

rows with txid, kind, amount, memo, recipient

POST /api/wallet/settings

{recoverable_history} → OVK capture. Opt-in, not retroactive

POST /api/wallet/sign

{message} → address-control proof. Discloses the FVK — use a dedicated seed

POST /api/verify

{address, message, signature} → {valid, reason}; needs no wallet

POST /api/wallet/rescan

rebuild the scan from the wallet birthday

GET /api/status

{
  "has_wallet": true, "network": "mainnet",
  "node_connected": true, "daa_score": 5529882,
  "synced": true, "spend_ready": true, "blocks_behind": 12,
  "loading": false, "warming": false, "watch_only": false,
  "missing_history": false, "note_count": 41,
  "balance_sompi":   "412000000000",
  "spendable_sompi": "374000000000",
  "maturing_sompi":   "38000000000",
  "pending_in_sompi": "0", "pending_out_sompi": "0",
  "updated_unix": 1790603316
}

Deposit attribution: one wallet, one address

One wallet per customer

Howa token per customer, each its own .scan fileVerdictDoes not scale. Every wallet syncs independently; 350 loaded wallets already strain a 4-core box. Fine for hundreds, not hundreds of thousands

One deposit wallet + memo

Howevery customer gets the same address plus a unique memo / payment idVerdictUse this. The XRP/XLM destination-tag pattern — one wallet, one scan

Memos survive on the receive side and are readable per transaction from /api/wallet/history. Full walkthrough in Integrations → exchange.

Performance — what actually costs time

The proof is not the expensive part; the Merkle witness used to be. The node keeps only the tree's ~32-node frontier, so wallets hold their own witnesses. Building one meant replaying the note-commitment stream, and a single Sinsemilla combine costs ~150–260 µs — one hash per leaf, so ~30–50 s per send on a 200K-leaf chain, growing forever.

Fixed by SubtreeCache: for a note at position p witnessed at anchor S, every sibling is a subtree either entirely below S (complete, immutable forever) or entirely above it (the empty root), with exactly one exception — the subtree straddling S, which is O(depth).

Proving is now the entire cost

Total CPU is flat whatever the thread count — 91.7 s at one thread, 93.4 s at four, for 38 spends — so the only honest formula is wall = 2.4 s × spends ÷ effective cores. Measured on 4 cores:

One proof already uses 3.13 of 4 cores, so there is no idle CPU to parallelise into. More cores help; more threads do not.

Paying many recipients

Sending 5,000 ZKAS from a treasury of ~57 ZKAS coinbase notes needs ~88 notes whichever way you do it:

One plan across the whole amount (selection runs once, value-descending, so separate calls round up their own change and spend more notes), chunk proofs get grouped for 1.21×, one witness pass at one anchor under one lock, and fees stop multiplying the fixed 2,837-byte header.

All three rows are within ~15% of each other because they all spend ~88 notes. That is the point: note size is the whole game. Consolidated to ~2,166 ZKAS notes, the same 5,000 ZKAS payment is 3 notes, 1 transaction, ~7 seconds.

Health checks for a payout service

# the number that decides your payout time
curl -s -H "X-Wallet-Token: $TOK" localhost:8501/api/status | jq .note_count

grep "auto-consolidate: merged" walletd.log | tail -5       # is merging keeping up?
grep -E "send: (building|tx .* proven)" walletd.log | tail   # payout in progress

If note_count climbs steadily while auto-consolidate: merged lines are rare, merging is being starved — check whether something keeps a payment permanently in flight.

Self-hosting and the apps

kaspad --wallet-api

embeds walletd in the node with auto-provisioned TLS and a pairing QR. No reverse proxy, domain or certbot

zkas-walletd --serve-public

the same standalone. --insecure only behind a VPN, or viewing keys cross the wire in clear

Android

seed stays on device; walletd runs in-process as a native library, so nothing outside sees even a viewing key. Back up the keystore

Desktop (mac / linux)

embeds the same crate. Watch-only: the seed lives in app storage, so backup and passphrase are client-side

Web wallet

wallet.zkas.info — hosted walletd, token-scoped multi-wallet, plus the reference SPA

Paper wallet

served from GitHub Pages straight out of its own repo, so the page always matches the audited source

Tor

one-click "Connect over Tor" — an onion endpoint in front of a hosted walletd, baked into the app

Cross-device sync

a second device with the same seed adopts a twin checkpoint and clones a scan in ~32 ms