0xMiden / 0xMiden/web-sdk

Improve WebClient MASM and runtime error details

未關閉
#192 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement
主要語言
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

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。