This guide walks you through installing all required dependencies and building Clementine from source.
Install Rust
Install Rust toolchain
Clementine requires Rust version 1.88.0. Install Rust using rustup:curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Verify installation
Verify that Rust is properly installed: Install RISC Zero
Clementine uses RISC Zero version 2.1.0 for zero-knowledge proof generation.
Install RISC Zero toolchain
Run the RISC Zero installation script:curl -L https://risczero.com/install | bash
Install specific RISC Zero versions
Install the required RISC Zero components at version 2.1.0:rzup install cargo-risczero 2.1.0
rzup install r0vm 2.1.0
rzup install rust 1.88.0
Install cargo-risczero
Install the cargo-risczero plugin:cargo install cargo-risczero
Set Up PostgreSQL
Clementine uses PostgreSQL 15 for data persistence.
Run PostgreSQL with Docker
The quickest way to get started is using Docker:docker run --name clementine-test-db \
-e POSTGRES_USER=clementine \
-e POSTGRES_PASSWORD=clementine \
-e POSTGRES_DB=clementine \
-p 5432:5432 \
--restart always \
-d postgres:15 \
bash -c "exec docker-entrypoint.sh postgres -c 'max_connections=1000'"
The database is configured with max_connections=1000 to support multiple concurrent Clementine services.
Alternative: Install PostgreSQL natively
Alternatively, install PostgreSQL 15 or later using your system’s package manager:brew install postgresql@15
brew services start postgresql@15
Build Clementine
Clone the repository
git clone https://github.com/chainwayxyz/clementine.git
cd clementine
Build the project
Build Clementine in release mode:To enable automation features (State Manager and Transaction Sender):cargo build --release --features automation
The automation feature enables automatic fulfillment of verifier/operator/aggregator duties and automatic transaction management.
Verify the build
Check that the binary was created successfully:./target/release/clementine-core --help
Generate TLS Certificates
Clementine uses mutual TLS (mTLS) for secure gRPC communications.
Generate certificates for testing
For development and testing, generate self-signed certificates:./scripts/generate_certs.sh
certs/
├── ca/
│ ├── ca.key
│ └── ca.pem
├── server/
│ ├── server.key
│ └── server.pem
├── client/
│ ├── client.key
│ └── client.pem
└── aggregator/
├── aggregator.key
└── aggregator.pem
For production deployments, use certificates signed by a trusted Certificate Authority (CA) rather than self-signed certificates. Keep private keys (*.key files) secure and never commit them to version control.
Download BitVM Cache (Optional)
To speed up initialization, download pre-generated BitVM cache files:
# For production mode
wget https://static.testnet.citrea.xyz/common/bitvm_cache_v3.bin -O bitvm_cache.bin
export BITVM_CACHE_PATH=/path/to/bitvm_cache.bin
# For development mode (RISC0_DEV_MODE=1)
wget https://static.testnet.citrea.xyz/common/bitvm_cache_dev.bin -O bitvm_cache_dev.bin
export BITVM_CACHE_PATH=/path/to/bitvm_cache_dev.bin
If you don’t download the cache files, they will be generated automatically on first run, which may take some time.
Set Environment Variables
Set the required environment variables:
# Required: Minimum stack size
export RUST_MIN_STACK=33554432
# Optional: Enable development mode for testing
export RISC0_DEV_MODE=1
# Optional: Enable full backtraces for debugging
export RUST_LIB_BACKTRACE=full
Next Steps
Now that Clementine is installed, proceed to Configuration to set up your configuration files and environment.