GITBOOK-3: Josh's Brotocol Overhaul (Apr 7)

README.md

@@ -1,45 +1,51 @@
 ---
-cover: .gitbook/assets/DocCoverXlink.png
+cover: .gitbook/assets/gbbanner.png
 coverY: 0
+layout:
+  cover:
+    visible: true
+    size: hero
+  title:
+    visible: true
+  description:
+    visible: true
+  tableOfContents:
+    visible: true
+  outline:
+    visible: true
+  pagination:
+    visible: true
 ---
 
-# What is XLink
+# What is Brotocol?
 
-XLink is a cutting-edge, bi-directional cross-chain bridge that enables seamless asset transfers between Bitcoin and its Layer 2 networks (L2s) as well as other blockchain ecosystems. By abstracting the complexity of blockchain layers from the user experience, XLink allows users to move assets like Bitcoin effortlessly between different chains while maintaining security and full asset control.
+Brotocol Bridge is a MPC-based hybrid bi-directional bridge that acts as a 'connector' between Bitcoin and other blockchains, enabling seamless asset transfers and swaps between Bitcoin and its Layer 2 networks (L2s) as well as other blockchain ecosystems. 
 
-[**🌁 Connect to XLink and Start Bridging Now!**](https://app.xlink.network)
+**Brotocol currently offers two key features:**
+
+* [BroBridge](features/broswap/)
+* [BroSwap](features/broswap/)
 
 ## Key Features
 
-- **Bi-Directional Asset Transfers**: Easily transfer assets between Bitcoin and L2s, as well as non-Bitcoin chains.
-- **Secure and Decentralized**: Utilizes multisigs and decentralized validators to secure all transfers.
-- **User-Friendly Interface**: Designed to provide a smooth experience for both novice and experienced users.
-- **Cross-Chain Interoperability**: Supports multiple blockchains including Bitcoin, Stacks, and EVM-compatible chains.
+* **Bi-Directional Asset Transfers**: Easily transfer assets between Bitcoin and L2s, as well as non-Bitcoin chains.
+* **Secure and Decentralized**: Utilizes multisigs and decentralized validators to secure all transfers.
+* **User-Friendly Interface**: Designed to provide a smooth experience for both novice and experienced users.
+* **Cross-Chain Interoperability**: Supports multiple blockchains including Bitcoin, Stacks, and EVM-compatible chains.
 
-XLink plays a crucial role in projects building on Bitcoin, offering a 'native-like' DeFi experience by enabling users to interact with smart contracts on L2s using native BTC or other Bitcoin L1 assets.
+Brotocol plays a crucial role in projects building on Bitcoin, offering a 'native-like' DeFi experience by enabling users to interact with smart contracts on L2s using native BTC or other Bitcoin L1 assets.
 
-## Documentation
+## Types of blockchain bridges
 
-XLink's functionality is detailed across various sections in our documentation. Here's an overview of the key files and structure:
+Not all bridges work the same way, and understanding the differences can help you determine which one best suits your needs:
 
-- **Overview**
-  - [Introduction](overview/introduction.md): Learn the basics of how XLink operates and its role in cross-chain transfers.
-  - [How XLink Works](overview/how-xlink-works.md): Overview of the mechanics behind the XLink bridge.
-  - [Supported Blockchains & Tokens](overview/supported-blockchains-and-tokens.md): Explore the ecosystems XLink integrates with.
-  
-- **Getting Started**
-  - [Prerequisites](getting-started/prerequisites.md): Essential requirements to begin using the XLink bridge.
-  - [Quickstart: The Bridge](getting-started/the-bridge.md): Step-by-step guide to initiate asset transfers.
-  - [Quickstart: Campaigns](getting-started/campaigns.md): A detailed guide on how to participate in XLink campaigns and earn rewards.
-  - [Guides](getting-started/guides/README.md): Practical walkthroughs, including [How to Connect Your Wallet](getting-started/guides/how-to-connect-your-wallet.md) and [How to Swap non-bridgeable Tokens](getting-started/guides/how-to-swap-non-bridgeable-tokens.md).
+* `Trust-based Bridges`: These are operated by a centralized entity, requiring users to trust that entity to manage and safeguard their assets. While these bridges can offer faster and more straightforward operations, they introduce a single point of failure, as the security of the entire system depends on the integrity of the operator.
+* `Decentralized Bridges`: These rely on smart contracts and a distributed group of validators to ensure smooth and secure operations without needing a central authority. Although they avoid centralization issues, they can sometimes be slower or more costly due to the additional security checks involved.
+* `Hybrid Bridges`: Hybrid bridges combine elements of both trusted and decentralized models, using centralized intermediaries alongside decentralized smart contracts or consensus systems. This approach aims to balance efficiency and security, providing a flexible solution for cross-chain asset transfers.
+* `Two-way Bridges`: Bi-directional bridges enable the transfer of assets in both directions between two blockchains, making it easy to move your tokens in either direction.
+* `One-way Bridges`: As the name suggests, these bridges allow the transfer of assets from one blockchain to another but do not support transfers in the opposite direction. They’re useful in cases where you only need to transfer tokens once, such as when moving assets to a chain where they will remain and be used.
 
-- **Integrations**
-  - [Bitcoin](integrations/understanding-the-bitcoin-bridge.md): Delve into how XLink integrates with Bitcoin.
-  - [Bitcoin L2s](integrations/bitcoin-l2s.md): Understand how XLink works with various L2 solutions.
-  - [Non-Bitcoin Chains](integrations/non-bitcoin-chains.md): Overview of support for non-Bitcoin blockchains.
-
-- **Security**
-  - [Security Audits](security-audits.md): Learn about XLink’s robust security measures and audit reports.
+Brotocol's type is **`Two-way Bridges` .** 
 
 ## Support
 

SUMMARY.md

@@ -1,30 +1,34 @@
 # Table of contents
 
-- [What is XLink](README.md)
+## 👊 Introduction
 
-- [Overview](overview/README.md)
-  - [Introduction](overview/introduction.md)
-  - [How XLink Bridge Works?](overview/how-xlink-works.md)
-  - [Supported Blockchains and Tokens](overview/supported-blockchains-and-tokens.md)
+* [What is Brotocol?](README.md)
+  * [✨ Brotocol 101](introduction/readme/brotocol-101.md)
+* [Getting Started](introduction/getting-started/README.md)
+  * [Supported Wallets](introduction/getting-started/prerequisites/README.md)
+    * [How to Connect your Wallet](introduction/getting-started/prerequisites/how-to-connect-your-wallet.md)
+* [What is Bonbori?](introduction/what-is-bonbori/README.md)
+  * [Why Bonbori?](introduction/what-is-bonbori/why-bonbori.md)
+  * [Bonbori Consensus Model](introduction/what-is-bonbori/bonbori-consensus-model.md)
 
-- [Getting Started](getting-started/README.md)
-  - [Prerequisites](getting-started/prerequisites.md)
-  - [Quickstart: The Bridge](getting-started/the-bridge.md)
-  - [Quickstart: Campaigns](getting-started/campaigns.md)
-  - [Guides](getting-started/guides/README.md)
-    - [How to Connect your Wallet](getting-started/guides/how-to-connect-your-wallet.md)
-    - [How to Swap non-bridgeable Tokens](getting-started/guides/how-to-swap-non-bridgeable-tokens.md)
-   
-- [Reserves](reserves.md)
+## 🌉 Features
 
-- [Integrations](integrations/README.md)
-  - [Bitcoin](integrations/understanding-the-bitcoin-bridge.md)
-  - [Bitcoin L2s](integrations/bitcoin-l2s.md)
-  - [Non-Bitcoin chains](integrations/non-bitcoin-chains.md)
+* [BroSwap](features/broswap/README.md)
+  * [DEX Aggregation](features/broswap/dex-aggregation.md)
+  * [How to swap Non-bridgeable Tokens?](features/broswap/how-to-swap-non-bridgeable-tokens.md)
+* [BroBridge](features/brobridge/README.md)
+  * [How Brotocol Bridge Works?](features/brobridge/how-xlink-works.md)
+* [Explorer](features/explorer/README.md)
+  * [Active Notifications](features/explorer/active-notifications.md)
 
-- [Security Audits](security-audits.md)
+***
+
+* [Reserves](reserves/README.md)
+  * [What is aBTC?](reserves/what-is-abtc.md)
+  * [What is aUSD?](reserves/what-is-ausd.md)
 
 ## 🎮 Developers
+
 * [Smart Contracts](developers/contracts/README.md)
   * [btc peg-in endpoint](developers/contracts/btc-peg-in-endpoint.md)
   * [btc-peg-out-endpoint](developers/contracts/btc-peg-out-endpoint.md)
@@ -32,33 +36,15 @@
   * [meta peg-out endpoint](developers/contracts/meta-peg-out-endpoint.md)
   * [cross-peg-in-endpoint](developers/contracts/cross-peg-in-endpoint.md)
   * [cross-peg-out-endpoint](developers/contracts/cross-peg-out-endpoint.md)
-  * [xlink-staking](developers/contracts/xlink-staking.md)
+  * [brotocol-staking](developers/contracts/xlink-staking.md)
   * [BridgeEndpoint](developers/contracts/BridgeEndpoint.md)
+* [Add a New Chain](developers/add-a-new-chain.md)
+* [Supported Blockchains and Tokens](developers/supported-blockchains-and-tokens.md)
+* [Security Audits](developers/security-audits.md)
+* [Integrations](developers/integrations/README.md)
+  * [Bitcoin](developers/integrations/understanding-the-bitcoin-bridge.md)
+  * [Bitcoin L2s or EVMs](developers/integrations/bitcoin-l2s.md)
 
-<!-- 
+## 🖼️ Media Kits
 
-Future work:
-
-## Special Features
-
-* [Campaigns](special-features/campaigns.md)
-* [Points](special-features/points.md)
-
-## Developers
-
-* [Technical Overview](developers/technical-overview/README.md)
-    * [Components](developers/technical-overview/components.md)
-    * [Smart Contracts](developers/technical-overview/smart-contracts.md)
-    * [Oracle Integration](developers/technical-overview/oracle-integration.md)
-
-* [Development & Integrations](developers/development-and-integrations/README.md)
-    * [XLink SDK](developers/development-and-integrations/sdk.md)
-    * [New features, Changelog, Roadmap?](developers/development-and-integrations/new-features.md)
-
-## Resources
-
-* [Glossary](resources/glossary.md)
-* [FAQs](resources/faqs.md)
-* [Networks](resources/networks.md) 
-
--->
+* [Official Links](media-kits/official-links.md)

developers/add-a-new-chain.md

@@ -0,0 +1,70 @@
+# Add a New Chain
+
+<figure><img src="../.gitbook/assets/join the bridge.png" alt=""><figcaption></figcaption></figure>
+
+Want to bring your chain into the Brotocol ecosystem?&#x20;
+
+Whether you're an L1, L2, or appchain team, integrating with Brotocol opens your users to native Bitcoin liquidity, cross-chain swaps, and secure bridging—all while preserving Bitcoin as the settlement layer.
+
+**Here’s how to get started:**
+
+***
+
+### 🧩 Overview
+
+To support a new chain, Brotocol deploys a smart contract called an **Endpoint**, which acts as the entry and exit point for cross-chain asset transfers. These Endpoints are governed by multisigs (e.g. Gnosis Safe, ExecutorDAO) and coordinated through the **Bonbori** consensus layer.
+
+Once deployed, your Endpoint becomes part of the BroBridge routing network—supporting swaps, payments, and bridging for supported assets.
+
+***
+
+### ✅ Integration Requirements
+
+To be eligible for integration, your chain should support:
+
+* ✅ Smart contract deployment (EVM-compatible or custom logic)
+* ✅ Reliable block finality for message validation
+* ✅ Token standards (ERC-20 or equivalent) for fungible assets
+* ✅ A relayer-friendly RPC interface for transaction submissions
+
+For Bitcoin L2s or non-EVM chains, custom integration paths are available. Reach out to the team for support.
+
+***
+
+### 🔧 Integration Steps
+
+#### 1. Contact the Brotocol Team
+
+Reach out via Discord or email to start the process. Provide basic info:
+
+* Chain name & website
+* RPC endpoints & explorers
+* Token assets you want to support
+* Dev contact for coordination
+
+#### 2. Deploy Endpoint Contract
+
+Brotocol will deploy an **Endpoint contract** to your chain. This contract:
+
+* Receives incoming assets
+* Validates cryptographic proofs from Bonbori validators
+* Releases assets to users or contracts
+
+Endpoints are owned by a multisig for security and flexibility.
+
+#### 3. Configure the Endpoint
+
+Once deployed, the following parameters are set:
+
+* Approved token list
+* Validator set & thresholds
+* Fee structure
+* Supported swap paths (optional)
+
+#### 4. Enable Relayer Support
+
+Brotocol relayers will monitor your chain’s Endpoint and submit proofs to/from other chains.
+
+#### 5. (Optional) Deploy Synthetic Assets
+
+If your chain doesn’t natively support a desired asset (e.g., BTC), a synthetic version (e.g., aBTC or aUSD) may be deployed and mapped to real assets via BroBridge.

developers/contracts/BridgeEndpoint.md

@@ -1,79 +1,86 @@
 # BridgeEndpoint
-- Location: `xlink/packages/contracts/bridge-solidity/contracts`
-- Deployed contracts: See [Ethereum Contract Addresses](https://docs.xlink.network/xlink-network/readme/ethereum-contract-addresses).
 
-This technical document provides a detailed overview of the Bridge Endpoint in EVM-compatible blockchains. The Bridge Endpoint facilitates communication between two blockchain networks by acting as the entry and exit point for assets moving along the Cross Chain Bridge. It passes messages between chains in the form of events, triggers contract calls, processes token transfers and validates and executes the unwrapping of tokens. `BridgeEndpointWithSwap` extends `BridgeEndpoint` and implements the necessary features to source liquidity from external aggregators.
+* Location: `xlink/packages/contracts/bridge-solidity/contracts`
+* Deployed contracts: See [Ethereum Contract Addresses](https://docs.xlink.network/xlink-network/readme/ethereum-contract-addresses).
+
+This technical document provides a detailed overview of the Bridge Endpoint in EVM-compatible blockchains. The Bridge Endpoint facilitates communication between two blockchain networks by acting as the entry and exit point for assets moving along the Cross Chain Bridge. 
+
+It passes messages between chains in the form of events, triggers contract calls, processes token transfers and validates and executes the unwrapping of tokens. `BridgeEndpointWithSwap` extends `BridgeEndpoint` and implements the necessary features to source liquidity from external aggregators.
 
 This Bridge Endpoint functionality is implemented and distributed across the following contracts:
 
-- `BridgeEndpoint`: the base contract that facilitates bridging operations.
-- `BridgeEndpointWithSwap`: extends `BridgeEndpoint` and integrates swaps during a bridge transfer.
+* `BridgeEndpoint`: the base contract that facilitates bridging operations.
+* `BridgeEndpointWithSwap`: extends `BridgeEndpoint` and integrates swaps during a bridge transfer.
 
 ## Storage
 
 ### `registry`
 
-| Data     | Type   |
-| -------- | ------ |
+| Data     | Type             |
+| -------- | ---------------- |
 | Variable | `BridgeRegistry` |
 
 Stores a reference to the `BridgeRegistry` contract, which manages approved tokens, relayers, and validators.
 
 ### `pegInAddress`
 
-| Data     | Type   |
-| -------- | ------ |
+| Data     | Type      |
+| -------- | --------- |
 | Variable | `address` |
 
-The address in which non-burnable tokens from peg-out orders are stored before they are bridged out of the EVM-compatible blockchain. The user calls [`sendMessageWithToken`](#sendmessagewithtoken), which deducts a fee and transfers the remaining non-burnable tokens to `pegInAddress`. This address also provides the funds for non-burnable peg-in orders.
+The address in which non-burnable tokens from peg-out orders are stored before they are bridged out of the EVM-compatible blockchain. The user calls [`sendMessageWithToken`](BridgeEndpoint.md#sendmessagewithtoken), which deducts a fee and transfers the remaining non-burnable tokens to `pegInAddress`. This address also provides the funds for non-burnable peg-in orders.
 
 ### `timeLock`
 
-| Data     | Type   |
-| -------- | ------ |
+| Data     | Type        |
+| -------- | ----------- |
 | Variable | `ITimeLock` |
 
 Manages locked transactions that require a delay before execution. Tokens amounts that exceed the threshold are not immediately sent to the user. Instead, the `timeLock` contract holds them until the waiting period expires. At that point, the `timeLock` owner can fulfill the order, completing the cross-chain transfer.
 
 ### `timeLockThreshold`
 
-| Data     | Type   |
-| -------- | ------ |
+| Data     | Type      |
+| -------- | --------- |
 | Variable | `uint256` |
 
 The global minimum token amount that triggers a timelock. By default, the value is set to `0`.
 
 ### `timeLockThresholdByToken`
-| Data     | Type   |
-| -------- | ------ |
+
+| Data     | Type                          |
+| -------- | ----------------------------- |
 | Variable | `mapping(address => uint256)` |
 
-Optional custom timelock thresholds for different tokens. The timelock will be triggered when a token amount exceeds the custom threshold, if applicable. If no custom threshold is set, the token amount will need to exceed the global threshold set in [`timeLockThreshold`](#timelockthreshold).
+Optional custom timelock thresholds for different tokens. The timelock will be triggered when a token amount exceeds the custom threshold, if applicable. If no custom threshold is set, the token amount will need to exceed the global threshold set in [`timeLockThreshold`](BridgeEndpoint.md#timelockthreshold).
 
 ### `unwrapSent`
-| Data     | Type   |
-| -------- | ------ |
+
+| Data     | Type                               |
+| -------- | ---------------------------------- |
 | Variable | `mapping(bytes32 => OrderPackage)` |
 
-Stores unwrap orders that need to be finalized. It stores a mapping of [`OrderPackage`](#orderpackage) structs, which contain a flag indicating whether the unwrap has been completed. `bytes32` is a unique hash of the struct parameters, as calculated by [`transferToUnwrap`](#transfertounwrap).
+Stores unwrap orders that need to be finalized. It stores a mapping of [`OrderPackage`](BridgeEndpoint.md#orderpackage) structs, which contain a flag indicating whether the unwrap has been completed. `bytes32` is a unique hash of the struct parameters, as calculated by [`transferToUnwrap`](BridgeEndpoint.md#transfertounwrap).
 
 ### `swapExecutor`
-###### _(only present in BridgeEndpointWithSwap)_
 
-| Data     | Type   |
-| -------- | ------ |
+_**(only present in BridgeEndpointWithSwap)**_
+
+| Data     | Type           |
+| -------- | -------------- |
 | Variable | `SwapExecutor` |
 
 Holds a reference to `SwapExecutor`, which is the contract that executes swaps.
 
 ### `swapSent`
-###### _(only present in BridgeEndpointWithSwap)_
 
-| Data     | Type   |
-| -------- | ------ |
+_**(only present in BridgeEndpointWithSwap)**_
+
+| Data     | Type                                   |
+| -------- | -------------------------------------- |
 | Variable | `mapping(bytes32 => SwapOrderPackage)` |
 
-A mapping of [`SwapOrderPackage`](#swaporderpackage) structs that contains details of swap orders.`bytes32` is a unique hash of the swap parameters, as calculated by [`transferToSwap`](#transfertoswap).
+A mapping of [`SwapOrderPackage`](BridgeEndpoint.md#swaporderpackage) structs that contains details of swap orders.`bytes32` is a unique hash of the swap parameters, as calculated by [`transferToSwap`](BridgeEndpoint.md#transfertoswap).
 
 ## Data Types
 
@@ -103,7 +110,8 @@ struct SignaturePackage {
 ```
 
 #### `SwapOrderPackage`
-###### _(only present in BridgeEndpointWithSwap)_
+
+_**(only present in BridgeEndpointWithSwap)**_
 
 A struct that stores details of a swap order.
 
@@ -122,19 +130,24 @@ struct SwapOrderPackage {
 
 ## Modifiers
 
-- `onlyApprovedToken(token)`: ensures the token is approved in the registry.
-- `onlyApprovedRelayer()`: ensures the caller is an approved relayer.
-- `notWatchlist(recipient)`: prevents transfers to watchlisted addresses.
-- `nonReentrant`: protects against reentrancy attacks.
-- `onlyAllowlisted`: ensures only allowed addresses can execute certain functions.
+* `onlyApprovedToken(token)`: ensures the token is approved in the registry.
+* `onlyApprovedRelayer()`: ensures the caller is an approved relayer.
+* `notWatchlist(recipient)`: prevents transfers to watchlisted addresses.
+* `nonReentrant`: protects against reentrancy attacks.
+* `onlyAllowlisted`: ensures only allowed addresses can execute certain functions.
 
 ## Features
 
 #### `sendMessageWithToken`
 
-This function is called to initiate the peg-out process from an EVM-compatible blockchain onto other chains, such as Stacks or Bitcoin. The user deposits tokens in the bridge contract, which are burned or locked, depending on the token. The contract checks that the token is approved, since [`sendMessageWithToken`](#sendmessagewithtoken) has the `onlyApprovedToken` modifier. The function calls [`_transfer`](#_transfer), which performs validations. Finally, the function emits a [`SendMessageWithTokenEvent`](#sendmessagewithtokenevent) containing the transaction details, which will be reviewed by validators. Once they verify that the tokens were deposited in the `BridgeEndpoint` contract, the validators will sign the order and relayers will submit it in the destination chain.   
+This function is called to initiate the peg-out process from an EVM-compatible blockchain onto other chains, such as Stacks or Bitcoin. The user deposits tokens in the bridge contract, which are burned or locked, depending on the token. 
+
+The contract checks that the token is approved, since [`sendMessageWithToken`](BridgeEndpoint.md#sendmessagewithtoken) has the `onlyApprovedToken` modifier. The function calls [`_transfer`](BridgeEndpoint.md#_transfer), which performs validations. Finally, the function emits a [`SendMessageWithTokenEvent`](BridgeEndpoint.md#sendmessagewithtokenevent) containing the transaction details, which will be reviewed by validators. 
+
+Once they verify that the tokens were deposited in the `BridgeEndpoint` contract, the validators will sign the order and relayers will submit it in the destination chain.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 address token,
 uint256 amount, 
@@ -145,16 +158,18 @@ bytes calldata payload
 
 Emits an event with a message.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 bytes calldata payload
 ```
 
 #### `transferToUnwrap`
 
-This function is called by a relayer when a user initiates a token transfer from another blockchain. The originating order may come from an EVM chain (via [`sendMessageWithToken`](#sendmessagewithtoken)), or from a non-EVM chain like Stacks, Bitcoin or Solana. Relayers listen for the corresponding event on the source chain and call [`transferToUnwrap`](#transfertounwrap) on the destination chain, supplying the recipient, token, amount, a salt (usually the source chain transaction), and an array of validator signatures (proofs). The contract verifies these proofs and generates an EIP-712-compliant hash, which acts as a unique identifier for each order.
+This function is called by a relayer when a user initiates a token transfer from another blockchain. The originating order may come from an EVM chain (via [`sendMessageWithToken`](BridgeEndpoint.md#sendmessagewithtoken)), or from a non-EVM chain like Stacks, Bitcoin or Solana. Relayers listen for the corresponding event on the source chain and call [`transferToUnwrap`](BridgeEndpoint.md#transfertounwrap) on the destination chain, supplying the recipient, token, amount, a salt (usually the source chain transaction), and an array of validator signatures (proofs). The contract verifies these proofs and generates an EIP-712-compliant hash, which acts as a unique identifier for each order.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 address token,
 address recipient,
@@ -165,19 +180,22 @@ SignaturePackage[] calldata proofs
 
 #### `finalizeUnwrap`
 
-This function completes a pending unwrap order for non-burnable tokens. It is called by a hot wallet address once the timeLock period expires, which transfers the tokens to the recipients and finalizes peg-in orders. It loops through each `orderHash` and calls [`_finalizeUnwrap()`](#_finalizeunwrap), which verifies that the order has not already been completed and transfers the token and amount stored in [`unwrapSent`](#unwrapsent) to the recipient. The order is then marked as completed, and the [`FinalizeUnwrapEvent`](#finalizeunwrapevent) is emitted.
+This function completes a pending unwrap order for non-burnable tokens. It is called by a hot wallet address once the timeLock period expires, which transfers the tokens to the recipients and finalizes peg-in orders. It loops through each `orderHash` and calls [`_finalizeUnwrap()`](BridgeEndpoint.md#_finalizeunwrap), which verifies that the order has not already been completed and transfers the token and amount stored in [`unwrapSent`](BridgeEndpoint.md#unwrapsent) to the recipient. The order is then marked as completed, and the [`FinalizeUnwrapEvent`](BridgeEndpoint.md#finalizeunwrapevent) is emitted.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 bytes32[] calldata orderHash
 ```
 
 #### `transferToSwap`
-###### _(in contract BridgeEndpointWithSwap)_`
 
-This function executes a swap before bridging tokens. If the token is burnable, the contract mints the required amount before swapping, calls [`_executeSwap`](#_executeswap) to perform the swap and emits a [`TransferToSwapEvent`](#transfertoswapevent) recording the details. If it is not burnable, it saves swap details in the [`swapSent`](#swapsent) mapping and emits [`SwapOrderCreated`](#swapordercreated) so the swap can be finalized later. In either case, the function will validate token and relayer permissions and generate a unique EIP-712 hash to identify the swap.
+_**(in contract BridgeEndpointWithSwap)**_**\`**
+
+This function executes a swap before bridging tokens. If the token is burnable, the contract mints the required amount before swapping, calls [`_executeSwap`](BridgeEndpoint.md#_executeswap) to perform the swap and emits a [`TransferToSwapEvent`](BridgeEndpoint.md#transfertoswapevent) recording the details. If it is not burnable, it saves swap details in the [`swapSent`](BridgeEndpoint.md#swapsent) mapping and emits [`SwapOrderCreated`](BridgeEndpoint.md#swapordercreated) so the swap can be finalized later. In either case, the function will validate token and relayer permissions and generate a unique EIP-712 hash to identify the swap.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 address target,
 address tokenIn,
@@ -192,10 +210,13 @@ SignaturePackage[] calldata proofs
 ```
 
 #### `finalizeSwap`
-###### _(in contract BridgeEndpointWithSwap)_`
-This function is used when a token is not burnable, leading [`transferToSwap`](#transfertoswap) to store the swap order instead of executing it immediately. It ensures input arrays are valid, and it loops through each `orderHash` and calls [`_finalizeSwap()`](#_finalizeswap).
 
-##### Parameters
+_**(in contract BridgeEndpointWithSwap)**_**\`**
+
+This function is used when a token is not burnable, leading [`transferToSwap`](BridgeEndpoint.md#transfertoswap) to store the swap order instead of executing it immediately. It ensures input arrays are valid, and it loops through each `orderHash` and calls [`_finalizeSwap()`](BridgeEndpoint.md#_finalizeswap).
+
+**Parameters**
+
 ```solidity
 bytes32[] calldata orderHashes,
 bytes[] calldata swapPayloads
@@ -207,15 +228,18 @@ bytes[] calldata swapPayloads
 
 Updates the contract managing timelocks.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 address _timeLock
 ```
+
 #### `setTimeLockThreshold`
 
 Sets the global timelock threshold.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 uint256 _timeLockThreshold
 ```
@@ -224,7 +248,8 @@ uint256 _timeLockThreshold
 
 Sets a custom timelock threshold per token.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 address token, 
 uint256 _timeLockThreshold
@@ -238,24 +263,28 @@ Adds an address to the allowlist, granting it permission to perform specific con
 
 Removes an address from the allowlist, revoking its access.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 address account
 ```
 
 #### `pause`
+
 Pauses the contract, preventing token transfers until the contract is unpaused.
 
 #### `unpause`
+
 Resumes contract operations after a pause, allowing bridging and transfers again.
 
 ### Read-Only Functions
 
 #### `offAllowList`
 
-Returns `true` if the provided address is not on the allowlist. 
+Returns `true` if the provided address is not on the allowlist.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 address account
 ```
@@ -268,9 +297,12 @@ Returns `true` if the provided address is on the allowlist, which means it has p
 
 #### `_transfer`
 
-This internal function is responsible for processing token transfers when a user sends tokens into the bridge. It is called from [`sendMessageWithToken`](#sendmessagewithtoken) and performs validations, calculates and deducts fees, and sends the correct amount of tokens to the `pegInAddress`. This function ensures the transfer amount is within allowed limits and that it is large enough to cover the minimum fee. If the token is burnable, it burns the amount minus the fee. Otherwise, it transfers the same amount to the `pegInAddress`. In either case, the fee is sent to the `BridgeRegistry` contract.
+This internal function is responsible for processing token transfers when a user sends tokens into the bridge. It is called from [`sendMessageWithToken`](BridgeEndpoint.md#sendmessagewithtoken) and performs validations, calculates and deducts fees, and sends the correct amount of tokens to the `pegInAddress`. 
+
+This function ensures the transfer amount is within allowed limits and that it is large enough to cover the minimum fee. If the token is burnable, it burns the amount minus the fee. Otherwise, it transfers the same amount to the `pegInAddress`. In either case, the fee is sent to the `BridgeRegistry` contract.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 address token, 
 uint256 amount
@@ -280,7 +312,8 @@ uint256 amount
 
 Verifies if an order is legitimate by checking validator signatures.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 bytes32 orderHash, 
 SignaturePackage[] calldata proofs
@@ -290,28 +323,33 @@ SignaturePackage[] calldata proofs
 
 Completes an unwrap transaction by transferring tokens to the recipient.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 bytes32 orderHash
 ```
 
 #### `_finalizeSwap`
-###### _(in contract BridgeEndpointWithSwap)_`
 
-This function is called by [`finalizeSwap`](#finalizeswap) to retrieve a stored swap order and to execute the swap. It checks if the order exists and has not been executed, transfers `amountIn` tokens from the sender to the `BridgeEndpointWithSwap` contract and calls [`_executeSwap`](#_executeswap) to perform the swap. Finally, it marks the order as sent and emits a [`SwapOrderFinalized`](#swaporderfinalized) event.
+_**(in contract BridgeEndpointWithSwap)**_**\`**
+
+This function is called by [`finalizeSwap`](BridgeEndpoint.md#finalizeswap) to retrieve a stored swap order and to execute the swap. It checks if the order exists and has not been executed, transfers `amountIn` tokens from the sender to the `BridgeEndpointWithSwap` contract and calls [`_executeSwap`](BridgeEndpoint.md#_executeswap) to perform the swap. Finally, it marks the order as sent and emits a [`SwapOrderFinalized`](BridgeEndpoint.md#swaporderfinalized) event.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 bytes32 orderHash, 
 bytes memory swapPayload
 ```
 
 #### `_executeSwap`
-###### _(in contract BridgeEndpointWithSwap)_`
 
-This function approves `swapExecutor` to spend `tokenIn` and calls its `executeSwap()` function to attempt the swap. If the swap succeeds, it either burns the swapped tokens or prepares them for transfer. To transfer the tokens, `tokenOut` is sent to [`pegInAddress`](#peginaddress) for bridging and a [`SendMessageWithTokenEvent`](#sendmessagewithtokenevent) is emitted. If the swap fails, the error is logged via `SwapExecutorError`, approvals are revoked and a [`SendMessageWithTokenEvent`](#sendmessagewithtokenevent) with `bridgePayloadFailure` is emitted. In either case, the function will burn `tokenIn` tokens if applicable. 
+_**(in contract BridgeEndpointWithSwap)**_**\`**
+
+This function approves `swapExecutor` to spend `tokenIn` and calls its `executeSwap()` function to attempt the swap. If the swap succeeds, it either burns the swapped tokens or prepares them for transfer. To transfer the tokens, `tokenOut` is sent to [`pegInAddress`](BridgeEndpoint.md#peginaddress) for bridging and a [`SendMessageWithTokenEvent`](BridgeEndpoint.md#sendmessagewithtokenevent) is emitted. If the swap fails, the error is logged via `SwapExecutorError`, approvals are revoked and a [`SendMessageWithTokenEvent`](BridgeEndpoint.md#sendmessagewithtokenevent) with `bridgePayloadFailure` is emitted. In either case, the function will burn `tokenIn` tokens if applicable.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 address tokenIn,
 address tokenOut,
@@ -327,9 +365,10 @@ bytes memory bridgePayloadFailure
 
 #### `SendMessageEvent`
 
-Emitted when a user sends a message without transferring tokens. 
+Emitted when a user sends a message without transferring tokens.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 address indexed from, 
 uint256 value, 
@@ -340,7 +379,8 @@ bytes payload
 
 Emitted when a user initiates a peg-out order.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 address indexed from,
 address indexed token,
@@ -353,7 +393,8 @@ bytes payload
 
 Emitted when an order is created to unwrap tokens. This event is emitted when an order is validated and tokens have to be transfered to a recipient.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 bytes32 orderHash,
 bytes32 salt,
@@ -366,16 +407,18 @@ uint256 amount
 
 Emitted when an unwrap order is finalized and tokens are successfully transferred to the recipient.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 bytes32 indexed orderHash
 ```
 
 #### `SetTimelockEvent`
 
-Emitted when [`timeLock`](#timelock) is updated by the contract owner.
+Emitted when [`timeLock`](BridgeEndpoint.md#timelock) is updated by the contract owner.
+
+**Parameters**
 
-##### Parameters
 ```solidity
 address timeLock
 ```
@@ -384,7 +427,8 @@ address timeLock
 
 Emitted when the global time lock threshold is updated.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 uint256 timeLockThreshold
 ```
@@ -393,29 +437,34 @@ uint256 timeLockThreshold
 
 Emitted when the time lock threshold for a specific token is updated.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 address token,
 uint256 timeLockThreshold
 ```
 
 #### `SwapExecutorError`
-###### _(only present in BridgeEndpointWithSwap)_
+
+_**(only present in BridgeEndpointWithSwap)**_
 
 Emitted when a swap operation fails during the bridge transfer.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 address indexed target, 
 bytes reason
 ```
 
 #### `SwapOrderCreated`
-###### _(only present in BridgeEndpointWithSwap)_
+
+_**(only present in BridgeEndpointWithSwap)**_
 
 Emitted when a new swap order is created for non-burnable tokens. It logs the creation of swap orders, helping to track them before execution.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 bytes32 indexed orderHash,
 address indexed target,
@@ -428,11 +477,13 @@ bytes bridgePayloadFailure
 ```
 
 #### `SwapOrderFinalized`
-###### _(only present in BridgeEndpointWithSwap)_
+
+_**(only present in BridgeEndpointWithSwap)**_
 
 Emitted when a swap order is executed and finalized, confirming a swap has been processed.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 bytes32 indexed orderHash,
 address indexed executor,
@@ -441,11 +492,13 @@ bool success
 ```
 
 #### `TransferToSwapEvent`
-###### _(only present in BridgeEndpointWithSwap)_
+
+_**(only present in BridgeEndpointWithSwap)**_
 
 Emitted when a token transfer and swap operation is executed.
 
-##### Parameters
+**Parameters**
+
 ```solidity
 bytes32 orderHash,
 address target,
@@ -459,8 +512,8 @@ bool success
 
 ## Contract Calls (Interactions)
 
-- `BridgeRegistry`: this contract is called to process orders and to manage validator roles and fees. It acts as the central registry for approved tokens, relayers and validators. 
-- `ITimeLock`: the `ITimeLock` interface is utilized to interact with the [`timeLock`](#timelock) contract by calling the `createAgreement` function when bridged amounts exceeds the threshold.
-- `IBurnable`: this interface is used for burnable tokens to enable mint and burn operations.
-- `ERC20`:  all approved tokens within the bridge must implement the `ERC20Fixed` standard, which is an XLink's custom standard that extends ERC-20 to handle fixed precision. Token contract interactions occur in both peg-in and peg-out operations for non-burnable tokens, using the `transferFromFixed`, `transferFixed`, and `increaseAllowanceFixed` functions.
-- `SwapExecutor`: this contract is called by `BridgeEndpointWithSwap` to execute swaps with external liquidity aggregators during bridging.
+* `BridgeRegistry`: this contract is called to process orders and to manage validator roles and fees. It acts as the central registry for approved tokens, relayers and validators.
+* `ITimeLock`: the `ITimeLock` interface is utilized to interact with the [`timeLock`](BridgeEndpoint.md#timelock) contract by calling the `createAgreement` function when bridged amounts exceeds the threshold.
+* `IBurnable`: this interface is used for burnable tokens to enable mint and burn operations.
+* `ERC20`: all approved tokens within the bridge must implement the `ERC20Fixed` standard, which is an Brotocol's custom standard that extends ERC-20 to handle fixed precision. Token contract interactions occur in both peg-in and peg-out operations for non-burnable tokens, using the `transferFromFixed`, `transferFixed`, and `increaseAllowanceFixed` functions.
+* `SwapExecutor`: this contract is called by `BridgeEndpointWithSwap` to execute swaps with external liquidity aggregators during bridging.

developers/contracts/README.md

@@ -1,47 +1,49 @@
-# XLink Contracts Technical Documentation
+# Smart Contracts
 
-XLink core functionalities are contained in contracts deployed within the Stacks blockchain network. Its main goal is to provide a bridging mechanism, allowing the transfer of different tokens between Bitcoin or EVM-like chains and Stacks network. The possibility to add token swaps to the bridging processes are offered to the users as well.
-It is also worth mentioning that XLink has a staking feature available for the users and a Governance System that allows certain ecosystem decisions to be made together. 
-The purpose of this document is to give the reader a high-level overview of the different modules that constitute the XLink ecosystem and how some of the contracts interact.
+Brotocol core functionalities are contained in contracts deployed within the Stacks blockchain network. Its main goal is to provide a bridging mechanism, allowing the transfer of different tokens between Bitcoin or EVM-like chains and Stacks network. 
+
+The possibility to add token swaps to the bridging processes are offered to the users as well. It is also worth mentioning that Brotocol has a staking feature available for the users and a Governance System that allows certain ecosystem decisions to be made together. 
+
+The purpose of this document is to give the reader a high-level overview of the different modules that constitute the Brotocol ecosystem and how some of the contracts interact.
 
 ## Main Features
 
-The XLink ecosystem offers three main features that are implemented along different contracts. These are:
+The Brotocol ecosystem offers three main features that are implemented along different contracts. These are:
 
-- The **bridging of BTC**: this feature allows the transfer of BTC from the Bitcoin blockchain into the Stacks chain, where it will be represented as bridged BTC (aBTC) and the other way around.
-- The **bridging of BRC-20 assets**: this feature allows the transfer of assets that comply with the BRC-20 standard from the Bitcoin chain into the Stacks chain and vice versa.
-- The **bridging of EVM-like blockchain's assets**: this feature allows the transfer of assets back and forth between Stacks and several different blockchains that function based on the Ethereum Virtual Machine.
+* The **bridging of BTC**: this feature allows the transfer of BTC from the Bitcoin blockchain into the Stacks chain, where it will be represented as bridged BTC (aBTC) and the other way around.
+* The **bridging of BRC-20 assets**: this feature allows the transfer of assets that comply with the BRC-20 standard from the Bitcoin chain into the Stacks chain and vice versa.
+* The **bridging of EVM-like blockchain's assets**: this feature allows the transfer of assets back and forth between Stacks and several different blockchains that function based on the Ethereum Virtual Machine.
 
 ### BTC Bridge (Bitcoin's BTC <-> Stacks' aBTC)
 
 ![This is a simplified representation on the BTC Bridge main goal.](../../.gitbook/assets/glue-docs/btc-bridge.png)
 
-\*To see more information on this contract see the [auxiliary contracts section](#auxiliary-contracts).
+\*To see more information on this contract see the [auxiliary contracts section](./#auxiliary-contracts).
 
 #### 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`, `btc-peg-in-v2-07a-agg`.
-- [Complete technical documentation](btc-peg-in-endpoint.md)
+* 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).
 
 #### BTC Peg-Out Endpoint
 
-- Contract name: `btc-peg-out-endpoint-v2-01`
-- [Complete technical documentation](btc-peg-out-endpoint.md)
+* Contract name: `btc-peg-out-endpoint-v2-01`
+* [Complete technical documentation](btc-peg-out-endpoint.md)
 
 This endpoint is responsible for managing the bridging of Stacks' aBTC back to the Bitcoin blockchain as BTC.
 
 ### Meta Bridge (Bitcoin's BRC-20 <-> Stacks' SIP-010)
 
-![This is a simplified representation on the Meta Bridge main goal. ](../../.gitbook/assets/glue-docs/meta-bridge.png)
+![This is a simplified representation on the Meta Bridge main goal.](../../.gitbook/assets/glue-docs/meta-bridge.png)
 
-\*To see more information on these contracts see the [auxiliary contracts section](#auxiliary-contracts).</small>
+\*To see more information on these contracts see the [auxiliary contracts section](./#auxiliary-contracts).
 
 #### Meta Peg-In Endpoint
 
-- Contract names: `meta-peg-in-endpoint-v2-04`, `meta-peg-in-endpoint-v2-04-lisa`, `meta-peg-in-v2-06-swap`.
-- [Complete technical documentation](meta-peg-in-endpoint.md)
+* Contract names: `meta-peg-in-endpoint-v2-04`, `meta-peg-in-endpoint-v2-04-lisa`, `meta-peg-in-v2-06-swap`.
+* [Complete technical documentation](meta-peg-in-endpoint.md)
 
 This endpoint's main responsibility the bridging of assets in the Bitcoin chain that follow the BRC-20 standard into the Stacks chain as a specific token that complies with the `SIP-010` standard.
 
@@ -49,8 +51,8 @@ This endpoint's main responsibility the bridging of assets in the Bitcoin chain
 
 #### Meta Peg-Out Endpoint
 
-- Contract name: `meta-peg-out-endpoint-v2-04`
-- [Complete technical documentation](meta-peg-out-endpoint.md)
+* Contract name: `meta-peg-out-endpoint-v2-04`
+* [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.
 
@@ -58,19 +60,19 @@ This endpoint manages the bridging of tokens from the Stacks chain back to the B
 
 ![This is a simplified representation on the Cross Bridge main goal.](../../.gitbook/assets/glue-docs/cross-bridge.png)
 
-\*To see more information on these contracts see the [auxiliary contracts section](#auxiliary-contracts).</small>
+\*To see more information on these contracts see the [auxiliary contracts section](./#auxiliary-contracts).
 
 #### Cross Peg-In Endpoint
 
-- Contract names: `cross-peg-in-endpoint-v2-04`, `cross-peg-in-v2-04-launchpad`, `cross-peg-in-v2-04-swap`.
-- [Complete technical documentation](cross-peg-in-endpoint.md)
+* Contract names: `cross-peg-in-endpoint-v2-04`, `cross-peg-in-v2-04-launchpad`, `cross-peg-in-v2-04-swap`.
+* [Complete technical documentation](cross-peg-in-endpoint.md)
 
 This endpoint is responsible for managing the transfer of assets from other EVM-like blockchains into the Stacks chain, where they are represented as `SIP-010` tokens. Sometimes, it also involves swapping to other tokens as part of the peg-in process.
 
 #### Cross Peg-Out Endpoint
 
-- Contract names: `cross-peg-out-endpoint-v2-01`, `cross-peg-out-v2-01-agg`.
-- [Complete technical documentation](cross-peg-out-endpoint.md)
+* 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.
 
@@ -78,23 +80,23 @@ This endpoint is responsible for managing the transfer of `SIP-010` bridged toke
 
 These contracts do not include the implementation of any core functionality but they serve as a support for other contracts to facilitate calculations and common storage management.
 
-- **BTC Bridge Registry**: when a user wants to bridge BTC from Bitcoin chain into Stacks' aBTC or the other way around, this contract keeps record of the generated orders and their statuses, allowing those who interact with it to consult a bridging operation validity and update the records as well. Its current version can be found at `btc-bridge-registry`.
-- **Meta Bridge Registry**: this registry contains information about the approved tokens for bridging. It allows other modules to validate whether the BRC-20 token can be bridged into Stacks. The last version in use can be found at `meta-bridge` file.
-- **Cross Bridge Registry**: this registry allows other contracts to validate, among other things, if a specific token (from an EVM-like chain) can be bridged into Stacks. It also keeps record of the created bridging orders and their statuses. The current used version can be found at `cross-bridge-registry` file.
-- **Cross Router**: this contract is used to verify that a route between two tokens that gives as an output at least the expected minimum amount when swapping exists. It can, certainly, include intermediate exchanges to reach the desired token, meaning that if a user wants to swap token A to obtain token C, there may be some intermediate swaps needed such as `token A -> token B -> token C`(this is related to the existence or not of pools that includes the tokens of interest). It interacts with the `amm-pool-v2-01` contract to perform the swaps. Currently, it can be found at `cross-router` file.
-- **Bridge Common**: this contract provides common helper functions to all the others. These auxiliary functions facilitate order creation, transaction decoding, and cross-chain routing validations. Its implementation can be found at `bridge-common` file.
-- **Clarity Bitcoin**: this contract contains auxiliary functions that allows its users to interpret Bitcoin transactions and their content from a buffer. It can be found at `clarity-bitcoin` file.
+* **BTC Bridge Registry**: when a user wants to bridge BTC from Bitcoin chain into Stacks' aBTC or the other way around, this contract keeps record of the generated orders and their statuses, allowing those who interact with it to consult a bridging operation validity and update the records as well. Its current version can be found at `btc-bridge-registry`.
+* **Meta Bridge Registry**: this registry contains information about the approved tokens for bridging. It allows other modules to validate whether the BRC-20 token can be bridged into Stacks. The last version in use can be found at `meta-bridge` file.
+* **Cross Bridge Registry**: this registry allows other contracts to validate, among other things, if a specific token (from an EVM-like chain) can be bridged into Stacks. It also keeps record of the created bridging orders and their statuses. The current used version can be found at `cross-bridge-registry` file.
+* **Cross Router**: this contract is used to verify that a route between two tokens that gives as an output at least the expected minimum amount when swapping exists. It can, certainly, include intermediate exchanges to reach the desired token, meaning that if a user wants to swap token A to obtain token C, there may be some intermediate swaps needed such as `token A -> token B -> token C`(this is related to the existence or not of pools that includes the tokens of interest). It interacts with the `amm-pool-v2-01` contract to perform the swaps. Currently, it can be found at `cross-router` file.
+* **Bridge Common**: this contract provides common helper functions to all the others. These auxiliary functions facilitate order creation, transaction decoding, and cross-chain routing validations. Its implementation can be found at `bridge-common` file.
+* **Clarity Bitcoin**: this contract contains auxiliary functions that allows its users to interpret Bitcoin transactions and their content from a buffer. It can be found at `clarity-bitcoin` file.
 
 ## Governance
 
-At the top of the on-chain architecture is the XLink DAO, accounting for XLink's governance in a rule-based, modular and flexible manner. Built upon Marvin Janssen's ExecutorDAO project, it operates based on the following core principles:
+At the top of the on-chain architecture is the Brotocol DAO, accounting for Brotocol's governance in a rule-based, modular and flexible manner. Built upon Marvin Janssen's ExecutorDAO project, it operates based on the following core principles:
 
-- Proposals are smart contracts.
-- The core executes, the extensions give form.
-- Ownership control happens via sending context.
+* Proposals are smart contracts.
+* The core executes, the extensions give form.
+* Ownership control happens via sending context.
 
 For technical details on the ExecutorDAO, refer to the project's [README.md](https://github.com/MarvinJanssen/executor-dao#readme).
 
-## XLink Staking
+## Brotocol Staking
 
-XLink also offers users the possibility to stake their tokens. To see detailed information on how the staking protocol works refer to [xlink-staking](https://docs.xlink.network/developers/contracts/xlink-staking).
+Brotocol also offers users the possibility to stake their tokens. To see detailed information on how the staking protocol works refer to[ brotocol-staking](xlink-staking.md).

developers/contracts/btc-peg-in-endpoint.md

@@ -1,23 +1,26 @@
-# 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), [btc-peg-in-v2-07a-agg](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.btc-peg-in-v2-07a-agg?chain=mainnet)
+# 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), [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 five 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.
-- `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`: 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.
+* `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.
+* `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`: 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)_
+
+_**(all contracts include the following variables unless otherwise specified)**_
+
 ### `fee-to-address`
 
-| Data     | Type   |
-| -------- | ------ |
+| 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.
@@ -44,10 +47,11 @@ The percentage fee charged for peg-in transactions. By default, this value is `0
 | -------- | ------ |
 | 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`.
+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 and btc-peg-in-v2-07a-agg)_
+### `btc-peg-outfee`
+
+_**(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)**_
 
 | Data     | Type   |
 | -------- | ------ |
@@ -55,8 +59,9 @@ 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 and btc-peg-in-v2-07a-agg)_
+### `btc-peg-out-min-fee`
+
+_**(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)**_
 
 | Data     | Type   |
 | -------- | ------ |
@@ -67,11 +72,13 @@ This variable sets the minimum fee required for BTC peg-out operations during cr
 ## 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`. If the validation or routing fails, a refund is executed.
 
-##### Parameters
+_**(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`. If the validation or routing fails, a refund is executed.
+
+**Parameters**
+
 ```lisp
 (tx (buff 32768))
 (block { header: (buff 80), height: uint })
@@ -84,12 +91,13 @@ Once the transaction is validated, the function calculates fees, verifies that t
 ```
 
 #### `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
+_**(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 })
@@ -101,12 +109,13 @@ It interacts with `.btc-bridge-registry-v2-01` contract to register transaction
 ```
 
 #### `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
+_**(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 })
@@ -122,12 +131,13 @@ 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
+_**(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 })
@@ -138,13 +148,12 @@ In case of any error, it invokes the internal [refund](btc-peg-in-endpoint.md#re
 
 ### `finalize-peg-in-agg`
 
-###### _(in contract btc-peg-in-v2-07a-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.
+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**
 
-##### Parameters
 ```lisp
 (tx (buff 32768))
 (block { header: (buff 80), height: uint })
@@ -156,123 +165,152 @@ Instead of keeping the minted aBTC within the Stacks ecosystem, this function di
 ```
 
 ### 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
+**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
+**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
+**Parameters**
+
 ```lisp
 (fee uint)
 ```
 
 #### `set-peg-in-min-fee`
+
 This feature allows to set the minimum fee required for a peg-in transaction.
 
-##### Parameters
+**Parameters**
+
 ```lisp
 (fee uint)
 ```
 
 #### `set-btc-peg-out-fee`
-###### _(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)_
+
+_**(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
+**Parameters**
+
 ```lisp
 (fee uint)
 ```
 
 #### `set-btc-peg-out-min-fee`
-###### _(only present in btc-peg-in-v2-07-swap and btc-peg-in-v2-07a-agg)_
+
+_**(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
+**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`, `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
-- `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.
+
+* `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
+
+**Parameters**
+
 ```lisp
 (tx (buff 32768))
 (output uint)
 ```
+
 #### `get-txid`
-##### Parameters
+
+**Parameters**
+
 ```lisp
 (tx (buff 32768))
 ```
+
 #### `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)
-- `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.
-- `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.
-- `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.
+
+* `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.
+* `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.
+* `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
 
-| Error Name       | Value         |
-| ---------------- | ------------- |
-| `err-unauthorised` | `(err u1000)` |
-| `err-paused`    | `(err u1001)` |
+| 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)` |
-
-<!-- Documentation Contract Template v0.1.0 -->
+| `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)` |

developers/contracts/btc-peg-out-endpoint.md

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

developers/contracts/cross-peg-out-endpoint.md

@@ -1,17 +1,19 @@
 # cross-peg-out-endpoint
 
-- 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)
+* 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 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. 
+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:
 
-- `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.
+* `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`
+
 | Data     | Type   |
 | -------- | ------ |
 | Variable | `bool` |
@@ -19,7 +21,8 @@ The core functionalities of the module are implemented through public and govern
 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)_
+
+_**(only present in cross-peg-out-endpoint-v2-01)**_
 
 | Data     | Type   |
 | -------- | ------ |
@@ -28,11 +31,12 @@ 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` |
+_**(only present in cross-peg-out-endpoint-v2-01)**_
+
+| Data | Type               |
+| ---- | ------------------ |
+| Map  | `principal → bool` |
 
 This map stores the whitelist status of users. Each entry associates a `principal` with a boolean value indicating whether they are authorized to perform peg-out transactions. When `use-whitelist` is set to `true`, users with a value of `true` in this map are whitelisted and permitted to participate in the process; otherwise, the whitelist is not enforced.
 
@@ -41,13 +45,13 @@ This map stores the whitelist status of users. Each entry associates a `principa
 ### Peg-out feature
 
 #### `transfer-to-unwrap`
-###### _(in contract cross-peg-out-endpoint-v2-01)_
 
-This function manages the peg-out process, enabling users to transfer `SIP-010` bridged tokens from the Stacks network to EVM-compatible blockchains. It begins by validating the transfer through the `validate-transfer-to-unwrap` function, performing checks such as token and chain approval, whitelist status, 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 the net amount directly from the user's balance or transfers the entire amount (including the fee) to the `cross-bridge-registry-v2-01`.
-At the end of the process, the function logs key destination details, including the `settle-address`, which represents the recipient's address on the EVM-compatible blockchain.
+_**(in contract cross-peg-out-endpoint-v2-01)**_
+
+This function manages the peg-out process, enabling users to transfer `SIP-010` bridged tokens from the Stacks network to EVM-compatible blockchains. It begins by validating the transfer through the `validate-transfer-to-unwrap` function, performing checks such as token and chain approval, whitelist status, 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 the net amount directly from the user's balance or transfers the entire amount (including the fee) to the `cross-bridge-registry-v2-01`. At the end of the process, the function logs key destination details, including the `settle-address`, which represents the recipient's address on the EVM-compatible blockchain.
+
+**Parameters**
 
-##### Parameters
 ```lisp
 (token-trait <ft-trait>)
 (amount-in-fixed uint) 
@@ -57,11 +61,9 @@ 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 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 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.
+_**(in contract cross-peg-out-v2-01-agg)**_
+
+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 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)
@@ -73,57 +75,70 @@ At this point, an event is emitted, signaling relayers to detect and forward the
 ```
 
 ### 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)_
+
+_**(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
+**Parameters**
+
 ```lisp
 (user principal)
 ```
 
 #### `get-paused`
+
 A read-only function that checks the operational status of the contract.
 
 #### `set-paused`
+
 A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.
 
-##### Parameters
+**Parameters**
+
 ```lisp
 (paused bool)
 ```
 
 #### `apply-whitelist`
-###### _(only present in cross-peg-out-endpoint-v2-01)_
+
+_**(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
+**Parameters**
+
 ```lisp
 (new-use-whitelist bool)
 ```
 
 #### `whitelist`
-###### _(only present in cross-peg-out-endpoint-v2-01)_
+
+_**(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
+**Parameters**
+
 ```lisp
 (user principal)
 (whitelisted bool)
 ```
 
 #### `whitelist-many`
-###### _(only present in cross-peg-out-endpoint-v2-01)_
+
+_**(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
+**Parameters**
+
 ```lisp
 (users (list 2000 principal))
 (whitelisted (list 2000 bool))
@@ -132,43 +147,53 @@ 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)_
+
+_**(only present in cross-peg-out-endpoint-v2-01)**_
 
 #### `get-approved-chain-or-fail`
-##### Parameters
+
+**Parameters**
+
 ```lisp
 (dest-chain-id uint)
 ```
+
 #### `get-token-reserve-or-default`
-##### Parameters
+
+**Parameters**
+
 ```lisp
 (pair { token: principal, chain-id: uint })
 ```
+
 #### `get-min-fee-or-default`
-##### Parameters
+
+**Parameters**
+
 ```lisp
 (pair { token: principal, chain-id: uint })
 ```
+
 #### `get-approved-pair-or-fail`
-##### Parameters
+
+**Parameters**
+
 ```lisp
 (pair { token: principal, chain-id: uint })
 ```
 
 ## Contract calls (interactions)
-- `executor-dao`: Calls are made to verify whether a certain contract-caller is designated as an extension.
-- `cross-bridge-registry-v2-01`: This contract is called to verify key components of the peg-out process. It validates approved tokens and chain pairings, manages the deduction and queries of token reserves, and records accrued fees. It also handles updates to transaction statuses.
-- `token-trait`: In the cross-peg-out process, this trait is employed to manage token operations such as burning tokens when required or transferring them to the `cross-bridge-registry-v2-01` contract. It is a customized version of Stacks' standard definition for Fungible Tokens (`sip-010`), with support for 8-digit fixed notation.
+
+* `executor-dao`: Calls are made to verify whether a certain contract-caller is designated as an extension.
+* `cross-bridge-registry-v2-01`: This contract is called to verify key components of the peg-out process. It validates approved tokens and chain pairings, manages the deduction and queries of token reserves, and records accrued fees. It also handles updates to transaction statuses.
+* `token-trait`: In the cross-peg-out process, this trait is employed to manage token operations such as burning tokens when required or transferring them to the `cross-bridge-registry-v2-01` contract. It is a customized version of Stacks' standard definition for Fungible Tokens (`sip-010`), with support for 8-digit fixed notation.
 
 ## Errors
 
-| Error Name       | Value         |
-| ---------------- | ------------- |
-| `ERR-NOT-AUTHORIZED` | `(err u1000)` |
-| `ERR-PAUSED`    | `(err u1015)` |
-| `ERR-USER-NOT-WHITELISTED` | `(err u1016)` |
-| `ERR-AMOUNT-LESS-THAN-MIN-FEE`    | `(err u1017)` |
-| `ERR-INVALID-AMOUNT`   | `(err u1019)` |
-
-
-<!-- Documentation Contract Template v0.1.0 -->
+| Error Name                     | Value         |
+| ------------------------------ | ------------- |
+| `ERR-NOT-AUTHORIZED`           | `(err u1000)` |
+| `ERR-PAUSED`                   | `(err u1015)` |
+| `ERR-USER-NOT-WHITELISTED`     | `(err u1016)` |
+| `ERR-AMOUNT-LESS-THAN-MIN-FEE` | `(err u1017)` |
+| `ERR-INVALID-AMOUNT`           | `(err u1019)` |

developers/contracts/meta-peg-in-endpoint.md

@@ -1,29 +1,32 @@
-# meta-peg-in-endpoint
-- Location: `xlink/packages/contracts/bridge-stacks/contracts`
-- Deployed contracts: [meta-peg-in-endpoint-v2-04](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.meta-peg-in-endpoint-v2-04?chain=mainnet), [meta-peg-in-endpoint-v2-04-lisa](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.meta-peg-in-endpoint-v2-04-lisa?chain=mainnet), [meta-peg-in-v2-06-swap](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.meta-peg-in-v2-06-swap?chain=mainnet).
+# meta peg-in endpoint
+
+* Location: `xlink/packages/contracts/bridge-stacks/contracts`
+* Deployed contracts: [meta-peg-in-endpoint-v2-04](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.meta-peg-in-endpoint-v2-04?chain=mainnet), [meta-peg-in-endpoint-v2-04-lisa](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.meta-peg-in-endpoint-v2-04-lisa?chain=mainnet), [meta-peg-in-v2-06-swap](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.meta-peg-in-v2-06-swap?chain=mainnet).
 
 This technical document provides a comprehensive overview on the module responsible for the peg-in (bridging) of Bitcoin's BRC-20 assets to the Stacks network. BRC-20 is a token standard on Bitcoin's metaprotocol layer, enabling fungible assets similar to Ethereum's ERC-20. The module's core functionality is implemented through a series of public functions distributed across multiple specialized contracts, each addressing specific aspects of the peg-in process.
 
 This functionality is implemented and distributed across the following contracts:
 
-- `meta-peg-in-endpoint-v2-04`: facilitates the bridging of BRC-20 tokens from Bitcoin to Stacks, leveraging cross-router for routing to the appropriate destination.
-- `meta-peg-in-endpoint-v2-04-lisa`: facilitates peg-in operations for BRC-20 tokens from Bitcoin that involve burning LiaBTC tokens within the ALEX system.
-- `meta-peg-in-v2-06-swap`: facilitates peg-in operations for BRC-20 tokens from Bitcoin to Stacks with integrated asset swapping capabilities.
+* `meta-peg-in-endpoint-v2-04`: facilitates the bridging of BRC-20 tokens from Bitcoin to Stacks, leveraging cross-router for routing to the appropriate destination.
+* `meta-peg-in-endpoint-v2-04-lisa`: facilitates peg-in operations for BRC-20 tokens from Bitcoin that involve burning LiaBTC tokens within the ALEX system.
+* `meta-peg-in-v2-06-swap`: facilitates peg-in operations for BRC-20 tokens from Bitcoin to Stacks with integrated asset swapping capabilities.
 
 ## Storage
-###### _(all contracts include the following variables unless otherwise specified)_
+
+_**(all contracts include the following variables unless otherwise specified)**_
+
 ### `paused`
 
 | Data     | Type   |
 | -------- | ------ |
 | Variable | `bool` |
 
-This data variable serves as a flag to control the operational status of the contract. When set to `true`, all meta peg-in transactions are suspended. By default, the contract is deployed in *paused* mode. Refer to the [pause](meta-peg-in-endpoint.md#pause) governance feature to know more on how to change this status.
+This data variable serves as a flag to control the operational status of the contract. When set to `true`, all meta peg-in transactions are suspended. By default, the contract is deployed in _paused_ mode. Refer to the [pause](meta-peg-in-endpoint.md#pause) governance feature to know more on how to change this status.
 
 ### `fee-to-address`
 
-| Data     | Type   |
-| -------- | ------ |
+| Data     | Type        |
+| -------- | ----------- |
 | Variable | `principal` |
 
 This is the address where fees, charged in Bridged BTC tokens (token-abtc), are sent. By default, this address is the `tx-sender` who deployed the contract.
@@ -37,7 +40,8 @@ This is the address where fees, charged in Bridged BTC tokens (token-abtc), are
 This value represents the fee required for peg-in operations, expressed in fixed BTC (Bitcoin's base unit: satoshis). Fee amounts below this limit will be rejected with the error `err-invalid-amount`. By default, this value is set to `0`.
 
 ### `btc-peg-out-fee`
-###### _(only present in meta-peg-in-v2-06-swap)_
+
+_**(only present in meta-peg-in-v2-06-swap)**_
 
 | Data     | Type   |
 | -------- | ------ |
@@ -46,7 +50,8 @@ This value represents the fee required for peg-in operations, expressed in fixed
 This variable represents the percentage fee applied to BTC peg-out operations during cross-swap transactions. By default, it is initialized to `u0` and can be updated via governance functions. Refer to the [set-btc-peg-out-fee](meta-peg-in-endpoint.md#set-btc-peg-out-fee) governance feature to know more about updating this variable.
 
 ### `btc-peg-out-min-fee`
-###### _(only present in meta-peg-in-v2-06-swap)_
+
+_**(only present in meta-peg-in-v2-06-swap)**_
 
 | Data     | Type   |
 | -------- | ------ |
@@ -58,21 +63,21 @@ This variable sets the minimum fee required for BTC peg-out operations during cr
 
 #### `burn-height-start`
 
-| Type   | Value |
-| ------ | ----- |
-| `uint` |`burn-block-height` [(see more)](https://docs.stacks.co/reference/keywords#burn-block-height)  |
+| Type   | Value                                                                                         |
+| ------ | --------------------------------------------------------------------------------------------- |
+| `uint` | `burn-block-height` [(see more)](https://docs.stacks.co/reference/keywords#burn-block-height) |
 
 This constant denotes the block height at which the contract was deployed on the underlying burn blockchain. It serves to restrict operations to only include transactions minted from this block onward.
 
 ## Features
 
 #### `finalize-peg-in-cross-on-index`
-###### _(in contract meta-peg-in-endpoint-v2-04)_
 
-This function processes the order recipient, which is extracted and decoded from the provided reveal transaction. The reveal transaction contains additional details about the peg-in operation, such as the recipient's address and the `order-idx`. In this scenario, the recipient may be on a different blockchain. To facilitate the peg-in process, the contract calls the supporting contract `cross-router-v2-03`, to route the tokens based on the destination chain.
-As this peg-in feature is designed for Bitcoin metaprotocol tokens (e.g., BRC-20), the primary objective of this function is to facilitate 'crossing' to an EVM network. In such cases, the `cross-router-v2-03` contract will subsequently call `cross-peg-out-endpoint-v2-01` to execute the transfer of BRC-20 tokens from Bitcoin to an EVM chain. If any errors occur during the cross-transaction data validation, the function triggers a refund mechanism.
+_**(in contract meta-peg-in-endpoint-v2-04)**_
 
-##### Parameters
+This function processes the order recipient, which is extracted and decoded from the provided reveal transaction. The reveal transaction contains additional details about the peg-in operation, such as the recipient's address and the `order-idx`. In this scenario, the recipient may be on a different blockchain. To facilitate the peg-in process, the contract calls the supporting contract `cross-router-v2-03`, to route the tokens based on the destination chain. As this peg-in feature is designed for Bitcoin metaprotocol tokens (e.g., BRC-20), the primary objective of this function is to facilitate 'crossing' to an EVM network. In such cases, the `cross-router-v2-03` contract will subsequently call `cross-peg-out-endpoint-v2-01` to execute the transfer of BRC-20 tokens from Bitcoin to an EVM chain. If any errors occur during the cross-transaction data validation, the function triggers a refund mechanism.
+
+**Parameters**
 
 ```lisp
 (tx { 
@@ -102,11 +107,12 @@ As this peg-in feature is designed for Bitcoin metaprotocol tokens (e.g., BRC-20
 ```
 
 #### `finalize-peg-in-cross-swap-on-index`
-###### _(in contract meta-peg-in-v2-06-swap)_
+
+_**(in contract meta-peg-in-v2-06-swap)**_
 
 Similar to the peg-in-cross, the peg-in-cross-swap involves a cross-blockchain operation with an additional asset swapping capability. This feature is useful when the desired target token requires intermediate swap operations. The function achieves this by receiving a list of token traits (interfaces that define the behavior of tokens in the operation) involved in the operation up to the target token. Refer to the [AMM Pool documentation](https://docs.alexgo.io/developers/protocol-contracts#amm-trading-pool) for more details. In addition to the sender (from) and recipient (to) addresses, the order details in the reveal transaction include information about the swap route. This swap route is validated against the `amm-pool-v2-01` contract through the `cross-router-v2-03` contract to check pool parameters. Additionally, this function includes a refund mechanism that gets triggered in case any errors occur during the cross-swap transaction validation.
 
-##### Parameters
+**Parameters**
 
 ```lisp
 (tx {
@@ -132,12 +138,12 @@ Similar to the peg-in-cross, the peg-in-cross-swap involves a cross-blockchain o
 ```
 
 #### `finalize-peg-in-request-burn-liabtc-on-index`
-###### _(in contract meta-peg-in-endpoint-v2-04-lisa)_
-This function handles a peg-in operation that involves requesting the burn of LiaBTC tokens in the ALEX system. It begins by indexing the provided Bitcoin transaction using the `oracle-v2-01` contract to verify its validity and ensure it has not been processed before. Once the transaction is validated, the function calls `finalize-peg-in-request-burn-liabtc` to complete the burn request.
-The function interacts with the `meta-bridge-registry-v2-03-lisa` contract to retrieve and validate token pair details, which refer to the registered combination of a token and its target chain ID, and with the `liabtc-mint-endpoint` to register the burn request. Additionally, it utilizes the `clarity-bitcoin-v1-07` contract to extract transaction details such as the SegWit transaction ID. Any accrued rewards or updates, which are likely tied to the use or staking of LiaBTC tokens within the ALEX system, are processed through the provided `liabtc-message` and validated using signature packs.
-The function includes mechanisms to handle fees, using the `btc-bridge-registry-v2-01` contract to register these transactions and to ensure the peg-in-fee is properly accounted for. 
 
-##### Parameters
+_**(in contract meta-peg-in-endpoint-v2-04-lisa)**_
+
+This function handles a peg-in operation that involves requesting the burn of LiaBTC tokens in the ALEX system. It begins by indexing the provided Bitcoin transaction using the `oracle-v2-01` contract to verify its validity and ensure it has not been processed before. Once the transaction is validated, the function calls `finalize-peg-in-request-burn-liabtc` to complete the burn request. The function interacts with the `meta-bridge-registry-v2-03-lisa` contract to retrieve and validate token pair details, which refer to the registered combination of a token and its target chain ID, and with the `liabtc-mint-endpoint` to register the burn request. Additionally, it utilizes the `clarity-bitcoin-v1-07` contract to extract transaction details such as the SegWit transaction ID. Any accrued rewards or updates, which are likely tied to the use or staking of LiaBTC tokens within the ALEX system, are processed through the provided `liabtc-message` and validated using signature packs. The function includes mechanisms to handle fees, using the `btc-bridge-registry-v2-01` contract to register these transactions and to ensure the peg-in-fee is properly accounted for.
+
+**Parameters**
 
 ```lisp
 (tx { 
@@ -167,11 +173,12 @@ The function includes mechanisms to handle fees, using the `btc-bridge-registry-
 ```
 
 #### `finalize-peg-in-update-burn-liabtc`
-###### _(in contract meta-peg-in-endpoint-v2-04-lisa)_
-This function finalizes or revokes a burn request for LiaBTC tokens initiated in the ALEX system. It validates the Bitcoin transaction through the `oracle-v2-01` contract, ensuring it was mined and indexed correctly. It interacts with the `meta-bridge-registry-v2-03-lisa` contract to verify the status of the burn request and update its details.
-If the burn request is finalized (status `0x01`), the function confirms the burn through the `liabtc-mint-endpoint` and completes the operation. For revocations (status `0x02`), the function handles re-minting of LiaBTC tokens and executes a peg-out process using the `meta-peg-out-endpoint-v2-04`.
 
-##### Parameters
+_**(in contract meta-peg-in-endpoint-v2-04-lisa)**_
+
+This function finalizes or revokes a burn request for LiaBTC tokens initiated in the ALEX system. It validates the Bitcoin transaction through the `oracle-v2-01` contract, ensuring it was mined and indexed correctly. It interacts with the `meta-bridge-registry-v2-03-lisa` contract to verify the status of the burn request and update its details. If the burn request is finalized (status `0x01`), the function confirms the burn through the `liabtc-mint-endpoint` and completes the operation. For revocations (status `0x02`), the function handles re-minting of LiaBTC tokens and executes a peg-out process using the `meta-peg-out-endpoint-v2-04`.
+
+**Parameters**
 
 ```lisp
 (commit-tx { tx: (buff 32768), fee-idx: (optional uint) })  
@@ -200,57 +207,73 @@ The following functions are tools to assist the off-chain activities.
 ### Governance features
 
 #### `is-dao-or-extension`
+
 This standard protocol function checks whether a caller (`tx-sender`) is the DAO executor or an authorized extension, delegating the extensions check to the `executor-dao` contract.
 
 #### `is-paused`
+
 A read-only function that checks the operational status of the contract.
 
 #### `pause`
+
 A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.
 
-##### Parameters
+**Parameters**
+
 ```lisp
 (new-paused bool)
 ```
 
 #### `transfer-all-to-many`
+
 This contract feature is designed to transfer its entire balance of a specified list of tokens to a new owner. Access to this feature is restricted by the `is-dao-or-extension` function.
 
-##### Parameters
+**Parameters**
+
 ```lisp
 (new-owner principal) (token-traits (list 10 <ft-trait>))
 ```
 
 #### `set-fee-to-address`
+
 A public function, governed through the `is-dao-or-extension`, that sets the address to which the fee in Bridged BTC tokens will be transferred.
 
-##### Parameters
+**Parameters**
+
 ```lisp
 (new-fee-to-address principal)
 ```
 
 #### `set-peg-in-fee`
+
 A public function, governed through the `is-dao-or-extension`, that establishes the fee to be deducted for the peg-in operation.
 
-##### Parameters
+**Parameters**
+
 ```lisp
 (fee uint)
 ```
 
 #### `set-btc-peg-out-fee`
-###### _(only present in meta-peg-in-v2-06-swap)_
+
+_**(only present in meta-peg-in-v2-06-swap)**_
+
 A public function, governed through the `is-dao-or-extension`, that sets the percentage fee applied to BTC peg-out operations.
 
-##### Parameters
+**Parameters**
+
 ```lisp
 (fee uint)
 ```
 
 #### `set-btc-peg-out-min-fee`
-###### _(only present in meta-peg-in-v2-06-swap)_
+
+_**(only present in meta-peg-in-v2-06-swap)**_
+
 A public function, governed through the `is-dao-or-extension`, that establishes the minimum fee required for BTC peg-out operations.
 
-##### Parameters
+**Parameters**
+
 ```lisp
 (fee uint)
 ```
@@ -292,28 +315,25 @@ A public function, governed through the `is-dao-or-extension`, that establishes
 
 ## Errors
 
-| Error Name                        | Value         |
-| --------------------------------- | ------------- |
-| `err-unauthorised`                | `(err u1000)` |
-| `err-paused`                      | `(err u1001)` |
-| `err-peg-in-address-not-found`    | `(err u1002)` |
-| `err-invalid-amount`              | `(err u1003)` |
-| `err-token-mismatch`              | `(err u1004)` |
-| `err-invalid-tx`                  | `(err u1005)` |
-| `err-already-sent`                | `(err u1006)` |
-| `err-address-mismatch`            | `(err u1007)` |
-| `err-request-already-revoked`     | `(err u1008)` |
-| `err-request-already-finalized`   | `(err u1009)` |
-| `err-revoke-grace-period`         | `(err u1010)` |
-| `err-request-already-claimed`     | `(err u1011)` |
-| `err-invalid-input`               | `(err u1012)` |
-| `err-tx-mined-before-request`     | `(err u1013)` |
-| `err-commit-tx-mismatch`          | `(err u1014)` |
-| `err-invalid-burn-height`         | `(err u1003)` |
-| `err-tx-mined-before-start`       | `(err u1015)` |
-| `err-slippage-error`              | `(err u1016)` |
-| `err-bitcoin-tx-not-mined`        | `(err u1017)` |
-| `err-invalid-request` _(only present in meta-peg-in-endpoint-v2-04-lisa)_      | `(err u1018)` |
-
-
-<!-- Documentation Contract Template v0.1.0 -->
+| Error Name                                                                | Value         |
+| ------------------------------------------------------------------------- | ------------- |
+| `err-unauthorised`                                                        | `(err u1000)` |
+| `err-paused`                                                              | `(err u1001)` |
+| `err-peg-in-address-not-found`                                            | `(err u1002)` |
+| `err-invalid-amount`                                                      | `(err u1003)` |
+| `err-token-mismatch`                                                      | `(err u1004)` |
+| `err-invalid-tx`                                                          | `(err u1005)` |
+| `err-already-sent`                                                        | `(err u1006)` |
+| `err-address-mismatch`                                                    | `(err u1007)` |
+| `err-request-already-revoked`                                             | `(err u1008)` |
+| `err-request-already-finalized`                                           | `(err u1009)` |
+| `err-revoke-grace-period`                                                 | `(err u1010)` |
+| `err-request-already-claimed`                                             | `(err u1011)` |
+| `err-invalid-input`                                                       | `(err u1012)` |
+| `err-tx-mined-before-request`                                             | `(err u1013)` |
+| `err-commit-tx-mismatch`                                                  | `(err u1014)` |
+| `err-invalid-burn-height`                                                 | `(err u1003)` |
+| `err-tx-mined-before-start`                                               | `(err u1015)` |
+| `err-slippage-error`                                                      | `(err u1016)` |
+| `err-bitcoin-tx-not-mined`                                                | `(err u1017)` |
+| `err-invalid-request` _(only present in meta-peg-in-endpoint-v2-04-lisa)_ | `(err u1018)` |

developers/contracts/meta-peg-out-endpoint.md

@@ -1,7 +1,7 @@
-# meta-peg-out-endpoint
+# meta peg-out endpoint
 
-- Location: `xlink/packages/contracts/bridge-stacks/contracts/meta-peg-out-endpoint-v2-04`
-- [Deployed contract](https://explorer.hiro.so/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.meta-peg-out-endpoint-v2-04?chain=mainnet)
+* Location: `xlink/packages/contracts/bridge-stacks/contracts/meta-peg-out-endpoint-v2-04`
+* [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.
 
@@ -15,12 +15,12 @@ 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. 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.
+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`
 
-| Data     | Type   |
-| -------- | ------ |
+| Data     | Type        |
+| -------- | ----------- |
 | Variable | `principal` |
 
 This variable represents the address to which fees are paid. In this contract, there are two categories of fees: peg-out fees and gas fees. 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.
@@ -29,31 +29,31 @@ This variable represents the address to which fees are paid. In this contract, t
 
 #### `burn-height-start`
 
-| Type   | Value |
-| ------ | ----- |
+| Type   | Value                                                                              |
+| ------ | ---------------------------------------------------------------------------------- |
 | `uint` | [`burn-block-height`](https://docs.stacks.co/reference/keywords#burn-block-height) |
 
 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 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.
+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 contract meta-peg-out-endpoint-v2-04)**_
 
 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:
 
-- 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).
+* 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, known as the `request-id`, ensuring traceability and reference for future operations.
 
-##### Parameters
+**Parameters**
 
 ```lisp
 (amount uint)
@@ -63,19 +63,20 @@ Once these validations are met, the operation is registered in the meta registry
 ```
 
 #### `claim-peg-out`
-###### _(in contract meta-peg-out-endpoint-v2-04)_
+
+_**(in contract meta-peg-out-endpoint-v2-04)**_
 
 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:
 
-- The request must exist.
-- The token pair must be approved and operational (not paused for peg-out).
-- The request must not be revoked, finalized, or previously claimed.
+* The request must exist.
+* The token pair must be approved and operational (not paused for peg-out).
+* The request must not be revoked, finalized, or previously claimed.
 
 Once these conditions are met, the final step is to register the claim in the meta registry. This registration includes the claimer, the fulfilled-by address and the calculated grace period, during which the claimed request will be eligible for finalization.
 
-##### Parameters
+**Parameters**
 
 ```lisp
 (request-id uint)
@@ -83,30 +84,31 @@ 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 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.
+_**(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 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.
-- The token pair must be approved and operational (not paused for peg-out).
-- 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 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 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 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 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).
+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).
+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.
+   * 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.
 
-##### Parameters
+**Parameters**
 
 ```lisp
 (request-id uint)
@@ -128,18 +130,19 @@ This operation involves indexing the specified transaction through the `oracle-v
 ```
 
 #### `revoke-peg-out`
-###### _(in contract meta-peg-out-endpoint-v2-04)_
+
+_**(in contract meta-peg-out-endpoint-v2-04)**_
 
 In certain scenarios, a requested peg-out may need to be revoked, allowing users to retract it if necessary.
 
 Key validations include:
 
-- The request must be revoked within the grace period before it expires.
-- The request must not have been claimed, finalized, or previously revoked.
+* 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`.
 
-##### Parameters
+**Parameters**
 
 ```lisp
 (request-id uint)
@@ -167,7 +170,7 @@ A read-only function that checks the operational status of the contract.
 
 A public function, governed through the `is-dao-or-extension`, that can change the contract's operational status.
 
-##### Parameters
+**Parameters**
 
 ```lisp
 (new-paused bool)
@@ -177,7 +180,7 @@ A public function, governed through the `is-dao-or-extension`, that can change t
 
 This contract feature is designed to transfer its entire balance of a specified list of tokens to a new owner. Access to this feature is restricted by the `is-dao-or-extension` function.
 
-##### Parameters
+**Parameters**
 
 ```lisp
 (new-owner principal) (token-traits (list 10 <ft-trait>))
@@ -187,7 +190,7 @@ This contract feature is designed to transfer its entire balance of a specified
 
 This contract feature allows for specifying the address to which peg-out fees (denominated in the relevant tokens) and gas fees (denominated in Bridged BTC tokens, known as `token-abtc`) will be transferred.
 
-##### Parameters
+**Parameters**
 
 ```lisp
 (new-fee-to-address principal)
@@ -221,25 +224,22 @@ This contract feature allows for specifying the address to which peg-out fees (d
 
 ## Errors
 
-| Error Name                        | Value         |
-| --------------------------------- | ------------- |
-| `err-unauthorised`                | `(err u1000)` |
-| `err-paused`                      | `(err u1001)` |
-| `err-peg-in-address-not-found`    | `(err u1002)` |
-| `err-invalid-amount`              | `(err u1003)` |
-| `err-token-mismatch`              | `(err u1004)` |
-| `err-invalid-tx`                  | `(err u1005)` |
-| `err-already-sent`                | `(err u1006)` |
-| `err-address-mismatch`            | `(err u1007)` |
-| `err-request-already-revoked`     | `(err u1008)` |
-| `err-request-already-finalized`   | `(err u1009)` |
-| `err-revoke-grace-period`         | `(err u1010)` |
-| `err-request-already-claimed`     | `(err u1011)` |
-| `err-invalid-input`               | `(err u1012)` |
-| `err-tx-mined-before-request`     | `(err u1013)` |
-| `err-commit-tx-mismatch`          | `(err u1014)` |
-| `err-invalid-burn-height`         | `(err u1003)` |
-| `err-tx-mined-before-start`       | `(err u1015)` |
-
-
-<!-- Documentation Contract Template v0.1.0 -->
+| Error Name                      | Value         |
+| ------------------------------- | ------------- |
+| `err-unauthorised`              | `(err u1000)` |
+| `err-paused`                    | `(err u1001)` |
+| `err-peg-in-address-not-found`  | `(err u1002)` |
+| `err-invalid-amount`            | `(err u1003)` |
+| `err-token-mismatch`            | `(err u1004)` |
+| `err-invalid-tx`                | `(err u1005)` |
+| `err-already-sent`              | `(err u1006)` |
+| `err-address-mismatch`          | `(err u1007)` |
+| `err-request-already-revoked`   | `(err u1008)` |
+| `err-request-already-finalized` | `(err u1009)` |
+| `err-revoke-grace-period`       | `(err u1010)` |
+| `err-request-already-claimed`   | `(err u1011)` |
+| `err-invalid-input`             | `(err u1012)` |
+| `err-tx-mined-before-request`   | `(err u1013)` |
+| `err-commit-tx-mismatch`        | `(err u1014)` |
+| `err-invalid-burn-height`       | `(err u1003)` |
+| `err-tx-mined-before-start`     | `(err u1015)` |

developers/contracts/xlink-staking.md

@@ -1,21 +1,21 @@
-# xlink-staking
+# brotocol-staking
 
-- Location: `xlink-dao/contracts/aux/xlink-staking.clar`
-- [Deployed contract](https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.xlink-staking)
+* Location: `xlink-dao/contracts/aux/xlink-staking.clar`
+* [Deployed contract](https://explorer.stxer.xyz/txid/SP673Z4BPB4R73359K9HE55F2X91V5BJTN5SXZ5T.xlink-staking)
 
-The `xlink-staking` contract, also known as the **XLink Staking Manager**, is designed to manage liquid staking pools for multiple tokens and track staker positions within each pool. It holds users' staked funds, while the actual staking execution and reward reinvestment processes are managed off-chain by XLink's infrastructure.
+The `xlink-staking` contract, also known as the **Brotocol Staking Manager**, is designed to manage liquid staking pools for multiple tokens and track staker positions within each pool. It holds users' staked funds, while the actual staking execution and reward reinvestment processes are managed off-chain by Brotocol's infrastructure.
 
-The Staking Manager contract is part of a hybrid, token-agnostic liquid staking management system, that operates alongside off-chain backend and frontend components managed by XLink.
+The Staking Manager contract is part of a hybrid, token-agnostic liquid staking management system, that operates alongside off-chain backend and frontend components managed by Brotocol.
 
 ## Liquid staking
 
 The lifecycle of liquid staking pools is based on three main operations:
 
-1. **Staking**. Users deposit tokens into the `xlink-staking` contract, which are staked externally.
+1. **Staking**. Users deposit tokens into the `brotocol-staking` contract, which are staked externally.
 2. **Rewards accrual**. Rewards earned through the external staking protocol are periodically restaked, generating automatic compound interest for stakers.
 3. **Unstaking**. Users can withdraw their staked tokens, which include accumulated restaked rewards, at any time.
 
-These are the main three features of the `xlink-staking` contract. Each of these has an impact on the contract storage and generates on-chain events, which are listened by the XLink off-chain components to facilitate corresponding external staking operations.
+These are the main three features of the `brotocol-staking` contract. Each of these has an impact on the contract storage and generates on-chain events, which are listened by the Brotocol off-chain components to facilitate corresponding external staking operations.
 
 ### Shares-based staking
 
@@ -23,23 +23,23 @@ The system utilizes **shares** instead of token amounts to represent users' stak
 
 ## Reward accrual
 
-The account for the restaked rewards is permissionlessly performed by **updaters**, who submit messages signed by **validators**. This action is performed via the [`add-rewards`](#add-rewards) function and it's the core operation of the liquid staking mechanism.
+The account for the restaked rewards is permissionlessly performed by **updaters**, who submit messages signed by **validators**. This action is performed via the [`add-rewards`](xlink-staking.md#add-rewards) function and it's the core operation of the liquid staking mechanism.
 
-Validators are XLink protocol actors responsible for maintaining the system's integrity and synchronization. In this sense, their role includes generating a **proof** whenever rewards are successfully collected and restaked in the external protocol.
+Validators are Brotocol protocol actors responsible for maintaining the system's integrity and synchronization. In this sense, their role includes generating a **proof** whenever rewards are successfully collected and restaked in the external protocol.
 
 Each proof consists of a signed message indicating the token, the updated total accrued rewards, and a timestamp. Once updaters collect a sufficient number of proofs, they submit these to the Staking Manager to perform a state update.
 
-It is important to note that this operation does not involve shares management. The key state update is the total staked amount in the [`total-staked`](#total-staked) map.
+It is important to note that this operation does not involve shares management. The key state update is the total staked amount in the [`total-staked`](xlink-staking.md#total-staked) map.
 
 ## Stake / Unstake
 
 ### Authorization
 
-These operations are exclusively available for **governance** roles, as they are guarded by the [`is-dao-or-extension`](#is-dao-or-extension) function. What does this imply?
+These operations are exclusively available for **governance** roles, as they are guarded by the [`is-dao-or-extension`](xlink-staking.md#is-dao-or-extension) function. What does this imply?
 
-The [`stake`](#stake) and [`unstake`](#unstake) functions are designed to be called by a DAO extension acting as the `contract-caller`. Alternatively, in more exceptional cases, the `tx-sender` can be the DAO itself calling through a proposal contract.
+The [`stake`](xlink-staking.md#stake) and [`unstake`](xlink-staking.md#unstake) functions are designed to be called by a DAO extension acting as the `contract-caller`. Alternatively, in more exceptional cases, the `tx-sender` can be the DAO itself calling through a proposal contract.
 
-This setup implies that end users can only access these features indirectly through intermediary contracts (façade, endpoint, etc.) that must be enabled DAO extensions. The external call from the extension to the `xlink-staking` contract, a.k.a. Staking Manager, can be implemented in two ways, resulting in different authentications for the `tx-sender`, the staker.
+This setup implies that end users can only access these features indirectly through intermediary contracts (façade, endpoint, etc.) that must be enabled DAO extensions. The external call from the extension to the `brotocol-staking` contract, a.k.a. Staking Manager, can be implemented in two ways, resulting in different authentications for the `tx-sender`, the staker.
 
 In summary, these operations are typically accessed by users through intermediary contracts registered as DAO extensions. However, they can also be directly called by a proposal contract executed by the DAO.
 
@@ -72,9 +72,11 @@ flowchart LR
 
 ### Mechanics
 
-In the Staking Manager, the staker is represented by the `tx-sender`. As explained above, depending on the intermediary contract design, the staker may either be an end user or the endpoint/façade acting on behalf of the user. Therefore, every reference to "staker" (or `user`, as defined within the contract) applies to any of these two possibilities.
+In the Staking Manager, the staker is represented by the `tx-sender`. As explained above, depending on the intermediary contract design, the staker may either be an end user or the endpoint/façade acting on behalf of the user. 
 
-Upon staking, the shares corresponding to the amount being staked are calculated and stored in the [`user-shares`](#user-shares) map. This is the staking position and represents the user's portion of the total amount staked. During this operation, the amount to stake is transferred from the `tx-sender` to the Staking Manager, and since the total amount staked and total shares increased, the contract updates its internal state to reflect the changes. Refer to the [`stake`](#stake) function for detailed information.
+Therefore, every reference to "staker" (or `user`, as defined within the contract) applies to any of these two possibilities.
+
+Upon staking, the shares corresponding to the amount being staked are calculated and stored in the [`user-shares`](xlink-staking.md#user-shares) map. This is the staking position and represents the user's portion of the total amount staked. During this operation, the amount to stake is transferred from the `tx-sender` to the Staking Manager, and since the total amount staked and total shares increased, the contract updates its internal state to reflect the changes. Refer to the [`stake`](xlink-staking.md#stake) function for detailed information.
 
 Unstaking performs the inverse operations. It first calculates the shares that correspond to the amount willing to unstake. Then, the unstaked amount is transferred from the Staking Manager to the `tx-sender` and, finally, state upates are performed to decrease user shares, total shares and total amount staked.
 
@@ -90,7 +92,7 @@ $$
 \textrm{Shares} = \frac{\textrm{Amount}}{\textrm{Total Staked}} \; \cdot \; \textrm{Total Shares}.
 $$
 
-This is how [`get-shares-given-amount`](#supporting-features) function works. The ratio between the total staked amount and the total shares determines the "share price" in token units, i.e., how many tokens one share represents:
+This is how [`get-shares-given-amount`](xlink-staking.md#supporting-features) function works. The ratio between the total staked amount and the total shares determines the "share price" in token units, i.e., how many tokens one share represents:
 
 $$
 \textrm{Price} = \frac{\textrm{Total Staked}}{\textrm{Total Shares}}
@@ -102,43 +104,45 @@ Before completing a staking or unstaking operation, these two values are updated
 
 <summary>How does the share price remain constant after staking/unstaking operations?</summary>
 
-The price formula shows that the share price is the ratio between the staked tokens amount and the shares amount. Staking adds tokens, so to maintain the price, shares are issued at the price before the staking state update. Analogously, unstaking removes tokens, and to preserve the price, shares are burned at the same price as before the unstaking state update.
+The price formula shows that the share price is the ratio between the staked tokens amount and the shares amount. Staking adds tokens, so to maintain the price, shares are issued at the price before the staking state update.&#x20;
+
+Analogously, unstaking removes tokens, and to preserve the price, shares are burned at the same price as before the unstaking state update.
 
 </details>
 
 ## Roles
 
-- **Validators**: Trusted entities responsible for maintaining the system's integrity and synchronization. In the context of the XLink Staking Manager, they generate proofs of reward reinvestment on the external staking protocol.
-- **Updaters**: Actors resposible for submitting validator proofs to update the total staked value for any token in the system.
-- **Governance**: Includes DAO and its enabled extensions. These roles are authenticated via the [`is-dao-or-extension`](#is-dao-or-extension) function. Extensions are authenticated as `contract-caller`, while the DAO is authenticated as the `tx-sender` for proposal execution scenarios.
+* **Validators**: Trusted entities responsible for maintaining the system's integrity and synchronization. In the context of the Brotocol Staking Manager, they generate proofs of reward reinvestment on the external staking protocol.
+* **Updaters**: Actors resposible for submitting validator proofs to update the total staked value for any token in the system.
+* **Governance**: Includes DAO and its enabled extensions. These roles are authenticated via the [`is-dao-or-extension`](xlink-staking.md#is-dao-or-extension) function. Extensions are authenticated as `contract-caller`, while the DAO is authenticated as the `tx-sender` for proposal execution scenarios.
 
 ## Tokens
 
 Each token within the Staking Manager has the following attributes.
 
-- **Implementation contract**: The Stacks principal indicating the token's implementation contract, which needs to be approved in the [`approved-tokens`](#approved-tokens) map.
-- **Total staked**: The total staked amount, tracked in the [`total-staked`](#total-staked) map.
-- **Accrued rewards**: The total amount of rewards already restaked, tracked in the [`accrued-rewards`](#accrued-rewards) map.
-- **Total shares**: The total amount of shares issued for the token, tracked in the [`total-shares`](#total-shares) map.
-- **Staker registry**: The record of each staker's shares, where the sum of all staker shares equals the total shares. This ownership is tracked in the [`user-shares`](#user-shares) map.
+* **Implementation contract**: The Stacks principal indicating the token's implementation contract, which needs to be approved in the [`approved-tokens`](xlink-staking.md#approved-tokens) map.
+* **Total staked**: The total staked amount, tracked in the [`total-staked`](xlink-staking.md#total-staked) map.
+* **Accrued rewards**: The total amount of rewards already restaked, tracked in the [`accrued-rewards`](xlink-staking.md#accrued-rewards) map.
+* **Total shares**: The total amount of shares issued for the token, tracked in the [`total-shares`](xlink-staking.md#total-shares) map.
+* **Staker registry**: The record of each staker's shares, where the sum of all staker shares equals the total shares. This ownership is tracked in the [`user-shares`](xlink-staking.md#user-shares) map.
 
 ## Features
 
 ### Main operations
 
-These operations are privileged and protected by the [`is-dao-or-extension`](#is-dao-or-extension) function, allowing only governance roles to execute them. However, the [`add-rewards`](#add-rewards) function is more permissive than staking and unstaking, also allowing approved updaters as callers (`tx-sender`).
+These operations are privileged and protected by the [`is-dao-or-extension`](xlink-staking.md#is-dao-or-extension) function, allowing only governance roles to execute them. However, the [`add-rewards`](xlink-staking.md#add-rewards) function is more permissive than staking and unstaking, also allowing approved updaters as callers (`tx-sender`).
 
 #### `add-rewards`
 
-Adds accrued staking rewards for a specific token. The function requires a message `{ token: principal, accrued-rewards: uint, update-block: uint }` signed by a sufficient number of approved validators ([`required-validators`](#required-validators)). The message must be proccessed within a block range determined by the `update-block` value and [`block-threshold`](#block-threshold) variable, or it is considered expired.
+Adds accrued staking rewards for a specific token. The function requires a message `{ token: principal, accrued-rewards: uint, update-block: uint }` signed by a sufficient number of approved validators ([`required-validators`](xlink-staking.md#required-validators)). The message must be proccessed within a block range determined by the `update-block` value and [`block-threshold`](xlink-staking.md#block-threshold) variable, or it is considered expired.
 
 Actions performed:
 
-- Calculates the difference (`delta`) between the previous and the updated amount of accrued rewards, given by the `accrued-rewards` value of the message. Mints the `delta` amount to the `xlink-staking` contract's balance to account for the new staked amount.
-- Updates the [`accrued-rewards`](#accrued-rewards) and [`total-staked`](#total-staked) maps.
-- Emits an `"add-rewards"` log with a detailed payload.
+* Calculates the difference (`delta`) between the previous and the updated amount of accrued rewards, given by the `accrued-rewards` value of the message. Mints the `delta` amount to the `xlink-staking` contract's balance to account for the new staked amount.
+* Updates the [`accrued-rewards`](xlink-staking.md#accrued-rewards) and [`total-staked`](xlink-staking.md#total-staked) maps.
+* Emits an `"add-rewards"` log with a detailed payload.
 
-##### Parameters
+**Parameters**
 
 | Name              | Type                                                                              |
 | ----------------- | --------------------------------------------------------------------------------- |
@@ -152,13 +156,13 @@ Allows users to stake a specified token amount.
 
 Actions performed:
 
-- Calls `add-rewards` to update the total staked value if needed. Note this is very important since the `total-staked` value of the token is utilized to calculate the shares.
-- Calculates `shares` corresponding to the newly stake amount.
-- Transfers the specified amount from the `tx-sender` (user) to the `xlink-staking` contract.
-- Updates the `user-shares`, `total-shares` and `total-staked` maps.
-- Emits a `"stake"` log with a detailed payload (user, token, updated values).
+* Calls `add-rewards` to update the total staked value if needed. Note this is very important since the `total-staked` value of the token is utilized to calculate the shares.
+* Calculates `shares` corresponding to the newly stake amount.
+* Transfers the specified amount from the `tx-sender` (user) to the `brotocol-staking` contract.
+* Updates the `user-shares`, `total-shares` and `total-staked` maps.
+* Emits a `"stake"` log with a detailed payload (user, token, updated values).
 
-##### Parameters
+**Parameters**
 
 | Name              | Type                                                                              |
 | ----------------- | --------------------------------------------------------------------------------- |
@@ -173,13 +177,13 @@ Allows users to unstake a specified token amount.
 
 Actions performed:
 
-- As in [`stake`](#stake), calls `add-rewards` to update the total staked value if needed.
-- Calculates `shares` corresponding to the amount to unstake.
-- Transfers the specified amount from the `tx-sender` (user) to the `xlink-staking` contract.
-- Updates the `user-shares`, `total-shares` and `total-staked` map.
-- Emits an `"unstake"` log with a detailed payload (user, token, updated values).
+* As in [`stake`](xlink-staking.md#stake), calls `add-rewards` to update the total staked value if needed.
+* Calculates `shares` corresponding to the amount to unstake.
+* Transfers the specified amount from the `tx-sender` (user) to the `xlink-staking` contract.
+* Updates the `user-shares`, `total-shares` and `total-staked` map.
+* Emits an `"unstake"` log with a detailed payload (user, token, updated values).
 
-##### Parameters
+**Parameters**
 
 | Name              | Type                                                                              |
 | ----------------- | --------------------------------------------------------------------------------- |
@@ -190,20 +194,19 @@ Actions performed:
 
 ### Governance
 
-These features are protected by the [`is-dao-or-extension`](#is-dao-or-extension) function and resticted to the XLink DAO or its enabled extensions.
+These features are protected by the [`is-dao-or-extension`](xlink-staking.md#is-dao-or-extension) function and resticted to the XLink DAO or its enabled extensions.
 
 #### `withdraw`
 
-Withdraws an amount of any approved token and deducts it from the total staked amount. This function serves as an emergecy mechanism designed to adjust protocol values if necessary,
-though such a situation is considered rare.
+Withdraws an amount of any approved token and deducts it from the total staked amount. This function serves as an emergecy mechanism designed to adjust protocol values if necessary, though such a situation is considered rare.
 
 Actions performed:
 
-- Transfers the specified amount from the `xlink-staking` contract to the `tx-sender`.
-- Updates the `total-staked` map.
-- Emits a `"withdraw"` log and a payload.
+* Transfers the specified amount from the `brotocol-staking` contract to the `tx-sender`.
+* Updates the `total-staked` map.
+* Emits a `"withdraw"` log and a payload.
 
-##### Parameters
+**Parameters**
 
 | Name          | Type         |
 | ------------- | ------------ |
@@ -212,9 +215,9 @@ Actions performed:
 
 #### `set-paused`
 
-Sets the [`is-paused`](#is-paused) variable.
+Sets the [`is-paused`](xlink-staking.md#is-paused) variable.
 
-##### Parameters
+**Parameters**
 
 | Name     | Type   |
 | -------- | ------ |
@@ -222,9 +225,9 @@ Sets the [`is-paused`](#is-paused) variable.
 
 #### `set-approved-token`
 
-Sets the approval status of a token within the Staking Manager. Modifies the [`approved-tokens`](#approved-tokens) map.
+Sets the approval status of a token within the Staking Manager. Modifies the [`approved-tokens`](xlink-staking.md#approved-tokens) map.
 
-##### Parameters
+**Parameters**
 
 | Name       | Type        |
 | ---------- | ----------- |
@@ -233,9 +236,9 @@ Sets the approval status of a token within the Staking Manager. Modifies the [`a
 
 #### `set-approved-updater`
 
-Sets the approval status of an updater. Modifies the [`approved-updaters`](#approved-updaters) map.
+Sets the approval status of an updater. Modifies the [`approved-updaters`](xlink-staking.md#approved-updaters) map.
 
-##### Parameters
+**Parameters**
 
 | Name       | Type        |
 | ---------- | ----------- |
@@ -244,9 +247,9 @@ Sets the approval status of an updater. Modifies the [`approved-updaters`](#appr
 
 #### `set-block-threshold`
 
-Sets the [`block-threshold`](#block-threshold) variable.
+Sets the [`block-threshold`](xlink-staking.md#block-threshold) variable.
 
-##### Parameters
+**Parameters**
 
 | Name        | Type   |
 | ----------- | ------ |
@@ -254,9 +257,9 @@ Sets the [`block-threshold`](#block-threshold) variable.
 
 #### `set-accrued-rewards`
 
-Permissionlessly sets the accrued rewards value of a certain `token` key in the [`accrued-rewards`](#accrued-rewards) map. Note this function potentially overwrites the value updatead via the [`add-rewards`](#add-rewards) function.
+Permissionlessly sets the accrued rewards value of a certain `token` key in the [`accrued-rewards`](xlink-staking.md#accrued-rewards) map. Note this function potentially overwrites the value updatead via the [`add-rewards`](xlink-staking.md#add-rewards) function.
 
-##### Parameters
+**Parameters**
 
 | Name      | Type                                   |
 | --------- | -------------------------------------- |
@@ -265,9 +268,9 @@ Permissionlessly sets the accrued rewards value of a certain `token` key in the
 
 #### `set-required-validators`
 
-Sets the [`set-required-validators`](#required-validators) variable.
+Sets the [`set-required-validators`](xlink-staking.md#required-validators) variable.
 
-##### Parameters
+**Parameters**
 
 | Name       | Type   |
 | ---------- | ------ |
@@ -275,9 +278,9 @@ Sets the [`set-required-validators`](#required-validators) variable.
 
 #### `add-validator`
 
-Adds a new `validator` key in the [`validators-registry`](#validators-registry) map. Values cannot be modified if the key already exists, since the the update is performed with the [`map-insert`](https://docs.stacks.co/reference/functions#map-insert) Clarity function.
+Adds a new `validator` key in the [`validators-registry`](xlink-staking.md#validators-registry) map. Values cannot be modified if the key already exists, since the the update is performed with the [`map-insert`](https://docs.stacks.co/reference/functions#map-insert) Clarity function.
 
-##### Parameters
+**Parameters**
 
 | Name        | Type                                      |
 | ----------- | ----------------------------------------- |
@@ -286,9 +289,9 @@ Adds a new `validator` key in the [`validators-registry`](#validators-registry)
 
 #### `remove-validator`
 
-Removes an entry in the [`validators-registry`](#validators-registry) map, using the [`map-delete`](https://docs.stacks.co/reference/functions#map-delete) Clarity function.
+Removes an entry in the [`validators-registry`](xlink-staking.md#validators-registry) map, using the [`map-delete`](https://docs.stacks.co/reference/functions#map-delete) Clarity function.
 
-##### Parameters
+**Parameters**
 
 | Name        | Type        |
 | ----------- | ----------- |
@@ -298,44 +301,44 @@ Removes an entry in the [`validators-registry`](#validators-registry) map, using
 
 #### `is-dao-or-extension`
 
-Standard protocol function to check whether the `contract-caller` is an enabled extension within the DAO or the `tx-sender` is the DAO itself (proposal execution scenario). The enabled extension check is delegated to the XLink's `executor-dao` contract.
+Standard protocol function to check whether the `contract-caller` is an enabled extension within the DAO or the `tx-sender` is the DAO itself (proposal execution scenario). The enabled extension check is delegated to the Brotocol's `executor-dao` contract.
 
 #### Staking validation
 
-- `validate-stake`
-- `validate-unstake`
+* `validate-stake`
+* `validate-unstake`
 
 #### Shares conversion
 
-- `get-shares-given-amount`
-- `get-amount-given-shares`
+* `get-shares-given-amount`
+* `get-amount-given-shares`
 
 #### Message handling
 
-- `message-domain`
-- `create-oracle-message`
-- `decode-oracle-message`
-- `hash-oracle-message`
+* `message-domain`
+* `create-oracle-message`
+* `decode-oracle-message`
+* `hash-oracle-message`
 
 ### Getters
 
-Getter functions to retrieve all the [storage](#storage) variables and values within each map. For maps related to validators, an error is thrown if the principal is not present as a key within the [`validators-regitry`](#validators-registry). In contrast, for token maps, a default value is returned if the principal is not found.
+Getter functions to retrieve all the [storage](xlink-staking.md#storage) variables and values within each map. For maps related to validators, an error is thrown if the principal is not present as a key within the [`validators-regitry`](xlink-staking.md#validators-registry). In contrast, for token maps, a default value is returned if the principal is not found.
 
 #### Variables
 
-- `get-paused`
-- `get-block-threshold`
-- `get-required-validators`
+* `get-paused`
+* `get-block-threshold`
+* `get-required-validators`
 
 #### Maps
 
-- `get-validator-or-fail`
-- `get-approved-token-or-default`
-- `get-shares-or-default`
-- `get-total-shares-or-default`
-- `get-total-staked-or-default`
-- `get-accrued-rewards-or-default`
-- `get-approved-updater-or-default`
+* `get-validator-or-fail`
+* `get-approved-token-or-default`
+* `get-shares-or-default`
+* `get-total-shares-or-default`
+* `get-total-staked-or-default`
+* `get-accrued-rewards-or-default`
+* `get-approved-updater-or-default`
 
 ## Storage
 
@@ -345,7 +348,7 @@ Getter functions to retrieve all the [storage](#storage) variables and values wi
 | -------- | ------ |
 | Variable | `bool` |
 
-Indicates the operational status of the main contract operations: [`add-rewards`](#add-rewards), [`stake`](#stake) and [`unstake`](#unstake).
+Indicates the operational status of the main contract operations: [`add-rewards`](xlink-staking.md#add-rewards), [`stake`](xlink-staking.md#stake) and [`unstake`](xlink-staking.md#unstake).
 
 ### `approved-tokens`
 
@@ -401,7 +404,7 @@ Indicates the minimum number of validators required to sign a message for it to
 | ---- | ------------------------------------------------ |
 | Map  | `principal { amount: uint, update-block: uint }` |
 
-Tracks the total rewards that have been collected and restaked for each token, identified by its contract `principal`. The `update-block` field records the [`stacks-block-height`](https://docs.stacks.co/reference/keywords#stacks-block-height) of the last update. This map plays a key role in the [`add-rewards`](#add-rewards) function mechanism.
+Tracks the total rewards that have been collected and restaked for each token, identified by its contract `principal`. The `update-block` field records the [`stacks-block-height`](https://docs.stacks.co/reference/keywords#stacks-block-height) of the last update. This map plays a key role in the [`add-rewards`](xlink-staking.md#add-rewards) function mechanism.
 
 ### `block-threshold`
 
@@ -409,7 +412,7 @@ Tracks the total rewards that have been collected and restaked for each token, i
 | -------- | ------ |
 | Variable | `uint` |
 
-Specifies the number of Stacks blocks allowed as a delay for submitting an [`add-rewards`](#add-rewards) message.
+Specifies the number of Stacks blocks allowed as a delay for submitting an [`add-rewards`](xlink-staking.md#add-rewards) message.
 
 ### `approved-updaters`
 
@@ -435,13 +438,12 @@ Mathematical constant used to restrict the decimal precision to 8 digits.
 | ------ | ----- |
 | `uint` | `u20` |
 
-Defines the upper bound for the [`required-validators`](#required-validators) variable.
+Defines the upper bound for the [`required-validators`](xlink-staking.md#required-validators) variable.
 
 ## Contract calls
 
-- `<ft-trait>`: Interaction with any approved token to perform mint actions ([`add-rewards`](#add-rewards)) and transfers (mostly within [`stake`](#stake) and [`unstake`](#unstake), but also within the [`withdraw`](#withdraw) governance function). The `ft-trait` within the contract is the custom SIP-010 implementation for handling fixed notation, available at `'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.trait-sip-010`.
-
-- `'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.executor-dao`: This contract is exclusively called by the [`is-dao-or-extension`](#is-dao-or-extension) function for authorizing governance operations.
+* `<ft-trait>`: Interaction with any approved token to perform mint actions ([`add-rewards`](xlink-staking.md#add-rewards)) and transfers (mostly within [`stake`](xlink-staking.md#stake) and [`unstake`](xlink-staking.md#unstake), but also within the [`withdraw`](xlink-staking.md#withdraw) governance function). The `ft-trait` within the contract is the custom SIP-010 implementation for handling fixed notation, available at `'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.trait-sip-010`.
+* `'SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.executor-dao`: This contract is exclusively called by the [`is-dao-or-extension`](xlink-staking.md#is-dao-or-extension) function for authorizing governance operations.
 
 ## Errors
 
@@ -462,5 +464,3 @@ Defines the upper bound for the [`required-validators`](#required-validators) va
 | `err-invalid-amount`               | `(err u1019)` |
 | `err-update-failed`                | `(err u1020)` |
 | `err-duplicated-signatures`        | `(err u1021)` |
-
-<!-- Documentation Contract Template v0.1.1 -->

developers/integrations/README.md

@@ -2,7 +2,7 @@
 
 Integration requires a deployment of an endpoint smart contract on the target chain.
 
-For the list of currently supported chains, please visit [XLink Contract Deployment](https://app.gitbook.com/s/xagAneFBZMxG6fw5k0WK/).
+For the list of currently supported chains, please visit Brotocol[ Contract Deployment](https://app.gitbook.com/s/xagAneFBZMxG6fw5k0WK/).
 
 Below is a typical integration process.
 
@@ -26,11 +26,11 @@ The configuration parameters include, among others,:
 
 ## Integration with Bitcoin Oracle
 
-XLink scales by partnering with [Bitcoin Oracle](https://docs.alexgo.io/bitcoin-oracle/what-is-the-bitcoin-oracle) which runs the validator and verifier networks of XLink.
+Brotocol scales by partnering with [Bitcoin Oracle](https://docs.alexgo.io/bitcoin-oracle/what-is-the-bitcoin-oracle) which runs the validator and verifier networks of Brotocol.
 
 Bitcoin Oracle produces the consensus data based on the computation from the off-chain engines and provides a consensus model framework that allows the end consumer to customise their consensus model by optimising across the trust and the security budget.
 
-The validators of Bitcoin Oracle observe every Endpoint on the XLink and produce a set of cryptographic proofs for the relevant destination chain to process.
+The validators of Bitcoin Oracle observe every Endpoint on the Brotocol and produce a set of cryptographic proofs for the relevant destination chain to process.
 
 The relayers then aggregate those cryptographic proofs and submit to the relevant destination Endpoints upon meeting the validator threshold.
 

developers/integrations/understanding-the-bitcoin-bridge.md

@@ -2,6 +2,6 @@
 
 On Bitcoin, users interact with Multisigs (operated by a decentralsed network of validators and verifiers) to lock assets to be bridged ("source asset"), and on L2s to receive the L2 asset ("destination asset").
 
-Additionally, users on Bitcoin may provide additional data (`OP_RETURN`) to trigger certain smart contract interaction on their behalf automatically by XLink.
+Additionally, users on Bitcoin may provide additional data (`OP_RETURN`) to trigger certain smart contract interaction on their behalf automatically by Brotocol.
 
 Multisigs are Bitcoin wallets that are operated by multiple signers. In contrast to a typicall wallet requiring just one party to sign a transaction, a multisig requires multiple parties or signers to sign a transaction.

developers/security-audits.md

@@ -0,0 +1,14 @@
+# Security Audits
+
+As with all crypto technology, risk is real whether using a centralized or decentralized bridge. Some of the more novel decentralized bridges are relatively untested and even those that have been tested are still subject to exploits.
+
+Brotocol is audited by CoinFabrik, covering both the contracts and the backends.
+
+* [2022-12 Bridge Endpoints](https://cdn.xlink.network/pdf/ALEX_Audit_bridge_coinfabrik_202212.pdf)
+* [2023-04 Bridge Backend and Endpoints](https://cdn.xlink.network/pdf/ALEX_Audit_Bridge_2023-04.pdf)
+* [2023-10 Bitcoin Oracle and Bridge](https://cdn.xlink.network/pdf/ALEX_Audit_202310_Bitcoin_Oracle_and_Bridge.pdf)
+* [2024-11 Brotocol Staking Manager](https://cdn.xlink.network/pdf/XLINK_Staking_Audit_2024_11_final.pdf)
+* [2024-11 Brotocol Peg-out Endpoints](https://cdn.xlink.network/pdf/XLINK_Peg-out_Endpoints_Audit%2011-2024.pdf)
+* [2024-11 Brotocol Peg-in Endpoints](https://cdn.xlink.network/pdf/XLINK_Peg-in_Endpoints_Audit_11-2024.pdf)
+
+The smart contracts are also subject to our [bug bounty](https://immunefi.com/bounty/alex/) programme on Immunefi.

developers/supported-blockchains-and-tokens.md

@@ -0,0 +1,28 @@
+# Supported Blockchains and Tokens
+
+We list below the different bridgable tokens with Brotocol.
+
+{% hint style="info" %}
+**Important:** Users can only bridge tokens that represent the **same asset** across different blockchains. 
+
+For example, BTC can be transferred to its equivalent, WBTC, when moving from Bitcoin to an EVM network, as both represent the same asset on different chains.
+{% endhint %}
+
+| **AILayer**  | aBTC, ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                                      |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Arbitrum** | aBTC, WBTC,  ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                               |
+| **Aurora**   | aBTC, ALEX, aUSD, vLiALEX, vLiSTX                                                                                            |
+| **B²**       | aBTC, ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                                      |
+| **Bitcoin**  | BTC                                                                                                                          |
+| **Bitlayer** | aBTC, ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                                      |
+| **BNB**      | aBTC, ALEX, BTCB, aUSD, SKO, USDT, uBTC                                                                                      |
+| **BOB**      | aBTC, ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                                      |
+| **Core**     | aBTC, ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                                      |
+| **Ethereum** | ALEX, aUSD, WBTC                                                                                                             |
+| **Lorenzo**  | aBTC, ALEX, aUSD, vLiALEX, vLiSTX                                                                                            |
+| **Merlin**   | aBTC, ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                                      |
+| **Mode**     | aBTC, ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                                      |
+| **Runes**    | DOG•GO•TO•THE•MOON, ETHEREUM•ON•BITCOIN, MAKE•BITCORN•GREAT•AGAIN, NOT•GONNA•MAKE•IT, SATOSHI•NAKAMOTO•INU, WELSH•CORGI•COIN |
+| **Stacks**   | aBTC, ALEX, DOG•GO•TO•THE•MOON, ETHEREUM, NOT, PEPE, SATOSHI•NAKAMOTO•INU, SKO, aUSD, uBTC, vLiALEX, vLiSTX, WELSH           |
+| **X Layer**  | aBTC, ALEX, aUSD, uBTC, vLiALEX, vLiSTX                                                                                      |
+| Base         | aBTC, cbBTC, aUSD,  ALEX, uBTC, vLiALEX, vLiSTX                                                                              |

features/brobridge/README.md

@@ -0,0 +1,125 @@
+# BroBridge
+
+<figure><img src="../../.gitbook/assets/bridgzz.png" alt=""><figcaption></figcaption></figure>
+
+BroBridge is the best place to bridge from Bitcoin to any chains for lowest fees!
+
+If you have not try BroBridge, try it now via here:  [https://brotocol.xyz/bridge/cross-bridge](https://brotocol.xyz/bridge/cross-bridge)
+
+Follow these steps to bridge your assets between chains using Brotocol!
+
+{% hint style="info" %}
+**Important:** Users can only bridge tokens that represent the **same asset** across different blockchains. For example, BTC can be transferred to its equivalent, WBTC, when moving from Bitcoin to an EVM network, as both represent the same asset on different chains.
+{% endhint %}
+
+### Step 0: Connecting your Wallet
+
+Before using the bridge, you need to connect a wallet for the blockchain you are bridging from, as well as one for the blockchain you are bridging to (e.g., **Stacks Chain**, **Bitcoin Chain**, or **EVM Chain**).
+
+{% hint style="info" %}
+See the [Prerequisites](../../introduction/getting-started/prerequisites/) section for the list of **Supported Wallets** and their installation guides.
+{% endhint %}
+
+You can connect your wallet by clicking the **Wallet Manager** located in the top right corner of the Brotocol app. This is where you’ll manage all your wallet connections.
+
+![Select Wallet Manager](<../../.gitbook/assets/Screenshot 2025-04-16 at 12.29.06 PM.png>)
+
+In some cases, you can use the same wallet for both blockchains, but you must connect it separately for each blockchain to specify the source and destination accounts.
+
+In this example, we will use [Xverse](https://www.xverse.app/), as it supports both the Bitcoin and Stacks networks. Since we are bridging from native BTC to Arbitrum's WBTC, we also need to connect an EVM wallet; in this example, we are using [Rabby Wallet](https://rabby.io/).
+
+{% hint style="info" %}
+For a detailed explanation on how to connect your wallet, check our guide: [**How to Connect your Wallet**](../../introduction/getting-started/prerequisites/how-to-connect-your-wallet.md).
+{% endhint %}
+
+Once you have connected both wallets, you will see them active in the **Wallet Manager**.
+
+![Active Wallets](<../../.gitbook/assets/Screenshot 2025-04-18 at 12.27.10 PM.png>)
+
+#### Step 1: Select the Source Blockchain and Token
+
+To start, click on the '**From Asset Selection**'.
+
+![To Token Selector](<../../.gitbook/assets/Screenshot 2025-04-18 at 12.24.27 PM.png>)
+
+Next, choose the **source blockchain** from which you want to bridge your assets (e.g., **Stacks Chain**).&#x20;
+
+Then, select the **source token** you would like to bridge (e.g., **aUSD**).
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-18 at 12.28.20 PM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+{% hint style="info" %}
+Bridgable tokens for a specific blockchain are identified by the double arrow icon ⮂. You will only be able to select these tokens for bridging with the selected blockchain.
+{% endhint %}
+
+#### Step 2: Select the Destination Blockchain and Token
+
+First, click on the  '**To Asset Selection**'.
+
+![Select Destination Token](<../../.gitbook/assets/Screenshot 2025-04-18 at 12.29.28 PM.png>)
+
+Next, select the **destination blockchain** where you brindge the assets (e.g., Native BTC -> Arbitrum's WBTC).&#x20;
+
+Then, choose the corresponding **destination token** on this chain (e.g., **WBTC Arbitrum ERC-20**).
+
+{% hint style="info" %}
+While you need to select the same bridge asset for the swap, **aUSD can still be bridged to USDT or USDC—and back again!**
+{% endhint %}
+
+![Select Blockchain and Token Destination](<../../.gitbook/assets/Screenshot 2025-04-18 at 12.32.42 PM.png>)
+
+Important to remember, whichever chain you want to bridge to, you will be able to know if its available to bridge or not based on the green highlight shown above.&#x20;
+
+If you do not see the '<mark style="color:orange;">**⮂ ₿**</mark>' icon, it's mean it's not supported / available to bridge to.&#x20;
+
+#### Step 3: Input the Amount to Bridge
+
+Enter the amount of tokens you would like to bridge.&#x20;
+
+You can also use the **Max** button to select your full balance.
+
+![Input Amount of Tokens](<../../.gitbook/assets/Screenshot 2025-04-18 at 12.40.50 PM.png>)
+
+If you would like to customize the network fee, you can do it so too as shown above!
+
+#### Step 4: Initiate the Bridge
+
+After confirming the selected blockchains and token amounts, click the **Bridge** button to begin the process.
+
+![Click on Bridge](<../../.gitbook/assets/Screenshot 2025-04-18 at 12.41.50 PM.png>)
+
+Before you click Bridge, if you need to check how much the fee breakdown and time required for the bridge, you can scroll down to check as shown below.
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-18 at 12.42.34 PM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+#### Step 5: Confirm the Transaction
+
+You will be prompted to confirm the bridging transaction.&#x20;
+
+Review the details, ensure everything is correct, and click Confirm to proceed.
+
+![Confirm the Bridge Transaction](<../../.gitbook/assets/Screenshot 2025-04-18 at 1.00.28 PM.png>)
+
+#### Step 6: Confirm Transaction
+
+After you click Confirm, you will be required to confirm the transaction on-chain by clicking "**Confirm**" on the Xverse Review Transaction pop-up page.
+
+![Scroll Down to Transfer to Unwrap](<../../.gitbook/assets/Screenshot 2025-04-18 at 1.01.26 PM.png>)
+
+### Step 7: Wait for Confirmation
+
+Finally, wait for the transaction to be confirmed on the blockchain.&#x20;
+
+The confirmation time can take anywhere from 10 to 30 minutes, depending on network conditions.&#x20;
+
+Once the transaction is broadcasted, you should see the bridged tokens deposited in your destination wallet.
+
+![Wait for Transaction Confirmation](<../../.gitbook/assets/Screenshot 2025-04-16 at 5.12.27 PM.png>)
+
+{% hint style="info" %}
+You can monitor your transaction in real time by clicking the **Explorer** page or "<mark style="color:orange;">**1 Pending**</mark>" as shown in the screenshot above.
+{% endhint %}
+
+## Support
+
+For assistance, please reach out to our Community Managers on [Discord](https://discord.com/invite/xlink).

features/brobridge/how-xlink-works.md

@@ -0,0 +1,17 @@
+# How Brotocol Bridge Works?
+
+The Brotocol Bridge is a hybrid bi-directional bridge that acts as a '**connector**' between Bitcoin and other blockchains. 
+
+When you want to move assets (like Bitcoin) from one network to another, Brotocol handles the process, making sure everything happens securely.
+
+<div align="center"><img src="../../.gitbook/assets/meta2.png" alt="XLink Bridge"></div>
+
+Brotocol works by using secure multisignature wallets (multisigs) and special checkpoints called Endpoints to manage the transfer of assets.&#x20;
+
+For example, when you want to move your Bitcoin to another blockchain, Brotocol "locks" your Bitcoin in a multisig on the Bitcoin network.&#x20;
+
+Then, an equivalent amount is unlocked on the other blockchain through an Endpoint, which is a smart contract responsible for handling the transfer.&#x20;
+
+These Endpoints are owned by multisigs and operated by a decentralized network of validators and verifiers, ensuring that the process is secure and reliable.&#x20;
+
+This system allows you to use your Bitcoin in different blockchain environments, like Ethereum or other layer 2 networks, while keeping your original assets safe.

features/broswap/README.md

@@ -0,0 +1,109 @@
+---
+description: >-
+  Swap directly from native Bitcoin to any assets; including EVM and non-EVM
+  assets without restriction!
+---
+
+# BroSwap
+
+<figure><img src="../../.gitbook/assets/swap.png" alt=""><figcaption></figcaption></figure>
+
+With BroSwap, you would initiate a swap directly from your Bitcoin wallet to any assets you would like to swap to.&#x20;
+
+**BroSwap currently supports:**&#x20;
+
+* Bitcoin native network
+* BRC-20
+* Runes
+
+Swap from BTC to aUSD (Wrapped version of USDT) back and forth or even purchase Runes with stables (aUSD)!
+
+If you haven't try BroSwap, try it now here: [https://brotocol.xyz/bitcoin/swap](https://brotocol.xyz/bitcoin/swap)
+
+{% hint style="info" %}
+Be sure to [connect your wallet first](../../introduction/getting-started/prerequisites/how-to-connect-your-wallet.md) before using BroSwap!&#x20;
+{% endhint %}
+
+#### Step #1: Select the Asset You'd Like to Swap From&#x20;
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-17 at 12.51.03 PM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+BroSwap currently supports up to three different networks to swap to and from:
+
+* Bitcoin
+* BRC-20
+* Runes
+
+To start, click on the Asset Selection A (The first option) as shown in the screenshot above) to pick the asset you want to swap from.&#x20;
+
+#### Step #2: Select the Asset You'd Like to Swap To
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-17 at 12.51.27 PM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+After you have selected the asset you want to swap from, click on the Asset Selection (The second option) as shown in the screenshot above) to pick the asset you want to want to swap to.&#x20;
+
+#### Step #3: Choose the Token you want to Swap From / To
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-17 at 12.52.10 PM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+In the Asset Selection pop-up (as shown in the screenshot above), you’ll notice a ‘<mark style="color:orange;">**⮂ ₿**</mark>’ symbol next to certain assets.
+
+This indicates that the asset is available for swapping. In our example, I have selected $BTC -> $aUSD; Native Bitcoin network to BRC-20's $aUSD.&#x20;
+
+If the symbol is not shown, that asset cannot be swapped to.
+
+#### Step #4: Checking the Rate, Network Fees, Slippages and Minimum Received
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-18 at 11.17.31 AM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+Once you’ve selected the assets you want to swap from and to, you can enter the amount you'd like to swap.\
+BroSwap will then display an estimate of what you'll receive based on your input.
+
+On the same page, you can also adjust settings like **Network Fees**, **Slippage**, and **Route**.
+
+{% hint style="success" %}
+By default, BroSwap selects the most optimal route and network fee to ensure you get the best value for your swap!
+{% endhint %}
+
+#### (Optional) Step #5: Double Check your Fee Estimates, Price Impact and Minimum Received
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-18 at 11.20.10 AM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+Before you click Swap, you can check the section below the Swap button to get a good idea on how much you would receive for the Swap.&#x20;
+
+**Important to note:** Our UI sets a default slippage of 4%, which may cause a slight difference between the _Minimum Received_ and the _Estimated_ amount shown. However, most transactions typically go through with less than 1% slippage—for example, swaps like $BTC <> $aUSD.
+
+#### Step #6: Swap it!&#x20;
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-18 at 11.20.47 AM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+We’ll show you the details from Step #5 again before you click **Confirm** to swap.
+
+If you're not satisfied with the estimates, you can go back and adjust the slippage or network fee.
+
+Once you're happy with the rate, click **Confirm** to proceed.
+
+#### Step #7: Approve the Transaction on your Wallet
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-18 at 11.25.19 AM.png" alt="" width="375"><figcaption><p>Xverse Transaction Confirmation Breakdown</p></figcaption></figure>
+
+On your wallet’s confirmation screen, you’ll see the amount that will be spent for the bridge.
+
+Depending on the wallet you’re using, the estimated fees will also be displayed.
+
+If everything looks good, go ahead and click **Confirm** to proceed.
+
+#### Step #8: All done! Just wait for your Swap to Complete!
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-17 at 12.58.21 PM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+You’ve successfully initiated your first swap! 🎉
+
+A pop-up will appear in the upper-right corner of your screen, letting you know there’s a pending transaction.
+
+You’ll also notice the [**Explorer**](../explorer/) button changes to '**1 Pending'**, indicating an active swap is in progress.
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-18 at 11.28.17 AM.png" alt=""><figcaption></figcaption></figure>
+
+If you clicked 'My Records only' , you will be able to see your pending transactions and all you have to do now, is just wait until it's completed, that's all!&#x20;
+

features/broswap/dex-aggregation.md

@@ -0,0 +1,13 @@
+# DEX Aggregation
+
+<figure><img src="../../.gitbook/assets/aggregate.png" alt=""><figcaption></figcaption></figure>
+
+To ensure you get the best possible deal for your swaps directly on the native Bitcoin network, BroSwap aggregates liquidity from multiple sources, including Kyber, ALEX, 0xMatcha, and more, tapping into over 100 liquidity pools.&#x20;
+
+This means you avoid high fees, excessive slippage, and the need to use multiple services.&#x20;
+
+You’ll always receive the most optimal rate for your Bitcoin swaps.
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-17 at 4.46.23 PM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+For example, in the screenshot above showing a BTC to aUSD swap, the displayed route uses Kyber to offer the best available rate.

features/broswap/how-to-swap-non-bridgeable-tokens.md

@@ -0,0 +1,21 @@
+# How to swap Non-bridgeable Tokens?
+
+In some cases, certain tokens may not be supported by the Brotocol bridge due to compatibility limitations. If you are attempting to bridge a token that is not compatible with the Brotocol bridge, it is recommended to use **ALEX Swap** to exchange it for a bridgeable token. 
+
+This ensures that you can proceed with your cross-chain activities without interruption.
+
+[**🔄 Swap your tokens now on ALEX Swap!**](https://app.alexlab.co/swap)
+
+## Supported Tokens
+
+Swap your tokens for tokens that can be bridged in Brotocol. You can find a list of supported tokens in our [**Overview section**](../../developers/supported-blockchains-and-tokens.md).
+
+## Example Use Case
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-17 at 4.15.58 PM.png" alt=""><figcaption></figcaption></figure>
+
+Let’s say you have **USDh**, a token that is not bridgeable via Brotocol.&#x20;
+
+In this case, you can use **ALEX Swap** to exchange **USDh** for **aUSD**, which is compatible with the Brobridge. After the swap, you can proceed with bridging **aUSD** to another blockchain using Brotocol.
+
+For more detailed instructions on how to perform swaps on ALEX, visit the [**ALEX Swap documentation**](https://docs.alexlab.co/product-features/token-swaps/how-to).

features/explorer/README.md

@@ -0,0 +1,24 @@
+# Explorer
+
+<figure><img src="../../.gitbook/assets/8.png" alt=""><figcaption></figcaption></figure>
+
+Click here to access the [**Brotocol Reserve**](https://brotocol.xyz/bridge/reserve).
+
+The Brotocol **Reserve** currently holds approximately 16 different assets, which include:
+
+* [aBTC](../../reserves/what-is-abtc.md)
+* uBTC
+* [aUSD](../../reserves/what-is-ausd.md)
+* ALEX
+* STX
+* vLiaBTC
+* CHAX
+* $B20
+* ORDG
+* ORNJ
+* TRIO
+* TX20
+* DOG•GO•TO•THE•MOON
+* BILLION•DOLLAR•CAT
+* PUPS•WORLD•PEACE
+* TANUKI•WISDOM

features/explorer/active-notifications.md

@@ -0,0 +1,16 @@
+# Active Notifications
+
+<figure><img src="../../.gitbook/assets/notify.png" alt=""><figcaption></figcaption></figure>
+
+Not all chains are lightning fast—especially for those unfamiliar with Bitcoin’s native network speed, transactions may take some time to complete.
+
+But fret not! Brotocol includes **active notifications** to keep you informed about ongoing transactions in real time.
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-17 at 12.58.21 PM.png" alt="" width="375"><figcaption></figcaption></figure>
+
+If you have at least one pending notification, your '[**Explorer**](./)' button will be updated to look like the screenshot above.&#x20;
+
+<figure><img src="../../.gitbook/assets/Screenshot 2025-04-17 at 12.58.49 PM.png" alt=""><figcaption></figcaption></figure>
+
+By clicking 'My records only', you will be able to see the status of your transaction.&#x20;
+

getting-started/README.md

@@ -1,31 +0,0 @@
----
-description: Get started with asset transfers using the XLink cross-chain bridge!
-layout:
-  title:
-    visible: true
-  description:
-    visible: true
-  tableOfContents:
-    visible: true
-  outline:
-    visible: true
-  pagination:
-    visible: false
----
-
-# Getting Started
-
-XLink enables seamless asset transfers across blockchains, keeping you in control of your tokens. Start using XLink by setting up your wallet and bridging assets across chains.
-
-[**🌁 Connect to XLink and Start Bridging Now!**](https://app.xlink.network)
-
-## Explore
-
- - [Prerequisites](prerequisites.md): Essential requirements to begin using the XLink bridge.
-  - [Quickstart: The Bridge](the-bridge.md): Step-by-step guide to initiate asset transfers.
-  - [Quickstart: Campaigns](campaigns.md): A detailed guide on how to participate in XLink campaigns and earn rewards.
-  - [Guides](./guides/README.md): Practical walkthroughs, including [How to Connect Your Wallet](./guides/how-to-connect-your-wallet.md) and [How to Swap non-bridgeable Tokens](./guides/how-to-swap-non-bridgeable-tokens.md).
-
-## Support
-
-For help, join us on [Discord](https://discord.com/invite/xlink).

getting-started/campaigns.md

@@ -1,94 +0,0 @@
----
-description: Learn what are and how to participate in XLink campaigns and earn rewards.
-layout:
-  title:
-    visible: true
-  description:
-    visible: true
-  tableOfContents:
-    visible: true
-  outline:
-    visible: true
-  pagination:
-    visible: false
----
-
-# Campaign Guide
-
-## What are XLink Campaigns
-
-Welcome to the **Campaigns**! XLink campaigns are special events where users can participate in various actions on supported blockchains to earn rewards. These actions typically involve interacting with many different actors in the STACKS ecosystem, like the XLink bridge, and use them to accomplish different challenges. Campaigns offer great opportunities to earn **ALEX**, **LiSTX**, **XLink Points**, and other project-specific tokens as rewards.
-
-Each campaign involves different requirements and actions, and all aim to incentivize user participation and strengthen user confidence in the Bitcoin DeFi ecosystem. Below, we'll explore the rewards you can earn and some tips on how to maximize your participation.
-
-## How do XLink Campaigns work
-
-Campaigns work by offering users the chance to earn rewards for completing specific tasks across different blockchains. Here's a quick overview:
-
-- **Actions**: Users typically need to perform tasks like staking, adding liquidity, or bridging assets.
-- **Rewards**: In return, participants can earn tokens such as **ALEX**, **LiSTX**, **XLink Points**, or project-specific tokens like **aBTC** and **MODE Points**.
-- **Platforms**: Campaigns can be hosted on various platforms like CORE, Mode, or Stacks, and often involve bridging assets between blockchains to complete the tasks.
-
-## Typical Rewards in XLink Campaigns
-
-XLink campaigns offer a variety of rewards based on the campaign and the blockchain involved. Here are some common rewards you can earn:
-
-- **ALEX**: Earn ALEX by participating in campaigns on the Stacks or Ethereum blockchains.
-- **LiSTX**: A popular reward on Stacks campaigns, allowing users to stake and earn additional tokens.
-- **XLink Points**: Earn XLink Points by bridging assets and completing actions.
-- **Project-Specific Tokens**: Earn tokens tied to the specific blockchain you're interacting with (e.g., **aBTC**, **MODE Points**).
-
-## Tips for Participating in Campaigns
-
-- **Check the Requirements**: Each campaign has different requirements, so be sure to review the campaign details before you start.
-- **Stay Updated**: New campaigns are launched regularly. Keep an eye on the XLink platform or join our community channels for the latest updates.
-- **Plan Ahead**: Some campaigns offer better rewards for specific actions (e.g., staking certain tokens or adding liquidity). Plan to maximize your rewards!
-
-## Where to Find Campaigns
-
-To view and join active campaigns, visit the [**XLink Campaigns Page**](https://app.xlink.network/bridge-campaign). You’ll find detailed instructions, the supported tokens, and the rewards for each campaign.
-
-## How to Participate in XLink Campaigns
-
-Participating in campaigns is easy and rewarding. Although each campaign might be slightly different, the basic steps to participate are similar. Here’s how you can get started:
-
-### Step 1: **Register on the Platform**
-First, visit the **XLink App** and navigate to the **Campaigns** tab. This is where you'll find all the active campaigns. 
-
-Look for the **See Details** button next to the campaign you're interested in. Clicking it will provide more details on how to participate, including specific steps and links to register.
-
-![Campaign Browsing](../.gitbook/assets/campaigns/campaigns-menu.png)
-
-Once you've selected a campaign, you'll need to register for it by following the instructions provided under the **How to Participate** section. You might be directed to specific platforms like **CORE**, **Mode**, or **Stacks**, depending on the campaign.
-
-For example, in the **ALEX Staking Campaign**, you'll be directed to stake your ALEX tokens on LISA. Follow the campaign-specific instructions to complete the staking process and earn rewards.
-
-![ALEX Staking Campaign Example](../.gitbook/assets/campaigns/alex-staking-example.png)
-
-Similarly, in the **ALEX Liquidity Campaign**, you’ll be directed to add liquidity on a supported DeFi platform. Be sure to follow the specific steps outlined in each campaign.
-   
-### Step 2: **Bridge Your Assets** (If Required)
-Next, you’ll typically bridge assets from one blockchain to another, depending on the campaign. This could include tokens like **aBTC**, **WBTC**, or other supported assets. Make sure to check the campaign’s instructions on which assets to bridge and to which chain.
-
-*Note*: Not all campaigns require bridging assets, so always check the campaign details first.
-
-   <!-- *screenshot here showing the bridge interface and how to select assets for bridging.*
-   ![Bridge Assets](../.gitbook/assets/special-features/bridge-assets.png) -->
-
-### Step 3: **Complete the Required Action**
-Once your assets are bridged, you may need to perform additional actions like re-staking your tokens, adding liquidity to a pool, or borrowing/supplying tokens on a DeFi platform. These actions unlock the campaign rewards.
-
-*Note*: The actions required in each campaign can vary, so be sure to check the campaign details for specific requirements.
-  
-  <!-- *screenshot here showing an example of completing an action like staking or adding liquidity.* 
-  ![Staking and Liquidity](../.gitbook/assets/special-features/staking-liquidity.png) -->
-
-### Step 4: **Earn Rewards**
-After completing the necessary steps, you'll start earning rewards like **ALEX**, **LiSTX**, **XLink Points**, or other project-specific tokens.
-   
-  <!-- *screenshot here showing how rewards are tracked or where users can see their earned rewards.*
-  ![Earn Rewards](../.gitbook/assets/special-features/earn-rewards.png) -->
-
-## Need Help?
-
-If you have any questions or need help with a campaign, join our community on [**Discord**](https://discord.com/invite/xlink).

getting-started/guides/README.md

@@ -1,29 +0,0 @@
----
-description: Tutorials to help you get started with XLink.
-layout:
-  title:
-    visible: true
-  description:
-    visible: true
-  tableOfContents:
-    visible: true
-  outline:
-    visible: true
-  pagination:
-    visible: false
----
-
-# 🛠 XLink Guides
-
-This section provides tutorials to help you use XLink effectively.
-
-## Available Guides
-
-- [How to Connect your Wallet](how-to-connect-your-wallet.md)
-- [How to Swap non-bridgeable Tokens](how-to-swap-non-bridgeable-tokens.md)
-
-More guides coming soon to assist with managing assets, bridging tokens, and more.
-
-## Support
-
-For assistance, join our community on [Discord](https://discord.com/invite/xlink).