Brotocol
Developers
Introduction
Introduction
  • 👊Introduction
    • What is Brotocol?
      • ✨Brotocol 101
    • Getting Started
      • Supported Wallets
        • How to Connect your Wallet
    • What is Bonbori?
      • Why Bonbori?
      • Bonbori Consensus Model
  • 🌉Features
    • BroSwap
      • DEX Aggregation
      • How to swap Non-bridgeable Tokens?
    • BroBridge
      • How Brotocol Bridge Works?
    • Explorer
      • Active Notifications
  • Reserves
    • What is aBTC?
    • What is aUSD?
  • 🎮Developers
    • Smart Contracts
      • btc peg-in endpoint
      • btc-peg-out-endpoint
      • meta peg-in endpoint
      • meta peg-out endpoint
      • cross-peg-in-endpoint
      • cross-peg-out-endpoint
      • brotocol-staking
      • BridgeEndpoint
    • Add a New Chain
    • Supported Blockchains and Tokens
    • Security Audits
    • Integrations
      • Bitcoin
      • Bitcoin L2s or EVMs
  • 🖼️Media Kits
    • Official Links
Powered by GitBook
On this page
  • Storage
  • registry
  • pegInAddress
  • timeLock
  • timeLockThreshold
  • timeLockThresholdByToken
  • unwrapSent
  • swapExecutor
  • swapSent
  • Data Types
  • Modifiers
  • Features
  • Governance Features
  • Read-Only Functions
  • Relevant Internal Functions
  • Events
  • Contract Calls (Interactions)
Edit on GitHub
  1. Developers
  2. Smart Contracts

BridgeEndpoint

Previousbrotocol-stakingNextAdd a New Chain

Last updated 1 month ago

  • Location: xlink/packages/contracts/bridge-solidity/contracts

  • Deployed contracts: See .

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.

Storage

registry

Data
Type

Variable

BridgeRegistry

Stores a reference to the BridgeRegistry contract, which manages approved tokens, relayers, and validators.

pegInAddress

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 , 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

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

Variable

uint256

The global minimum token amount that triggers a timelock. By default, the value is set to 0.

timeLockThresholdByToken

Data
Type

Variable

mapping(address => uint256)

unwrapSent

Data
Type

Variable

mapping(bytes32 => OrderPackage)

swapExecutor

(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

Variable

mapping(bytes32 => SwapOrderPackage)

Data Types

OrderPackage

Holds details of a pending unwrap operation.

struct OrderPackage {
  address recipient;
  address token;
  uint256 amount;
  bool sent;
}

SignaturePackage

Contains signatures from validators to prove an order is legitimate. It is used for verifying cross-chain transfers.

struct SignaturePackage {
  bytes32 orderHash;
  address signer;
  bytes signature;
}

SwapOrderPackage

(only present in BridgeEndpointWithSwap)

A struct that stores details of a swap order.

struct SwapOrderPackage {
  address target;
  address tokenIn;
  address tokenOut;
  uint256 amountIn;
  uint256 amountOutMin;
  bytes bridgePayloadSuccess;
  bytes bridgePayloadFailure;
  bool sent;
}

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.

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.

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

address token,
uint256 amount, 
bytes calldata payload

sendMessage

Emits an event with a message.

Parameters

bytes calldata payload

transferToUnwrap

Parameters

address token,
address recipient,
uint256 amount,
bytes32 salt,
SignaturePackage[] calldata proofs

finalizeUnwrap

Parameters

bytes32[] calldata orderHash

transferToSwap

(in contract BridgeEndpointWithSwap)`

Parameters

address target,
address tokenIn,
address tokenOut,
uint256 amountIn,
uint256 amountOutMin,
bytes calldata swapPayload,
bytes calldata bridgePayloadSuccess,
bytes calldata bridgePayloadFailure,
bytes32 salt,
SignaturePackage[] calldata proofs

finalizeSwap

(in contract BridgeEndpointWithSwap)`

Parameters

bytes32[] calldata orderHashes,
bytes[] calldata swapPayloads

Governance Features

setTimeLock

Updates the contract managing timelocks.

Parameters

address _timeLock

setTimeLockThreshold

Sets the global timelock threshold.

Parameters

uint256 _timeLockThreshold

setTimeLockThresholdByToken

Sets a custom timelock threshold per token.

Parameters

address token, 
uint256 _timeLockThreshold

addAllowList

Adds an address to the allowlist, granting it permission to perform specific contract actions.

removeAllowedList

Removes an address from the allowlist, revoking its access.

Parameters

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.

Parameters

address account

onAllowList

Returns true if the provided address is on the allowlist, which means it has permission to use the contract’s functions.

Relevant Internal Functions

_transfer

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

address token, 
uint256 amount

_validateOrder

Verifies if an order is legitimate by checking validator signatures.

Parameters

bytes32 orderHash, 
SignaturePackage[] calldata proofs

_finalizeUnwrap

Completes an unwrap transaction by transferring tokens to the recipient.

Parameters

bytes32 orderHash

_finalizeSwap

(in contract BridgeEndpointWithSwap)`

Parameters

bytes32 orderHash, 
bytes memory swapPayload

_executeSwap

(in contract BridgeEndpointWithSwap)`

Parameters

address tokenIn,
address tokenOut,
address target,
uint256 amountIn,
uint256 amountOutMin,
bytes memory swapPayload,
bytes memory bridgePayloadSuccess,
bytes memory bridgePayloadFailure

Events

SendMessageEvent

Emitted when a user sends a message without transferring tokens.

Parameters

address indexed from, 
uint256 value, 
bytes payload 

SendMessageWithTokenEvent

Emitted when a user initiates a peg-out order.

Parameters

address indexed from,
address indexed token,
uint256 amount,
uint256 fee,
bytes payload

TransferToUnwrapEvent

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

bytes32 orderHash,
bytes32 salt,
address indexed recipient,
address indexed token,
uint256 amount

FinalizeUnwrapEvent

Emitted when an unwrap order is finalized and tokens are successfully transferred to the recipient.

Parameters

bytes32 indexed orderHash

SetTimelockEvent

Parameters

address timeLock

SetTimeLockThresholdEvent

Emitted when the global time lock threshold is updated.

Parameters

uint256 timeLockThreshold

SetTimeLockThresholdByTokenEvent

Emitted when the time lock threshold for a specific token is updated.

Parameters

address token,
uint256 timeLockThreshold

SwapExecutorError

(only present in BridgeEndpointWithSwap)

Emitted when a swap operation fails during the bridge transfer.

Parameters

address indexed target, 
bytes reason

SwapOrderCreated

(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

bytes32 indexed orderHash,
address indexed target,
address indexed tokenIn,
address tokenOut,
uint256 amountIn,
uint256 amountOutMin,
bytes bridgePayloadSuccess,
bytes bridgePayloadFailure

SwapOrderFinalized

(only present in BridgeEndpointWithSwap)

Emitted when a swap order is executed and finalized, confirming a swap has been processed.

Parameters

bytes32 indexed orderHash,
address indexed executor,
uint256 amountOut,
bool success

TransferToSwapEvent

(only present in BridgeEndpointWithSwap)

Emitted when a token transfer and swap operation is executed.

Parameters

bytes32 orderHash,
address target,
bytes swapPayload,
address tokenIn,
address tokenOut,
uint256 amountIn,
uint256 amountOut,
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.

  • 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.

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 .

Stores unwrap orders that need to be finalized. It stores a mapping of structs, which contain a flag indicating whether the unwrap has been completed. bytes32 is a unique hash of the struct parameters, as calculated by .

A mapping of structs that contains details of swap orders.bytes32 is a unique hash of the swap parameters, as calculated by .

The contract checks that the token is approved, since has the onlyApprovedToken modifier. The function calls , which performs validations. Finally, the function emits a containing the transaction details, which will be reviewed by validators.

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 ), or from a non-EVM chain like Stacks, Bitcoin or Solana. Relayers listen for the corresponding event on the source chain and call 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 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 , which verifies that the order has not already been completed and transfers the token and amount stored in to the recipient. The order is then marked as completed, and the is emitted.

This function executes a swap before bridging tokens. If the token is burnable, the contract mints the required amount before swapping, calls to perform the swap and emits a recording the details. If it is not burnable, it saves swap details in the mapping and emits 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.

This function is used when a token is not burnable, leading to store the swap order instead of executing it immediately. It ensures input arrays are valid, and it loops through each orderHash and calls .

This internal function is responsible for processing token transfers when a user sends tokens into the bridge. It is called from and performs validations, calculates and deducts fees, and sends the correct amount of tokens to the pegInAddress.

This function is called by 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 to perform the swap. Finally, it marks the order as sent and emits a event.

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 for bridging and a is emitted. If the swap fails, the error is logged via SwapExecutorError, approvals are revoked and a with bridgePayloadFailure is emitted. In either case, the function will burn tokenIn tokens if applicable.

Emitted when is updated by the contract owner.

ITimeLock: the ITimeLock interface is utilized to interact with the contract by calling the createAgreement function when bridged amounts exceeds the threshold.

🎮
Ethereum Contract Addresses
sendMessageWithToken
timeLockThreshold
OrderPackage
transferToUnwrap
SwapOrderPackage
transferToSwap
sendMessageWithToken
_transfer
SendMessageWithTokenEvent
sendMessageWithToken
transferToUnwrap
_finalizeUnwrap()
unwrapSent
FinalizeUnwrapEvent
_executeSwap
TransferToSwapEvent
swapSent
SwapOrderCreated
transferToSwap
_finalizeSwap()
sendMessageWithToken
finalizeSwap
_executeSwap
SwapOrderFinalized
pegInAddress
SendMessageWithTokenEvent
SendMessageWithTokenEvent
timeLock
timeLock