0xMiden / 0xMiden/docs

Add Build docs for Miden Assembly (MASM)

オープン
#288 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
documentation enhancement
主要言語
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

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。