token-vliabtc
Last updated
Last updated
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.
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:
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.
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
amount
uint
sender
principal
recipient
principal
memo
optional (buff 2048)
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
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
amount
uint
sender
principal
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
new-name
string-ascii 32
set-symbol
Updates the token-symbol
variable.
Parameters
new-symbol
string-ascii 10
set-decimals
Updates the token-decimals
variable.
Parameters
new-decimals
uint
set-token-uri
Updates the token-uri
variable.
Parameters
new-uri
string-utf8 256
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
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
shares
uint
get-balance
Returns the vLiaBTC
balance of a specified principal (who
) using the ft-get-balance
Clarity function.
Parameters
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
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.
token-name
Variable
string-ascii 32
Intial value is "vLiaBTC"
.
token-symbol
Variable
string-ascii 10
Intial value is "vLiaBTC"
.
token-uri
Variable
optional (string-utf8 256)
Initial value is some u"https://cdn.alexlab.co/metadata/vtoken-liabtc.json"
.
token-decimals
Variable
uint
Initial value is u8
.
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
).
'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.executor-dao
: This contract is exclusively called by the is-dao-or-extension
function for authorizing governance operations.
err-unauthorised
(err u3000)
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:
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:
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:
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:
After cancelling Total Shares on both sides, we obtain
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:
This scenario is a specific case of equation (2), showing that both approaches are functionally equivalent.