Cross Peg-In Endpoints
Last updated
Last updated
Location: ./packages/contracts/bridge-stacks/contracts/
Deployed contracts: , .
This technical document provides a detailed overview of the module responsible for managing the peg-in process, enabling the transfer of assets from external EVM-like blockchains into the Stacks network. The contract serves as the operational interface for relayers to submit orders, which are validated against a threshold of required validators as determined in the cross-bridge-registry-v2-01
. The module's primary functionality is implemented through a suite of public functions that are distributed across the following contracts:
cross-peg-in-endpoint-v2-04
: handles bridging tokens from EVM-like blockchains to Stacks, leveraging cross-router to manage the routing of tokens to the appropriate destination.
cross-peg-in-v2-04-launchpad
: facilitates bridging tokens from EVM-like blockchains to Stacks, specifically for participation in launchpad activities.
cross-peg-in-v2-04-swap
: enables token bridging from EVM-like blockchains to Stacks while performing token swaps through predefined routes.
All contracts include the following variables unless otherwise specified.
is-paused
Variable
bool
A flag that indicates whether the peg-in process is paused. If set to true
, all operations are paused, preventing relayers from submitting new peg-in orders. The contract is initialized in a paused state by default.
use-whitelist
Variable
bool
A flag that determines whether the whitelist mechanism is enforced. When set to true
, only whitelisted users are authorized to perform restricted actions. By default, this value is false
.
whitelisted-users
Map
principal bool
A map that keeps track of the whitelist status of specific users. Each entry associates a user's principal with a boolean value indicating whether they are authorized to interact with the contract under a whitelist-enabled configuration. If true
, the user is allowed to perform actions that are otherwise restricted.
structured-data-prefix
, message-domain-main
, message-domain-test
: these constants are utilized in the validate-order
function to verify the signature consistency with the order hash.
transfer-to-cross
In cross-peg-in-endpoint-v2-04
contract.
This function enables peg-in operations to transfer tokens from an external EVM-like blockchain to Stacks. It validates the provided order by checking its hash and verifying signatures to meet a threshold of validators defined in cross-bridge-registry-v2-01
. If the order is valid, it mints or transfers the bridged tokens to the sender of the transaction (tx-sender
), and updates the token reserve for the source EVM chain. It then utilizes cross-router-v2-03
to route the tokens based on the destination chain. In case the validation fails, the function initiates a refund process.
Parameters
transfer-to-cross-swap
In cross-peg-in-v2-04-swap
contract.
This function facilitates advanced peg-in operations by incorporating token swapping during cross-chain transfers. It validates the order hash and signatures using cross-bridge-registry-v2-01
, ensuring compliance with routing configurations, such as token paths and output amounts. Upon successful validation, the bridged tokens are swapped and routed to the recipient using cross-router-v2-03
, following the same logic outlined in the transfer-to-cross
feature. If validation fails, the function processes a refund.
Parameters
transfer-to-launchpad
In cross-peg-in-v2-04-launchpad
contract.
Parameters
The following functions are tools to assist the off-chain activities.
Validation helpers (validate-cross-order
, validate-cross-swap-order
, validate-launchpad-order
).
Order creation helpers (create-cross-order
, create-cross-swap-order
, create-launchpad-order
).
Decoding helpers (decode-cross-order
, decode-cross-swap-order
, decode-launchpad-order
).
Relayer helper (is-approved-relayer-or-default
).
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
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
.
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
apply-whitelist
A public function, governed through the is-dao-or-extension
, that toggles the use of the whitelist in the contract. When enabled, only users who are on the whitelist are authorized to execute restricted actions within the contract.
Parameters
whitelist
A public function, governed through the is-dao-or-extension
, that allows authorized extensions, to add or remove a single user from the whitelist. It updates the whitelisted-users
map, where the user's principal is mapped to a bool
value (true
for accepted users and false
for denied users).
Parameters
whitelist-many
A public function, governed through the is-dao-or-extension
, that allows to batch add or remove multiple users from the whitelist. This function iteratively calls whitelist
, which handles the mapping of each user's principal to a bool value in the whitelisted-users
map.
Parameters
get-use-whitelist
get-validator-or-fail
Parameters
get-required-validators
get-approved-chain-or-fail
Parameters
get-token-reserve-or-default
Parameters
get-min-fee-or-default
Parameters
get-approved-pair-or-fail
Parameters
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 validate key components of the peg-in process, such as approved tokens, chain IDs, and relayers. It also handles updates to transaction statuses, token reserves, and validator signatures.
cross-router-v2-03
: this contract is used to validate routing details and execute cross-chain token transfers and swaps. It ensures that the provided routing tokens and factors align with the transfer requirements, performs swaps through amm-pool-v2-01
when multiple tokens are involved, validates minimum output amounts, and handles the final routing process for peg-in operations, including cross and cross-swap transactions.
alex-launchpad-v2-03
: this contract is used to validate and register peg-in operations specifically related to launchpad projects on the Stacks network.
token-trait
: in cross peg-in operations (featuring transfer-to-cross
, transfer-to-cross-swap
, and transfer-to-launchpad
) this trait is employed to interact with relevant tokens for obtaining their principals, minting, and executing necessary transfers within the transaction. It is a customized version of Stacks' standard definition for Fungible Tokens (sip-010
), with support for 8-digit fixed notation.
cross-peg-out-endpoint-v2-01
: this contract is invoked to manage refunds for peg-in operations that failed external validations.
ERR-NOT-AUTHORIZED
(err u1000)
ERR-TOKEN-NOT-AUTHORIZED
(err u1001)
ERR-DUPLICATE-SIGNATURE
(err u1009)
ERR-ORDER-HASH-MISMATCH
(err u1010)
ERR-INVALID-SIGNATURE
(err u1011)
ERR-UKNOWN-RELAYER
(err u1012)
ERR-REQUIRED-VALIDATORS
(err u1013)
ERR-ORDER-ALREADY-SENT
(err u1014)
ERR-PAUSED
(err u1015)
ERR-INVALID-VALIDATOR
(err u1016)
ERR-INVALID-INPUT
(err u1020)
ERR-NOT-IN-WHITELIST
(err u1021)
ERR-INVALID-TOKEN
(err u1022)
ERR-SLIPPAGE
(err u1023)
This function enables peg-in operations linked to . It validates the order and signatures through cross-bridge-registry-v2-01
and confirms compatibility with the launchpad parameters. Once validated, the function mints bridged tokens, transfers them to the recipient and registers the operation in the alex-launchpad-v2-03
contract. In case of validation failure, a refund is processed.