# kohaku-cli Source: https://github.com/kassandraoftroy/kohaku-cli Kiwi News: https://news.kiwistand.com/stories/kohaku-cli?index=0x6ab772935af5eebe25d1f832ff6f2afbdf5dc338db0048e0ffcb66f9efd1b86100577ef6 Submitted by misha on 2026-09-26 UTC, 1 upvote, 0 comments ## Summary kohaku-cli is a command line wallet for moving funds between public Ethereum accounts derived from a seed phrase and private balances on Tornado Cash, Railgun and Privacy Pools (V1). The README marks it as unaudited, under active development, written with help from Claude, and not for mainnet use unless the user understands the risk of catastrophic loss of funds. The CLI encrypts the seed on disk, prompts for shield and unshield steps, and can run headlessly with --non-interactive for scripts and agents. It requires Node.js 22+ and an Ethereum RPC URL, and wallet data is stored in ~/.kohaku-cli by default. ## Article Important NOTICE: this CLI has NOT BEEN AUDITED and IS UNDER ACTIVE DEVELOPMENT and HAS BEEN WRITTEN WITH HELP FROM CLAUDE et al. DO NOT USE ON MAINNET unless you know EXACTLY WHAT YOU ARE DOING and understand YOU RISK CATASTROPHIC LOSS OF FUNDS. A command line interface wallet for moving funds between public Ethereum accounts (derived from your seed) and private balances on Tornado Cash, Railgun and Privacy Pools (V1) -- whose credentials also conveniently live on the wallet seed phrase. It also covers ENS / GNS / WNS names, EIP-5564 stealth address "profile" concept, and Tornado note import/export. The CLI encrypts your seed on disk, walks you through shield / unshield with prompts, and can run headlessly with --non-interactive for scripts and agents. Requirements: Node.js 22+, an Ethereum RPC URL (RPC_URL or --rpc-url). See Kohaku CLI Wiki for a practical guide to using kohaku-cli as a wallet solution "in real life" See README below for quick testnet demo and other technical details. npm install npm run build # or during development: npm run dev:prod -- ... Keep the committed package-lock.json when installing on another OS or CPU architecture. It includes the platform-specific Rollup and esbuild binaries; node_modules should be installed on the target machine. For a clean installation from the pinned versions, use npm ci --include=optional followed by npm run build. The explicit include also overrides an npm configuration that omits optional dependencies. After changing dependencies, run npm run check:platform-lock to catch platform entries removed by npm's optional-dependency lockfile bug. After build, run via the bin launcher (registers an ESM resolve hook, then loads dist/): npm start -- --version # or link onto PATH (point at bin/, not dist/): # ln -sf "$(pwd)/bin/kohaku.mjs" ~/.local/bin/kohaku Examples below use kohaku; swap in npm run dev:prod -- if you have not built yet. For slow Tornado Merkle tree for ... leaves took ...ms operations, run the same diagnostic on each machine: npm run diagnose:tornado # Optionally match the leaf count from the slow operation: npm run diagnose:tornado -- --leaves 65536 --timeout-ms 180000 This reports Node/V8 versions, CPU availability, memory/load, Linux pressure and cgroup limits when available, and cold/warm SDK tree timings versus a single-threaded build. It also times proof extraction from an existing tree and checks that all roots match. Only synthetic leaves are used; no wallet, RPC, or network access is needed. Compare the same leaf count and runtime version. The installed SDK's MiMC trees use JavaScript BigInt and Node worker threads, independently of Rollup's native build binary. A full-node workload, CPU limits, memory pressure, or runtime differences can affect the results; a machine-specific speedup requires those measurements. The diagnostic measures Merkle construction, not Groth16 proving or RPC sync latency. Set your RPC once per shell (Sepolia for --testnet wallets): export RPC_URL="https://sepolia.infura.io/v3/YOUR_KEY" Optionally set a default privacy protocol so shield / unshield can omit --protocol, and so balances includes that protocol’s private balances by default: export DEFAULT_PRIVACY_PROTOCOL=tornado # or railgun | privacy-pools If unset (or set to anything else), --protocol is required on shield/unshield, and balances shows public balances only unless you pass --include. Some commands sync private state by calling eth_getLogs in chunks (default: up to 499 blocks per request). If your provider rejects large log ranges or times out, lower the chunk size: export KOHAKU_GETLOGS_MAX_BLOCK_SPAN=100 Use any positive integer; smaller values mean more RPC calls but fewer failures on strict nodes. Wallet data lives in ~/.kohaku-cli by default (--dataDir to override). Getting started This walkthrough creates a testnet wallet, funds a fresh public address, shields 0.1 ETH with Tornado Cash, checks balances, then unshields that note to a new public address. 1. Create wallets New seed (CLI generates and shows the mnemonic once): kohaku create-wallet testWallet --testnet You will be asked for an encryption password twice. Copy the mnemonic from the boxed output and store it offline; it is not shown again. Import an existing seed (scans RPC for used addresses and resumes account index): kohaku create-wallet importTest --testnet --import Paste your 12- or 24-word phrase when prompted (masked). --rpc-url or RPC_URL is required for import so the CLI can detect which derived addresses already have activity. 2. See what you have kohaku balances --include tornado Pick testWallet if you have more than one wallet, enter the wallet password, then wait for the spinner. You should see Public totals (ETH + common ERC-20s on Sepolia) and Tornado private balances (--include selects which private protocols to sync; without it, only DEFAULT_PRIVACY_PROTOCOL is included, or none if that env is unset). To pin the wallet and get per-address detail: kohaku balances --wallet testWallet --include tornado --verbose 3. Get a deposit address kohaku next-fresh-address --wallet testWallet The command prints a single 0x… address and saves it as the next public account in your wallet. Send Sepolia ETH (and optionally test ERC-20s) to that address from a faucet or another wallet. Run balances again until public ETH shows up. 4. Shield with Tornado Cash (ETH) Dry run first (prints transaction JSON, does not send): kohaku shield --protocol tornado --wallet testWallet --amount-formatted 0.1 Choose a public account that has enough balance and review the planned transaction. Add --broadcast when you are ready to sign and submit on-chain: kohaku shield --protocol tornado --wallet testWallet --amount-formatted 0.1 --broadcast Tornado ETH shields accept exact multiples of 0.01 ETH by default, or 0.1 ETH with --exclude-new-pools. Confirm the shield transaction when asked; spinners show mining status. Check balances again — public ETH should drop and the Tornado private balance should show a 0.1 ETH note: kohaku balances --wallet testWallet --include tornado 5. Unshield to a fresh public address Withdraw the private note back to the public chain. The dry run builds the private operation JSON: kohaku unshield --protocol tornado --wallet testWallet --next --amount-formatted 0.1 --next selects a fresh public account from this wallet, which can sign the EIP-7702 delegation required by Tornado. If that index already has a nonce, balance, or code, it is saved and the next index is used. balances also checks the next two unstored indexes and saves any that already have activity, so a broadcast that landed without being recorded still shows up. Add --broadcast to submit through the paymaster: kohaku unshield --protocol tornado --wallet testWallet --next --amount-formatted 0.1 --broadcast Confirm the broadcast prompt (amount + recipient). The CLI syncs private state, prepares the proof, and submits the UserOperation. One Tornado unshield can spend multiple notes in a single paymaster UserOp when the amount needs more than one denomination. kohaku balances --wallet testWallet --include tornado You should see the Tornado private balance decrease and the fresh public account receive the unshielded ETH minus the paymaster fee. Commands list Global behavior: Topic Detail RPC --rpc-url or env RPC_URL (required for most commands except create-wallet without --import, and list-wallets). Default privacy protocol Env DEFAULT_PRIVACY_PROTOCOL (tornado | railgun | privacy-pools). When set, shield / unshield / private-transfer may omit --protocol, and balances includes that protocol by default. Examples below still pass --protocol / --include explicitly. Data directory --dataDir (default ~/.kohaku-cli). Networks Wallets created with --testnet expect Sepolia (11155111); otherwise mainnet (1). RPC chain ID must match the wallet. --non-interactive Available on every command below. Skips prompts and spinners; prints JSON where applicable. Requires flags documented per command (--password-file or --password, --wallet, amounts, --from, --to / --next, etc.). Use for CI, agents, and piping output. --password-file Preferred for automation on POSIX. Reads the wallet password from a regular, non-symlink file, so the password is not exposed in process arguments. The file must be owned by the current user with mode 0400 or 0600. Secure file inputs fail closed on Windows because ACLs are not validated. Mutually exclusive with --password. --password Legacy wallet unlock input. A literal string or existing file path is accepted for compatibility; prefer the unambiguous --password-file form in scripts. --without-tor Disable Tor for non-RPC HTTP (default: Tor on for private-protocol and Pimlico-backed commands, including transfer / transact-raw / names). Or set KOHAKU_WITHOUT_TOR=1. Ethereum RPC stays clearnet. Review contacts with view-network-traffic. Proving artifacts Railgun, Tornado, and Privacy Pools circuits ship in the kohaku-artifacts package installed with this CLI. Prove and unshield read that package. They are not downloaded. Public-sync cache kohaku fetch-sync-cache installs a verified mainnet snapshot for Railgun, Tornado, and Privacy Pools under /sync-cache-v2. It includes historical Railgun PPOI leaves; Merkle-root validation and the growing tip remain live. Live Subsquid or RPC covers blocks after the snapshot. Sepolia keeps its existing live sync. Existing /public-sync-cache files from older versions are left alone and are not used. Wipe both directories with kohaku clear-tor-cache --public-sync. --password-file removes one trailing line ending and otherwise preserves password whitespace. When unlocking an existing wallet, it also retries the fully trimmed value for compatibility with the legacy --password behavior. New wallets created with --password-file use the preserved value exactly. create-wallet Create a BIP-39 seed wallet encrypted on disk. The argument is a single token (no spaces) and cannot be proving-artifacts, public-sync-cache, or sync-cache-v2 (these are reserved data directories under --dataDir). New seed: records the current chain tip in .stealth-start-block so later balances stealth scans do not walk announcement history from before the wallet existed. Uses --rpc-url / RPC_URL when set; otherwise a public RPC for mainnet or Sepolia (--testnet). Import (--import): scans used public HD indexes via RPC. Writes the current chain tip to .stealth-start-block (same as a new seed) so the first balances stealth scan does not walk historical announcements. Pass --stealth-start-block with no value to opt into the Kohaku-schema floor (mainnet 25700000, Sepolia 11455454), or --stealth-start-block for an explicit floor (values below the ERC-5564 announcer deploy are rounded up to that block). Later, balances --stealth-start-block can still back-date below whatever was written at import. Option Description --testnet Tag wallet for Sepolia instead of mainnet. --import Restore from mnemonic instead of generating a new one. --long-seed Generate a 24-word (256-bit) mnemonic instead of the default 12-word (128-bit). Ignored with --import. --rpc-url Required with --import (or RPC_URL) to scan used addresses. Optional for new wallets when writing .stealth-start-block. --stealth-start-block [block] With --import: write .stealth-start-block. Omit the flag to record the current tip (same as a new wallet). Bare flag: Kohaku floor (mainnet 25700000, Sepolia 11455454). With a number: that block, rounded up to the ERC-5564 announcer deploy if lower. --mnemonic Mnemonic (required with --non-interactive --import). --mnemonic-file Preferred POSIX import input for automation. Reads the mnemonic from an owner-only regular file without following symlinks; fails closed on Windows. Mutually exclusive with --mnemonic. --password Encryption password required with --non-interactive. As before, interactive creation prompts instead of consuming this legacy flag. --password-file Preferred POSIX automation input; see global behavior above. Mutually exclusive with --password. --non-interactive No prompts; no mnemonic box on create. --dataDir Data root. Interactive: encryption password (twice); for --import, masked mnemonic entry. New wallets display the mnemonic once in a warning box. Examples: kohaku create-wallet myWallet --testnet kohaku create-wallet myWallet24 --testnet --long-seed kohaku create-wallet restored --testnet --import --rpc-url "$RPC_URL" kohaku create-wallet restored --testnet --import --rpc-url "$RPC_URL" --stealth-start-block kohaku create-wallet restored --testnet --import --rpc-url "$RPC_URL" --stealth-start-block 10000000 chmod 600 ./wallet-password ./wallet-mnemonic kohaku create-wallet restored-safe --testnet --import --rpc-url "$RPC_URL" --password-file ./wallet-password --mnemonic-file ./wallet-mnemonic --non-interactive list-wallets List wallet names and network kind (mainnet / testnet). Option Description --non-interactive Output `{"wallets":{"name":{"mainnet":true --format json-v1 Opt-in versioned JSON: {kind:"kohaku-cli/wallet-list",version:1,wallets:[{name,network,chainId,caip2}]}. Does not require --non-interactive. --dataDir Data root. The legacy --non-interactive object shape remains unchanged for compatibility. New machine integrations should use --format json-v1; network is mainnet, testnet, or unknown, and caip2 is the CAIP-2 identifier when the network is known. next-fresh-address Derive the next HD public account and print its address. By default the account is also persisted; use --peek to inspect it without writing. Option Description --wallet Wallet (prompt if omitted). --password Unlock password. --peek Print the next fresh address without persisting it (e.g. to craft --tail-calls before unshield --next). --non-interactive Requires --wallet and --password; prints address only. --dataDir Data root. Interactive: wallet picker (if needed), wallet password. Examples: kohaku next-fresh-address --wallet testWallet kohaku next-fresh-address --wallet testWallet --peek kohaku next-fresh-address --wallet testWallet --password "$WALLET_PW" --non-interactive init-profile Publish EIP-5564 stealth viewing/spending keys on the ERC-6538 registry for an HD account. Optionally register (or reuse) a .eth / .gwei / .wei name and set stealth-address-scheme-1 on it. With a name: commit → wait 60s → one EIP-7702 UserOp for reveal/register + reverse + text + registerKeys. With --no-name: a single EOA registerKeys transaction (no 7702). Creates public account index 0 if missing. Provide exactly one of --name or --no-name. Option Description --name Bare label or full name (alice / alice.gwei). Existing owned names are reused. --no-name Skip name registration; only register stealth keys for --index on ERC-6538. --protocol Required when --name is a bare label (no TLD). --index HD account that owns/registers the name and registry entry (default: 0). --years Registration duration when registering a new ENS name (default: 1). GNS/WNS are always 1 year. --wallet Wallet. --password Unlock password. --rpc-url RPC endpoint. --broadcast Sign and submit on-chain. Omit to simulate / print payloads. --owner-priv Derive --index from the seed when that account is not yet in public accounts. --without-tor Disable Tor for non-RPC HTTP (Pimlico when using EIP-7702, etc.). RPC stays clearnet. Or set KOHAKU_WITHOUT_TOR=1. --non-interactive JSON where applicable; requires --wallet and --password. --dataDir Data root. Examples: kohaku init-profile --wallet testWallet --name alice --protocol ens --broadcast kohaku init-profile --wallet testWallet --name alice.gwei --broadcast kohaku init-profile --wallet testWallet --no-name --broadcast export-private-key Export the private key for one public account. The key is printed directly to stdout; handle it as sensitive material. Option Description --wallet Wallet (prompt if omitted). --password Unlock password. --address
Export a persisted public account by address. --index Export by non-negative HD derivation index, even if the account has not been persisted yet. --non-interactive Skip the reveal confirmation; requires --wallet and --password. --dataDir Data root. Provide exactly one of --address or --index. Interactive mode confirms before revealing the key. Examples: kohaku export-private-key --wallet testWallet --index 0 kohaku export-private-key --wallet testWallet --address 0xYourAddress reveal-seed-phrase Decrypt and print the wallet’s BIP-39 seed phrase. Interactive mode asks you to confirm twice before printing (both default to No). Option Description --wallet Wallet (prompt if omitted). --password Unlock password. --non-interactive Skip both reveal confirmations; requires --wallet and --password. Prints the phrase only (no box). --dataDir Data root. Examples: kohaku reveal-seed-phrase --wallet testWallet balances If Railgun history sync succeeds but POI refresh fails, balances remain visible with [ERR: POI data missing]. Affected amounts are shown as unavailable for spending until POI refresh succeeds; JSON includes the POI error under private_balance_freshness.railgun.poiError. Show aggregated public balances (ETH + default ERC-20s for the chain, plus any private tokens discovered), and private balances for the protocols you select. Also prints the wallet profile name (reverse-resolved for HD index 0, if any; JSON: wallet_profile_name). Use see-stealth-meta-address for the stealth meta URI. By default, private balances are included only for DEFAULT_PRIVACY_PROTOCOL (if set). Otherwise only public balances are shown, with a short warning. Pass --include to sync one or more protocols explicitly (required for multiple protocols at once, or for any private balance when the env is unset). Successful private balance checks can be reused for up to one minute from an encrypted wallet-local display cache. Cached sections show when they were checked; JSON includes private_balance_freshness. Use --refresh to sync now. Changes to protocol storage, wallet identity or operation activity invalidate these views. Spending flows always use their normal sync path. If every requested private view is recent, no private wallet or Tor session is opened. Public balances are still fetched. balances always loads already-imported stealth accounts into public totals. It also scans ERC-5564 announcements for new payments (same spinner progress as protocol first-sync). A line of the form Stealth scan from block {start} · {latest - start} blocks prints before that progress bar. --stealth-start-block sets the history floor (and can back-date below the wallet file, down to the announcer deploy block); use --skip-stealth-scan to skip discovery for a faster run. Option Description --wallet Wallet (optional in interactive mode). --password Unlock password. --rpc-url RPC endpoint. --include Comma-separated private protocols to sync (railgun, privacy-pools, tornado). Default: DEFAULT_PRIVACY_PROTOCOL only, or none if unset. --verbose Human: per-address public breakdown + private note list for included protocols. JSON: adds public_account_indexes_by_address and private_notes. --refresh Bypass private balance checks cached within the last minute and sync now. --tokensList Extra ERC-20 addresses (comma- or space-separated), merged with chain defaults. --without-tor Disable Tor for privacy HTTP when syncing private protocols (default: Tor on). Covers Railgun Subsquid/PPOI, Tornado saga/artifacts, Privacy Pools ASP, Pimlico, etc. RPC stays clearnet. Or set KOHAKU_WITHOUT_TOR=1. --stealth-start-block Floor for the ERC-5564 announcement scan (decimal or 0x-hex); skips older history on first/full scan. Can back-date below the wallet .stealth-start-block (often the creation/import tip; as far as the announcer deploy block). When omitted, uses that file if present, otherwise the Kohaku import default (mainnet 25700000, Sepolia 11455454). Not a way to skip scanning. --skip-stealth-scan Skip announcement discovery for this run. Already-imported stealth accounts still appear in public balances. --non-interactive JSON only; requires --wallet and --password. --dataDir Data root. Interactive: wallet picker, password, loading spinner, formatted tables. Default Sepolia ERC-20s include USDC, DAI, and WETH; mainnet adds USDC, USDT, DAI, WETH. Examples: kohaku balances --wallet testWallet --include tornado kohaku balances --wallet testWallet --include railgun,tornado --verbose kohaku balances --wallet testWallet --verbose --include privacy-pools --tokensList 0xYourToken kohaku balances --wallet testWallet --include tornado --without-tor kohaku balances --wallet testWallet --include railgun,privacy-pools,tornado --refresh kohaku balances --wallet testWallet --skip-stealth-scan transfer Transfer ETH or ERC-20 tokens from a public account to a public address or shield them into a private protocol. Set --to to railgun, tornado, or privacy-pools to run shield --protocol with the same sender, amount, and broadcast options. The sender can be a wallet HD index, stored stealth selector, address, or name. External senders use --sender-priv, or a hidden key prompt during an interactive broadcast; their keys are checked against the sender and never saved. Dry runs need no external key. Privacy Pools and Railgun accept arbitrary token amounts subject to token precision, protocol minimums, fees, and available funds. Tornado ETH shields require an exact multiple of 0.01 ETH by default (0.1 with --exclude-new-pools); ERC-20 shields follow their pool denominations. Explicit amounts are never rounded. Set --from to railgun, tornado, or privacy-pools to run the same private transfer as private-transfer --protocol . A Railgun --to 0zk… recipient receives an internal private transfer without unshielding; public recipients receive an exact amount through a fresh account. Protocol-to-protocol transfers are rejected. Omit --broadcast to prepare/simulate a transfer or shield without submitting it. Option Description --wallet Wallet. --password Unlock password. --from Public account address, HD index, stealth selector (s0), or private protocol (railgun, tornado, privacy-pools). --sender-priv Private key for an external sender. Interactive broadcasts prompt with hidden input if the selected address has no stored key. The key must match --from and is not saved. --to Recipient address/name, or railgun, tornado, privacy-pools to shield. --token Token address or symbol (default: eth). --amount-wei Amount in base units. --amount-formatted Human-readable amount using token decimals. --amount-max Maximum recipient amount after estimated fees. Public ERC-20 transfers send the full token balance; public ETH transfers reserve gas using the signed fee caps. --exclude-new-pools With --from tornado or --to tornado, use classic Tornado pools. --exclude-denomination With --to tornado, exclude a denomination in token units (repeatable). --disallow-multiple-userops With --to tornado, require a packing of at most five notes. --skip-sim With --to , skip simulation and fee estimates for a dry run. Cannot combine with --broadcast. --base-fee-gwei , --priority-fee-gwei Shield fee settings with --to . --rpc-url RPC endpoint. --broadcast Sign and submit. Omit to print a public transaction payload or prepared private operation. --without-tor Disable Tor for non-RPC HTTP (Pimlico UserOps, etc.). RPC stays clearnet. Or set KOHAKU_WITHOUT_TOR=1. --non-interactive JSON output; requires --wallet, --password, --from, --to, and one amount flag. --dataDir Data root. Provide at most one of --amount-wei, --amount-formatted, or --amount-max. In interactive mode, omitted sender, recipient, and amount values are prompted. Private protocol sources accept the same options as private-transfer. --sender-priv accepts public senders for both public transfers and shields; --stealth requires a public recipient. --amount-max works in all three flows and reserves the relevant fees and gas; Tornado shields floor it to an allowed denomination. Examples: kohaku transfer --wallet testWallet --from 0 --to 0xRecipient --amount-formatted 0.01 kohaku transfer --wallet testWallet --from 0 --to 0xRecipient --token USDC --amount-max --broadcast kohaku transfer --wallet testWallet --from tornado --to 0xRecipient --amount-formatted 0.1 --broadcast kohaku transfer --wallet testWallet --from railgun --to 0xRecipient --amount-formatted 0.1 --broadcast kohaku transfer --wallet testWallet --from 0 --to tornado --amount-formatted 0.02 --broadcast kohaku transfer --wallet testWallet --from 0 --to privacy-pools --amount-formatted 0.012345 --broadcast kohaku transfer --wallet testWallet --from 0xExternalSender --to railgun --amount-formatted 0.012345 --broadcast # The last command prompts for the external sender's private key; automation uses --sender-priv . transact-raw Simulate or submit one or more raw contract calls from a public account. One call: processed as a normal EOA transaction. Two or more calls: batched into a single EIP-7702 UserOperation (Simple7702Account executeBatch) and submitted via Pimlico. If the sender is not already delegated to 0xe6Cae83BdE06E4c305530e199D7217f42808555B, the EIP-7702 authorization is included in that same UserOp. Option Description --targets Required. Comma- or space-separated contract addresses. --payloads Required. Comma- or space-separated calldata values matching --targets by position. --values ETH value in wei for each call (default: 0 for every call). The count must match --targets. --wallet Wallet. --password Unlock password. --from Sender public account address, HD index, or stealth selector (s0). --sender-priv Private key for an external sender. Interactive broadcasts prompt with hidden input if the selected address has no stored key. The key must match --from and is not saved. --rpc-url RPC endpoint. --broadcast Sign and submit on-chain (single EOA tx, or one batched UserOp for 2+ calls). Omit to simulate and print payloads. --without-tor Disable Tor for non-RPC HTTP (Pimlico UserOps, etc.). RPC stays clearnet. Or set KOHAKU_WITHOUT_TOR=1. --non-interactive JSON output; requires --wallet, --password, and --from. --dataDir Data root. Each target must have one payload and, when provided, one value. Every call is simulated before any transaction is broadcast. Examples: kohaku transact-raw --wallet testWallet --from 0 --targets 0xContract --payloads 0xCalldata kohaku transact-raw --wallet testWallet --from 0 --targets 0xContractA,0xContractB --payloads 0xDataA,0xDataB --values 0,1000000000000000 --broadcast shield Move funds from a public account into a private protocol. Option Description --protocol Required unless DEFAULT_PRIVACY_PROTOCOL is set to one of those values. --wallet Wallet. --password Unlock password. --from Sender public account address, HD index, or stealth selector (s0). --sender-priv Private key for an external sender; interactive broadcasts prompt when no stored key exists. The key must match --from and is not saved. --token Token (default: eth). --amount-wei Amount in base units. --amount-formatted Human amount (uses token decimals). --amount-max Shield the maximum spendable amount. ETH: balance minus estimated gas. ERC-20: full token balance (ETH must still cover gas). Tornado: floored to a multiple of the smallest pool denomination; if gas then knocks the amount below a step, the CLI drops one step and rebuilds. Provide at most one of --amount-wei, --amount-formatted, or --amount-max. --rpc-url RPC endpoint. --broadcast Sign and send on-chain. Omit for dry-run (transaction JSON only). --skip-sim Dry-run only: skip eth_call / UserOp simulation and fee estimates. fees stay in --non-interactive JSON but are zeroed. Cannot be combined with --broadcast. Use this for counterfactual senders (no balance) so you can still print payloads for later --tail-calls. --base-fee-gwei, --priority-fee-gwei Optional fee overrides (reserved; auto fees used today). --without-tor Disable Tor for privacy HTTP (Subsquid / PPOI / saga / ASP / etc.). RPC stays clearnet. Or set KOHAKU_WITHOUT_TOR=1. --non-interactive JSON output; requires --wallet, --password, --from, and an amount flag (--amount-wei, --amount-formatted, or --amount-max). --dataDir Data root. Interactive (no amount / from flags): lists public accounts with balances for the token → amount prompt (or max) → account picker → dry-run JSON or confirmations with --broadcast. --amount-max skips the amount prompt and picks the account first. Protocols: privacy-pools — Any asset the entrypoint has a pool for (mainnet: ETH, USDC, USDT; Sepolia: ETH). Any amount at or above that pool's minimum deposit. The vetting fee is deducted from the deposit and shown in the fee preview. railgun — ETH and ERC-20; non-ETH may need an approval. Approval + shield (2+ calls) are submitted as one EIP-7702 UserOp via Pimlico. tornado — ETH and ERC-20 tokens in the installed SDK's static TornadoInstances catalog that also have SDK paymaster support (src/utils/tornado-pools.ts adapts it for the CLI; mainnet and Sepolia differ). Amount must be an exact multiple of the smallest pool denomination for that asset. Multi-denomination deposits (and any ERC-20 approvals) use EIP-7702 UserOps with up to five deposit notes each. Approvals are aggregated per pool (e.g. 2×1000 + 5×100 → approve 2000 and 500, not seven separate approves). Interactive Tornado shields always offer a note-packing choice. The first option uses the fewest notes; alternatives explicitly exclude denominations, prioritizing individual 3-style sizes before pairs and broader groups (for example exclude only 0.3, only 0.03, then both). Only distinct exact packings are offered, up to four choices, with the option to enter another amount. Each choice shows the note count, denominations used, and transaction count. Confirmation shows a multiline count-by-denomination breakdown, with blank lines separating the sender, full pool addresses, and transaction/fee details. It rounds displayed ETH fee estimates upward to six decimal places; JSON retains exact values. Non-interactive shields use the fewest-note exact packing. Repeat --exclude-denomination to exclude specific sizes in the selected token's normal units, for example --exclude-denomination 3 for the 3 ETH pool. This combines with --exclude-new-pools and does not narrow sync or balances. Tornado shields allow five deposit notes per transaction, automatically splitting larger plans into sequential EIP-7702 UserOps. Approvals do not count as notes and are included independently in each token batch. A single native-note shield still uses an EOA transaction. --disallow-multiple-userops errors before preparing commitments unless the entire packing fits in five notes. Five is a conservative CLI policy, not a protocol limit or a guarantee of simulation success. The CLI estimates every batch before confirming the full plan and combined fee; each send is prepared against current state after the previous transaction has been included successfully with one confirmation. Later estimation/submission/inclusion failures stop the sequence. A shield can complete partially: earlier deposits remain shielded, and the CLI reports their hashes, confirmed amount, and unconfirmed remainder with a nonzero exit status. Non-interactive output includes per-batch status and hashes. An unresolved receipt is labelled unknown; reconcile its saved hash before retrying and never repeat the original full amount blindly. Prepared commitments/calls and progress are saved encrypted in /shield-runs/.json; no automatic replay or resume is performed. --amount-max must also cover the combined estimated batch fees; if its initial reserve is insufficient, the CLI stops before submitting and asks for a smaller explicit amount. When a shield needs more than one on-chain call, the CLI uses EIP-7702 Simple7702Account (0xe6Cae83B…855B) the same way as transact-raw. Examples: kohaku shield --protocol tornado --wallet testWallet --from 0 --amount-formatted 0.1 --broadcast kohaku shield --protocol tornado --wallet testWallet --from s0 --amount-formatted 0.1 --broadcast kohaku shield --protocol tornado --wallet testWallet --from 0 --amount-max --broadcast kohaku shield --protocol railgun --wallet testWallet --from 0 --token 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 --amount-formatted 10 --broadcast kohaku shield --protocol tornado --wallet testWallet --from 0 --amount-formatted 0.1 --without-tor # Counterfactual sender: print payloads without simulating (e.g. to compose unshield --tail-calls) kohaku shield --protocol tornado --wallet testWallet --from 1 --amount-formatted 0.1 --skip-sim --non-interactive unshield Withdraw private balance to a public address. Railgun, Tornado Cash, and Privacy Pools all submit an ERC-4337 user operation. Option Description --protocol Required unless DEFAULT_PRIVACY_PROTOCOL is set to one of those values. --wallet Wallet. --password Unlock password. --to
Recipient: public address, HD index address, stealth selector (s0), or name (.eth / .gwei / .wei). --next Create and use the next fresh public account (mutually exclusive with --to). An index that already has a nonce, balance, or code is saved and skipped. --token Token (default: eth). --amount-wei Amount in base units. --amount-formatted Human amount. --amount-max Maximum spendable amount from one derivation scheme (Railgun: after estimated fees; Privacy Pools: one scheme after its own estimated fees; Tornado: one scheme's unspent notes). --tail-calls Ordered calls appended after the payout. Optional third field is msg.value (hex or decimal wei) — ETH unshields only; ERC-20 tails cannot include msg.value. Tornado ERC-20 tails work for paymaster-supported tokens (Sepolia: DAI; mainnet: DAI, USDC, USDT, WBTC). Railgun ERC-20 tails work for any shielded token; bundler gas is paid from a separate shielded WETH balance, not from the unshielded asset. Tornado and Privacy Pools tails require --next, a stored public HD --to, or a stored stealth --to (sN). Peeked/custom addresses are not allowed. That account is the EIP-7702 delegator: tail calls run there and leftover funds stay there. Railgun tails require a wallet-controlled recipient (--next / HD --to / stealth). --rpc-url RPC endpoint. --broadcast Submit via the protocol bundler or paymaster. Omit to print prepared private operation JSON only. --without-tor Disable Tor for non-RPC HTTP (default: Tor on for all private-protocol network calls). Covers Pimlico (via local reverse proxy), Railgun Subsquid/PPOI, Tornado saga CDN + proving artifacts, Privacy Pools ASP, and other fetch traffic. Ethereum RPC stays on clearnet. First Tor bootstrap may take several seconds. Or set KOHAKU_WITHOUT_TOR=1. --non-interactive JSON; requires --wallet, --password, --to or --next, and an amount flag. --dataDir Data root. Interactive: recipient menu (next fresh / custom address / existing public or stealth account) → amount (shows max: the larger single-scheme amount; Railgun and Privacy Pools after estimated fees; Tornado by that scheme's unspent notes) → a warning only when the withdrawal spends legacy notes → prepared op or broadcast confirmation. Tornado amounts: shields must be an exact multiple of the smallest denomination for that asset (ETH: 0.01 by default, 0.1 with --exclude-new-pools; DAI Sepolia: 100; etc.). New shields use signature-derived secrets. Existing BIP-32 notes and imported note strings stay spendable as legacy notes. A withdrawal spends one derivation scheme. The balance line names the legacy portion only when it is non-zero, and a warning is printed only when that withdrawal spends legacy notes. Wallets with no legacy notes do not mention derivation schemes. --amount-max is the larger single-scheme amount, not the sum of both. Unshield can combine multiple notes of that one scheme in one paymaster UserOp (including ERC-20: fee taken from the first note via quoteWeiInToken, remaining notes withdrawn in the execution phase). For a custom / peeked --to, a single-note withdrawal with no tail calls uses the SDK's default note-derived EIP-7702 executor, recoverable from the note's secrets: both the withdrawal and unused-gas refund go directly to the requested address. The confirmation labels it temporary; the account is not tracked and no public account index is reserved. Multi-note withdrawals instead reserve the next unused public HD account and forward through it. This recoverable executor is saved before preparation, including dry runs and failed or cancelled attempts, so any refund or stranded execution balance appears in normal balances and the index is not reused. --next, stored public HD --to, and stored stealth --to (sN) continue to use that recipient's wallet path. --tail-calls still require one of those wallet-controlled recipients. Every Tornado unshield uses an EIP-7702 executor, including a single note. Confirmation and JSON output show the executor and refund recipient; custom multi-note payouts also show the executor's public account index. ERC-20 tails cannot include msg.value. Shield note indexes: Tornado signature nonces and Privacy Pools deposit indexes each span all pools and assets on the selected chain, with separate sequences for the two protocols. A Tornado packing assigns a distinct nonce to every note, across pool denominations and transaction batches. Before choosing an index, shield preparation refreshes the full protocol history and checks the candidate's commitments/precommitment and spent nullifiers across pools, including deposits submitted outside the CLI. Spent and unspent notes both consume their index. Tornado denomination exclusions restrict the deposit plan, not this freshness check. Checks cover mined history at preparation time; independently prepared or pending external transactions can still race. A discarded preview does not permanently consume an index. Railgun amounts: treasury BPS is added on top of the requested amount so the recipient receives that amount exactly. Bundler / privacy-paymaster gas is always paid from shielded WETH (you need a WETH note even when unshielding USDC). --tail-calls works for ETH and ERC-20; funds already land at to via the privacy paymaster (no leftover-forward baking). ERC-20 tails cannot include msg.value. Privacy Pools amounts: New shields use signature-derived secrets. Existing BIP-32 notes stay spendable as legacy notes. A withdrawal spends one derivation scheme, preferring legacy when those notes cover the net plus that scheme's paymaster fee. The balance line names the legacy portion only when it is non-zero, and a warning is printed only when that withdrawal spends legacy notes. Wallets with no legacy notes do not mention derivation schemes. --amount is the net the recipient receives. The paymaster fee comes out of the private balance on top of that net. Unused gas refunds are explicitly sent to the same recipient, including a custom third-party address, so they may receive a little more than the typed amount. Approved notes are spent largest first; further notes are execution-phase withdrawals in the same user operation. --tail-calls and multi-note withdrawals require --next, a stored public HD --to, or a stored stealth --to (sN). That account signs the EIP-7702 delegation, runs the tail calls, and keeps any change, so custom tails do not have to transfer leftovers out of a hidden account. A custom / peeked --to is allowed only for a single-note unshield with no --tail-calls (the pool pays that address during validation). Sepolia has no paymaster adapter, so unshield fails there until one is configured; shield and balances still work. Withdrawals are not sent through fastrelay. SDK upgrade: Privacy Pools v1 alpha.40 ignores the old wallet protocol cache and rebuilds it once on both networks. Mainnet replays Saga history or the installed public sync snapshot and fetches the RPC tip; Sepolia replays RPC history instead of the retired bundled state. Keys and notes remain recoverable. The CLI shares PPv1 chain state across legacy and signature note scanners. Paymaster broadcasts for Tornado and Privacy Pools wait for a successful UserOperation receipt before reporting completion; bundler acceptance alone is not confirmation. An unconfirmed submission retains its hash in activity and may still land. Stealth recipients: --to s0 (or another stored stealth selector) works for Tornado, Railgun, and Privacy Pools when the stealth private key is in this wallet, including Tornado and Privacy Pools --tail-calls and multi-note amounts (the CLI uses the stored key as the EIP-7702 account). Railgun ERC-20 without --tail-calls can also go to a custom (non-wallet) address. Railgun native ETH unshield and --tail-calls still need a recipient whose key is in this wallet (--next, stored public/stealth address, or sN), because unwrap / tails run on that EIP-7702 account. Examples: kohaku unshield --protocol tornado --wallet testWallet --next --amount-max kohaku unshield --protocol tornado --wallet testWallet --next --amount-formatted 0.1 --broadcast kohaku unshield --protocol tornado --wallet testWallet --to s0 --amount-formatted 0.1 --broadcast kohaku unshield --protocol tornado --wallet testWallet --to s0 --amount-formatted 1 --tail-calls 0x1111111111111111111111111111111111111111:0x1234 --broadcast kohaku unshield --protocol tornado --wallet testWallet --next --amount-formatted 1 --tail-calls 0x1111111111111111111111111111111111111111:0x1234,0x2222222222222222222222222222222222222222:0xabcd:0x2386f26fc10000 --broadcast kohaku unshield --protocol tornado --wallet testWallet --next --token DAI --amount-formatted 100 --broadcast kohaku unshield --protocol tornado --wallet testWallet --next --token DAI --amount-formatted 100 --tail-calls 0x1111111111111111111111111111111111111111:0x1234 --broadcast kohaku unshield --protocol railgun --wallet testWallet --to 0xStoredWalletAddress --token USDC --amount-formatted 25 --broadcast kohaku unshield --protocol railgun --wallet testWallet --next --token USDC --amount-formatted 3 --tail-calls 0x1111111111111111111111111111111111111111:0x1234 --broadcast kohaku unshield --protocol tornado --wallet testWallet --next --amount-formatted 0.1 --without-tor private-transfer Interactive transfers show the protocol's token balance, spendable balance, and available amount after estimated fees before asking for an amount. Railgun also shows private WETH available for gas; a 0zk recipient receives WETH when --token eth is used. Send an exact private amount to someone else. For a public recipient, this unshields through a fresh public account and forwards the amount with a tail call. For a Railgun 0zk recipient, the transfer stays inside Railgun and does not unshield. The 4337 paymaster gas is paid from private WETH. Option Description --protocol Required unless DEFAULT_PRIVACY_PROTOCOL is set. --wallet Wallet. --password / --password-file Unlock password. --to
Final recipient: public address, Railgun 0zk address, stealth selector (s0), or name (.eth / .gwei / .wei). A stealth selector is paid by the tail call; its key is not the delegator. --token Token (default: eth). --exclude-new-pools Tornado only: use classic pools. --amount-wei Exact amount the recipient receives, in base units. --amount-formatted Exact amount the recipient receives. --amount-max Maximum recipient amount after estimated protocol and gas fees. --rpc-url RPC endpoint. --broadcast Submit via the protocol bundler or paymaster. Omit to print the prepared private operation. --without-tor Disable Tor for non-RPC HTTP. --non-interactive JSON; requires --wallet, --password or --password-file, --to, and one of --amount-wei, --amount-formatted, or --amount-max. --dataDir Data root. Use --amount-max (or enter max interactively) to send the available amount after estimated fees. There is no --next or --tail-calls. For public recipients, the fresh account is persisted only after a successful --broadcast. Railgun internal transfers use a fresh wallet-owned 4337 executor, persisted after broadcast, but do not create a fresh receiving account or unshield funds to it. transfer --from railgun, transfer --from tornado, and transfer --from privacy-pools are aliases for this command with the corresponding --protocol value. Tornado: the paymaster fee is taken from the unshielded notes, so the command unshields the smallest note sum that covers the transfer plus that fee. Sending exactly 0.1 ETH from 0.1 notes unshields 0.2. The tail pays 0.1 and the remainder stays on the fresh account. The same rule applies to tokens (--token DAI and the other paymaster fee-adapter tokens). Railgun and Privacy Pools: the unshield net equals the transfer amount, so the tail can drain the fresh account to zero. Railgun's treasury fee is added on top of that amount. Railgun bundler gas is paid from shielded WETH. The Privacy Pools paymaster fee is paid from the private balance on top of the net. On Privacy Pools the fresh account is the delegate and the refund recipient — --to is not. Unused-gas change stays on the fresh account and is not forwarded. Railgun 0zk recipient: private-transfer --protocol railgun and transfer --from railgun prepare a direct Railgun transfer with no unshield or tail call. The amount is the exact private token amount delivered; eth selects private WETH. The signed operation still uses the ERC-4337 paymaster, which charges private WETH for gas. The CLI activity log records the sending 0zk address, receiving 0zk address, UserOp hash, and mined transaction hash when available. Examples: kohaku private-transfer --protocol tornado --wallet testWallet --to 0xFriend --amount-formatted 0.1 --broadcast kohaku private-transfer --protocol railgun --wallet testWallet --to 0xFriend --amount-formatted 0.1 --broadcast kohaku private-transfer --protocol railgun --wallet testWallet --to 0zk1... --amount-formatted 0.1 --broadcast kohaku private-transfer --protocol privacy-pools --wallet testWallet --to 0xFriend --amount-formatted 0.1 --broadcast kohaku private-transfer --protocol tornado --wallet testWallet --to 0xFriend --token DAI --amount-formatted 50 --broadcast import-tornado-note Import legacy Tornado Cash note string(s) into this wallet (deposits that were not made from this mnemonic). Notes are synced against chain state and stored for later unshield / export-tornado-note. Argument Description One or more legacy note strings: tornado----0x… Option Description --wallet Wallet. --password Unlock password. --rpc-url RPC endpoint. --without-tor Disable Tor for privacy HTTP (default: Tor on). --non-interactive No prompts; requires --wallet and --password. --dataDir Data root. Examples: kohaku import-tornado-note --wallet testWallet 'tornado-eth-0.1-11155111-0x…' export-tornado-note Export unspent Tornado Cash note secret(s) for an exact pool denomination (legacy note strings compatible with import-tornado-note). Interactive mode confirms before printing secrets; --non-interactive skips the confirmation. Option Description --wallet Wallet. --password Unlock password. --rpc-url RPC endpoint. --token Token (default: eth). --amount-wei Exact pool denomination in base units. --amount-formatted Exact pool denomination as a decimal. --without-tor Disable Tor for privacy HTTP (default: Tor on). --non-interactive No prompts; requires --wallet and --password. --dataDir Data root. Provide exactly one of --amount-wei or --amount-formatted. Examples: kohaku export-tornado-note --wallet testWallet --amount-formatted 0.1 kohaku export-tornado-note --wallet testWallet --token DAI --amount-formatted 100 --non-interactive Names (.eth / .gwei / .wei) Commands below manage top-level ENS (.eth), GNS (.gwei), and WNS (.wei) names. Shared options: Option Description --wallet Wallet. --password Unlock password. --rpc-url RPC endpoint. --broadcast Sign and submit on-chain. Omit to simulate / print payloads. --owner-priv Derive --index from the seed when that account is not yet in public accounts. --without-tor Disable Tor for non-RPC HTTP (Pimlico when broadcasting UserOps, etc.). RPC stays clearnet. Or set KOHAKU_WITHOUT_TOR=1. --non-interactive JSON where applicable; requires --wallet and --password. --dataDir Data root. --index on most name commands is only needed when the required HD account is not stored in the public accounts list yet (the controller is still a specific seed index). register-name is different: --index selects which account will own the new name (default 0). ENS has separate owner (NFT / registrant) and manager (registry owner for records). GNS/WNS have a single NFT owner only. register-name Register a top-level name: commit → 60s wait → reveal/register. Option Description --protocol Required. Naming system. --name Bare label (alice) or full name (alice.gwei). TLD must match --protocol when present. --index HD account that will own the name (default: 0). --years Duration in whole years (ENS only; GNS/WNS always 1 year). Default: 1. --set-reverse Also set this name as the account’s primary reverse record. Plus shared name wallet options above. Examples: kohaku register-name --wallet testWallet --protocol ens --name alice --years 1 --broadcast kohaku register-name --wallet testWallet --protocol gns --name bob.gwei --index 2 --set-reverse --broadcast renew-name Extend / renew a top-level name. Anyone may pay on-chain; the CLI prefers the name owner when present in the wallet. Interactive mode prompts for --years on ENS (Enter → 1); GNS/WNS always add 1 year. Option Description --name Required. Full name including TLD. --years Extension in whole years (ENS only). Interactive default: 1. --index Only needed when the payer HD index is not stored in public accounts yet (defaults to name owner when present). Examples: kohaku renew-name --wallet testWallet --name alice.eth --years 1 --broadcast kohaku renew-name --wallet testWallet --name alice.gwei --broadcast transfer-name Transfer name ownership and/or ENS manager. GNS/WNS only support NFT owner transfer. Interactive mode prompts for --to and (ENS) --role when omitted; role default is both. Option Description --name Required. Full name including TLD. --to Recipient address or .eth / .gwei / .wei name; prompted if omitted. --role What to transfer (default: both). manager / both are ENS-only; prompted if omitted. --index Only needed when the required HD index is not stored in public accounts yet. Examples: kohaku transfer-name --wallet testWallet --name alice.eth --to 0xRecipient --role both --broadcast kohaku transfer-name --wallet testWallet --name alice.gwei --to bob.gwei --broadcast set-name-text-record Set a text record on a top-level name. Interactive mode prompts for --key / --value when omitted. Option Description --name Required. Full name including TLD. --key Text record key (e.g. url, avatar, com.twitter); prompted if omitted. --value Text record value (empty string clears); prompted if omitted. --index Only needed when the required HD index is not stored in public accounts yet. Examples: kohaku set-name-text-record --wallet testWallet --name alice.eth --key url --value https://example.com --broadcast set-name-website Set the contenthash / website for a top-level name (ipfs:// or bzz://). Interactive mode prompts for --content-hash when omitted. Option Description --name Required. Full name including TLD. --content-hash Must start with ipfs:// or bzz://; prompted if omitted. --index Only needed when the required HD index is not stored in public accounts yet. Examples: kohaku set-name-website --wallet testWallet --name alice.eth --content-hash ipfs://bafy… --broadcast set-name-reverse-record Set a name as the primary reverse record for the signing account. Option Description --name Required. Full name including TLD. --index Only needed when the required HD index is not stored in public accounts yet. Examples: kohaku set-name-reverse-record --wallet testWallet --name alice.eth --broadcast fetch-sync-cache Download the mainnet public sync snapshot into /sync-cache-v2. It contains bounded Railgun Subsquid records, complete historical PPOI leaf pages, and frozen Tornado and Privacy Pools Saga history. A fresh wallet reads that history locally. Live Subsquid or RPC covers blocks after the snapshot; live PPOI handles Merkle-root validation, TXID status, proof submission, and the growing list tip. Sepolia keeps its existing sync path and does not use this snapshot. Each file is checked against its size and SHA-256 in the snapshot manifest. Public files live directly under sync-cache/v2/saga/, sync-cache/v2/railgun/, and sync-cache/v2/ppoi/; verified downloads are stored by hash under /sync-cache-v2/objects/. An interrupted download can be resumed; the CLI activates a snapshot only when every file is present and verified. The previous active v2 snapshot remains usable while a new one downloads. Older /public-sync-cache files are not read by this version. Live mainnet sync also retains complete PPOI leaf pages and indexer ranges at least 128 blocks behind a live observed indexer head in sync-cache-v2/live, shared across wallets and capped at 256 MiB. Heads, incomplete leaf pages, root checks, status and submissions remain live. Existing v2 snapshots remain compatible; this update does not require rebuilding or uploading the published snapshot. Option Description (none) Fetch the snapshot manifest, then install files not already verified on disk. --force Re-download files even when they already verify locally. --without-tor Download over clearnet. Much faster, and reveals only that this IP fetched public pool data. Or set KOHAKU_WITHOUT_TOR=1. --dataDir Data root (cache lives at /sync-cache-v2). --non-interactive JSON summary only. Snapshot base URL: KOHAKU_SYNC_CACHE_BASE_URL (default https://artifacts.0000000000.org/sync-cache/v2). Each file has a five-minute download budget and three attempts. The command exits nonzero if a file fails. Re-run it to resume; partial snapshots are not used for sync. Examples: # Consumers kohaku fetch-sync-cache kohaku fetch-sync-cache --without-tor # Publisher: build a new mainnet snapshot from the live public sources npx tsx scripts/build-sync-cache-v2-saga.ts ./sync-cache-v2-publish 2026-11-01-ppoi npx tsx scripts/build-sync-cache-v2-railgun.ts ./sync-cache-v2-publish 2026-11-01-ppoi npx tsx scripts/build-sync-cache-v2-ppoi.ts ./sync-cache-v2-publish 2026-11-01-ppoi The Railgun builder reads GraphQL queries from a clean local ../kohaku-rs checkout at commit be8862740832a7bac9325270c5b8f8066e32e1d5, matching the pinned WASM package. It can take a while; completed segment files are reused on rerun. The Saga builder verifies the source digest of every sealed and hot chunk before freezing it. The PPOI builder uses the same pinned Rust configuration and freezes only complete historical leaf pages; its source-root checks still happen live in every wallet sync. For a full new snapshot, build on a trusted connection and run both npx tsx scripts/verify-sync-cache-v2.ts ./sync-cache-v2-publish and npx tsx scripts/verify-sync-cache-v2-ppoi.ts ./sync-cache-v2-publish. To extend an already published v2 snapshot, place its current manifest.json in a directory, run only the PPOI builder there, and verify the new files with npx tsx scripts/verify-sync-cache-v2-ppoi.ts . Upload the new ppoi/ directory to the R2 sync-cache/v2/ prefix, then upload the updated manifest.json last. Existing Saga and Railgun objects stay in place. During an update, a download that encounters an old manifest with newly replaced public files will fail verification and can be retried after the new manifest is live. For staging, point KOHAKU_SYNC_CACHE_BASE_URL at a host serving the release and run kohaku fetch-sync-cache --without-tor --dataDir before updating the public manifest. view-network-traffic Browse the per-wallet network traffic log (what the CLI contacted, when, and whether the request went over Tor). Useful for reviewing anonymity risk. Traffic is appended to //network-traffic.ndjson while you use the wallet (balances / shield / unshield / transfer / …). API keys in URLs are redacted before write. Ethereum RPC is always logged as clearnet. Option Description --wallet Wallet (optional interactive picker). --tor-only / --clearnet-only Filter by path. --category pimlico | subsquid | ppoi | saga | asp | fastrelay | artifacts | rpc | other. --limit Last N events only. --json Print JSON (summary + entries). --non-interactive Dump the log to stdout (no scroll UI). --clear Delete this wallet's traffic log. --dataDir Data root. Interactive (TTY): scrollable viewer — j/k or arrows, space/PgDn, g/G top/bottom, q quit. Tor rows are green; clearnet yellow; errors red. Examples: kohaku view-network-traffic --wallet testWallet kohaku view-network-traffic --wallet testWallet --clearnet-only kohaku view-network-traffic --wallet testWallet --category rpc --json kohaku view-network-traffic --wallet testWallet --clear clear-tor-cache Delete the on-disk tor-js Arti cache (~/.local/share/tor-js). Use after Tor bootstrap failures such as corrupted cache / “Unable to bootstrap a working directory”. The next Tor start re-downloads consensus (slower first bootstrap). Option Description --public-sync Also delete /sync-cache-v2 and old /public-sync-cache files. --non-interactive Print JSON { cleared, path } instead of a human message. Examples: kohaku clear-tor-cache kohaku clear-tor-cache --public-sync kohaku clear-tor-cache --non-interactive see-stealth-meta-address Print this wallet’s scheme-1 stealth meta-address URI (st::0x…). Derived from the seed; no RPC required. Option Description --wallet Wallet (prompt if omitted). Required with --non-interactive. --password Unlock password. --non-interactive Requires --wallet and --password; prints the URI only. --dataDir Data root. Examples: kohaku see-stealth-meta-address --wallet testWallet kohaku see-stealth-meta-address --wallet testWallet --password "$WALLET_PW" --non-interactive see-decrypted-storage Debug helper: decrypt and print wallet storage JSON. Argument public | stealth | railgun | privacy-pools | tornado Options Same wallet / password / --non-interactive / --dataDir as other commands. Files include public-accounts.json, stealth storage, rg-v2-storage.json, ppv1-storage.json, and Tornado note storage. The previous Railgun rg-storage.json is preserved during migration. Large protocol-state entries are gzip-compressed inside the encrypted file and decompressed transparently by the CLI. Existing uncompressed entries remain readable and are compressed on the next successful save. Tips Railgun v0.0.16 migration and PPOI recovery Railgun uses kohaku-rg-js-wrapper 0.0.3 with WASM built from kohaku-rs commit be8862740832a7bac9325270c5b8f8066e32e1d5. An existing wallet's old rg-storage.json stays untouched. The first Railgun command rebuilds its history into a separate encrypted rg-v2-storage.json; the CLI explains the resync and shows bounded progress. Each completed history window saves a checkpoint, so an interrupted resync resumes. The first sync can take several minutes, particularly over Tor. Upgrading an existing Rust checkpoint rebuilds its computed Merkle nodes once; later opens restore those nodes directly. Sync checks historical private transactions for missing PPOI and attempts to submit recoverable proofs. The CLI reports submissions, waits, and failures. A submitted proof remains pending until a later PPOI list sync reports it as Valid; missing or unavailable notes cannot be spent. Repeat balances --include railgun later to refresh status and retry pending proof submissions. A blocked shield requires a valid shield POI source and cannot be repaired by submitting its dependent proof alone. Dry run vs broadcast: transfer, transact-raw, shield, unshield, init-profile, and the name commands default to prepare or simulate only. Always read the printed transaction data before adding --broadcast. Tor (all-but-RPC): Non-RPC HTTP (Pimlico, Railgun Subsquid/PPOI, Tornado saga/artifacts, Privacy Pools ASP, …) goes through tor-js by default on balances (when syncing private protocols), shield, unshield, Tornado note import/export, transfer, transact-raw, and name commands. Ethereum RPC stays clearnet. Use --without-tor or KOHAKU_WITHOUT_TOR=1 to skip. Saga CDN is Tor-or-fail (no clearnet fallback; large GETs time out after KOHAKU_TOR_CDN_TIMEOUT_MS, default 45s). Private balance protocols sync concurrently with one progress display; each protocol keeps its legacy and signature writes ordered. Railgun restores its checkpoint in a worker, catches up history, then refreshes PPOI/TXIDs once. Progress shows stable phases, history or cached-leaf counts, and approximate remaining time for measured work. Later phases can have unknown duration. Short requests do not replace phase labels, and an overdue estimate is marked as taking longer than expected. Sync does not download proving keys. Circuits come from the kohaku-artifacts dependency installed with the CLI and are not fetched at prove time. Prefetch mainnet protocol history with kohaku fetch-sync-cache, which verifies a snapshot under /sync-cache-v2. Railgun bounded historical queries, complete historical PPOI leaf pages, and frozen Tornado and Privacy Pools Saga files are served locally; Subsquid head queries, PPOI root validation and tip, Privacy Pools ASP, and RPC remain live. After Tor bootstrap corruption, run kohaku clear-tor-cache. Set KOHAKU_TOR_DEBUG=1 for per-request Tor logs. A keyed RPC URL still identifies you to that provider regardless of Tor. Review with view-network-traffic --wallet . Fresh addresses: Use next-fresh-address before funding, and unshield --next when you want withdrawals to land on a new public key that was not your shield source. Use next-fresh-address --peek to see the next address without persisting it (e.g. when building --tail-calls for a later unshield --next). Do not pass a peeked address as Tornado --to together with --tail-calls — peeked addresses are not stored, so the CLI will refuse rather than 7702 a note-derived key. Profile / stealth: Prefer init-profile to publish ERC-6538 keys (and optionally a name). Unshield to stored stealth accounts with --to s0. Print the meta URI with see-stealth-meta-address. New wallets and imports store .stealth-start-block at the current chain tip so first balances stealth scans skip pre-wallet announcer history. Pass create-wallet --import --stealth-start-block (bare) for the Kohaku-schema floor (mainnet 25700000 / Sepolia 11455454), or an explicit block. Later balances --stealth-start-block can still back-date below the file. Tornado notes: Use export-tornado-note / import-tornado-note to move legacy note secrets between wallets for testing or recovery. Private key / seed exports: export-private-key, reveal-seed-phrase, and export-tornado-note print raw secrets to stdout. Avoid terminal logs, shell history, and shared environments. Agents: Pass --non-interactive --password-file … --wallet … and parse JSON stdout. Set RPC_URL in the environment to avoid repeating --rpc-url. Secret files must be regular files, cannot be symlinks, and on POSIX must be owned by the current user with mode 0400 or 0600 (chmod 600). New Tornado pools (v0.0.12) Tornado includes the extended ETH pools by default: 0.01, 0.03, 0.3, 3, and 30 ETH, plus 10 ETH on Sepolia. They may have small anonymity sets. shield --exclude-new-pools, unshield --exclude-new-pools, and private-transfer --exclude-new-pools restrict the operation to classic pools. This flag is Tornado-only. Every command still syncs the complete pool set first; balances, note import/export, and balance sync always include new pools. The default minimum-fee packing for 2.45 ETH is 2×1 + 0.3 + 0.1 + 0.03 + 2×0.01 ETH. The opt-out rejects 2.45 ETH because classic pools cannot represent it. For 2.4 ETH, default packing is 2×1 + 0.3 + 0.1; classic packing is 2×1 + 4×0.1. --amount-max floors to the minimum denomination permitted by the selected policy. Unshield's opt-out excludes new-pool notes from scheme selection, available balance, and maximum amount. Tornado unshield amounts must be exact sums of the wallet's available whole notes within one derivation scheme. An invalid interactive amount offers the nearest valid lower/higher amounts, their note counts and derivation schemes, or another amount. Explicit command-line amounts fail with the same alternatives instead of being rounded. Alternatives are amounts leaving the pools before paymaster fees, use actual available notes, respect the selected pool policy, and are not limited by shield batch size. Standard unshield confirmation shows the expected recipient amount after the prepared paymaster fee. There is no fixed unshield note-count limit. The SDK estimates and rebuilds the gas limits, fee, proof and signature together. The CLI honors its final gasEstimation status without requiring a second estimate. Standard unshields use the SDK's best-effort policy: recognized estimation availability failures or a single-note zero-execution estimator incompatibility may return conservative fallback gas, with a warning before broadcast. Real validation rejections still stop preparation. User --tail-calls and private transfers require successful estimation. Payloads without SDK metadata still undergo the CLI's strict preflight. The CLI never edits signed gas fields. Fee previews use the fee committed in the prepared proof, in the withdrawn asset; unused gas may refund to the recipient for direct single-note payouts, or the executor for execution-phase withdrawals. Non-interactive prepare and broadcast JSON include gasEstimation (one status per withdrawal) and executor. Fallback gas may cost more or be rejected at bundler admission; an execution failure can leave funds on the executor rather than the final recipient. Tornado SDK alpha.32 includes new direct-paymaster deployments for both mainnet and Sepolia, covering every classic and extended ETH pool plus the existing supported token pools. Pools without SDK paymaster support, including cDAI, are excluded from both shields and unshields. Unshields and private transfers support the new denominations by default. Before proving, the CLI checks that each selected pool is supported by the SDK configuration, that the paymaster is deployed, and that its on-chain instances allowlist permits the pool. An unsupported or disabled pool produces a clear error. --exclude-new-pools still leaves new-pool notes untouched, while balances and sync include all pools. Activity kohaku activity --wallet my-wallet shows transactions submitted by this CLI, newest first. Add --non-interactive for versioned JSON. It uses the wallet password (--password-file is supported) and requires no RPC or protocol sync. The encrypted local log covers shield, unshield, public/stealth/private transfers, raw transactions, ragequit, and name/profile transactions. Each submission records its operation, protocol when applicable, chain, time, UserOp hash when applicable, and actual transaction hash once a receipt is available. Railgun outgoing operations also record the sending 0zk address and final receiving 0x or 0zk address. Reverted operations are marked reverted. A receipt timeout leaves the submission recorded as submitted; activity does not poll or refresh its later status. Dry runs and cancelled commands do not create entries. The log starts with v0.0.12 and does not reconstruct earlier transactions or activity from other tools. Back up the wallet's activity/ directory along with the rest of the wallet. Privacy Pools ragequit Use ragequit to recover the full remaining balance of one unapproved Privacy Pools note to its original depositor. The original depositor must sign and hold ETH for gas. Ragequit reveals the link to that deposit. It applies to unapproved notes, including notes awaiting vetting; it is not for a shield transaction that reverted and never created a deposit. Find the note label in balances --wallet my-wallet --include privacy-pools --verbose, then simulate: kohaku ragequit --wallet my-wallet --label NOTE_LABEL --scheme signature Add --broadcast to submit after reviewing the simulation. The sender defaults to the note's depositor; --from 0, --from s0, or --from ADDRESS selects it explicitly. --sender-priv signs for an external depositor; interactive broadcasts prompt for the key if needed. Unsaved HD indices are derived from the wallet seed automatically. Use --scheme legacy for an older BIP-32 note. Approved notes use unshield instead.