​

Contributing to Clementine

​

Getting Started

​

Prerequisites

1. Rust toolchain installed via rustup.rs
2. RISC Zero (version 2.1.0):
   curl -L https://risczero.com/install | bash
   rzup install cargo-risczero 2.1.0
   rzup install r0vm 2.1.0
   rzup install rust 1.88.0
   
3. System dependencies:
   • macOS: Xcode Command Line Tools (xcode-select --install)
   • Ubuntu: sudo apt install build-essential libssl-dev pkg-config
4. Development tools:
   • PostgreSQL (for testing)
   • Bitcoin Core v29.0 or later
   • Git

​

Setting Up Your Development Environment

1. Fork and clone the repository:
   git clone https://github.com/YOUR-USERNAME/clementine.git
   cd clementine
   
2. Set up PostgreSQL for testing:
   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'"
   
3. Set required environment variables:
   export RISC0_DEV_MODE=1
   export RUST_MIN_STACK=33554432
   
4. Generate test certificates:
   ./scripts/generate_certs.sh
   
5. Download BitVM cache (optional but recommended):
   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
   

​

Development Workflow

​

Making Changes

1. Create a new branch for your changes:
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/issue-number-description
   
2. Make your changes following the code style guidelines
3. Write or update tests for your changes
4. Run the test suite to ensure everything passes:
   # Run all tests
   cargo test --all-features
   
   # Or run separately
   cargo test_unit_debug      # Unit tests only
   cargo test_integration     # Integration tests only
   
5. Generate documentation if you’ve changed public APIs:
   cargo doc --no-deps
   

​

Testing Your Changes

​

Unit Tests

# Debug mode (faster compilation)
cargo test_unit_debug

# Release mode (faster execution)
cargo test_unit_release

​

Integration Tests

# Debug mode
cargo test_integration

# Release mode
cargo test_integration_release

​

Writing Tests

1. Add unit tests in the same file as your code or in the appropriate test module
2. Add integration tests in core/src/test/ if testing cross-component functionality
3. Follow existing test patterns - see core/src/test/ for examples
4. Test both success and error cases

​

Code Style

• Format your code with rustfmt:
  cargo fmt
  
• Check for common issues with clippy:
  cargo clippy --all-features
  
• Follow Rust naming conventions:
  • snake_case for functions, variables, and modules
  • PascalCase for types and traits
  • SCREAMING_SNAKE_CASE for constants
• Write clear, descriptive comments:
  • Document public APIs with /// doc comments
  • Explain complex logic with inline comments
  • Reference related issues or RFCs when relevant
• Keep functions focused: Each function should do one thing well
• Handle errors properly: Use Result and propagate errors with ? where appropriate

​

Submitting Changes

​

Pull Request Process

1. Commit your changes with clear, descriptive commit messages:
   git add .
   git commit -m "feat: add support for X"
   # or
   git commit -m "fix: resolve issue with Y (#123)"
   
2. Push to your fork:
   git push origin your-branch-name
   
3. Open a Pull Request on GitHub with:
   • Clear title describing the change
   • Description of what changed and why
   • Linked issues (use “Closes #123” to auto-close issues)
   • Testing details - how you tested the changes
   • Documentation updates - if you changed documented interfaces

​

Pull Request Template

# Description

Describe what this pull request does.

## Linked Issues

- Closes #(issue number)
- Related to #(issue number)

## Testing

Describe how these changes were tested. If you've added new features, 
have you added unit tests?

## Docs

Describe where this code is documented. If it changes a documented 
interface, have the docs been updated?

​

Commit Message Guidelines

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• test: - Adding or updating tests
• refactor: - Code refactoring
• perf: - Performance improvements
• chore: - Maintenance tasks

feat: implement withdrawal timeout mechanism
fix: resolve race condition in musig2 nonce aggregation (#456)
docs: update configuration examples in usage.md
test: add integration tests for deposit flow

​

Code Review Process

​

What to Expect

1. Code owners review: PRs are reviewed by @chainwayxyz/clementine-bdfl
2. CI/CD checks: Automated tests and linting must pass
3. Infrastructure changes: Changes to .github/**, .gitsecret/**, or devops/** require review from @chainwayxyz/ops-bdfl

​

Review Guidelines

• Code quality: Is the code clear, maintainable, and well-structured?
• Tests: Are there sufficient tests? Do they cover edge cases?
• Documentation: Are public APIs documented? Are changes reflected in docs?
• Security: Are there any security implications?
• Performance: Are there any performance concerns?
• Breaking changes: Are breaking changes justified and well-documented?

​

Types of Contributions

​

Bug Reports

1. Search existing issues to avoid duplicates
2. Create a new issue with:
   • Clear, descriptive title
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment details (OS, Rust version, Clementine version)
   • Error messages and logs
   • Minimal reproduction case if possible

​

Feature Requests

1. Check existing issues to see if it’s already proposed
2. Open a discussion or issue describing:
   • The problem you’re trying to solve
   • Your proposed solution
   • Alternative approaches considered
   • Potential impact on existing functionality

​

Documentation Improvements

• Fix typos or clarify confusing sections
• Add examples for common use cases
• Improve API documentation
• Translate documentation (if applicable)

​

Code Contributions

• Bug fixes
• New features
• Performance improvements
• Code refactoring
• Test coverage improvements

​

Security Reporting

1. Email the security team at: security@citrea.xyz
2. Encrypt sensitive reports using the GPG key:
   -----BEGIN PGP PUBLIC KEY BLOCK-----
   
   mQINBGhZQXgBEADs4X61A9OcXJ1vbsFwq/tCm8FVCjHx9KADZ7WRht4Tr/4tlrXP
   [... full key available in SECURITY.md ...]
   
   Full GPG key is available in the SECURITY.md file.
3. Include in your report:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if you have one)
4. Wait for response before public disclosure

​

Helper Scripts

• generate_certs.sh - Generate TLS certificates for testing
• docker/ - Docker and docker-compose configurations
• Various testing and setup scripts

​

Building for Production

# Build with automation features
cargo build --release --features automation

# Binary will be at:
./target/release/clementine-core

• State Manager - Automatic duty fulfillment
• Transaction Sender - Automatic transaction management

​

Resources

• Source Code: github.com/chainwayxyz/clementine
• Issue Tracker: GitHub Issues
• API Docs: chainwayxyz.github.io/clementine/clementine_core
• Whitepaper: citrea.xyz/clementine_whitepaper.pdf
• Discord: discord.gg/citrea

​

Questions?

1. Check the FAQ and Troubleshooting guides
2. Search existing issues
3. Ask in the Citrea Discord
4. Open a GitHub Discussion