kylefang/bro-sdk
1
0
Fork 0
mirror of https://github.com/Brotocol-xyz/bro-sdk.git synced 2026-04-30 20:31:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update main readme

Browse Source
This commit is contained in:
sofinico
2025-03-26 18:10:28 +01:00
parent 452b1cad7f
commit 98ee4741d5
1 changed files with 176 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
README.md
View File

@@ -1,67 +1,60 @@
# XLinkSDK # 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. 🐙 **XLINK isn't just a bridge—it's the liquidity layer for Bitcoin and the essential connector for Bitcoin DeFi** 🐙
## System Type and Purpose XLinkSDK enables seamless asset transfers between Bitcoin, Stacks, and EVM-compatible blockchains. It supports cross-chain swaps, Runes & BRC20 metaprotocols, and DEX aggregator integrations.
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. 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 ## Installation
### Prerequisites ### Prerequisites
Ensure you have the following installed:
- [Node.js](https://nodejs.org/en) - [Node.js](https://nodejs.org/en)
- [pnpm](https://pnpm.io/) - [pnpm](https://pnpm.io/)
### Installing the XLink SDK Library ### Install
To install the XLink SDK, use the following command:
```bash ```bash
pnpm install @xlink-network/xlink-sdk pnpm install @xlink-network/xlink-sdk
``` ```
## XLink SDK API ## Usage
The [`XLinkSDK`](./src/XLinkSDK.ts) class provides the core functions of the library. To create an instance:
```typescript
import { XLinkSDK } from "@xlink-network/xlink-sdk"
const sdk = new XLinkSDK()
```
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).
### Supported Blockchains and Tokens ### Supported Blockchains and Tokens
#### KnownChainId #### [`KnownChainId`](https://releases-latest.xlink-sdk.pages.dev/modules/index.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. Defines types and utility functions for supported networks, ensuring only valid chain IDs are used within the SDK.
| Namespace | Mainnet | Testnet | | Namespace | Mainnet | Testnet |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Bitcoin | `Mainnet` | `Testnet` | | Bitcoin | `Mainnet` | `Testnet` |
| Stacks | `Mainnet` | `Testnet` | | Runes | `Mainnet` | `Testnet` |
| EVM | `Ethereum`, `BSC`, `CoreDAO`, `Bsquared`, `BOB`, `Bitlayer`, `Lorenzo`, `Merlin`, `AILayer`, `Mode`, `XLayer`, `Arbitrum`, `Aurora`, `Manta`, `Linea` | `Sepolia`, `BSCTestnet`, `CoreDAOTestnet`, `BisonTestnet`, `BitboyTestnet`, `BeraTestnet` | | 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 #### [`KnownTokenId`](https://releases-latest.xlink-sdk.pages.dev/modules/index.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. Defines types, utility functions, and supported tokens within the SDK.
##### Namespaces | Namespace | Tokens |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namespace | Tokens | | Bitcoin | `BTC` |
| --------- | ------------------------------------------------------------------------------------------------------------------- | | Runes | _To be confirmed_ |
| Bitcoin | `BTC` | | BRC20 | _To be confirmed_ |
| Stacks | `sUSDT`, `sLUNR`, `aBTC`, `ALEX`, `sSKO`, `vLiSTX`, `vLiALEX`, `uBTC`, `DB20`, `DOG` | | Stacks | `sUSDT`, `sLUNR`, `aBTC`, `ALEX`, `sSKO`, `vLiSTX`, `vLiALEX`, `vLiaBTC`,`uBTC`, `DB20`, `DOG`, `STX`, `TRUMP` |
| EVM | `USDT`, `LUNR`, `WBTC`, `BTCB`, `aBTC`, `sUSDT`, `ALEX`, `SKO`, `vLiSTX`, `vLiALEX`, `uBTC`, `wuBTC`, `DB20`, `DOG` | | EVM | `USDT`, `sUSDT`, `USDC`, `aBTC`, `WTCB`, `BTCB`, `cbBTC`, `uBTC`, `wuBTC`, `STX`, `vLiSTX`, `ALEX`, `vLiALEX`, `LUNR`, `SKO`, `DB20`, `DOG`, `TRUMP` |
**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:
```typescript
const theSdk = new XLinkSDK()
```
For detailed API documentation, including a full list of available methods and their usage, please refer to:
[SDK API Documentation](https://releases-latest.xlink-sdk.pages.dev)
### Use Cases ### Use Cases
@@ -74,146 +67,211 @@ const xlinkSdk = new XLinkSDK()
#### Bridge from Stacks #### Bridge from Stacks
Use case showcasing a transfer of 100 `sUSDT` from Stacks to `USDT` on Ethereum using XLinkSDK.
```typescript ```typescript
import { serializeCVBytes } from '@stacks/transactions';
import { import {
BridgeInfoFromStacksInput,
BridgeFromStacksInput, BridgeFromStacksInput,
KnownChainId, KnownChainId,
KnownTokenId, KnownTokenId,
toSDKNumberOrUndefined, toSDKNumberOrUndefined,
} from '@xlink-network/xlink-sdk'; } from '@xlink-network/xlink-sdk';
import { serializeCVBytes, makeContractCall, broadcastTransaction } from '@stacks/transactions';
// Get bridge info // Retrieve bridge information
const bridgeInfo = await xlinkSdk.bridgeInfoFromStacks({ const bridgeInfo = await xlinkSdk.bridgeInfoFromStacks({
fromChain: KnownChainId.Stacks.Mainnet, fromChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.Stacks.sUSDT, toChain: KnownChainId.EVM.Ethereum,
toChain: KnownChainId.EVM.Ethereum, fromToken: KnownTokenId.Stacks.sUSDT,
toToken: KnownTokenId.EVM.USDT, toToken: KnownTokenId.EVM.USDT,
amount: toSDKNumberOrUndefined(100), amount: toSDKNumberOrUndefined(100),
}); });
console.log("Bridge Info:", bridgeInfo); 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 // Perform the bridge operation
const result = await xlinkSdk.bridgeFromStacks({ const result = await xlinkSdk.bridgeFromStacks(bridgeFromStacksInput);
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};
},
});
console.log("Transaction ID:", result.txid); console.log("Transaction ID:", result.txid);
``` ```
#### Bridge from EVM #### Bridge from EVM
Use case showcasing a transfer of 100 `USDT` from Ethereum to `UsSDT` on Stacks using XLinkSDK.
```typescript ```typescript
import { import {
BridgeInfoFromEVMInput,
BridgeFromEVMInput, BridgeFromEVMInput,
KnownChainId, KnownChainId,
KnownTokenId, KnownTokenId,
toSDKNumberOrUndefined, toSDKNumberOrUndefined,
} from "@xlink-network/xlink-sdk" } from "@xlink-network/xlink-sdk"
import { ethers } from "ethers";
// Get bridge info
// Retrieve bridge information
const bridgeInfo = await xlinkSdk.bridgeInfoFromEVM({ const bridgeInfo = await xlinkSdk.bridgeInfoFromEVM({
fromChain: KnownChainId.EVM.Ethereum, fromChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.EVM.USDT,
toChain: KnownChainId.Stacks.Mainnet, toChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.EVM.USDT,
toToken: KnownTokenId.Stacks.sUSDT, toToken: KnownTokenId.Stacks.sUSDT,
amount: toSDKNumberOrUndefined(100), amount: toSDKNumberOrUndefined(100),
}) });
console.log("Bridge Info:", bridgeInfo)
// Perform the bridge operation console.log("Bridge Info:", bridgeInfo);
const result = await xlinkSdk.bridgeFromEVM({
// 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, fromChain: KnownChainId.EVM.Ethereum,
fromToken: KnownTokenId.EVM.USDT,
fromAddress: "0x95222290DD7278Aa3D......................",
toChain: KnownChainId.Stacks.Mainnet, toChain: KnownChainId.Stacks.Mainnet,
fromToken: KnownTokenId.EVM.USDT,
toToken: KnownTokenId.Stacks.sUSDT, toToken: KnownTokenId.Stacks.sUSDT,
toAddress: "0x95222290DD7278Aa3D......................", fromAddress: /* Sender EVM address */,
amount: toSDKNumberOrUndefined(10), toAddress: /* Receiver Stacks principal */,
sendTransaction: async function (tx: { amount: toSDKNumberOrUndefined(100),
from: `0x${string}` sendTransaction: async (tx:
to: `0x${string}` {
data: Uint8Array from: EVMAddress /* Sender EVM address */
recommendedGasLimit: `${string} (XLinkSDK number)` to: EVMAddress /* Bridge Endpoint address */
}): Promise<{ txHash: string }> { data: Uint8Array /* Transaction data */
// Implementation for sending transaction from EVM chain recommendedGasLimit: SDKNumber /* Recommended gas limit */
return { txHash: "....." } 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 };
}, },
}) };
console.log("Transaction ID:", result.txHash)
// Perform the bridge operation
const result = await xlinkSdk.bridgeFromEVM(bridgeFromEVMInput);
console.log("Transaction ID:", result.txHash);
``` ```
#### Bridge from Bitcoin #### Bridge from Bitcoin
Use case showcasing a transfer of 1 `BTC` from Bitcoin to `WBTC` on Ethereum using XLinkSDK.
```typescript ```typescript
import { import {
BridgeInfoFromBitcoinInput,
BridgeFromBitcoinInput, BridgeFromBitcoinInput,
KnownChainId, KnownChainId,
KnownTokenId, KnownTokenId,
toSDKNumberOrUndefined, toSDKNumberOrUndefined,
} from "@xlink-network/xlink-sdk" } 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";
// Get bridge info // Retrieve bridge information
const bridgeInfo = await xlinkSdk.bridgeInfoFromBitcoin({ const bridgeInfo = await xlinkSdk.bridgeInfoFromBitcoin({
fromChain: KnownChainId.Bitcoin.Mainnet, fromChain: KnownChainId.Bitcoin.Mainnet,
fromToken: KnownTokenId.Bitcoin.BTC,
toChain: KnownChainId.EVM.Ethereum, toChain: KnownChainId.EVM.Ethereum,
toToken: KnownTokenId.EVM.BTCB, fromToken: KnownTokenId.Bitcoin.BTC,
toToken: KnownTokenId.EVM.WBTC,
amount: toSDKNumberOrUndefined(1), amount: toSDKNumberOrUndefined(1),
}) });
console.log("Bridge Info:", bridgeInfo) console.log("Bridge Info:", bridgeInfo)
// Perform the bridge operation const bridgeFromBitcoinInput: BridgeFromBitcoinInput = {
const result = await xlinkSdk.bridgeFromBitcoin({
fromChain: KnownChainId.Bitcoin.Mainnet, fromChain: KnownChainId.Bitcoin.Mainnet,
fromToken: KnownTokenId.Bitcoin.BTC, fromToken: KnownTokenId.Bitcoin.BTC,
fromAddress: "bitcoin address",
toChain: KnownChainId.EVM.Ethereum, toChain: KnownChainId.EVM.Ethereum,
toToken: KnownTokenId.EVM.WBTC, toToken: KnownTokenId.EVM.WBTC,
toAddress: "0x...", fromAddress: /* Sender Bitcoin address */,
fromAddressScriptPubKey: new Uint8Array([10, 20, 30, 40]), toAddress: /* Receiver EVM address */,
amount: toSDKNumberOrUndefined(1), amount: toSDKNumberOrUndefined(1),
networkFeeRate: 10n, networkFeeRate: 10n,
reselectSpendableUTXOs( reselectSpendableUTXOs: async (
satsToSend: bigint, satsToSend: bigint,
pinnedUTXOs: UTXOSpendable[], pinnedUTXOs: UTXOSpendable[],
lastTimeSelectedUTXOs: UTXOSpendable[], lastTimeSelectedUTXOs: UTXOSpendable[]
): Promise<UTXOSpendable[]> { ): Promise<UTXOSpendable[]> => {
return Promise.resolve([]) /**
* Implementation for selecting spendable UTXOs from the wallet
* This should fetch available UTXOs from a Bitcoin node or explorer API
*/
return [];
}, },
signPsbt: function (tx: { signPsbt: async (tx: { psbt: Uint8Array; signInputs: number[] }): Promise<{ psbt: Uint8Array }> => {
psbt: Uint8Array /**
signInputs: number[] * Implementation for signing a Bitcoin PSBT (Partially Signed Bitcoin Transaction)
}): Promise<{ psbt: Uint8Array }> { * See https://github.com/bitcoinjs/bitcoinjs-lib for reference
throw new Error("Function not implemented.") */
let psbt = Psbt.fromBuffer(tx.psbt);
tx.signInputs.forEach((index) => {
psbt.signInput(index, keyPair);
});
psbt.finalizeAllInputs();
return { psbt: psbt.toBuffer() };
}, },
sendTransaction: function (tx: { hex: string }): Promise<{ txid: string }> { sendTransaction: async (tx: { hex: string }): Promise<{ txid: string }> => {
throw new Error("Function not implemented.") /**
* 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 };
}, },
}) };
console.log("Transaction ID:", result.tx)
``` // Perform the bridge operation
const result = await xlinkSdk.bridgeFromBitcoin(bridgeFromBitcoinInput);
console.log("Transaction ID:", result.txid);
```