midenup

The Miden toolchain installer.

Warning

This tool is still a work in progress.

The midenup executable facilitates two primary tasks:

1. Toolchain management, i.e. bootstrapping the environment, and installing, updating, and configuring installed toolchain components.
2. Using toolchains for working on Miden projects

Note

The notion of a toolchain here refers to the various components of the Miden project which are required in order to develop, test, run, and interact with Miden programs, both locally and on the network.

Currently, the set of such components consists of:

• Miden VM
• The Miden compiler, midenc, and its Rust tooling, i.e. cargo-miden
• The Miden client
• The Miden standard library
• The Miden transaction kernel library

In the future, more components will be added.

Usage

To get started, you must first install midenup, and then initialize its environment, like so:

cargo install midenup && midenup init

The midenup init command initializes the $MIDENUP_HOME directory, and creates a miden symlink in $CARGO_HOME/bin (default ~/.cargo/bin) pointing to the midenup executable. Since Rust users typically already have $CARGO_HOME/bin in their PATH, the miden command should be available immediately.

Warning

If miden is not found after running midenup init, ensure $CARGO_HOME/bin is in your PATH. On macOS with zsh, add export PATH="$HOME/.cargo/bin:$PATH" to ~/.zprofile and create that file first if it does not exist.

You are now ready to install your first toolchain!

Installing a toolchain

After initializing midenup, the first thing you will want to do is actually install a toolchain so you can work with the various Miden components. There are two ways to do this:

1. Installing a release network, e.g. mainnet, which installs the toolchain currently deployed to that network. When a network is promoted to a newer toolchain, midenup update mainnet follows it, carrying your component selection and any toolchain-managed data across.
2. Installing a specific toolchain version, e.g. 0.15.0, which pins you to that toolchain regardless of what the networks do.

In both cases, you simply run midenup install <TOOLCHAIN>.

The networks are:

Network	Also accepted as	What it is
mainnet	stable	The toolchain deployed to mainnet
testnet	beta	The toolchain deployed to testnet
devnet	nightly	The toolchain deployed to devnet

When getting started, it is recommended that you install the mainnet toolchain, like so:

midenup install mainnet

midenup also assumes mainnet to be the default toolchain if not overridden in the current working directory or by the user's default toolchain (for more information on how to configure the active toolchain, see Configuring the active toolchain).

Updating a toolchain

To update a given toolchain, you can use the midenup update <TOOLCHAIN> command. This command's behavior differs slightly depending on how it is called.

Updating a network

To bring a network up to the toolchain it now runs, run:

midenup update mainnet

This follows the network's pointer wherever it has moved, carrying your component selection and toolchain-owned data across. If the pointer has not moved, it still picks up any changes to the components of the toolchain it names.

Updating a specific toolchain

When updating a versioned toolchain, only updates which are known to work with that version of the toolchain will be installed/updated.

For example, if you'd like to update toolchain version 0.16.0, run:

midenup update 0.16.0

Using a toolchain

Interacting with Miden toolchain components is done via the miden command, which handles delegating commands to the underlying components using subprocesses. For example, miden new calls out to cargo miden new to create a new Rust-based Miden project.

By default, the miden command uses the currently active toolchain, which you can view using midenup show active-toolchain. To see how to configure the active toolchain, see Configuring the active toolchain section.

Aliases

To facilitate development, the miden command is also aware of a number of aliases. These aliases exist to facilitate the execution of common miden task.

Here's a table with all the currently available aliases:

Alias	Action	Corresponds to
miden account	Create local account	miden-client account
miden faucet	Fund account via faucet	miden-client mint
miden new	Create new project	cargo miden new
miden build	Build project	cargo miden build
miden deploy	Deploy a contract	miden-client -s public --account-type regular-account-immutable-code
miden new-wallet	Create a wallet	miden-client new-wallet --deploy
miden call	Call a procedure on an account	miden-client call
miden send	Send transaction (state-changing)	miden-client send
miden simulate	Simulate transaction (no commit)	miden-client exec

Uninstalling a toolchain

You can easily uninstall a Miden toolchain with the midenup uninstall <TOOLCHAIN> command. For example, to uninstall toolchain version 0.16.0, run:

midenup uninstall 0.16.0

This keeps the toolchain's mutable data and tells you where it left it. To remove that too, pass --purge:

midenup uninstall 0.16.0 --purge

Warning

It is strongly discouraged to delete the toolchain directories manually, since this will most likely generate an invalid environment and midenup will probably not work as intended.

Reclaiming disk space

Installing or updating a toolchain publishes a fresh copy of it and leaves the previous copy in place, because another shell may still be running a component out of it. Once you are done with those, reclaim them with:

midenup gc

This only ever removes installations nothing refers to any more. It never touches an installed toolchain, and it is safe to run at any time.

Upgrading from an older midenup

The first time a newer midenup runs, it converts the record an older one left in $MIDENUP_HOME into its own format. It carries over which channels you had installed and which components you had in each, and nothing else - everything else is re-derived from the published manifest, which is authoritative for it. Your toolchains are reinstalled the next time you use them, so that midenup knows exactly which files it owns; var/ is untouched throughout.

This is one-way. After the conversion, an older midenup will not see your installation and will report it as absent. If you need to go back, reinstall your toolchains with the older version.

Uninstalling midenup

You can easily uninstall midenup itself by deleting the $MIDENUP_HOME directory. The location of the $MIDENUP_HOME directory can be obtained by running:

midenup show home

Configuring the active toolchain

miden and midenup determine the current active toolchain according to the following rules:

1. If there's a miden-toolchain.toml file in the present working directory, then miden will use that to determine the current active toolchain.
2. If not, miden will check if a toolchain has been set as the system's default (more details in the Configuring the active toolchain section).

If none of the previous conditions are met, then mainnet will be used.

Setting a project specific toolchain

To configure a toolchain to be active in the present working directory, you can use the midenup set <TOOLCHAIN> command. For example, to set 0.16.0 run:

midenup set 0.16.0

This procedure will generate a miden-toolchain.toml file in the directory where midenup set was invoked:

[toolchain]
channel = "0.16.0"
components = []

The channel entry may also name a network, e.g. channel = "mainnet", in which case the project follows that network as it moves. A file written before the networks were named, saying channel = "stable", still works and means mainnet: stable, beta and nightly are accepted as synonyms for mainnet, testnet and devnet.

Now, whenever miden is called in this directory (or any of its subdirectories), it will use the specified toolchain.

The profile entry selects a baseline set of components, and components names extras on top of it. An omitted profile means minimal, so an empty components list installs the minimal profile's members -- not everything. To install every component in the channel, ask for the complete profile:

[toolchain]
channel = "mainnet"
profile = "complete"
components = []

Listing components adds them to the profile's members. With this file:

[toolchain]
channel = "mainnet"
components = ["vm", "midenc", "client"]

the minimal profile is installed, plus vm, midenc and client if they are not already part of it.

Activating a project's toolchain only ever adds to what is installed for a channel. Two projects sharing a channel cannot remove each other's components: if one asks for less, the other's components stay. Use midenup install <channel> --profile <profile> to deliberately reduce what is installed.

Setting a global default toolchain

You can customize your system's default toolchain with midenup override <TOOLCHAIN>. For example, to set 0.16.0 as the default toolchain, run:

midenup override 0.16.0

You can even set toolchains that are not currently installed in the system. midenup (via miden) will handle installation as soon as you use any component from the newly selected toolchain.

Note

If a network such as mainnet is set as the active toolchain, midenup follows that network as it moves. To pin a specific release instead, name its version.

Development

Internally, midenup relies on a channel manifest, which describes the available toolchain channels, their names and versions, and their components. Currently, the canonical version of our channel manifest lives in this repo as channel-manifest.json, and is published to Github Pages here: https://0xmiden.github.io/midenup/channel-manifest.json .

Locally, you can override the channel manifest URI, for testing or development purposes, by setting the MIDENUP_MANIFEST_URI environment variable. The URI must begin with either file:// or https:// at this time, but we could in theory support other URIs in the future if found useful.

The manifest format is described by the Manifest struct in src/manifest/v3/mod.rs, and supports a variety of features that we haven't currently fully implemented, but which are intended to allow for handy functionality such as defining toolchains that pull components from the local filesystem, or from a Git repository.

For now, a simple make build and make test is all you need to work on midenup itself, though there is not yet much in the way of tests.

To work with the midenup executable after running make build, you'll need to invoke it as target/debug/midenup.