Manual Build and Deployment

Prerequisites

Before compiling Clementine, ensure you have the following installed:

Install Rust

Install Rust using rustup: rustup.rs

Install RiscZero

Install RiscZero (v2.1.0): dev.risczero.com/api/zkvm/install

curl -L https://risczero.com/install | bash
rzup install cargo-risczero 2.1.0 # Or v2.1.0
rzup install r0vm 2.1.0
rzup install rust 1.88.0

Platform-Specific Dependencies

macOS
Ubuntu/Debian

Install XCode and its app from AppStore (if xcrun metal gives an error):

xcode-select --install

Install required system packages:

sudo apt install build-essential libssl-dev pkg-config

Runtime Prerequisites

Before running Clementine, you need to set up the following services:

Install Bitcoin Core

Install and configure a Bitcoin node (at least v29.0)

Set up PostgreSQL

Install and configure PostgreSQL. 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'"

Install RISC Zero toolchain

Install the cargo-risczero tool:

cargo install cargo-risczero

Generate TLS certificates (Optional)

TLS certificates are required to start and connect to a Clementine server. For tests, these are automatically generated if not present.

./scripts/generate_certs.sh

For production use, you should use certificates signed by a trusted CA rather than self-signed ones. See the RPC Authentication section for more details.

Set environment variables

Set required environment variables:

# Enable development mode for testing
export RISC0_DEV_MODE=1

# Set minimum stack size
export RUST_MIN_STACK=33554432

Download BitVM cache (Optional)

Download pre-generated BitVM cache. If not downloaded, it will be generated automatically:

wget https://static.testnet.citrea.xyz/common/bitvm_cache_v3.bin -O bitvm_cache.bin
wget https://static.testnet.citrea.xyz/common/bitvm_cache_dev.bin -O bitvm_cache_dev.bin

# If RISC0_DEV_MODE is not set
export BITVM_CACHE_PATH=/path/to/bitvm_cache.bin

# If RISC0_DEV_MODE is set
export BITVM_CACHE_PATH=/path/to/bitvm_cache_dev.bin

Building Clementine

Standard Build

Build Clementine without automation features:

cargo build --release

Build with Automation

Clementine can be configured to enable automation at build-time via the automation feature. The automation feature enables the State Manager and Transaction Sender which automatically fulfills the duties of verifier/operator/aggregator entities:

cargo build --release --features automation

The compiled binary will be located at ./target/release/clementine-core.

Running Clementine Services

Clementine provides a single binary that can act as 3 different services:

Verifier (sometimes called signer)
Operator
Aggregator

These services communicate via gRPC and use a PostgreSQL database. They can be configured to share the same database.

Using Configuration Files

Prepare configuration files

Running the binary requires a configuration file. An example configuration file is located at core/src/test/data/bridge_config.toml. Copy and modify it for your deployment:

cp core/src/test/data/bridge_config.toml /path/to/your/config.toml

Optionally, prepare a protocol parameters file for protocol-specific settings.

Run a service

Verifier
Operator
Aggregator

./target/release/clementine-core verifier --config /path/to/config.toml

./target/release/clementine-core operator --config /path/to/config.toml

./target/release/clementine-core aggregator --config /path/to/config.toml

Add protocol parameters (Optional)

Run with both configuration and protocol parameter files:

./target/release/clementine-core verifier \
  --config /path/to/config.toml \
  --protocol-params /path/to/params.toml

Using Environment Variables

It is also possible to use environment variables instead of configuration files. See the .env.example file for reference.

Set configuration source

Enable environment-based configuration:

export READ_CONFIG_FROM_ENV=1
export READ_PARAMSET_FROM_ENV=1

Run with environment variables

READ_CONFIG_FROM_ENV=1 READ_PARAMSET_FROM_ENV=1 \
  ./target/release/clementine-core verifier

Mixed Configuration

You can mix configuration approaches - for example, reading main configuration from a file but protocol parameters from environment variables:

READ_CONFIG_FROM_ENV=0 READ_PARAMSET_FROM_ENV=1 \
  ./target/release/clementine-core verifier --config /path/to/config.toml

Command-Line Options

Verbose Logging

Specify log level with the --verbose flag (0-5, where 5 logs everything):

./target/release/clementine-core operator \
  --config /path/to/config.toml \
  --verbose 5

Enable Full Backtraces

Set RUST_LIB_BACKTRACE to full to enable full backtraces for errors:

RUST_LIB_BACKTRACE=full \
  ./target/release/clementine-core operator \
  --config /path/to/config.toml

Available Commands

The Clementine binary supports the following commands:

verifier - Run the verifier service
operator - Run the operator service
aggregator - Run the aggregator service
test-actor - Run the test actor (for health checks)
generate-bitvm-cache - Generate BitVM cache files

View all available options:

./target/release/clementine-core --help

Generating BitVM Cache

You can pre-generate BitVM cache files to avoid generation during runtime:

./target/release/clementine-core generate-bitvm-cache

This command generates the BitVM cache files required for circuit verification. The cache files can be quite large and generation may take significant time depending on your hardware.

RPC Authentication

Clementine uses mutual TLS (mTLS) to secure gRPC communications between entities and to authenticate clients.

Certificate Setup

Before running the servers, generate certificates:

# Run from the project root
./scripts/generate_certs.sh

This creates certificates in the following structure:

certs/
├── ca/
│   ├── ca.key     # CA private key
│   └── ca.pem     # CA certificate
├── server/
│   ├── ca.pem     # Copy of CA certificate (for convenience)
│   ├── server.key # Server private key
│   └── server.pem # Server certificate
├── client/
│   ├── ca.pem     # Copy of CA certificate (for convenience)
│   ├── client.key # Client private key
│   └── client.pem # Client certificate
└── aggregator/
    ├── ca.pem     # Copy of CA certificate (for convenience)
    ├── aggregator.key # Aggregator private key
    └── aggregator.pem # Aggregator certificate

Certificate Verification

Client certificates are verified and filtered by the verifier/operator to ensure that:

Verifier/Operator methods can only be called by the aggregator (using aggregator’s client certificate aggregator_cert_path)
Internal methods can only be called by the entity’s own client certificate (using the entity’s client certificate client_cert_path)

The aggregator does not enforce client certificates but does use TLS for encryption.

For production use, you should use certificates signed by a trusted CA rather than self-signed ones.

Deployment Entities

Typical deployment entities are:

Operator Entity

Runs both an operator and a verifier service

Verifier Entity

Runs a verifier service

Aggregator Entity

Runs both an aggregator and a verifier service

All services run by a single entity should ideally share the same database.

Running Tests

To run all tests:

cargo test --all-features

Run unit and integration tests separately:

cargo test_unit
cargo test_integration

Security Considerations

Keep private keys (*.key) secure and don’t commit them to version control
In production, use properly signed certificates from a trusted CA
Rotate certificates regularly
Consider using distinct client certificates for different clients/services

Overview

Getting Started

Deployment

Actors

Operations

Circuits

Manual Build and Deployment

Prerequisites

Install Rust

Install RiscZero

Platform-Specific Dependencies

Runtime Prerequisites

Building Clementine

Standard Build

Build with Automation

Running Clementine Services

Using Configuration Files

Using Environment Variables

Mixed Configuration

Command-Line Options

Verbose Logging

Enable Full Backtraces

Available Commands

Generating BitVM Cache

RPC Authentication

Certificate Setup

Certificate Verification

Deployment Entities

Operator Entity

Verifier Entity

Aggregator Entity

Running Tests

Security Considerations

Build docs developers (and LLMs) love

Overview

Getting Started

Deployment

Actors

Operations

Circuits

​Prerequisites

​Install Rust

​Install RiscZero

​Platform-Specific Dependencies

​Runtime Prerequisites

​Building Clementine

​Standard Build

​Build with Automation

​Running Clementine Services

​Using Configuration Files

​Using Environment Variables

​Mixed Configuration

​Command-Line Options

​Verbose Logging

​Enable Full Backtraces

​Available Commands

​Generating BitVM Cache

​RPC Authentication

​Certificate Setup

​Certificate Verification

​Deployment Entities

​Operator Entity

​Verifier Entity

​Aggregator Entity

​Running Tests

​Security Considerations

Build docs developers (and LLMs) love

Prerequisites

Install Rust

Install RiscZero

Platform-Specific Dependencies

Runtime Prerequisites

Building Clementine

Standard Build

Build with Automation

Running Clementine Services

Using Configuration Files

Using Environment Variables

Mixed Configuration

Command-Line Options

Verbose Logging

Enable Full Backtraces

Available Commands

Generating BitVM Cache

RPC Authentication

Certificate Setup

Certificate Verification

Deployment Entities

Operator Entity

Verifier Entity

Aggregator Entity

Running Tests

Security Considerations