From 3410bb5ba5307c94e6b20a7aa08ea0a25d30c3b9 Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Thu, 30 Jan 2025 10:17:27 -0300 Subject: [PATCH 1/3] minor fixes --- SUMMARY.md | 2 +- developers/contracts/README.md | 2 +- developers/contracts/meta-peg-out-endpoint.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/SUMMARY.md b/SUMMARY.md index 6caa3dd..6295219 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -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.md) + * [meta peg-out endpoint](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) diff --git a/developers/contracts/README.md b/developers/contracts/README.md index c1bca58..e191255 100644 --- a/developers/contracts/README.md +++ b/developers/contracts/README.md @@ -49,7 +49,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` +- Contract name: `meta-peg-out-endpoint` - [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. diff --git a/developers/contracts/meta-peg-out-endpoint.md b/developers/contracts/meta-peg-out-endpoint.md index 310c6fc..a84359e 100644 --- a/developers/contracts/meta-peg-out-endpoint.md +++ b/developers/contracts/meta-peg-out-endpoint.md @@ -1,6 +1,6 @@ # meta-peg-out-endpoint -- Location: `xlink/packages/contracts/bridge-stacks/contracts/meta-peg-out-endpoint-v2-04` +- Location: `xlink/packages/contracts/bridge-stacks/contracts` - [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. From 9f52781e51d6aaa404dc642e9b13f93fb95c963f Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Fri, 7 Feb 2025 18:18:59 -0300 Subject: [PATCH 2/3] meta-peg-out: @tenuki review --- developers/contracts/meta-peg-out-endpoint.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/developers/contracts/meta-peg-out-endpoint.md b/developers/contracts/meta-peg-out-endpoint.md index a84359e..639e0e5 100644 --- a/developers/contracts/meta-peg-out-endpoint.md +++ b/developers/contracts/meta-peg-out-endpoint.md @@ -3,7 +3,7 @@ - Location: `xlink/packages/contracts/bridge-stacks/contracts` - [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. +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 chain. 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. @@ -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. 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. +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 (token-abtc) within the Stacks network, the actual transaction on the burn-chain (Bitcoin) still requires BTC to cover mining fees. 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 @@ -33,17 +33,17 @@ This variable represents the address to which fees are paid. In this contract, t | ------ | ----- | | `uint` | [`burn-block-height`](https://docs.stacks.co/reference/keywords#burn-block-height) | -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. +This constant specifies the block height of the underlying burn chain 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 -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. +The peg-out is a multi-step process comprising several phases to ensure secure and orderly transactions. The process begins with a peg-out request to initiate the transfer of tokens out of the Stacks network. Configured grace periods then allow users to either revoke their request or claim it. Once a peg-out request is claimed, the final step is to finalize the peg-out, executing the transfer and updating the relevant records. +Each of these steps is implemented through dedicated contract functions, which are explained in detail below. #### `request-peg-out` ###### _(in contract meta-peg-out-endpoint-v2-04)_ -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. +In this first step, the `tx-sender` requests a peg-out a specified amount of previously bridged tokens. 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, several validations must be met: @@ -85,7 +85,7 @@ 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 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. +Finalizing a peg-out is the final step in committing the process. This function takes in the burn chain (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. @@ -98,7 +98,7 @@ The procedure is as follows, based on who finalizes it: 1) Peg-In 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). + - 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 tokens requested for the peg-out operation and the gas fee are transferred from the contract to the claimer, so the overall involved token supply remains unaffected. @@ -134,7 +134,7 @@ In certain scenarios, a requested peg-out may need to be revoked, allowing users Key validations include: -- The grace period must have elapsed. +- The request must be revoked within the grace period before it expires. - 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`. @@ -217,7 +217,7 @@ This contract feature allows for specifying the address to which peg-out fees (d * `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). +* `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 chain base-coin (BTC). ## Errors From b5f621649303a9e316f2139002de5a9349d8ce42 Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Mon, 10 Feb 2025 12:11:22 -0300 Subject: [PATCH 3/3] btc-peg-in: @tenuki review --- developers/contracts/btc-peg-in-endpoint.md | 8 ++++---- developers/contracts/meta-peg-out-endpoint.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/developers/contracts/btc-peg-in-endpoint.md b/developers/contracts/btc-peg-in-endpoint.md index ec73ae2..7e7cd5b 100644 --- a/developers/contracts/btc-peg-in-endpoint.md +++ b/developers/contracts/btc-peg-in-endpoint.md @@ -1,18 +1,18 @@ # btc-peg-in-endpoint - Location: `xlink/packages/contracts/bridge-stacks/contracts` -- [Deployed contract]() +- Deployed contracts: [btc-peg-in-endpoint-v2-05](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.btc-peg-in-endpoint-v2-05?chain=mainnet), [btc-peg-in-endpoint-v2-05-lisa](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.btc-peg-in-endpoint-v2-05-lisa?chain=mainnet), [btc-peg-in-v2-05-launchpad](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.btc-peg-in-v2-05-launchpad?chain=mainnet), [btc-peg-in-v2-07-swap](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.btc-peg-in-v2-07-swap?chain=mainnet). -This technical document provides a detailed overview of the contract responsible for managing the peg-in process, enabling the transfer of BTC from the Bitcoin network to the Stacks network. In this process, BTC is represented as bridged tokens on Stacks (aBTC). The module's core functionality is implemented through a series of public functions distributed across three specialized contracts. Each contract addresses specific aspects of the BTC peg-in process. +This technical document provides a detailed overview of the contracts responsible for managing the peg-in process, enabling the transfer of BTC from the Bitcoin network to the Stacks network. In this process, BTC is represented as bridged tokens on Stacks (aBTC). The module's core functionality is implemented through a series of public functions distributed across three specialized contracts. Each contract addresses specific aspects of the BTC peg-in process. This functionality is implemented and distributed across the following contracts: - `btc-peg-in-endpoint-v2-05`: handles bridging BTC into the Stacks network, leveraging cross-router to manage the routing of BTC to the appropriate destination. - `btc-peg-in-endpoint-v2-05-lisa`: extends Bitcoin peg-in operations by converting BTC into LiaBTC through intermediate bridging steps, ultimately enabling the issuance of BRC-20 tokens on Bitcoin. -- `btc-peg-in-v2-05-launchpad`: facilitates BTC peg-ins specifically for participation in launchpad projects on Stacks by minting bridged tokens and transferring them to the launchpad contract for project-related activities. +- `btc-peg-in-v2-05-launchpad`: facilitates BTC peg-ins specifically for participation in launchpad projects on Stacks. - `btc-peg-in-v2-07-swap`: enables the bridging of BTC into the Stacks network while enabling token swaps to convert BTC into other predefined assets during the process. - ## Storage +###### _(all contracts include the following variables unless otherwise specified)_ ### `fee-to-address` | Data | Type | diff --git a/developers/contracts/meta-peg-out-endpoint.md b/developers/contracts/meta-peg-out-endpoint.md index 639e0e5..90c0f66 100644 --- a/developers/contracts/meta-peg-out-endpoint.md +++ b/developers/contracts/meta-peg-out-endpoint.md @@ -1,7 +1,7 @@ # meta-peg-out-endpoint - Location: `xlink/packages/contracts/bridge-stacks/contracts` -- [Deployed contract]() +- [Deployed contract](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.meta-peg-out-endpoint-v2-04?chain=mainnet) 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 chain. 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. @@ -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. The first ones are charged in the same token being bridged, while gas fees are handled using the Bridged BTC token (token-abtc) within the Stacks network, the actual transaction on the burn-chain (Bitcoin) still requires BTC to cover mining fees. 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. +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