private-state CLI

Command-line client for the Tokamak private-state DApp.

The full private-state DApp documentation is published with the repository:

• https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/tree/main/docs/dapps/private-state

The Service Privacy Notice is published in the repository:

• https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/privacy-notice.md

The Service Terms of Service are published in the repository:

• https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/terms.md

Terminology And Exchange Boundary

This npm README uses the same terminology as the repository README:

• Tokamak Private App Channels: Ethereum-settled, validity-proven execution domains for bridge-coupled DApps.
• private-state DApp: the current reference DApp that programs confidential application state inside a channel.
• canonical Tokamak Network Token: the Ethereum mainnet asset whose custody remains anchored on Ethereum.
• self-custody Ethereum wallet: a user-controlled Ethereum account, not an exchange deposit address.
• public bridge edge: public Ethereum mainnet bridge deposit and withdrawal transactions involving the canonical token.
• channel-local accounting balance: liquid application balance inside a channel before or after note use.
• private-state note: a channel-local application note, not an exchange-supported token or deposit asset.
• Join Toll: the one-time Channel entry fee paid when a user joins a Channel.
• proof-backed confidential application state: DApp state advanced by accepted proof-backed channel transitions.
• user-controlled selective disclosure: optional user disclosure from local wallet state; the Provider and Tokamak Network PTE. LTD. do not hold a master viewing key.
• viewing key: the note-receive private key used to decrypt note-delivery events for the registered note-receive public key.
• spending key: the channel-bound private application key used to authorize proof-backed note use.

Tokamak Private App Channels are not an exchange deposit network. Exchange-facing token transfers and bridge entry or exit remain public Ethereum mainnet activity. Internal private-state note counterparty relationships and note provenance are not public by default and are not reconstructed by the Provider or Tokamak Network PTE. LTD. on a user's behalf.

Address And Key-Safety Warnings

Do not use an exchange deposit address as a private-state wallet address. Private-state notes are not supported exchange assets. Always withdraw TON to a self-custody Ethereum wallet before using a channel.

Bridge deposits and withdrawals are public Ethereum mainnet events. Internal note transfers are designed so public contract state does not automatically reconstruct the full note path.

This CLI does not send your spending key, wallet secret, or private note plaintext to the Provider or Tokamak Network PTE. LTD.

Browser Wallet L1 Signing

The CLI supports two L1 signing paths. Supplying --account <ACCOUNT> uses the protected local account secret imported with account import. Omitting --account on supported commands opens a local signing page and asks the user to approve the required L1 action in a MetaMask-compatible browser wallet. The browser-wallet path uses an injected EIP-1193 provider and is not Chrome-specific. The CLI prints the localhost signing URL so the same approval page can be opened in another MetaMask-capable browser when the default browser is not the intended wallet browser.

The localhost page is a request relay, not an approval UI. It starts the wallet provider request when the page loads and returns the provider result to the terminal. Users should approve or reject only in the MetaMask-compatible wallet UI, not in UI provided by the CLI page. During one CLI command, sequential wallet requests use the same localhost origin so the wallet account permission granted at connection can apply to later signature and transaction requests. The relay page stays open and receives later wallet requests from the CLI instead of asking the user to trust a localhost approval button.

Browser-wallet mode avoids CLI access to the raw L1 private key. It does not remove the local private-state wallet key model: channel join still reads --wallet-secret-path once, derives the channel-bound spending key, derives the note-receive viewing key, and stores those L2 keys under the existing protected wallet-key rules. Note commands such as wallet mint-notes, wallet transfer-notes, and wallet redeem-notes still use the local spending key and viewing key for proof generation and note recovery.

When the browser wallet is connected to a different chain than the CLI --network, the CLI asks the wallet to switch to the selected chain with wallet_switchEthereumChain and then verifies eth_chainId again. The command continues only after the user approves the switch and the wallet reports the expected chain. The CLI does not send local RPC URLs or API keys to the browser to add missing chains.

channel join in browser-wallet mode asks the user to approve the following browser wallet requests: account connection, chain check, network switch when needed, the EIP-191 message signature for L2 spending-key derivation, the EIP-712 typed-data signature for note-receive viewing-key derivation, any Join Toll token approval, and the final join transaction. User-Controlled AI Agents must not click browser wallet approval UI for the user.

Proof-backed note commands can also separate local L2 authority from L1 gas payment. Use --tx-submitter <ACCOUNT> to submit executeChannelTransaction through a separate imported local account, or pass --tx-submitter without a value to submit through a browser wallet. If --tx-submitter is omitted and the wallet owner L1 key is not available locally, the CLI falls back to the browser wallet and requires the selected browser account to match the wallet owner address.

Documented Mainnet Channels

The table below lists private-state mainnet channels documented by this package. Dates are UTC.

| Channel name | Channel creator / leader | Created at | Genesis block | Channel manager | | --- | --- | --- | ---: | --- | | the-great-first-channel | 0x32e6EE3d9820F0843E3e596132368747d36425F0 | 2026-05-04 01:30:59 UTC | 25018368 | 0x3108d92A38bFb4B3396DE7ad4D92318a8fbE61D7 |

Install

Prerequisites

Before installing this package, prepare the private-state CLI prerequisites:

• Node.js 18 or newer and npm for installing and running private-state-cli.
• Outbound HTTPS access to the npm registry, the public private-state deployment artifact index, and the public Groth16 CRS archive source.
• A writable home-directory workspace under ~/tokamak-private-channels/ for private-state artifacts, Groth16 workspace files, account secrets, wallet key files, channel workspaces, and proof outputs.
• For private-state-cli install --read-only, no proof runtime prerequisites are needed because read-only mode installs only public bridge and private-state DApp artifacts.
• For private-state-cli install --include-local-artifacts, run the command from a repository or deployment workspace that contains the local deployment/ artifacts you intentionally want to install.
• For private-state-cli install --docker, the private-state Groth16 Docker path requires Docker to be installed and running. The Groth16 Docker path is supported on Linux hosts and Windows hosts with Docker Desktop; macOS hosts should use the native Groth16 path.

Full private-state-cli install also installs and invokes @tokamak-zk-evm/cli. The operating-system, native build toolchain, Docker, CUDA, and network prerequisites for the Tokamak zk-EVM CLI are intentionally not duplicated here. Read the @tokamak-zk-evm/cli README before running full install, especially when using --docker or a GPU-enabled host.

npm install -g @tokamak-private-dapps/private-state-cli

Install the full local Tokamak zk-EVM runtime workspace, Groth16 runtime workspace, and public private-state deployment artifacts needed by transaction-sending channel commands:

private-state-cli install

install accepts optional --network <NAME> to install only that network's deployment artifacts. Mainnet install, and install without --network, opens a local browser page for the current Service Terms and requires explicit human acceptance before installation proceeds. Sepolia and anvil installs do not require Terms acceptance. The browser page is served from 127.0.0.1, uses a one-time local token, and lets the user review the Terms in the browser. After browser acceptance succeeds, the CLI immediately prints that installation is starting before any long-running install work begins. Use --terminal-terms only when the local browser flow cannot be used for a Terms-gated install. The CLI package includes the canonical Terms Markdown and reports its termsVersion and deterministic termsHash in install results. JSON mode cannot accept Terms for the user. For Terms-gated installs, private-state-cli install --json reports that browser-based interactive installation is required and includes Terms references without installing artifacts. The acceptance record is stored in the user's local private-state CLI workspace and is not sent to the Provider by default.

By default, install resolves the latest @tokamak-zk-evm/cli from the npm registry and uses the bundled @tokamak-private-dapps/groth16 dependency version selected by the installed private-state CLI package. To pin exact proof backend versions for a channel, pass explicit versions:

private-state-cli install --tokamak-zk-evm-cli-version 2.1.0 --groth16-cli-version 0.2.0

The Groth16 installer downloads the public Google Drive CRS archive whose major.minor compatibility version matches the selected Groth16 CLI package version. The Tokamak zk-EVM installer requires the selected CLI package to declare tokamakZkEvm.compatibleBackendVersion as a canonical major.minor version matching the selected package version.

For read-only channel recovery, channel metadata lookup, wallet recovery, wallet metadata lookup, bridge balance lookup, bridge deposit, bridge withdrawal, and local helper commands, install only the read-only artifact subset:

private-state-cli install --read-only

Read-only install materializes only bridge.<chainId>.json, bridge-abi-manifest.<chainId>.json, deployment.<chainId>.latest.json, and storage-layout.<chainId>.latest.json. It does not install the Tokamak zk-EVM runtime, Groth16 runtime, Groth16 zkey, callable DApp ABI, or DApp registration artifact, so commands that create or mutate channel state require a later full private-state-cli install.

install downloads public deployment artifacts from the configured artifact index. It does not read repository-local deployment/ outputs by default. Repository development and release-readiness workflows that intentionally need local deployment artifacts can opt in explicitly:

private-state-cli install --include-local-artifacts

When --include-local-artifacts is used, the CLI scans local deployment/chain-id-* directories for the selected DApp and records the final installed artifact source once per chain. Local artifacts override downloaded artifacts for the same chain.

Run the CLI with:

private-state-cli <command> ...

Check the installed package and runtime state with:

private-state-cli help doctor

Print only the installed CLI package version with:

private-state-cli --version

Check npm registry for a newer CLI package and update a global npm install when possible:

private-state-cli help update

update keeps --version suitable for scripts by using a separate command for registry checks. If the CLI is running from a repository checkout or npm does not report a global install, it does not edit local source files; it prints the recommended npm install -g @tokamak-private-dapps/private-state-cli@latest command instead.

Remove local private-state CLI data with:

private-state-cli uninstall

uninstall requires current Service Terms acceptance before the destructive confirmation prompt. It is intentionally interactive. By default, it deletes local workspaces, account secrets, wallet secret source files stored under the CLI root, installed private-state artifacts, the Groth16 workspace, the Tokamak zk-EVM runtime cache, and the global CLI npm package when npm reports that it is globally installed. It preserves wallet spending-key and viewing-key files under the CLI secret root.

To delete every local private-state CLI file, including wallet spending-key and viewing-key files, run:

private-state-cli uninstall --include-wallet-keys

Commands

A common note-use flow after channel policy review is:

1. channel create
2. channel join
3. account deposit-bridge
4. wallet deposit-channel
5. wallet mint-notes
6. wallet transfer-notes
7. wallet get-notes
8. wallet redeem-notes
9. wallet withdraw-channel
10. channel exit
11. account withdraw-bridge

channel join pays any Join Toll directly from the Ethereum wallet; account deposit-bridge funds later channel liquidity and does not pay the Join Toll.

Use private-state-cli help commands for the full command list and required options. private-state-cli --help continues to print the same command list for shell compatibility. Add --json to either form to print the command reference as structured JSON on stdout.

Command Warnings And User Confirmation

The CLI prints warning summaries before commands that send transactions, move funds, accept Channel policy, expose plaintext evidence, or delete local data. These warnings explain whether the command emits public Ethereum mainnet events, whether it changes private-state note state, which addresses or amounts become public, which note facts are not public by default, illegal-use prohibitions, no-recovery limits, and Channel policy acceptance.

Terms acceptance is handled at install and renewal time. Destructive commands and sensitive exports use interactive confirmation prompts. User-Controlled AI Agents must explain warnings to the user, but they must not accept Terms, confirm destructive actions, or handle secret material for the user.

Static warning scope:

| Command | Public surface | Private-state note state | Not public by default | |---|---|---|---| | account deposit-bridge | Ethereum account, bridge vault, amount, approval/funding txs | No note change | No note plaintext or provenance is created | | account withdraw-bridge | Ethereum recipient/account, bridge vault, amount, withdrawal tx | No note change | Prior private-state note path is not reconstructed | | channel join | Ethereum account, channel-local address, note-receive public key, Join Toll, channel id | No note change | Wallet secret, spending key, viewing key, and note plaintext | | wallet deposit-channel | Ethereum submitter, registered channel-local address, amount, channel id, accounting update | No note change | No note provenance is created | | wallet mint-notes | Ethereum submitter, registered channel-local address, commitments, encrypted note events, root update | Creates notes | Note owner, value, salt, and later provenance | | wallet transfer-notes | Ethereum submitter, input nullifiers, output commitments, encrypted note events, root update | Spends and creates notes | Sender-recipient relationship, note plaintext, and provenance | | wallet redeem-notes | Ethereum submitter, input nullifier, accounting update, root update | Consumes notes | Prior path by which the note was received | | wallet withdraw-channel | Ethereum submitter, registered channel-local address, amount, channel id, accounting update | No direct note spend | Prior private-state note path behind the liquid balance |

account deposit-bridge and account withdraw-bridge also print an exchange-controlled address warning. Do not use an exchange-controlled address as a self-custody bridge source or as the direct bridge withdrawal target unless the user explicitly understands the compliance implications. Prefer a self-custody Ethereum wallet.

Workspace recovery commands use saved recovery indexes by default. If the local channel workspace is missing, corrupted, or does not contain a usable index, channel recover-workspace stops with an explicit error instead of silently replaying logs from channel genesis. When the channel has a registered workspace mirror, recover from the mirror first:

private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source mirror

Use channel recover-workspace --source rpc --from-genesis only when no compatible workspace mirror is available and you intentionally want to rebuild channel workspace state from the channel creation block:

private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source rpc --from-genesis

When channel recover-workspace --from-genesis is used, the CLI treats the local channel workspace as a clean rebuild target. If ~/tokamak-private-channels/workspace/<network>/<channel> already exists, it is moved under ~/tokamak-private-channels/workspace-rebuild-backups/ before the current-format workspace is created. This backup step is workspace-only; files under ~/tokamak-private-channels/secrets/, including account private keys and wallet viewing/spending key files, are not removed. During RPC recovery, the CLI writes a usable channel workspace checkpoint after each RPC log chunk. If an RPC recovery run is interrupted, the next non---from-genesis RPC recovery resumes from the last completed chunk. Mirror recovery can also start from that local checkpoint: it uses a matching delta bundle when one is available, otherwise a newer verified full mirror checkpoint replaces the local checkpoint before RPC catch-up.

Use channel recover-workspace --source rpc --output-raw when you need to preserve the raw JSON-RPC request and response history for inspection. The CLI appends calls to method-specific JSON files, and splits eth_getLogs into event-specific files such as eth_getLogs.CurrentRootVectorObserved.json, under ~/tokamak-private-channels/workspace/<network>/<channel>/channel/rpcCallHistory/. Indexed recovery appends to the existing history, while --from-genesis overwrites it with one full genesis-to-latest scan.

channel create is the exception: after the channel is created on-chain, the CLI initializes that new local workspace by replaying from the channel's genesis block because no prior recovery index can exist for a new channel.

channel join refreshes stale channel workspace state through the saved recovery index before submitting the registration transaction. For a channel that was created elsewhere, recover from a registered workspace mirror first. Use channel recover-workspace --source rpc --from-genesis only when no compatible mirror is available; later joins and wallet commands resume from the saved index instead of silently replaying from genesis.

Wallet commands that need channel state, including wallet recover-workspace, wallet get-meta, wallet get-channel-fund, and wallet get-notes, refresh stale local channel workspaces through saved recovery indexes before reading state. wallet get-notes and wallet recover-workspace also refresh received-note logs through the saved wallet note recovery index. Wallet note freshness is measured against the fresh channel workspace frontier, not the provider's latest Ethereum mainnet block, so unrelated new Ethereum mainnet blocks do not make a wallet stale by themselves. Automatic refresh never replays from channel genesis and only runs when the recovery delta fits within the 7,200-block pre-command budget. If a saved index is missing, unusable, or too far behind, the command stops and asks the user to run the appropriate recovery command first.

Wallet note-delivery recovery checkpoints after each RPC log chunk by updating noteReceiveLastScannedBlock. If an ordinary wallet recover-workspace run is interrupted during note recovery, the next run resumes from the last completed chunk. This does not add a special resume path for wallet recover-workspace --from-genesis; that command intentionally starts received-note scanning from channel genesis after the channel workspace has passed the same freshness preflight used by other wallet commands.

Local wallet workspaces are epoch-aware. Each successful channel registration creates a wallet epoch under the canonical wallet directory. channel exit does not delete the local wallet workspace; it marks the active epoch as exited with the exit transaction, block, and timestamp, then keeps that epoch read-only for historical note inspection and evidence export. If the same account later joins the same channel again, the new registration is a separate active epoch under the same canonical wallet name.

The current CLI only supports this epoch-aware wallet workspace layout. If a local wallet directory was created by an older CLI and does not contain wallet-index.metadata.json plus epochs/<epoch-id>/ metadata files, rebuild it with wallet recover-workspace before using wallet commands.

Channel leaders can optionally register a workspace mirror server so users can bootstrap recovery from a signed checkpoint and download only the local-to-checkpoint delta when a local recovery index already exists. The channel leader can build the static mirror files with channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH> after recovering the channel workspace, and then deploy the output directory to the registered mirror host. If the existing mirror manifest is unreadable or invalid, add --force to write a full checkpoint without trusting that remote manifest as a delta base. The CLI protocol is documented at https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/channel-workspace-mirror-protocol.md.

Channel public observer URLs are also Channel-scoped. The CLI does not use a Tonigma-wide observer URL. To open a Channel's public observer, read the URL registered in that Channel's on-chain metadata:

private-state-cli help observer --channel-name <CHANNEL> --network mainnet

If no observer URL is registered, ask the Channel Provider for the correct observer location. A static observer URL in documentation is only an example for a specific Channel and is not a default for every Channel.

Back up a local wallet with:

private-state-cli wallet export backup --network mainnet --wallet <WALLET> --output ./wallet-backup.zip

Mainnet backup export requires current Service Terms acceptance. Sepolia and anvil backup exports do not require Terms acceptance. The backup export stores note-tracking metadata and the channel workspace cache, but it does not include spending keys, viewing keys, key derivation material, or plaintext note secrets. Note records in the backup keep commitments, nullifiers, and encrypted note payloads only; owner, value, and salt are excluded. Importing this backup restores encrypted tracking state and channel cache files, not wallet authority.

private-state-cli wallet import backup --network mainnet --input ./wallet-backup.zip

Mainnet imports, and imports without a network selector, require current Service Terms acceptance. Sepolia and anvil imports can pass --network sepolia or --network anvil to run without interactive Terms acceptance.

Export viewing and spending authority separately:

private-state-cli wallet export viewing-key --network mainnet --wallet <WALLET> --output ./wallet-viewing.key
private-state-cli wallet export spending-key --network mainnet --wallet <WALLET> --output ./wallet-spending.key

On mainnet, these export commands are intentionally interactive. They print a warning summary and require the user to type the exact confirmation phrase before writing secret-bearing .key files. Sepolia and anvil key exports do not require interactive confirmation. A viewing-key export can reveal readable note history when other required wallet state is available. A spending-key export can authorize note use when other required wallet state is available. Do not send exported key files to User-Controlled AI Agents, support channels, or untrusted parties.

Import those capabilities only when the target machine should receive them:

private-state-cli wallet import viewing-key --network mainnet --input ./wallet-viewing.key
private-state-cli wallet import spending-key --network mainnet --input ./wallet-spending.key

A backup plus a viewing key can reconstruct the wallet's readable note view from encrypted events, but it still cannot spend notes. A backup plus a spending key is still missing event-log decryption authority. A normal operational restore imports the backup, the viewing key, and the spending key, and still needs the relevant local Ethereum account secret for commands that submit bridge or channel-registration transactions.

Export a local full-note evidence bundle with:

private-state-cli wallet get-notes --network mainnet --wallet <WALLET> --export-evidence ./wallet-evidence.zip

On mainnet, this export is intentionally interactive. The CLI prints a warning summary and requires the user to type the exact confirmation phrase before writing plaintext evidence. Sepolia and anvil evidence exports do not require interactive confirmation. The raw ZIP is an input for private-state-cli investigator. It contains plaintext for all locally known notes, derived commitments and nullifiers, creation and spend transaction references, transaction calldata, receipts, events, and indexes for filtering by note, nullifier, transaction, block range, or available counterparty metadata. It includes all local epochs for the selected wallet, including exited epochs retained after channel exit. It does not include viewing keys, spending keys, wallet secret material, account private keys, or .key files. User-Controlled AI Agents must not confirm this export or receive the raw ZIP. Do not submit the raw ZIP as an exchange or auditor package unless full wallet-history disclosure is intended.

Open the local evidence investigator with:

private-state-cli investigator

The command prints the bundled investigator HTML path and file URL, then opens the static browser GUI. Load the raw evidence ZIP in that GUI, choose the disclosure request type, inspect the interactive note-linkage graph, and export a narrower user-consent disclosure ZIP. The graph view renders every matched note as a node and shows creation, spend, and local note-to-note linkage edges when the raw bundle contains enough local evidence. The GUI can also export a Markdown plain-text linkage report with a compact graph section and per-note detail sections. The GUI runs locally in the browser and does not send files over the network.

The investigator accepts current epoch-aware evidence bundles only. If a bundle was generated by an older CLI, rebuild the wallet workspace with wallet recover-workspace and export a new bundle with wallet get-notes --export-evidence.

Estimate live transaction costs before sending commands with:

private-state-cli help transaction-fees --network mainnet

help transaction-fees uses the measured gas data packaged in assets/tx-fees.json, the selected network's live fee data, and live ETH/USD pricing to print an ETH/USD fee table for transaction-sending commands. The table separates typical cost, based on the RPC gasPrice, from worst-case cost, based on maxFeePerGas when the network reports EIP-1559 fee data. Use private-state-cli help transaction-fees --network <NETWORK> --json when another tool needs machine-readable fee data.

Proof-backed note commands can use a separate Ethereum transaction submitter:

private-state-cli wallet mint-notes --wallet <WALLET> --network mainnet --amounts '[1]' --tx-submitter <ACCOUNT>

--tx-submitter <ACCOUNT> is available on wallet mint-notes, wallet transfer-notes, and wallet redeem-notes. The wallet still proves note ownership and builds the ZK proof, but the selected local account submits executeChannelTransaction and pays gas. Use this option when a separate imported local account should submit the transaction on the selected network and pay gas for a proof-backed note command. Use --tx-submitter without a value when the L1 submitter should be selected in a MetaMask-compatible browser wallet instead. In both cases, the local wallet spending key remains the authority for the private-state note transition.

wallet transfer-notes takes JSON arrays for note selection and outputs. --note-ids is a JSON array of input note commitment IDs from wallet get-notes; --recipients is a JSON array of recipient channel-local addresses; --amounts is a JSON array of token amounts. Quote decimal amounts to avoid shell or JSON ambiguity. The recipient count must match the amount count, only 1->1, 1->2, and 2->1 transfer shapes are supported, and the output amount sum must equal the selected input note value sum.

private-state-cli wallet transfer-notes \
  --wallet <WALLET> \
  --network mainnet \
  --note-ids '["0xNOTE1","0xNOTE2"]' \
  --recipients '["0xRECIPIENT1","0xRECIPIENT2"]' \
  --amounts '["1.5","2"]' \
  --tx-submitter <ACCOUNT>

Channel policy warning:

• channel create commits to an immutable channel policy: verifier bindings, DApp execution metadata, function layout, managed storage vector, and refund policy are fixed for that channel.
• channel join means the user accepts the channel's current policy. Later policy-level fixes require a new channel or migration; the existing channel is intentionally not mutated in place without renewed user consent.
• Before sending a channel-creation transaction or a first channel-registration transaction, the CLI prints the policy snapshot that will be accepted: DApp metadata digest, digest schema, Groth16 verifier address, Groth16 compatible backend version, Tokamak verifier address, and Tokamak compatible backend version.
• Users and operators must review this snapshot before signing. If any digest, schema, verifier address, or compatible backend version is unexpected or has not been reviewed, do not create or join the channel. A later correction creates a new channel; it does not rewrite the policy of an already-created channel.

private-state-cli help doctor reports the CLI package version, dependency versions recorded by the last private-state-cli install, selected proof backend runtime versions when full mode was installed, current dependency versions through tokamak-l2js, Tokamak zk-EVM runtime install mode, Docker mode, CUDA runtime metadata, live nvidia-smi and Docker GPU probe results, Groth16 runtime health, deployment artifact readiness, and per-command availability. In read-only install mode, proof runtime checks are skipped and proof-backed or channel-mutating commands are reported unavailable until full install is completed.

Local helper commands:

private-state-cli secret create-private-key-source --output ./ethereum-private-key.txt
private-state-cli account import --account <ACCOUNT_NAME> --network mainnet --private-key-file ./ethereum-private-key.txt
private-state-cli account get-l1-address --account <ACCOUNT_NAME> --network mainnet
private-state-cli account get-l1-address --network mainnet
private-state-cli secret create-wallet-secret-source --output ./wallet-secret.txt
private-state-cli wallet list --network mainnet --channel-name <CHANNEL>
private-state-cli wallet get-meta --wallet <WALLET_NAME> --network mainnet
private-state-cli wallet export backup --network mainnet --wallet <WALLET_NAME> --output ./wallet-backup.zip
private-state-cli wallet import backup --network mainnet --input ./wallet-backup.zip

The networkless secret create-private-key-source and secret create-wallet-secret-source helper commands require current Service Terms acceptance before they run. secret create-private-key-source prompts in the terminal with masked input and creates a local source file for account import. account import is the only supported way to bring an Ethereum signing key into the CLI: it reads --private-key-file once and stores a protected local account secret for later --account use. The source file does not need 0600 permissions. secret create-wallet-secret-source prompts in the terminal with masked input by default and creates a local wallet secret source file for channel join. Use --random only when a random wallet secret is explicitly wanted. channel join reads --wallet-secret-path <PATH> once while creating the channel-bound spending key and then stores wallet backup metadata, viewing-key metadata, and spending-key metadata as separate files. wallet list reads only the local workspace and prints saved wallet names that can be reused with --wallet. wallet get-meta opens the wallet metadata and reports the stored Ethereum/channel-local identity metadata plus the current on-chain channel registration match state, including the registered note-receive public key when present. On epoch-aware wallet workspaces it also reports the selected wallet epoch and whether that epoch is active or exited. account get-l1-address --account <ACCOUNT_NAME> is a simple offline helper that derives the Ethereum address for a local account. Omitting --account opens the browser-wallet path and reports the selected browser account address.

Wallet Secret Source File

channel join needs a wallet secret source file because the CLI no longer accepts raw wallet secrets on the command line. The source file is secret text that the CLI reads once for channel-bound spending-key derivation. It is not persisted in the wallet workspace.

After current Service Terms acceptance is recorded, create one before joining a channel:

private-state-cli secret create-wallet-secret-source --output ./wallet-secret.txt
private-state-cli channel join --channel-name <CHANNEL> --network mainnet --wallet-secret-path ./wallet-secret.txt

Add --account <ACCOUNT> only when the join should use an imported local account alias instead of browser-wallet L1 signing.

The default helper flow lets the user type a wallet secret so it can be retained more easily. If random generation is explicitly wanted, run private-state-cli secret create-wallet-secret-source --output ./wallet-secret.txt --random.

The import source file does not need 0600 permissions. The CLI does not persist a wallet-local secret: it reads the source once for channel-bound spending-key derivation. The join flow stores the viewing key and spending key as separate protected key files under the CLI secret root; macOS/Linux uses 0600, while Windows uses ACL repair and inspection when possible.

Keep the wallet secret source separately backed up if you expect to rederive the spending key later. The viewing key can be rederived from the same Ethereum account signing authority and channel context because it comes from the note-receive typed-data signing flow. The spending key needs the same Ethereum account signing authority, the same channel context, and the same wallet secret source. If the spending-key file is lost and the wallet secret source is also lost, no recovery method exists for the spending key and the notes for that wallet cannot be spent, transferred, or redeemed through the normal note flow.

wallet recover-workspace restores the viewing key by default. Add --wallet-secret-path <PATH> only when the account is currently active in the channel and you need to rederive the spending key. In that mode, the CLI checks the derived channel-local address and channel token-vault storage key against the current on-chain registration before received-note recovery starts, then stores the protected spending-key file. Exited or non-active accounts must be recovered without --wallet-secret-path; that restores viewing/evidence history but not spending authority. The wallet secret source is read for derivation and is not stored.

Wallet Backup, Viewing, And Spending Authority

The wallet workspace is split so that a backup is not a full-control wallet export. Backup metadata stores the recoverable local view of the channel: commitments, nullifiers, encrypted note-delivery payloads, scan checkpoints, operation history, and the channel workspace cache. It deliberately omits plaintext note fields and key material.

The viewing key is the note-receive private key. It lets wallet get-notes decrypt bridge-propagated encrypted note-delivery events and rebuild the user's readable note view. Sharing it gives read access to notes addressed to the registered note-receive public key, but not spending authority.

The spending key is the channel-bound private application key. It authorizes proof-backed use of the wallet identity. Commands that create or consume notes, such as wallet mint-notes, wallet transfer-notes, and wallet redeem-notes, need both the viewing key and the spending key because the CLI refreshes the readable note workspace after accepted note transactions and then proves authorized note use when inputs are consumed.

Key recovery is intentionally split. Recreating the viewing key requires the original Ethereum account signing authority and the same channel context. Recreating the spending key requires the original Ethereum account signing authority, the same channel context, and the same wallet secret source used at channel join. wallet recover-workspace --wallet-secret-path <PATH> performs this spending-key rederivation only for active channel registrations. Importing wallet-viewing.key or wallet-spending.key restores the corresponding capability without rerunning derivation, but a backup ZIP alone never restores either capability.

wallet get-notes --export-evidence <PATH> writes a local raw evidence ZIP. Mainnet export requires interactive confirmation; Sepolia and anvil export do not. The bundle is not a key export. It includes plaintext note facts for locally known notes and may include retained exited epochs for the selected wallet, so it can reveal sensitive wallet history. private-state-cli investigator can create narrower consent-disclosure packages without requiring viewing-key or spending-key sharing. User-Controlled AI Agents must not confirm the export or receive the raw ZIP.

Workspace

The CLI stores user workspaces under:

~/tokamak-private-channels/workspace/<network>/<channel>/

Wallet backup metadata lives under the channel workspace. Viewing and spending private keys live as separate protected key files under ~/tokamak-private-channels/secrets/<network>/wallets/<wallet>/.

Configure the network RPC endpoint before bridge-facing or wallet recovery commands:

private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --provider ankr

The CLI writes ~/tokamak-private-channels/workspace/<network>/rpc-config.env and later commands read RPC_URL, LOG_CHUNK_SIZE, LOG_REQUESTS_PER_SECOND, and RPC_BLOCK_RANGE_CAP from that file. Built-in provider limits are set to 90% of the provider reference values: Ankr 27 calls/s, 3000 blocks; Chainstack 22.5 calls/s, 100 blocks; Chainnodes 22.5 calls/s, 20000 blocks; QuickNode 13.5 calls/s, 5 blocks; Alchemy 7.497 calls/s, 10 blocks. If the provider is not listed, use --log-requests-per-second <N> and --block-range-cap <N> instead of --provider.

Slow Workspace Recovery

channel recover-workspace and wallet recover-workspace scan on-chain logs with eth_getLogs. If recovery is unexpectedly slow, first check the RPC scan limits saved by set rpc. The main speed factors are the provider's eth_getLogs block range cap and the allowed log request rate. A small block range cap can turn the same channel scan into thousands of RPC calls.

For example, an Alchemy free-tier-style cap of 10 blocks is much slower for long recovery scans than Ankr's built-in 3000 block setting or Chainnodes' built-in 20000 block setting. When recovery is too slow, re-run set rpc with a provider that supports a larger eth_getLogs block range cap, or provide explicit values:

private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --provider ankr
private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --log-requests-per-second <N> --block-range-cap <N>

If an RPC provider rejects the configured range or rate during recovery, run set rpc again with limits that match the provider's documented eth_getLogs policy, then retry the recovery command.

Canonical CLI secrets are checked on read: macOS/Linux uses 0600, while Windows uses ACL repair and inspection when possible.

User-Controlled AI Agent Guidance

User-Controlled AI Agents that help users operate this CLI should start with the state-aware guide in JSON mode:

private-state-cli help guide --json

The JSON guide is the machine-readable entrypoint for deciding the next safe instruction to give the user. Read agentGuidance from the result:

• agentGuidance.source identifies the instruction file, currently agents.md
• agentGuidance.refs lists the indexed items in that file that apply to the next step
• agentGuidance.step is the symbolic guide step that selected those refs
• agentGuidance.termsSource identifies the Terms document
• agentGuidance.termsRefs lists the Terms sections the agent must read and explain for legal and safety context

The purpose of --json mode is to let the user's AI agent guide the user through the smallest safe next action while preserving the user's informed consent. JSON output is an instruction surface for the user's tool. It is not permission for the tool to bypass human review, accept Terms, confirm destructive actions, confirm sensitive exports, or handle secret material. When a command reports required warnings, prohibitions, Terms, Channel policy, or Provider Party and Channel Operator disclaimers, the agent must explain those points to the user and must not accept Terms or confirmations on the user's behalf.

After reading the referenced agents.md items and Terms sections, translate the recipe into a short, safe instruction for the user. Do not ask users to paste raw private keys, wallet secrets, seed phrases, provider passwords, or provider dashboard access into a conversation or prompt. Use the CLI's local helper commands for secret source files.

Human private-state-cli help guide output is for people. It provides one plain next step. User-Controlled AI Agents should prefer help guide --json when deciding what to read and what safe instruction to give next.

When --json is used, the CLI follows one output contract for all commands:

• the final success result is one JSON object on stdout
• command failures are one JSON object on stdout with ok: false
• progress, warning, and informational events are JSON Lines on stderr
• human-readable mode remains the default when --json is omitted
• Terms-gated install --json reports that browser-based interactive Terms acceptance is required, includes Terms references, and does not install artifacts
• install results include canonical Terms metadata: termsVersion, termsHash, termsHashAlgorithm, and Terms source paths

Agents should parse stdout for the final result and may stream stderr JSONL events to explain progress to the user.

Artifacts

Proof-backed and channel-mutating commands require full installed bridge, DApp, and Groth16 artifacts. Run private-state-cli install before creating, joining, exiting, or mutating channels on a new machine. Channel-state read commands and commands unrelated to channel state can run after private-state-cli install --read-only.

Channel balance commands such as wallet deposit-channel and wallet withdraw-channel use the installed Groth16 runtime workspace directly. Proof generation writes to the fixed workspace paths under ~/tokamak-private-channels/groth16/proof; the CLI does not pass custom --zkey, proof-output, or public-output paths to the Groth16 prover. Before proof generation, the CLI compares the target channel's verifier compatibility versions with the installed Tokamak zk-EVM and Groth16 major.minor compatibility versions.

Release order matters for npm publication. @tokamak-private-dapps/common-library and @tokamak-private-dapps/groth16 must be published before this package version.

FAQ

What does this package install?

It installs the private-state-cli terminal command and the local files needed by that command. It does not install bridge contracts, app contracts, or local deployment outputs. The private-state-cli install command defaults to full mode, which provisions local Tokamak zk-EVM and Groth16 runtime workspaces used by proof-backed commands. private-state-cli install --read-only installs only the public bridge and private-state DApp artifacts needed by channel-state read commands and commands that do not depend on channel state.

When should I run private-state-cli install?

Run full install once on a machine that will create, join, exit, or mutate channels. Run read-only install on a machine that only needs channel recovery, wallet recovery, metadata lookup, bridge balance lookup, bridge deposit or withdrawal, and local import/export/helper commands. Re-run the relevant mode after public bridge, DApp, Groth16, or Tokamak zk-EVM runtime artifacts are updated.

Does this package publish private user data?

No. User wallets and channel workspaces are created locally under ~/tokamak-private-channels/. Bridge-facing commands still submit public transactions and proof-backed state transitions to the selected network. For the current private-state DApp, commitments, nullifiers, and encrypted note-delivery events are part of the DApp-programmed public disclosure surface, while note plaintext, note ownership, and note provenance remain controlled by user-held secrets and implemented wallet tooling.