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

Squashed commit of the following:

Browse Source 
commit f8b6eee30c
Author: ignacio.pena@coinfabrik.com <ignacio.pena@coinfabrik.com>
Date:   Wed Apr 16 16:04:42 2025 -0300

    update XLinkSDK typedoc

commit 4b1ab54cd9
Author: ignacio.pena@coinfabrik.com <ignacio.pena@coinfabrik.com>
Date:   Tue Apr 15 15:36:11 2025 -0300

    docs: @sofinico review

commit 8aae033117
Author: ignacio.pena@coinfabrik.com <ignacio.pena@coinfabrik.com>
Date:   Thu Apr 3 20:02:29 2025 -0300

    minor updates

commit 5d8ea690c6
Author: ignacio.pena@coinfabrik.com <ignacio.pena@coinfabrik.com>
Date:   Tue Apr 1 17:26:09 2025 -0300

    docs: update more functions

commit 43fd87c1ed
Author: ignacio.pena@coinfabrik.com <ignacio.pena@coinfabrik.com>
Date:   Tue Apr 1 15:25:39 2025 -0300

    docs: XlinkSDK update WIP

commit 2606781c5a
Author: sofinico <nicolettisofia1@gmail.com>
Date:   Fri Mar 21 10:19:30 2025 +0100

    chore: add dev instructions for docs

commit 98ee4741d5
Author: sofinico <nicolettisofia1@gmail.com>
Date:   Wed Mar 26 18:10:28 2025 +0100

    docs: update main readme

commit 452b1cad7f
Author: sofinico <nicolettisofia1@gmail.com>
Date:   Fri Mar 21 10:19:47 2025 +0100

    chore: apply format to main readme
This commit is contained in:
c4605
2025-04-21 10:50:58 +02:00
parent 7d46cce32c
commit 0699856953
5 changed files with 565 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

375
README.md
View File

@@ -1,204 +1,277 @@
# XLinkSDK
XLink is designed to facilitate the transfer of digital tokens between different blockchains. Its primary purpose is to act as a bridge, enabling users to move and swap their tokens seamlessly across various blockchain ecosystems.
## System Type and Purpose
🐙 **XLINK isn't just a bridge—it's the liquidity layer for Bitcoin and the essential connector for Bitcoin DeFi** 🐙
XLinkSDK allows users to interact with XLink. It can be used in backend environments as well as in browsers and mobile applications. The SDK enables bidirectional transfer of coins/tokens between Bitcoin, Stacks, and various EVM including Bitcoin Layer 2s networks. Also, provides information on transfer fees, route planning, transaction size calculations and implements security features for safe transfers.
XLinkSDK enables seamless asset transfers between Bitcoin, Stacks, and EVM-compatible blockchains. It supports cross-chain swaps, Runes & BRC20 metaprotocols, and DEX aggregator integrations.
The SDK allows users to interact with XLINK smart contracts from backend environments, browsers, and mobile apps. It securely handles cross-chain transfers, fee estimation, route planning, and transaction size calculations by using XLINK's on-chain and off-chain infrastructure.
## Installation
### Prerequisites
Ensure you have the following installed:
- [Node.js](https://nodejs.org/en)
- [pnpm](https://pnpm.io/)
### Installation
To install the XLink SDK, use the following command:
### Install
```bash
pnpm install @xlink-network/xlink-sdk
```
## XLink SDK API
### Supported Blockchains and Tokens
## Usage
#### KnownChainId
The `KnownChainId` namespace encapsulates types and utility functions to validate blockchain networks supported by the SDK. It ensures that only recognized chain IDs across Bitcoin, EVM-compatible chains, and Stacks are used.
| Namespace |Mainnet |Testnet |
| ----------|-----------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------- |
| Bitcoin |`Mainnet` |`Testnet` |
| Stacks |`Mainnet` |`Testnet` |
| EVM |`Ethereum`, `BSC`, `CoreDAO`, `Bsquared`, `BOB`, `Bitlayer`, `Lorenzo`, `Merlin`, `AILayer`, `Mode`, `XLayer`, `Arbitrum`, `Aurora`, `Manta`, `Linea`|`Sepolia`, `BSCTestnet`, `CoreDAOTestnet`, `BisonTestnet`, `BitboyTestnet`, `BeraTestnet` |
#### KnownTokenId
The `KnownTokenId` namespace manages the token IDs of supported cryptocurrencies across different blockchain networks within the SDK. It ensures that only recognized tokens specific to Bitcoin, EVM-compatible chains, and Stacks are used.
##### Namespaces
| Namespace |Tokens |
| ----------|------------------------------------------------------------------------------------------------------------------- |
| Bitcoin |`BTC` |
| Stacks |`sUSDT`, `sLUNR`, `aBTC`, `ALEX`, `sSKO`, `vLiSTX`, `vLiALEX`, `uBTC`, `DB20`, `DOG` |
| EVM |`USDT`, `LUNR`, `WBTC`, `BTCB`, `aBTC`, `sUSDT`, `ALEX`, `SKO`, `vLiSTX`, `vLiALEX`, `uBTC`, `wuBTC`, `DB20`, `DOG` |
**Future Support**: Support for Runes and BR20 tokens on the Bitcoin network is planned for a future update.
### XLink SDK
The [`XLinkSDK`](/modules/XLinkSDK) object contains the most important functions of this library, all grouped together. To create it:
The [`XLinkSDK`](./src/XLinkSDK.ts) class provides the core functions of the library. To create an instance:
```typescript
const theSdk = new XLinkSDK();
import { XLinkSDK } from "@xlink-network/xlink-sdk"
const sdk = new XLinkSDK()
```
For detailed API documentation, including a full list of available methods and their usage, please refer to:
For the full API reference, including a full list of available methods and their usage, visit the [SDK Documentation](https://releases-latest.xlink-sdk.pages.dev).
[SDK API Documentation](https://releases-latest.xlink-sdk.pages.dev)
### Supported Blockchains and Tokens
#### [`KnownChainId`](https://releases-latest.xlink-sdk.pages.dev/modules/index.KnownChainId)
Defines types and utility functions for supported networks, ensuring only valid chain IDs are used within the SDK.
| Namespace | Mainnet | Testnet |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Bitcoin | `Mainnet` | `Testnet` |
| Runes | `Mainnet` | `Testnet` |
| BRC20 | `Mainnet` | `Testnet` |
| Stacks | `Mainnet` | `Testnet` |
| EVM | `Ethereum`, `BSC`, `CoreDAO`, `Bsquared`, `BOB`, `Bitlayer`, `Lorenzo`, `Merlin`, `AILayer`, `Mode`, `XLayer`, `Arbitrum`, `Aurora`, `Manta`, `Linea`, `Base` | `Sepolia`, `BSCTestnet`, `CoreDAOTestnet`, `BlifeTestnet`, `BitboyTestnet`, `BeraTestnet` |
#### [`KnownTokenId`](https://releases-latest.xlink-sdk.pages.dev/modules/index.KnownTokenId)
Defines types, utility functions, and supported tokens within the SDK.
| Namespace | Tokens |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bitcoin | `BTC` |
| Runes | _To be confirmed_ |
| BRC20 | _To be confirmed_ |
| Stacks | `sUSDT`, `sLUNR`, `aBTC`, `ALEX`, `sSKO`, `vLiSTX`, `vLiALEX`, `vLiaBTC`,`uBTC`, `DB20`, `DOG`, `STX`, `TRUMP` |
| EVM | `USDT`, `sUSDT`, `USDC`, `aBTC`, `WTCB`, `BTCB`, `cbBTC`, `uBTC`, `wuBTC`, `STX`, `vLiSTX`, `ALEX`, `vLiALEX`, `LUNR`, `SKO`, `DB20`, `DOG`, `TRUMP` |
### Use Cases
Create an instance of the SDK with default options
Create an instance of the SDK with default options:
```typescript
import { XLinkSDK } from '@xlink-network/xlink-sdk';
const xlinkSdk = new XLinkSDK();
import { XLinkSDK } from "@xlink-network/xlink-sdk"
const xlinkSdk = new XLinkSDK()
```
1. Bridge from Stacks
#### Bridge from Stacks
Use case showcasing a transfer of 100 `sUSDT` from Stacks to `USDT` on Ethereum using XLinkSDK.
```typescript
import { serializeCVBytes } from '@stacks/transactions';
import {
BridgeInfoFromStacksInput,
import {
BridgeFromStacksInput,
KnownChainId,
KnownTokenId,
KnownTokenId,
toSDKNumberOrUndefined,
} from '@xlink-network/xlink-sdk';
import { serializeCVBytes, makeContractCall, broadcastTransaction } from '@stacks/transactions';
// Get bridge info
const bridgeInfo = await xlinkSdk.bridgeInfoFromStacks({
fromChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.Stacks.sUSDT,
toChain: KnownChainId.EVM.Ethereum,
toToken: KnownTokenId.EVM.USDT,
amount: toSDKNumberOrUndefined(100),
// Retrieve bridge information
const bridgeInfo = await xlinkSdk.bridgeInfoFromStacks({
fromChain: KnownChainId.Stacks.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.Stacks.sUSDT,
toToken: KnownTokenId.EVM.USDT,
amount: toSDKNumberOrUndefined(100),
});
console.log("Bridge Info:", bridgeInfo);
// Define bridge operation input
const bridgeFromStacksInput: BridgeFromStacksInput = {
fromChain: KnownChainId.Stacks.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.Stacks.sUSDT,
toToken: KnownTokenId.EVM.USDT,
fromAddress: /* Sender Stacks principal */,
toAddress: /* Receiver EVM address */,
amount: toSDKNumberOrUndefined(100),
sendTransaction: async (tx: ContractCallOptions) => {
/**
* Implementation for sending transaction on Stacks mainnet.
* Refer to: https://github.com/hirosystems/stacks.js/tree/main/packages/transactions#smart-contract-function-call
*/
const transaction = await makeContractCall({
contractAddress: tx.contractAddress,
contractName: tx.contractName,
functionName: tx.functionName,
functionArgs: tx.functionArgs,
postConditions: /* Add post conditions if necessary */,
validateWithAbi: true,
senderKey: /* Sender private key */,
network: "mainnet",
});
const broadcastResponse = await broadcastTransaction(transaction, "mainnet");
return { txid: broadcastResponse.txid };
},
};
// Example of how a `sendTransaction` argument would look like
const contractCallOptionsExample: ContractCallOptions = {
contractAddress: "SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK",
contractName: "cross-peg-out-endpoint-v2-01",
functionName: "transfer-to-unwrap",
functionArgs: [].map(arg => serializeCVBytes(arg)), // Array elements must be Clarity values
};
// Perform the bridge operation
const result = await xlinkSdk.bridgeFromStacks({
fromChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.Stacks.sUSDT,
toChain: KnownChainId.EVM.Ethereum,
toToken: KnownTokenId.EVM.USDT,
fromAddress: "0x...",
toAddress: "0x...",
amount: toSDKNumberOrUndefined(10),
sendTransaction: async tx => {
// 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.map(a => serializeCVBytes(a)),
network,
senderKey: "sender address private key here",
postConditions: /* add post conditions */,
anchorMode: /* add anchor mode */,
});
const broadcastResponse = await broadcastTransaction(transaction, network);
return {txid: broadcastResponse.txid};
},
});
const result = await xlinkSdk.bridgeFromStacks(bridgeFromStacksInput);
console.log("Transaction ID:", result.txid);
```
2. Bridge from EVM
#### Bridge from EVM
Use case showcasing a transfer of 100 `USDT` from Ethereum to `UsSDT` on Stacks using XLinkSDK.
```typescript
import {
BridgeInfoFromEVMInput,
BridgeFromEVMInput,
KnownChainId,
KnownTokenId,
toSDKNumberOrUndefined,
} from '@xlink-network/xlink-sdk';
// Get bridge info
import {
BridgeFromEVMInput,
KnownChainId,
KnownTokenId,
toSDKNumberOrUndefined,
} from "@xlink-network/xlink-sdk"
import { ethers } from "ethers";
// Retrieve bridge information
const bridgeInfo = await xlinkSdk.bridgeInfoFromEVM({
fromChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.EVM.USDT,
toChain: KnownChainId.Stacks.Mainnet,
toToken: KnownTokenId.Stacks.sUSDT,
amount: toSDKNumberOrUndefined(100),
fromChain: KnownChainId.EVM.Ethereum,
toChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.EVM.USDT,
toToken: KnownTokenId.Stacks.sUSDT,
amount: toSDKNumberOrUndefined(100),
});
console.log("Bridge Info:", bridgeInfo);
// Perform the bridge operation
const result = await xlinkSdk.bridgeFromEVM({
fromChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.EVM.USDT,
fromAddress: "0x95222290DD7278Aa3D......................",
toChain: KnownChainId.Stacks.Mainnet,
toToken: KnownTokenId.Stacks.sUSDT,
toAddress: "0x95222290DD7278Aa3D......................",
amount: toSDKNumberOrUndefined(10),
sendTransaction: async function (tx: {
from: `0x${string}`;
to: `0x${string}`;
data: Uint8Array;
recommendedGasLimit: `${string} (XLinkSDK number)`;
}): Promise<{ txHash: string; }> {
// Implementation for sending transaction from EVM chain
return { txHash: "....." }
console.log("Bridge Info:", bridgeInfo);
// Example signer setup using ethers.js
const provider = new ethers.providers.JsonRpcProvider("https://mainnet.someprovider.io/YOUR_PROJECT_ID");
const signer = new ethers.Wallet("SENDER_PRIVATE_KEY", provider);
const bridgeFromEVMInput: BridgeFromEVMInput = {
fromChain: KnownChainId.EVM.Ethereum,
toChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.EVM.USDT,
toToken: KnownTokenId.Stacks.sUSDT,
fromAddress: /* Sender EVM address */,
toAddress: /* Receiver Stacks principal */,
amount: toSDKNumberOrUndefined(100),
sendTransaction: async (tx:
{
from: EVMAddress /* Sender EVM address */
to: EVMAddress /* Bridge Endpoint address */
data: Uint8Array /* Transaction data */
recommendedGasLimit: SDKNumber /* Recommended gas limit */
value?: SDKNumber /* Transaction value */
}
});
): Promise<{ txHash: string }> => {
/**
* Implementation for sending transaction on Ethereum mainnet
* See https://docs.ethers.org/v5/api/contract/contract/ for reference
*/
const txRequest = {
from: tx.from,
to: tx.to,
data: ethers.utils.hexlify(tx.data),
gasLimit: ethers.BigNumber.from(tx.recommendedGasLimit.split(" ")[0]), // Convert string to BigNumber
};
const sentTx = await signer.sendTransaction(txRequest);
const receipt = await sentTx.wait();
return { txHash: receipt.transactionHash };
},
};
// Perform the bridge operation
const result = await xlinkSdk.bridgeFromEVM(bridgeFromEVMInput);
console.log("Transaction ID:", result.txHash);
```
3. Bridge from Bitcoin
```typescript
import {
BridgeInfoFromBitcoinInput,
BridgeFromBitcoinInput,
KnownChainId,
KnownTokenId,
toSDKNumberOrUndefined,
} from '@xlink-network/xlink-sdk';
#### Bridge from Bitcoin
// Get bridge info
Use case showcasing a transfer of 1 `BTC` from Bitcoin to `WBTC` on Ethereum using XLinkSDK.
```typescript
import {
BridgeFromBitcoinInput,
KnownChainId,
KnownTokenId,
toSDKNumberOrUndefined,
} from "@xlink-network/xlink-sdk"
/* Use your preferred Bitcoin libs here */
import { Psbt, networks, Transaction, script } from "bitcoinjs-lib";
import { ECPairFactory } from "ecpair";
import * as tinysecp from "tiny-secp256k1";
import axios from "axios";
// Retrieve bridge information
const bridgeInfo = await xlinkSdk.bridgeInfoFromBitcoin({
fromChain: KnownChainId.Bitcoin.Mainnet,
fromToken: KnownTokenId.Bitcoin.BTC,
toChain: KnownChainId.EVM.Ethereum,
toToken: KnownTokenId.EVM.BTCB,
amount: toSDKNumberOrUndefined(1),
fromChain: KnownChainId.Bitcoin.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.Bitcoin.BTC,
toToken: KnownTokenId.EVM.WBTC,
amount: toSDKNumberOrUndefined(1),
});
console.log("Bridge Info:", bridgeInfo);
console.log("Bridge Info:", bridgeInfo)
const bridgeFromBitcoinInput: BridgeFromBitcoinInput = {
fromChain: KnownChainId.Bitcoin.Mainnet,
fromToken: KnownTokenId.Bitcoin.BTC,
toChain: KnownChainId.EVM.Ethereum,
toToken: KnownTokenId.EVM.WBTC,
fromAddress: /* Sender Bitcoin address */,
toAddress: /* Receiver EVM address */,
amount: toSDKNumberOrUndefined(1),
networkFeeRate: 10n,
reselectSpendableUTXOs: async (
satsToSend: bigint,
pinnedUTXOs: UTXOSpendable[],
lastTimeSelectedUTXOs: UTXOSpendable[]
): Promise<UTXOSpendable[]> => {
/**
* Implementation for selecting spendable UTXOs from the wallet
* This should fetch available UTXOs from a Bitcoin node or explorer API
*/
return [];
},
signPsbt: async (tx: { psbt: Uint8Array; signInputs: number[] }): Promise<{ psbt: Uint8Array }> => {
/**
* Implementation for signing a Bitcoin PSBT (Partially Signed Bitcoin Transaction)
* See https://github.com/bitcoinjs/bitcoinjs-lib for reference
*/
let psbt = Psbt.fromBuffer(tx.psbt);
tx.signInputs.forEach((index) => {
psbt.signInput(index, keyPair);
});
psbt.finalizeAllInputs();
return { psbt: psbt.toBuffer() };
},
sendTransaction: async (tx: { hex: string }): Promise<{ txid: string }> => {
/**
* Implementation for broadcasting a Bitcoin transaction with Axios
* Using a Bitcoin node or explorer API (e.g., Blockstream API)
*/
const response = await axios.post("https://some-mempool/api/tx", tx.hex, {
headers: { "Content-Type": "text/plain" },
});
return { txid: response.data };
},
};
// Perform the bridge operation
const result = await xlinkSdk.bridgeFromBitcoin({
fromChain: KnownChainId.Bitcoin.Mainnet,
fromToken: KnownTokenId.Bitcoin.BTC,
fromAddress: "bitcoin address",
toChain: KnownChainId.EVM.Ethereum,
toToken: KnownTokenId.EVM.WBTC,
toAddress: "0x...",
fromAddressScriptPubKey: new Uint8Array([10, 20, 30, 40,]),
amount: toSDKNumberOrUndefined(1),
networkFeeRate: 10n,
reselectSpendableUTXOs(satsToSend: bigint, pinnedUTXOs: UTXOSpendable[], lastTimeSelectedUTXOs: UTXOSpendable[]): Promise<UTXOSpendable[]> {
return Promise.resolve([]);
},
signPsbt: function (tx: { psbt: Uint8Array; signInputs: number[]; }): Promise<{ psbt: Uint8Array }> {
throw new Error("Function not implemented.");
},
sendTransaction: function (tx: { hex: string }): Promise<{ txid: string; }> {
throw new Error("Function not implemented.");
}
});
console.log("Transaction ID:", result.tx);
```
const result = await xlinkSdk.bridgeFromBitcoin(bridgeFromBitcoinInput);
console.log("Transaction ID:", result.txid);
```

18
docs/dev-instructions.md Normal file
View File

@@ -0,0 +1,18 @@
# Test Instructions
## Visualize Typedoc Documentation
In the root directory, run:
```bash
pnpm run docs:watch
```
In a new terminal window, run:
```bash
cd generated/docs
python -m http.server 8080
```
Open `http://localhost:8080` in your browser to view the documentation.

6
package.json
View File

@@ -4,10 +4,12 @@
"description": "Brotocol js SDK",
"packageManager": "pnpm@9.9.0",
"keywords": [
"brotocol",
"bitcoin",
"brc-20",
"runes",
"ethereum",
"stacks",
"brotocol"
"stacks"
],
"repository": "github:brotocol-xyz/bro-sdk",
"author": "c4605",

327
src/XLinkSDK.ts
View File

@@ -318,8 +318,8 @@ export class XLinkSDK {
* cannot be determined at this point, so enabling this option may return routes that cannot
* actually be completed (optional).
*
* @returns A promise that resolves with an array of `KnownRoute` objects, each representing a
* possible route for the token transfer.
* @returns A promise that resolves with an array of `KnownRoute` objects, each representing a supported
* token transfer route between blockchains.
*/
async getPossibleRoutes(
conditions?: GetSupportedRoutesFn_Conditions,
@@ -379,8 +379,20 @@ export class XLinkSDK {
}
/**
* different from `getPossibleRoutes`, this function is designed to further
* determine if the route is supported by the SDK
* Determines whether a given route (from one blockchain/token to another) is supported by the XLink SDK.
* This function evaluates cross-chain compatibility for all supported networks (EVM, Stacks, Bitcoin, BRC20, Runes)
* by delegating to specialized validators per source chain type. It checks that the route is logically valid,
* not deprecated, and exists in the bridge configuration which is dynamically fetched.
*
* @param route - The route to validate, containing:
* - `fromChain`: the origin blockchain (`ChainId`)
* - `fromToken`: the token to bridge from (`TokenId`)
* - `toChain`: the destination blockchain (`ChainId`)
* - `toToken`: the token to receive on the destination (`TokenId`)
* - `swapRoute?` – (optional) An optional swap configuration that may be present in the route object.
*
* @returns A promise that resolves to `true` if the route is supported for bridging,
* or `false` if the route is invalid, unsupported, or incomplete.
*/
async isSupportedRoute(
route: DefinedRoute & { swapRoute?: SwapRoute },
@@ -396,12 +408,34 @@ export class XLinkSDK {
return checkingResult.some(r => r)
}
/**
* This function retrieves the Stacks contract address (principal) associated with a known Stacks token ID used by the SDK.
*
* @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.
*/
stacksAddressFromStacksToken(
chain: ChainId,
token: KnownTokenId.StacksToken,
): Promise<undefined | StacksContractAddress> {
return stacksAddressFromStacksToken(this.sdkContext, chain, token)
}
/**
* This function maps a given Stacks contract address to its corresponding known token ID.
* Always use this function to retrieve the current `KnownTokenId.StacksToken` for a contract at runtime.
*
* Token IDs are dynamically resolved and may change as supported tokens are updated — do not hardcode or cache these values.
*
* @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 is not
* supported by XLINK.
*/
stacksAddressToStacksToken(
chain: ChainId,
address: StacksContractAddress,
@@ -413,6 +447,7 @@ export class XLinkSDK {
* 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.).
@@ -428,6 +463,7 @@ export class XLinkSDK {
* - `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.
*/
@@ -441,6 +477,7 @@ export class XLinkSDK {
* 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.).
@@ -452,6 +489,7 @@ export class XLinkSDK {
* - `sendTransaction` - // Implementation for sending transaction from Stacks mainnet.
*
* @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.
*/
@@ -464,6 +502,7 @@ export class XLinkSDK {
/**
* 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.
@@ -484,12 +523,29 @@ export class XLinkSDK {
return
}
/**
* This function retrieves the numeric EVM chain ID (`chainId`) associated with a known EVM-compatible chain in the SDK.
* This chain ID serves as the identifier for chains within XLINK smart contracts.
*
* @param chain - A known EVM-compatible chain identifier (`KnownChainId.EVMChain`).
*
* @returns A promise that resolves with the numeric `chainId` (as a `bigint`) corresponding to the specified
* EVM-compatible chain. Returns `undefined` if the chain ID is not available or not supported.
*/
async evmChainIdFromKnownChainId(
chain: KnownChainId.EVMChain,
): Promise<undefined | bigint> {
return evmChainIdFromKnownChainId(chain)
}
/**
* This function maps a numeric chain ID (`chainId`) to its corresponding known chain identifier (`KnownChainId.EVMChain`) used in the SDK.
*
* @param chainId - The numeric chain ID (as a `bigint`) of an EVM-compatible blockchain.
*
* @returns A promise that resolves with the corresponding known EVM chain ID (`KnownChainId.EVMChain`),
* or `undefined` if the chain ID is not recognized or not supported.
*/
async evmChainIdToKnownChainId(
chainId: bigint,
): Promise<undefined | KnownChainId.EVMChain> {
@@ -498,6 +554,7 @@ export class XLinkSDK {
/**
* 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.
*
@@ -515,6 +572,10 @@ export class XLinkSDK {
/**
* This function maps a given contract address on an EVM-compatible blockchain to its corresponding known token ID.
*
* Always use this function to retrieve an `EVMToken` ID at runtime.
* Do not hardcode or cache token IDs, as supported tokens may change dynamically.
*
* @param chain - The ID of the EVM-compatible blockchain where the contract is deployed.
* @param address - The contract address on the EVM-compatible blockchain.
*
@@ -536,6 +597,7 @@ export class XLinkSDK {
* 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.).
@@ -551,6 +613,7 @@ export class XLinkSDK {
* - `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.
*/
@@ -564,6 +627,7 @@ export class XLinkSDK {
* 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).
@@ -576,6 +640,7 @@ export class XLinkSDK {
* - `sendTransaction` - // Implementation for sending transaction from EVM chain.
*
* @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.
*/
@@ -587,6 +652,7 @@ export class XLinkSDK {
* 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.
@@ -610,6 +676,7 @@ export class XLinkSDK {
/**
* 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.
@@ -624,6 +691,19 @@ export class XLinkSDK {
return claimTimeLockedAssetsFromEVM(this.sdkContext, input)
}
/**
* Retrieves the BTC Peg-In address and its corresponding ScriptPubKey for a given Bitcoin source
* chain (mainnet or testnet) and a specified destination chain.
* This address is used to initiate a transfer (peg-in) from the Bitcoin network into the XLink protocol.
*
* @param fromChain - The source Bitcoin chain (`Mainnet` or `Testnet`).
* @param toChain - The destination chain (must be a known chain, although it is not used in address generation).
*
* @returns A promise that resolves with an object containing:
* - `address`: the BTC Peg-In address to which the user should send BTC.
* - `scriptPubKey`: the ScriptPubKey representation of the address.
* Returns `undefined` if the provided chain is invalid or unsupported.
*/
async bitcoinReceiverAddress(
fromChain: ChainId,
toChain: ChainId,
@@ -637,7 +717,8 @@ export class XLinkSDK {
* 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:
*
* @param input - 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.
@@ -650,6 +731,7 @@ export class XLinkSDK {
* - `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.
*/
@@ -672,6 +754,7 @@ export class XLinkSDK {
/**
* 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.).
@@ -687,6 +770,7 @@ export class XLinkSDK {
* @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.
*/
@@ -712,6 +796,7 @@ export class 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.
*
* @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.).
@@ -726,6 +811,7 @@ export class XLinkSDK {
* - `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.
*/
@@ -742,6 +828,28 @@ export class XLinkSDK {
})
}
/**
* This function provides detailed information about token transfers from BRC-20 compatible chains to other supported
* blockchain networks, including Stacks, EVM-compatible chains, Bitcoin and Runes. It verifies the
* validity of the transfer route and retrieves bridge information, including intermediary steps and fees.
*
* @param input - An object containing the input parameters required to retrieve bridge information:
* - `fromChain: ChainId` – The source blockchain (must be a BRC-20-compatible chain).
* - `toChain: ChainId` – The destination blockchain.
* - `fromToken: TokenId` – The token being bridged from the source chain.
* - `toToken: TokenId` – The token expected on the destination chain.
* - `amount: SDKNumber` – The amount of tokens to bridge.
* - `swapRoute?: SwapRoute_WithExchangeRate_Public` – Optional: a route to perform token swaps during the bridge.
*
* @returns A promise that resolves with detailed bridge information:
* - `fromChain`, `toChain`, `fromToken`, `toToken` – Source and destination details.
* - `fromAmount`, `toAmount` – Input and estimated output amounts.
* - `fees` – A list of estimated fees applied to the bridge (fixed or rate-based).
* - `isPaused`, `minBridgeAmount`, `maxBridgeAmount` – Status and constraints of the bridge route.
* - `transferProphets` – A list of step-by-step bridge operations, including intermediary chains or swaps when applicable.
*
* @throws UnsupportedBridgeRouteError – If the route between the source and destination is not supported.
*/
bridgeInfoFromBRC20(
input: BridgeInfoFromBRC20Input,
): Promise<BridgeInfoFromBRC20Output> {
@@ -754,6 +862,34 @@ export class XLinkSDK {
throw err
})
}
/**
* This function estimates the transaction fee and vSize for transferring or swapping BRC-20 tokens
* from a Bitcoin-based network to other supported blockchains, including Stacks, EVM-compatible chains,
* Runes, or the Bitcoin network itself.
*
* @param input - An object containing the input parameters required for the transaction estimation:
* - `fromChain: ChainId` - The ID of the source chain (must be a BRC-20 compatible chain).
* - `fromToken: TokenId` - The token being bridged from the BRC-20 chain.
* - `toChain: ChainId` - The ID of the target chain.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `fromAddress: string` - The sender's Bitcoin address.
* - `fromAddressScriptPubKey: Uint8Array` - The script public key corresponding to the `fromAddress`.
* - `toAddress: string` - The recipient's address on the destination chain.
* - `toAddressScriptPubKey?: Uint8Array` - Required when bridging to a Bitcoin-based chain.
* - `inputInscriptionUTXO: UTXOSpendable` - The UTXO containing the BRC-20 inscription to be bridged.
* - `swapRoute?: SwapRoute_WithMinimumAmountsToReceive_Public` - Optional swap route if a token swap is involved before bridging.
* - `networkFeeRate: bigint` - The desired network fee rate.
* - `reselectSpendableNetworkFeeUTXOs: BridgeFromBRC20Input_reselectSpendableNetworkFeeUTXOs` - Function to reselect additional UTXOs for covering network fees.
*
* @returns A promise that resolves with estimated transaction parameters:
* - `fee: SDKNumber` - The estimated total fee in satoshis.
* - `estimatedVSize: SDKNumber` - The estimated virtual size of the transaction in vBytes.
* - `revealTransactionSatoshiAmount?: SDKNumber` - Optional, the amount of satoshis used in the reveal transaction output.
*
* @throws UnsupportedBridgeRouteError - If the provided route between the source and destination
* chains or tokens is not supported.
* @throws InvalidMethodParametersError - If any required parameters are missing or invalid for the selected route.
*/
estimateBridgeTransactionFromBRC20(
input: EstimateBridgeTransactionFromBRC20Input,
): Promise<EstimateBridgeTransactionFromBRC20Output> {
@@ -772,6 +908,35 @@ export class XLinkSDK {
},
)
}
/**
* This function facilitates the transfer of BRC-20 tokens from a BRC20-compatible network to other supported
* blockchain networks such as Stacks, EVM-compatible, Bitcoin, or Runes chains.
* It validates the provided route and delegates to the appropriate bridging logic depending on the destination.
*
* @param input - An object containing the input parameters required for the bridging operation:
* - `fromChain: ChainId` - The ID of the source blockchain (must be a BRC20-compatible chain).
* - `toChain: ChainId` - The ID of the destination blockchain (Stacks, EVM, Bitcoin, Runes, or another BRC20 chain).
* - `fromToken: TokenId` - The BRC-20 token being transferred.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `fromAddress: string` - The sender's Bitcoin address.
* - `fromAddressScriptPubKey: Uint8Array` - The script public key corresponding to the `fromAddress`.
* - `toAddress: string` - The recipient's address on the destination blockchain.
* - `toAddressScriptPubKey?: Uint8Array` - Required when the destination chain is Bitcoin, BRC20 or Runes.
* - `inputInscriptionUTXO: UTXOSpendable` - The inscription UTXO holding the BRC-20 token to bridge.
* - `networkFeeRate: bigint` - The fee rate for Bitcoin transaction construction.
* - `swapRoute?: SwapRoute_WithMinimumAmountsToReceive_Public` - Optional swap configuration for token conversion.
* Functions to be provided by the developer:
* - `reselectSpendableNetworkFeeUTXOs: BridgeFromBRC20Input_reselectSpendableNetworkFeeUTXOs` - Function to fetch additional UTXOs for network fee.
* - `signPsbt: BridgeFromBRC20Input_signPsbtFn` - Function to sign the PSBT (Partially Signed Bitcoin Transaction).
* - `sendTransaction` - Function used to broadcast the final signed transaction.
*
* @returns A promise that resolves with the Bitcoin transaction ID (`txid`) of the bridging operation.
*
* @throws `TooManyRequestsError` - is received from the backend API.
* @throws `UnsupportedBridgeRouteError` - If the combination of `fromChain`, `toChain`, `fromToken`, and `toToken` is unsupported.
* @throws `InvalidMethodParametersError` - If required parameters are missing.
* @throws `BridgeValidateFailedError` - If the bridge order validation fails.
*/
bridgeFromBRC20(input: BridgeFromBRC20Input): Promise<BridgeFromBRC20Output> {
return bridgeFromBRC20(this.sdkContext, input).catch(err => {
if (err instanceof TooManyRequestsError) {
@@ -782,19 +947,70 @@ export class XLinkSDK {
throw err
})
}
/**
* Retrieves the BRC20 tick (e.g., "ordi", "pepe") associated with a known BRC20 token ID
* on a specific BRC20-compatible blockchain in the SDK.
* Internally, this function looks up the list of supported BRC20 tokens on the given chain
* and returns the `brc20Tick` value corresponding to the provided `KnownTokenId.BRC20Token`.
*
* @param chain - The blockchain network (must be a valid BRC20 chain, like `brc20-mainnet` or `brc20-testnet`).
* @param token - The known BRC20 token identifier (must follow the `brc20-<tick>` format).
*
* @returns A promise that resolves with the corresponding BRC20 tick string, or `undefined`
* if the token is not found or the chain is not supported.
*/
brc20TickFromBRC20Token(
chain: ChainId,
token: KnownTokenId.BRC20Token,
): Promise<undefined | string> {
return brc20TickFromBRC20Token(this.sdkContext, chain, token)
}
/**
* Retrieves the `KnownTokenId.BRC20Token` corresponding to a given BRC20 tick
* on a specific BRC20-compatible blockchain.
* This function performs a case-insensitive match of the provided tick against
* the list of supported BRC20 tokens on the given chain.
*
* Always use this function to obtain a BRC20 token ID at runtime.
* Do not construct TokenId values manually, as supported tokens may change dynamically.
*
* @param chain - The blockchain network to search in (must be a BRC20-compatible chain such as `brc20-mainnet` or `brc20-testnet`).
* @param tick - The BRC20 tick (e.g., "ordi", "pepe") to look up.
*
* @returns A promise that resolves with the associated `KnownTokenId.BRC20Token`,
* or `undefined` if no match is found or the chain is not supported.
*
* @remarks Developers should always use this function to obtain a BRC20 token ID at runtime.
* Never construct `TokenId` values manually, as the supported token list may change dynamically.
*/
brc20TickToBRC20Token(
chain: ChainId,
tick: string,
): Promise<undefined | KnownTokenId.BRC20Token> {
return brc20TickToBRC20Token(this.sdkContext, chain, tick)
}
/**
* This function provides detailed information about bridging a token from the Runes protocol to other supported
* blockchain networks including Stacks, EVM, Bitcoin or BRC-20. It validates the compatibility
* of the route and determines fees, transfer amount, and route steps required to complete the bridge.
*
* @param input - An object containing the input parameters required to retrieve bridge information:
* - `fromChain: ChainId` – The source blockchain (must be a Runes-compatible chain).
* - `toChain: ChainId` – The destination blockchain.
* - `fromToken: TokenId` – The token being bridged from the source chain.
* - `toToken: TokenId` – The token expected on the destination chain.
* - `amount: SDKNumber` – The amount of tokens to bridge.
* - `swapRoute?: SwapRoute_WithExchangeRate_Public` – Optional: a route to perform token swaps during the bridge.
*
* @returns A promise that resolves with detailed bridge information:
* - `fromChain`, `toChain`, `fromToken`, `toToken` – Source and destination details.
* - `fromAmount`, `toAmount` – Input and estimated output amounts.
* - `fees` – A list of estimated fees applied to the bridge (fixed or rate-based).
* - `isPaused`, `minBridgeAmount`, `maxBridgeAmount` – Status and constraints of the bridge route.
* - `transferProphets` – A list of step-by-step bridge operations, including intermediary chains or swaps when applicable.
*
* @throws UnsupportedBridgeRouteError – If the route between the source and destination is not supported.
*/
bridgeInfoFromRunes(
input: BridgeInfoFromRunesInput,
): Promise<BridgeInfoFromRunesOutput> {
@@ -807,6 +1023,33 @@ export class XLinkSDK {
throw err
})
}
/**
* This function estimates the transaction fee and vSize for bridging Rune tokens from the Runes protocol
* to other supported blockchain networks such as Stacks, EVM-compatible chains, or BRC-20 destination.
*
* @param input - An object containing the input parameters required for estimating the transaction:
* - `fromChain: ChainId` - The ID of the source blockchain (a Runes-compatible Bitcoin chain).
* - `toChain: ChainId` - The ID of the destination blockchain.
* - `fromToken: TokenId` - The Rune token being transferred from the source.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `fromAddress: string` - The source Bitcoin address that holds the Rune token.
* - `fromAddressScriptPubKey: Uint8Array` - The script public key corresponding to the source address.
* - `toAddress: string` - The destination address on the target blockchain.
* - `toAddressScriptPubKey?: Uint8Array` - The script public key for the destination address, required when the destination is a Bitcoin-based chain.
* - `amount: SDKNumber` - The amount of Rune tokens to transfer.
* - `inputRuneUTXOs: RunesUTXOSpendable[]` - The list of Rune UTXOs used as inputs.
* - `networkFeeRate: bigint` - The fee rate to use for Bitcoin transaction construction.
* - `swapRoute?: SwapRoute_WithMinimumAmountsToReceive_Public` - Optional swap route to use in case token conversion is needed.
* - `reselectSpendableNetworkFeeUTXOs: BridgeFromRunesInput_reselectSpendableNetworkFeeUTXOs` - A function to reselect network fee UTXOs when needed.
*
* @returns A promise that resolves with an object containing estimated transaction data:
* - `fee: SDKNumber` - The estimated total fee in satoshis for the bridging operation.
* - `estimatedVSize: SDKNumber` - The estimated vSize of the transaction in bytes.
* - `revealTransactionSatoshiAmount?: SDKNumber` - (Optional) The satoshi amount associated with the reveal transaction used to complete the bridge.
*
* @throws UnsupportedBridgeRouteError - If the route between the source and destination tokens or chains is not supported.
* @throws InvalidMethodParametersError - If required parameters are missing.
*/
estimateBridgeTransactionFromRunes(
input: EstimateBridgeTransactionFromRunesInput,
): Promise<EstimateBridgeTransactionFromRunesOutput> {
@@ -825,6 +1068,35 @@ export class XLinkSDK {
},
)
}
/**
* This function facilitates the transfer of tokens from the Runes protocol to other supported
* blockchain networks. It validates the route using internal logic and delegates the transaction
* construction and broadcasting 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 (must be a Runes chain).
* - `toChain: ChainId` - The ID of the destination blockchain (Stacks, EVM, Bitcoin or BRC20).
* - `fromToken: TokenId` - The token being transferred from the Runes chain.
* - `toToken: TokenId` - The token expected on the destination chain.
* - `fromAddress: string` - The sender’s address on the Runes chain.
* - `fromAddressScriptPubKey: Uint8Array` - The script public key for `fromAddress`.
* - `toAddress: string` - The recipient’s address on the destination blockchain.
* - `toAddressScriptPubKey?: Uint8Array` - Required when the destination chain is Bitcoin or BRC20.
* - `amount: SDKNumber` - The amount of tokens to transfer.
* - `inputRuneUTXOs: RunesUTXOSpendable[]` - UTXOs containing the Runes to be spent.
* - `networkFeeRate: bigint` - The Bitcoin network fee rate to be used for the transaction.
* - `swapRoute?: SwapRoute_WithMinimumAmountsToReceive_Public` - Optional swap route for token conversion before bridging.
* Functions to be provided by the developer:
* - `reselectSpendableNetworkFeeUTXOs: BridgeFromRunesInput_reselectSpendableNetworkFeeUTXOs` - Callback to reselect UTXOs for network fee.
* - `signPsbt` - Callback function to sign the PSBT (Partially Signed Bitcoin Transaction).
* - `sendTransaction` - Callback function to broadcast the signed transaction.
*
* @returns A promise that resolves with the transaction ID (`txid`) of the bridging operation.
*
* @throws UnsupportedBridgeRouteError - If the route is not supported.
* @throws InvalidMethodParametersError - If required parameters are missing or invalid.
* @throws TooFrequentlyError - If the operation is rate-limited due to excessive requests.
*/
bridgeFromRunes(input: BridgeFromRunesInput): Promise<BridgeFromRunesOutput> {
return bridgeFromRunes(this.sdkContext, input).catch(err => {
if (err instanceof TooManyRequestsError) {
@@ -835,12 +1107,38 @@ export class XLinkSDK {
throw err
})
}
/**
* Retrieves the `RuneIdCombined` associated with a known Runes token on a specific Runes-compatible blockchain.
* Internally, this function queries the list of supported Runes tokens for the specified chain,
* and looks up the `runesId` that corresponds to the provided `KnownTokenId.RunesToken`.
*
* @param chain - The Runes-compatible blockchain (`runes-mainnet` or `runes-testnet`) to search in.
* @param token - The known Runes token ID (must follow the `runes-<id>` format).
*
* @returns A promise that resolves with the corresponding `RuneIdCombined` if found,
* or `undefined` if the token is not supported or the chain is invalid.
*/
runesIdFromRunesToken(
chain: ChainId,
token: KnownTokenId.RunesToken,
): Promise<undefined | RuneIdCombined> {
return runesIdFromRunesToken(this.sdkContext, chain, token)
}
/**
* Retrieves the `KnownTokenId.RunesToken` associated with a given `RuneIdCombined`
* on a specific Runes-compatible blockchain.
* This function queries the list of supported Runes tokens for the specified chain,
* and returns the known Runes token ID mapped to the provided `runesId`.
*
* Always use this function to retrieve a `RunesToken` ID at runtime.
* Do not hardcode or cache token IDs, as supported tokens may change dynamically.
*
* @param chain - The Runes-compatible blockchain (`runes-mainnet` or `runes-testnet`) to search in.
* @param id - The `RuneIdCombined` representing the unique Runes asset identifier.
*
* @returns A promise that resolves with the corresponding `KnownTokenId.RunesToken`,
* or `undefined` if the ID is not recognized or the chain is not supported.
*/
runesIdToRunesToken(
chain: ChainId,
id: RuneIdCombined,
@@ -849,14 +1147,6 @@ 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(
sdkContext: SDKGlobalContext,
chain: ChainId,
@@ -871,15 +1161,6 @@ async function stacksAddressFromStacksToken(
}
}
/**
* 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(
sdkContext: SDKGlobalContext,
chain: ChainId,

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

@@ -31,17 +31,19 @@ export namespace KnownTokenId {
/** Represents the Bitcoin token ID (BTC). */
export const BTC = tokenId("btc-btc")
}
/** This type includes all known Bitcoin tokens. */
/** This type defines known Bitcoin tokens. */
export type BitcoinToken = (typeof _allKnownBitcoinTokens)[number]
export function isBitcoinToken(value: TokenId): value is BitcoinToken {
return _allKnownBitcoinTokens.includes(value as any)
}
/** This type defines known BRC20 tokens. */
export type BRC20Token = TokenId<"a brc20 token">
export function isBRC20Token(value: TokenId): value is BRC20Token {
return value.startsWith("brc20-")
}
/** This type defines known Runes tokens. */
export type RunesToken = TokenId<"a runes token">
export function isRunesToken(value: TokenId): value is RunesToken {
return value.startsWith("runes-")
@@ -77,18 +79,24 @@ export namespace KnownTokenId {
export const vLiSTX = tokenId("evm-vlistx")
/** Represents the vLiALEX token ID on EVM-compatible blockchains. */
export const vLiALEX = tokenId("evm-vlialex")
/** Represents the uBTC token ID on EVM-compatible blockchains. */
export const uBTC = tokenId("evm-ubtc")
/** Represents the wuBTC token ID on EVM-compatible blockchains. */
export const wuBTC = tokenId("evm-wubtc")
/** Represents the DB20 token ID on EVM-compatible blockchains. */
export const DB20 = tokenId("evm-db20")
/** Represents the DOG token ID on EVM-compatible blockchains. */
export const DOG = tokenId("evm-dog")
/** Represents the STX token ID on EVM-compatible blockchains. */
export const STX = tokenId("evm-stx")
/** Represents the TRUMP token ID on EVM-compatible blockchains. */
export const TRUMP = tokenId("evm-trump")
export const GHIBLICZ = tokenId("evm-ghiblicz")
export const ETH = tokenId("evm-eth")
export const SOL = tokenId("evm-sol")
export const LINK = tokenId("evm-link")
}
/** This type includes all known tokens on EVM-compatible blockchains. */
/** This type defines 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)
@@ -113,10 +121,15 @@ export namespace KnownTokenId {
export const vLiALEX = tokenId("stx-vlialex")
/** Represents the vLiaBTC token ID on the Stacks blockchain. */
export const vLiaBTC = tokenId("stx-vliabtc")
/** Represents the DB20 token ID on the Stacks blockchain. */
export const DB20 = tokenId("stx-db20")
/** Represents the uBTC token ID on the Stacks blockchain. */
export const uBTC = tokenId("stx-ubtc")
/** Represents the DOG token ID on the Stacks blockchain. */
export const DOG = tokenId("stx-dog")
/** Represents the STX token ID on the Stacks blockchain. */
export const STX = tokenId("stx-stx")
/** Represents the TRUMP token ID on the Stacks blockchain. */
export const TRUMP = tokenId("stx-trump")
export const GHIBLICZ = tokenId("stx-ghiblicz")
export const ETH = tokenId("stx-eth")