kylefang/bro-sdk
1
0
Fork 0
mirror of https://github.com/Brotocol-xyz/bro-sdk.git synced 2026-01-12 06:44:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: use typedoc to maintain documents (#4)

Browse Source 
* add typedoc comments

* fix merge error

* update dev-dependencies to include typedoc

* update package json

* add errors to typedoc

* add use cases and missing function to typedoc

* README refactor and link to typedoc for documentation

---------

Co-authored-by: ignacio.pena@coinfabrik.com <ignacio.pena@coinfabrik.com>
Co-authored-by: david weil <david.weil@endlesstruction.com.ar>
This commit is contained in:
david weil
2024-08-28 20:26:06 -03:00
committed by GitHub
parent 96ab1b3b79
commit 12eef24476
7 changed files with 570 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
README.md
View File

@@ -60,160 +60,124 @@ Note: Users can transfer between different coins/tokens, not just the same token
### XLink SDK
The `XLinkSDK` object contains the most important functions of this library, all grouped together. To create it:
```typescript
const theSdk = new XLinkSDK();
```
These functions are part of the `XLinkSDK` object:
For detailed API documentation, including a full list of available methods and their usage, please refer to:
#### bridgeFromBitcoin
[SDK API Documentation](https://docs-typedoc.xlink-sdk.pages.dev/classes/XLinkSDK.XLinkSDK)
This function facilitates the transfer of tokens from the Bitcoin network to other supported blockchain networks. It checks the validity of the route and then calls the appropriate bridging function based on the destination chain.
### USE CASES
Create an instance of the SDK with default options
```typescript
bridgeFromBitcoin(input: BridgeFromBitcoinInput): Promise<BridgeFromBitcoinOutput>
import{ XLinkSDK } from '@xlink-project/xlink-sdk/src';
const xlinkSdk = new XLinkSDK();
```
1. Bridge from Stacks
```typescript
import { BridgeInfoFromStacksInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeInfoFromStacks';
import { BridgeFromStacksInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeFromStacks';
import { KnownChainId, KnownTokenId } from '@xlink-project/xlink-sdk/src/utils/types/knownIds';
// Get bridge info
const bridgeInfo = await xlinkSdk.bridgeInfoFromStacks({
fromChain: KnownChainId.Stacks.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.Stacks.sUSDT,
toToken: KnownTokenId.EVM.USDT,
amount: 100,
} as BridgeInfoFromStacksInput);
console.log("Bridge Info:", bridgeInfo);
// Perform the bridge operation
const result = await xlinkSdk.bridgeFromStacks({
fromChain: KnownChainId.Stacks.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.Stacks.sUSDT,
toToken: KnownTokenId.EVM.USDT,
toAddress: "0x...",
amount: 10,
sendTransaction: async (tx: ContractCallOptions) => {
// Implementation for sending transaction from Stacks mainnet
const network = new StacksMainnet();
const transaction = await makeContractCall({
contractAddress: tx.contractAddress,
contractName: tx.contractName,
functionName: tx.functionName,
functionArgs: tx.functionArgs,
senderKey: /* sender address private key */,
network,
postConditions: tx.postConditions,
anchorMode: tx.anchorMode,
});
const broadcastResponse = await broadcastTransaction(transaction, network);
return broadcastResponse.txid;
}
} as BridgeFromStacksInput);
console.log("Transaction ID:", result.txid);
```
Possible exceptions: `UnsupportedBridgeRouteError`.
#### bridgeFromEVM
This function facilitates the transfer of tokens from an EVM-compatible blockchain to other supported blockchain networks, including Stacks, Bitcoin, and other EVM-compatible chains. It validates the route and calls the appropriate bridging function based on the destination chain and tokens involved.
2. Bridge from EVM
```typescript
bridgeFromEVM(input: BridgeFromEVMInput): Promise<BridgeFromEVMOutput>
```
Possible exceptions: `UnsupportedBridgeRouteError`.
import { BridgeInfoFromEVMInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeInfoFromEVM';
import { BridgeFromEVMInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeFromEVM';
import { KnownChainId, KnownTokenId } from '@xlink-project/xlink-sdk/src/utils/types/knownIds';
#### bridgeFromStacks
This function facilitates the transfer of tokens from the Stacks network to other supported blockchain networks, including Bitcoin and EVM-compatible chains. It validates the route and calls the appropriate bridging function based on the destination chain and tokens involved.
```typescript
bridgeFromStacks(input: BridgeFromStacksInput): Promise<BridgeFromStacksOutput>
```
Possible exceptions: `UnsupportedBridgeRouteError`.
// Get bridge info
const bridgeInfo = await xlinkSdk.bridgeInfoFromEVM({
fromChain: KnownChainId.EVM.Ethereum,
toChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.EVM.USDT,
toToken: KnownTokenId.Stacks.sUSDT,
amount: 100,
} as BridgeInfoFromEVMInput);
console.log("Bridge Info:", bridgeInfo);
#### bridgeInfoFromBitcoin
This function provides detailed information about token transfers from the Bitcoin network to other supported blockchain networks, including Stacks and EVM-compatible chains. It verifies the validity of the transfer route and retrieves bridge information based on the destination chain.
```typescript
const bridgeInfoFromBitcoin = async (info: BridgeInfoFromBitcoinInput): Promise<BridgeInfoFromBitcoinOutput>
```
Possible exceptions: `UnsupportedBridgeRouteError`.
#### bridgeInfoFromEVM
This function provides detailed information about token transfers from an EVM-compatible blockchain to other supported blockchain networks, including Stacks, Bitcoin, and other EVM-compatible chains. It verifies the validity of the transfer route and retrieves bridge information based on the destination chain and tokens.
```typescript
bridgeInfoFromEVM(input: BridgeInfoFromEVMInput): Promise<BridgeInfoFromEVMOutput>
```
Possible exceptions: `UnsupportedBridgeRouteError`.
#### bridgeInfoFromStacks
This function provides detailed information about token transfers from the Stacks network to other supported blockchain networks, including Bitcoin and EVM-compatible chains. It verifies the validity of the transfer route and retrieves bridge information based on the destination chain and tokens.
```typescript
bridgeInfoFromStacks(input: BridgeInfoFromStacksInput): Promise<BridgeInfoFromStacksOutput>
```
Possible exceptions: `UnsupportedBridgeRouteError`.
#### claimTimeLockedAssetsFromEVM
This function facilitates the claiming of time-locked assets on EVM-compatible chains. It uses smart contract functions to execute the release of locked assets based on predefined conditions.
```typescript
claimTimeLockedAssetsFromEVM(input: ClaimTimeLockedAssetsInput): Promise<undefined | ClaimTimeLockedAssetsOutput>
// Perform the bridge operation
const result = await xlinkSdk.bridgeFromEVM({
fromChain: KnownChainId.EVM.Ethereum,
toChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.EVM.USDT,
toToken: KnownTokenId.Stacks.sUSDT,
toAddress: "0x...",
amount: 10,
sendTransaction: // Implementation for sending transaction from EVM chain
} as BridgeFromEVMInput);
console.log("Transaction ID:", result.txHash);
```
Possible exceptions: `UnsupportedChainError`.
#### getTimeLockedAssetsFromEVM
This function retrieves a list of time-locked assets for a given wallet address across multiple EVM-compatible blockchain networks. It queries smart contracts to find and return information about the assets that are currently locked in time-based agreements.
3. Bridge from Bitcoin
```typescript
getTimeLockedAssetsFromEVM(input: GetTimeLockedAssetsInput): Promise<GetTimeLockedAssetsOutput>
```
import { BridgeInfoFromBitcoinInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeInfoFromBitcoin';
import { BridgeFromBitcoinInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeFromBitcoin';
import { KnownChainId, KnownTokenId } from '@xlink-project/xlink-sdk/src/utils/types/knownIds';
Possible exceptions: `UnsupportedChainError`.
// Get bridge info
const bridgeInfo = await xlinkSdk.bridgeInfoFromBitcoin({
fromChain: KnownChainId.Bitcoin.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
amount: 1,
} as BridgeInfoFromBitcoinInput);
console.log("Bridge Info:", bridgeInfo);
#### estimateBridgeTransactionFromBitcoin
This function estimates the transaction fee and vSize for move or swap tokens from the Bitcoin network to other supported blockchain networks, including Stacks and EVM-compatible chains.
```typescript
estimateBridgeTransactionFromBitcoin(input: EstimateBridgeTransactionFromBitcoinInput): Promise<EstimateBridgeTransactionFromBitcoinOutput>
```
Possible exceptions: `UnsupportedBridgeRouteError`
#### evmAddressFromEVMToken
This function retrieves the contract address of a specific token on a given EVM-compatible blockchain.
```typescript
async evmAddressFromEVMToken(chain: ChainId, token: KnownTokenId.EVMToken): Promise<undefined | EVMAddress>
```
Possible exceptions: None. The function returns `undefined` if the chain is not EVM-compatible or if the contract address cannot be retrieved.
#### evmAddressToEVMToken
This function maps a given contract address on an EVM-compatible blockchain to its corresponding known token ID.
```typescript
async evmAddressToEVMToken(chain: ChainId, address: EVMAddress): Promise<undefined | KnownTokenId.EVMToken>
```
Possible exceptions: None. The function returns `undefined` if the chain is not EVM-compatible or if the address cannot be matched.
#### getEVMContractAddress
This function retrieves the contract address of a specific type of contract (e.g., a bridge endpoint) on a given EVM-compatible blockchain.
```typescript
async getEVMContractAddress(chain: ChainId, contractType: PublicEVMContractType): Promise<undefined | EVMAddress>
```
Possible exceptions: None. The function returns `undefined` if the chain is not EVM-compatible or if the address cannot be matched.
#### getSupportedRoutes
This function retrieves the list of supported routes for token transfers between blockchain networks, filtered based on optional conditions. It aggregates the results from different blockchain networks (Stacks, EVM, Bitcoin) to return a list of possible routes.
```typescript
async getSupportedRoutes(conditions?: GetSupportedRoutesFn_Conditions): Promise<KnownRoute[]>
```
Possible exceptions: None.
#### stacksAddressFromStacksToken
This function retrieves the contract address associated with a specific token on the Stacks blockchain.
```typescript
async function stacksAddressFromStacksToken(chain: ChainId, token: KnownTokenId.StacksToken): Promise<undefined | StacksContractAddress>
```
Possible exceptions: None. The function returns `undefined` if the chainId or token is not valid.
#### stacksAddressToStacksToken
This function maps a given Stacks contract address to its corresponding known token ID.
```typescript
async function stacksAddressToStacksToken(chain: ChainId, address: StacksContractAddress): Promise<undefined | KnownTokenId.StacksToken>
```
Possible exceptions: None. The function returns `undefined` if the chainId or address is not valid.
### Errors
- `InvalidMethodParametersError`: It is thrown when a method in the SDK receives invalid parameters.
- `UnsupportedBridgeRouteError`: It is thrown when an attempt is made to bridge tokens between unsupported chains in the SDK.
- `UnsupportedChainError`: It is thrown when a method in the SDK receives an unknown chain.
- `UnsupportedContractAssignedChainIdError`: It is thrown when a smart contract is assigned an unknown or unsupported chain ID.
- `XLinkSDKErrorBase`: Extends the Error class and serves as the base for all custom errors within the SDK.
// Perform the bridge operation
const result = await xlinkSdk.bridgeFromBitcoin({
fromChain: KnownChainId.Bitcoin.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.Bitcoin.BTC,
toToken: KnownTokenId.EVM.WBTC,
fromAddress: "bitcoin address",
fromAddressScriptPubKey: scriptPubKey,
toAddress: "0x...",
amount: 1,
networkFeeRate: 10n,
reselectSpendableUTXOs: // Implementation for reselect UTXOs
signPsbt: // Implementation for signing PSBT
} as BridgeFromBitcoinInput);
console.log("Transaction ID:", result.tx);
```

2
package.json
View File

@@ -34,6 +34,7 @@
"scripts": {
"gen:stacksContract": "rm -rf generated/smartContract && mkdir -p generated/smartContract && tsx ./scripts/generateClarityTranscoders.ts",
"gen": "pnpm run gen:stacksContract",
"docs": "npx typedoc src/index.ts",
"build": "pnpm run gen && rm -rf lib && tsup-node --sourcemap --dts -d lib --format cjs,esm src",
"prepare": "pnpm run build",
"test": "vitest --exclude lib"
@@ -57,6 +58,7 @@
"prettier": "^3.2.5",
"tsup": "^8.0.2",
"tsx": "^4.7.2",
"typedoc": "^0.26.6",
"typescript": "^5.4.5",
"viem": "^2.15.1",
"vitest": "^1.4.0"

160
pnpm-lock.yaml generated
View File

@@ -21,7 +21,7 @@ importers:
devDependencies:
'@c4605/toolconfs':
specifier: ^5.3.0
version: 5.3.0(@typescript-eslint/eslint-plugin@7.17.0)(@typescript-eslint/experimental-utils@5.62.0)(@typescript-eslint/parser@7.17.0)(eslint-config-prettier@9.1.0)(eslint-plugin-prettier@5.2.1)(eslint@8.57.0)(prettier@3.3.3)
version: 5.3.0(@typescript-eslint/eslint-plugin@7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4))(@typescript-eslint/experimental-utils@5.62.0(eslint@8.57.0)(typescript@5.5.4))(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint-plugin-prettier@5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3))(eslint@8.57.0)(prettier@3.3.3)
'@stacks/network':
specifier: ^6.13.0
version: 6.16.0
@@ -36,7 +36,7 @@ importers:
version: 6.2.2
'@typescript-eslint/eslint-plugin':
specifier: ^7.5.0
version: 7.17.0(@typescript-eslint/parser@7.17.0)(eslint@8.57.0)(typescript@5.5.4)
version: 7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4)
'@typescript-eslint/parser':
specifier: ^7.5.0
version: 7.17.0(eslint@8.57.0)(typescript@5.5.4)
@@ -51,16 +51,19 @@ importers:
version: 9.1.0(eslint@8.57.0)
eslint-plugin-prettier:
specifier: ^5.1.3
version: 5.2.1(eslint-config-prettier@9.1.0)(eslint@8.57.0)(prettier@3.3.3)
version: 5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3)
prettier:
specifier: ^3.2.5
version: 3.3.3
tsup:
specifier: ^8.0.2
version: 8.2.3(tsx@4.16.2)(typescript@5.5.4)
version: 8.2.3(postcss@8.4.40)(tsx@4.16.2)(typescript@5.5.4)(yaml@2.5.0)
tsx:
specifier: ^4.7.2
version: 4.16.2
typedoc:
specifier: ^0.26.6
version: 0.26.6(typescript@5.5.4)
typescript:
specifier: ^5.4.5
version: 5.5.4
@@ -69,7 +72,7 @@ importers:
version: 2.18.4(typescript@5.5.4)
vitest:
specifier: ^1.4.0
version: 1.6.0
version: 1.6.0(@types/node@18.19.42)
packages:
@@ -588,6 +591,9 @@ packages:
'@scure/btc-signer@1.3.2':
resolution: {integrity: sha512-BmcQHvxaaShKwgbFC0vDk0xzqbMhNtNmgXm6u7cz07FNtGsVItUuHow6NbgHmc+oJSBZJRym5dz8+Uu0JoEJhQ==}
'@shikijs/core@1.14.1':
resolution: {integrity: sha512-KyHIIpKNaT20FtFPFjCQB5WVSTpLR/n+jQXhWHWVUMm9MaOaG9BGOG0MSyt7yA4+Lm+4c9rTc03tt3nYzeYSfw==}
'@sinclair/typebox@0.27.8':
resolution: {integrity: sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==}
@@ -612,6 +618,9 @@ packages:
'@types/estree@1.0.5':
resolution: {integrity: sha512-/kYRxGDLWzHOB7q+wtSUQlFrtcdUccpfy+X+9iMBpHK8QLLhx2wIPYuS5DYtR9Wa/YlZAbIovy7qVdB1Aq6Lyw==}
'@types/hast@3.0.4':
resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
'@types/json-schema@7.0.15':
resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
@@ -621,6 +630,9 @@ packages:
'@types/semver@7.5.8':
resolution: {integrity: sha512-I8EUhyrgfLrcTkzV3TSsGyl1tSuPrEDzr0yd5m90UgNxQkyDXULk3b6MlQqTCpZpNtWe1K0hzclnZkTcLBe2UQ==}
'@types/unist@3.0.3':
resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
'@typescript-eslint/eslint-plugin@7.17.0':
resolution: {integrity: sha512-pyiDhEuLM3PuANxH7uNYan1AaFs5XE0zw1hq69JBvGvE7gSuEoQl1ydtEe/XQeoC3GQxLXyOVa5kNOATgM638A==}
engines: {node: ^18.18.0 || >=20.0.0}
@@ -940,6 +952,10 @@ packages:
emoji-regex@9.2.2:
resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
entities@4.5.0:
resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
engines: {node: '>=0.12'}
esbuild@0.21.5:
resolution: {integrity: sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==}
engines: {node: '>=12'}
@@ -1246,6 +1262,9 @@ packages:
lines-and-columns@1.2.4:
resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
linkify-it@5.0.0:
resolution: {integrity: sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==}
load-tsconfig@0.2.5:
resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==}
engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
@@ -1276,9 +1295,19 @@ packages:
lru-cache@10.4.3:
resolution: {integrity: sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==}
lunr@2.3.9:
resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==}
magic-string@0.30.11:
resolution: {integrity: sha512-+Wri9p0QHMy+545hKww7YAu5NyzF8iomPL/RQazugQ9+Ez4Ic3mERMd8ZTX5rfK944j+560ZJi8iAwgak1Ac7A==}
markdown-it@14.1.0:
resolution: {integrity: sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==}
hasBin: true
mdurl@2.0.0:
resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==}
merge-stream@2.0.0:
resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
@@ -1482,6 +1511,10 @@ packages:
proxy-from-env@1.1.0:
resolution: {integrity: sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==}
punycode.js@2.3.1:
resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==}
engines: {node: '>=6'}
punycode@2.3.1:
resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
engines: {node: '>=6'}
@@ -1541,6 +1574,9 @@ packages:
resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
engines: {node: '>=8'}
shiki@1.14.1:
resolution: {integrity: sha512-FujAN40NEejeXdzPt+3sZ3F2dx1U24BY2XTY01+MG8mbxCiA2XukXdcbyMyLAHJ/1AUUnQd1tZlvIjefWWEJeA==}
siginfo@2.0.0:
resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
@@ -1705,11 +1741,21 @@ packages:
resolution: {integrity: sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==}
engines: {node: '>=10'}
typedoc@0.26.6:
resolution: {integrity: sha512-SfEU3SH3wHNaxhFPjaZE2kNl/NFtLNW5c1oHsg7mti7GjmUj1Roq6osBQeMd+F4kL0BoRBBr8gQAuqBlfFu8LA==}
engines: {node: '>= 18'}
hasBin: true
peerDependencies:
typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x
typescript@5.5.4:
resolution: {integrity: sha512-Mtq29sKDAEYP7aljRgtPOpTvOfbwRWlS6dPRzwjdE+C0R4brX/GUyhHSecbHMFLNBLcJIPt9nl9yG5TZ1weH+Q==}
engines: {node: '>=14.17'}
hasBin: true
uc.micro@2.1.0:
resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==}
ufo@1.5.4:
resolution: {integrity: sha512-UsUk3byDzKd04EyoZ7U4DOlxQaD14JUKQl6/P7wiX4FNvUfm3XL246n9W5AmqwW5RSFJ27NAuM0iLscAOYUiGQ==}
@@ -1841,6 +1887,11 @@ packages:
resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
engines: {node: '>=10'}
yaml@2.5.0:
resolution: {integrity: sha512-2wWLbGbYDiSqqIKoPjar3MPgB94ErzCtrNE1FdqGuaO0pi2JGjmE8aW8TDZwzU7vuxcGRdL/4gPQwQ7hD5AMSw==}
engines: {node: '>= 14'}
hasBin: true
yargs-parser@21.1.1:
resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
engines: {node: '>=12'}
@@ -1868,14 +1919,15 @@ snapshots:
optionalDependencies:
'@scure/btc-signer': 1.3.2
'@c4605/toolconfs@5.3.0(@typescript-eslint/eslint-plugin@7.17.0)(@typescript-eslint/experimental-utils@5.62.0)(@typescript-eslint/parser@7.17.0)(eslint-config-prettier@9.1.0)(eslint-plugin-prettier@5.2.1)(eslint@8.57.0)(prettier@3.3.3)':
'@c4605/toolconfs@5.3.0(@typescript-eslint/eslint-plugin@7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4))(@typescript-eslint/experimental-utils@5.62.0(eslint@8.57.0)(typescript@5.5.4))(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint-plugin-prettier@5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3))(eslint@8.57.0)(prettier@3.3.3)':
dependencies:
'@typescript-eslint/eslint-plugin': 7.17.0(@typescript-eslint/parser@7.17.0)(eslint@8.57.0)(typescript@5.5.4)
'@typescript-eslint/experimental-utils': 5.62.0(eslint@8.57.0)(typescript@5.5.4)
optionalDependencies:
'@typescript-eslint/eslint-plugin': 7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4)
'@typescript-eslint/parser': 7.17.0(eslint@8.57.0)(typescript@5.5.4)
eslint: 8.57.0
eslint-config-prettier: 9.1.0(eslint@8.57.0)
eslint-plugin-prettier: 5.2.1(eslint-config-prettier@9.1.0)(eslint@8.57.0)(prettier@3.3.3)
eslint-plugin-prettier: 5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3)
prettier: 3.3.3
'@esbuild/aix-ppc64@0.21.5':
@@ -2185,6 +2237,10 @@ snapshots:
micro-packed: 0.6.3
optional: true
'@shikijs/core@1.14.1':
dependencies:
'@types/hast': 3.0.4
'@sinclair/typebox@0.27.8': {}
'@stacks/common@6.16.0':
@@ -2220,6 +2276,10 @@ snapshots:
'@types/estree@1.0.5': {}
'@types/hast@3.0.4':
dependencies:
'@types/unist': 3.0.3
'@types/json-schema@7.0.15': {}
'@types/node@18.19.42':
@@ -2228,7 +2288,9 @@ snapshots:
'@types/semver@7.5.8': {}
'@typescript-eslint/eslint-plugin@7.17.0(@typescript-eslint/parser@7.17.0)(eslint@8.57.0)(typescript@5.5.4)':
'@types/unist@3.0.3': {}
'@typescript-eslint/eslint-plugin@7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4)':
dependencies:
'@eslint-community/regexpp': 4.11.0
'@typescript-eslint/parser': 7.17.0(eslint@8.57.0)(typescript@5.5.4)
@@ -2241,6 +2303,7 @@ snapshots:
ignore: 5.3.1
natural-compare: 1.4.0
ts-api-utils: 1.3.0(typescript@5.5.4)
optionalDependencies:
typescript: 5.5.4
transitivePeerDependencies:
- supports-color
@@ -2261,6 +2324,7 @@ snapshots:
'@typescript-eslint/visitor-keys': 7.17.0
debug: 4.3.6
eslint: 8.57.0
optionalDependencies:
typescript: 5.5.4
transitivePeerDependencies:
- supports-color
@@ -2282,6 +2346,7 @@ snapshots:
debug: 4.3.6
eslint: 8.57.0
ts-api-utils: 1.3.0(typescript@5.5.4)
optionalDependencies:
typescript: 5.5.4
transitivePeerDependencies:
- supports-color
@@ -2299,6 +2364,7 @@ snapshots:
is-glob: 4.0.3
semver: 7.6.3
tsutils: 3.21.0(typescript@5.5.4)
optionalDependencies:
typescript: 5.5.4
transitivePeerDependencies:
- supports-color
@@ -2313,6 +2379,7 @@ snapshots:
minimatch: 9.0.5
semver: 7.6.3
ts-api-utils: 1.3.0(typescript@5.5.4)
optionalDependencies:
typescript: 5.5.4
transitivePeerDependencies:
- supports-color
@@ -2385,7 +2452,7 @@ snapshots:
pretty-format: 29.7.0
abitype@1.0.5(typescript@5.5.4):
dependencies:
optionalDependencies:
typescript: 5.5.4
acorn-jsx@5.3.2(acorn@8.12.1):
@@ -2581,6 +2648,8 @@ snapshots:
emoji-regex@9.2.2: {}
entities@4.5.0: {}
esbuild@0.21.5:
optionalDependencies:
'@esbuild/aix-ppc64': 0.21.5
@@ -2642,13 +2711,14 @@ snapshots:
dependencies:
eslint: 8.57.0
eslint-plugin-prettier@5.2.1(eslint-config-prettier@9.1.0)(eslint@8.57.0)(prettier@3.3.3):
eslint-plugin-prettier@5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3):
dependencies:
eslint: 8.57.0
eslint-config-prettier: 9.1.0(eslint@8.57.0)
prettier: 3.3.3
prettier-linter-helpers: 1.0.0
synckit: 0.9.1
optionalDependencies:
eslint-config-prettier: 9.1.0(eslint@8.57.0)
eslint-scope@5.1.1:
dependencies:
@@ -2946,6 +3016,10 @@ snapshots:
lines-and-columns@1.2.4: {}
linkify-it@5.0.0:
dependencies:
uc.micro: 2.1.0
load-tsconfig@0.2.5: {}
local-pkg@0.5.0:
@@ -2971,10 +3045,23 @@ snapshots:
lru-cache@10.4.3: {}
lunr@2.3.9: {}
magic-string@0.30.11:
dependencies:
'@jridgewell/sourcemap-codec': 1.5.0
markdown-it@14.1.0:
dependencies:
argparse: 2.0.1
entities: 4.5.0
linkify-it: 5.0.0
mdurl: 2.0.0
punycode.js: 2.3.1
uc.micro: 2.1.0
mdurl@2.0.0: {}
merge-stream@2.0.0: {}
merge2@1.4.1: {}
@@ -3114,10 +3201,13 @@ snapshots:
mlly: 1.7.1
pathe: 1.1.2
postcss-load-config@6.0.1(tsx@4.16.2):
postcss-load-config@6.0.1(postcss@8.4.40)(tsx@4.16.2)(yaml@2.5.0):
dependencies:
lilconfig: 3.1.2
optionalDependencies:
postcss: 8.4.40
tsx: 4.16.2
yaml: 2.5.0
postcss@8.4.40:
dependencies:
@@ -3141,6 +3231,8 @@ snapshots:
proxy-from-env@1.1.0: {}
punycode.js@2.3.1: {}
punycode@2.3.1: {}
queue-microtask@1.2.3: {}
@@ -3199,6 +3291,11 @@ snapshots:
shebang-regex@3.0.0: {}
shiki@1.14.1:
dependencies:
'@shikijs/core': 1.14.1
'@types/hast': 3.0.4
siginfo@2.0.0: {}
signal-exit@3.0.7: {}
@@ -3304,7 +3401,7 @@ snapshots:
tslib@2.6.3: {}
tsup@8.2.3(tsx@4.16.2)(typescript@5.5.4):
tsup@8.2.3(postcss@8.4.40)(tsx@4.16.2)(typescript@5.5.4)(yaml@2.5.0):
dependencies:
bundle-require: 5.0.0(esbuild@0.23.0)
cac: 6.7.14
@@ -3316,12 +3413,14 @@ snapshots:
globby: 11.1.0
joycon: 3.1.1
picocolors: 1.0.1
postcss-load-config: 6.0.1(tsx@4.16.2)
postcss-load-config: 6.0.1(postcss@8.4.40)(tsx@4.16.2)(yaml@2.5.0)
resolve-from: 5.0.0
rollup: 4.19.1
source-map: 0.8.0-beta.0
sucrase: 3.35.0
tree-kill: 1.2.2
optionalDependencies:
postcss: 8.4.40
typescript: 5.5.4
transitivePeerDependencies:
- jiti
@@ -3349,8 +3448,19 @@ snapshots:
type-fest@0.20.2: {}
typedoc@0.26.6(typescript@5.5.4):
dependencies:
lunr: 2.3.9
markdown-it: 14.1.0
minimatch: 9.0.5
shiki: 1.14.1
typescript: 5.5.4
yaml: 2.5.0
typescript@5.5.4: {}
uc.micro@2.1.0: {}
ufo@1.5.4: {}
undici-types@5.26.5: {}
@@ -3368,21 +3478,22 @@ snapshots:
'@scure/bip39': 1.3.0
abitype: 1.0.5(typescript@5.5.4)
isows: 1.0.4(ws@8.17.1)
typescript: 5.5.4
webauthn-p256: 0.0.5
ws: 8.17.1
optionalDependencies:
typescript: 5.5.4
transitivePeerDependencies:
- bufferutil
- utf-8-validate
- zod
vite-node@1.6.0:
vite-node@1.6.0(@types/node@18.19.42):
dependencies:
cac: 6.7.14
debug: 4.3.6
pathe: 1.1.2
picocolors: 1.0.1
vite: 5.3.5
vite: 5.3.5(@types/node@18.19.42)
transitivePeerDependencies:
- '@types/node'
- less
@@ -3393,15 +3504,16 @@ snapshots:
- supports-color
- terser
vite@5.3.5:
vite@5.3.5(@types/node@18.19.42):
dependencies:
esbuild: 0.21.5
postcss: 8.4.40
rollup: 4.19.1
optionalDependencies:
'@types/node': 18.19.42
fsevents: 2.3.3
vitest@1.6.0:
vitest@1.6.0(@types/node@18.19.42):
dependencies:
'@vitest/expect': 1.6.0
'@vitest/runner': 1.6.0
@@ -3420,9 +3532,11 @@ snapshots:
strip-literal: 2.1.0
tinybench: 2.8.0
tinypool: 0.8.4
vite: 5.3.5
vite-node: 1.6.0
vite: 5.3.5(@types/node@18.19.42)
vite-node: 1.6.0(@types/node@18.19.42)
why-is-node-running: 2.3.0
optionalDependencies:
'@types/node': 18.19.42
transitivePeerDependencies:
- less
- lightningcss
@@ -3481,6 +3595,8 @@ snapshots:
y18n@5.0.8: {}
yaml@2.5.0: {}
yargs-parser@21.1.1: {}
yargs@17.7.2:

237
src/XLinkSDK.ts
View File

@@ -151,6 +151,19 @@ export class XLinkSDK {
}
}
/**
* This function retrieves the list of supported routes for token transfers between blockchain
* networks, filtered based on optional conditions. It aggregates the results from different
* blockchain networks (Stacks, EVM, Bitcoin) to return a list of possible routes.
* @param conditions - An optional object containing the conditions for filtering the supported routes:
* - `fromChain?: ChainId` - The ID of the source blockchain (optional).
* - `toChain?: ChainId` - The ID of the destination blockchain (optional).
* - `fromToken?: TokenId` - The ID of the token being transferred from the source blockchain (optional).
* - `toToken?: TokenId` - The ID of the token expected on the destination blockchain (optional).
*
* @returns A promise that resolves with an array of `KnownRoute` objects, each representing a
* possible route for the token transfer.
*/
async getSupportedRoutes(
conditions?: GetSupportedRoutesFn_Conditions,
): Promise<KnownRoute[]> {
@@ -165,17 +178,68 @@ export class XLinkSDK {
stacksAddressFromStacksToken = stacksAddressFromStacksToken
stacksAddressToStacksToken = stacksAddressToStacksToken
/**
* This function provides detailed information about token transfers from the Stacks network to other supported
* blockchain networks, including Bitcoin and EVM-compatible chains. It verifies the validity of the transfer
* route and retrieves bridge information based on the destination chain and tokens.
* @param input - An object containing the input parameters required for retrieving bridge information:
* - `fromChain: ChainId` - The ID of the source blockchain (Stacks in this case).
* - `toChain: ChainId` - The ID of the destination blockchain (Bitcoin, EVM-compatible chains, etc.).
* - `fromToken: TokenId` - The token being transferred from the Stacks network.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `amount: SDKNumber` - The amount of tokens involved in the transfer.
*
* @returns A promise that resolves with an object containing detailed information about the token transfer, including:
* - `fromChain: KnownChainId.KnownChain` - The source blockchain.
* - `fromToken: KnownTokenId.KnownToken` - The token being transferred from the Stacks network.
* - `toChain: KnownChainId.KnownChain` - The destination blockchain.
* - `toToken: KnownTokenId.KnownToken` - The token expected on the destination chain.
* - `fromAmount: SDKNumber` - The amount of tokens being transferred.
* - `toAmount: SDKNumber` - The amount of tokens expected on the destination chain after the transfer.
* - `feeAmount: SDKNumber` - The fee amount deducted during the transfer.
* @throws UnsupportedBridgeRouteError - If the provided route between the source and destination
* chains or tokens is unsupported.
*/
bridgeInfoFromStacks(
input: BridgeInfoFromStacksInput,
): Promise<BridgeInfoFromStacksOutput> {
return bridgeInfoFromStacks(this.sdkContext, input)
}
/**
* This function facilitates the transfer of tokens from the Stacks network to other supported blockchain
* networks, including Bitcoin and EVM-compatible chains. It validates the route and calls the appropriate
* bridging function based on the destination chain and tokens involved.
* @param input - An object containing the input parameters required for the bridging operation:
* - `fromChain: ChainId` - The ID of the source blockchain.
* - `toChain: ChainId` - The ID of the destination blockchain (Bitcoin, EVM, etc.).
* - `fromToken: TokenId` - The token being transferred from the source chain.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `toAddress: string` - The recipient's address on the destination blockchain.
* - `amount: SDKNumber` - The amount of tokens to transfer.
* - `sendTransaction: // TODO.
*
* @returns A promise that resolves with the transaction ID (`txid`) of the bridging operation.
* @throws UnsupportedBridgeRouteError - If the provided route between the source and destination
* chains or tokens is unsupported.
*/
bridgeFromStacks(
input: BridgeFromStacksInput,
): Promise<BridgeFromStacksOutput> {
return bridgeFromStacks(this.sdkContext, input)
}
/**
* This function retrieves the contract address of a specific type of contract
* (e.g., a bridge endpoint) on a given EVM-compatible blockchain.
* @param chain - The ID of the EVM-compatible blockchain where the contract is deployed.
* @param contractType - The type of contract (e.g., `PublicEVMContractType.BridgeEndpoint`)
* for which the address is to be retrieved.
*
* @returns A promise that resolves with the contract address of the specified type, or
* `undefined` if the chain is not EVM-compatible or if the address cannot be retrieved.
*/
async getEVMContractAddress(
chain: ChainId,
contractType: PublicEVMContractType,
@@ -188,6 +252,15 @@ export class XLinkSDK {
}
return
}
/**
* This function retrieves the contract address of a specific token on a given EVM-compatible blockchain.
* @param chain - The ID of the EVM-compatible blockchain where the token contract is deployed.
* @param token - The specific token ID for which the contract address is to be retrieved.
*
* @returns A promise that resolves with the contract address of the token, or `undefined` if the
* chain is not EVM-compatible or if the contract address cannot be retrieved.
*/
async evmAddressFromEVMToken(
chain: ChainId,
token: KnownTokenId.EVMToken,
@@ -196,6 +269,15 @@ export class XLinkSDK {
const info = await getEVMTokenContractInfo(this.sdkContext, chain, token)
return info?.tokenContractAddress
}
/**
* This function maps a given contract address on an EVM-compatible blockchain to its corresponding known token ID.
* @param chain - The ID of the EVM-compatible blockchain where the contract is deployed.
* @param address - The contract address on the EVM-compatible blockchain.
*
* @returns A promise that resolves with the known token ID corresponding to the provided contract
* address, or `undefined` if the token ID cannot be found or if the chain is not EVM-compatible.
*/
async evmAddressToEVMToken(
chain: ChainId,
address: EVMAddress,
@@ -203,19 +285,92 @@ export class XLinkSDK {
if (!KnownChainId.isEVMChain(chain)) return
return getEVMToken(this.sdkContext, chain, address)
}
/**
* This function provides detailed information about token transfers from an EVM-compatible blockchain to other supported
* blockchain networks, including Stacks, Bitcoin, and other EVM-compatible chains. It verifies the validity of the transfer
* route and retrieves bridge information based on the destination chain and tokens.
* @param input - An object containing the input parameters required for retrieving bridge information:
* - `fromChain: ChainId` - The ID of the source blockchain (Stacks in this case).
* - `toChain: ChainId` - The ID of the destination blockchain (Bitcoin, EVM-compatible chains, etc.).
* - `fromToken: TokenId` - The token being transferred from the Stacks network.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `amount: SDKNumber` - The amount of tokens involved in the transfer.
*
* @returns A promise that resolves with an object containing detailed information about the token transfer, including:
* - `fromChain: KnownChainId.KnownChain` - The source blockchain.
* - `fromToken: KnownTokenId.KnownToken` - The token being transferred from the Stacks network.
* - `toChain: KnownChainId.KnownChain` - The destination blockchain.
* - `toToken: KnownTokenId.KnownToken` - The token expected on the destination chain.
* - `fromAmount: SDKNumber` - The amount of tokens being transferred.
* - `toAmount: SDKNumber` - The amount of tokens expected on the destination chain after the transfer.
* - `feeAmount: SDKNumber` - The fee amount deducted during the transfer.
* @throws UnsupportedBridgeRouteError - If the provided route between the source and destination
* chains or tokens is unsupported.
*/
bridgeInfoFromEVM(
input: BridgeInfoFromEVMInput,
): Promise<BridgeInfoFromEVMOutput> {
return bridgeInfoFromEVM(this.sdkContext, input)
}
/**
* This function facilitates the transfer of tokens from an EVM-compatible blockchain to other supported
* blockchain networks, including Stacks, Bitcoin, and other EVM-compatible chains. It validates the
* route and calls the appropriate bridging function based on the destination chain and tokens involved.
* @param input - An object containing the input parameters required for the bridging operation:
* - `fromChain: ChainId` - The ID of the source blockchain (an EVM-compatible chain in this case).
* - `toChain: ChainId` - The ID of the destination blockchain (Stacks, Bitcoin, or another EVM-compatible chain).
* - `fromToken: TokenId` - The token being transferred from the EVM-compatible blockchain.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `toAddress: string` - The recipient's address on the destination blockchain.
* - `toAddressScriptPubKey?: Uint8Array` - The script public key for the `toAddress`, required when the destination is a Bitcoin chain.
* - `amount: SDKNumber` - The amount of tokens to transfer.
* - `sendTransaction: // TODO.
*
* @returns A promise that resolves with the transaction hash (`txHash`) of the bridging operation.
* @throws UnsupportedBridgeRouteError - If the provided route between the source and destination
* chains or tokens is unsupported.
*/
bridgeFromEVM(input: BridgeFromEVMInput): Promise<BridgeFromEVMOutput> {
return bridgeFromEVM(this.sdkContext, input)
}
/**
* This function retrieves a list of time-locked assets for a given wallet address across multiple EVM-compatible
* blockchain networks. It queries smart contracts to find and return information about the assets that are
* currently locked in time-based agreements.
* @param input - An object containing the input parameters required for retrieving time-locked assets:
* - `walletAddress: EVMAddress` - The address of the wallet for which to retrieve the time-locked assets.
* - `chains: KnownChainId.EVMChain[]` - An array of EVM-compatible blockchains to query for locked assets.
*
* @returns A promise that resolves with an object containing a list of time-locked assets:
* - `assets: TimeLockedAsset[]` - An array of objects, each representing a time-locked asset, including:
* - `id: string` - The unique identifier of the time-locked agreement.
* - `chain: KnownChainId.EVMChain` - The blockchain where the asset is locked.
* - `token: KnownTokenId.EVMToken` - The token that is locked.
* - `amount: SDKNumber` - The amount of the token that is locked.
* - `releaseTime: Date` - The time when the asset is scheduled to be released.
*
* @throws UnsupportedChainError - If any of the provided EVM chains is unsupported or invalid.
*/
getTimeLockedAssetsFromEVM(
input: GetTimeLockedAssetsInput,
): Promise<GetTimeLockedAssetsOutput> {
return getTimeLockedAssetsFromEVM(this.sdkContext, input)
}
/**
* This function facilitates the claiming of time-locked assets on EVM-compatible chains. It uses smart
* contract functions to execute the release of locked assets based on predefined conditions.
* @param input - An object containing the input parameters required for claiming time-locked assets:
* - `chain: KnownChainId.EVMChain` - The ID of the EVM-compatible blockchain where the assets are locked.
* - `lockedAssetIds: string[]` - An array of IDs representing the locked assets to be claimed.
* - `sendTransaction: // TODO.
*
* @returns A promise that resolves with the transaction hash (`txHash`) of the claiming operation, or `undefined` if the operation fails.
* @throws UnsupportedChainError - If the provided EVM chain is unsupported or invalid.
*/
claimTimeLockedAssetsFromEVM(
input: ClaimTimeLockedAssetsInput,
): Promise<undefined | ClaimTimeLockedAssetsOutput> {
@@ -230,12 +385,76 @@ export class XLinkSDK {
if (!KnownChainId.isKnownChain(toChain)) return
return getBTCPegInAddress(fromChain, toChain)
}
/**
* This function provides detailed information about token transfers from the Bitcoin network to other supported
* blockchain networks, including Stacks and EVM-compatible chains. It verifies the validity of the transfer route
* and retrieves bridge information based on the destination chain.
* @param info - An object containing the input parameters required for retrieving bridge information:
* - `fromChain: ChainId` - The ID of the source blockchain.
* - `toChain: ChainId` - The ID of the destination blockchain (Stacks, EVM, etc.).
* - `amount: SDKNumber` - The amount of tokens involved in the transfer.
*
* @returns A promise that resolves with an object containing detailed information about the token transfer, including:
* - `fromChain: KnownChainId.KnownChain` - The source blockchain.
* - `fromToken: KnownTokenId.KnownToken` - The token being transferred from the Bitcoin network.
* - `toChain: KnownChainId.KnownChain` - The destination blockchain.
* - `toToken: KnownTokenId.KnownToken` - The token expected on the destination chain.
* - `fromAmount: SDKNumber` - The amount of tokens being transferred.
* - `toAmount: SDKNumber` - The amount of tokens expected on the destination chain after the transfer.
* - `feeAmount: SDKNumber` - The fee amount deducted during the transfer.
* @throws UnsupportedBridgeRouteError - If the provided route between the source and destination
* chains is unsupported.
*/
bridgeInfoFromBitcoin = bridgeInfoFromBitcoin
/**
* This function estimates the transaction fee and vSize for move or swap tokens from the Bitcoin network
* to other supported blockchain networks, including Stacks and EVM-compatible chains.
* @param input - An object containing the input parameters required for estimating the transaction:
* - `fromChain: ChainId` - The ID of the source blockchain (Bitcoin in this case).
* - `toChain: ChainId` - The ID of the destination blockchain (Stacks, EVM-compatible chains, etc.).
* - `fromToken: TokenId` - The token being transferred from the Bitcoin network.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `fromAddress: string` - The source address on the Bitcoin network.
* - `fromAddressScriptPubKey: Uint8Array` - The script public key of the source address.
* - `toAddress: string` - The destination address on the target blockchain.
* - `amount: SDKNumber` - The amount of tokens to be transferred.
* - `networkFeeRate: bigint` - The fee rate for the Bitcoin network.
* - `reselectSpendableUTXOs: // TODO.
*
* @returns A promise that resolves with an object containing the estimated transaction details:
* - `fee: SDKNumber` - The estimated transaction fee.
* - `estimatedVSize: SDKNumber` - The estimated vSize of the transaction.
* @throws UnsupportedBridgeRouteError - If the provided route between the source and destination
* chains or tokens is unsupported.
*/
estimateBridgeTransactionFromBitcoin(
input: EstimateBridgeTransactionFromBitcoinInput,
): Promise<EstimateBridgeTransactionFromBitcoinOutput> {
return estimateBridgeTransactionFromBitcoin(this.sdkContext, input)
}
/**
* This function facilitates the transfer of tokens from the Bitcoin network to other supported
* blockchain networks. It checks the validity of the route and then calls the appropriate
* bridging function based on the destination chain.
* @param input - An object containing the input parameters required for the bridging operation:
* - `fromChain: ChainId` - The ID of the source blockchain.
* - `toChain: ChainId` - The ID of the destination blockchain (Stacks, EVM, etc.).
* - `fromToken: TokenId` - The token being transferred from the Bitcoin network.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `fromAddress: string` - The source address on the Bitcoin network.
* - `fromAddressScriptPubKey: Uint8Array` - The script public key corresponding to the `fromAddress`.
* - `toAddress: string` - The recipient's address on the destination blockchain.
* - `amount: SDKNumber` - The amount of tokens to transfer.
* - `networkFeeRate: bigint` - The network fee rate to be used for the transaction.
* - `reselectSpendableUTXOs: ReselectSpendableUTXOsFn`.
* - `signPsbt: BridgeFromBitcoinInput_signPsbtFn`.
*
* @returns A promise that resolves with the transaction ID (`tx`) of the bridging operation.
* @throws UnsupportedBridgeRouteError - If the provided route between the source and destination
* chains or tokens is unsupported.
*/
bridgeFromBitcoin(
input: BridgeFromBitcoinInput,
): Promise<BridgeFromBitcoinOutput> {
@@ -243,6 +462,14 @@ export class XLinkSDK {
}
}
/**
* This function retrieves the contract address associated with a specific token on the Stacks blockchain.
* @param chain - The ID of the Stacks blockchain.
* @param token - The specific token ID for which the contract address is to be retrieved.
*
* @returns A promise that resolves with the contract address associated with the specified token,
* or `undefined` if the chain is not a Stacks chain or if the contract address cannot be retrieved.
*/
async function stacksAddressFromStacksToken(
chain: ChainId,
token: KnownTokenId.StacksToken,
@@ -255,6 +482,16 @@ async function stacksAddressFromStacksToken(
contractName: info.contractName,
}
}
/**
* This function maps a given Stacks contract address to its corresponding known token ID.
* @param chain - The ID of the Stacks blockchain.
* @param address - The contract address on the Stacks blockchain.
*
* @returns A promise that resolves with the known token ID corresponding to the provided
* contract address, or `undefined` if the chain is not a Stacks chain or if the token ID
* cannot be found.
*/
async function stacksAddressToStacksToken(
chain: ChainId,
address: StacksContractAddress,

5
src/utils/errors.ts
View File

@@ -1,5 +1,6 @@
import { ChainId, TokenId } from "../xlinkSdkUtils/types"
/** Extends the Error class and serves as the base for all custom errors within the SDK. */
export class XLinkSDKErrorBase extends Error {
constructor(...args: ConstructorParameters<typeof Error>) {
super(...args)
@@ -7,6 +8,7 @@ export class XLinkSDKErrorBase extends Error {
}
}
/** It is thrown when a method in the SDK receives invalid parameters. */
export class InvalidMethodParametersError extends XLinkSDKErrorBase {
constructor(
public methodPath: string[],
@@ -21,6 +23,7 @@ export class InvalidMethodParametersError extends XLinkSDKErrorBase {
}
}
/** It is thrown when an attempt is made to bridge tokens between unsupported chains in the SDK. */
export class UnsupportedBridgeRouteError extends XLinkSDKErrorBase {
constructor(
public fromChain: ChainId,
@@ -35,12 +38,14 @@ export class UnsupportedBridgeRouteError extends XLinkSDKErrorBase {
}
}
/** It is thrown when a method in the SDK receives an unknown chain. */
export class UnsupportedChainError extends XLinkSDKErrorBase {
constructor(public chain: ChainId) {
super(`Unsupported chain: ${chain}`)
this.name = "UnsupportedChainError"
}
}
/** It is thrown when a smart contract is assigned an unknown or unsupported chain ID. */
export class UnsupportedContractAssignedChainIdError extends XLinkSDKErrorBase {
constructor(public chainId: bigint) {
super(`Unsupported smart contract assigned chain id: ${chainId}`)

76
src/utils/types/knownIds.ts
View File

@@ -4,49 +4,77 @@ import { checkNever } from "../typeHelpers"
const chainId = <const T extends string>(value: T): ChainId<T> => value as any
const tokenId = <const T extends string>(value: T): TokenId<T> => value as any
/**
* The `KnownTokenId` namespace provides types of tokens supported by the SDK,
* including Bitcoin, EVM-compatible tokens, and Stacks tokens.
*/
export namespace KnownTokenId {
/** Represents a known token supported by the SDK. */
export type KnownToken = BitcoinToken | EVMToken | StacksToken
export function isKnownToken(value: TokenId): value is KnownToken {
return isBitcoinToken(value) || isEVMToken(value) || isStacksToken(value)
}
/** A namespace that contains constants and types for Bitcoin tokens. */
export namespace Bitcoin {
/** Represents the Bitcoin token ID (BTC). */
export const BTC = tokenId("btc-btc")
}
/** This type includes all known Bitcoin tokens. */
export type BitcoinToken = (typeof _allKnownBitcoinTokens)[number]
export function isBitcoinToken(value: TokenId): value is BitcoinToken {
return _allKnownBitcoinTokens.includes(value as any)
}
/** A namespace that contains constants and types for EVM-compatible tokens. */
export namespace EVM {
/** Represents the USDT token ID on EVM-compatible blockchains. */
export const USDT = tokenId("evm-usdt")
/** Represents the LUNR token ID on EVM-compatible blockchains. */
export const LUNR = tokenId("evm-lunr")
/** Represents the WBTC token ID on EVM-compatible blockchains. */
export const WBTC = tokenId("evm-wbtc")
/** Represents the BTCB token ID on EVM-compatible blockchains. */
export const BTCB = tokenId("evm-btcb")
// wrapped tokens
/** Represents the aBTC token ID on EVM-compatible blockchains. */
export const aBTC = tokenId("evm-abtc")
/** Represents the sUSDT token ID on EVM-compatible blockchains. */
export const sUSDT = tokenId("evm-susdt")
/** Represents the ALEX token ID on EVM-compatible blockchains. */
export const ALEX = tokenId("evm-alex")
/** Represents the SKO token ID on EVM-compatible blockchains. */
export const SKO = tokenId("evm-sko")
/** Represents the vLiSTX token ID on EVM-compatible blockchains. */
export const vLiSTX = tokenId("evm-vlistx")
/** Represents the vLiALEX token ID on EVM-compatible blockchains. */
export const vLiALEX = tokenId("evm-vlialex")
}
/** This type includes all known tokens on EVM-compatible blockchains. */
export type EVMToken = (typeof _allKnownEVMTokens)[number]
export function isEVMToken(value: TokenId): value is EVMToken {
return _allKnownEVMTokens.includes(value as any)
}
/** A namespace that contains constants and types for Stacks tokens. */
export namespace Stacks {
/** Represents the sUSDT token ID on the Stacks blockchain. */
export const sUSDT = tokenId("stx-susdt")
/** Represents the sLUNR token ID on the Stacks blockchain. */
export const sLUNR = tokenId("stx-slunr")
/** Represents the aBTC token ID on the Stacks blockchain. */
export const aBTC = tokenId("stx-abtc")
/** Represents the ALEX token ID on the Stacks blockchain. */
export const ALEX = tokenId("stx-alex")
/** Represents the sSKO token ID on the Stacks blockchain. */
export const sSKO = tokenId("stx-ssko")
/** Represents the vLiSTX token ID on the Stacks blockchain. */
export const vLiSTX = tokenId("stx-vlistx")
/** Represents the vLiALEX token ID on the Stacks blockchain. */
export const vLiALEX = tokenId("stx-vlialex")
}
/** This type includes all known tokens on the Stacks blockchain. */
export type StacksToken = (typeof _allKnownStacksTokens)[number]
export function isStacksToken(value: TokenId): value is StacksToken {
return _allKnownStacksTokens.includes(value as any)
@@ -56,90 +84,126 @@ export const _allKnownBitcoinTokens = Object.values(KnownTokenId.Bitcoin)
export const _allKnownEVMTokens = Object.values(KnownTokenId.EVM)
export const _allKnownStacksTokens = Object.values(KnownTokenId.Stacks)
/**
* The `KnownChainId` namespace provides types of blockchain networks
* supported by the SDK, including Bitcoin, EVM-compatible chains, and Stacks.
*/
export namespace KnownChainId {
/** Represents a known blockchain network supported by the SDK. */
export type KnownChain = BitcoinChain | EVMChain | StacksChain
export function isKnownChain(value: ChainId): value is KnownChain {
return isBitcoinChain(value) || isEVMChain(value) || isStacksChain(value)
}
/** A namespace that contains constants and types for Bitcoin networks. */
export namespace Bitcoin {
/** Represents the Bitcoin mainnet chain ID. */
export const Mainnet = chainId("bitcoin-mainnet")
/** Represents the Bitcoin testnet chain ID. */
export const Testnet = chainId("bitcoin-testnet")
}
/** Represents a Bitcoin blockchain network. */
export type BitcoinChain = (typeof _allKnownBitcoinChains)[number]
export function isBitcoinChain(value: ChainId): value is BitcoinChain {
return _allKnownBitcoinChains.includes(value as any)
}
/** A namespace that contains constants and types for EVM-compatible networks. */
export namespace EVM {
// Mainnet
/** Represents the Ethereum mainnet chain ID. */
export const Ethereum = chainId("evm-ethereum")
/** Represents the Ethereum testnet chain ID. */
export const Sepolia = chainId("evm-sepolia")
// BNB Smart Chain
/** Represents the BNB Smart Chain mainnet chain ID. */
export const BSC = chainId("evm-bsc")
/** Represents the BNB Smart Chain testnet chain ID. */
export const BSCTestnet = chainId("evm-bsctestnet")
// CoreDAO
/** Represents the CoreDAO mainnet chain ID. */
export const CoreDAO = chainId("evm-coredao")
/** Represents the CoreDAO testnet chain ID. */
export const CoreDAOTestnet = chainId("evm-coredao-testnet")
// B2 Bsquared
/** Represents the Bsquared mainnet chain ID. */
export const Bsquared = chainId("evm-bsquared")
/** Represents the Bsquared testnet chain ID. */
// export const BsquaredTestnet = chainId("evm-bsquared-testnet")
// BOB
/** Represents the BOB mainnet chain ID. */
export const BOB = chainId("evm-bob")
/** Represents the BOB testnet chain ID. */
// export const BOBTestnet = chainId("evm-bob-testnet")
// Bitlayer
/** Represents the Bitlayer mainnet chain ID. */
export const Bitlayer = chainId("evm-bitlayer")
/** Represents the Bitlayer testnet chain ID. */
// export const BitlayerTestnet = chainId("evm-bitlayer-testnet")
// Lorenzo
/** Represents the Lorenzo mainnet chain ID. */
export const Lorenzo = chainId("evm-lorenzo")
/** Represents the Lorenzo testnet chain ID. */
// export const LorenzoTestnet = chainId("evm-lorenzo-testnet")
// Merlin
/** Represents the Merlin mainnet chain ID. */
export const Merlin = chainId("evm-merlin")
/** Represents the Merlin testnet chain ID. */
// export const MerlinTestnet = chainId("evm-merlin-testnet")
// AILayer
/** Represents the AILayer mainnet chain ID. */
export const AILayer = chainId("evm-ailayer")
/** Represents the AILayer testnet chain ID. */
// export const AILayerTestnet = chainId("evm-ailayer-testnet")
// Mode
/** Represents the Mode mainnet chain ID. */
export const Mode = chainId("evm-mode")
/** Represents the Mode testnet chain ID. */
// export const ModeTestnet = chainId("evm-mode-testnet")
// X Layer
/** Represents the XLayer mainnet chain ID. */
export const XLayer = chainId("evm-xlayer")
/** Represents the XLayer testnet chain ID. */
// export const XLayerTestnet = chainId("evm-xlayer-testnet")
// Aribitrum
// Arbitrum
/** Represents the Arbitrum mainnet chain ID. */
export const Arbitrum = chainId("evm-arbitrum")
// export const ArbitrumTestnet = chainId("evm-arbitrum-testnet")
}
/** Represents a mainnet EVM-compatible blockchain network. */
export type EVMMainnetChain = (typeof _allKnownEVMMainnetChains)[number]
export function isEVMMainnetChain(value: ChainId): value is EVMMainnetChain {
return _allKnownEVMMainnetChains.includes(value as any)
}
/** Represents a testnet EVM-compatible blockchain network. */
export type EVMTestnetChain = (typeof _allKnownEVMTestnetChains)[number]
export function isEVMTestnetChain(value: ChainId): value is EVMTestnetChain {
return _allKnownEVMTestnetChains.includes(value as any)
}
/** Represents an EVM-compatible blockchain network. */
export type EVMChain = (typeof _allKnownEVMChains)[number]
export function isEVMChain(value: ChainId): value is EVMChain {
return _allKnownEVMChains.includes(value as any)
}
/** A namespace that contains constants and types for Stacks blockchain networks. */
export namespace Stacks {
/** Represents the Stacks mainnet chain ID. */
export const Mainnet = chainId("stacks-mainnet")
/** Represents the Stacks testnet chain ID. */
export const Testnet = chainId("stacks-testnet")
}
/** Represents a Stacks blockchain network. */
export type StacksChain = (typeof _allKnownStacksChains)[number]
export function isStacksChain(value: ChainId): value is StacksChain {
return _allKnownStacksChains.includes(value as any)

17
src/xlinkSdkUtils/types.ts
View File

@@ -7,7 +7,13 @@ type SDKBrandedLiteral<
T extends string | number,
> = `${T} (XLinkSDK ${Type})`
/**
* Represents a unique identifier for a blockchain network.
*/
export type ChainId<T extends string = string> = SDKBrandedLiteral<"ChainId", T>
/**
* Represents a unique identifier for a cryptocurrency token.
*/
export type TokenId<T extends string = string> = SDKBrandedLiteral<"TokenId", T>
export type SDKNumber = SDKBrandedLiteral<"number", string>
@@ -57,7 +63,18 @@ export interface StacksContractAddress {
contractName: string
}
/**
* Represents the type of public EVM contracts that are accessible through the SDK.
* The `PublicEVMContractType` is tied to the specific `BridgeEndpoint` contract type defined
* in the `EVMEndpointContract` namespace.
*/
export type PublicEVMContractType = typeof PublicEVMContractType.BridgeEndpoint
/**
* A namespace that defines the public contract types available in the SDK for EVM-compatible blockchains.
* This namespace currently includes only the `BridgeEndpoint` contract type, which corresponds to
* the main contract used for bridging assets across EVM-compatible blockchains.
*/
export namespace PublicEVMContractType {
/** Represents the bridge endpoint contract type in an EVM-compatible blockchain. */
export const BridgeEndpoint = EVMEndpointContract.BridgeEndpoint
}