Quick Start Guide

[Keinberger]

Quick Start Guide

As of right now, our docs do not offer readers a direct and quick way to get started with developing on Miden.

Henceforth we have decided to work on including that. This guide will mostly work by introducing our users to Miden through CLI tooling and making use of our Miden Rust & Web Client SDKs.

Motivation

Similar blockchain projects like Solana, Sui and Aztec do offer "Quick Start" guides, which often serve as quick reference books for devs and offer anyone a straight and easy to understand way to get started with developing on Miden.

Beyond that, such a guide will also introduce readers to important basic concepts of the Miden protocol, which are vital for developing on Miden (Accounts, Notes, Transaction flow, etc...).

Reference Quick-Start sections of other projects:

• Solana
• Sui
• Starknet

Structure & Content

The Quick Start guide follows this structure (each point represents a page in the documentation):

1. Installation & Set Up
   • 1.1 Rust & midenup installation
   • 1.2 midenup CLI Basics: Creating a simple wallet and minting assets from a network faucet
2. Network Interactions 101
   • 2.1 Transactions: Receiving and sending assets using the Rust and Web Client
   • 2.2 Reading from Network: Making calls to the network using the Rust and Web Client
3. Your First Smart Contract:
   • 3.1: midenup Project CLI Basics: Commands on how to set up a project environment using midenup
   • 3.2: Deploying the Smart Contract
   • 3.3: Testing the Smart Contract

1 Installation & Set Up Instruction

This section provides a streamlined introduction to Miden development using exclusively CLI tools. You'll learn to install the Miden toolchain and perform essential operations like wallet creation and asset minting through simple command-line interfaces. The focus is on getting you up and running quickly with minimal setup complexity.

1.1

This page serves as the entry point for developers. It provides installation and configuration instructions for both midenup and Rust.

1.2

This page serves as a quick reference for essential midenup CLI commands. It includes guidance on creating a wallet and minting assets from a network faucet, each accomplished with a single CLI command.

This page will utilize new miden-client CLI commands for directly instantiating wallets and minting tokens from network faucets.

2. Network Interactions 101

This section guides users through using the Rust and Web Client to create accounts, execute transactions, work with notes, and read values from the network.

This section serves two main purposes: 1) providing developers with a quick reference for basic client SDK operations and 2) teaching core Miden concepts like "Accounts" and "Notes".

2.1

This page guides users through transaction execution on Miden. It explains how to create a Miden account and use it to create and consume notes for asset transfers. The page includes details about account components, types, and general account functionality on Miden, along with comprehensive information about notes.

Additionally, this page introduces users to Miden's unique transaction model, including the actor model, notes, faucets, and assets.

2.2

This page explains how to read values from the network. It serves as a reference for developers who want to interact with the Miden network using the Rust and Web Client.

Beyond learning Rust / Web Client SDK functionality for retrieving storage values, the main learning objective is understanding Account Storage architecture, including words & felts, mapping slots, and value slots.

3. Your First Smart Contract

This guide uses the miden new command to create a local development environment.

It walks users through a simple demo smart contract (counter contract or example bank contract) and teaches the complete Miden development workflow: building, testing, and deploying smart contracts.

3.1 Setting up local environment

Covers environment setup using miden new and teaches users proper repository structure.

3.2 Deploying the Smart Contract

This page teaches users how to deploy their contracts. Ideally, this should utilize a CLI-integrated "script" command for contract deployment, similar to the current miden-client exec command.

The deployment workflow should be as straightforward as deploying contracts using Foundry. See details here: Script deployment using Foundry

3.3 Testing the Smart Contract

This page provides developers with standardized boilerplate code and guidance for structuring tests for Miden smart contracts.

Many community members have requested best practices for testing Miden smart contracts and organizing test suites effectively.

Essentially, this page establishes a best-practice foundation for testing methodology.

Regarding CLI integration, while it may not be strictly required, we might consider adding a miden test command that maps to cargo test for running all tests in a test/ directory.

Table

Installation & Set Up Pages

Page Name	Description	Dev Purpose	Key Learning Takeaway
Rust & midenup Installation	Entry-point guide with installation & configuration instructions for midenup and Rust	Setting up development environment	Understanding the Miden development toolchain and getting a working local setup
midenup CLI Basics	Quick reference for simple midenup CLI commands: creating wallets and minting assets	Basic wallet and asset management	Essential CLI operations for wallet creation and asset minting from network faucets

Network Interactions 101 Pages

Page Name	Description	Dev Purpose	Key Learning Takeaway
Transactions	Receiving and sending assets using the Rust and Web Client	Asset transfers and transaction execution using the client SDKs	Miden's transaction model, actor model, notes, and asset management using client SDKs
Reading from Network	Making calls to the network using the Rust and Web Client	Network interaction and data retrieval using the client SDKs	Account Storage architecture (words & felts, mapping slots, value slots) and client usage

Your First Smart Contract Pages

Page Name	Description	Dev Purpose	Key Learning Takeaway
midenup Project CLI Basics	Commands for setting up a project environment using midenup	Project initialization and workspace setup	Proper repository structure and development environment configuration for Miden projects
Deploying the Smart Contract	Contract deployment process using CLI-integrated scripts	Contract deployment to testnet/mainnet	Deployment workflows, contract compilation, and production deployment best practices
Testing the Smart Contract	Standardized testing patterns and boilerplate code for Miden smart contracts	Writing and running comprehensive tests	Testing methodology, test structure patterns / best practices for Miden smart contracts / Note scripts

Work-In-Progress version:

The WIP guide can be found on this branch of the miden-docs repo: https://github.com/0xMiden/miden-docs/tree/feat/getting-started

If you want to try out the guide, please be sure to run the following commands in the miden-docs repository to run the local Docusaurus server and view the docs:

npm install
npm run start

Note: The Smart Contract guide is not included yet as many things depend on clarifying midenup and miden-client CLI features.

External dependencies for Quick Start Guide

The Quick Start Guide depends on several components across the Miden ecosystem, including miden-client and midenup toolchain features. Many of these dependencies require consensus on implementation approaches and coordination between different parts of the Miden project. The following sections outline both critical requirements needed immediately and future enhancements that will improve the developer experience.

Critical (absolutely needed)

Feature	Why Needed	GitHub
Project structure consensus	Needed for Smart Contract guide to provide standardized development patterns	compiler#646
miden-client silent initialization	Essential so that midenup aliases for miden-client commands work out of the box without requiring individual toolchain component initialization (confusing for users interfacing only through midenup aliases)	miden-client#1424
mint CLI command	Critical for minting testnet tokens without requiring developers to deploy their own faucet	miden-client#1396
miden-client global directory	Prevents local files in working directory, creating a more seamless and less confusing developer experience	miden-client#1366
Assembly project structure	Potentially needed if Rust compiler development isn't viable from a marketing perspective - would require a command to initialize work environments exclusively with Miden Assembly	midenup#109

Needed in the future for a good dev experience

Feature	Why Needed	GitHub
Default web-client project	Frontend developers need to manage Notes effectively, requiring best-practice guidance on structuring frontend repositories	midenup#115
Script CLI integration	Essential for seamless network interaction and contract deployment experience comparable to popular frameworks like Foundry	miden-client#1398
Test CLI integration	Required for seamless, standardized testing framework that matches the quality of popular frameworks like Foundry	midenup#111
Deploy command	CLI contract deployment functionality for deploying single contracts from a file-path	miden-client#1397
Call command	Direct CLI contract interaction capabilities	miden-client#1395

Goals

The Quick Start Guide serves three core purposes that will accelerate Miden ecosystem adoption:

1. Quick Reference for Common Development Tasks

A practical reference for operations like creating accounts, transferring assets, reading storage, and deploying contracts that remains valuable beyond initial learning.

2. Best-Practice Template for Smart Contract Development

Standardized patterns for project structure, testing, and deployment workflows that our community has been requesting - establishing consistency across the ecosystem.

3. Quick-Guide for Core Miden Concepts

An accessible entry point for understanding fundamental Miden concepts like the actor model, account types, and note-based transactions without overwhelming technical depth.

This guide should match industry standards (Solana, Sui, Starknet), accelerate developer adoption by reducing time-to-first-success from days to hours, and establish the foundation for consistent & high-quality development practices for Miden projects.

[guelowrd]

First things first: Great work, Philipp – this is looking great already 🙂

Conceptual vs practical

As mentioned separately, I wanted to bring up a quick reflection on the "conceptual vs practical" ratio we currently have in the Quick Start. To get a better sense of what others are doing, I went through Solana’s and Sui’s Quick Start guides for comparison.

TL;DR comparison

• Solana’s approach: Still conceptually rich, but every explanation is wrapped around a task. Concepts appear in small doses right between commands – just enough to explain what’s happening before moving on. It keeps the reader active, constantly alternating between reading and doing.
• Sui’s approach: Much more minimal and purely hands-on – almost no conceptual content at all. It’s basically a straight sequence of commands that gets you from zero to first success.
• Miden right now: In terms of ratio, we’re quite close to Solana — but the “why” and “how” are more separated. The conceptual explanations come in large blocks before any code appears, which makes the early part heavier for someone who just wants to start running commands.

Observation

I think we could move closer to Solana’s rhythm by sprinkling short conceptual notes throughout the flow rather than grouping them all at the start. That way, the Quick Start stays practical and fast, while still introducing the key ideas right when they become relevant.

But it's not only about being easy to read, it’s also a structural question – whether we want the Quick Start to be a “rubric for monkeys” 🐒 (fastest path to first success) or lean more toward a “learn by doing” guide. Both directions make sense; I just think it's worth aligning on the intention before we iterate further.

Small polish & potential fixes

This is just to keep track of a few smaller things I noticed while reading through the new Quick Start.
Some of these may already be addressed – just listing them here so nothing slips through.

Quick Start page

• Some longer outputs or setup steps (like “Install Rust”) could optionally be collapsible, similar to the Expected output blocks. Or the block could start with "If you already have Rust installed, skip to /quick-start/#install-miden-cli"
• It might help to mention at the very top that midenup is the toolchain installer and miden is the CLI alias – to avoid confusion later. It's technically "Install the toolchain installer" then "Install the toolchain" (thanks to the newly installed toolchain installer) 😅
• Having the details about what will be learned is great ("In this tutorial, you will learn about" bit). We can also be clear abt the things done in the 1st page, "Before you can get started developing on Miden, you need to install the correct binaries and dependencies: Rust, midenup, miden CLI" for instance

Create Account

• The line “think of Miden account as your smart programmable wallet…” seems cut mid-way
• “Understanding Miden Accounts” might be better as a separate page or collapsible section rather than inline (see discussion here)
• Could add a quick note on where generated files are stored

Transactions

• Explanations are clear but maybe too verbose right before the first commands (again, see discussion here)
• Might be worth adding a short 1-liner intro: “In Miden, transactions are executed and proven locally and only proofs are sent onchain.”
• Expected output boxes are great, let's keep those consistent across all pages

Read Storage

• Intro could start with one short framing line: “Now that you have an account, let’s explore its contents.”
• Link forward to next logical step (e.g. “Next: send your first transaction”, but I guess eventually it won't be the Roadmap after this)

[Dominik1999]

This is a really nice writeup and thank you for all the effort you have put in here. I was thinking about it a bit more as well. Currently the Quick Start Guide uses the miden client CLI quite heavily, but actually, that is not what people should learn. People should learn how to use those concepts in Rust or TypeScript, but there should be quick wins.

Let me explain in more detail: I suggest, that we have a overarching "Getting Started" section, that has two sub-sections "Installation" and "Quick Start".

• Installation can guide the user to (1) install the dependencies (Rust, cargo miden, midenup), (2) create a simple wallet account and fund it, and (3) lets the user to create a Miden project using midenup
• Quick Start can then guide the user through what you have defined about (Account creation, Transaction, Reading values, Deploying smart contracts / custom components), but in Rust or using a toggle TypeScript

The first section "Installation" can in subsection (2) consists of super simple commands of miden or midenup. It might be only miden wallet new --private and the CLI shows the new wallet account. miden mint would be a new command that mints tokens from a default faucet and the wallet consumes it. This follows pretty closely to the "Solana CLI basics" from the Solana docs.

The second section in "Installation" should explain midenup and in the end the user has created a new project (structure to be defined) in which the user has a main Rust or TypeScript file. We have most of it already in midenup, a user can simply compile and deploy. This is what is explained in the "Anchor basics" in the Solana docs. Anchor is their development framework.

Now the Quick Start section can use what is in the new Miden project and the user can copy code snippets in there. We follow your structure. First, we create a simple Account, but not using the CLI and explain what is happening. When the user runs it with a command, we see the effects. Then we create a transaction using the TransactionBuilder and send tokens to some other account. Then we read a storage slot, for example the token symbol from a faucet. And in the end, we let the user work on a smart contract (which is basically just an account component) that we add to the account.