diff --git a/SUMMARY.md b/SUMMARY.md index ee77856..4c2199b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -76,7 +76,7 @@ * [LISA Supported Network](developers/lisa-supported-network.md) * [LISA Media Kits](developers/lisa-media-kits.md) -* Contracts +* [Contracts](developers/contracts/README.md) * [liabtc-mint-endpoint](developers/contracts/liabtc-mint-endpoint.md) * [liabtc-mint-registry](developers/contracts/liabtc-mint-registry.md) * [token-liabtc](developers/contracts/token-liabtc.md) diff --git a/developers/contracts/README.md b/developers/contracts/README.md new file mode 100644 index 0000000..ec4187e --- /dev/null +++ b/developers/contracts/README.md @@ -0,0 +1,124 @@ +--- +description: Technical Design Overview +--- + +# Contracts + +LISA is deployed and functioning within the Stacks blockchain network. This document aims to serve both as an index and an overarching overview of the LISA on-chain ecosystem. + +## Governance + +At the top of the on-chain architecture is the LISA DAO, accounting for LISA's governance in a rule-based, modular and flexible manner. Built upon Marvin Janssen's ExecutorDAO project, it operates based on the following core principles: + +1. Proposals are smart contracts. +2. The core executes, the extensions give form. +3. Ownership control happens via sending context. + +For technical details on the ExecutorDAO, refer to the project's [README.md](https://github.com/MarvinJanssen/executor-dao#readme). To understand how the ExecutorDAO is customized and implemented within LISA, visit the dedicated [LISA DAO](https://docs.lisalab.io/governance/lisa-dao) governance page in the documentation. + +## Liquid Staking + +### aBTC as LiaBTC + +`aBTC`, or [ALEX BTC](https://medium.com/alexgobtc/abtc-from-alex-a-practical-step-towards-bitcoin-defi-ccb6ec684d87), is a Stacks SIP-010 token pegged 1:1 to Bitcoin. `LiaBTC` is a rebasing token for `aBTC`, while `vLiaBTC` is its non-rebasing, value-accruing wrapper. + +#### Relations Diagram + +```mermaid +flowchart LR + classDef smclass fill:#FFE4B5,stroke:#FF8C00 + + subgraph XLink Infrastructure + sm[XLink Staking + Manager]:::smclass + sm -.-o stake[["External BTC Staking Platform + (Cobo + Babylon)"]]:::smclass + end + + mint[LiaBTC Mint + Endpoint] + reg[LiaBTC Mint + Registry] + mint <--state update & fund management--> reg + + subgraph Tokens + direction LR + lia["LiaBTC + (Rebasing)"] + wrap["vLiaBTC + (Non-Rebasing + Wrapper)"] + lia <--> wrap + end + + mint --stake/unstake aBTC--> sm[XLink Staking + Manager] + + mint --mint/burn--> lia +``` + +#### LiaBTC Mint Endpoint + +- Contract name: `liabtc-mint-endpoint` +- [Complete technical documentation](liabtc-mint-endpoint.md) + +The Mint Endpoint serves as the users' operational interface to stake and unstake `aBTC`, facilitating the minting and burning of `LiaBTC`. It relies on the XLink Staking Manager to handle the liquid staking pool management. + +#### LiaBTC Mint Registry + +- Contract name: `liabtc-mint-registry` +- [Complete technical documentation](liabtc-mint-registry.md) + +The Mint Registry functions as the persistence and treasury module for the Mint Endpoint operations. + +#### Token LiaBTC + +- Contract name: `token-liabtc` +- [Complete technical documentation](token-liabtc.md) + +Implementation of the `LiaBTC` rebasing token that represents staked `aBTC`. The underlying Bitcoin backing these `aBTC` tokens is staked externally utilizing the XLink on-chain and off-chain infrastructure. The lifecycle of the token invoves minting when `aBTC` is submitted for staking and burning upon unstaking. When users stake `aBTC` through the Mint Endpoint, they receive `LiaBTC` at a 1:1 ratio. + +#### Token vLiaBTC + +- Contract name: `token-vliabtc` +- [Complete technical documentation](token-vliabtc.md) + +Implementation of the `vLiaBTC` value-accruing token, designed as a non-rebasing wrapper for `LiaBTC`. It is mainly used as a layer of compatibility to integrate `LiaBTC` with other DeFi protocols. Users can wrap their `LiaBTC` into `vLiaBTC` to maintain the same value in a non-rebasing format. + +#### XLink Staking Manager + +- Contract name: `xlink-staking` +- [Complete technical documentation](https://docs.xlink.network/developers/contracts/xlink-staking) + +The XLink Staking Manager is a generic contract designed to manage liquid staking pools for multiple tokens and track staker positions within each pool. It is part of a hybrid, token-agnostic liquid staking management system, that operates alongside off-chain backend and frontend components managed by XLink. + +{% hint style="info" %} +This contract is part of [XLink](https://docs.lisalab.io/ecosystem-partners/xlink) ecosystem and is governed by the XLink DAO. +{% endhint %} + +## Deployed contracts + +{% hint style="warning" %} +Page under construction. This is not an exhaustive list. +{% endhint %} + +### Governance + +- ExecutorDAO: [`'SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.lisa-dao`][lisa-dao] +- Operators: [`'SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.operators`][operators] + +### aBTC Liquid Staking + +- LiaBTC Mint Endpoint: [`'SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.liabtc-mint-endpoint`][liabtc-mint-endpoint] +- LiaBTC Mint Registry: [`'SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.liabtc-mint-registry`][liabtc-mint-registry] +- LiaBTC Token: [`'SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.token-liabtc`][token-liabtc] +- vLiaBTC Token: [`'SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.token-vliabtc`][token-vliabtc] +- XLink Staking Manager: [`'SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.xlink-staking`][xlink-staking] + +[lisa-dao]: https://explorer.stxer.xyz/txid/SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.lisa-dao +[operators]: https://explorer.stxer.xyz/txid/SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.operators +[liabtc-mint-registry]: https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.liabtc-mint-registry +[liabtc-mint-endpoint]: https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.liabtc-mint-endpoint +[token-liabtc]: https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.token-liabtc +[token-vliabtc]: https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.token-vliabtc +[xlink-staking]: https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.xlink-staking diff --git a/developers/contracts/liabtc-mint-endpoint.md b/developers/contracts/liabtc-mint-endpoint.md index c1e644e..0c7bafc 100644 --- a/developers/contracts/liabtc-mint-endpoint.md +++ b/developers/contracts/liabtc-mint-endpoint.md @@ -1,7 +1,7 @@ # liabtc-mint-endpoint - Location: `xlink-dao/contracts/liabtc/liabtc-mint-endpoint.clar` - +- [Deployed contract](https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.liabtc-mint-endpoint) Façade for [`xlink-staking`][sm] contract designed to handle the lifecycle of the `LiaBTC` rebasing token (mint, burn and rebase operations). @@ -31,26 +31,26 @@ The burn operation (or unstake) allows users to withdraw their `aBTC` from the l ### Request -User initiates the request to unstake a specific amount of `aBTC`. During this step: +User initiates the request to unstake a specific amount of `aBTC`. During this step: -- That same amount of `LiaBTC` tokens are burned from the user wallet. -- A burn request is created in the registry with a unique `request-id` and a [`PENDING`](#pending) status. +- That same amount of `LiaBTC` tokens are burned from the user wallet. +- A burn request is created in the registry with a unique `request-id` and a [`PENDING`](#pending) status. - The `aBTC` are sent from the Staking Manager to the registry, which will hold the funds until the request is either finalized or revoked. ### Finalize -Once the [`burn-delay`](#burn-delay) period (typically 1,000 Bitcoin blocks) has passed, the user or any other principal can finalize the request. On finalization: +Once the [`burn-delay`](#burn-delay) period (typically 1,000 Bitcoin blocks) has passed, the user or any other principal can finalize the request. On finalization: -- The corresponding `aBTC` is transferred from the registry to the requester, completing the unstaking process. -- The request status is updated to [`FINALIZED`](#finalized). +- The corresponding `aBTC` is transferred from the registry to the requester, completing the unstaking process. +- The request status is updated to [`FINALIZED`](#finalized). ### Revoke Burn requests can be revoked by the requester at any time before it is finalized. When revoke: -- The corresponding `aBTC` is returned to the user. -- A [`mint`](#mint) operation is executed in the same transaction, restoring the user's original amount of `LiaBTC`. -- The request status is updated to [`REVOKED`](#revoked). +- The corresponding `aBTC` is returned to the user. +- A [`mint`](#mint) operation is executed in the same transaction, restoring the user's original amount of `LiaBTC`. +- The request status is updated to [`REVOKED`](#revoked). ## Rebase @@ -380,8 +380,7 @@ Burn request revoked status. - `'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-abtc`: As the underlying token that backs `LiaBTC`, this contract is called for transfers and to specify the token being staked in the Staking Manager. - -- `'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.executor-dao`: This contract is exclusively called by the [`is-dao-or-extension`](#is-dao-or-extension) function for authorizing governance operations. +- `'SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.lisa-dao`: This contract is exclusively called by the [`is-dao-or-extension`](#is-dao-or-extension) function for authorizing governance operations. ## Errors diff --git a/developers/contracts/liabtc-mint-registry.md b/developers/contracts/liabtc-mint-registry.md index 2eb983d..ab97efb 100644 --- a/developers/contracts/liabtc-mint-registry.md +++ b/developers/contracts/liabtc-mint-registry.md @@ -1,7 +1,7 @@ # liabtc-mint-registry - Location: `xlink-dao/contracts/liabtc/liabtc-mint-registry.clar` - +- [Deployed contract](https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.liabtc-mint-registry) The `liabtc-mint-registry` is the data and treasury counterpart to the [`liabtc-mint-endpoint`][mint] contract. It manages the storage of burn requests data and serves as the `aBTC` treasury during burn operations. @@ -114,9 +114,7 @@ Burn request revoked status. - ``: Interaction with potentially any contract implementing the [official SIP-010][sip010] occurs when the [`transfer`](#transfer) function is called. - - -- `'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.executor-dao`: This contract is exclusively called by the [`is-dao-or-extension`](#is-dao-or-extension) function for authorizing governance operations. +- `'SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.lisa-dao`: This contract is exclusively called by the [`is-dao-or-extension`](#is-dao-or-extension) function for authorizing governance operations. ## Errors diff --git a/developers/contracts/token-liabtc.md b/developers/contracts/token-liabtc.md index c9d5725..72f8bef 100644 --- a/developers/contracts/token-liabtc.md +++ b/developers/contracts/token-liabtc.md @@ -1,5 +1,8 @@ # token-liabtc +- Location: `xlink-dao/contracts/liabtc/token-liabtc.clar` +- [Deployed contract](https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.token-liabtc) + ## What is LiaBTC? The `LiaBTC` token is a [SIP-010][sip010] compliant rebasing token that represents staked `aBTC`. The underlying Bitcoin backing these `aBTC` tokens is staked externally. @@ -15,7 +18,7 @@ The rebasing nature of `LiaBTC` is implemented via the "shares" concept. The con The `LiaBTC` balance of a specific user is calculated according to the following equation. $$ -\begin{equation} \textrm{User Balance} = \frac{\textrm{User Shares}}{\textrm{Total Shares}} \; \cdot \: \textrm{Reserve} \end{equation} +\begin{equation} \textrm{User Balance} = \frac{\textrm{User Shares}}{\textrm{Total Shares}} \; \cdot \: \textrm{Reserve} \end{equation} $$ Where: @@ -305,9 +308,7 @@ Initial value is `u8`. ## Contract calls - - -- `'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.executor-dao`: This contract is exclusively called by the [`is-dao-or-extension`](#is-dao-or-extension) function for authorizing governance operations. +- `'SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.lisa-dao`: This contract is exclusively called by the [`is-dao-or-extension`](#is-dao-or-extension) function for authorizing governance operations. ## Errors diff --git a/developers/contracts/token-vliabtc.md b/developers/contracts/token-vliabtc.md index 8205165..1c09cf8 100644 --- a/developers/contracts/token-vliabtc.md +++ b/developers/contracts/token-vliabtc.md @@ -1,5 +1,8 @@ # token-vliabtc +- Location: `xlink-dao/contracts/liabtc/token-vliabtc.clar` +- [Deployed contract](https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.token-vliabtc) + ## What is vLiaBTC? The `vLiaBTC` token is a [SIP-010][sip010] compliant value-accruing token, designed as a non-rebasing wrapper for `LiaBTC`. @@ -221,9 +224,7 @@ Initial value is `u8`. - [`token-liabtc`][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`](#is-dao-or-extension) function for authorizing governance operations. +- `'SM26NBC8SFHNW4P1Y4DFH27974P56WN86C92HPEHH.lisa-dao`: This contract is exclusively called by the [`is-dao-or-extension`](#is-dao-or-extension) function for authorizing governance operations. ## Errors