From 0b68939f5bee240a120b6e0958b6812a907aafb6 Mon Sep 17 00:00:00 2001 From: maquirriaincf Date: Mon, 24 Feb 2025 22:53:16 -0300 Subject: [PATCH 1/6] added btc peg in agg documentation --- developers/contracts/btc-peg-in-endpoint.md | 31 +++++++++++++++++---- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/developers/contracts/btc-peg-in-endpoint.md b/developers/contracts/btc-peg-in-endpoint.md index 7e7cd5b..4c866db 100644 --- a/developers/contracts/btc-peg-in-endpoint.md +++ b/developers/contracts/btc-peg-in-endpoint.md @@ -1,6 +1,6 @@ # btc-peg-in-endpoint - Location: `xlink/packages/contracts/bridge-stacks/contracts` -- 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). +- 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), [btc-peg-in-v2-07a-agg](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.btc-peg-in-v2-07a-agg?chain=mainnet) 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. @@ -10,6 +10,7 @@ This functionality is implemented and distributed across the following contracts - `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. - `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. +- `btc-peg-in-v2-07a-agg`: extends Bitcoin peg-in operations by routing token swaps to non-ALEX liquidity aggregators, which optimize token exchanges by accessing multiple liquidity sources. This allows ALEX to execute swaps even when there are no ALEX pools for a specific token pair. ## Storage ###### _(all contracts include the following variables unless otherwise specified)_ @@ -46,7 +47,7 @@ The percentage fee charged for peg-in transactions. By default, this value is `0 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)_ +###### _(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)_ | Data | Type | | -------- | ------ | @@ -55,7 +56,7 @@ The minimum fee required for a peg-in transaction, regardless of the transaction 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)_ +###### _(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)_ | Data | Type | | -------- | ------ | @@ -135,6 +136,25 @@ In case of any error, it invokes the internal [refund](btc-peg-in-endpoint.md#re (order-idx uint) ``` +### `finalize-peg-in-agg` + +###### _(in contract btc-peg-in-v2-07a-agg)_ + +This function facilitates a BTC peg-in operation designed for aggregated cross-chain routing. Unlike standard peg-in processes where users receive aBTC directly on Stacks, this function integrates a routing mechanism that forwards the bridged tokens for immediate cross-chain processing. +The process begins by verifying that the provided Bitcoin transaction has been mined and meets all peg-in validation criteria. It checks that the peg-in address is approved and calculates the required transaction fees. Once validated, the function mints aBTC for the net amount (after deducting fees) and registers the peg-in transaction in the `.btc-bridge-registry-v2-01 contract`. +Instead of keeping the minted aBTC within the Stacks ecosystem, this function directly transfers it to the `.cross-peg-out-v2-01-agg contract`. This interaction enables automated routing and potential asset swaps to facilitate seamless movement of assets across blockchains. The function logs transaction details and ensures that any failure in the process triggers a refund mechanism. + +##### 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 }) +``` + ### 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. @@ -195,8 +215,8 @@ 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`, `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`). +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`, `create-order-agg-or-fail`). +3. Decoding helpers (`decode-order-cross-from-reveal-tx-or-fail`, `decode-order-cross-swap-from-reveal-tx-or-fail`, `decode-order-agg-or-fail`, `decode-order-agg-from-reveal-tx-or-fail`). ### Relevant internal functions @@ -234,6 +254,7 @@ The following functions are tools to assist the off-chain activities. - `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. +- `cross-peg-out-v2-01-agg`: this contract is called to finalize the transaction by preparing the swap to be executed in an EVM-compatible blockchain. ## Errors From 94d07a76a35945de23b4399fbe238c382307cc51 Mon Sep 17 00:00:00 2001 From: maquirriaincf Date: Mon, 24 Feb 2025 23:58:41 -0300 Subject: [PATCH 2/6] added cross peg out agg and BridgeEndpointWithSwap documentations --- .../contracts/BridgeEndpointWithSwap.md | 118 ++++++++++++++++++ developers/contracts/btc-peg-in-endpoint.md | 2 +- .../contracts/cross-peg-out-endpoint.md | 42 ++++++- 3 files changed, 157 insertions(+), 5 deletions(-) create mode 100644 developers/contracts/BridgeEndpointWithSwap.md diff --git a/developers/contracts/BridgeEndpointWithSwap.md b/developers/contracts/BridgeEndpointWithSwap.md new file mode 100644 index 0000000..3f2103e --- /dev/null +++ b/developers/contracts/BridgeEndpointWithSwap.md @@ -0,0 +1,118 @@ +# BridgeEndpointWithSwap.sol + +- Location: `packages/contracts/bridge-solidity/contracts/BridgeEndpointWithSwap.sol` +- [Deployed contract]() + +This technical document provides a detailed overview of the contract responsible for transferring a swap between two tokens to **IceCreamSwap**, a non-ALEX liquidity aggregator. The contract burns or transfers the base tokens and sends the necessary information to complete the swap to IceCreamSwap. The main logic is implemented in the `transferToSwap` function. Lets review its core functionality. + +## Storage + +### `_owner` +| Data | Type | +| -------- | ------ | +| Variable | `address` | + +This address corresponds to the owner of the contract. + +### `name` +| Data | Type | +| -------- | ------ | +| Variable | `string memory` | + +This variable stores the name of the contract. + +### `version` +| Data | Type | +| -------- | ------ | +| Variable | `string memory` | + +This variable stores the version of the contract that is deployed. + +### `_registry` +| Data | Type | +| -------- | ------ | +| Variable | `address` | + +This address corresponds to the `cross-bridge-registry-v2-01` contract, that stores information on all transactions. + +### `_pegInAddress` +| Data | Type | +| -------- | ------ | +| Variable | `address` | + +This parameter represents the address of the peg-in contract. + +### `_timeLock` +| Data | Type | +| -------- | ------ | +| Variable | `address` | + +This variable stores the address of the time lock contract. + +## Features + +### Swap Features + +#### `transferToSwap` + +This function implements the main logic to swap tokens through the bridge endpoint. calculates the `orderHash` taking `salt` as one of the parameters for the calculation. It also validates the order. It calculates `amountOut`, which seems like the amount sent out after the transfer. it either burns `tokenOut` or transfers using `pegInAddress`. It emits two events: `TransferToSwapEvent` and `SendMessageWithTokenEvent`. If unsuccessful, it burns `tokenIn`. + +##### Parameters +```solidity +( + address target, + address tokenIn, + address tokenOut, + uint256 amountIn, + uint256 amountOutMin, + bytes calldata swapPayload, + bytes calldata bridgePayload, + bytes32 salt, + SignaturePackage[] calldata proofs +) +``` + +### Governance Features + +#### `setTimeLock` +This function is called in the constructor of the contract to ensure that _timeLock is set to the appropriate value. + +##### Parameters +```solidity +(_timeLock) +``` + +## Events + +#### `TransferToSwapEvent` +This event is emitted when a token swap is performed within the bridge endpoint. `tokenIn` represents the base token in the swap, whereas `tokenOut` represents the token it is being bridged to. `amountIn` and `amountOut` correspond to the amount of each token. The `swapPayload` parameter is a data payload that is necessary for the swap to execute. `success` indicates whether the swap could be performed or not. + +##### Parameters +```solidity +( + bytes32 orderHash, + bytes32 salt, + address target, + bytes swapPayload, + address tokenIn, + address tokenOut, + uint256 amountIn, + uint256 amountOut, + bool success +) +``` + +#### `SendMessageWithTokenEvent` +When a token is burnt or transferred to another blockchain, this event is emitted to log the transaction corresponding to that token. Similarly, when a token is minted in the target blockchain after a swap is performed, this event will also be emited to record that operation. + +##### Parameters +```solidity +( + address indexed from, + address indexed token, + uint256 amount, + uint256 fee, + bytes payload +) +``` + diff --git a/developers/contracts/btc-peg-in-endpoint.md b/developers/contracts/btc-peg-in-endpoint.md index 4c866db..823fc84 100644 --- a/developers/contracts/btc-peg-in-endpoint.md +++ b/developers/contracts/btc-peg-in-endpoint.md @@ -2,7 +2,7 @@ - Location: `xlink/packages/contracts/bridge-stacks/contracts` - 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), [btc-peg-in-v2-07a-agg](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.btc-peg-in-v2-07a-agg?chain=mainnet) -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 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 five specialized contracts. Each contract addresses specific aspects of the BTC peg-in process. This functionality is implemented and distributed across the following contracts: diff --git a/developers/contracts/cross-peg-out-endpoint.md b/developers/contracts/cross-peg-out-endpoint.md index 5b085f5..cdb677f 100644 --- a/developers/contracts/cross-peg-out-endpoint.md +++ b/developers/contracts/cross-peg-out-endpoint.md @@ -1,9 +1,14 @@ -# cross-peg-out-endpoint-v2-01.clar +# cross-peg-out-endpoint -- Location: `xlink/packages/contracts/bridge-stacks/contracts/cross-peg-out-endpoint-v2-01.clar` -- [Deployed contract](https://explorer.hiro.so/txid/SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.cross-peg-out-endpoint-v2-01?chain=mainnet) +- Location: `xlink/packages/contracts/bridge-stacks/contracts` +- Deployed contracts:[cross-peg-out-endpoint-v2-01](https://explorer.hiro.so/txid/SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.cross-peg-out-endpoint-v2-01?chain=mainnet), [cross-peg-out-v2-01-agg](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.cross-peg-out-v2-01-agg?chain=mainnet) -This technical document provides a detailed overview of the contract responsible for managing the peg-out process, enabling the transfer of `SIP-010` bridged tokens from the Stacks network to EVM-compatible blockchain networks as the EVM-based assets. The contract manages token transfers by validating amounts, applying fees, and maintaining a whitelist for authorized users if enabled. During the process, tokens are either burned or transferred (depending on the token's configuration) to a designated address on the EVM chain. The core functionalities of the contract are implemented through a series of public and governance functions, as described below. +This technical document provides a detailed overview of the contracts responsible for managing the peg-out process, enabling the transfer of `SIP-010` bridged tokens from the Stacks network to EVM-compatible blockchain networks as EVM-based assets. The contracts manage token transfers by validating amounts, applying fees, and maintaining a whitelist for authorized users if enabled. During the process, tokens are either burned or transferred (depending on the token's configuration) to a designated address on the EVM chain. + +The core functionalities of the module are implemented through public and governance functions in the following contracts: + +- `cross-peg-out-endpoint-v2-01`: handles bridging of aBTC tokens from Stacks to EVM-compatible blockchains. +- `cross-peg-out-v2-01-agg`: enables the bridging of tokens from Stacks to an EVM-compatible blockchain to perform a swap on a non-ALEX liquidity aggregator. ## Storage ### `is-paused` @@ -14,6 +19,8 @@ This technical document provides a detailed overview of the contract responsible A flag that indicates whether the peg-out process is active. If set to `true`, all peg-out operations are paused, preventing any new transactions. The contract is deployed in a paused state by default. ### `use-whitelist` +###### _(only present in cross-peg-out-endpoint-v2-01)_ + | Data | Type | | -------- | ------ | | Variable | `bool` | @@ -21,6 +28,8 @@ A flag that indicates whether the peg-out process is active. If set to `true`, a A flag that determines whether a whitelist is enforced for peg-out operations. If set to `true`, only addresses explicitly whitelisted can execute peg-out transactions. By default, this feature is disabled. ### `whitelisted-users` +###### _(only present in cross-peg-out-endpoint-v2-01)_ + | Data | Type | | -------- | ------ | | Map | `principal → bool` | @@ -46,11 +55,28 @@ At the end of the process, the function logs key destination details, including (settle-address (buff 256)) ``` +#### `transfer-to-swap` + +###### _(in contract cross-peg-out-v2-01-agg)_ +This function handles the necessary validations to execute the peg-out process from Stacks to an EVM-compatible blockchain. It begins by validating the transfer through the `validate-transfer-to-swap` function, performing checks such as token and chain approval, amount thresholds, and sufficient reserves for the operation. +Once validated, the function calculates the required fee and determines the net amount to be transferred. Depending on the token's properties, the function either burns or transfers the net amount directly from the user's balance. The transaction is documented in the `cross-bridge-registry-v2-01`, and an event is emitted with the transaction's details. The relayers detect the transaction and perform the necessary operations to route the swap to `BridgeEndpointWithSwap`, which completes the operation through an external liquidity aggregator. + +```lisp +(amount-in-fixed uint) +(token-in-trait ) +(token-out principal) +(min-amount-out (optional uint)) +(dest-chain-id uint) +(settle-details { address: (buff 256), chain-id: (optional 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-whitelisted` +###### _(only present in cross-peg-out-endpoint-v2-01)_ + A read-only function that checks whether a specific user is included in the `whitelisted-users` map. It returns `true` if the user is whitelisted; otherwise, it returns `false`. ##### Parameters @@ -70,6 +96,8 @@ A public function, governed through the `is-dao-or-extension`, that can change t ``` #### `apply-whitelist` +###### _(only present in cross-peg-out-endpoint-v2-01)_ + A public function, governed through the `is-dao-or-extension`, that enables or disables the whitelist mechanism for peg-out transactions. When enabled, only users listed in the `whitelisted-users` map can perform peg-out operations. ##### Parameters @@ -78,6 +106,8 @@ A public function, governed through the `is-dao-or-extension`, that enables or d ``` #### `whitelist` +###### _(only present in cross-peg-out-endpoint-v2-01)_ + A public function, governed through the `is-dao-or-extension`, that allows the DAO to manage user access to the peg-out feature. It updates the `whitelisted-users` map to either include or remove a specific user. If the `whitelisted` parameter is set to `true`, the user is added to the whitelist; if set to `false`, the user is removed. ##### Parameters @@ -87,6 +117,8 @@ A public function, governed through the `is-dao-or-extension`, that allows the D ``` #### `whitelist-many` +###### _(only present in cross-peg-out-endpoint-v2-01)_ + A public function, governed through the `is-dao-or-extension`, that allows the DAO to update the whitelist for multiple users in a single call. It works as a batch operation for the `whitelist` function, applying the specified whitelist status (`true` to add or `false` to remove) for each user in the provided list. The `whitelisted-users` map is updated. ##### Parameters @@ -98,6 +130,8 @@ A public function, governed through the `is-dao-or-extension`, that allows the D ### Getters #### `get-use-whitelist` +###### _(only present in cross-peg-out-endpoint-v2-01)_ + #### `get-approved-chain-or-fail` ##### Parameters ```lisp From f174219bab23f9895808b7b86d9ea064fdf3a728 Mon Sep 17 00:00:00 2001 From: maquirriaincf Date: Wed, 26 Feb 2025 14:58:35 -0300 Subject: [PATCH 3/6] deleted solidity contract bridgeendpointwithswap, edited cross-peg-out-agg --- .../contracts/BridgeEndpointWithSwap.md | 118 ------------------ .../contracts/cross-peg-out-endpoint.md | 5 +- 2 files changed, 3 insertions(+), 120 deletions(-) delete mode 100644 developers/contracts/BridgeEndpointWithSwap.md diff --git a/developers/contracts/BridgeEndpointWithSwap.md b/developers/contracts/BridgeEndpointWithSwap.md deleted file mode 100644 index 3f2103e..0000000 --- a/developers/contracts/BridgeEndpointWithSwap.md +++ /dev/null @@ -1,118 +0,0 @@ -# BridgeEndpointWithSwap.sol - -- Location: `packages/contracts/bridge-solidity/contracts/BridgeEndpointWithSwap.sol` -- [Deployed contract]() - -This technical document provides a detailed overview of the contract responsible for transferring a swap between two tokens to **IceCreamSwap**, a non-ALEX liquidity aggregator. The contract burns or transfers the base tokens and sends the necessary information to complete the swap to IceCreamSwap. The main logic is implemented in the `transferToSwap` function. Lets review its core functionality. - -## Storage - -### `_owner` -| Data | Type | -| -------- | ------ | -| Variable | `address` | - -This address corresponds to the owner of the contract. - -### `name` -| Data | Type | -| -------- | ------ | -| Variable | `string memory` | - -This variable stores the name of the contract. - -### `version` -| Data | Type | -| -------- | ------ | -| Variable | `string memory` | - -This variable stores the version of the contract that is deployed. - -### `_registry` -| Data | Type | -| -------- | ------ | -| Variable | `address` | - -This address corresponds to the `cross-bridge-registry-v2-01` contract, that stores information on all transactions. - -### `_pegInAddress` -| Data | Type | -| -------- | ------ | -| Variable | `address` | - -This parameter represents the address of the peg-in contract. - -### `_timeLock` -| Data | Type | -| -------- | ------ | -| Variable | `address` | - -This variable stores the address of the time lock contract. - -## Features - -### Swap Features - -#### `transferToSwap` - -This function implements the main logic to swap tokens through the bridge endpoint. calculates the `orderHash` taking `salt` as one of the parameters for the calculation. It also validates the order. It calculates `amountOut`, which seems like the amount sent out after the transfer. it either burns `tokenOut` or transfers using `pegInAddress`. It emits two events: `TransferToSwapEvent` and `SendMessageWithTokenEvent`. If unsuccessful, it burns `tokenIn`. - -##### Parameters -```solidity -( - address target, - address tokenIn, - address tokenOut, - uint256 amountIn, - uint256 amountOutMin, - bytes calldata swapPayload, - bytes calldata bridgePayload, - bytes32 salt, - SignaturePackage[] calldata proofs -) -``` - -### Governance Features - -#### `setTimeLock` -This function is called in the constructor of the contract to ensure that _timeLock is set to the appropriate value. - -##### Parameters -```solidity -(_timeLock) -``` - -## Events - -#### `TransferToSwapEvent` -This event is emitted when a token swap is performed within the bridge endpoint. `tokenIn` represents the base token in the swap, whereas `tokenOut` represents the token it is being bridged to. `amountIn` and `amountOut` correspond to the amount of each token. The `swapPayload` parameter is a data payload that is necessary for the swap to execute. `success` indicates whether the swap could be performed or not. - -##### Parameters -```solidity -( - bytes32 orderHash, - bytes32 salt, - address target, - bytes swapPayload, - address tokenIn, - address tokenOut, - uint256 amountIn, - uint256 amountOut, - bool success -) -``` - -#### `SendMessageWithTokenEvent` -When a token is burnt or transferred to another blockchain, this event is emitted to log the transaction corresponding to that token. Similarly, when a token is minted in the target blockchain after a swap is performed, this event will also be emited to record that operation. - -##### Parameters -```solidity -( - address indexed from, - address indexed token, - uint256 amount, - uint256 fee, - bytes payload -) -``` - diff --git a/developers/contracts/cross-peg-out-endpoint.md b/developers/contracts/cross-peg-out-endpoint.md index cdb677f..f2cc9e2 100644 --- a/developers/contracts/cross-peg-out-endpoint.md +++ b/developers/contracts/cross-peg-out-endpoint.md @@ -3,7 +3,7 @@ - Location: `xlink/packages/contracts/bridge-stacks/contracts` - Deployed contracts:[cross-peg-out-endpoint-v2-01](https://explorer.hiro.so/txid/SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.cross-peg-out-endpoint-v2-01?chain=mainnet), [cross-peg-out-v2-01-agg](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.cross-peg-out-v2-01-agg?chain=mainnet) -This technical document provides a detailed overview of the contracts responsible for managing the peg-out process, enabling the transfer of `SIP-010` bridged tokens from the Stacks network to EVM-compatible blockchain networks as EVM-based assets. The contracts manage token transfers by validating amounts, applying fees, and maintaining a whitelist for authorized users if enabled. During the process, tokens are either burned or transferred (depending on the token's configuration) to a designated address on the EVM chain. +This technical document provides a detailed overview of the contracts responsible for managing the peg-out process, enabling the transfer of `SIP-010` bridged tokens from the Stacks network to EVM-compatible blockchain networks as EVM-based assets. The contracts manage token transfers by validating amounts and applying fees. During the process, tokens are either burned or transferred (depending on the token's configuration) to a designated address on the EVM chain. The core functionalities of the module are implemented through public and governance functions in the following contracts: @@ -58,7 +58,8 @@ At the end of the process, the function logs key destination details, including #### `transfer-to-swap` ###### _(in contract cross-peg-out-v2-01-agg)_ -This function handles the necessary validations to execute the peg-out process from Stacks to an EVM-compatible blockchain. It begins by validating the transfer through the `validate-transfer-to-swap` function, performing checks such as token and chain approval, amount thresholds, and sufficient reserves for the operation. +This function handles the necessary validations to execute the peg-out process from Stacks to an EVM-compatible blockchain. It prepares the transaction to be sent to an external liquidity aggregator in the `BridgeEndpointWithSwap.sol` contract. Its core functionality consists of emitting an event with the transaction details. +The function begins by validating the transfer through the `validate-transfer-to-swap` function, performing checks such as token and chain approval, amount thresholds, and sufficient reserves for the operation. Once validated, the function calculates the required fee and determines the net amount to be transferred. Depending on the token's properties, the function either burns or transfers the net amount directly from the user's balance. The transaction is documented in the `cross-bridge-registry-v2-01`, and an event is emitted with the transaction's details. The relayers detect the transaction and perform the necessary operations to route the swap to `BridgeEndpointWithSwap`, which completes the operation through an external liquidity aggregator. ```lisp From 4e875a70d2528a171eacedfb260aa252b50bfe6d Mon Sep 17 00:00:00 2001 From: maquirriaincf Date: Wed, 26 Feb 2025 17:01:15 -0300 Subject: [PATCH 4/6] rework nacho --- developers/contracts/btc-peg-in-endpoint.md | 2 +- developers/contracts/cross-peg-out-endpoint.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/developers/contracts/btc-peg-in-endpoint.md b/developers/contracts/btc-peg-in-endpoint.md index 823fc84..468c133 100644 --- a/developers/contracts/btc-peg-in-endpoint.md +++ b/developers/contracts/btc-peg-in-endpoint.md @@ -10,7 +10,7 @@ This functionality is implemented and distributed across the following contracts - `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. - `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. -- `btc-peg-in-v2-07a-agg`: extends Bitcoin peg-in operations by routing token swaps to non-ALEX liquidity aggregators, which optimize token exchanges by accessing multiple liquidity sources. This allows ALEX to execute swaps even when there are no ALEX pools for a specific token pair. +- `btc-peg-in-v2-07a-agg`: facillitates the BTC peg-in process for swaps with non-ALEX liquidity aggregators. Liquidity aggregators optimize token exchanges by accessing multiple liquidity sources. This allows ALEX to execute swaps even when there are no ALEX pools for a specific token pair. ## Storage ###### _(all contracts include the following variables unless otherwise specified)_ diff --git a/developers/contracts/cross-peg-out-endpoint.md b/developers/contracts/cross-peg-out-endpoint.md index f2cc9e2..c9c1847 100644 --- a/developers/contracts/cross-peg-out-endpoint.md +++ b/developers/contracts/cross-peg-out-endpoint.md @@ -58,9 +58,10 @@ At the end of the process, the function logs key destination details, including #### `transfer-to-swap` ###### _(in contract cross-peg-out-v2-01-agg)_ -This function handles the necessary validations to execute the peg-out process from Stacks to an EVM-compatible blockchain. It prepares the transaction to be sent to an external liquidity aggregator in the `BridgeEndpointWithSwap.sol` contract. Its core functionality consists of emitting an event with the transaction details. +This function handles the peg-out process from Stacks to an EVM-compatible blockchain. It prepares the transaction to be sent to an external liquidity aggregator in the `BridgeEndpointWithSwap.sol` contract. Its core functionality consists of validating amounts, deducting fees, transferring tokens and emitting an event with the transaction details. The function begins by validating the transfer through the `validate-transfer-to-swap` function, performing checks such as token and chain approval, amount thresholds, and sufficient reserves for the operation. -Once validated, the function calculates the required fee and determines the net amount to be transferred. Depending on the token's properties, the function either burns or transfers the net amount directly from the user's balance. The transaction is documented in the `cross-bridge-registry-v2-01`, and an event is emitted with the transaction's details. The relayers detect the transaction and perform the necessary operations to route the swap to `BridgeEndpointWithSwap`, which completes the operation through an external liquidity aggregator. +Once validated, the function calculates the required fee and determines the net amount to be transferred. Depending on the token's properties, the function either burns the tokens or transfers them to the `cross-bridge-registry-v2-01` contract. This action records the transaction and prepares it for further processing. +At this point, an event is emitted, signaling relayers to detect and forward the transaction to `BridgeEndpointWithSwap`, which completes the operation through an external liquidity aggregator. ```lisp (amount-in-fixed uint) From 4a61350313f331001f79ec24f5f504adacd1a7c5 Mon Sep 17 00:00:00 2001 From: maquirriaincf Date: Fri, 28 Feb 2025 16:27:38 -0300 Subject: [PATCH 5/6] changes requested in final review --- developers/contracts/btc-peg-in-endpoint.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/developers/contracts/btc-peg-in-endpoint.md b/developers/contracts/btc-peg-in-endpoint.md index 468c133..35862d5 100644 --- a/developers/contracts/btc-peg-in-endpoint.md +++ b/developers/contracts/btc-peg-in-endpoint.md @@ -69,7 +69,7 @@ This variable sets the minimum fee required for BTC peg-out operations during cr #### `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. +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`. If the validation or routing fails, a refund is executed. ##### Parameters ```lisp @@ -141,8 +141,8 @@ In case of any error, it invokes the internal [refund](btc-peg-in-endpoint.md#re ###### _(in contract btc-peg-in-v2-07a-agg)_ This function facilitates a BTC peg-in operation designed for aggregated cross-chain routing. Unlike standard peg-in processes where users receive aBTC directly on Stacks, this function integrates a routing mechanism that forwards the bridged tokens for immediate cross-chain processing. -The process begins by verifying that the provided Bitcoin transaction has been mined and meets all peg-in validation criteria. It checks that the peg-in address is approved and calculates the required transaction fees. Once validated, the function mints aBTC for the net amount (after deducting fees) and registers the peg-in transaction in the `.btc-bridge-registry-v2-01 contract`. -Instead of keeping the minted aBTC within the Stacks ecosystem, this function directly transfers it to the `.cross-peg-out-v2-01-agg contract`. This interaction enables automated routing and potential asset swaps to facilitate seamless movement of assets across blockchains. The function logs transaction details and ensures that any failure in the process triggers a refund mechanism. +The process begins by verifying that the provided Bitcoin transaction has been mined and meets all peg-in validation criteria. It checks that the peg-in address is approved and calculates the required transaction fees. Once validated, the function mints aBTC for the net amount (after deducting fees) and registers the peg-in transaction in the `.btc-bridge-registry-v2-01` contract. +Instead of keeping the minted aBTC within the Stacks ecosystem, this function directly transfers it to the `.cross-peg-out-v2-01-agg` contract. This interaction enables automated routing and potential asset swaps to facilitate seamless movement of assets across blockchains. The function logs transaction details and ensures that any failure in the process triggers a refund mechanism. ##### Parameters ```lisp @@ -195,7 +195,7 @@ This feature allows to set the minimum fee required for a peg-in transaction. ``` #### `set-btc-peg-out-fee` -###### _(only present in btc-peg-in-v2-07-swap)_ +###### _(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)_ This feature sets the percentage fee applied to BTC peg-out operations. ##### Parameters @@ -204,7 +204,7 @@ This feature sets the percentage fee applied to BTC peg-out operations. ``` #### `set-btc-peg-out-min-fee` -###### _(only present in btc-peg-in-v2-07-swap)_ +###### _(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)_ This feature establishes the minimum fee required for BTC peg-out operations. ##### Parameters @@ -238,8 +238,8 @@ The following functions are tools to assist the off-chain activities. ```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-btc-peg-out-fee` _(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)_ +#### `get-btc-peg-out-min-fee` _(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)_ #### `get-liabtc-decimals` _(only present in btc-peg-in-endpoint-v2-05-lisa)_ ## Contract calls (interactions) From 09460cb458d9d5bd26bff01bc48330046f7d3bcb Mon Sep 17 00:00:00 2001 From: maquirriaincf Date: Wed, 5 Mar 2025 15:08:54 -0300 Subject: [PATCH 6/6] added aggregator contracts to README list --- developers/contracts/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developers/contracts/README.md b/developers/contracts/README.md index 39b8da8..1a9afe3 100644 --- a/developers/contracts/README.md +++ b/developers/contracts/README.md @@ -20,7 +20,7 @@ The XLink ecosystem offers three main features that are implemented along differ #### BTC Peg-In Endpoint -- Contract names: `btc-peg-in-endpoint-v2-05`, `btc-peg-in-endpoint-v2-05-lisa`, `btc-peg-in-v2-05-launchpad`, `btc-peg-in-v2-07-swap`. +- Contract names: `btc-peg-in-endpoint-v2-05`, `btc-peg-in-endpoint-v2-05-lisa`, `btc-peg-in-v2-05-launchpad`, `btc-peg-in-v2-07-swap`, `btc-peg-in-v2-07a-agg`. - [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). @@ -69,7 +69,7 @@ This endpoint is responsible for managing the transfer of assets from other EVM- #### Cross Peg-Out Endpoint -- Contract name: `cross-peg-out-endpoint-v2-01` +- Contract names: `cross-peg-out-endpoint-v2-01`, `cross-peg-out-v2-01-agg`. - [Complete technical documentation](cross-peg-out-endpoint.md) This endpoint is responsible for managing the transfer of `SIP-010` bridged tokens from the Stacks network to EVM-like blockchains.