https://github.com/dusk-network/rusk
The reference Dusk platform implementation and tools
https://github.com/dusk-network/rusk
Last synced: 2 days ago
JSON representation
The reference Dusk platform implementation and tools
- Host: GitHub
- URL: https://github.com/dusk-network/rusk
- Owner: dusk-network
- License: mpl-2.0
- Created: 2020-02-10T13:24:17.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2025-04-13T23:50:10.000Z (2 days ago)
- Last Synced: 2025-04-14T00:36:43.307Z (2 days ago)
- Language: Rust
- Homepage:
- Size: 46.7 MB
- Stars: 193
- Watchers: 18
- Forks: 65
- Open Issues: 312
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-rust - dusk-network/rusk - Reference implementation of Dusk, a privacy-focused, scalable FMI for real-world assets (RWA) and compliant financial applications. [](https://github.com/dusk-network/rusk/actions/workflows/rusk_ci.yml) (Applications / Blockchain)
- awesome-rust - dusk-network/rusk - Reference implementation of Dusk, a privacy-focused, scalable FMI for real-world assets (RWA) and compliant financial applications. [](https://github.com/dusk-network/rusk/actions/workflows/rusk_ci.yml) (Applications / Blockchain)
README
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](https://docs.dusk.network/operator/overview/)
# 📃 Table of Contents
- [Prerequisites](#prerequisites)
- [Setup script](#setup-script)
- [Rust Installation](#rust-installation)
- [Build and Tests](#️-build-and-tests)
- [Run a local node for development](#-run-a-local-node-for-development)
- [Spin up local node](#spin-up-local-node)
- [Prepare modules](#prepare-modules)
- [Run a node](#run-a-node)
- [Run an archive node](#run-an-archive-node)
- [Run a prover node](#run-a-prover-node)
- [Contracts compilation](#-contracts-compilation)
- [Docker support](#-docker-support)
## 📝 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
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:
```bash
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:
```bash
make
```
To run tests:
```bash
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:
```bash
# Generate the keys used by the circuits
# Compile all the genesis contracts
# Copy example consensus.keys
make prepare-dev
```
#### Run a Node
```bash
# Launch a local ephemeral node
make run-dev
```
#### Run an Archive node
```bash
make run-dev-archive
```
#### Run a Prover Node
The node can be build as a prover only as follows:
```bash
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](https://github.com/dusk-network/rusk/tree/master/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:
```bash
make contracts
```
Compile a specific genesis contract:
```bash
# 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:
```bash
docker build -f Dockerfile.ephemeral -t rusk .
```
To build the Docker image **without** archive:
```bash
docker build -t -f Dockerfile.ephemeral rusk --build-arg CARGO_FEATURES="" .
```
To run Rusk inside a Docker container:
```bash
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
```bash
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:
```bash
docker run -it \
-v /path/to/consensus.keys:/opt/dusk/conf/consensus.keys \
-v /path/to/rusk/profile:/opt/dusk/rusk \
-e NETWORK= \
-e DUSK_CONSENSUS_KEYS_PASS= \
-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`.
```bash
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= \
-e DUSK_CONSENSUS_KEYS_PASS= \
-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:
```toml
[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](./LICENSE).