@vultisig/cli 2.19.18 → 2.20.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @vultisig/cli
 
+## 2.20.0
+
+### Minor Changes
+
+- [#1284](https://github.com/vultisig/vultisig-sdk/pull/1284) [`1c4fc80`](https://github.com/vultisig/vultisig-sdk/commit/1c4fc80be959af4b650e32b4db30859f449dfa60) Thanks [@rcoderdev](https://github.com/rcoderdev)! - Expose generic CosmWasm Amino and protobuf execute builders from the root SDK and reuse the canonical Amino envelope in the CLI.
+
+- [#1128](https://github.com/vultisig/vultisig-sdk/pull/1128) [`f885e91`](https://github.com/vultisig/vultisig-sdk/commit/f885e91da06674dbef2ca1495291ca7d201e4c58) Thanks [@rcoderdev](https://github.com/rcoderdev)! - Add first-class XRP DestinationTag support alongside transaction memos.
+
+### Patch Changes
+
+- [#1234](https://github.com/vultisig/vultisig-sdk/pull/1234) [`3f4ead5`](https://github.com/vultisig/vultisig-sdk/commit/3f4ead52fe5722a9c22ebf0aa517fba41c1c86a9) Thanks [@neavra](https://github.com/neavra)! - Support JSON-formatted per-vault passwords for names with spaces and document the complete headless credential setup flow.
+
+- [#1259](https://github.com/vultisig/vultisig-sdk/pull/1259) [`955486c`](https://github.com/vultisig/vultisig-sdk/commit/955486cd3c749888ce9d37a0b8a0b59eabc8ac0d) Thanks [@neavra](https://github.com/neavra)! - Persist direct transaction confirmation and failure resolutions in the shared broadcast journal.
+
+- [#1304](https://github.com/vultisig/vultisig-sdk/pull/1304) [`63f7b6c`](https://github.com/vultisig/vultisig-sdk/commit/63f7b6c4d01b5bec5552c7002ee936b9486908fa) Thanks [@neavra](https://github.com/neavra)! - Report failed or declined agent signing, non-success turn outcomes, stale sessions, invalid command input, and permanent raw-broadcast validation errors with truthful non-success envelopes and typed exit codes.
+
+  Exit codes change for previously-mis-reported paths, so callers branching on `$?` should re-check: a declined/failed agent sign now exits non-zero (`CONFIRMATION_REQUIRED`/12 for a decline) instead of 0; a failure that follows an on-chain broadcast exits `BROADCAST_COMMITTED`/13 (never a retryable code); `send` to a malformed address now exits `INVALID_ADDRESS`/4 instead of `USAGE_ERROR`/1, matching the documented table and `address-book`.
+
+- [#1280](https://github.com/vultisig/vultisig-sdk/pull/1280) [`5b99730`](https://github.com/vultisig/vultisig-sdk/commit/5b99730019a462bb8489dd32d154483f705b2a23) Thanks [@neavra](https://github.com/neavra)! - Give `tx-status` a dedicated `INVALID_HASH` error before vault access and expose consistent CLI-facing statuses: `pending`, `not_found`, `confirmed`, and `failed`.
+
+- [#1233](https://github.com/vultisig/vultisig-sdk/pull/1233) [`88f0ee6`](https://github.com/vultisig/vultisig-sdk/commit/88f0ee617627fa85b0ff5057c4adcd7f1927e81d) Thanks [@neavra](https://github.com/neavra)! - Classify agent errors that occur after a transaction broadcast as a non-retryable partial success, preserving transaction hashes and original diagnostics while warning callers not to blindly retry.
+
+- [#1259](https://github.com/vultisig/vultisig-sdk/pull/1259) [`955486c`](https://github.com/vultisig/vultisig-sdk/commit/955486cd3c749888ce9d37a0b8a0b59eabc8ac0d) Thanks [@neavra](https://github.com/neavra)! - Scope the broadcast-journal empty-calldata canonicalization (`"0x"` → `""`) to EVM calldata only. `intent.data` also carries non-EVM memos, so canonicalizing it for every intent made a real memo of `"0x"` collide with an empty memo and falsely dedupe two different memo-chain sends inside the double-spend guard window. The fingerprint now folds `"0x"` only when the intent marks its data as EVM calldata, and every intent builder derives that mark from the chain kind (`getChainKind(chain) === 'evm'`): an EVM `"0x"` memo is empty calldata and still folds (so cross-path dedup is preserved), while a `"0x"` memo on a memo-routed chain stays distinct from an empty memo.
+
+- [#1308](https://github.com/vultisig/vultisig-sdk/pull/1308) [`48ad7a2`](https://github.com/vultisig/vultisig-sdk/commit/48ad7a269186965b2b7a20d4b9d52ccd3b77fcbd) Thanks [@rcoderdev](https://github.com/rcoderdev)! - Expose one SDK chain-reference resolver and use it for CLI and MCP chain names, aliases, and IDs.
+
+- Updated dependencies [[`747b6c6`](https://github.com/vultisig/vultisig-sdk/commit/747b6c68a81e14f3242003f39a4b58499ef44a21), [`b6fbbe3`](https://github.com/vultisig/vultisig-sdk/commit/b6fbbe3705d6aae02b483de0b7dd1b8a097acd6b), [`a08a52b`](https://github.com/vultisig/vultisig-sdk/commit/a08a52bb0933fd5470ea849613e147baa29286ad), [`9e366db`](https://github.com/vultisig/vultisig-sdk/commit/9e366db273e87e62d260867ea6702466b325d7fc), [`c3168e2`](https://github.com/vultisig/vultisig-sdk/commit/c3168e24a32d733da85b2f6038e7e55c4dbe8d72), [`7bb79ba`](https://github.com/vultisig/vultisig-sdk/commit/7bb79ba9ef968bc20ba88e1bdd189ca8864b0221), [`a8e873e`](https://github.com/vultisig/vultisig-sdk/commit/a8e873e41a41693dcdee575c5271422fe6c6b6e3), [`1c4fc80`](https://github.com/vultisig/vultisig-sdk/commit/1c4fc80be959af4b650e32b4db30859f449dfa60), [`30b76c6`](https://github.com/vultisig/vultisig-sdk/commit/30b76c6d0fbe7f0ad3015fee9bc77b5ee9fa7927), [`421e8da`](https://github.com/vultisig/vultisig-sdk/commit/421e8da0b11a35bcc95351e7b644318fe171c5ec), [`846d6c2`](https://github.com/vultisig/vultisig-sdk/commit/846d6c24e96ba4f8133721f1030dd9d023376570), [`6de79ab`](https://github.com/vultisig/vultisig-sdk/commit/6de79ab1ec6e3566ea8511a0a6c7afde87752c48), [`21ca074`](https://github.com/vultisig/vultisig-sdk/commit/21ca07454d5ac462882317da4f49d5f80ef32837), [`72da781`](https://github.com/vultisig/vultisig-sdk/commit/72da781743fad0664edfc5ffcd72720ac7f0d0bd), [`32aaf40`](https://github.com/vultisig/vultisig-sdk/commit/32aaf40edb28ea46f8275341ce4205411197a652), [`48ad7a2`](https://github.com/vultisig/vultisig-sdk/commit/48ad7a269186965b2b7a20d4b9d52ccd3b77fcbd), [`dda2e90`](https://github.com/vultisig/vultisig-sdk/commit/dda2e9084859eae02dd16149ac3ab2240a7d37e5), [`eb11e50`](https://github.com/vultisig/vultisig-sdk/commit/eb11e50b2f478fbb21db2970f8616d5f296b49f5), [`4815346`](https://github.com/vultisig/vultisig-sdk/commit/4815346d794f4a198e84a562c503b3bdd5ae10b8), [`f885e91`](https://github.com/vultisig/vultisig-sdk/commit/f885e91da06674dbef2ca1495291ca7d201e4c58)]:
+  - @vultisig/core-chain@2.26.0
+  - @vultisig/sdk@2.20.0
+  - @vultisig/rujira@53.0.0
+
 ## 2.19.18
 
 ### Patch Changes

package/README.md

@@ -370,24 +370,24 @@ Swap quotes and previews show your VULT discount tier when affiliate fees are ap
 
 #### Transaction Status
 
-Check whether a transaction has confirmed on-chain. By default, polls every 5 seconds until the transaction reaches a final state (success or error):
+Check whether a transaction has confirmed on-chain. The CLI reports `pending`, `not_found`, `confirmed`, or `failed`. A recently broadcast hash may briefly be `not_found`, so the default mode polls every 5 seconds for up to 120 seconds. Use `--no-wait` for one read:
 
 ```bash
 # Poll until confirmed (default)
-vultisig tx-status ethereum 0x9f8e7d6c...
+vultisig tx-status --chain Ethereum --tx-hash 0x9f8e7d6c...
 
 # Check current status without polling
-vultisig tx-status ethereum 0x9f8e7d6c... --no-wait
+vultisig tx-status --chain Ethereum --tx-hash 0x9f8e7d6c... --no-wait
 
 # JSON output
-vultisig tx-status ethereum 0x9f8e7d6c... -o json
+vultisig --output json tx-status --chain Ethereum --tx-hash 0x9f8e7d6c... --no-wait
 ```
 
 **Output:**
 
 ```
-✓ Transaction status: success
-Status: success
+✓ Transaction status: confirmed
+Status: confirmed
 Fee: 0.00042 ETH
 Explorer: https://etherscan.io/tx/0x9f8e7d6c...
 ```
@@ -396,18 +396,26 @@ Explorer: https://etherscan.io/tx/0x9f8e7d6c...
 
 ```json
 {
-  "chain": "ethereum",
-  "txHash": "0x9f8e7d6c...",
-  "status": "success",
-  "receipt": {
-    "feeAmount": "420000000000000",
-    "feeDecimals": 18,
-    "feeTicker": "ETH"
-  },
-  "explorerUrl": "https://etherscan.io/tx/0x9f8e7d6c..."
+  "success": true,
+  "v": 1,
+  "data": {
+    "chain": "Ethereum",
+    "txHash": "0x9f8e7d6c...",
+    "status": "confirmed",
+    "receipt": {
+      "feeAmount": "420000000000000",
+      "feeDecimals": 18,
+      "feeTicker": "ETH"
+    },
+    "explorerUrl": "https://etherscan.io/tx/0x9f8e7d6c..."
+  }
 }
 ```
 
+A malformed hash fails before vault access or RPC with exit code `4`. JSON output uses error code `INVALID_HASH` and includes `error.context.status: "invalid_hash"`. A well-formed hash unknown to the node reports `not_found` in `--no-wait` mode; default polling exits `5` with `TX_NOT_FOUND` if it remains unseen for the wait budget. A known, unconfirmed transaction remains `pending`; if it is still `pending` when the wait budget is exhausted, default polling exits `3` with `TX_STATUS_TIMEOUT` (retryable) rather than reporting a false terminal status.
+
+EVM RPCs can distinguish a missing receipt from a hash the node does not know, so they report `not_found` explicitly. Some non-EVM providers do not distinguish an absent transaction from a failed lookup; those chains conservatively remain `pending` with an unknown-presence signal, and default CLI polling is still bounded by `--timeout`.
+
 #### Signing Arbitrary Bytes
 
 Sign pre-hashed data for externally constructed transactions:
@@ -647,18 +655,61 @@ JSON output for two-step create:
 
 Send a single natural-language message and get a structured response. Designed for AI-to-AI communication.
 
-**Password resolution:** `agent ask` unlocks the vault from the keyring/env chain before prompting, so a headless operator never has to put the password on argv. Set it up **once** — store it in the OS keyring with `vsig auth setup` (recommended), or export `VAULT_PASSWORD` (or `VAULT_PASSWORDS="VaultName:pw ..."` for multiple vaults) — then run `agent ask` with **no** `--password`. The `--password` flag still works as a fallback but is discouraged: it exposes the secret to `ps` and shell history, and triggers a stderr warning.
+#### Headless Password and Credential Chain
+
+`agent ask` resolves the vault password before prompting, so automation does not need to put a secret on argv. The lookup order is:
+
+1. In-memory cache (an explicit `--password` or a password already resolved in this process)
+2. Stored credentials from `vsig auth setup` (OS keyring, or the encrypted-file backend)
+3. `VAULT_PASSWORDS` by vault name, then by vault ID
+4. `VAULT_PASSWORD`, then its namespaced alias `VULTISIG_PASSWORD`
+5. Interactive prompt, or an error in non-interactive mode
+
+The five password-related environment variables have distinct roles:
+
+| Variable                          | Purpose                                                                                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VAULT_PASSWORD`                  | Single fallback vault/server-signing password. It is also the server password required by `auth setup --non-interactive`.                                     |
+| `VULTISIG_PASSWORD`               | Namespaced alias for the single-password fallback during normal vault unlock. `auth setup` still requires `VAULT_PASSWORD`.                                   |
+| `VAULT_PASSWORDS`                 | Per-vault passwords keyed by vault name or ID. Use the JSON form for names containing spaces.                                                                 |
+| `VAULT_DECRYPT_PASSWORD`          | Password for decrypting an encrypted `.vult` backup during `auth setup`; it is not part of the normal signing-password lookup chain.                          |
+| `VULTISIG_CREDENTIALS_PASSPHRASE` | Passphrase for the AES-256-GCM `credentials.enc` backend used instead of an OS keyring in Docker/CI. It must be set again when later commands read that file. |
+
+`VAULT_PASSWORDS` accepts a JSON object (recommended) or the legacy whitespace-separated form:
 
 ```bash
-# Recommended: store the password once, then no --password on each call
-vsig auth setup                 # stores in the OS keyring
-# or: export VAULT_PASSWORD="..."
+# Unambiguous: supports spaces and other punctuation in vault names
+export VAULT_PASSWORDS='{"Vultisig Cluster #1":"pw","vault-id":"other-pw"}'
 
-# Simple query (password resolved from keyring/env)
-vultisig agent ask "What is my ETH balance?"
+# Backward-compatible for space-free keys; passwords may contain colons
+export VAULT_PASSWORDS='MyVault:pw vault-id:other:pw'
+```
+
+Vault-ID keys are the most deterministic choice. If a JSON-looking value is malformed, the CLI warns on stderr and falls back to legacy parsing.
 
-# Execute a transaction
-vultisig agent ask "Send 0.01 ETH to 0x742d..."
+For a keychain-less container, provide all setup secrets once, persist the config directory, then remove the vault passwords from the environment. Keep the credentials-file passphrase available to later CLI processes:
+
+```bash
+export VULTISIG_CONFIG_DIR=/var/lib/vultisig
+export VAULT_DECRYPT_PASSWORD='backup-file-password'
+export VAULT_PASSWORD='server-signing-password'
+export VULTISIG_CREDENTIALS_PASSPHRASE='credentials-file-passphrase'
+
+vsig auth setup --non-interactive --vault-file /run/secrets/vault.vult
+
+# Setup stored both passwords in $VULTISIG_CONFIG_DIR/credentials.enc (mode 0600).
+unset VAULT_DECRYPT_PASSWORD VAULT_PASSWORD
+vsig auth status
+
+# No vault password on argv or in the environment. --yes authorizes signing/broadcast.
+vsig agent ask 'Send 0.01 ETH to 0x742d...' --yes
+```
+
+Omit `VAULT_DECRYPT_PASSWORD` when the `.vult` file is not encrypted. Mount `VULTISIG_CONFIG_DIR` persistently and provide the same `VULTISIG_CREDENTIALS_PASSPHRASE` to each new container. The `--password` flag remains available as a fallback, but it exposes the secret to `ps` and shell history and emits a stderr warning.
+
+```bash
+# Simple query (password resolved from stored credentials or environment)
+vultisig agent ask "What is my ETH balance?"
 
 # Continue a conversation (multi-turn)
 vultisig agent ask "Now swap it to USDC" --session abc123
@@ -685,41 +736,61 @@ explorer:https://etherscan.io/tx/0x9f8e7d6c...
 
 ```json
 {
-  "session_id": "abc123-def456",
-  "response": "Your ETH balance is 1.5 ETH ($3,750.00 USD).",
-  "tool_calls": [
-    {
-      "action": "get_balances",
-      "success": true,
-      "data": {
-        "balances": [
-          {
-            "chain": "Ethereum",
-            "symbol": "ETH",
-            "amount": "1.5",
-            "decimals": 18,
-            "raw_amount": "1500000000000000000"
-          }
-        ]
+  "success": true,
+  "v": 1,
+  "data": {
+    "conversation_id": "abc123-def456",
+    "session_id": "abc123-def456",
+    "response": "Your ETH balance is 1.5 ETH ($3,750.00 USD).",
+    "tool_calls": [
+      {
+        "id": "tool-call-1",
+        "action": "get_balances",
+        "success": true,
+        "data": { "balances": [] }
       }
-    }
-  ],
-  "transactions": [
-    {
-      "hash": "0x9f8e7d6c...",
-      "chain": "ethereum",
-      "explorerUrl": "https://etherscan.io/tx/0x9f8e7d6c..."
-    }
-  ]
+    ],
+    "transactions": [],
+    "outcome": { "kind": "success" }
+  }
 }
 ```
 
-On failure, stdout is a single JSON object with both a human `error` string and a stable `code` (the `error` field is unchanged for older parsers):
+Failures use the same v1 envelope with `success:false` and a stable `error.code`. This includes
+failed/declined signing and typed blocked/refusal/error turn endings; their partial turn data remains under `data`.
+If `--session` cannot be resumed, ask mode exits `5` before sending the message and does not fall back to a fresh
+conversation.
+If a transaction hash has already been submitted and a later backend outcome/error prevents the overall request
+from completing, the CLI exits `13` with `BROADCAST_COMMITTED`. This is deliberately **not** overall success:
+an approval or other first leg may have landed while a swap or follow-up step did not. Inspect every hash and do
+not blindly retry the original request.
 
 ```json
 {
-  "error": "Agent backend unreachable at https://example.invalid",
-  "code": "BACKEND_UNREACHABLE"
+  "success": false,
+  "v": 1,
+  "error": {
+    "message": "A transaction was broadcast, but the overall agent request may be incomplete. Inspect the transaction status before continuing.",
+    "code": "BROADCAST_COMMITTED",
+    "conversation_id": "abc123-def456"
+  },
+  "data": {
+    "transactions": [
+      {
+        "hash": "0x9f8e7d6c...",
+        "chain": "ethereum",
+        "status": "broadcast",
+        "explorerUrl": "https://etherscan.io/tx/0x9f8e7d6c..."
+      }
+    ],
+    "tool_calls": [],
+    "response": "",
+    "outcome": { "kind": "error", "code": "follow_up_failed" },
+    "original_error": {
+      "message": "Confirmation indexer failed after broadcast",
+      "code": "TRANSACTION_FAILED"
+    }
+  }
 }
 ```
 
@@ -735,13 +806,18 @@ Orchestrators should branch on `code`. The message in `error` / `message` stays
 | `AUTH_FAILED`             | Auth/token failure, HTTP 401/403, or wrong vault password                                                                    |
 | `VAULT_LOCKED`            | Encrypted vault needs unlock (password)                                                                                      |
 | `PASSWORD_REQUIRED`       | Password was not supplied when required (e.g. pipe mode or signing)                                                          |
-| `CONFIRMATION_REQUIRED`   | User confirmation needed (pipe mode; message prefix `CONFIRMATION_REQUIRED:`)                                                |
+| `CONFIRMATION_REQUIRED`   | User confirmation needed (pipe mode; message prefix `CONFIRMATION_REQUIRED:`); also returned by `agent ask` on a declined sign (no `--yes`), exit 12 |
 | `ACTION_NOT_IMPLEMENTED`  | Local executor does not implement this action type                                                                           |
 | `INVALID_INPUT`           | Bad parameters, unknown chain, malformed NDJSON input, etc.                                                                  |
 | `NETWORK_ERROR`           | RPC/fetch connectivity (includes many SDK `VaultError` network cases)                                                        |
 | `TIMEOUT`                 | Deadline exceeded, or abort where the message indicates a timeout                                                            |
 | `TRANSACTION_FAILED`      | Build/broadcast/gas errors mapped from the SDK                                                                               |
 | `SIGNING_FAILED`          | MPC/signing failed                                                                                                           |
+| `ACK_FAILED`              | Transaction broadcast, but its immediate acknowledgement/report failed; hash is valid and must be inspected before retrying  |
+| `BROADCAST_COMMITTED`     | At least one transaction broadcast, but the overall agent request may be incomplete; do not blindly retry                    |
+| `AGENT_TURN_BLOCKED`      | A fund-safety guardrail blocked the requested action (exit 10)                                                               |
+| `AGENT_TURN_REFUSAL`      | The model refused or requested clarification without completing the action (exit 11)                                         |
+| `AGENT_TURN_ERROR`        | The typed turn ending reported a failure without a more specific stream error                                                |
 | `SESSION_NOT_INITIALIZED` | Internal session state error                                                                                                 |
 | `UNKNOWN_ERROR`           | Unclassified failure (default for opaque SSE `error` events). Plain `AbortError` without “timeout” in the message maps here. |
 
@@ -749,7 +825,7 @@ SSE `error` events may optionally include a `code` field from the backend; if it
 
 **Agent ask options:**
 
-- `--session <id>` - Continue an existing conversation
+- `--session <id>` - Continue an existing conversation; a stale ID fails closed before the message is sent
 - `--backend-url <url>` - Agent backend URL (default: https://abe.vultisig.com)
 - `--password <password>` - Vault password (fallback only; prefer the keyring/`VAULT_PASSWORD` env — see **Password resolution** above)
 - `--verbose` - Show tool calls and debug info on stderr
@@ -855,7 +931,7 @@ VULTISIG_VAULT=MyWallet
 VAULT_PASSWORD=mypassword
 
 # Multiple vault passwords
-VAULT_PASSWORDS="Vault1:pass1 Vault2:pass2"
+VAULT_PASSWORDS='{"Vault 1":"pass1","vault-id-2":"pass2"}'
 
 # Suppress spinners and info messages
 VULTISIG_SILENT=1
@@ -1100,7 +1176,7 @@ VULTISIG_NO_UPDATE_CHECK=1
 VAULT_PASSWORD=mypassword
 
 # Multiple vault passwords
-VAULT_PASSWORDS="Vault1:pass1 Vault2:pass2"
+VAULT_PASSWORDS='{"Vault 1":"pass1","vault-id-2":"pass2"}'
 ```
 
 ### Config Directory
@@ -1109,9 +1185,10 @@ Configuration is stored in `~/.vultisig/`:
 
 ```
 ~/.vultisig/
-├── config.json      # User preferences
-├── vaults/          # Vault data
-├── cache/           # Version checks, etc.
+├── config.json       # User preferences and registered vaults
+├── credentials.enc   # Optional encrypted-file credential backend
+├── vaults/           # Vault data
+├── cache/            # Version checks, etc.
 └── address-book.json
 ```
 
@@ -1149,6 +1226,7 @@ Configuration is stored in `~/.vultisig/`:
 | 10   | agent ask: a fund-safety guardrail blocked the requested action                                                        |
 | 11   | agent ask: the model refused or asked a clarifying question (no action taken)                                          |
 | 12   | Interactive confirmation/input required but the session is non-interactive — pass --yes/--confirm or the required flag |
+| 13   | agent ask: transaction broadcast but the overall request may be incomplete — inspect the hash, do NOT blindly retry    |
 
 > These are generated from the `ExitCode` enum in `src/core/errors.ts` (the single source of
 > truth) and are covered by a doc-lint test that fails if this table drifts from the code. Run