@tokamak-private-dapps/private-state-cli 0.1.8 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## Unreleased
+
+- Changed the channel-bound L2 identity derivation signing domain and mode from password wording
+  to wallet-secret wording. Existing local wallets from the pre-1.0.0 cleanup path are not
+  compatibility targets.
+- Centralized CLI command option schemas used by validation, while keeping the existing command
+  implementations in the single CLI entrypoint.
+- Moved private-state Tokamak L2 snapshot, storage, and leaf-index helpers into a shared CLI library
+  reused by the CLI and registration materialization scripts.
+- Moved runtime install, artifact install, and doctor report helpers out of the CLI entrypoint.
+- Reused the same command registry for CLI help text and the browser command assistant so command
+  additions no longer require three separate hardcoded updates.
+- Made live Docker/NVIDIA GPU probing in `doctor` opt-in through `doctor --gpu`; the default doctor
+  run now reports runtime metadata without launching GPU containers.
+- Shared private-state registration fixture builders between DApp registration materialization and
+  the CLI end-to-end scenario.
+- Moved note receive key derivation and note value encryption/decryption into a CLI library helper
+  reused by the CLI, DApp registration materializer, and CLI end-to-end scenario.
+- Removed the CLI end-to-end runner's trailing-JSON fallback now that CLI progress logs are kept off
+  stdout in `--json` mode.
+- Required public-network private-state DApp deployment scripts to receive an explicit `--rpc-url`
+  instead of deriving deployment RPC endpoints from environment-only Alchemy settings.
+- Replaced local wallet recovery hint string matching with typed CLI error codes for local RPC,
+  wallet, artifact, registration, and stale-workspace failures.
+- Removed unused replay/synthetic snapshot helpers from the CLI end-to-end script.
+- Added deterministic anvil account and wallet secret cleanup to the CLI end-to-end runner so
+  repeated local runs do not fail on stale canonical secret files.
+- Stopped parsing the `install --include-local-artifacts` end-to-end step as JSON because runtime
+  package installation legitimately writes installer logs to stdout.
+- Reused a shared artifact selection helper for Drive and local private-state artifact installs.
+- Removed stale `--install` and `--doctor` compatibility aliases after the command syntax was
+  standardized around positional command names.
+- Tightened local wallet loading to require the current wallet format instead of silently filling
+  legacy defaults.
+- Renamed stale internal wallet-secret terminology consistently around wallet secrets and moved the
+  canonical wallet secret path from `password` to `secret`.
+- Reused private-state CLI shared helpers in the CLI end-to-end test instead of duplicating channel
+  ID, wallet path, and L2 identity derivation logic.
+- Fixed the browser CLI assistant's `create-channel` builder to include required `--join-toll`.
+- Preserved the resolved network name in CLI runtime contexts so account-backed commands and
+  wallet-backed commands can pass the correct network selector into downstream recovery helpers.
+- Routed Groth16 prover package root, entrypoint, and proof-manifest path resolution through
+  runtime management instead of leaving the CLI entrypoint to call internal runtime helper names.
+- Routed Tokamak CLI invocation resolution through runtime management instead of calling internal
+  runtime helper names from the CLI entrypoint.
+- Kept Groth16 prover stdout quiet during `--json` proof-backed commands so machine-readable output
+  remains valid JSON.
+- Verified the full private-state CLI end-to-end flow through channel exit and bridge withdrawal
+  after the runtime-management refactor.
+
+## 1.0.0 - 2026-05-04
+
+- Stabilized the private-state CLI command contract for the first mainnet-ready release.
+- Removed routine raw `--private-key` and `--password` command arguments.
+- Added named local L1 account management through `account import --private-key-file`, with later
+  signing commands using `--account`.
+- Moved wallet commands to wallet-local canonical secret files instead of explicit password input.
+- Added the wallet secret source-file flow for `join-channel --wallet-secret-path <PATH>`.
+- Removed `join-channel --random-wallet-secret`; channel joins now always require
+  `--wallet-secret-path <PATH>`.
+- Relaxed imported source secret file permission checks while keeping canonical CLI secrets
+  protected with POSIX `0600` or Windows ACL repair and inspection.
+- Added per-network RPC URL persistence under the private-state workspace, with `--rpc-url` as
+  the optional bridge-facing override.
+- Renamed private-state CLI commands `--install` and `--doctor` to `install` and `doctor` so
+  commands consistently omit a leading `--`.
+- Replaced the old zk-EVM-only uninstall command with interactive `uninstall`, which removes local
+  private-state data, Tokamak zk-EVM runtime data, and the global CLI package when installed.
+- Added `guide` as the state-aware workflow assistant command.
+- Added `get-channel` for channel policy, toll, refund schedule, and immutable policy snapshot
+  inspection.
+- Added CLI-wide `--json`; commands print human-readable output by default and structured output
+  when requested.
+- Made `doctor` human-readable by default while preserving full machine-readable diagnostics through
+  `doctor --json`.
+- Added durable progress phases for proof-backed commands: `loading`, `proving`, `submitting`,
+  `persisting`, and `done`.
+- Added centralized recovery hints for common RPC, artifact, account, wallet, channel selector,
+  registration, and local-state errors.
+
+## 0.1.9 - 2026-05-03
+
+- Used the bundled Groth16 package version as the default `private-state-cli --install` Groth16 runtime version.
+- Treated stale local Groth16 CRS metadata without `compatibleBackendVersion` as a cache miss so the matching public CRS can be reinstalled.
+
 ## 0.1.8 - 2026-04-30
 
 - Reused common proof backend version helpers for Tokamak and Groth16 compatibility checks.

package/README.md

@@ -2,6 +2,10 @@
 
 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/packages/apps/private-state/docs
+
 ## Install
 
 ```bash
@@ -12,14 +16,15 @@ Install the local Tokamak zk-EVM runtime workspace, Groth16 runtime workspace, a
 artifacts:
 
 ```bash
-private-state-cli --install
+private-state-cli install
 ```
 
-By default, `--install` resolves the latest `@tokamak-zk-evm/cli` and `@tokamak-private-dapps/groth16` versions from
-the npm registry. To pin exact proof backend versions for a channel, pass explicit versions:
+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:
 
 ```bash
-private-state-cli --install --tokamak-zk-evm-cli-version 2.0.8 --groth16-cli-version 0.1.1
+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
@@ -27,11 +32,11 @@ 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.
 
-`--install` downloads public deployment artifacts from the configured artifact index. It does not read repository-local
+`install` downloads public deployment artifacts from the configured artifact index. It does not read repository-local
 `deployment/` outputs by default. Repository development workflows that need local anvil artifacts can opt in explicitly:
 
 ```bash
-private-state-cli --install --include-local-artifacts
+private-state-cli install --include-local-artifacts
 ```
 
 Run the CLI with:
@@ -43,9 +48,20 @@ private-state-cli <command> ...
 Check the installed package and runtime state with:
 
 ```bash
-private-state-cli --doctor
+private-state-cli doctor
+```
+
+Remove all local private-state CLI data with:
+
+```bash
+private-state-cli uninstall
 ```
 
+`uninstall` is intentionally interactive. It requires typing
+`I understand that the wallet secrets deleted due to this decision cannot be recovered` before deleting
+`~/tokamak-private-channels/`, the Tokamak zk-EVM runtime cache, and the global CLI npm package when npm reports that it
+is globally installed.
+
 ## Commands
 
 A common private-state flow is:
@@ -59,27 +75,62 @@ A common private-state flow is:
 7. `get-my-notes`
 8. `redeem-notes`
 9. `withdraw-channel`
-10. `withdraw-bridge`
+10. `exit-channel`
+11. `withdraw-bridge`
 
 Use `private-state-cli --help` for the full command list and required options.
 
-`private-state-cli --doctor` reports the CLI package version, dependency versions recorded by the last
-`private-state-cli --install`, selected proof backend runtime versions, current dependency versions through `tokamak-l2js`, and Tokamak zk-EVM runtime
+Channel policy warning:
+
+- `create-channel` commits to an immutable channel policy: verifier bindings, DApp execution metadata, function layout,
+  managed storage vector, and refund policy are fixed for that channel.
+- `join-channel` 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 doctor` reports the CLI package version, dependency versions recorded by the last
+`private-state-cli install`, selected proof backend runtime versions, current dependency versions through `tokamak-l2js`, and Tokamak zk-EVM runtime
 install mode, Docker mode, CUDA runtime metadata, live `nvidia-smi` and Docker GPU probe results, and Groth16
 runtime health. The doctor check fails when the Tokamak Docker `useGpus` metadata does not match the live GPU probes.
 
 Local helper commands:
 
 ```bash
+private-state-cli account import --account <ACCOUNT_NAME> --network sepolia --private-key-file <PATH>
 private-state-cli list-local-wallets --network sepolia --channel-name cuda
-private-state-cli get-my-wallet-meta --wallet <WALLET_NAME> --password <PASSWORD> --network sepolia
-private-state-cli get-my-l1-address --private-key <HEX>
+private-state-cli get-my-wallet-meta --wallet <WALLET_NAME> --network sepolia
+private-state-cli get-my-l1-address --account <ACCOUNT_NAME> --network sepolia
 ```
 
-`list-local-wallets` reads only the local workspace and prints saved wallet names that can be reused with `--wallet`.
+`account import` is the only supported way to bring an L1 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.
+`join-channel` imports `--wallet-secret-path <PATH>` into the protected wallet-local default secret while creating the
+encrypted local wallet. `list-local-wallets` reads only the local workspace and prints saved wallet names that can be reused with
+`--wallet`.
 `get-my-wallet-meta` opens an encrypted local wallet and reports the stored L1/L2 identity metadata plus the current
 on-chain channel registration match state. `get-my-l1-address` is a simple offline helper that derives the L1 address
-for a private key.
+for a local account.
+
+### Wallet Secret Source File
+
+`join-channel` needs a wallet secret source file because the CLI no longer accepts raw wallet secrets on the command
+line. The source file is arbitrary high-entropy secret text that the CLI reads once and imports into the protected
+wallet-local canonical secret.
+
+Create one before joining a channel:
+
+```bash
+openssl rand -hex 32 > ./wallet-secret.txt
+private-state-cli join-channel --channel-name <CHANNEL> --network sepolia --account <ACCOUNT> --wallet-secret-path ./wallet-secret.txt
+```
+
+The import source file does not need `0600` permissions. The canonical wallet-local secret written by the CLI remains
+protected: macOS/Linux uses `0600`, while Windows uses ACL repair and inspection when possible.
 
 ## Workspace
 
@@ -89,7 +140,14 @@ The CLI stores user workspaces under:
 ~/tokamak-private-channels/workspace/<network>/<channel>/
 ```
 
-Wallet data is encrypted with the password supplied to `join-channel` or `recover-wallet`.
+Wallet data is encrypted with the wallet-local default secret file under
+`~/tokamak-private-channels/secrets/<network>/wallets/<wallet>/secret`.
+
+Bridge-facing commands accept optional `--rpc-url <URL>`. When `--rpc-url` is provided, the CLI stores it in
+`~/tokamak-private-channels/secrets/<network>/.env` as `RPC_URL=<URL>` with protected canonical secret permissions.
+When `--rpc-url` is omitted, the CLI reads `RPC_URL` from that file. The `anvil` network falls back to
+`http://127.0.0.1:8545` when no saved RPC URL exists. Canonical CLI secrets are checked on read: macOS/Linux uses
+`0600`, while Windows uses ACL repair and inspection when possible.
 
 ## LLM Agent Guidance
 
@@ -102,21 +160,24 @@ explaining each step only as much as needed to proceed safely.
 
 Operating rules:
 
-- Do not ask the user to reveal raw private keys in chat. Use environment variable placeholders such as `$ADDR6`,
-  `$CREATOR`, or `$PRIVATE_STATE_TEST_PK`.
+- Do not ask the user to reveal raw private keys or wallet secrets in chat. Use `account import --private-key-file`
+  once, then use `--account` for L1 signing commands. Wallet commands use wallet-local default secret files.
 - Prefer testnet examples unless the user explicitly asks for mainnet.
-- Before any proof-backed or bridge-facing workflow, ask the user to run `private-state-cli --doctor` and inspect
+- Before any proof-backed or bridge-facing workflow, ask the user to run `private-state-cli doctor` and inspect
   whether the runtime, Docker mode, CUDA/GPU probes, Groth16 runtime, and deployment artifacts are healthy.
 - Use `private-state-cli list-local-wallets` to discover local wallet names instead of asking the user to inspect
   filesystem paths manually.
-- Use `private-state-cli get-my-l1-address --private-key "$KEY_ENV"` to derive the L1 address for a private-key
-  environment variable when wallet ownership needs to be identified.
-- Use `private-state-cli get-my-wallet-meta --wallet <WALLET> --password <PASSWORD> --network <NETWORK>` to inspect
+- Use `private-state-cli get-my-l1-address --account <ACCOUNT> --network <NETWORK>` to derive the L1 address for a
+  local account when wallet ownership needs to be identified.
+- Use `private-state-cli get-my-wallet-meta --wallet <WALLET> --network <NETWORK>` to inspect
   local wallet metadata and on-chain channel registration state.
 - Use `private-state-cli get-my-bridge-fund` and `private-state-cli get-my-channel-fund` to check balances before
   telling the user to move funds.
 - Explain that wallet names are local CLI identifiers, while private transfers use notes owned by L2 addresses
   registered in the channel.
+- Before guiding a user through `create-channel` or `join-channel`, explain that channel policy is immutable after
+  creation and that joining a channel means accepting its current verifier, DApp metadata, function layout, managed
+  storage vector, and refund policy.
 - Do not present one fixed command sequence as universally correct. Some flows start from an existing channel or wallet,
   while others require creating or joining a channel first.
 - When the user asks for a transfer, first determine whether the sender has minted notes available. If not, guide them
@@ -128,8 +189,8 @@ Suggested interaction flow:
 
 1. Identify the target network, usually `sepolia` for testing.
 2. Identify whether a channel already exists.
-3. Identify the sender and recipient wallets or private-key environment variables.
-4. Run `--doctor`.
+3. Identify the sender and recipient wallets or local account names.
+4. Run `doctor`.
 5. Run `list-local-wallets` and relevant metadata or balance checks.
 6. If needed, guide the user through `create-channel`, `deposit-bridge`, `join-channel`, `deposit-channel`, and
    `mint-notes`.
@@ -144,7 +205,7 @@ command.
 
 ## Artifacts
 
-Proof-backed commands require installed bridge, DApp, and Groth16 artifacts. Run `private-state-cli --install` before
+Proof-backed commands require installed bridge, DApp, and Groth16 artifacts. Run `private-state-cli install` before
 using bridge-facing commands on a new machine.
 
 Channel balance commands such as `deposit-channel` and `withdraw-channel` use the installed Groth16 runtime workspace
@@ -161,10 +222,10 @@ Release order matters for npm publication. `@tokamak-private-dapps/common-librar
 ### 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`
+It does not install bridge contracts, app contracts, or local deployment outputs. The `private-state-cli install`
 command provisions the local Tokamak zk-EVM and Groth16 runtime workspaces used by proof-backed commands.
 
-### When should I run `private-state-cli --install`?
+### When should I run `private-state-cli install`?
 
 Run it once on a new machine, or after public bridge, DApp, Groth16, or Tokamak zk-EVM runtime artifacts are updated.