Treasury

Overview

The treasury serves as the central storage for all interBTC. It exposes the transfer function, which allows any user to transfer interBTC. Three additional internal functions are exposed for the Issue and Redeem components.

Step-by-step

  • Transfer: A user sends an amount of interBTC to another user by calling the transfer function.

  • Issue: The issue module calls into the treasury when an issue request is completed (via executeIssue) and the user has provided a valid proof that the required amount of BTC was sent to the correct vault. The issue module calls the mint function to create interBTC.

  • Redeem: The redeem protocol requires two calls to the treasury module. First, a user requests a redeem via the requestRedeem function. This invokes a call to the lock function that locks the requested amount of tokens for this user. Second, when a redeem request is completed (via executeRedeem) and the vault has provided a valid proof that it transferred the required amount of BTC to the correct user, the redeem module calls the burn function to destroy the previously locked interBTC.

Data Model

Scalars

TotalSupply

The total supply of interBTC.

Maps

Accounts

Mapping from accounts to the Account struct.

Structs

Account

Stores the balances of a single account.

Parameter

Type

Description

free

Balance

Free and may be transferred without restriction.

reserved

Balance

Reserved and may not be used by holder until unlocked.

Functions

transfer

Transfers a specified amount of interBTC from a sender to a receiver.

Specification

Function Signature

transfer(sender, receiver, amount)

Parameters

  • sender: Account sending an amount of interBTC.

  • receiver: Account receiving an amount of interBTC.

  • amount: The number of interBTC being sent.

Events

Preconditions

  • The function call MUST be signed by the sender.

  • The account MUST have sufficient free balance.

Postconditions

  • The sender’s free balance MUST decrease by amount.

  • The receiver’s free balance MUST increase by amount.

mint

In the BTC Parachain new interBTC can be created by leveraging the Issue. However, to separate concerns and access to data, the Issue module has to call the mint function to complete the issue process in the interBTC component. The function increases the totalSupply of interBTC.

Warning

This function can only be called from the Issue module.

Specification

Function Signature

mint(account, amount)

Parameters

  • account: The account requesting interBTC.

  • amount: The amount of interBTC to be minted.

Events

Preconditions

  • The function MUST ONLY be called as part of the Issue.

Postconditions

  • The account’s free balance MUST increase by amount.

  • The TotalSupply MUST increase by amount.

lock

During the Redeem, a user needs to be able to lock interBTC. Locking transfers coins from the free balance to the reserved balance to prevent users from transferring the coins.

Specification

Function Signature

lock(account, amount)

Parameters

  • account: The account locking a certain amount of interBTC.

  • amount: The amount of interBTC that should be locked.

Events

Preconditions

  • The account MUST have sufficient free balance.

Postconditions

  • The account’s free balance MUST decrease by amount.

  • The account’s reserved balance MUST increase by amount.

burn

During the Redeem, users first lock and then “burn” (i.e. destroy) their interBTC to receive BTC. Users can only burn tokens once they are locked to prevent transaction ordering dependencies. This means a user first needs to move his tokens from the Balances to the LockedBalances mapping via the lock function.

Warning

This function can only be called from the Redeem module.

Specification

Function Signature

burn(account, amount)

Parameters

  • account: The account burning locked interBTC.

  • amount: The amount of interBTC that should be burned.

Events

Preconditions

  • The account MUST have sufficient reserved balance.

  • The function MUST ONLY be called from the Redeem.

Postconditions

  • The account’s reserved balance MUST decrease by amount.

  • The TotalSupply MUST decrease by amount.

Events

Transfer

Issues an event when a transfer of funds was successful.

Event Signature

Transfer(sender, receiver, amount)

Parameters

  • sender: Account sending an amount of interBTC.

  • receiver: Account receiving an amount of interBTC.

  • amount: The number of interBTC being sent.

Function

Mint

Issue an event when new interBTC are minted.

Event Signature

Mint(account, amount)

Parameters

  • account: The account requesting interBTC.

  • amount: The amount of interBTC to be added to an account.

Function

Lock

Emits the newly locked amount of interBTC by a user.

Event Signature

Lock(redeemer, amount)

Parameters

  • account: The account locking interBTC.

  • amount: The amount of interBTC that should be locked.

Function

Burn

Issue an event when the amount of interBTC is successfully destroyed.

Event Signature

Burn(account, amount)

Parameters

  • account: The account burning interBTC.

  • amount: The amount of interBTC that should be burned.

Function

Errors

ERR_INSUFFICIENT_FREE_BALANCE

  • Message: “The free balance of this account is insufficient to complete the transaction.”

  • Functions: transfer | lock

  • Cause: The free balance of the account is too low to complete this action.

ERR_INSUFFICIENT_RESERVED_BALANCE

  • Message: “The reserved balance of this account is insufficient to burn the tokens.”

  • Function: burn

  • Cause: The reserved balance of the account is too low to complete this action.