The official Dusk protocol node client and smart contract platform.

           

Unstable : No guarantees can be made regarding the API stability, the project is in development.

🖧 How to run a node

This README is for people who want to develop, test nodes locally, and contribute to the Rusk codebase.

For more information on running a node for main- or testnet, see our Node operator docs

📃 Table of Contents

• Repo Overview
• Prerequisites
  • Setup script
  • Rust Installation
• Build and Tests
• Run a local node for development
  • Spin up local node
    • Prepare modules
    • Run a node
    • Run an archive node
    • Run a prover node
• Contracts compilation
• Docker support

🗺️ Overview

Code projects

Name	Description
🌒 rusk	Entrypoint for the blockchain node
🔗 consensus	Implementation of Dusk's succinct attestation consensus
📜 contracts	Dusk genesis contracts
🧩 data-drivers	Tools to encode/decode contract arguments between RKYV and JS I/O
🧬 dusk-core	Core types used for interacting with Dusk and writing smart contracts
🌐 dusk-abi	Dusk application binary interface to develop smart contracts (part of core)
🧭 explorer	Dusk's blockchain explorer
📊 node-data	Core datatypes for the blockchain node
⚙️ dusk-vm	The virtual machine to run Dusk smart contracts
🪪 rusk-profile	Utility to generate a genesis state based on a set profile
📨 rusk-prover	Service exposing functionality to remotely prove zero knowledge proofs
⬇️ rusk-recovery	Utility to recover the state of a chain
⌨️ rusk-wallet	Dusk CLI wallet
🔨 w3sper.js	Js SDK to integrate Dusk features into applications
⚙️ wallet-core	WASM library providing core logic for Dusk wallet implementations
📱 web-wallet	Cross platform Dusk wallet

Infrastructure & Testing

Name	Description
📂 examples	Example data used for local chain spawning and development
📄 scripts	Utility scripts
🔧 test-wallet	Wallet for testing against the specifications

📝 Prerequisites

• Rust 1.71 nightly or higher
• GCC 13 or higher
• Clang 16 or higher

Setup script

We provide a setup script in the scripts folder that can take care of everything.

bash scripts/dev-setup.sh

Rust Installation

Rusk makes use of the nightly toolchain, make sure it is installed. Furthermore, to build the WASM contracts, wasm-pack is required.

To install and set the nightly toolchain, and install wasm-pack, run:

rustup toolchain install nightly
rustup default nightly
cargo install wasm-pack

🛠️ Build and Tests

To build rusk from source, make sure the prerequisites are met. Then you can simply run the following command to compile everything:

make

To run tests:

make test

That will also compile all the genesis contracts and its associated circuits. See also make help for all the available commands

💻 Run a local node for development

Spin up local node

Run a single full-node cluster with example state.

Prepare modules:

# Generate the keys used by the circuits
# Compile all the genesis contracts
# Copy example consensus.keys
make prepare-dev

Run a Node

# Launch a local ephemeral node
make run-dev

Run an Archive node

make run-dev-archive

Run a Prover Node

The node can be build as a prover only as follows:

cargo r --release --no-default-features --features prover -p dusk-rusk

This prover node will be accessible on https://localhost:8080. Apps like the rusk-wallet can be connected to it for quicker and more private local proving.

📜 Contracts compilation

Compile all the genesis contracts without running the server:

make contracts

Compile a specific genesis contract:

# generate the wasm for `transfer` contract
make wasm for=transfer

🐳 Docker support

Local Ephemeral Node

It's also possible to run a local ephemeral node with Docker.

To build the Docker image with archive:

docker build -f Dockerfile.ephemeral -t rusk .

To build the Docker image without archive:

docker build -t -f Dockerfile.ephemeral rusk --build-arg CARGO_FEATURES="" .

To run Rusk inside a Docker container:

docker run -p 9000:9000/udp -p 8080:8080/tcp rusk

Port 9000 is used for Kadcast, port 8080 for the HTTP and GraphQL APIs.

Persistent Node

To build the docker image for a provisioner

docker build -f Dockerfile.persistent -t rusk --build-arg NODE_TYPE=provisioner .

To build for an archiver or prover instead, build with NODE_TYPE=archive or NODE_TYPE=prover, respectively.

To run:

docker run -it \
  -v /path/to/consensus.keys:/opt/dusk/conf/consensus.keys \
  -v /path/to/rusk/profile:/opt/dusk/rusk \
  -e NETWORK=<mainnet|testnet> \
  -e DUSK_CONSENSUS_KEYS_PASS=<consensus-keys-password> \
  -p 9000:9000/udp \
  -p 8080:8080/tcp \
  rusk

Customizing Configuration

The configuration used for rusk is based on the template file at https://raw.githubusercontent.com/dusk-network/node-installer/ac1dd78eb31be4dba1c9c0986f6d6a06b5bd4fcc/conf/mainnet.toml for mainnet and https://raw.githubusercontent.com/dusk-network/node-installer/ac1dd78eb31be4dba1c9c0986f6d6a06b5bd4fcc/conf/testnet.toml for testnet. As part of the node setup process when the container is started, the IP addresses used for listening in kadcast and, if configured, http will be detected and automatically configured.

To customize the configuration, the configuration template file can be copied and modified. The custom configuration template should be mounted on /opt/dusk/conf/rusk.template.toml.

docker run -it \
  -v /path/to/consensus.keys:/opt/dusk/conf/consensus.keys
  -v /path/to/rusk/profile:/opt/dusk/rusk \
  -v /path/to/rusk.modified-template.toml:/opt/dusk/conf/rusk.template.toml \
  -e NETWORK=<mainnet|testnet|devnet> \
  -e DUSK_CONSENSUS_KEYS_PASS=<consensus-keys-password> \
  -p 9000:9000/udp \
  -p 8080:8080/tcp \
  rusk

IP Addresses

When using a custom configuration file, properties that use IP addresses should be set to 'N/A'. For example, if you want HTTP to be configured:

[http]
listen_address = 'N/A'

This entry should be present in the template configuration file. When the node is starting, the address to be used will be detected and this configuration will be set to listen at port 8080.

Likewise, the kadcast.public_address and kadcast.listen_address properties in the configuration file should be set to 'N/A'. During node startup, they will be detected and set to use port 9000.

License

The Rusk software is licensed under the Mozilla Public License Version 2.0.