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

update of the meta-peg-out technical documentation

Browse Source
This commit is contained in:
ignacio.pena@coinfabrik.com
2025-01-23 17:04:06 -03:00
parent 24ce550a14
commit 82b16e0c0f
3 changed files with 34 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
SUMMARY.md
View File

@@ -29,7 +29,7 @@
* [btc peg-in endpoint](developers/contracts/btc-peg-in-endpoint.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)
* [meta peg-out endpoint v2-03](developers/contracts/meta-peg-out-endpoint.md)
* [cross-peg-in-endpoint-v2-03](developers/contracts/cross-peg-in-endpoint-v2-03.md)
* [cross-peg-out-endpoint-v2-01](developers/contracts/cross-peg-out-endpoint-v2-01.md)
* [xlink-staking](developers/contracts/xlink-staking.md)

2
developers/contracts/README.md
View File

@@ -50,7 +50,7 @@ This endpoint's main responsibility the bridging of assets in the Bitcoin chain
#### Meta Peg-Out Endpoint
- Contract name: `meta-peg-out-endpoint-v2-03`
- [Complete technical documentation](meta-peg-out-endpoint-v2-03.md)
- [Complete technical documentation](meta-peg-out-endpoint.md)
This endpoint manages the bridging of tokens from the Stacks chain back to the Bitcoin blockchain, where they are converted into BRC-20 assets.

61
developers/contracts/meta-peg-out-endpoint-v2-03.md → developers/contracts/meta-peg-out-endpoint.md
View File

@@ -1,6 +1,6 @@
# meta-peg-out-endpoint-v2-03.clar
# meta-peg-out-endpoint
- Location: `xlink/packages/contracts/bridge-stacks/contracts/meta-peg-out-endpoint-v2-03.clar`
- Location: `xlink/packages/contracts/bridge-stacks/contracts/meta-peg-out-endpoint-v2-04`
- [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.
@@ -15,7 +15,7 @@ Unlike the meta-peg-in contract, the meta-peg-out feature is specifically design
| -------- | ------ |
| 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.
This data variable serves as a flag to control the operational status of the contract. When set to `true`, all peg-out transactions are blocked. By default, the contract is deployed in *paused* mode. Refer to the [pause](meta-peg-out-endpoint.md#pause) governance feature to know more on how to change this status.
### `fee-to-address`
@@ -23,7 +23,7 @@ This data variable serves as a flag to control the operational status of the con
| -------- | ------ |
| 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.
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. The first ones are charged in the same token being bridged, while gas fees are handled using the Bridged BTC token. For more details on these transactions, refer to the [finalize peg-out feature](meta-peg-out-endpoint.md#finalize-peg-out-on-index). By default, the address assigned to receive these fees is the one used to deployed the contract.
### Relevant constants
@@ -31,27 +31,27 @@ This variable represents the address to which fees are paid. In this contract, t
| Type | Value |
| ------ | ----- |
| `uint` | `burn-block-height` |
| `constant` | `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.
This constant specifies the block height of the underlying burn blockchain at the time the contract was deployed. 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.
The peg-out feature is a multi-step process comprising several phases to ensure secure and orderly transactions. The process begins when a peg-out request is issued to initiate the transfer of tokens out of the Stacks network. Following this request, configured grace periods allows users to either 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, which executes the transfer and updates the relevant records as part of the process.
Below, we will explain in more detail the functions that execute each step of this process.
#### `request-peg-out`
###### _(in contract meta-peg-out-endpoint-v2-04)_
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.
In this first step, the `tx-sender` requests to peg-out a specified amount of previously bridged 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, where they remain until the operation is either finalized or revoked.
To proceed, the request must satisfy several validations:
To proceed, several validations must be met:
- The pair (token + chain-id) must be approved in the meta registry.
- The pair (token + chain-id) must be approved in the meta registry, meaning it is recognized as eligible for bridging operations.
- 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.
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, known as the `request-id`, ensuring traceability and reference for future operations.
##### Parameters
@@ -63,8 +63,9 @@ Once these validations are met, the operation is registered in the meta registry
```
#### `claim-peg-out`
###### _(in contract meta-peg-out-endpoint-v2-04)_
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.
A next potential step is to claim the request previously issued. This step is critical, as it marks the request as ready for finalization. This action is executed by calling the function with the id of the request, along with the `fulfilled-by` parameter, which designates the address responsible for executing the bitcoin operation.
The claim must satisfy the following validations:
@@ -72,7 +73,7 @@ The claim must satisfy the following validations:
- 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.
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
@@ -82,25 +83,26 @@ Once these conditions are met, the final step is to register the claim in the me
```
#### `finalize-peg-out-on-index`
###### _(in contract meta-peg-out-endpoint-v2-04)_
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.
Finalizing a peg-out is the final step in committing the process. This function takes in the burn blockchain (Bitcoin) transaction that corresponds to the Stacks layer operation and executes the peg-out request 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 transaction cannot be indexed to a time before the deployment of the contract.
- The transaction's metaprotocol token (BRC-20) must match the requested details, including the `tick` (a unique identifier for the token) and the `amount` (the quantity of the token involved in the transaction). 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).
- The net amount of tokens requested for the peg-out operation is burned from the contract balance, affecting the overall total supply.
- The peg-out fee and gas fees are paid to the [configured address](meta-peg-out-endpoint.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).
- The net amount of tokens requested for the peg-out operation and the 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.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.
@@ -126,8 +128,9 @@ This operation involves indexing the specified transaction through the `oracle-v
```
#### `revoke-peg-out`
###### _(in contract meta-peg-out-endpoint-v2-04)_
In certain scenarios, a requested peg-out may need to be revoked, allowing users to retract their request if necessary.
In certain scenarios, a requested peg-out may need to be revoked, allowing users to retract it if necessary.
Key validations include:
@@ -206,15 +209,15 @@ This contract feature allows for specifying the address to which peg-out fees (d
### Relevant internal functions
* `index-tx`
* `index-tx`: this function validates and indexes a Bitcoin transaction in the `oracle-v2-01` contract.
## 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).
* `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