From 734830253dcc2555f8b8a8796bc94f8268492fb7 Mon Sep 17 00:00:00 2001 From: Robbian Saputra Gumay <120354104+Alice699@users.noreply.github.com> Date: Tue, 3 Mar 2026 03:13:57 +0700 Subject: [PATCH 1/6] docs: add learning path for new developers Adds a structured learning path page to help new developers navigate the Miden docs from complete beginner to active builder. Organized into four levels: Understand, Experiment, Build Locally, and Build Seriously. --- docs/builder/learning-path.md | 62 +++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/builder/learning-path.md diff --git a/docs/builder/learning-path.md b/docs/builder/learning-path.md new file mode 100644 index 00000000..2ebaf486 --- /dev/null +++ b/docs/builder/learning-path.md @@ -0,0 +1,62 @@ +Miden Learning Path +New to Miden? This page gives you a clear, structured path from complete beginner to active builder — so you always know exactly what to do next. +The path is divided into four levels. Each level builds on the previous one. You don't need to complete every item before moving forward, but the order is intentional. + +Level 1 — Understand (No Setup Required) +Start here if you're new to Miden or ZK-based blockchains. No installation needed — everything in this level runs in your browser or requires only reading. +Goal: Understand what Miden is, why it exists, and how it works at a high level. +ResourceWhat You'll LearnIntroductionWhat Miden is and what makes it differentCore ConceptsAccounts, notes, transactions, and the actor modelMiden Smart ContractsHow contracts work on Miden vs other chainsGlossaryKey terms used throughout the documentation + +Level 2 — Experiment (Browser Only) +Once you understand the concepts, explore them hands-on. The Miden Playground requires no installation — everything runs in your browser. +Goal: Write and run your first Miden programs without any local setup. +ResourceWhat You'll LearnMiden PlaygroundInteractive environment for writing MASM programsMiden WalletExperience client-side proving in the browserMiden FaucetGet testnet tokensMiden ScanExplore accounts and transactions on testnetFAQAnswers to common questions + +Level 3 — Build Locally +When the browser playground isn't enough, set up a full local development environment. This level requires installing Rust and the Miden toolchain on your machine. +Goal: Run Miden locally, connect to testnet, and submit real transactions. +Step 1 — Install the toolchain +Follow the Quick Start guide to install Rust and midenup. + +Ubuntu/Linux users: After running midenup install stable, you may need to add the Miden binaries to your PATH manually. If miden --version returns "command not found", run: +bashecho 'export PATH="/home/YOUR_USERNAME/.local/share/midenup/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc +Replace YOUR_USERNAME with your actual username. + +Step 2 — Connect to a node +You have two options: + +Testnet (recommended for beginners): Connect directly to rpc.testnet.miden.io:443 — no setup required +Local node (optional, for development): Follow the Miden Node Setup tutorial to run a node on your own machine + +Most users should start with testnet. +Step 3 — Interact via client +Choose your preferred interface: +InterfaceBest ForRust ClientBackend developers, programmatic interaction via RustWeb ClientFrontend developers, browser-based applications (TypeScript) + +Level 4 — Build Seriously +Ready to write real smart contracts? This level covers the Miden Rust compiler and a full end-to-end application. +Goal: Write, test, and deploy Miden smart contracts in Rust. +Prerequisites for this level + +Completed Level 3 +Basic Rust programming experience + +Start here +ResourceWhat You'll LearnRust Compiler OverviewHow the Miden Rust compiler worksMiden Bank TutorialBuild a complete banking application end-to-endTesting with MockChainHow to test your contracts locallyDebugging GuideTroubleshoot issues in your contractsCommon PitfallsAvoid known mistakes + +How to Contribute +Once you've explored Miden, consider contributing back: + +Non-technical: Fix typos in docs, help in Telegram, give feedback +Some technical: Build projects in the playground, create MASM templates, submit GitHub Issues for bugs you encounter +Technical: Contribute to the Rust Client, Web Client, or Miden VM + +See the contributing guidelines for details. + +Get Help +Stuck at any level? Here's where to go: + +Miden Docs — full technical reference +Build On Miden Telegram — community support +GitHub Issues — report documentation bugs and gaps From 0468ffe74cce1d83c12ea83b51c24e101b02c68c Mon Sep 17 00:00:00 2001 From: Robbian Saputra Gumay <120354104+Alice699@users.noreply.github.com> Date: Tue, 3 Mar 2026 03:31:27 +0700 Subject: [PATCH 2/6] Fix typos and improve clarity in learning path --- docs/builder/learning-path.md | 86 +++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 24 deletions(-) diff --git a/docs/builder/learning-path.md b/docs/builder/learning-path.md index 2ebaf486..2ac70552 100644 --- a/docs/builder/learning-path.md +++ b/docs/builder/learning-path.md @@ -1,62 +1,100 @@ Miden Learning Path -New to Miden? This page gives you a clear, structured path from complete beginner to active builder — so you always know exactly what to do next. + +New to Miden? This page gives you a clear, structured path from complete beginner to active builder so you always know exactly what to do next. + The path is divided into four levels. Each level builds on the previous one. You don't need to complete every item before moving forward, but the order is intentional. Level 1 — Understand (No Setup Required) -Start here if you're new to Miden or ZK-based blockchains. No installation needed — everything in this level runs in your browser or requires only reading. + +Start here if you're new to Miden or ZK-based blockchains. No installation needed everything in this level runs in your browser or requires only reading. + Goal: Understand what Miden is, why it exists, and how it works at a high level. -ResourceWhat You'll LearnIntroductionWhat Miden is and what makes it differentCore ConceptsAccounts, notes, transactions, and the actor modelMiden Smart ContractsHow contracts work on Miden vs other chainsGlossaryKey terms used throughout the documentation + +Resource | What You'll Learn +[Introduction](/builder/) | What Miden is and what makes it different +[Core Concepts](/core-concepts/) | Accounts, notes, transactions, and the actor model +[Miden Smart Contracts](/builder/smart-contracts/) | How contracts work on Miden vs other chains +[Glossary](/builder/glossary) | Key terms used throughout the documentation Level 2 — Experiment (Browser Only) -Once you understand the concepts, explore them hands-on. The Miden Playground requires no installation — everything runs in your browser. + +Once you understand the concepts, explore them hands-on. The Miden Playground requires no installation everything runs in your browser. + Goal: Write and run your first Miden programs without any local setup. -ResourceWhat You'll LearnMiden PlaygroundInteractive environment for writing MASM programsMiden WalletExperience client-side proving in the browserMiden FaucetGet testnet tokensMiden ScanExplore accounts and transactions on testnetFAQAnswers to common questions + +Resource | What You'll Learn +[Miden Playground](https://playground.miden.xyz) | Interactive environment for writing MASM programs +[Miden Wallet](https://chromewebstore.google.com/detail/miden-wallet/ablmompanofnodfdkgchkpmphailefpb) | Experience client-side proving in the browser +[Miden Faucet](https://faucet.testnet.miden.io/) | Get testnet tokens +[Miden Scan](https://testnet.midenscan.com/) | Explore accounts and transactions on testnet +[FAQ](/builder/faq) | Answers to common questions Level 3 — Build Locally + When the browser playground isn't enough, set up a full local development environment. This level requires installing Rust and the Miden toolchain on your machine. + Goal: Run Miden locally, connect to testnet, and submit real transactions. Step 1 — Install the toolchain -Follow the Quick Start guide to install Rust and midenup. -Ubuntu/Linux users: After running midenup install stable, you may need to add the Miden binaries to your PATH manually. If miden --version returns "command not found", run: -bashecho 'export PATH="/home/YOUR_USERNAME/.local/share/midenup/bin:$PATH"' >> ~/.bashrc -source ~/.bashrc -Replace YOUR_USERNAME with your actual username. +Follow the [Quick Start guide](/builder/quick-start/) to install Rust and midenup. + +> **Ubuntu/Linux users:** After running `midenup install stable`, you may need to add the Miden binaries to your PATH manually. If `miden --version` returns "command not found", run: +> ```bash +> echo 'export PATH="/home/YOUR_USERNAME/.local/share/midenup/bin:$PATH"' >> ~/.bashrc +> source ~/.bashrc +> ``` +> Replace `YOUR_USERNAME` with your actual username. Step 2 — Connect to a node + You have two options: -Testnet (recommended for beginners): Connect directly to rpc.testnet.miden.io:443 — no setup required -Local node (optional, for development): Follow the Miden Node Setup tutorial to run a node on your own machine +- Testnet (recommended for beginners): Connect directly to `rpc.testnet.miden.io:443` — no setup required +- Local node (optional, for development): Follow the [Miden Node Setup](/builder/develop/tutorials/miden_node_setup) tutorial to run a node on your own machine Most users should start with testnet. + Step 3 — Interact via client + Choose your preferred interface: -InterfaceBest ForRust ClientBackend developers, programmatic interaction via RustWeb ClientFrontend developers, browser-based applications (TypeScript) + +Interface | Best For +[Rust Client](/builder/develop/tutorials/rust-client/) | Backend developers, programmatic interaction via Rust +[Web Client](/builder/develop/tutorials/web-client/) | Frontend developers, browser-based applications (TypeScript) Level 4 — Build Seriously + Ready to write real smart contracts? This level covers the Miden Rust compiler and a full end-to-end application. + Goal: Write, test, and deploy Miden smart contracts in Rust. -Prerequisites for this level -Completed Level 3 -Basic Rust programming experience +Prerequisites for this level +- Completed Level 3 +- Basic Rust programming experience Start here -ResourceWhat You'll LearnRust Compiler OverviewHow the Miden Rust compiler worksMiden Bank TutorialBuild a complete banking application end-to-endTesting with MockChainHow to test your contracts locallyDebugging GuideTroubleshoot issues in your contractsCommon PitfallsAvoid known mistakes + +Resource | What You'll Learn +[Rust Compiler Overview](/builder/develop/tutorials/rust-compiler/) | How the Miden Rust compiler works +[Miden Bank Tutorial](/builder/develop/tutorials/rust-compiler/miden-bank/) | Build a complete banking application end-to-end +[Testing with MockChain](/builder/develop/tutorials/rust-compiler/testing) | How to test your contracts locally +[Debugging Guide](/builder/develop/tutorials/rust-compiler/debugging) | Troubleshoot issues in your contracts +[Common Pitfalls](/builder/develop/tutorials/rust-compiler/pitfalls) | Avoid known mistakes How to Contribute + Once you've explored Miden, consider contributing back: -Non-technical: Fix typos in docs, help in Telegram, give feedback -Some technical: Build projects in the playground, create MASM templates, submit GitHub Issues for bugs you encounter -Technical: Contribute to the Rust Client, Web Client, or Miden VM +- Non-technical: Fix typos in docs, help in [Telegram](https://t.me/BuildOnMiden), give feedback +- Some technical: Build projects in the playground, create MASM templates, submit GitHub Issues for bugs you encounter +- Technical: Contribute to the Rust Client, Web Client, or Miden VM -See the contributing guidelines for details. +See the [contributing guidelines](https://github.com/0xMiden/.github/blob/main/CONTRIBUTING.md) for details. Get Help + Stuck at any level? Here's where to go: -Miden Docs — full technical reference -Build On Miden Telegram — community support -GitHub Issues — report documentation bugs and gaps +- [Miden Docs](https://docs.miden.xyz) — full technical reference +- [Build On Miden Telegram](https://t.me/BuildOnMiden) — community support +- [GitHub Issues](https://github.com/0xMiden/miden-docs/issues) — report documentation bugs and gaps From 6f9be5acc67f7fbef89a25ccb4782be256f648ac Mon Sep 17 00:00:00 2001 From: Robbian Saputra Gumay <120354104+Alice699@users.noreply.github.com> Date: Tue, 3 Mar 2026 15:40:07 +0700 Subject: [PATCH 3/6] docs: expand FAQ with questions for new developers --- docs/builder/faq.md | 117 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 94 insertions(+), 23 deletions(-) diff --git a/docs/builder/faq.md b/docs/builder/faq.md index cefcf9cb..bfb82c6e 100644 --- a/docs/builder/faq.md +++ b/docs/builder/faq.md @@ -1,79 +1,79 @@ -# FAQ +FAQ -## How is privacy implemented in Miden? +How is privacy implemented in Miden? Miden leverages zero-knowledge proofs and client side execution and proving to provide security and privacy. -## Does Miden support encrypted notes? +Does Miden support encrypted notes? At the moment, Miden does not have support for encrypted notes but it is a planned feature. -## Why does Miden have delegated proving? +Why does Miden have delegated proving? Miden leverages delegated proving for a few technical and practical reasons: -1. **Computational:** Generating zero-knowledge proofs is a computationally intensive work. The proving process requires significant processing power and memory, making it impractical for some end-user devices (like smartphones) to generate. -2. **Technical architecture**: +1. Computational: Generating zero-knowledge proofs is a computationally intensive work. The proving process requires significant processing power and memory, making it impractical for some end-user devices (like smartphones) to generate. +2. Technical architecture: Miden's architecture separates concerns between: - - **Transaction Creation**: End users create and sign transactions - - **Proof Generation**: Specialized provers generate validity proofs - - **Verification**: The network verifies these proofs -3. **Proving efficiency**: + - Transaction Creation: End users create and sign transactions + - Proof Generation: Specialized provers generate validity proofs + - Verification: The network verifies these proofs +3. Proving efficiency: Delegated provers can use optimized hardware that wouldn't be available to end-user devices, specifically designed for the mathematical operations needed in STARK proof generation. -## What is the lifecycle of a transaction? +What is the lifecycle of a transaction? -### 1. Transaction Creation +1. Transaction Creation - User creates a transaction specifying the operations to perform (transfers, contract interactions, etc.) - Client performs preliminary validation of the transaction and its structure - The user authorizes the specified state transitions by signing the transaction -### 2. Transaction Submission +2. Transaction Submission - The signed transaction is submitted to Miden network nodes - The transaction enters the mempool (transaction pool) where it waits to be selected to be included in the state - Nodes perform basic validation checks on the transaction structure and signature -### 3. Transaction Selection +3. Transaction Selection - A sequencer (or multiple sequencers in a decentralized setting) selects transactions from the mempool - The sequencer groups transactions into bundles based on state access patterns and other criteria - The transaction execution order is determined according to protocol mechanism -### 4. Transaction Execution +4. Transaction Execution - The current state relevant to the transaction is loaded - The Miden VM executes the transaction operations -- **State Transition Computation**: The resulting state transitions are computed +- State Transition Computation: The resulting state transitions are computed - An execution trace of the transaction is generated which captures all the computation -### 5. Proof Generation +5. Proof Generation - A STARK based cryptographic proof is generated attesting to the correctness of the execution - A proof for the aggregated transaction is created -### 6. Block Production +6. Block Production - The aggregated bundle of transactions along with their proofs are assembled into a block - A recursive proof attesting to all bundle proofs is generated - The block data structure is finalized with the aggregated proof -### 7. L1 Submission +7. L1 Submission - Transaction data is posted to the data availability layer - The block proof and state delta commitment are submitted to the Miden contract (that is bridged to Ethereum/Agglayer) - The L1 contract verifies validity of the proof - Upon successful verification, the L1 contract updates the state root -### 8. Finalization +8. Finalization - Transaction receipts and events are generated - The global state commitment is updated to reflect the new state - The transaction is now considered finalized on the L1 - Users and indexers get notified/updated about the transaction completion -## Do notes in Miden support recency conditions? +Do notes in Miden support recency conditions? Yes, Miden enables consumption of notes based on time conditions, such as: @@ -82,7 +82,7 @@ Yes, Miden enables consumption of notes based on time conditions, such as: - An oracle providing specific data - Another transaction being confirmed -## What does a Miden operator do in Miden? +What does a Miden operator do in Miden? A Miden operator is an entity that maintains the infrastructure necessary for the functioning of the Miden rollup. Their roles may involve: @@ -92,10 +92,81 @@ A Miden operator is an entity that maintains the infrastructure necessary for th 4. Maintaining Data Availability 5. Participating in the Consensus Mechanism -## How does bridging works in Miden? +How does bridging works in Miden? Miden does not yet have a fully operational bridge, work in progress. ## What does the gas fee model of Miden look like? Miden does not yet have a fully implemented fee model, work in progress. + +What is a note in Miden? + +A note is the primary mechanism for transferring assets and communicating between accounts in Miden. Unlike account-to-account transfers on most blockchains, Miden uses a note-based model where assets are wrapped in notes that are consumed by recipient accounts. Each note contains assets, a script that defines the conditions under which it can be consumed, and inputs that parameterize that script. + +What is the difference between a public and a private transaction? + +In a public transaction, the transaction details — including inputs, outputs, and state changes — are visible on-chain. In a private transaction, execution happens client-side and only a validity proof is submitted to the network. The network verifies the proof without learning the details of the transaction. This is one of Miden's core differentiators: privacy is not a layer added on top, but a property built into the transaction model itself. + +What programming languages can I use to build on Miden? + +Miden supports two primary development paths: + +- Rust: Using the Miden Rust Compiler, you can write smart contracts in Rust. The compiler transpiles Rust code into Miden Assembly (MASM) which runs on the Miden VM. +- Miden Assembly (MASM): A low-level assembly language that runs directly on the Miden VM. MASM can be written manually for more fine-grained control. + +For interacting with the network programmatically, Miden provides: + +- Rust Client: A Rust library for backend developers +- Web Client: A TypeScript library for frontend and browser-based applications + +What is the difference between the Rust Client and the Web Client? + +Both clients allow you to deploy accounts, create transactions, and interact with the Miden network — but they are designed for different use cases: + +Rust Client | Web Client +Language | Rust | TypeScript +Environment | Backend / native applications | Browser / frontend applications +State storage | Local filesystem | Browser storage +Best for | Programmatic interaction, scripts, server-side apps | Web applications, dApps + +If you are building a backend service or running scripts, use the Rust Client. If you are building a browser-based application, use the Web Client. + +Is there a testnet? How do I connect to it? + +Yes, Miden has a public testnet. You can connect to it at: + +``` +rpc.testnet.miden.io:443 +``` + +To get testnet tokens, visit the [Miden Faucet](https://faucet.testnet.miden.io/). To explore accounts and transactions on testnet, use [Miden Scan](https://testnet.midenscan.com/). + +Is Miden EVM-compatible? + +No. Miden uses its own virtual machine (the Miden VM) and its own assembly language (MASM). It is not EVM-compatible and does not run Solidity contracts. This is an intentional architectural decision — the Miden VM is purpose-built for efficient STARK proof generation, which requires a different design than the EVM. + +How do I test my Miden smart contracts locally? + +Miden provides MockChain — a local testing environment that simulates the Miden network without requiring a live node connection. MockChain allows you to write unit tests for your smart contracts, verify state transitions, and debug issues before deploying to testnet. See the [Testing with MockChain](/builder/develop/tutorials/rust-compiler/testing) guide for details. + +## What is `midenup` and how do I install it? + +`midenup` is the official Miden toolchain installer, similar to `rustup` for Rust. It manages Miden toolchain versions and installs the `miden` CLI. To install it, follow the [Quick Start guide](/builder/quick-start/). + +> Note for Ubuntu/Linux users: After installation, you may need to add the Miden binaries to your PATH manually. If `miden --version` returns "command not found" after installing, run: +> ```bash +> echo 'export PATH="/home/YOUR_USERNAME/.local/share/midenup/bin:$PATH"' >> ~/.bashrc +> source ~/.bashrc +> ``` +> Replace `YOUR_USERNAME` with your actual username. + +Can I try Miden without installing anything? + +Yes. The [Miden Playground](https://playground.miden.xyz) is a browser-based environment where you can write and run MASM programs without any local setup. It is the recommended starting point for developers who want to explore Miden before committing to a full local installation. + +Where can I get help if I'm stuck? + +- [Build On Miden Telegram](https://t.me/BuildOnMiden) — the most active community channel for developer questions +- [GitHub Issues](https://github.com/0xMiden/miden-docs/issues) — for documentation bugs or gaps +- [Miden Docs](https://docs.miden.xyz) — full technical reference From 1510e467a4d12753596edc2103582d8932ee6bd5 Mon Sep 17 00:00:00 2001 From: Robbian Saputra Gumay <120354104+Alice699@users.noreply.github.com> Date: Tue, 3 Mar 2026 15:46:33 +0700 Subject: [PATCH 4/6] Update MockChain description in FAQ Adds 10 new FAQ entries covering questions commonly asked by new developers: notes, public vs private transactions, programming languages, Rust Client vs Web Client, testnet access, EVM compatibility, local testing with MockChain, midenup installation, browser-based playground, and getting help. --- docs/builder/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/builder/faq.md b/docs/builder/faq.md index bfb82c6e..c738bc8f 100644 --- a/docs/builder/faq.md +++ b/docs/builder/faq.md @@ -148,7 +148,7 @@ No. Miden uses its own virtual machine (the Miden VM) and its own assembly langu How do I test my Miden smart contracts locally? -Miden provides MockChain — a local testing environment that simulates the Miden network without requiring a live node connection. MockChain allows you to write unit tests for your smart contracts, verify state transitions, and debug issues before deploying to testnet. See the [Testing with MockChain](/builder/develop/tutorials/rust-compiler/testing) guide for details. +Miden provides MockChain a local testing environment that simulates the Miden network without requiring a live node connection. MockChain allows you to write unit tests for your smart contracts, verify state transitions, and debug issues before deploying to testnet. See the [Testing with MockChain](/builder/develop/tutorials/rust-compiler/testing) guide for details. ## What is `midenup` and how do I install it? From b498e4f67a59a74d8990384d97ebcbbc8d773c1d Mon Sep 17 00:00:00 2001 From: Robbian Saputra Gumay <120354104+Alice699@users.noreply.github.com> Date: Tue, 3 Mar 2026 16:00:13 +0700 Subject: [PATCH 5/6] revert: restore faq.md to original --- docs/builder/faq.md | 79 +++------------------------------------------ 1 file changed, 4 insertions(+), 75 deletions(-) diff --git a/docs/builder/faq.md b/docs/builder/faq.md index c738bc8f..080dff56 100644 --- a/docs/builder/faq.md +++ b/docs/builder/faq.md @@ -4,11 +4,11 @@ How is privacy implemented in Miden? Miden leverages zero-knowledge proofs and client side execution and proving to provide security and privacy. -Does Miden support encrypted notes? +## Does Miden support encrypted notes? At the moment, Miden does not have support for encrypted notes but it is a planned feature. -Why does Miden have delegated proving? +## Why does Miden have delegated proving? Miden leverages delegated proving for a few technical and practical reasons: @@ -45,7 +45,7 @@ What is the lifecycle of a transaction? - The current state relevant to the transaction is loaded - The Miden VM executes the transaction operations -- State Transition Computation: The resulting state transitions are computed +- **State Transition Computation**: The resulting state transitions are computed - An execution trace of the transaction is generated which captures all the computation 5. Proof Generation @@ -96,77 +96,6 @@ How does bridging works in Miden? Miden does not yet have a fully operational bridge, work in progress. -## What does the gas fee model of Miden look like? +What does the gas fee model of Miden look like? Miden does not yet have a fully implemented fee model, work in progress. - -What is a note in Miden? - -A note is the primary mechanism for transferring assets and communicating between accounts in Miden. Unlike account-to-account transfers on most blockchains, Miden uses a note-based model where assets are wrapped in notes that are consumed by recipient accounts. Each note contains assets, a script that defines the conditions under which it can be consumed, and inputs that parameterize that script. - -What is the difference between a public and a private transaction? - -In a public transaction, the transaction details — including inputs, outputs, and state changes — are visible on-chain. In a private transaction, execution happens client-side and only a validity proof is submitted to the network. The network verifies the proof without learning the details of the transaction. This is one of Miden's core differentiators: privacy is not a layer added on top, but a property built into the transaction model itself. - -What programming languages can I use to build on Miden? - -Miden supports two primary development paths: - -- Rust: Using the Miden Rust Compiler, you can write smart contracts in Rust. The compiler transpiles Rust code into Miden Assembly (MASM) which runs on the Miden VM. -- Miden Assembly (MASM): A low-level assembly language that runs directly on the Miden VM. MASM can be written manually for more fine-grained control. - -For interacting with the network programmatically, Miden provides: - -- Rust Client: A Rust library for backend developers -- Web Client: A TypeScript library for frontend and browser-based applications - -What is the difference between the Rust Client and the Web Client? - -Both clients allow you to deploy accounts, create transactions, and interact with the Miden network — but they are designed for different use cases: - -Rust Client | Web Client -Language | Rust | TypeScript -Environment | Backend / native applications | Browser / frontend applications -State storage | Local filesystem | Browser storage -Best for | Programmatic interaction, scripts, server-side apps | Web applications, dApps - -If you are building a backend service or running scripts, use the Rust Client. If you are building a browser-based application, use the Web Client. - -Is there a testnet? How do I connect to it? - -Yes, Miden has a public testnet. You can connect to it at: - -``` -rpc.testnet.miden.io:443 -``` - -To get testnet tokens, visit the [Miden Faucet](https://faucet.testnet.miden.io/). To explore accounts and transactions on testnet, use [Miden Scan](https://testnet.midenscan.com/). - -Is Miden EVM-compatible? - -No. Miden uses its own virtual machine (the Miden VM) and its own assembly language (MASM). It is not EVM-compatible and does not run Solidity contracts. This is an intentional architectural decision — the Miden VM is purpose-built for efficient STARK proof generation, which requires a different design than the EVM. - -How do I test my Miden smart contracts locally? - -Miden provides MockChain a local testing environment that simulates the Miden network without requiring a live node connection. MockChain allows you to write unit tests for your smart contracts, verify state transitions, and debug issues before deploying to testnet. See the [Testing with MockChain](/builder/develop/tutorials/rust-compiler/testing) guide for details. - -## What is `midenup` and how do I install it? - -`midenup` is the official Miden toolchain installer, similar to `rustup` for Rust. It manages Miden toolchain versions and installs the `miden` CLI. To install it, follow the [Quick Start guide](/builder/quick-start/). - -> Note for Ubuntu/Linux users: After installation, you may need to add the Miden binaries to your PATH manually. If `miden --version` returns "command not found" after installing, run: -> ```bash -> echo 'export PATH="/home/YOUR_USERNAME/.local/share/midenup/bin:$PATH"' >> ~/.bashrc -> source ~/.bashrc -> ``` -> Replace `YOUR_USERNAME` with your actual username. - -Can I try Miden without installing anything? - -Yes. The [Miden Playground](https://playground.miden.xyz) is a browser-based environment where you can write and run MASM programs without any local setup. It is the recommended starting point for developers who want to explore Miden before committing to a full local installation. - -Where can I get help if I'm stuck? - -- [Build On Miden Telegram](https://t.me/BuildOnMiden) — the most active community channel for developer questions -- [GitHub Issues](https://github.com/0xMiden/miden-docs/issues) — for documentation bugs or gaps -- [Miden Docs](https://docs.miden.xyz) — full technical reference From 9a82976b6facac1d9b237dd1418d9ea2f9d74f91 Mon Sep 17 00:00:00 2001 From: Robbian Saputra Gumay <120354104+Alice699@users.noreply.github.com> Date: Tue, 3 Mar 2026 16:15:44 +0700 Subject: [PATCH 6/6] docs: expand FAQ with questions for new developers Adds 10 new FAQ entries covering questions commonly asked by new developers: notes, public vs private transactions, programming languages, Rust Client vs Web Client, testnet access, EVM compatibility, local testing with MockChain, midenup installation, browser-based playground, and getting help. All existing FAQ entries are preserved exactly as written. This PR is purely additive. --- docs/builder/faq.md | 73 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 3 deletions(-) diff --git a/docs/builder/faq.md b/docs/builder/faq.md index 080dff56..70b0dc0d 100644 --- a/docs/builder/faq.md +++ b/docs/builder/faq.md @@ -4,11 +4,11 @@ How is privacy implemented in Miden? Miden leverages zero-knowledge proofs and client side execution and proving to provide security and privacy. -## Does Miden support encrypted notes? +Does Miden support encrypted notes? At the moment, Miden does not have support for encrypted notes but it is a planned feature. -## Why does Miden have delegated proving? +Why does Miden have delegated proving? Miden leverages delegated proving for a few technical and practical reasons: @@ -45,7 +45,7 @@ What is the lifecycle of a transaction? - The current state relevant to the transaction is loaded - The Miden VM executes the transaction operations -- **State Transition Computation**: The resulting state transitions are computed +- State Transition Computation: The resulting state transitions are computed - An execution trace of the transaction is generated which captures all the computation 5. Proof Generation @@ -99,3 +99,70 @@ Miden does not yet have a fully operational bridge, work in progress. What does the gas fee model of Miden look like? Miden does not yet have a fully implemented fee model, work in progress. + +What is a note in Miden? + +A note is the primary mechanism for transferring assets and communicating between accounts in Miden. Unlike account-to-account transfers on most blockchains, Miden uses a note-based model where assets are wrapped in notes that are consumed by recipient accounts. Each note contains assets, a script that defines the conditions under which it can be consumed, and inputs that parameterize that script. + +What is the difference between a public and a private transaction? + +In a public transaction, the transaction details including inputs, outputs, and state changes are visible on-chain. In a private transaction, execution happens client-side and only a validity proof is submitted to the network. The network verifies the proof without learning the details of the transaction. This is one of Miden's core differentiators: privacy is not a layer added on top, but a property built into the transaction model itself. + +What programming languages can I use to build on Miden? + +Miden supports two primary development paths: + +- Rust: Using the Miden Rust Compiler, you can write smart contracts in Rust. The compiler transpiles Rust code into Miden Assembly (MASM) which runs on the Miden VM. +- Miden Assembly (MASM): A low-level assembly language that runs directly on the Miden VM. MASM can be written manually for more fine-grained control. + +For interacting with the network programmatically, Miden provides: + +- Rust Client: A Rust library for backend developers +- Web Client: A TypeScript library for frontend and browser-based applications + +What is the difference between the Rust Client and the Web Client? + +Both clients allow you to deploy accounts, create transactions, and interact with the Miden network but they are designed for different use cases: + +| Rust Client | Web Client | +| Language | Rust | TypeScript | +| Environment | Backend / native applications | Browser / frontend applications | +| State storage | Local filesystem | Browser storage | +| Best for | Programmatic interaction, scripts, server-side apps | Web applications, dApps | + +If you are building a backend service or running scripts, use the Rust Client. If you are building a browser-based application, use the Web Client. + +Is there a testnet? How do I connect to it? + +Yes, Miden has a public testnet. You can connect to it at: +```rpc.testnet.miden.io:443``` +To get testnet tokens, visit the [Miden Faucet](https://faucet.testnet.miden.io/). To explore accounts and transactions on testnet, use [Miden Scan](https://testnet.midenscan.com/). + +Is Miden EVM-compatible? + +No. Miden uses its own virtual machine (the Miden VM) and its own assembly language (MASM). It is not EVM-compatible and does not run Solidity contracts. This is an intentional architectural decision the Miden VM is purpose-built for efficient STARK proof generation, which requires a different design than the EVM. + +How do I test my Miden smart contracts locally? + +Miden provides MockChain a local testing environment that simulates the Miden network without requiring a live node connection. MockChain allows you to write unit tests for your smart contracts, verify state transitions, and debug issues before deploying to testnet. See the [Testing with MockChain](/builder/develop/tutorials/rust-compiler/testing) guide for details. + +What is `midenup` and how do I install it? + +`midenup` is the official Miden toolchain installer, similar to `rustup` for Rust. It manages Miden toolchain versions and installs the `miden` CLI. To install it, follow the [Quick Start guide](/builder/quick-start/). + +> Note for Ubuntu/Linux users: After installation, you may need to add the Miden binaries to your PATH manually. If `miden --version` returns "command not found" after installing, run: +> ```bash +> echo 'export PATH="/home/YOUR_USERNAME/.local/share/midenup/bin:$PATH"' >> ~/.bashrc +> source ~/.bashrc +> ``` +> Replace `YOUR_USERNAME` with your actual username. + +Can I try Miden without installing anything? + +Yes. The [Miden Playground](https://playground.miden.xyz) is a browser-based environment where you can write and run MASM programs without any local setup. It is the recommended starting point for developers who want to explore Miden before committing to a full local installation. + +Where can I get help if I'm stuck? + +- [Build On Miden Telegram](https://t.me/BuildOnMiden) — the most active community channel for developer questions +- [GitHub Issues](https://github.com/0xMiden/miden-docs/issues) — for documentation bugs or gaps +- [Miden Docs](https://docs.miden.xyz) — full technical reference