Improve WebClient MASM and runtime error details
- 主要語言
- TypeScript
- 星號
- 1
- 分支
- 21
- 平均合併
- 12 小時 14 分鐘
- 30 天內合併 PR
- 41
描述
## Problem
Web client errors from MASM/runtime execution can be too opaque to debug.
Pioneer feedback gave an example shaped like:
```text
Diagnostic { message: "assertion failed at clock cycle 7386 with error code: 0", labels: "[LabeledSpan { label: None, span: SourceSpan { offset: SourceOffset(0), length: 0 }, primary: false }]" }
```
This does not tell the developer which file, procedure, source line, input note, or account context caused the failure.
## Why this matters
Most app developers using the web client are not MASM experts. If the SDK returns a low-level diagnostic without usable source context, developers cannot distinguish between:
- a bad assertion in their MASM,
- a missing import,
- a source manager mismatch,
- an account/interface context issue,
- missing foreign account data,
- a protocol-level runtime error.
## Proposed scope
Improve WebClient error formatting and source-context preservation for MASM/runtime failures:
- preserve source manager information through compile and execute paths,
- surface file/procedure/span where available,
- include relevant transaction context when the error happens while consuming notes,
- map known protocol/standards error codes to readable messages where possible,
- ensure JS/TS consumers receive structured error fields rather than only stringified Rust diagnostics.
## Acceptance criteria
- WebClient errors include source file/procedure/span when available.
- Runtime assertion failures expose useful context in JS/TS.
- Known error codes from protocol/standards are mapped or documented.
- Tests cover at least one failing MASM assertion and verify the JS-visible error content.
- The docs include guidance on debugging MASM/runtime errors from web clients.
## Related context
- Pioneer feedback from Zoro.
- 0xMiden/miden-vm#2762
- 0xMiden/miden-vm#2778
- miden-client v0.14.5 fixed one source-manager mismatch case in Rust tests via 0xMiden/miden-client#2047.
貢獻指南
研究方向
The issue references miden-vm issues #2762 and #2778, and a fix in miden-client #2047. Start by examining the WebClient's error handling code, likely in the TypeScript SDK that interfaces with Rust/WASM. Look for where MASM compilation and runtime execution diagnostics are converted for JS/TS consumption. The goal is to preserve source manager info, map error codes, and structure errors. Check existing tests for error formatting to understand the current output and add new tests for the improved error details.
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- rust, typescript
- 領域
- backend-api-design, devtools
- Issue 類型
- 功能
- 難度
- 4/5
- 預估耗時
- 3-5 天
- 活躍度
- 冷清
- 描述清晰度
- 基本清楚
- 新手友好度
- 45/100