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.
Notes, not coins
Almost every surprise operators hit comes from one fact:
38 × your average note size.Two wallets with the same balance behave completely differently:
| Wallet | Avg. note | Max per transaction | Moving 100,000 ZKAS |
|---|---|---|---|
| Pool treasury, raw coinbase notes | ~57 ZKAS | ~2,166 ZKAS | 1,754 notes → 47 transactions |
| Same treasury, consolidated | ~2,166 ZKAS | ~82,300 ZKAS | 47 notes → 2 transactions |
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.
| Part | Bytes per action |
|---|---|
Action data (ActionWire) | 884 |
| Its slice of the Halo 2 proof | 2,272 |
| Total | 3,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
| Cap | Value | Applies to |
|---|---|---|
max_spends_per_tx() | 38 | notes consumed (inputs) |
max_actions_per_tx() | 38 | max(spends, outputs), what mass is charged on |
max_payees_per_tx() | 37 | recipients 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- Default
127.0.0.1:16810Notesnode gRPC. Point at a local node, a tunnel to a remote node was a large, measurable slowdown -l, --listen- Default
127.0.0.1:8501Notesloopback by default, on purpose --wallet-dir- Default
~/.ZKas/walletsNotesone<token>.scanper 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
Nnotes 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- Default
min(2, cores)Notesglobal proof admission limit --sync-wallets N- Default
cores − 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-budgetdisables 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.
--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.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
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};birthdayis a DAA scorePOST /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 laterGET /api/wallet/revealseed_hexof a custodial wallet; refused on watch-onlyGET /api/wallet/address- the receive address;
?index=Nreturns the wallet's N-th diversified address, see deposit attribution GET /api/wallet/balance- total / spendable / maturing / pending;
?notes=1adds 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}. Readtxids, a large send splits across transactions. See paying exactly oncePOST /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_txidssays which transaction paid whomPOST /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 minutesPOST /api/wallet/submit{session, sigs:[{index, sig}]}→ same shape assend. Sessions are single-usePOST /api/wallet/consolidate{fee, heal}→ merge notes.heal:truetakes the oldest notes, advancing the witness base and speeding every later send; default merges smallest-value dustGET /api/wallet/history- newest first,
limit(up to 5,000) andoffset. Each row haskind,txid,daaScore, amounts, andcredits[](each with the customerindexits address was issued at)>: one entry per output with its address, exact amount and memo.pendingOutgoinglists sends not yet on chain GET /api/wallet/deposits?after=&limit=- the deposit journal: numbered
credit,memoandrebuildevents, oldest first; ask with the lastseqyou 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, orsentwith each transactionlanded(block, depth),pendingorreturned_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 seedPOST /api/verify{address, message, signature}→{valid, reason}; needs no walletGET/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 recordedPOST /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 > 0is normal. A wallet deliberately never ingests the last few blocks near the tip.- Gate sends on
spend_ready, never onsyncedalone. loading:truewith balance 0 means opening, not empty. Rendering it as a balance is what asks a user to retype their seed.missing_history:truemeans 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.
_fcis the human form,_sompithe 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.
/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.
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).
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) | Before | After |
|---|---|---|
| 1 note | 38.8 s | n/a |
| 2 notes | 94.7 s | 58.5 ms |
| 22 notes | n/a | 243.9 ms |
| 38 notes | n/a | 538.8 ms |
| At 200K leaves, per send | 29.36 s | 0.357 s (82×) |
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:
| Spends | Wall | CPU | Cores used | s / spend |
|---|---|---|---|---|
| 1 | 4.3 s | 10.4 s | 2.42× | includes one-time setup |
| 4 | 3.4 s | 10.7 s | 3.14× | 0.85 |
| 12 | 9.6 s | 30.2 s | 3.15× | 0.80 |
| 38 | 30.0 s | 93.8 s | 3.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
Sending 5,000 ZKAS from a treasury of ~57 ZKAS coinbase notes needs ~88 notes whichever way you do it:
| Approach | Notes | Txs | Proving (4 cores) | Fees |
|---|---|---|---|---|
1 call, amount_fc: 5000 | 88 | 3 (38+38+12) | ~60 s | 0.573 ZKAS |
| 3 calls of ~1,667 | 90 | 3 | ~70 s | 0.586 ZKAS |
| 88 calls of one note | 88 | 88 | ~68 s + 88 round-trips | 1.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.
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.
--insecureonly 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
zkas-rusty at zkas-v1.0.12. If this page contradicts the code, the code is right. Report an error.