kylefang/xlink-docs
1
0
Fork 0
mirror of https://github.com/Brotocol-xyz/xlink-docs.git synced 2026-01-12 22:25:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7 from CoinFabrik/docs/xlink-contracts-w2

Browse Source 
Developers: add xLINK contracts documentation (w2)
This commit is contained in:
fiftyeightandeight
2025-01-10 21:57:04 +08:00
committed by GitHub
parent bb34c34e38 58870edddc
commit a772f939e2
4 changed files with 399 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
SUMMARY.md
View File

@@ -27,7 +27,9 @@
## 🎮 Developers
* [Smart Contracts](developers/contracts/README.md)
* [btc peg-in endpoint v2-03](developers/contracts/btc-peg-in-endpoint-v2-03.md)
* [btc-peg-out-endpoint-v2-01](developers/contracts/btc-peg-out-endpoint-v2-01.md)
* [meta peg-in endpoint v2-02](developers/contracts/meta-peg-in-endpoint-v2-02.md)
* [meta peg-out endpoint v2-03](developers/contracts/meta-peg-out-endpoint-v2-03.md)
* [xlink-staking](developers/contracts/xlink-staking.md)
<!--

4
developers/contracts/README.md
View File

@@ -2,6 +2,10 @@
## [btc-peg-in-endpoint-v2-03](btc-peg-in-endpoint-v2-03.md)
## [btc-peg-out-endpoint-v2-01](btc-peg-out-endpoint-v2-01.md)
## [meta-peg-in-endpoint-v2-02](meta-peg-in-endpoint-v2-02.md)
## [meta-peg-out-endpoint-v2-03](meta-peg-out-endpoint-v2-03.md)
## [xlink-staking](xlink-staking.md)

151
developers/contracts/btc-peg-out-endpoint-v2-01.md Normal file
View File

@@ -0,0 +1,151 @@
# btc-peg-out-endpoint-v2-01.clar
- Location: `xlink/packages/contracts/bridge-stacks/contracts/btc-peg-out-endpoint-v2-01.clar`
- [Deployed contract]()
This technical document provides a detailed overview of the contract responsible for managing the peg-out process, enabling the transfer of bridged BTC from the Stacks network back to the Bitcoin network. In this process, aBTC (Bridged BTC tokens on Stacks) is burned or transferred, depending on the context, and BTC is released to a specified Bitcoin address. The contract's primary functionality is implemented through a series of public functions. Let's review this core operation.
## Storage
### `fee-to-address`
| Data | Type |
| -------- | ------ |
| Variable | `principal` |
The address where the fees collected from peg-out operations are transferred. By default, the address assigned to receive these fees is the `tx-sender` address of the contract deployer.
### `peg-out-paused`
| Data | Type |
| -------- | ------ |
| Variable | `bool` |
A flag that indicates whether the peg-out process is active. If set to true, all peg-out operations are paused, preventing any new transactions. The contract is deployed in a paused state by default.
### `peg-out-fee`
| Data | Type |
| -------- | ------ |
| Variable | `uint` |
The percentage fee charged for peg-out transactions. The fee is represented in a fixed-point format with 6 decimal places. This means that 100% is represented as `u100000000`and 1% is represented as `u1000000`. By default, this value is `u0`.
### `peg-out-min-fee`
| Data | Type |
| -------- | ------ |
| Variable | `uint` |
The minimum fee required for a peg-out transaction, regardless of the transaction amount. By default, this value is `u0`.
## Features
### Peg-out features
#### `request-peg-out-0`
This function initiates the peg-out process, enabling users to transfer bridged BTC from the Stacks network to a specified Bitcoin address (peg-out-address). First, it validates the requested amount using `validate-peg-out-0` to ensure it meets the minimum requirements (the requested amount must be sufficient to cover both the peg-out fee and the gas fee, leaving a positive net amount available for transfer). The function registers the request by interacting with the `.btc-bridge-registry-v2-01` contract, storing details such as the requesting user, target Bitcoin address, calculated fees, and associated block heights (e.g., `block-height` and `burn-block-height`). A unique request ID is generated for tracking. Finally, the amount of aBTC is escrowed by transferring it from the user to the contract, securing the funds until the request is either completed or revoked.
##### Parameters
```lisp
(peg-out-address (buff 128))
(amount uint)
```
#### `claim-peg-out`
This function allows a user to claim a specific peg-out request. The function first retrieves the request details and performs several validations to check that the request is active and valid. It checks that the peg-out process is not paused, the request has not been finalized, revoked, or already claimed, and that all conditions for claiming are met. Upon successful validation, the function registers the request as claimed in the `.btc-bridge-registry-v2-01` contract, updating the state with the claimer's identity, the Bitcoin address (`fulfilled-by`) responsible for completing the transaction, and the block height defining the claim's expiration period. Note that the expiration period defines a specific timeframe during which the claimed request must be finalized. And finally, the updated request details are logged, and the claimer is granted the right to proceed with finalizing the peg-out.
##### Parameters
```lisp
(request-id uint)
(fulfilled-by (buff 128))
```
#### `finalize-peg-out`
This function completes the peg-out process. It performs checks to finalize the peg-out, including verifying that the transaction has been mined, and verifies that the included details in the transaction (concerning the amount, recipient address, and fulfiller address) align with the request specifications. The function interacts with the `.btc-bridge-registry-v2-01` contract to mark the request as finalized.
Additionally, the function processes fees by transferring them to the designated governance address. It then handles the bridged tokens (aBTC) associated with the request in one of two ways:
1. Approved Peg-in Address:
- The tokens are burned, reducing the total supply.
2. Third-Party Address:
- The tokens are transferred from the contract to the claimer, maintaining the total supply.
Once all operations are completed, the function logs the transaction details and confirms the successful finalization of the request.
##### Parameters
```lisp
(request-id uint)
(tx (buff 32768))
(block { header: (buff 80), height: uint })
(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint })
(output-idx uint)
(fulfilled-by-idx uint)
```
#### `revoke-peg-out`
This function allows the user who created a peg-out request to cancel it, only if certain conditions are met. The function checks that the required `request-revoke-grace-period` has passed since the request was created, and verifies that the request has not already been claimed, finalized, or already revoked. Once these validations are passed, the function updates the request's status to "revoked" in the `.btc-bridge-registry-v2-01` contract. It then processes the refund by transferring the associated fees and the bridged tokens (aBTC) back to the requester.
##### Parameters
```lisp
(request-id uint)
```
### Governance features
#### `is-dao-or-extension`
This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.
#### `is-peg-out-paused`
A read-only function that checks the operational status of the contract.
#### `pause-peg-out`
A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.
##### Parameters
```lisp
(paused bool)
```
### Getters
#### `get-peg-out-fee`
#### `get-peg-out-min-fee`
#### `get-request-revoke-grace-period`
#### `get-request-claim-grace-period`
#### `get-request-or-fail`
##### Parameters
```lisp
(request-id uint)
```
#### `get-peg-in-sent-or-default`
##### Parameters
```lisp
(tx (buff 32768))
(output uint)
```
#### `get-fee-to-address`
#### `get-txid`
##### Parameters
```lisp
(tx (buff 32768))
```
## Contract calls (interactions)
- `executor-dao`: Calls are made to verify whether a certain contract-caller is designated as an extension.
- `btc-bridge-registry-v2-01`: This contract is called to register, update, and track peg-out requests.
- `clarity-bitcoin-v1-07`: This contract is called to validate Bitcoin transactions by verifying that they have been mined and extracting relevant transaction details, such as inputs, outputs, and script data.
- `token-abtc`: This contract represents the aBTC token on the Stacks network. It is directly responsible for managing the transfer, burning, and refunding of aBTC tokens during the peg-out process.
## Errors
| Error Name | Value |
| ---------------- | ------------- |
| `err-unauthorised` | `(err u1000)` |
| `err-paused` | `(err u1001)` |
| `err-invalid-amount` | `(err u1003)` |
| `err-invalid-tx` | `(err u1004)` |
| `err-already-sent` | `(err u1005)` |
| `err-address-mismatch` | `(err u1006)` |
| `err-request-already-revoked` | `(err u1007)` |
| `err-request-already-finalized` | `(err u1008)` |
| `err-revoke-grace-period` | `(err u1009)` |
| `err-request-already-claimed` | `(err u1010)` |
| `err-bitcoin-tx-not-mined` | `(err u1011)` |
| `err-tx-mined-before-request` | `(err u1013)` |
| `err-slippage` | `(err u1016)` |
<!-- Documentation Contract Template v0.1.0 -->

242
developers/contracts/meta-peg-out-endpoint-v2-03.md Normal file
View File

@@ -0,0 +1,242 @@
# meta-peg-out-endpoint-v2-03.clar
- Location: `xlink/packages/contracts/bridge-stacks/contracts/meta-peg-out-endpoint-v2-03.clar`
- [Deployed contract]()
This technical document provides a detailed overview of the contract responsible for facilitating the peg-out process of tokens from the Stacks network to the burn blockchain. The target token standard is BRC-20, a protocol on Bitcoin's metaprotocol layer that supports fungible assets, inspired by Ethereum's ERC-20 standard.
Unlike the meta-peg-in contract, the meta-peg-out feature is specifically designed to support the bridging-out process. This is achieved through a series of public functions, each intended to execute sequentially, while incorporating grace periods between their execution. In the following sections, we will explore these functions in detail.
## Storage
### `paused`
| Data | Type |
| -------- | ------ |
| Variable | `bool` |
This data variable serves as a flag to control the operational status of the contract within the system. When set to 'paused,' it blocks all peg-out transactions. By default, the contract is deployed in 'paused' mode. Refer to the [pause](meta-peg-out-endpoint-v2-03.md#pause) governance feature to change this status.
### `fee-to-address`
| Data | Type |
| -------- | ------ |
| Variable | `principal` |
This variable represents the address to which fees are paid. In this contract, there are two categories of fees: peg-out fees and gas fees. Peg-out fees are transactioned with the relevant token, while gas fees are handled using the Bridged BTC token (`token-abtc`). For more details on these transactions, refer to the [finalize peg-out feature](meta-peg-out-endpoint-v2-03.md#finalize-peg-out-on-index). By default, the address assigned to receive these fees is the `tx-sender` address of the contract deployer.
### Relevant constants
#### `burn-height-start`
| Type | Value |
| ------ | ----- |
| `uint` | `burn-block-height` |
This constant specifies the block height of the underlying burn blockchain at the time of contract deployment. It is utilized to ensure that operations within the `finalize-peg-out` function are limited to transactions minted from this block onward.
## Features
### Peg-out features
The peg-out feature is a multi-step process comprising several phases to ensure secure and orderly transactions. The process begins with requesting a peg-out to initiate the transfer of tokens out of the Stacks network. Following this request, configured grace periods allow for specific actions: users can choose to revoke their request or claim it. Once a peg-out request is claimed, the final step is to complete the transaction by finalizing the peg-out.
#### `request-peg-out`
The first step in the peg-out process is to submit a request. This operation involves the `tx-sender` (requester) initiating a peg-out request for a specified amount of a pegged-in token. Upon initiation, the net amount along with fee costs are escrowed by transferring the token and the gas fee token (`token-abtc`) to the contract. These are held until the request is either finalized or revoked.
To proceed, the request must satisfy several validations:
- The pair (token + chain-id) must be approved in the meta registry.
- The specified amount must exceed the peg-out operation fee for that particular token.
- The token peg-out operation must be active in the registry (not paused).
Once these validations are met, the operation is registered in the meta registry via the contract `meta-bridge-registry-v2-03`. The function then generates a unique identifier for the request, known as the `request-id`, ensuring traceability and reference for future operations.
##### Parameters
```lisp
(amount uint)
(peg-out-address (buff 128))
(token-trait <ft-trait>)
(the-chain-id uint)
```
#### `claim-peg-out`
Following the peg-out request, a next potential step is to claim the request. This step is critical, as it marks the request as ready for finalization. This action is executed by calling the function with the `request-id` of the previously created request, along with the `fulfilled-by` parameter, which designates the address responsible for executing the burn blockchain operation.
The claim must satisfy the following validations:
- The request must exist.
- The token pair must be approved and operational (not paused for peg-out).
- The request must not be revoked, finalized, or previously claimed.
Once these conditions are met, the final step is to register the claim in the meta registry. This registration includes the claimer, the fulfilled-by address, and the calculated grace period, during which the claimed request will be eligible for finalization.
##### Parameters
```lisp
(request-id uint)
(fulfilled-by (buff 128))
```
#### `finalize-peg-out-on-index`
Finalizing a peg-out is the final step in committing the peg-out process. This function takes in the burn blockchain transaction (Bitcoin) that corresponds to the Stacks layer operation and executes the peg-out request (`request-id`) along with all related token transfers and their corresponding fees. The finalization can be performed by either a peg-in address or a third-party address.
Key validations include:
- The request must exist.
- The token pair must be approved and operational (not paused for peg-out).
- The transaction cannot be indexed to a time before the contract deployment.
- The transaction's metaprotocol token (BRC-20) must match the requested details (`tick` and `amount`). Additionally, the `from` address must correspond to the `fulfilled-by` address, and the `to` address must match the `peg-out-address`.
- The request must not be revoked or already finalized.
The procedure is as follows, based on who finalizes it:
1) Peg-In Address
- The net amount of the peg-in token requested is burned from the contract balance, affecting the overall total supply.
- The peg-out fee (involved token) and gas fees (`token-abtc`) are paid to the [configured address](meta-peg-out-endpoint-v2-03.md#fee-to-address).
2) Third-Party Address
- The net amount of the peg-in token and the burn blockchain gas fee are transferred from the contract to the claimer, so the overall involved token balance remains unaffected.
- The peg-out fee is transferred from the contract to the [configured address](meta-peg-out-endpoint-v2-03.md#fee-to-address).
This operation involves indexing the specified transaction through the `oracle-v2-01` contract and marking the request as "finalized" in the `meta-bridge-registry-v2-03` contract.
##### Parameters
```lisp
(request-id uint)
(tx {
bitcoin-tx: (buff 32768),
output: uint,
tick: (string-utf8 256),
amt: uint,
from: (buff 128),
to: (buff 128),
from-bal: uint,
to-bal: uint,
decimals: uint
})
(block { header: (buff 80), height: uint })
(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint })
(signature-packs (list 10 { signer: principal, tx-hash: (buff 32), signature: (buff 65) }))
(token-trait <ft-trait>)
```
#### `revoke-peg-out`
In certain scenarios, a requested peg-out may need to be revoked, allowing users to retract their request if necessary.
Key validations include:
- The grace period must have elapsed.
- The request must not have been claimed, finalized, or previously revoked.
If these conditions are met, the process continues by returning the tokens initially escrowed for the request, including both the peg-in tokens and the associated fees. These returns are made from the contract directly back to the requester. Finally, the `meta-bridge-registry-v2-03` contract is invoked to mark this request as `revoked`.
##### Parameters
```lisp
(request-id uint)
(token-trait <ft-trait>)
```
### Supporting features
The following functions are tools to assist the off-chain activities.
1. Validation helpers (`validate-peg-out`).
2. Token pair helpers (`get-pair-details-many`).
### Governance features
#### `is-dao-or-extension`
This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.
#### `is-paused`
A read-only function that checks the operational status of the contract.
#### `pause`
A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.
##### Parameters
```lisp
(new-paused bool)
```
#### `transfer-all-to-many`
This contract feature is designed to transfer its entire balance of a specified list of tokens to a new owner. Access to this feature is restricted by the `is-dao-or-extension` function.
##### Parameters
```lisp
(new-owner principal) (token-traits (list 10 <ft-trait>))
```
#### `set-fee-to-address`
This contract feature allows for specifying the address to which peg-out fees (denominated in the relevant tokens) and gas fees (denominated in Bridged BTC tokens, known as `token-abtc`) will be transferred.
##### Parameters
```lisp
(new-fee-to-address principal)
```
### Getters
* `get-fee-to-address`
* `get-request`
* `get-request-many`
* `get-request-revoke-grace-period`
* `get-request-claim-grace-period`
* `get-request-or-fail`
* `get-pair-details`
* `get-pair-details-many`
* `get-pair-details-or-fail`
* `get-tick-to-pair-or-fail`
* `get-peg-in-sent-or-default`
### Relevant internal functions
* `index-tx`
## Contract calls (interactions)
* `executor-dao`: Calls are made to verify whether a certain contract-caller is designated as an extension.
* `meta-bridge-registry-v2-03`: This interaction is primarily utilized by the peg-out contract to register request operations. Additionally, this contract is responsible for managing approved addresses. It provides functionality through its `is-peg-in-address-approved` and `is-fulfill-address-approved` functions, which verify whether specific addresses are authorized within the system.
* `oracle-v2-01`: This contract is called to verify that a transaction was mined and to index Bitcoin transactions.
* Tokens (`token-trait`) During the steps of peg-out operations, this trait is utilized to invoke the relevant tokens and execute the necessary transfers involved in the transaction. It is a customized adaptation of Stacks' standard definition for Fungible Tokens (`sip-010`), with additional support for 8-digit fixed-point notation.
* `token-abtc`: This is the Bridged BTC token used throughout the peg-out contract to operate with native Stacks' SIP-010 token transactions involving the burn blockchain base-coin (BTC).
## Errors
| Error Name | Value |
| --------------------------------- | ------------- |
| `err-unauthorised` | `(err u1000)` |
| `err-paused` | `(err u1001)` |
| `err-peg-in-address-not-found` | `(err u1002)` |
| `err-invalid-amount` | `(err u1003)` |
| `err-token-mismatch` | `(err u1004)` |
| `err-invalid-tx` | `(err u1005)` |
| `err-already-sent` | `(err u1006)` |
| `err-address-mismatch` | `(err u1007)` |
| `err-request-already-revoked` | `(err u1008)` |
| `err-request-already-finalized` | `(err u1009)` |
| `err-revoke-grace-period` | `(err u1010)` |
| `err-request-already-claimed` | `(err u1011)` |
| `err-invalid-input` | `(err u1012)` |
| `err-tx-mined-before-request` | `(err u1013)` |
| `err-commit-tx-mismatch` | `(err u1014)` |
| `err-invalid-burn-height` | `(err u1003)` |
| `err-tx-mined-before-start` | `(err u1015)` |
<!-- Documentation Contract Template v0.1.0 -->