token-vliabtc

• Location: xlink-dao/contracts/liabtc/token-vliabtc.clar

• Deployed contract

What is vLiaBTC?

The vLiaBTC token is a SIP-010 compliant value-accruing token, designed as a non-rebasing wrapper for LiaBTC.

This token is mainly used as a layer of compatibility to integrate LiaBTC with other DeFi since the total supply and wallet balances remain constant over time. However, its value in terms of LiaBTC does change over time.

Users can wrap their LiaBTC into vLiaBTC to maintain the same value in a non-rebasing format. Upon unwrapping, users receive the same amount of LiaBTC tokens as they would have if they had held the liquid token (LiaBTC) throughout.

How it works?

The token-vliabtc contract can be used as a trustless wrapper that accepts LiaBTC tokens and mints vLiaBTC in return. The contract locks the wrapped LiaBTC in its own balance. When the user unwraps, the contract burns the user's vLiaBTC and sends the corresponding LiaBTC in return.

Internally, the vLiaBTC balance represents the user's share of the total LiaBTC held by the token-vliabtc contract (vaulted LiaBTC). This means that for a general user that holds vLiaBTC, the value in LiaBTC is given by the following equation:

$$\textrm{LiaBTC value} = \frac{\textrm{vLiaBTC Balance}}{\textrm{vLiaBTC Total Supply}} \; \cdot \; \textrm{Vaulted LiaBTC}$$

Unlike some other DeFi protocols, the amount of vLiaBTC minted when wrapping does not directly correspond to the LiaBTC shares exchanged. However, both approaches are equivalent and achieve the same functional outcome. For a detailed explanation of this equivalence, see the Appendix.

Features

Public

transfer

Transfers LiaBTC from the sender to the recipient. For authorization, the specified sender must either be the tx-sender or the contract-caller. Uses the ft-transfer? Clarity function, where the actual transferred assets are shares.

Parameters

Name	Type
amount	uint
sender	principal
recipient	principal
memo	optional (buff 2048)

Token management

The following functions are guarded by the is-dao-or-extension function. These features are resticted to the LISA DAO or enabled extensions.

mint

Mints vLiaBTC for the specified recipient. The recipient must be either the tx-sender or the contract-caller. The amount of vLiaBTC minted is calculated by applying get-tokens-to-share to the provided amount before transferring the LiaBTC from the user to the contract.

Parameters

Name	Type
amount	uint
recipient	principal

burn

Burns vLiaBTC for the specified sender. The sender must be either the tx-sender or the contract-caller. The amount of LiaBTC to be transferred back to the user is calculated via the get-shares-to-tokens function before performing the burn.

Parameters

Name	Type
amount	uint
sender	principal

Token governance

The following functions are guarded by the is-dao-or-extension function. These features are resticted to the LISA DAO or enabled extensions.

set-name

Updates the token-name variable.

Parameters

Name	Type
new-name	string-ascii 32

set-symbol

Updates the token-symbol variable.

Parameters

Name	Type
new-symbol	string-ascii 10

set-decimals

Updates the token-decimals variable.

Parameters

Name	Type
new-decimals	uint

set-token-uri

Updates the token-uri variable.

Parameters

Name	Type
new-uri	string-utf8 256

Supporting features

is-dao-or-extension

Standard protocol function to check whether the contract-caller is an enabled extension within the DAO or the tx-sender is the DAO itself (proposal execution scenario). The enabled extension check is delegated to the LISA's executor-dao contract.

get-tokens-to-shares

Converts a specified LiaBTC amount into its equivalent value in vLiaBTC. The term shares is utilized because vLiaBTC amounts represent a share of the total vaulted LiaBTC.

Parameters

Name	Type
amount	uint

get-shares-to-tokens

Converts a specified amount of vLiaBTC (referred to as the shares parameter) into its equivalent value in LiaBTC. This function is called within the burn function to determine the amount of LiaBTC to transfer to the user. The term shares is utilized because vLiaBTC amounts represent a share of the total vaulted LiaBTC.

Parameters

Name	Type
shares	uint

Getters

get-balance

Returns the vLiaBTC balance of a specified principal (who) using the ft-get-balance Clarity function.

Parameters

Name	Type
who	principal

get-total-supply

Returns the total supply of vLiaBTC using the ft-get-supply Clarity function.

get-share

Returns the value in LiaBTC of a user's total balance of vLiaBTC. It is calculated by retrieveing the LiaBTC amount and converting it to tokens with the get-shares-to-tokens.

Parameters

Name	Type
who	principal

get-total-shares

Returns the vaulted LiaBTC balance. This is the LiaBTC held by the token-vliabtc contract, which are the tokens from the users that currently hold the wrapped token.

get-name

Returns the token-name variable.

get-symbol

Returns the token-symbol variable.

get-token-uri

Returns the token-uri variable.

get-decimals

Returns the token-decimals variable.

Storage

token-name

Data	Type
Variable	string-ascii 32

Intial value is "vLiaBTC".

token-symbol

Data	Type
Variable	string-ascii 10

Intial value is "vLiaBTC".

token-uri

Data	Type
Variable	optional (string-utf8 256)

Initial value is some u"https://cdn.alexlab.co/metadata/vtoken-liabtc.json".

token-decimals

Data	Type
Variable	uint

Initial value is u8.

Contract calls

• token-liabtc: Core external calls are made to perform LiaBTC transfers when wrapping/unwrapping and to retrieve the balance of LiaBTC held by the token-vliabtc contract (vaulted LiaBTC).
• 'SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.lisa-dao: This contract is exclusively called by the is-dao-or-extension function for authorizing governance operations.

Errors

Error Name	Value
err-unauthorised	(err u3000)

Appendix

The amount of vLiaBTC minted during wrapping does not directly correspond to the LiaBTC shares exchanged. In some other DeFi protocols, these two values are exactly the same. Why are these different approaches to wrapping equivalent?

To understand this, let's revisit the equation from the How it works? section, pasted down here to facilitate the explanation:

$$\begin{equation} \textrm{LiaBTC value} = \frac{\textrm{vLiaBTC Balance}}{\textrm{vLiaBTC Total Supply}} \; \cdot \; \textrm{Vaulted LiaBTC}. \end{equation}$$

This equation shows the LiaBTC value for a general user holding a specific vLiaBTC Balance.

Now, consider the relationship between LiaBTC shares and tokens, given by equation (1) of the token-liabtc document. Using that equation, the Vaulted LiaBTC can be expressed as:

$$\textrm{Vaulted LiaBTC} = \frac{\textrm{Vaulted Shares}}{\textrm{Total Shares}} \; \cdot \: \textrm{Reserve},$$

where the Vaulted Shares are the LiaBTC shares representation of the vaulted LiaBTC. Similarly, we can think of the LiaBTC value expressed as a fraction of the Reserve using a hypothetical shares term:

$$\textrm{LiaBTC value} = \frac{\textrm{Shares}_h}{\textrm{Total Shares}} \; \cdot \: \textrm{Reserve}.$$

Assuming the LiaBTC value remain unchanged since the user wrapped their tokens, the hypothetical shares are the shares representation of the LiaBTC amount that the user wrapped. So, from now on, we will refer them as User Shares, the LiaBTC shares that the user exchanged during the wrap operation. Replacing the expressions for Vaulted LiaBTC and LiaBTC value into equation (1) and cancelling the Reserve factor from both sides, we get:

$$\frac{\textrm{User Shares}}{\textrm{Total Shares}} = \frac{\textrm{vLiaBTC Balance}}{\textrm{vLiaBTC Total Supply}} \; \cdot \; \frac{\textrm{Vaulted Shares}}{\textrm{Total Shares}}.$$

After cancelling Total Shares on both sides, we obtain

$$\begin{equation} \textrm{User Shares} = \frac{\textrm{vLiaBTC Balance}}{\textrm{vLiaBTC Total Supply}} \; \cdot \; \textrm{Vaulted Shares} \end{equation}$$

as the general equation that relates the LiaBTC shares (representing the LiaBTC amount that the user initially wrapped) and the corresponding vLiaBTC balance.

In many DeFi protocols, the amount of wrapped tokens minted equals the rebasing token's shares exchanged. In such cases, the Vaulted Shares equal the total circulating supply of the wrapped token (vLiaBTC Total Supply), simplifying the equation to:

$$\textrm{User Shares} = \textrm{vLiaBTC Balance}.$$

This scenario is a specific case of equation (2), showing that both approaches are functionally equivalent.