Build/Wallets & walletd

Wallets & walletd

zkas-walletd scans the chain, holds witnesses, builds Halo 2 proofs and broadcasts. It can run with a viewing key only, in which case it can watch but never spend.

Spends per tx38notes, not coins
Proving cost2.4 score-seconds / note
Payees per tx37plus a change output
Fee range0.019–0.246ZKAS, per action
Auto-consolidate500notes, on by default

Notes, not coins

Almost every surprise operators hit comes from one fact:

A transaction can spend at most 38 notes, a count of notes, not an amount of ZKAS. How much value one transaction can move is 38 × your average note size.

Two wallets with the same balance behave completely differently:

WalletAvg. noteMax per transactionMoving 100,000 ZKAS
Pool treasury, raw coinbase notes~57 ZKAS~2,166 ZKAS1,754 notes → 47 transactions
Same treasury, consolidated~2,166 ZKAS~82,300 ZKAS47 notes → 2 transactions
Moving 100,000 ZKAS · one transaction spends at most 38 notes raw coinbase notes ~57 ZKAS each 1,754 notes → 47 transactions 47× consolidated ~2,166 ZKAS each 47 notes → 2 transactions 2× same balance, same chain, same fee schedule wall time = 2.4 core-seconds × notes spent ÷ effective cores
Cost tracks the number of notes, never the amount. This is why a fragmented treasury is slow even for a tiny payment, and why consolidation, not more cores, is the fix.

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.

PartBytes per action
Action data (ActionWire)884
Its slice of the Halo 2 proof2,272
Total3,156

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

CapValueApplies to
max_spends_per_tx()38notes consumed (inputs)
max_actions_per_tx()38max(spends, outputs), what mass is charged on
max_payees_per_tx()37recipients in one send_many, plus one change output

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"
Every walletd flag26 entries
-s, --rpc-server
Default127.0.0.1:16810Notesnode gRPC. Point at a local node, a tunnel to a remote node was a large, measurable slowdown
-l, --listen
Default127.0.0.1:8501Notesloopback by default, on purpose
--wallet-dir
Default~/.ZKas/walletsNotesone <token>.scan per wallet
--wallet-secret
DefaultnoneNotesencrypts seeds at rest (XChaCha20-Poly1305 + Argon2). Without it seeds are stored in plaintext (mode 0600) and startup warns
--allow-origin
Defaultsame-origin onlyNotesrepeatable CORS allow-list. With none set, cross-origin browser calls are refused, this is what stops any page a user visits from reaching a daemon on their machine
--allow-default-token
DefaultfalseNotesallows the tokenless "default" wallet. Trusted single-user localhost only
--allow-remote
DefaultfalseNotesbind a non-loopback address directly. Prefer a TLS proxy
--serve-public ADDR:PORT
DefaultoffNotesself-hosting: auto-provisioned TLS and a pairing QR for the mobile wallet. No proxy, domain or certbot. Implies a bearer token
--auto-consolidate N
Default500Noteson by default. Keeps custodial wallets under N notes by merging their oldest in the background. Wallets below the ceiling are untouched
--proof-threads N
Defaultevery coreNotesa throttle, not a tuning knob: caps threads Halo 2 proving may use so the daemon cannot starve a co-located node. Lowering it makes payments slower
--max-concurrent-proves N
Defaultmin(2, cores)Notesglobal proof admission limit
--sync-wallets N
Defaultcores − 1 (1–8)Notesmaximum concurrent wallet scans
--idle-evict SECONDS
Default1800Notesdrop an idle wallet checkpoint from RAM, not disk
--diagnose
DefaultfalseNotesoffline: print each wallet's note / base / stranded-note report, then exit. Daemon stopped
--graft TOKEN:/path/older.scan
DefaultoffNotesoffline: repair a stranded wallet from an older snapshot of itself
--no-custodial
DefaultfalseNotesdisable every seed-holding endpoint (create, import, send, send_many, reveal, consolidate, sign). The daemon then holds no seeds and serves only watch, prepare and submit. Recommended for any public watch-only service
--warm-always N
Default0Noteskeep the N most recently used wallets resident and fully prepared, so the first payment after a quiet period does not wait. About 100 to 190 MiB each
--max-resident-wallets N
DefaultMemAvailable ÷ 192 MiB (4 to 256)Notessoft cap on wallets held in RAM: never evicts one used within the active-sync window
--hard-max-resident-wallets N
Default0 (none)Noteshard cap: a load evicts the least recently used idle wallet or waits. A wallet whose payment awaits signatures is never evicted
--resident-budget-mb MIB
Default70% of the cgroup memory limitNotesbyte budget for resident wallets; --no-resident-budget disables it
--chain-files URL_OR_DIR[,...]
DefaultnoneNotesread history covered by published chain files from a CDN or a local directory instead of the node: a restore takes minutes, not hours. Every file is checked against the node before it is trusted; segments downloaded from a URL are kept in <wallet-dir>/chainfiles-cache/ so each is fetched once
--shared-leaf-store
DefaultfalseNotescheckpoints reference the shared tree's leaf stream instead of embedding a copy: a 500 MB checkpoint becomes a few MB. One-way, builds older than v11 cannot read the converted wallets
--no-shared-tree
DefaultfalseNotesdo not build the daemon-wide shared chain tree. Only for a device engine. With the tree a wallet keeps only its notes, however many it holds, and every spend is witnessed by the daemon's one copy of the chain; without it a wallet carries every leaf since its oldest note
--compact-nullifiers
DefaultfalseNotesstore the nullifier table once and a compact bitset per wallet: much smaller, faster checkpoints
--checkpoint-interval SECONDS
Default60Notestime rule for checkpointing a wallet that has advanced by at least 1,000 blocks (or by anything, once an hour). Parked spends and other state that must not be lost are written at once
--prefetch-depth N
Default1Notesblock pages fetched concurrently ahead of a deep scan; raise it for a remote node

The complete flag reference, with every default, is in WALLETD.md.

Sizing, measured 7 November 2026. A public, watch-only daemon in the shared-tree modes (--no-custodial --chain-files --shared-leaf-store --compact-nullifiers) restored three wallets from genesis at once under a hard 2 GB memory limit in 10 minutes at about 1.2 GB RSS, and seven resident wallets later sat at 1.2 GB: the nullifier table (about 0.5 GB at 8.4 M nullifiers), loaded chain-file segments, the shared tree's index and the allocator; a resident wallet is a few MB. 2 GB is the floor for this mode, give it 4 GB. GET /api/admin/memory (loopback) shows the live breakdown. An exchange daemon needs the same plus proving.
Reverse proxy timeouts. Proving takes tens of seconds, so set the read timeout or clients appear to hang on a send that is actually progressing.
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
Keys. The official wallet creates a 12-word recovery phrase (BIP-39, English, no passphrase) and derives each account with ZIP-32 for Orchard, m/32'/111111'/account'. The 32-byte result is the seed_hex the daemon works with (import, reveal); the daemon never sees the phrase. Wallets created before phrases existed hold a raw 64-hex seed, and both forms restore in the official wallet.

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 /health
liveness; no token
GET /api/status
the one call a client should poll, see the example below
POST /api/wallet/create
no body. A new wallet born at the current tip; the seed is returned once, plus the address
POST /api/wallet/import
{seed_hex, birthday}; birthday is a DAA score
POST /api/wallet/watch
{fvk_hex, birthday} → watch-only. Syncs and builds proofs, holds no spend authority. Re-registering the same key never moves its birthday later
GET /api/wallet/reveal
seed_hex of a custodial wallet; refused on watch-only
GET /api/wallet/address
the receive address; ?index=N returns the wallet's N-th diversified address, see deposit attribution
GET /api/wallet/balance
total / spendable / maturing / pending; ?notes=1 adds the per-note array
POST /api/wallet/send
{to, amount_sompi|amount_fc, memo, fee, max_total_fee, request_id} → {txid, txids, tx_count, amount_sompi, fee_sompi}. Read txids, a large send splits across transactions. See paying exactly once
POST /api/wallet/send_many
{payees:[{to, amount_sompi, memo}], fee, max_total_fee, request_id} → one proof per batch of up to 37 payees; payee_txids says which transaction paid whom
POST /api/wallet/prepare
{fvk_hex, to, amount_*, fee, memo, allow_partial, request_id} → {session, sighash, bundle_hex, spend_auth[], disclosure[], remaining_sompi}. The session lives 5 minutes
POST /api/wallet/submit
{session, sigs:[{index, sig}]} → same shape as send. Sessions are single-use
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
newest first, limit (up to 5,000) and offset. Each row has kind, txid, daaScore, amounts, and credits[] (each with the customer index its address was issued at)>: one entry per output with its address, exact amount and memo. pendingOutgoing lists sends not yet on chain
GET /api/wallet/deposits?after=&limit=
the deposit journal: numbered credit, memo and rebuild events, oldest first; ask with the last seq you processed and nothing is skipped or repeated, however long you were away. The way an exchange credits deposits
GET /api/wallet/requests/{id}
what became of a payment sent with that request_id: in_progress, or sent with each transaction landed (block, depth), pending or returned_or_settled; 404 when nothing was recorded. For a caller that lost the answer
GET /api/admin/memory
loopback only: where the process's memory goes, the resident wallets largest first
GET /api/wallet/proof?txid=
proof of one of this wallet's sends: recipient, amount and memo of each payment output, nothing else
POST /api/proof/verify
a proof → {valid, recipient, amount, memo, confirmations}; needs no wallet or token
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
GET / POST /api/wallet/scan-receipt
export a synced wallet's notes and witnesses as a small receipt, or adopt one, to move a wallet between daemons without a rescan
POST /api/wallet/warm
prepare this wallet for a fast first payment now
POST /api/checkpoint
write this wallet's checkpoint now (the mobile app calls it when backgrounded)
POST /api/wallet/settings
{private_sends}: build sends without the sender-recoverable ciphertext. Off by default; such sends can never be proven or restored. History itself is always recorded
POST /api/wallet/rescan
rebuild from the wallet birthday; refused unless the node serves the chain from genesis
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
}
  • blocks_behind > 0 is normal. A wallet deliberately never ingests the last few blocks near the tip.
  • Gate sends on spend_ready, never on synced alone.
  • loading:true with balance 0 means opening, not empty. Rendering it as a balance is what asks a user to retype their seed.
  • missing_history:true means the balance is a lower bound, the view was rebuilt from a pruning point below its birthday. Say so in the UI.
  • Balances are decimal strings, so parse with BigInt. _fc is the human form, _sompi the exact one.
  • Several fields are serde(default), an older daemon omits them. Treat absent as the safe value; never hard-fail on an unknown field.

Paying exactly once

Give every payment a request_id: 1 to 128 characters, unique per payment, such as your withdrawal id. The daemon records each broadcast under it for 24 hours, across restarts, and answers a retry of the same payment (same id, same recipient, same amount) from that record instead of paying again. The record is written as each transaction is accepted, so even a payment interrupted part-way is answered with exactly the parts that went out.

200
paid; record every id in txids
409 already_sent
paid earlier by this request; if its amount is below the request, only part was paid and the rest needs a new payment with a new id
409 in_progress
the same request is still being sent; retry later with the same id
400, 500, 503, 502 without txids
nothing was paid
502 with txids
a split payment was partly paid: the listed transactions went out
504 outcome_unknown
the node connection failed mid-broadcast and resending did not settle it. Possibly paid: retry with the same id, never under a new one

A broadcast whose answer is lost is resent unchanged (same transaction, so it can never pay twice) before the daemon reports it unknown, and a payment that never confirms has its coins returned only after the node confirms it no longer holds the transaction. Set max_total_fee to cap what one payment may pay in fees.

Lost the answer altogether (a crash, a timeout)? Ask GET /api/wallet/requests/<request_id>: it says whether the request is still in progress or was sent, and for each transaction whether it landed (with its block and depth, from the chain's own acceptance), is still pending, or was returned. Settle your ledger from that, never by paying again. A payment the chain has not accepted after 600 DAA has its coins returned once the node's mempool no longer holds it; one the chain accepted keeps them parked until the scan settles it.

Build requirement. The request-id matching on recipient and amount, per-transaction records, memos on received payments, the deposit journal and /requests/{id} are in zkas-v1.0.14 and later (released 7 November 2026); zkas-v1.0.13 and earlier predate them.

Deposit attribution

GET /api/wallet/address            # index 0 — the wallet's own address
GET /api/wallet/address?index=7    # a distinct, unlinkable address for customer 7

Every diversified address of a wallet is paid into the same notes and the same balance, and is found by the same scan: trial decryption uses the incoming viewing key, which does not depend on the diversifier. A received note records the diversified address it was sent to in its history row, so a service can hand each customer their own address and attribute deposits by address, with no memo required.

One bound, and it only affects mining payouts. Coinbase recognition pre-derives indices 0..255 (COINBASE_DIVERSIFIER_SCAN = 256), because a coinbase publishes its recipient in the clear and is matched by raw equality rather than trial decryption. A coinbase paid to an index ≥ 256 is not credited. Ordinary receives work at any index. The limit is pinned by a test rather than left to chance, if you pay miners to diversified addresses, stay inside the window.
One wallet, an address per customer
How?index=N, one scan, attribution by addressVerdictUse this. One wallet to sync, no memo discipline required of the payer
One wallet, memo as a payment id
Howsame address for everyone, unique memo per customerVerdictStill valid, the destination-tag pattern. Useful when the payer's wallet cannot be told which address to use
One wallet per customer
Howa token per customer, each its own .scanVerdictDoes not scale. Every wallet syncs independently; 350 loaded wallets already strain a 4-core box

Credit from the deposit journal. GET /api/wallet/deposits?after=<seq> returns one numbered credit event per output that paid the wallet, with the address, its index (the customer id it was issued at, recovered from the address itself), the exact amount, the memo and daaScore. Store the last seq you processed; nothing is skipped however long you were away, nothing comes twice, and a rebuild event tells you the wallet is re-scanning so you can review any credit that does not reappear. Key your ledger on (txid, i).

Attribute from credits[] (or the journal), not from the row. One transaction can pay several of your addresses; the history row's amountSompi is then their sum and its recipient is null (daemons before 6 November 2026 named the first). Credit each credits[] entry by its address and amountSompiExact, keyed on (txid, index), and hold rows whose credits are empty or do not sum to the row amount for review.

Full walkthrough in Integrations → exchange, and the complete exchange launch guide in WALLETD.md.

Performance

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).

Witness build (62K-note wallet)BeforeAfter
1 note38.8 sn/a
2 notes94.7 s58.5 ms
22 notesn/a243.9 ms
38 notesn/a538.8 ms
At 200K leaves, per send29.36 s0.357 s (82×)
A wrong witness cache can only decline to help. Three layers: a fresh cache must reproduce the tip mirror's root or it is discarded; every path served is verified against the anchor root before use; a rejected build is remembered so an O(chain) rebuild is never re-paid per tick.

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:

SpendsWallCPUCores useds / spend
14.3 s10.4 s2.42×includes one-time setup
43.4 s10.7 s3.14×0.85
129.6 s30.2 s3.15×0.80
3830.0 s93.8 s3.13×0.79

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

Always issue one call for the full amount. The daemon splits it into transactions itself. Splitting by hand is worse on every axis.

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

ApproachNotesTxsProving (4 cores)Fees
1 call, amount_fc: 5000883 (38+38+12)~60 s0.573 ZKAS
3 calls of ~1,667903~70 s0.586 ZKAS
88 calls of one note8888~68 s + 88 round-trips1.63 ZKAS

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.

Concurrent calls gain nothing. The daemon runs one custodial payment at a time per wallet, so parallel calls on the same wallet simply queue; proving is already parallel inside each call. Separate wallets pay in parallel.

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 (Windows, macOS, Linux)
embeds the same crate. Watch-only: the seed lives in app storage, so backup and passphrase are client-side. Downloads at zkas.info/downloads/wallet/latest
Web wallet
wallet.zkas.info, hosted walletd, token-scoped multi-wallet, plus the reference SPA
Paper wallet
served at zkas.info/paper-wallet (GitLab Pages, built from its public source); source at zkas.info/code/paper-wallet
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
Verified against zkas-rusty at zkas-v1.0.12. If this page contradicts the code, the code is right. Report an error.