BridgeEndpoint
Last updated
Last updated
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.
registry
Variable
BridgeRegistry
Stores a reference to the BridgeRegistry
contract, which manages approved tokens, relayers, and validators.
pegInAddress
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
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
Variable
uint256
The global minimum token amount that triggers a timelock. By default, the value is set to 0
.
timeLockThresholdByToken
Variable
mapping(address => uint256)
unwrapSent
Variable
mapping(bytes32 => OrderPackage)
swapExecutor
(only present in BridgeEndpointWithSwap)
Variable
SwapExecutor
Holds a reference to SwapExecutor
, which is the contract that executes swaps.
swapSent
(only present in BridgeEndpointWithSwap)
Variable
mapping(bytes32 => SwapOrderPackage)
OrderPackage
Holds details of a pending unwrap operation.
SignaturePackage
Contains signatures from validators to prove an order is legitimate. It is used for verifying cross-chain transfers.
SwapOrderPackage
(only present in BridgeEndpointWithSwap)
A struct that stores details of a swap order.
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.
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
sendMessage
Emits an event with a message.
Parameters
transferToUnwrap
Parameters
finalizeUnwrap
Parameters
transferToSwap
(in contract BridgeEndpointWithSwap)`
Parameters
finalizeSwap
(in contract BridgeEndpointWithSwap)`
Parameters
setTimeLock
Updates the contract managing timelocks.
Parameters
setTimeLockThreshold
Sets the global timelock threshold.
Parameters
setTimeLockThresholdByToken
Sets a custom timelock threshold per token.
Parameters
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
pause
Pauses the contract, preventing token transfers until the contract is unpaused.
unpause
Resumes contract operations after a pause, allowing bridging and transfers again.
offAllowList
Returns true
if the provided address is not on the allowlist.
Parameters
onAllowList
Returns true
if the provided address is on the allowlist, which means it has permission to use the contract’s 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
_validateOrder
Verifies if an order is legitimate by checking validator signatures.
Parameters
_finalizeUnwrap
Completes an unwrap transaction by transferring tokens to the recipient.
Parameters
_finalizeSwap
(in contract BridgeEndpointWithSwap)`
Parameters
_executeSwap
(in contract BridgeEndpointWithSwap)`
Parameters
SendMessageEvent
Emitted when a user sends a message without transferring tokens.
Parameters
SendMessageWithTokenEvent
Emitted when a user initiates a peg-out order.
Parameters
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
FinalizeUnwrapEvent
Emitted when an unwrap order is finalized and tokens are successfully transferred to the recipient.
Parameters
SetTimelockEvent
Parameters
SetTimeLockThresholdEvent
Emitted when the global time lock threshold is updated.
Parameters
SetTimeLockThresholdByTokenEvent
Emitted when the time lock threshold for a specific token is updated.
Parameters
SwapExecutorError
(only present in BridgeEndpointWithSwap)
Emitted when a swap operation fails during the bridge transfer.
Parameters
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
SwapOrderFinalized
(only present in BridgeEndpointWithSwap)
Emitted when a swap order is executed and finalized, confirming a swap has been processed.
Parameters
TransferToSwapEvent
(only present in BridgeEndpointWithSwap)
Emitted when a token transfer and swap operation is executed.
Parameters
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.