Architecture Deep Dive

System Overview

ckBoost is designed as a modular, secure, and scalable protocol with clean separation of concerns.

Canister Architecture

Core Modules

1. Main Canister (main.mo)

Purpose: Orchestration layer and public API Responsibilities:

• Expose public functions defined in Candid interface

• Coordinate between modules

• Handle authentication and authorization

• Manage system state

2. State Management (state.mo)

Purpose: Centralized state storage with persistence Responsibilities:

• Store all boost requests

• Store all booster accounts

• Provide atomic updates

• Handle canister upgrades

3. Ledger Operations (ledger.mo)

Purpose: All ICRC-1 token operations Responsibilities:

• Handle ckBTC transfers

• Manage transaction fees

• Account balance queries

• Error handling and logging

4. Validation Module (validation.mo)

Purpose: Input validation and business rules Responsibilities:

• Validate amounts and fees

• Check business logic constraints

• Sanitize inputs

5. Booster Account Management (booster_account.mo)

Purpose: Liquidity provider operations Responsibilities:

• Register new boosters

• Manage deposits and withdrawals

• Track available balances

• Handle pool operations

6. Minting Operations (minting_operations.mo)

Purpose: Complex ckBTC minting workflows Responsibilities:

• Two-phase minting processes

• Cross-canister call management

• Error recovery and retry logic

• Fund reclamation flows

Data Architecture

Type System

// Core types with clear relationships
type BoostRequest = {
  id: Nat;
  owner: Principal;
  amount: Nat;                    // Amount in satoshis
  maxFeePercentage: Float;        // Maximum fee user will pay
  receivedBTC: Nat;               // Actually received Bitcoin
  btcAddress: ?Text;              // Generated Bitcoin address
  subaccount: Blob;               // Isolated subaccount
  status: BoostStatus;            // Current state
  matchedBooster: ?Principal;     // Which booster accepted
  createdAt: Int;                 // Timestamp
  updatedAt: Int;                 // Last modification
};

type BoosterAccount = {
  owner: Principal;
  feePercentage: Float;           // Fee this booster charges
  subaccount: Blob;               // Booster's isolated subaccount
  availableBalance: Nat;          // Available for new boosts
  totalDeposited: Nat;            // Lifetime deposits
  totalWithdrawn: Nat;            // Lifetime withdrawals
  totalBoosted: Nat;              // Volume provided
  totalFeesEarned: Nat;           // Fees earned
  createdAt: Int;
  updatedAt: Int;
};

State Transitions

Security Architecture

Trust Boundaries

Fund Isolation Strategy

Every operation uses isolated subaccounts to prevent fund mixing:

Security Benefits:

• Request funds cannot be mixed with other requests

• Booster funds cannot be mixed with user funds

• Clear audit trail for every satoshi

• Isolated failure domains

---

Next: API Reference →