Add Build docs for Miden Assembly (MASM)
- 主要言語
- TypeScript
- スター
- 10
- フォーク
- 50
- 平均マージ
- 22日 23時間
- マージ済み PR(30日)
- 1
説明
## Context
The Build section currently has a Rust-first **Smart Contracts** path, while MASM appears mostly through tutorials, migration notes, playground links, and lower-level reference material. Developers who write account components, note scripts, transaction scripts, or custom libraries in MASM need a dedicated authoring path inside Smart Contracts.
This is also important for the planned Miden Standards docs: `miden-standards` is used both through Rust APIs and through direct MASM imports such as `miden::standards::*`. Standards docs should not carry the full burden of teaching MASM from scratch.
Related issues:
- `0xMiden/docs#287` tracks Build-facing docs for Miden standards.
- `0xMiden/docs#286` tracks renaming **Core Concepts** to **Reference**.
- `0xMiden/docs#289` tracks the Rust authoring path and compiler maturity warning.
## Recommendation
Add **Miden Assembly (MASM)** as a first-class authoring path under **Build → Smart Contracts**.
Framing:
- **Smart Contracts** is the domain.
- **Rust** and **MASM** are authoring paths for smart-contract code.
- MASM is also used for note scripts, transaction scripts, helper libraries, and direct standards imports, but these are still part of the smart-contract authoring workflow on Miden.
This should be a practical authoring guide, not a replacement for the VM/assembler reference. The Build section should answer: "How do I write, assemble, test, debug, and use MASM in Miden smart contracts and scripts?" Reference docs should answer: "What are the exact instructions, contexts, kernel APIs, and library procedure contracts?"
## Proposed information architecture
Recommended placement:
- `builder/smart-contracts/masm/index.md`
- `builder/smart-contracts/masm/project-structure.md`
- `builder/smart-contracts/masm/account-components.md`
- `builder/smart-contracts/masm/note-scripts.md`
- `builder/smart-contracts/masm/transaction-scripts.md`
- `builder/smart-contracts/masm/imports-and-libraries.md`
- `builder/smart-contracts/masm/stack-and-memory.md`
- `builder/smart-contracts/masm/testing-and-debugging.md`
- `builder/smart-contracts/masm/common-errors.md`
The broader Smart Contracts section can then expose three sibling authoring/building areas:
- Rust-authored smart contracts
- MASM-authored smart contracts and scripts
- Miden Standards, usable from both Rust and MASM
## Content to cover
Minimum first pass:
- What MASM is and when to write MASM directly instead of Rust.
- How Rust smart-contract authoring compiles down to MASM.
- How MASM code is organized as modules/libraries.
- How to import protocol and standards modules.
- How to write account components with account context constraints.
- How to write note scripts with `@note_script`.
- How to write transaction scripts.
- Stack discipline, word ordering, memory conventions, and common pitfalls.
- How to assemble and test MASM snippets locally.
- Debugging workflow and error interpretation.
- Cross-links to VM reference, protocol library reference, and Miden Standards docs.
## Relationship to Miden Standards docs
The Standards Build docs should show small MASM examples for standard imports and calls, but the MASM section should teach the underlying mechanics:
- module paths and imports
- stack inputs/outputs
- account/note/transaction contexts
- assembler project layout
- validation/debugging workflow
This keeps Standards docs focused on reusable building blocks and keeps MASM docs focused on the authoring model.
## Validation requirements
All MASM examples added to Build docs should be validated in a brand-new Docker environment before the PR is opened.
Expected validation path:
- Assemble MASM snippets against the appropriate protocol/standards library for the target version.
- Run any transaction/account/note script examples in the smallest available harness when assembly alone is not sufficient.
- Add or extend a docs-test harness so MASM snippets can be re-run in Docker.
- Run the docs build after ingestion and confirm no new broken links or anchors.
- Update versioned docs when examples describe v0.14 APIs or behavior.
## Scope
- Add the Build-facing MASM docs under Smart Contracts.
- Add sidebar entries and cross-links from Smart Contracts, Tutorials, Standards, Playground, and Migration pages.
- Keep examples executable and grounded in shipped APIs.
## Out of scope
- Replacing the VM instruction reference.
- Moving canonical protocol/standards reference docs into the docs repo.
- Documenting every protocol or standards procedure in the Build MASM guide.
コントリビューションガイド
調査の方向性
この issue は、`builder/smart-contracts/masm/` の下に新しいドキュメントページを追加することを提案しています。まず、既存のドキュメントリポジトリの構造を調べて、レイアウトとスタイルを理解することから始めてください。最初のステップは、index.md ファイルを作成し、提案されたセクションの概要を作成することです。指定された Docker 環境で MASM の例を検証してください。新しいページがサイドバーにリンクされ、既存のチュートリアルやリファレンス資料から参照されるようにしてください。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- markdown, typescript
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 3/5
- 見積もり時間
- 1〜2日
- 活発さ
- 停滞
- 明瞭さ
- 明確に書かれている
- 初心者へのやさしさ
- 65/100