API Reference

Complete reference for all ckBoost Protocol functions based on the Candid interface.

Type Definitions

Basic Types

Type	Description
BoostId	nat - Unique identifier for boost requests
BoosterPoolId	nat - Unique identifier for booster pools
Subaccount	blob - ICRC-1 subaccount for fund isolation
Amount	nat - Amount in satoshis
Timestamp	int - Unix timestamp in nanoseconds
Fee	float64 - Fee percentage (0.1 to 10.0)

Status Types

type BoostStatus = variant {
  pending;     // Waiting for booster acceptance
  active;      // Booster matched, waiting for Bitcoin
  completed;   // Transaction completed successfully
  cancelled;   // Request cancelled
  boosted;     // ckBTC provided, waiting for reclamation
  minting;     // Minting process in progress
};

Record Types

type BoostRequest = record {
  id: BoostId;
  owner: principal;
  amount: Amount;
  fee: Fee;
  receivedBTC: Amount;
  btcAddress: opt text;
  subaccount: Subaccount;
  status: BoostStatus;
  matchedBoosterPool: opt BoosterPoolId;
  createdAt: Timestamp;
  updatedAt: Timestamp;
};

type BoosterPool = record {
  id: BoosterPoolId;
  owner: principal;
  fee: Fee;
  subaccount: Subaccount;
  availableAmount: Amount;
  totalBoosted: Amount;
  createdAt: Timestamp;
  updatedAt: Timestamp;
};

Result Types

type BoostRequestResult = variant { ok: BoostRequest; err: text };
type BoosterPoolResult = variant { ok: BoosterPool; err: text };
type TextResult = variant { ok: text; err: text };

Helper Functions

Utility functions for conversions and system information.

Function	Parameters	Returns	Description
ckBTCToSatoshis	float64	nat	Converts ckBTC amount to satoshis
satoshisToCkBTC	nat	float64	Converts satoshis to ckBTC amount
getCanisterPrincipal	none	text (query)	Gets the canister's principal ID
getDirectBTCAddress	none	text	Gets the main Bitcoin address

System Functions

Function	Parameters	Returns	Description
greet	text	text (query)	Basic greeting function
whoami	none	text	Returns caller's principal

Boost Request Operations

Functions for creating, managing, and querying boost requests.

Request Lifecycle

Function	Parameters	Returns	Purpose
registerBoostRequest	Amount, Fee	BoostRequestResult	Create new boost request
updateReceivedBTC	BoostId, Amount	BoostRequestResult	Update Bitcoin deposit amount
getBoostRequestBTCAddress	BoostId	TextResult	Get Bitcoin address for request
checkBTCDeposit	BoostId	BoostRequestResult	Check and update Bitcoin deposits

Request Queries

Function	Parameters	Returns	Purpose
getBoostRequest	BoostId	opt BoostRequest (query)	Get specific request by ID
getUserBoostRequests	principal	vec BoostRequest (query)	Get all requests for user
getAllBoostRequests	none	vec BoostRequest (query)	Get all requests in system

Function Details

registerBoostRequest(Amount, Fee) -> BoostRequestResult

Creates a new boost request for instant ckBTC conversion.

• Amount: Satoshis to convert (minimum: 10,000)

• Fee: Maximum fee percentage (0.1 - 10.0)

• Errors: Invalid amount, invalid fee, address generation failure

updateReceivedBTC(BoostId, Amount) -> BoostRequestResult

Updates the Bitcoin amount received for a request.

• BoostId: Target request identifier

• Amount: Bitcoin amount received in satoshis

• Errors: Request not found, invalid status, invalid amount

getBoostRequestBTCAddress(BoostId) -> TextResult

Retrieves the unique Bitcoin address for a boost request.

• BoostId: Target request identifier

• Returns: Bitcoin address string

• Errors: Request not found, address not generated

checkBTCDeposit(BoostId) -> BoostRequestResult

Monitors and updates Bitcoin deposits for a request.

• BoostId: Target request identifier

• Returns: Updated request with current Bitcoin balance

• Errors: Request not found, monitoring failure

Booster Pool Operations

Functions for liquidity providers to manage their capital pools.

Pool Management

Function	Parameters	Returns	Purpose
registerBoosterPool	Fee	BoosterPoolResult	Create new booster pool

Pool Queries

Function	Parameters	Returns	Purpose
getBoosterPool	BoosterPoolId	opt BoosterPool (query)	Get specific pool by ID
getUserBoosterPools	principal	vec BoosterPool (query)	Get all pools for user
getAllBoosterPools	none	vec BoosterPool (query)	Get all pools in system

Function Details

registerBoosterPool(Fee) -> BoosterPoolResult

Creates a new liquidity pool for providing instant ckBTC.

• Fee: Fee percentage charged (0.1 - 10.0)

• Errors: User already has pool, invalid fee percentage

Advanced Operations

Core protocol operations for boosters and users.

Booster Operations

Function	Parameters	Returns	Purpose
acceptBoostRequest	BoostId	text	Accept a pending boost request
registerBoosterAccount	Fee	BoosterAccountResult	Create booster account
updateBoosterDeposit	principal, Amount	BoosterAccountResult	Add liquidity to account
withdrawBoosterFunds	Amount	text	Remove liquidity from account
triggerMintingForBoostReclaim	BoostId	text	Start fund reclamation process
reclaimMintedFunds	BoostId	text	Complete fund reclamation

User Fallback Operations

Function	Parameters	Returns	Purpose
triggerMintingForMyBoostRequest	BoostId	text	Start direct minting (no booster)
claimMintedCKBTC	BoostId	text	Complete direct minting

Additional Query Functions

Function	Parameters	Returns	Purpose
getBoosterAccount	principal	opt BoosterAccount (query)	Get booster account by principal
getAllBoosterAccounts	none	vec BoosterAccount (query)	Get all booster accounts
getPendingBoostRequests	none	vec BoostRequest (query)	Get all pending requests
getBoostedRequests	none	vec BoostRequest (query)	Get all boosted requests
getMintingRequests	none	vec BoostRequest (query)	Get all minting requests