kylefang/xlink-docs
1
0
Fork 0
mirror of https://github.com/Brotocol-xyz/xlink-docs.git synced 2026-05-01 20:54:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #9 from CoinFabrik/docs/xlink-contracts-w3

Browse Source 
Developers: add xLINK contracts documentation (w3)
This commit is contained in:
fiftyeightandeight
2025-01-10 21:57:19 +08:00
committed by GitHub
parent a772f939e2 3470795a0e
commit b2f789ffd8
4 changed files with 371 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
SUMMARY.md
View File

@@ -30,6 +30,8 @@
* [btc-peg-out-endpoint-v2-01](developers/contracts/btc-peg-out-endpoint-v2-01.md)
* [meta peg-in endpoint v2-02](developers/contracts/meta-peg-in-endpoint-v2-02.md)
* [meta peg-out endpoint v2-03](developers/contracts/meta-peg-out-endpoint-v2-03.md)
* [cross-peg-in-endpoint-v2-03](developers/contracts/cross-peg-in-endpoint-v2-03.md)
* [cross-peg-out-endpoint-v2-01](developers/contracts/cross-peg-out-endpoint-v2-01.md)
* [xlink-staking](developers/contracts/xlink-staking.md)
<!--

4
developers/contracts/README.md
View File

@@ -8,4 +8,8 @@
## [meta-peg-out-endpoint-v2-03](meta-peg-out-endpoint-v2-03.md)
## [cross-peg-in-endpoint-v2-03](cross-peg-in-endpoint-v2-03.md)
## [cross-peg-out-endpoint-v2-01](cross-peg-out-endpoint-v2-01.md)
## [xlink-staking](xlink-staking.md)

229
developers/contracts/cross-peg-in-endpoint-v2-03.md Normal file
View File

@@ -0,0 +1,229 @@
# cross-peg-in-endpoint-v2-03.clar
- Location: `xlink/packages/contracts/bridge-stacks/contracts/cross-peg-in-endpoint-v2-03.clar`
- [Deployed contract]()
This technical document provides a detailed overview of the contract 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 contract's primary functionality is implemented through a suite of public functions. Let's review them.
## Storage
### `is-paused`
| Data | Type |
| -------- | ------ |
| Variable | `bool` |
A flag indicating whether the peg-in operations are currently active. 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`
| Data | Type |
| -------- | ------ |
| 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 within the contract. By default, this value is `false`.
### `order-hash-to-iter`
| Data | Type |
| -------- | ------ |
| Variable | `buff 32` |
A temporary variable used internally to store the hash of the current order being processed.
### `src-chain-id-to-iter`
| Data | Type |
| -------- | ------ |
| Variable | `uint` |
A temporary variable used to store the source chain ID of the order currently being processed.
### `whitelisted-users`
| Data | Type |
| -------- | ------ |
| 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.
### Relevant constants
* `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.
## Features
### Peg-in features
#### `transfer-to-cross`
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 and updates the token reserve for the source EVM chain. It then utilizes `cross-router-v2-02` to route the tokens based on the destination chain. In the event of validation failure, the function initiates a refund process.
##### Parameters
```lisp
(order {
from: (buff 128),
to: (buff 128),
token: principal,
amount-in-fixed: uint,
src-chain-id: uint,
dest-chain-id: (optional uint),
salt: (buff 256)
})
(token-trait <ft-trait>)
(signature-packs (list 100 {
signer: principal,
order-hash: (buff 32),
signature: (buff 65)
}))
```
#### `transfer-to-cross-swap`
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-02`, following the same logic outlined in the `transfer-to-cross` feature. If validation fails, the function processes a refund.
##### Parameters
```lisp
(order {
from: (buff 128),
to: (buff 128),
amount-in-fixed: uint,
routing-tokens: (list 5 principal),
routing-factors: (list 4 uint),
min-amount-out-fixed: (optional uint),
src-chain-id: uint,
dest-chain-id: (optional uint),
salt: (buff 256)
})
(routing-traits (list 5 <ft-trait>))
(signature-packs (list 100 {
signer: principal,
order-hash: (buff 32),
signature: (buff 65)
}))
```
#### `transfer-to-launchpad`
This function enables peg-in operations linked to launchpad projects. 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-01` contract. In case of validation failure, a refund is processed.
##### Parameters
```lisp
(order {
address: (buff 128),
chain-id: uint,
launch-id: uint,
dest: (buff 128),
token: principal,
amount-in-fixed: uint,
salt: (buff 256)
})
(token-trait <ft-trait>)
(signature-packs (list 100 {
signer: principal,
order-hash: (buff 32),
signature: (buff 65)
}))
```
### 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`
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
```lisp
(paused bool)
```
#### `apply-whitelist`
A public function 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
```lisp
(new-use-whitelist bool)
```
#### `whitelist`
A public function 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
```lisp
(user principal)
(whitelisted bool)
```
#### `whitelist-many`
A public function 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
```lisp
(users (list 2000 principal))
(whitelisted (list 2000 bool))
```
#### `execute`
A public function that deactivates earlier versions of the `cross-peg-in-endpoint` contract and ensures that only the latest version (`cross-peg-in-endpoint-v2-03`) remains active.
##### Parameters
```lisp
(sender principal)
```
### Getters
#### `get-use-whitelist``
#### `get-validator-or-fail`
##### Parameters
```lisp
(validator principal)
```
#### `get-required-validators`
#### `get-approved-chain-or-fail`
##### Parameters
```lisp
(src-chain-id uint)
```
#### `get-token-reserve-or-default`
##### Parameters
```lisp
(pair { token:principal, chain-id: uint })
```
#### `get-min-fee-or-default`
##### Parameters
```lisp
(pair { token:principal, chain-id: uint })
```
#### `get-approved-pair-or-fail`
##### 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 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-02`: 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-01`: 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.
## Errors
| Error Name | Value |
| ---------------- | ------------- |
| `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)` |
<!-- Documentation Contract Template v0.1.0 -->

136
developers/contracts/cross-peg-out-endpoint-v2-01.md Normal file
View File

@@ -0,0 +1,136 @@
# cross-peg-out-endpoint-v2-01.clar
- Location: `xlink/packages/contracts/bridge-stacks/contracts/cross-peg-out-endpoint-v2-01.clar`
- [Deployed contract]()
This technical document provides a detailed overview of the contract 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 the EVM-based assets. The contract manages token transfers by validating amounts, applying fees, and maintaining a whitelist for authorized users if enabled. 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 contract are implemented through a series of public and governance functions, as described below.
## Storage
### `is-paused`
| Data | Type |
| -------- | ------ |
| Variable | `bool` |
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`
| Data | Type |
| -------- | ------ |
| Variable | `bool` |
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`
| 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.
## Features
### Peg-out feature
#### `transfer-to-unwrap`
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
```lisp
(token-trait <ft-trait>)
(amount-in-fixed uint)
(dest-chain-id uint)
(settle-address (buff 256))
```
### 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`
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
```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
```lisp
(paused bool)
```
#### `apply-whitelist`
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
```lisp
(new-use-whitelist bool)
```
#### `whitelist`
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
```lisp
(user principal)
(whitelisted bool)
```
#### `whitelist-many`
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
```lisp
(users (list 2000 principal))
(whitelisted (list 2000 bool))
```
### Getters
#### `get-use-whitelist`
#### `get-approved-chain-or-fail`
##### Parameters
```lisp
(dest-chain-id uint)
```
#### `get-token-reserve-or-default`
##### Parameters
```lisp
(pair { token: principal, chain-id: uint })
```
#### `get-min-fee-or-default`
##### Parameters
```lisp
(pair { token: principal, chain-id: uint })
```
#### `get-approved-pair-or-fail`
##### 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.
## 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 -->