This repository holds the Miden node; that is, the software which processes transactions and creates blocks for the Miden rollup.
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.
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).
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 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 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
You can verify the installation by checking the node's version:
miden-node --version
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 \
--inputs-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.
An example service file is provided here. If you used the Debian package installer then this service was already installed alongside it.
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
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.
See our contributing guidelines and our makefile for example workflows e.g. run the testsuite using
make test
This project is MIT licensed.