Developer Manual

Step 1. Installation

Install SDK

npm install @hellobtu/sdk
# or
yarn add @hellobtu/sdk

Prerequisites

Download the required WASM file:

• Get secp256k1.wasm

• Place it in your project's public/ directory

Network Support

The SDK supports testnet:

• Use 'bitcoin_testnet' for testnet operations

Step 2. Registration

Check User's Status

import { getProInfo } from '@hellobtu/sdk'

// Check if a Bitcoin address is PRO
const info = await getProInfo('bitcoin_testnet', 'tb1q...')
console.log(info)

Returns:
 {
   feeAddress: string,
   fee: number,
   committee: string,
   consumer: string,
   isPro: 'none' | 'processing' | 'completed'
 }

Upgrade to PRO

Note: You must first send the required fee to the feeAddress before calling this function.

import { upgradeToPro } from '@hellobtu/sdk'

// Upgrade a Bitcoin address to PRO status
const result = await upgradeToPro('bitcoin_testnet', 'tb1q...')

Step 3. Stake Bitcoin

import { stakeBitcoin } from '@hellobtu/sdk'

// Configure staking parameters
const stakeProps = {
  // Your Bitcoin address
  address: 'tb1q...', 
  
  // Your Bitcoin public key
  pubkey: '02...', 
  
  // Committee address to stake to
  committee: 'tb1q...', 
  
  // Amount to stake (in satoshis)
  amount: '1000000',
  
  // Transaction fee rate (in sat/vB)
  feeRate: 5,
  
  // Destination chain ID (e.g., 11155111 for Sepolia testnet)
  chainId: 11155111,
  
  // Recipient address on the destination chain
  recipient: '0x...',
  
  // Your wallet provider (must implement signPsbt)
  signer: walletProvider
}

// Execute staking transaction
const txHash = await stakeBitcoin('bitcoin_testnet', stakeProps)
console.log('Staking Transaction Hash:', txHash)

Step 4. Call Contract

Custody ABI (For User Channel)

Unstake

To proceed, you must identify the consumer contract linked to the particular user channel (each channel is uniquely paired with a consumer contract). Subsequently, call the withdraw method function of the contract.

The location of the consumer contract

function withdraw(
        uint256 amount,
        bytes calldata recipient,
        address refundAddress
    ) external payable override whenNotPaused(PausedType.Withdraw) nonReentrant 

Release

Release the BTC assets which locked in the user channel to the escape channel.

function release(
        uint256 amount,
        bytes calldata releaseAddress
    ) external whenNotPaused(PausedType.Withdraw) nonReentrant 

Get Channel Fee

function getTotalWithdrawFee(
        uint256 amount,
        bytes calldata recipient
    ) public view override returns (uint256 bridgeFee_, uint256 withdrawFee_)

Get BTCC Contract

function getTokenAddress() public view returns (address) 

BTCC ABI

Contract address：

0x12aEa1Ae7cCb3d452753ea4E441d0656c559bFAB

Borrow (BTCC → BTU)

// Function
function deposit(uint256 _amount, uint256 _time) public onlyWhenLive

// Parameters
_amount: The quantity of BTU you require to borrow.
_time: The duration for which you need to borrow BTU, measured in seconds.

// Exmaple
deposit(100000,3600)

A borrowing order can only exist for an address if it has not been liquidated or fully repaid. Multiple borrowing orders per address are not allowed.

Increase Collateral (BTCC)

// Function
function inc(address _usr, uint256 _amount) public onlyWhenLive

// Parameters
_user: The user address involved in increasing their BTCC position.
_amount: The amount of BTCC collateral that the user adds.

// Exmaple
inc(0x2da..,100000)

Redeem (BTCC → BTC)

Withdraw BTC asset by using the escape channel.

// Function
function withdraw(uint256 _amount, bytes memory btc_address) public onlyWhenLive

// Parameters
_amount: User's Bitcoin withdrawal amount
btc_address: User's Bitcoin wallet address

// Exmaple
withdraw(10000,tp1p.....)

BTU ABI

Contract address：

0x564Af3A5e10D978aE67806fca6640068B7d8D62c

Repay / Prepay (BTU → BTCC)

// Function
function withdraw(uint256 _amount) public onlyWhenLive

// Parameters
_amount: The quantity of BTU you require to repay/prepay.

// Exmaple
withdraw（100000）

Liquidate (BTU → BTCC)

// Function
function liquidate(address _liqAddress) public onlyWhenLive

// Parameters
_liqAddress: The target user address for liquidation.

// Exmaple
liquidate(0x1100....)

Oracle ABI

Contract address：

0x4B5c5fDB82bB51F21355e397DC93f9D71467314E

Update Currency

The system necessitates a real-time oracle service that can automatically fetch and update the latest BTC/USDT price data. This data will be used for calculating margin requirements, executing trades and etc.

// Function
function update(uint256 price_, uint32 time_) external onlyOracle

// Parameters
price_: The BTC/USDT market prices with four decimal places of precision.
time_: The timestamp when the price updates.

// Exmaple
update(52000000,1735362497)

StableVault ABI

Contract address：

0x162814596955dcDDa77498c218695f2581ecD93b

Get Bill Records

function getliqRecord(
        uint256 begin,
        uint256 end
    ) external view returns (uint256 length, Record[] memory recordList)
    
return：
// Number
length
// List
Record {
        address borrower;
        address payer;
        uint256 startTime;
        uint256 endTime;
        uint256 terminal;
        uint256 interest_rate;
        Status status;
        uint256 btcc_amount;
        uint256 btu_amount;
        uint256 initial_btu_amount;
        uint256 interest;
        uint256 fee;
    }
enum Status {
        Null,
        Activated,
        Completed,
        Devalued,
        Expired
    }

Get Liquidation Index

function getRecordLiquidationHistoryIndex(
        address addr_
    ) public view returns (uint256[] memory)

return：
The index array of the liquidation records

Important: 
the index should be used as (index_ - 1) as a funtion parameter.

Get Bill Detail

function getRecord(uint256 index_) public view returns (Record memory) 

return： 
// Record detail
Record {
        address borrower;
        address payer;
        uint256 startTime;
        uint256 endTime;
        uint256 terminal;
        uint256 interest_rate;
        Status status;
        uint256 btcc_amount;
        uint256 btu_amount;
        uint256 initial_btu_amount;
        uint256 interest;
        uint256 fee;
    }

Get Debt Detail

function getDebt(address addr_) public view returns (uint256, uint256)

return： 
The collateralized amount of BTCC and the outstanding BTU debt

Get All Index

function getRecordHistoryIndex(
        address addr_
    ) public view returns (uint256[] memory)

return： 
The index array of all the records

Important: 
the index should be used as (index_ - 1) as a funtion parameter.

Get Bill Index

function getRecordIndex(address addr_) public view returns (uint256) 

return： 
The index of the current record

Important: 
the index should be used as (index_ - 1) as a funtion parameter.

Get Currency

function getPrice() public view returns (uint256)

return： 
The market price of the BTC/USDT token pair

Get LTV Rate

function getCurLtvRate(address addr_) public view returns (uint256)

return： 
Loan-to-value Ratio

Get All Rates

function getAllRate()
        public
        view
        returns (uint256 ltv_rate_, uint256 liq_rate_, uint256 interest_rate_)
        
return：
Loan-to-value Ratio(LTV), Liquidation Margin Ratio(LR), Annual Interest Rate(IR)

Get Service Fee

function getFee() public view returns (uint256)

return： 
The fixed service fee (default: 1 BTU)

Liquidation ABI

Get Rewards Rate

function getRewardsRate() external view returns (uint256) {
        return rewardsRate;
    }

return：
The incentive rate paid to liquidators (default: 0.2%)

Get LMR

function getLiquidationRate() external view returns (uint256) {
        return liquidationRate;
    }
    
return：
Liquidation Margin Ratio (default: 120%)

Get Delay Period

function getBufferPeriod() external view returns (uint256) {
        return buffer_period;
    }

return：
The delay period for past-due debts (default: 7 days)

Case study

Case 1. Borrowing BTU with BTCC

Before borrowing BTU, you should prepare all the borrowing information like rates and the currency.

// Get the rate information
- stableVaulte.getAllRate()
The collateralization rate returns 15000 indicates 150%.
The interest rate returns 200 indicates 2%.

// Get the currency of BTCC/USDT
- stableVaulte.getPrice()
The price returns 90000000000, means 1 BTCC = 90,000 BTU

// Get the service fee
- stableVaulte.getFee()
The fee returns 10000, means 1 BTU.

// Initiate the process of borrowing
- BTCC.deposit(uint256 _amount, uint256 _time)

// Example
Using 1.5 BTCC as collateral to borrow BTU for 1 year
You should input (1.5 * 1e18, 3600*24*365) into the following function:
BTCC.deposit(1500000000000000000,31536000)

The user will receive 1.5 / 150% * 90000 = 90000 BTU as the principal of the borrowing.
And the interest fee is 90000 * 2% * 31536000 / 31536000 = 1,800 BTU.

Meanwhile, the fixed service fee is 1 BTU.

So the user needs to prepare a total of 90,000 + 1,800 + 1 = 91,801 BTU as the repayment.

Here are two ways to get detailed bill record information:

// Get the deposit and debt of a bill
- stableVault.getDebt(address addr_)
// Get more details of a bill by its index
- stableVault.getRecord(uint256 index_)

The index can be obtained through:

// Get the historical bill index list
- stableVault.getRecordHistoryIndex(address addr_)
// Get the current order index
- stableVault.getRecordIndex(address addr_)

Important: 
the index should be used as (index_ - 1) as a funtion parameter.

Case 2. Add More Collateral

You can increase BTCC to your own address or others' address.

- BTCC.inc(address _usr, uint256 _amount)

// Add 0.4 BTCC to a debt address
BTCC.inc(0xa.., 400000000000000000)

Case 3. Repay Your Loan with BTU

// Before the deadline, users can make partial repayments
The current debt has a deposit of 1.9 BTCC and an outstanding balance of 91,801 BTU.
Assuming the user repays 35,801 BTU, at the current price of 1 BTCC = 84,000 BTU,
the repayment can be executed by calling BTU.withdraw(35801000000000000000000).

After the repayment, the outstanding balance of the bill will be 56,000 BTU. 
The system only needs to retain 56,000 * 150% / 84,000 == 1 BTCC to maintain a healthy state.
Finally, 1.9 - 1 = 0.9 BTCC will be returned to the user.

// For full repayment, all BTCC will be returned to the user
This can be done by calling BTU.withdraw(90000000000000000000000).
An event, emit Repay(user_, btu_amount_), will be triggered to indicate the repayment (user address, repaid amount).

// The calculation formula of Repayment
((BBTC - BBTC') * Price) / (BTU - BTU') = 150%

BBTC: Initial collateral amount
BBTC': Returned collateral amount after repayment
BTU: Total debt amount
BTU': Current repayment amount

Case 4. Liquidate others' Debts

Process:

A liquidator repays the BTU owed by the borrower and receives the corresponding amount of BTCC based on the current market price. If there are any remaining BTCC, it will be returned to the borrower.

Example:

User A has collateralized 15 BTCC with a current price of 1 BTCC = 100 BTU. As the collateralization rate is 150%, user A can borrow 1000 BTU.

The system price is a delayed price. When the price drops to 1 BTCC = 80 BTU, the account is facing liquidation. At this time, user B liquidates the debt owed by user A with 1000 BTU.

According to the current market price, 1000 BTU is equivalent to 12.5 BTCC. The reward rate is 0.2%. So user B receives 12.5 BTCC as the liquidation principal and 0.025 BTCC (12.5 BTCC * 0.2%) as the liquidation reward.

The remaining 15 - 12.5 - 0.025 = 2.475 BTCC is returned to user A.

Profit:

• Liquidation Reward: The liquidator receives 0.025 BTCC as the liquidation reward from the borrower.

• Market Arbitrage: When the market price goes up to 1 BTCC = 85 BTU, user B can choose to sell BTCC to cash.

Profit calculation: (12.5 + 0.025) * 85 - 1000 = 64.625 BTU

Assuming a price drop causes the bill to become insolvent, or if the bill is overdue, liquidation can be initiated.

After an order times out, there will be a delay period. Liquidation can only occur after the delay period has passed. 

// To get the Delay period
- stableVault.getBufferPeriod()

// To check the current Loan-to-Value (LTV) ratio of a user's debt bill
stableVault.getCurLtvRate(address addr_)

// To query for liquidatable bills in pages
- stableVault.getliqRecord(uint256 begin, uint256 end)

// To liquidate an order
- BTU.liquidate(address _liqAddress)

// After a debt is liquidated, view the liquidation history index
- stableVault.getRecordLiquidationHistoryIndex(address user)

// To query the liquidation reward rate
- stableVault.getRewardsRate()