Clementine CLI

A wallet-agnostic command-line tool for depositing 10 BTC from Bitcoin to Citrea and withdrawing 10 cBTC from Citrea to Bitcoin.

For more information about the Clementine bridge, visit https://docs.citrea.xyz/essentials/clementine-trust-minimized-bitcoin-bridge.

If you are looking for bridging smaller amounts, you can use third party bridges, visit https://citrea.xyz/bridge for more information.

If you encounter any issues, email us at clementine-cli@citrea.xyz.

Installation

Choose one of the following installation paths.

Option A: Build from source

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install Clementine CLI:

cargo install --git https://github.com/chainwayxyz/clementine-cli --tag v0.1.0 --locked --force

Option B: Download a pre-built binary and verify it

• Download & Verify

Initialize and configure

Install the default configuration by running the CLI init command which creates the ~/.clementine/bridge_cli_config.toml file for you:

clementine-cli init

Show configuration:

clementine-cli show-config

Show help:

clementine-cli --help

Quick Usage

By default, clementine-cli uses bitcoin (mainnet) network. If you wish to make deposits and withdrawals on testnet, please provide --network testnet flag every time you invoke clementine-cli. Throughout the docs, network aliases are used interchangeably: bitcoin/mainnet, testnet4/testnet, signet/devnet, and regtest.

Deposit

# Create wallet for deposit (Recovery Taproot Address)
clementine-cli wallet create my-deposit-wallet deposit

# Start deposit (generate deposit address)
clementine-cli deposit start <RECOVERY_TAPROOT_ADDRESS> <CITREA_ADDRESS>

# Send 10 BTC to the shown address as prompted by the start command

# Monitor deposits
clementine-cli deposit status <DEPOSIT_ADDRESS>

Withdrawal

# Create wallet for withdrawal (Withdrawal Signer Address)
clementine-cli wallet create my-withdrawal-wallet withdrawal

# Start withdrawal (Generate Withdrawal Address)
clementine-cli withdraw start <WITHDRAWAL_TAPROOT_ADDRESS> <DESTINATION_ADDRESS>

# Send 330 sats to the shown address as prompted by the start command
# Then run withdrawal scan command to find available withdrawal UTXOs
clementine-cli withdraw scan <WITHDRAWAL_TAPROOT_ADDRESS> <DESTINATION_ADDRESS>

# Run the prompted commands to generate withdrawal signatures and send withdrawal request to Citrea for optimistic withdrawal

# Monitor withdrawals
clementine-cli withdraw status <WITHDRAWAL_ADDRESS>

Two-Device Security

We suggest using Clementine CLI with two devices for maximum security:

• Airgapped device:
  All wallet creation, key generation, and signing operations
     clementine-cli wallet create
   clementine-cli deposit create-signed-recovery-tx
   clementine-cli withdraw generate-withdrawal-signatures

• Online device:
  Status monitoring, address generation, broadcasting

Documentation

See docs/README.md for an overview of how to use this CLI to deposit to and withdraw from Citrea.

• Download & Verify - Download pre-built binaries and verify signatures
• Wallet Guide - Wallet operations
• Deposit Guide - Deposit Bitcoin to Citrea
• Withdrawal Guide - Withdrawal from Citrea to Bitcoin
• Advanced Usage - Advanced users only: signet/regtest config, API/RPC selection, hidden CLI commands