Crate clementine_core

Source
Expand description

§Clementine 🍊

Clementine is Citrea’s BitVM-based, trust-minimized two-way peg program. Please refer to the whitepaper to understand the design of Clementine.

Clementine Core is the backbone of Clementine. As the name suggests, it provides the core functionalities for Clementine to operate.

Most of the modules are self-explanatory and documented. Please refer to the documentation of each module for more information.

§Binaries and Using Clementine

Clementine’s architecture is designed so that every actor is a separate server. They all communicate with each other via gRPC.

For this reason, Clementine Core provides a single main binary, clementine-core, which acts as a server starter for every actor. There is also a helper binary, clementine-core-cli, which is a command-line interface for communicating with these servers. It is located in bin/cli.rs.

The crate::cli module provides the command-line interface for Clementine. It is used in every binary.

The crate::config module is also essential for Clementine to operate. It specifies essential variables for the protocol as well as the user’s environment setup.

§Utilizing Actors

The core behavior of Clementine’s actors is defined in the respective modules:

For all these modules, the crate::actor module provides common utilities.

§Servers

An actor is only meaningful if its server is running. For each actor, there is a server module, which provides the server implementation.

The main server architecture is defined in the rpc/clementine.proto file. It is compiled to Rust code by the tonic library. Server logic for each actor is defined in the respective server module in the crate::rpc module.

§Building Transactions and Managing Flow with Tasks

Clementine operates on Bitcoin transactions. The crate::builder module provides utilities for building Bitcoin transactions based on the specification (detailed in the whitepaper). The crate::builder module can create a transaction according to the specification with the required signatures, addresses, and scripts.

Clementine requires a few background tasks to be running in order to operate properly. The task interface is defined in the crate::task module. These tasks are:

  • The crate::bitcoin_syncer module syncs Bitcoin blocks and transactions.
  • The crate::tx_sender module sends transactions to the Bitcoin network depending on the transaction type.
  • The crate::states module provides state machine implementations for managing some of the steps in the specification.

There are other modules that are not tasks, but they are used in the tasks and are important for the flow of Clementine:

§Communicating with the Outside

Some steps require communicating with external systems:

  • The [crate::extended_rpc] module provides a client that talks with the Bitcoin node.
  • The crate::citrea module provides a client for interacting with Citrea.
  • The crate::bitvm_client module provides a client for BitVM.
  • The crate::database module provides a database interface for interacting with the PostgreSQL database.

§Development Guidelines

§Error Handling

There are rules about error handling in Clementine. Please refer to the crate::errors module for more information.

§Testing Clementine

There are a few quirks about testing Clementine. One of the main ones is that there is no tests directory for integration tests. Rather, there is a [crate::test] module, which is compiled only if test is enabled by Cargo (when running cargo test). That module provides common utilities for unit and integration testing, as well as integration tests themselves. This is a workaround for having common test utilities between unit and integration tests.

Please refer to the [crate::test] module to check what utilities are available for testing and how to use them.

Also, if a new integration test file is added, it should be guarded by the #[cfg(feature = "integration-tests")] attribute. This ensures that the integration and unit tests can be run separately.

Modules§

actor
aggregator
bitcoin_syncer
Bitcoin Syncer
bitvm_client
builder
Bitcoin Transaction Builder for Clementine Bridge
citrea
Citrea Related Utilities
cli
Command Line Interface
compatibility
Compatibility Module
config
Configuration Options
constants
database
Database Operations
deposit
This module defines the data structures related to Citrea deposits in the Clementine bridge.
encryption
errors
Errors
extended_bitcoin_rpc
Bitcoin Extended RPC Interface
header_chain_prover
Header Chain Prover
metrics
This module includes helper functions to get the blockchain synchronization status of the entity. The entity tracks on-chain transactions for many purposes (TxSender, FinalizedBlockFetcher, HCP) and takes action (header chain proving, payout, disprove, L2 state sync, etc.) SyncStatus tracks the latest processed block heights for each of these tasks.
musig2
MuSig2
operator
rpc
servers
Servers
states
State manager module
task
tx_sender
Transaction Sender
utils
verifier

Macros§

execute_query_with_tx
Executes a query with a transaction if it is provided.
fetch_next_message_from_stream
Fetches the next message from a stream which is unwrapped and encapsulated by a Result.
fetch_next_optional_message_from_stream
Fetches next message from a stream.
impl_try_from_vec_u8 🔒

Structs§

ByteArray32
ByteArray64
ByteArray66
EVMAddress
Type alias for EVM address
UTXO

Type Aliases§

ConnectorUTXOTree
InscriptionTxs