Miden node

This repository holds the Miden node; that is, the software which processes transactions and creates blocks for the Miden rollup.

Status

The Miden node is still under heavy development and the project can be considered to be in an alpha stage. Many features are yet to be implemented and there are a number of limitations which we will lift in the near future.

At this point, we are developing the Miden node for a centralized operator. As such, the work does not yet include components such as P2P networking and consensus. These will be added in the future.

Architecture

The Miden node consists of 3 main components, which communicate using gRPC:

• RPC: an externally-facing component through which clients can interact with the node. It receives client requests (e.g., to synchronize with the latest state of the chain, or to submit transactions), performs basic validation, and forwards the requests to the appropriate internal components.
• Store: maintains the state of the chain. It serves as the "source of truth" for the chain - i.e., if it is not in the store, the node does not consider it to be part of the chain.
• Block Producer: accepts transactions from the RPC component, creates blocks containing those transactions, and sends them to the store.

All 3 components can either run as one process, or each component can run in its own process. See the Running the node section for more details.

The diagram below illustrates high-level design of each component as well as basic interactions between them (components in light-grey are yet to be built).

Installation

The node software can be installed as a Debian package or using Rust's package manager cargo.

Official releases are available as debian packages which can be found under our releases page.

Alternatively, the Rust package manager cargo can be used to install on non-debian distributions or to compile from source.

Debian package

Debian packages are available and are the fastest way to install the node on a Debian-based system. Currently only amd64 architecture are supported.

These packages can be found under our releases page along with a checksum.

Note that this includes a systemd service called miden-node (disabled by default).

To install, download the desired releases .deb package and checksum files. Install using

sudo dpkg -i $package_name.deb

Tip

You should verify the checksum using a SHA256 utility. This differs from platform to platform, but on most linux distros:

sha256sum --check $checksum_file.deb.checksum

can be used so long as the checksum file and the package file are in the same folder.

Install using cargo

Install Rust version 1.82 or greater using the official Rust installation instructions.

Depending on the platform, you may need to install additional libraries. For example, on Ubuntu 22.04 the following command ensures that all required libraries are installed.

sudo apt install llvm clang bindgen pkg-config libssl-dev libsqlite3-dev

Install the node binary for production using cargo:

cargo install miden-node --locked

This will install the latest official version of the node. You can install a specific version using --version <x.y.z>:

cargo install miden-node --locked --version x.y.z

You can also use cargo to compile the node from the source code if for some reason you need a specific git revision. Note that since these aren't official releases we cannot provide much support for any issues you run into, so consider this for advanced users only. The incantation is a little different as you'll be targetting this repo instead:

# Install from a specific branch
cargo install --locked --git https://github.com/0xPolygonMiden/miden-node miden-node --branch <branch>

# Install a specific tag
cargo install --locked --git https://github.com/0xPolygonMiden/miden-node miden-node --tag <tag>

# Install a specific git revision
cargo install --locked --git https://github.com/0xPolygonMiden/miden-node miden-node --rev <git-sha>

More information on the various options can be found here.

Tip

Miden account generation uses a proof-of-work puzzle to prevent DoS attacks. These puzzles can be quite expensive, especially for test purposes. You can lower the difficulty of the puzzle by appending --features testing to the cargo install .. invocation. For example:

cargo install miden-node --locked --features testing

Verify installation

You can verify the installation by checking the node's version:

miden-node --version

Usage

Setup

Decide on a location to store all the node data and configuration files in. This guide will use the placeholder <STORAGE> and <CONFIG> to represent these directories. They are allowed to be the same, though most unix distributions have conventions for these being /opt/miden and /etc/miden respectively. Note that if you intend to use the systemd service then by default it expects these conventions to be upheld.

We need to configure the node as well as bootstrap the chain by creating the genesis block. Generate the default configurations for both:

miden-node init \
  --config-path  <CONFIG>/miden-node.toml \
  --genesis-path <CONFIG>/genesis.toml  

which will generate miden-node.toml and genesis.toml files. The latter controls the accounts that the genesis block will be spawned with and by default includes a basic wallet account and a basic fungible faucet account. You can modify this file to add/remove accounts as desired.

Next, bootstrap the chain by generating the genesis data:

miden-node make-genesis \
  --input-path  <CONFIG>/genesis.toml \
  --output-path <STORAGE>/genesis.dat

which will create genesis.dat and an accounts directory containing account data based on the genesis.toml file.

Note

make-genesis will take a long time if you're running the production version of miden-node, see the tip in the installation section.

Modify the miden-node.toml configuration file such that the [store] paths point to our <STORAGE> folder:

[store]
database_filepath = "<STORAGE>/miden-store.sqlite3"
genesis_filepath  = "<STORAGE>/genesis.dat"
blockstore_dir    = "<STORAGE>/blocks"

Finally, configure the node's endpoints to your liking.

Systemd

An example service file is provided here. If you used the Debian package installer then this service was already installed alongside it.

Running the node

Using the node configuration file created in the previous step, start the node:

miden-node start \
  --config <CONFIG>/miden-node.toml \
  node

or alternatively start the systemd service if that's how you wish to operate:

systemctl start miden-node.service

Updating

We currently make no guarantees about backwards compatibility. Updating the node software therefore consists of wiping all existing data and re-installing the node's software again. This includes regenerating the configuration files and genesis block as these formats may have changed. This effectively means every update is a complete reset of the blockchain.

First stop the currently running node or systemd service then remove all existing data. If you followed the Setup section, then this can be achieved by deleting all information in <STORAGE>:

rm -rf <STORAGE>

Warning

Failure to remove existing node data could result in strange behaviour.

Development

See our contributing guidelines and our makefile for example workflows e.g. run the testsuite using

make test

License

This project is MIT licensed.