Stacks

Introduction

This document provides a technical overview of Brotocol's bridge built with Clarity smart contracts on the Stacks blockchain. The system enables secure cross-chain asset transfers through three core bridging mechanisms:

• Bitcoin Bridge: Transfers BTC between the Bitcoin blockchain and the Stacks chain. BTC bridged to Stacks is represented as aBTC (bridged BTC), maintaining a 1:1 peg with native Bitcoin.

• Meta Bridge: Transfers BRC-20 and Runes-compliant assets between the Bitcoin chain and the Stacks chain, converting them to SIP-010 compliant tokens.

• Cross Bridge: Enables transfers between Stacks and other Brotocol supported networks, allowing interoperability with EVM-compatible blockchains.

Each bridging pathway uses specialized endpoint contracts for handling incoming transactions (peg-in) and outgoing transactions (peg-out), with supporting contracts (such as registries) to ensure security and proper transaction validation.

Bitcoin Bridge (Bitcoin's BTC <-> Stacks' aBTC)

This is a simplified representation on the BTC Bridge main goal.

*To see more information on registry contract see the auxiliary contracts section.

BTC Peg-In Endpoints

• 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

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

Responsible for managing the bridging of Stacks' aBTC back to the Bitcoin blockchain as native BTC.

Meta Bridge (Bitcoin's BRC-20 <-> Stacks' SIP-010)

This is a simplified representation on the Meta Bridge main goal.

*To see more information on these contracts see the auxiliary contracts section.

Meta Peg-In Endpoints

• Contract names: meta-peg-in-endpoint-v2-04, meta-peg-in-endpoint-v2-04-lisa, meta-peg-in-v2-06-swap.

• Complete technical documentation

Responsible for the bridging of assets that comply with the BRC-20 and Runes standards (on Bitcoin chain) into the corresponding tokens on the Stacks blockchain, complying with the Stacks SIP-010 fungible token standard.

Meta Peg-Out Endpoint

• Contract name: meta-peg-out-endpoint-v2-04

• Complete technical documentation

Manages the bridging of tokens from the Stacks chain back to the Bitcoin blockchain, where they are converted into BRC-20 or Runes compliant assets.

Cross Bridge (EVM Chains' Tokens <-> Stacks' SIP-010)

This is a simplified representation on the Cross Bridge main goal.

*To see more information on these contracts see the auxiliary contracts section.

Cross Peg-In Endpoints

• Contract names: cross-peg-in-endpoint-v2-04, cross-peg-in-v2-04-launchpad, cross-peg-in-v2-04-swap.

• Complete technical documentation

Responsible for managing the transfer of assets from other EVM-like blockchains into the Stacks chain, where they are represented as SIP-010 tokens.

Cross Peg-Out Endpoint

• Contract names: cross-peg-out-endpoint-v2-01, cross-peg-out-v2-01-agg.

• Complete technical documentation

Responsible for managing the transfer of SIP-010 tokens from the Stacks network to other supported networks (mostly EVM-like blockchains).

Auxiliary Contracts

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.

Governance

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.

For technical details on the ExecutorDAO, refer to the project's README.md.

Brotocol Staking

Brotocol also offers users the possibility to stake their tokens. To see detailed information on how the staking protocol works refer to the Brotocol Staking Manager contract.