This repository contains the implementation of Midnight's ledger, as well as documents specifying its behaviour. It defines the transaction structure and state of Midnight, as well as providing Rust and WASM TypeScript APIs to interact with it.

A good starting point to understanding the ledger is reading the specification.

The ledger currently requires Nix to build and bootstrap. We use the flakes experimental features for nix, which can be enable as part of the nix configuration, or by adding --extra-experimental-features 'nix-command flakes' to the below nix commands. Once nix is installed, the development shell of the ledger can be entered simply with:

$ nix develop

This opens a sub-shell with the correct development environment set-up. If you use direnv, this should work out of the box with Nix installed, by running:

$ direnv allow

Once the devshell has been opened, the ledger behaves as a standard rust project, and can be built with

$ cargo build

Rust-side tests can be run similarly with

$ cargo test

Note that by default, rust-side tests do not do proving. To enable this, pass the --release --features proving flags to cargo test. --release is strongly recommended for proving-enabled tests.

Running WASM/TS tests is more involved, as it requires first requires a complete 'formal' build through nix:

$ nix build
$ ./run_it.sh

Note that nix build internally runs the rust-side tests, checks cargo fmt, and produces optimized build targets, so this is an expensive step.

Once in the devshell, it is possible to generate rust-side documentation simply with cargo doc. However, we also provide a nix-built documentation command, which uses unstable rust features to provide more information about features in the generated docs. This may be run with nix run .#doc, placing generated documentation in target/doc.

The TS API docs for ledger-wasm, onchain-runtime-wasm, and zkir-wasm can each be generated by running:

$ cd <package>
$ npm install
$ npm run build:markdown-docs

The Midnight ledger is predominantly a rust project, structured as a workspace with multiple sub-crates. Below is a table explaining the function of each crate. They are presented here in their direct dependency order, with a table explaining the purpose of each crate below.

graph TD;
    ledger-wasm-->ledger;
    ledger-wasm-->onchain-runtime-wasm;
    zkir-wasm-->zkir;
    proof-server-->ledger;
    proof-server-->zkir;
    ledger-->zswap;
    ledger-->zkir;
    zswap-->onchain-runtime;
    zkir-->transient-crypto;
    onchain-runtime-wasm-->onchain-runtime;
    onchain-runtime-->onchain-vm;
    onchain-vm-->onchain-state;
    onchain-state-->coin-structure;
    coin-structure-->transient-crypto;
    transient-crypto-->storage;
    storage-->base-crypto;
    storage-->storage-macros;
    base-crypto-->serialize;
    base-crypto-->base-crypto-derive;
    serialize-->serialize-macros;

Some of these rust crates use feature flags. For the most part, using default features is the best approach, however the following feature flags may be useful:

In addition to the rust crates, there are some notable directories and files captured in the table below:

The ledger comes with a suite of benchmarks for various basic operations. These can be run with cargo bench, however be warned that in particular the onchain VM benchmarks can take over a day to run! It's recommended to only run a subset of the benchmarks in most cases.

1. For each crate assess the relevant CHANGELOGs and update the versions in Cargo.toml for rust only crates, and in Cargo.toml and package.json for wasm components.
2. Update the CHANGELOGs to capture the features of the new versions
3. Commit changes to a release branch, open a PR for review in the ledger repo
4. Run "Publish Ledger Release" against the release branch
5. After the run is successful merge the PR into main, (bug: this requires squashing CI-generated commits are not signed)

The TypeScript integration tests have their own README covering more specialized usage.