Skip to content

Commit e6aaddd

Browse files
VolodymyrBgmmagicianigamigo
authored
docs: add debugging guide and lifecycle diagram (0xMiden#1343)
* docs(debugging): add debugging guide and transaction lifecycle diagram * Update EXPORTED.md * Update SUMMARY.md * add note clarifying it applies to the CLI client only * Update debugging.md * Apply suggestions from code review * Update debugging.md * Update docs/src/debugging.md Co-authored-by: igamigo <[email protected]> * Update docs/src/debugging.md Co-authored-by: igamigo <[email protected]> * Update and rename debugging.md to troubleshooting.md * Update SUMMARY.md * Update EXPORTED.md * chore: rename to cli-troubleshooting, place under CLI sec * chore: move troublshotting under CLI in summary --------- Co-authored-by: Marti <[email protected]> Co-authored-by: igamigo <[email protected]> Co-authored-by: Marti <[email protected]>
1 parent 57e9d91 commit e6aaddd

File tree

3 files changed

+131
-0
lines changed

3 files changed

+131
-0
lines changed

‎docs/src/EXPORTED.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
* [Library](./library.md)
1515
* [CLI](./cli-reference.md)
1616
+ [Config](./cli-config.md)
17+
+ [Troubleshooting](./cli-troubleshooting.md)
1718
* [Examples](./examples.md)
1819
* [API](./api-docs.md)
1920
- [Typescript](./web-client/index.md)

‎docs/src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,4 @@
2929

3030
- [CLI](./cli-reference.md)
3131
- [Config](./cli-config.md)
32+
- [Troubleshooting](./cli-troubleshooting.md)

‎docs/src/cli-troubleshooting.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
## Troubleshooting and transaction lifecycle (CLI)
2+
3+
This guide helps you troubleshoot common issues and understand the end-to-end lifecycle of transactions and notes in the Miden client.
4+
5+
### TL;DR checklist
6+
7+
> Note: This section applies to the Miden CLI client. Guidance for the Rust and Web clients may differ.
8+
9+
- Ensure you are running commands in the same directory that contains `miden-client.toml`.
10+
- If you need a clean local state, delete the SQLite store file referenced by `store_filepath` (default: `store.sqlite3`). It will be recreated automatically on the next command.
11+
- Verify your node RPC endpoint is reachable and correct in `miden-client.toml`.
12+
- Run with debug output when troubleshooting: add `--debug` or set `MIDEN_DEBUG=true`.
13+
- Run `miden-client sync` to refresh local state after errors involving missing data or outdated heights.
14+
15+
### Enable debug output
16+
17+
- CLI flag: `miden-client --debug <command> ...` (overrides `MIDEN_DEBUG`)
18+
- Environment variable: `MIDEN_DEBUG=true`
19+
20+
When enabled, the transaction executor and script compiler emit debug logs that help diagnose MASM-level issues (you can also consult the Miden VM debugging instructions).
21+
22+
### Typical CLI outputs when debugging
23+
24+
```sh
25+
# Enable debug output for a command
26+
miden-client --debug send --sender <SENDER> --target <TARGET> --asset 100::<FAUCET_ID>
27+
28+
# Force non-interactive submission (e.g., CI)
29+
miden-client send --force ...
30+
31+
# Refresh local state
32+
miden-client sync
33+
```
34+
35+
If you see a gRPC error, it may include a status-derived kind (e.g. `Unavailable`, `InvalidArgument`) which narrows possible causes.
36+
37+
### Common errors and how to resolve
38+
39+
Below are representative errors you may encounter, their likely causes, and suggested fixes.
40+
41+
#### `RpcError.GrpcError: Unavailable` / `DeadlineExceeded`
42+
- Cause: Node is down, unreachable, or behind a load balancer that blocked the request.
43+
- Fix: Check `rpc.endpoint` in `miden-client.toml`, verify the node is running/accessible, and retry.
44+
45+
#### `RpcError.InvalidArgument` / `ExpectedDataMissing` / `InvalidResponse`
46+
- Cause: Malformed request parameters or unexpected server response.
47+
- Fix: Re-check command flags/inputs. If using partial IDs, ensure they map to a single entity. Update to the latest client if the server API has changed.
48+
49+
#### Client/network compatibility mismatch
50+
- Cause: Client and network versions or the genesis header commitment are incompatible.
51+
- Symptoms: CLI may report messages like:
52+
53+
```
54+
accept header validation failed: server rejected request - please check your version and network settings
55+
```
56+
57+
or requests being rejected due to a mismatched genesis header commitment.
58+
- Details: These are validated by the node by verifying client headers on gRPC requests.
59+
- Fix: Ensure your client version matches the target network. Switch to the correct network or upgrade/downgrade the client accordingly. Verify the configured genesis header commitment matches the network, then retry.
60+
61+
#### `ClientError.AccountDataNotFound(<account_id>)`
62+
- Cause: The account is not known to the local store yet.
63+
- Fix: Create/import the account first, or run `miden-client sync` to fetch it if it exists on-chain.
64+
65+
#### `ClientError.AccountLocked(<account_id>)`
66+
- Cause: Attempting to modify a locked account.
67+
- Fix: Unlock or use another account as appropriate.
68+
69+
#### `ClientError.StoreError(AccountCommitmentAlreadyExists(...))`
70+
- Cause: Trying to apply a transaction whose final account commitment is already present locally.
71+
- Fix: Ensure you are not re-applying the same transaction. Sync and check transaction status.
72+
73+
#### `ClientError.NoteNotFoundOnChain(<note_id>)` / `RpcError.NoteNotFound(<note_id>)`
74+
- Cause: The note has not been published/committed yet or the ID is incorrect.
75+
- Fix: Verify the note ID. If it should exist, run `miden-client sync` and retry.
76+
77+
#### `ClientError.TransactionInputError` / `TransactionScriptError`
78+
- Cause: Invalid transaction inputs, script logic errors, or failing constraints.
79+
- Fix: Run with `--debug` to collect execution logs. Validate input notes, foreign accounts, and script assumptions.
80+
81+
#### `ClientError.TransactionProvingError`
82+
- Cause: Local proving failed or remote prover returned an error.
83+
- Fix: If using remote proving, verify `remote_prover_endpoint` is reachable and add `--delegate-proving`. Check prover logs.
84+
85+
#### Recency/block delta errors
86+
- Cause: Client is too far behind the network and validation enforces a max delta.
87+
- Fix: Run `miden-client sync` or increase `max_block_number_delta` via `miden-client init --block-delta <N>` and re-run.
88+
89+
### Transaction lifecycle (CLI-oriented overview)
90+
91+
For the full protocol-level lifecycle, see the Miden book: [Transaction lifecycle](https://0xmiden.github.io/miden-docs/imported/miden-base/src/transaction.html#transaction-lifecycle).
92+
93+
```mermaid
94+
flowchart LR
95+
A[Build Request] --> B[Validate Request]
96+
A -.->|optional| C[Collect/Insert Input Notes]
97+
A -.->|optional| D[Load Foreign Accounts]
98+
B -.->|optional| K[Insert Public Note Recipients]
99+
B --> E[Execute Transaction]
100+
E --> F[Prove Transaction]
101+
F --> G[Submit to Node]
102+
G --> H[Track Locally]
103+
104+
subgraph Tracking
105+
H --> I[Update Account State]
106+
H --> J[Update Notes/Tags]
107+
end
108+
```
109+
110+
Key states the CLI surfaces:
111+
112+
- Transaction status: `Pending` (after execution), `Committed` (after node inclusion), `Discarded` (not included).
113+
- Input notes: `Expected` → `Processing` → `Consumed` (after sync) or `Committed` if fetched with inclusion.
114+
115+
### Recovery flow
116+
117+
1. Re-run with `--debug` or `MIDEN_DEBUG=true` for richer logs.
118+
2. Verify `rpc.endpoint` connectivity and timeouts.
119+
3. Run `miden-client sync` to refresh local headers/notes.
120+
4. If local DB is inconsistent for development purposes, delete `store.sqlite3` (or configured path) and retry.
121+
5. Adjust `max_block_number_delta` if strict recency checks block validation.
122+
6. If proving errors persist with a remote prover, confirm `remote_prover_endpoint` and consider running locally to isolate the issue.
123+
124+
### References
125+
126+
- CLI debug flag and environment variable are documented in `CLI` and `Config` docs.
127+
- Common error enums originate from the client and RPC layers.
128+
- Protocol lifecycle: [Miden book — Transaction lifecycle](https://0xmiden.github.io/miden-docs/imported/miden-base/src/transaction.html#transaction-lifecycle)
129+

0 commit comments

Comments
 (0)