# User Flow

### Complete User Journey

This diagram shows the entire user flow from creating a boost request to receiving ckBTC, including all actors and timeframes.

{% @mermaid/diagram content="sequenceDiagram
participant U as User
participant P as ckBoost Protocol
participant B as Booster
participant BN as Bitcoin Network
participant M as ckBTC Minter

```
Note over U,M: Happy Path: Booster Available

%% Phase 1: Request Creation
U->>P: registerBoostRequest(0.01 BTC, 2% max fee)
P->>P: Generate unique subaccount
P->>M: Create Bitcoin address for subaccount
M-->>P: Bitcoin address (bc1q...)
P-->>U: Request created + Bitcoin address

%% Phase 2: Market Discovery
P->>B: Broadcast pending request
B->>B: Evaluate request (profit, risk, liquidity)
B->>P: acceptBoostRequest(requestId)
P->>P: Verify booster balance
P->>U: Transfer ckBTC instantly (0.98 ckBTC)
P-->>U: ✅ ckBTC received!

%% Phase 3: User sends Bitcoin
U->>BN: Send 0.01 BTC to address
BN->>BN: Transaction propagates
Note over BN: ~10-60 minutes for confirmations

%% Phase 4: Bitcoin confirmation & reclamation
BN->>M: Bitcoin confirmations (6/6)
M->>P: Notify of confirmed deposit
B->>P: triggerMintingForBoostReclaim(requestId)
P->>M: update_balance(subaccount)
M->>P: Mint ckBTC from Bitcoin
B->>P: reclaimMintedFunds(requestId)
P->>B: Transfer 0.01 ckBTC + 0.002 fee to booster
P->>P: Mark request as completed

Note over U,M: Fallback Path: No Booster Available 

%% Alternative flow when no booster
U->>P: registerBoostRequest(0.01 BTC, 2% max fee)
P->>P: Generate subaccount + Bitcoin address
P-->>U: Request created, waiting for booster...
Note over P: no booster accepts
U->>P: triggerMintingForMyBoostRequest(requestId)
P->>P: Switch to direct minting mode

U->>BN: Send 0.01 BTC to address
BN->>BN: Transaction confirms
BN->>M: Bitcoin deposit confirmed
M->>P: Notify of deposit
P->>M: update_balance(subaccount)
M->>P: Mint ckBTC from Bitcoin
U->>P: claimMintedCKBTC(requestId)
P->>U: Transfer 0.01 ckBTC directly
P-->>U: ✅ ckBTC received!
```

" %}

### Step-by-Step User Experience

#### Phase 1: Request Creation

**What the user does:**

1. **Decides amount and fee**: User wants to convert 0.01 BTC and is willing to pay up to 2% fee for instant service
2. **Creates boost request**: Calls `registerBoostRequest(1000000, 2.0)` via wallet or dApp
3. **Receives Bitcoin address**: Gets a unique address like `bc1q7x8k2...` where they need to send Bitcoin

**What happens behind the scenes:**

* Protocol generates a unique subaccount for this request
* Bitcoin address is created specifically for this request (fund isolation)
* Request enters `pending` status and becomes visible to boosters
* Unique request ID is assigned for tracking

#### Phase 2: Market Discovery (0-5 minutes)

**Two possible paths from here:**

**Path A: Booster Available (Happy Path)**

**What happens:**

1. **Booster monitoring**: Active boosters continuously scan pending requests
2. **Request evaluation**: Booster evaluates:
   * **Profitability**: X% fee on 0.01 BTC
   * **Risk assessment**: Amount size, user history, current market conditions
   * **Available liquidity**: Does booster have 0.01 ckBTC available?
3. **Instant acceptance**: If profitable and low-risk, booster accepts within seconds
4. **Immediate ckBTC transfer**: User receives 0.98 ckBTC (0.01 BTC minus \~2% fee) instantly

**Path B: No Booster Available (Fallback                                                                                                )**

**What happens:**

1. **Waiting period**: Request sits in `pending` status
2. **User decision**: After some time, user can trigger direct minting
3. **Fallback activation**: User calls `triggerMintingForMyBoostRequest()`
   1. **Direct processing**: Protocol handles minting directly without booster2 wj

#### Phase 3: Bitcoin Transaction (User action required)

**What the user does:**

1. **Send Bitcoin**: User sends exactly 0.01 BTC to the provided address
   * Can use any Bitcoin wallet
   * Must send the exact amount requested
   * Should use appropriate fee for timely confirmation

**What happens behind the scenes:**

* Bitcoin transaction broadcasts to the network
* Transaction appears in mempool (unconfirmed)
* ckBTC minter begins monitoring this specific address
* Protocol tracks the incoming transaction

**Timeline**: Immediate broadcast, 10-60 minutes for confirmations

#### Phase 4A: Instant Liquidity (Booster Path)

**What the user experiences:**

1. **Immediate notification**: "ckBTC received! Transaction complete."
2. **Balance update**: Wallet shows new ckBTC balance
3. **Ready to use**: Can immediately use ckBTC in DeFi, transfers, etc.

**What happens behind the scenes:**

1. **ICRC-1 transfer**: Booster's ckBTC is transferred to user's principal
2. **Booster balance**: Booster's available balance decreases
3. **Status update**: Request status changes to `boosted`
4. **Fee calculation**: User pays agreed fee (e.g., 1.5% actual vs 2% max)

#### Phase 4B: Direct Minting (Fallback Path)

**What the user experiences:**

1. **Minting notification**: "Bitcoin received, minting ckBTC..."
2. **Progress updates**: Regular status updates during minting process
3. **Completion**: "ckBTC minted and transferred!"

**What happens behind the scenes:**

1. **Bitcoin confirmation**: Wait for sufficient Bitcoin confirmations (usually 6)
2. **Minter interaction**: Protocol calls ckBTC minter to convert BTC to ckBTC
3. **Direct transfer**: Minted ckBTC goes directly to user (no booster involved)
4. **No additional fees**: User only pays standard ckBTC minting fees

#### Phase 5: Fund Reclamation (Background - Booster Path Only)

**What happens (user doesn't see this):**

1. **Bitcoin monitoring**: Protocol monitors for Bitcoin deposit confirmation
2. **Minting trigger**: Once Bitcoin arrives, booster can trigger fund reclamation
3. **Two-phase process**:
   * **Phase 1**: Call ckBTC minter to mint ckBTC from deposited Bitcoin
   * **Phase 2**: Transfer minted ckBTC back to booster's pool
4. **Profit realization**: Booster receives original amount + earned fees
5. **Pool replenishment**: Booster's available balance is restored + profit