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

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.

Roadmap

• Bitcoin <> EVM
• Bitcoin <> Stacks
• Runes <> Stacks
• BRC-20 <> Stacks
• EVM <> EVM
• EVM <> Bitcoin
• EVM <> Stacks

Installation

Prerequisites

Ensure you have the following installed:

• Node.js
• pnpm

Installation

To install the XLink SDK, use the following command:

pnpm install @xlink-network/xlink-sdk

XLink SDK API

Supported Blockchains and Tokens

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	Sepolia, BSCTestnet, CoreDAOTestnet, BsquaredTestnet, BOBTestnet, BitlayerTestnet, LorenzoTestnet, MerlinTestnet, AILayerTestnet, ModeTestnet

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	Token
Bitcoin	BTC
Stacks	ALEX, aBTC, sLUNR, sSKO, sUSDT, uBTC, vLiALEX, vLiSTX
EVM	ALEX, aBTC, BTCB, LUNR, SKO, sUSDT, uBTC, USDT, vLiALEX, vLiSTX, WBTC, wuBTC

Future Support: Support for Runes and BR20 tokens on the Bitcoin network is planned for a future update.

XLink SDK

The XLinkSDK object contains the most important functions of this library, all grouped together. To create it:

const theSdk = new XLinkSDK();

For detailed API documentation, including a full list of available methods and their usage, please refer to:

SDK API Documentation

Use Cases

Create an instance of the SDK with default options

import { XLinkSDK } from '@xlink-network/xlink-sdk';
const xlinkSdk = new XLinkSDK();

1. Bridge from Stacks

import { 
    BridgeInfoFromStacksInput, 
    BridgeFromStacksInput,
    KnownChainId,
    KnownTokenId, 
    toSDKNumberOrUndefined,
} from '@xlink-network/xlink-sdk';

// 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),
});
console.log("Bridge Info:", bridgeInfo);

// 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,
    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,
            senderKey: /* sender address private key */,
            network,
            postConditions: tx.postConditions,
            anchorMode: tx.anchorMode,
        });
        const broadcastResponse = await broadcastTransaction(transaction, network);
        return broadcastResponse.txid;
    },
});
console.log("Transaction ID:", result.txid);

2. Bridge from EVM

import { 
    BridgeInfoFromEVMInput,
    BridgeFromEVMInput,
    KnownChainId,
    KnownTokenId,
    toSDKNumberOrUndefined,
} from '@xlink-network/xlink-sdk';

// Get bridge info
const bridgeInfo = await xlinkSdk.bridgeInfoFromEVM({
    fromChain: KnownChainId.EVM.Ethereum,
    fromToken: KnownTokenId.EVM.USDT,
    toChain: KnownChainId.Stacks.Mainnet,
    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,
    toChain: KnownChainId.Stacks.Mainnet,
    toToken: KnownTokenId.Stacks.sUSDT,
    toAddress: "0x...",
    amount: toSDKNumberOrUndefined(10),
    sendTransaction: // Implementation for sending transaction from EVM chain
});
console.log("Transaction ID:", result.txHash);

3. Bridge from Bitcoin

import { 
    BridgeInfoFromBitcoinInput,
    BridgeFromBitcoinInput,
    KnownChainId,
    KnownTokenId,
    toSDKNumberOrUndefined,
} from '@xlink-network/xlink-sdk';

// Get bridge info
const bridgeInfo = await xlinkSdk.bridgeInfoFromBitcoin({
    fromChain: KnownChainId.Bitcoin.Mainnet,
    toChain: KnownChainId.EVM.Ethereum,
    amount: toSDKNumberOrUndefined(1),
});
console.log("Bridge Info:", bridgeInfo);

// Perform the bridge operation
const result = await xlinkSdk.bridgeFromBitcoin({
    fromChain: KnownChainId.Bitcoin.Mainnet,
    fromToken: KnownTokenId.Bitcoin.BTC,
    toChain: KnownChainId.EVM.Ethereum,
    toToken: KnownTokenId.EVM.WBTC,
    fromAddress: "bitcoin address",
    fromAddressScriptPubKey: scriptPubKey,
    toAddress: "0x...",
    amount: toSDKNumberOrUndefined(1),
    networkFeeRate: 10n,
    reselectSpendableUTXOs: // Implementation for reselect UTXOs
    signPsbt: // Implementation for signing PSBT
});
console.log("Transaction ID:", result.tx);