# Architecture Deep Dive

### System Overview

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

{% @mermaid/diagram content="graph TB
subgraph "Internet Computer"
subgraph "ckBoost Protocol"
A\[Main Canister] --> B\[Ledger Module]
A --> C\[Validation Module]
A --> D\[Booster Account Module]
A --> E\[Minting Operations Module]
A --> F\[Boost Request Module]
A --> G\[State Management]
end

```
    subgraph "External IC Canisters"
        H[ckBTC Ledger]
        I[ckBTC Minter]
    end
end

subgraph "Bitcoin Network"
    J[Bitcoin Addresses]
    K[Bitcoin Transactions]
end

A --> H
A --> I
I --> J
K --> I
```

" %}

### 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

```motoko
// 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

{% @mermaid/diagram content="stateDiagram-v2
\[\*] --> pending : registerBoostRequest()

```
pending --> active : acceptBoostRequest()
pending --> minting : triggerMintingForMyBoostRequest()
pending --> cancelled : User cancels

active --> boosted : ckBTC transferred

boosted --> minting : triggerMintingForBoostReclaim()

minting --> completed : claimMintedFunds() / claimMintedCKBTC()

cancelled --> [*]
completed --> [*]" %}
```

### Security Architecture

#### Trust Boundaries

{% @mermaid/diagram content="graph TB
subgraph "Trusted Zone (ckBoost Canister)"
A\[Main Logic]
B\[State Storage]
C\[Subaccount Management]
end

```
subgraph "External Trust (IC System Canisters)"
    D[ckBTC Ledger]
    E[ckBTC Minter]
end

subgraph "Untrusted Zone"
    F[User Inputs]
    G[Bitcoin Network]
    H[External Calls]
end

F --> A
A --> D
A --> E
G --> E
H --> A" %}
```

#### 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 →


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ckboost.com/ckbtc/architecture-deep-dive.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.