From 24ce550a1423ddf8c07052c0d202f409befc94f2 Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Thu, 23 Jan 2025 16:58:37 -0300 Subject: [PATCH 1/7] update of the btc-peg-in technical documentation --- SUMMARY.md | 2 +- developers/contracts/README.md | 4 +- .../contracts/btc-peg-in-endpoint-v2-03.md | 195 -------------- developers/contracts/btc-peg-in-endpoint.md | 239 ++++++++++++++++++ 4 files changed, 242 insertions(+), 198 deletions(-) delete mode 100644 developers/contracts/btc-peg-in-endpoint-v2-03.md create mode 100644 developers/contracts/btc-peg-in-endpoint.md diff --git a/SUMMARY.md b/SUMMARY.md index c352cdf..3fc6309 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -26,7 +26,7 @@ ## 🎮 Developers * [Smart Contracts](developers/contracts/README.md) - * [btc peg-in endpoint v2-03](developers/contracts/btc-peg-in-endpoint-v2-03.md) + * [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) diff --git a/developers/contracts/README.md b/developers/contracts/README.md index 8265edc..0984950 100644 --- a/developers/contracts/README.md +++ b/developers/contracts/README.md @@ -20,8 +20,8 @@ The XLink ecosystem offers three main features that are implemented along differ #### BTC Peg-In Endpoint -- Contract name: `btc-peg-in-endpoint-v2-03` -- [Complete technical documentation](btc-peg-in-endpoint-v2-03.md) +- Contract name: `btc-peg-in-endpoint` +- [Complete technical documentation](btc-peg-in-endpoint.md) This endpoint is responsible for managing the bridging of BTC from Bitcoin chain into Stacks chain as bridged BTC (aBTC). diff --git a/developers/contracts/btc-peg-in-endpoint-v2-03.md b/developers/contracts/btc-peg-in-endpoint-v2-03.md deleted file mode 100644 index c8fbaad..0000000 --- a/developers/contracts/btc-peg-in-endpoint-v2-03.md +++ /dev/null @@ -1,195 +0,0 @@ -# btc-peg-in-endpoint-v2-03.clar - -- Location: `xlink/packages/contracts/bridge-stacks/contracts/btc-peg-in-endpoint-v2-03.clar` -- [Deployed contract]() - -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 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-in operations are transferred. By default, this address is set to the executor-dao responsible for governance. - -### `peg-in-paused` -| Data | Type | -| -------- | ------ | -| Variable | `bool` | - -A flag that indicates whether the peg-in process is active. If set to true, all peg-in operations are paused, preventing any new transactions. The contract is deployed in a paused state by default. - -### `peg-in-fee` -| Data | Type | -| -------- | ------ | -| Variable | `uint` | - -The percentage fee charged for peg-in transactions. By default, this value is `u0`. - -### `peg-in-min-fee` -| Data | Type | -| -------- | ------ | -| Variable | `uint` | - -The minimum fee required for a peg-in transaction, regardless of the transaction amount. For each transaction, the fee is determined by taking the maximum value between the specified fee amount and the `peg-in-min-fee`. By default, this value is `u0`. - -## Features - -### Peg-in features - -#### `finalize-peg-in-0` -This function manages the basic peg-in process for transferring BTC to Stacks. It validates the provided Bitcoin transaction using a proof that confirms it has been mined and calculates the appropriate fees for the operation. The function verifies that the transaction meets the necessary conditions, including checking that the peg-in address is approved, before finalizing it by registering it in the `.btc-bridge-registry-v2-02` contract. Finally, it mints bridged BTC tokens for the recipient address specified in the Bitcoin transaction, processes fees, and logs the transaction details. - -##### Parameters -```lisp -(tx (buff 32768)) -(block { header: (buff 80), height: uint }) -(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) -(output-idx uint) -(order-idx uint) -``` - -#### `finalize-peg-in-cross` -Building upon the checks performed in `finalize-peg-in-0`, this function extends the peg-in process to support cross-chain routing. After validating the Bitcoin transaction, it performs additional checks involving a "reveal transaction", which specifies the token and chain-id for the destination chain. The function calculates fees and verifies the token trait of the assets being transferred against the `.btc-bridge-registry-v2-02` contract to ensure it is approved and registers the transaction status. Once validated, the function mints bridged BTC tokens and sends them to the recipient specified in the transaction details via the `.cross-router-v2-02 contract`. - -##### Parameters -```lisp -(tx (buff 32768)) -(block { header: (buff 80), height: uint }) -(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) -(output-idx uint) -(reveal-tx { tx: (buff 32768), order-idx: uint }) -(token-trait ) -``` - -#### `finalize-peg-in-cross-swap` -This function builds on `finalize-peg-in-cross` by adding token swapping capabilities during the peg-in process. In addition to the verifications performed in `finalize-peg-in-cross`, it ensures that routing configurations (e.g., minimum output amounts, token paths) are valid and meets all conditions. It interacts with `.btc-bridge-registry-v2-02` contract to register transaction statuses, uses `.cross-router-v2-02` to handle the cross operation, and to perform token swaps through the `.amm-pool-v2-01` contract. The function mints bridged BTC tokens and swaps them according to routing instructions. - -##### Parameters -```lisp -(tx (buff 32768)) -(block { header: (buff 80), height: uint }) -(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) -(output-idx uint) -(reveal-tx { tx: (buff 32768), order-idx: uint }) -(routing-traits (list 5 )) -``` - -#### `finalize-peg-in-launchpad` -This function is tailored for peg-ins associated with launchpad projects on Stacks. It uses `.btc-bridge-registry-v2-02` to validate and register transaction details while ensuring compatibility with the project’s parameters. These parameters include fields such as `user`, `launch-id`, and `payment-token-trait`, which define the specifics of the launchpad operation. -The function first mints bridged BTC tokens for the user and then registers the operation in the `.alex-launchpad-v2-01` contract. This registration involves transferring the minted bridged tokens assets to the launchpad contract on behalf of the user, where they are associated with the launchpad project. -In case of any error, it invokes the internal [refund](btc-peg-in-endpoint-v2-03.md#relevant-internal-functions) function and logs the issue. - -##### Parameters -```lisp -(tx (buff 32768)) -(block { header: (buff 80), height: uint }) -(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) -(output-idx uint) -(order-idx 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-in-paused` -A read-only function that checks the operational status of the contract. - -#### `pause-peg-in` -A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status. - -##### Parameters -```lisp -(paused bool) -``` - -#### `set-fee-to-address` -This feature establishes the address where the fees collected from peg-in operations are transferred. - -##### Parameters -```lisp -(new-fee-to-address principal) -``` - -#### `set-peg-in-fee` -This feature sets the fee for the peg-in operation as a percentage of the transaction amount to be deducted. - -##### Parameters -```lisp -(fee uint) -``` - -#### `set-peg-in-min-fee` -This feature establishes the minimum fee required for a peg-in transaction. - -##### Parameters -```lisp -(fee uint) -``` - -### Supporting features -The following functions are tools to assist the off-chain activities. -1. Construct and destruct helpers (`destruct-principal`, `construct-principal`). -2. Order creation helpers (`create-order-0-or-fail`, `create-order-cross-or-fail`, `create-order-cross-swap-or-fail`, `create-order-launchpad-or-fail`). -3. Decoding helpers (`decode-order-cross-from-reveal-tx-or-fail`, `decode-order-cross-swap-from-reveal-tx-or-fail`). - - -### Relevant internal functions -- `refund` - - -### Getters - -#### `get-peg-in-fee` -#### `get-peg-in-min-fee` -#### `get-fee-to-address` -#### `get-peg-in-sent-or-default` -##### Parameters -```lisp -(tx (buff 32768)) -(output uint) -``` -#### `get-approved-wrapped-or-default` -Checks if the given token is approved as a wrapped token by consulting the `approved-wrapped` map in the `.btc-bridge-registry-v2-02` contract. If the token is not found in the map, it returns false as the default value. -##### Parameters -```lisp -(token principal) -``` -#### `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-02` This contract is called to validate peg-in addresses, check and set transaction statuses, and order details during peg-in operations. -- `bridge-common-v2-02` This contract is called to extract and validate Bitcoin transaction details, decode routing and order information during peg-in operations. -- `token-abtc` This contract handles the management of aBTC (Bridged BTC) tokens, representing BTC on the Stacks network. It is called to mint and transfer aBTC during peg-in operations. -- `cross-router-v2-02` This contract is called to route tokens and execute cross-chain transfers during advanced peg-in operations, such as cross and cross-swap transactions. -- `alex-launchpad-v2-01` This contract is called to register and validate peg-in operations associated with launchpad projects on the Stacks network. -- `clarity-bitcoin-v1-07` This contract is called to retrieve the transaction ID of native SegWit Bitcoin transactions by excluding witness data. -- `btc-peg-out-endpoint-v2-01` This contract is called to manage refunds during peg-in failures to transfer BTC back to users. - -## 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-invalid-tx` | `(err u1004)` | -| `err-already-sent` | `(err u1005)` | -| `err-bitcoin-tx-not-mined` | `(err u1011)` | -| `err-invalid-input` | `(err u1012)` | -| `err-token-mismatch` | `(err u1015)` | -| `err-slippage` | `(err u1016)` | -| `err-not-in-whitelist` | `(err u1017)` | -| `err-invalid-routing` | `(err u1018)` | -| `err-commit-tx-mismatch` | `(err u1019)` | -| `err-invalid-token` | `(err u1020)` | - - \ No newline at end of file diff --git a/developers/contracts/btc-peg-in-endpoint.md b/developers/contracts/btc-peg-in-endpoint.md new file mode 100644 index 0000000..5b6e856 --- /dev/null +++ b/developers/contracts/btc-peg-in-endpoint.md @@ -0,0 +1,239 @@ +# btc-peg-in-endpoint +- Location: `xlink/packages/contracts/bridge-stacks/contracts` +- [Deployed contract]() + +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 functionality is implemented and distributed across the following contracts: + +- `btc-peg-in-endpoint-v2-05`: responsible for the `finalize-peg-in-cross` function. +- `btc-peg-in-endpoint-v2-05-lisa`: responsible for the `finalize-peg-in-mint-liabtc` function. +- `btc-peg-in-v2-07-swap`: responsible for the `finalize-peg-in-cross-swap` function. + +## Storage +### `fee-to-address` + +| Data | Type | +| -------- | ------ | +| Variable | `principal` | + +The address where the fees collected from peg-in operations are transferred. By default, this address is set to the executor-dao responsible for governance. + +### `peg-in-paused` + +| Data | Type | +| -------- | ------ | +| Variable | `bool` | + +A flag that indicates whether the peg-in process is paused. If set to `true`, all peg-in operations are suspended, preventing any new transactions. The contract is deployed in a paused state by default. + +### `peg-in-fee` + +| Data | Type | +| -------- | ------ | +| Variable | `uint` | + +The percentage fee charged for peg-in transactions. By default, this value is `0`. + +### `peg-in-min-fee` + +| Data | Type | +| -------- | ------ | +| Variable | `uint` | + +The minimum fee required for a peg-in transaction, regardless of the transaction amount. For each transaction, the fee is the maximum value between the calculated fee amount and the `peg-in-min-fee`. By default, this value is `0`. + +### `btc-peg-outfee` +###### _(only present in btc-peg-in-v2-07-swap)_ + +| Data | Type | +| -------- | ------ | +| Variable | `uint` | + +This variable represents the percentage fee applied to BTC peg-out operations during cross-swap transactions, where BTC is swapped and routed across chains to reach the final recipient. By default, it is initialized to `0` and can be updated via governance functions. + +### `btc-peg-out-min-fee` +###### _(only present in btc-peg-in-v2-07-swap)_ + +| Data | Type | +| -------- | ------ | +| Variable | `uint` | + +This variable sets the minimum fee required for BTC peg-out operations during cross-swap transactions. By default, it is initialized to `0`. + +## Features + +#### `finalize-peg-in-cross` +###### _(in contract btc-peg-in-endpoint-v2-05)_ +This function manages the peg-in process for transferring BTC to Stacks with support for cross-chain routing. It validates the provided Bitcoin transaction (which represents the transfer of BTC to a peg-in address on the Bitcoin network), ensuring it has been mined and meets the necessary conditions including an approved peg-in address. The function also performs additional checks involving a "reveal transaction," which specifies the token and chain-id for the destination chain. +Once the transaction is validated, the function calculates fees, verifies that the asset being transferred is approved for bridging operations in the `.btc-bridge-registry-v2-01` contract, and registers the transaction status. Once validated, the function mints bridged BTC tokens and sends them to the recipient specified in the transaction details via the `.cross-router-v2-03 contract`. If the validation or routing fails, a refund is executed. + +##### Parameters +```lisp +(tx (buff 32768)) +(block { header: (buff 80), height: uint }) +(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) +(output-idx uint) +(reveal-tx { tx: (buff 32768), order-idx: uint }) +(reveal-block { header: (buff 80), height: uint }) +(reveal-proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) +(token-out-trait ) +``` + +#### `finalize-peg-in-cross-swap` +###### _(in contract btc-peg-in-v2-07-swap)_ +This function mints bridged BTC tokens and swaps them according to routing instructions. Building upon the functionality of `finalize-peg-in-cross`, it adds token swapping capabilities during the peg-in process. In addition to the verifications performed in `finalize-peg-in-cross`, it ensures that routing configurations (e.g., minimum output amounts or token paths) are valid and meet the required conditions. +During the process, the function temporarily modifies the `peg-out-fee` and `peg-out-min-fee` values within the `btc-peg-out-endpoint-v2-01` contract. These adjustments allow the transaction to apply specific fee values during the routing and swap operations. Once the process is completed, the original values are restored. +It interacts with `.btc-bridge-registry-v2-01` contract to register transaction statuses. It also uses the `.cross-router-v2-03` to handle the cross operation and to perform token swaps through the `.amm-pool-v2-01` contract. The function mints bridged BTC tokens and swaps them according to routing instructions. + +##### Parameters +```lisp +(tx (buff 32768)) +(block { header: (buff 80), height: uint }) +(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) +(output-idx uint) +(reveal-tx { tx: (buff 32768), order-idx: uint }) +(routing-traits (list 5 )) +(token-out-trait ) +``` + +#### `finalize-peg-in-mint-liabtc` +###### _(in contract btc-peg-in-endpoint-v2-05-lisa)_ +The main purpose of this function is to convert BTC into LiaBTC, with the ultimate goal of issuing it as a BRC-20 token in Bitcoin. To achieve this, the function goes through an intermediate bridging step: after locking the desired amount of BTC on the Bitcoin network, it converts it into aBTC within the Stacks ecosystem. The aBTC is then wrapped into `wvLiaBTC`, a tokenized form of LiaBTC within Stacks. +Once the conversion is complete, the function initiates a peg-out operation using the `.meta-peg-out-endpoint-v2-04` contract. This step bridges the `wvLiaBTC` back to Bitcoin and issues it as BRC-20 tokens, sending it to a specific inscription address provided in the order. The function verifies both the validation of the Bitcoin transaction and the fulfillment of all LiaBTC minting conditions. +It also registers the peg-in transaction in the `.btc-bridge-registry-v2-01` contract. In case of any error, the refund mechanism is triggered to return the corresponding funds to the sender. + +##### Parameters +```lisp +(tx (buff 32768)) +(block { header: (buff 80), height: uint }) +(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) +(output-idx uint) +(order-idx uint) +(message { token: principal, accrued-rewards: uint, update-block: uint }) +(signature-packs (list 100 + { signer: principal, + message-hash: (buff 32), + signature: (buff 65) + })) +``` + +### 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-in-paused` +A read-only function that checks the operational status of the contract. + +#### `pause-peg-in` +A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status. + +##### Parameters +```lisp +(paused bool) +``` + +#### `set-fee-to-address` +This feature establishes the address to which the fees collected from peg-in operations are transferred. + +##### Parameters +```lisp +(new-fee-to-address principal) +``` + +#### `set-peg-in-fee` +This feature sets the fee for the peg-in operation as a percentage of the transaction amount. + +##### Parameters +```lisp +(fee uint) +``` + +#### `set-peg-in-min-fee` +This feature allows to set the minimum fee required for a peg-in transaction. + +##### Parameters +```lisp +(fee uint) +``` + +#### `set-btc-peg-out-fee` +###### _(only present in btc-peg-in-v2-07-swap)_ +This feature sets the percentage fee applied to BTC peg-out operations. + +##### Parameters +```lisp +(fee uint) +``` + +#### `set-btc-peg-out-min-fee` +###### _(only present in btc-peg-in-v2-07-swap)_ +This feature establishes the minimum fee required for BTC peg-out operations. + +##### Parameters +```lisp +(fee uint) +``` + +### Supporting features +The following functions are tools to assist the off-chain activities. +1. Construct and destruct helpers (`destruct-principal`, `construct-principal`). +2. Order creation helpers (`create-order-cross-or-fail`, `create-order-cross-swap-or-fail`, `create-order-mint-liabtc-or-fail`). +3. Decoding helpers (`decode-order-cross-from-reveal-tx-or-fail`, `decode-order-cross-swap-from-reveal-tx-or-fail`). + + +### Relevant internal functions +- `refund`: this function returns the total amount of the peg-in transaction, including the fee, to the sender in case of a failure during the operation. + +### Getters + +#### `get-peg-in-fee` +#### `get-peg-in-min-fee` +#### `get-fee-to-address` +#### `get-peg-in-sent-or-default` +##### Parameters +```lisp +(tx (buff 32768)) +(output uint) +``` +#### `get-txid` +##### Parameters +```lisp +(tx (buff 32768)) +``` +#### `get-btc-peg-out-fee` _(only present in btc-peg-in-v2-07-swap)_ +#### `get-btc-peg-out-min-fee` _(only present in btc-peg-in-v2-07-swap)_ +#### `get-liabtc-decimals` _(only present in btc-peg-in-endpoint-v2-05-lisa)_ + +## 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 validate peg-in addresses, check and set transaction statuses, and order details during peg-in operations. +- `bridge-common-v2-02`: this contract is called to extract and validate Bitcoin transaction details, decode routing and order information during peg-in operations. +- `token-abtc`: this contract handles the management of aBTC (Bridged BTC) tokens, representing BTC on the Stacks network. It is called to mint and transfer aBTC during peg-in operations. +- `cross-router-v2-03`: this contract is called to route tokens and execute cross-chain transfers during advanced peg-in operations, such as cross and cross-swap transactions. +- `clarity-bitcoin-v1-07`: this contract is called to retrieve the transaction ID of native SegWit Bitcoin transactions by excluding witness data. +- `btc-peg-out-endpoint-v2-01`: this contract is called to manage refunds during peg-in failures to transfer BTC back to users. +- `liabtc-mint-endpoint`: this contract is called to validate and mint liabtc during peg-in operations. +- `token-wvliabtc`: this contract handles the management of wvliabtc tokens, the wrapped representation of liabtc on the Stacks network. It is called to mint and manage wvliabtc during peg-in operations. +- `meta-peg-out-endpoint-v2-04`: this contract is called to bridge wvLiaBTC from the Stacks network to Bitcoin as a BRC-20 token, transferring it to a specified address. + +## 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-invalid-tx` | `(err u1004)` | +| `err-already-sent` | `(err u1005)` | +| `err-bitcoin-tx-not-mined` | `(err u1011)` | +| `err-invalid-input` | `(err u1012)` | +| `err-token-mismatch` | `(err u1015)` | +| `err-slippage` | `(err u1016)` | +| `err-not-in-whitelist` | `(err u1017)` | +| `err-invalid-routing` | `(err u1018)` | +| `err-commit-tx-mismatch` | `(err u1019)` | +| `err-invalid-token` | `(err u1020)` | + + \ No newline at end of file From 82b16e0c0ff37ae0e5fdf31cf8946c79c04f533d Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Thu, 23 Jan 2025 17:04:06 -0300 Subject: [PATCH 2/7] update of the meta-peg-out technical documentation --- SUMMARY.md | 2 +- developers/contracts/README.md | 2 +- ...oint-v2-03.md => meta-peg-out-endpoint.md} | 61 ++++++++++--------- 3 files changed, 34 insertions(+), 31 deletions(-) rename developers/contracts/{meta-peg-out-endpoint-v2-03.md => meta-peg-out-endpoint.md} (61%) diff --git a/SUMMARY.md b/SUMMARY.md index 3fc6309..6caa3dd 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-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) diff --git a/developers/contracts/README.md b/developers/contracts/README.md index 0984950..c1bca58 100644 --- a/developers/contracts/README.md +++ b/developers/contracts/README.md @@ -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. diff --git a/developers/contracts/meta-peg-out-endpoint-v2-03.md b/developers/contracts/meta-peg-out-endpoint.md similarity index 61% rename from developers/contracts/meta-peg-out-endpoint-v2-03.md rename to developers/contracts/meta-peg-out-endpoint.md index e9611ed..3c23594 100644 --- a/developers/contracts/meta-peg-out-endpoint-v2-03.md +++ b/developers/contracts/meta-peg-out-endpoint.md @@ -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 From faa924da6c261d8177770d5201ac1b164d50ec03 Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Fri, 24 Jan 2025 14:51:14 -0300 Subject: [PATCH 3/7] minor fixes --- developers/contracts/meta-peg-out-endpoint.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developers/contracts/meta-peg-out-endpoint.md b/developers/contracts/meta-peg-out-endpoint.md index 3c23594..310c6fc 100644 --- a/developers/contracts/meta-peg-out-endpoint.md +++ b/developers/contracts/meta-peg-out-endpoint.md @@ -31,7 +31,7 @@ This variable represents the address to which fees are paid. In this contract, t | Type | Value | | ------ | ----- | -| `constant` | `burn-block-height` | +| `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. @@ -101,7 +101,7 @@ The procedure is as follows, based on who finalizes it: - 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 balance remains unaffected. + - 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. - 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. From 60dff0fad55329b3366c734450b59ed67c873c7f Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Tue, 28 Jan 2025 11:21:10 -0300 Subject: [PATCH 4/7] btc-peg-in: added missing feature --- developers/contracts/btc-peg-in-endpoint.md | 26 +++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/developers/contracts/btc-peg-in-endpoint.md b/developers/contracts/btc-peg-in-endpoint.md index 5b6e856..ec73ae2 100644 --- a/developers/contracts/btc-peg-in-endpoint.md +++ b/developers/contracts/btc-peg-in-endpoint.md @@ -6,9 +6,11 @@ This technical document provides a detailed overview of the contract responsible This functionality is implemented and distributed across the following contracts: -- `btc-peg-in-endpoint-v2-05`: responsible for the `finalize-peg-in-cross` function. -- `btc-peg-in-endpoint-v2-05-lisa`: responsible for the `finalize-peg-in-mint-liabtc` function. -- `btc-peg-in-v2-07-swap`: responsible for the `finalize-peg-in-cross-swap` function. +- `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-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 ### `fee-to-address` @@ -118,6 +120,21 @@ It also registers the peg-in transaction in the `.btc-bridge-registry-v2-01` con })) ``` +### `finalize-peg-in-launchpad` +###### _(in contract btc-peg-in-v2-05-launchpad)_ +This function is tailored for peg-ins associated with launchpad projects on Stacks. It uses `.btc-bridge-registry-v2-01` to validate and register transaction details while ensuring compatibility with the project’s parameters. These parameters include fields such as `user`, `launch-id`, and `payment-token-trait`, which define the specifics of the launchpad operation. +The function first mints bridged BTC tokens for the user and then registers the operation in the `.alex-launchpad-v2-03` contract. This registration involves transferring the minted bridged tokens assets to the launchpad contract on behalf of the user, where they are associated with the launchpad project. +In case of any error, it invokes the internal [refund](btc-peg-in-endpoint.md#relevant-internal-functions) function and logs the issue. + +##### Parameters +```lisp +(tx (buff 32768)) +(block { header: (buff 80), height: uint }) +(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint }) +(output-idx uint) +(order-idx 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. @@ -178,7 +195,7 @@ This feature establishes the minimum fee required for BTC peg-out operations. ### Supporting features The following functions are tools to assist the off-chain activities. 1. Construct and destruct helpers (`destruct-principal`, `construct-principal`). -2. Order creation helpers (`create-order-cross-or-fail`, `create-order-cross-swap-or-fail`, `create-order-mint-liabtc-or-fail`). +2. Order creation helpers (`create-order-cross-or-fail`, `create-order-cross-swap-or-fail`, `create-order-mint-liabtc-or-fail`, `create-order-launchpad-or-fail`). 3. Decoding helpers (`decode-order-cross-from-reveal-tx-or-fail`, `decode-order-cross-swap-from-reveal-tx-or-fail`). @@ -211,6 +228,7 @@ The following functions are tools to assist the off-chain activities. - `bridge-common-v2-02`: this contract is called to extract and validate Bitcoin transaction details, decode routing and order information during peg-in operations. - `token-abtc`: this contract handles the management of aBTC (Bridged BTC) tokens, representing BTC on the Stacks network. It is called to mint and transfer aBTC during peg-in operations. - `cross-router-v2-03`: this contract is called to route tokens and execute cross-chain transfers during advanced peg-in operations, such as cross and cross-swap transactions. +- `alex-launchpad-v2-03`: this contract is called to register and validate peg-in operations associated with launchpad projects on the Stacks network. - `clarity-bitcoin-v1-07`: this contract is called to retrieve the transaction ID of native SegWit Bitcoin transactions by excluding witness data. - `btc-peg-out-endpoint-v2-01`: this contract is called to manage refunds during peg-in failures to transfer BTC back to users. - `liabtc-mint-endpoint`: this contract is called to validate and mint liabtc during peg-in operations. 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 5/7] 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 6/7] 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 7/7] 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