@teleportdao/teleswap-sdk

Table of contents

• TeleSwap SDK Integration
• Initialize SDK
• Estimate output amount
• Create unsigned transaction
• Create and sign transaction
• Examples

TeleSwap SDK integration

TeleSwap enables secure and seamless bridging of Bitcoin assets (BTC, BRC-20 tokens, and RUNEs) across blockchains. The SDK provides core functionalities for bridging Bitcoin assets between Bitcoin and EVM networks.

The SDK provides four main functionalities:

• wrap: Convert BTC to TELEBTC
• wrapAndSwap: Convert BTC to ERC-20
• unwrap: Convert TELEBTC to BTC
• swapAndUnwrap: Convert ERC-20 to BTC

Supported EVM networks & tokens

Base networks: You can wrap and unwrap BTC + swap BTC<>ERC-20 on these networks.

• Polygon: USTD, USDC, USDC.e, WBTC, WETH, MATIC, WMATIC, TELEBTC
• BNB: USDT, USDC, ETH, BTCB, BNB, WBNB, TELEBTC
• BSquared: USDT, USDC, BTC, WBTC, TELEBTC
• Bob: USDT, USDC, WETH, WBTC, TELEBTC

Cross-chain networks: You can swap BTC<>ERC-20 on these networks. Cross-chain networks use a base network as an intermediary.

• Ethereum: USDT, USDC, ETH, WETH, WBTC
• Optimism: USDT, USDC, ETH, WETH, WBTC
• Arbitrum: USDT, USDC, ETH, WETH, WBTC

Initialize SDK

1) Create SDK instance

First, create an instance of the SDK class.

• Optional: Set the default base network (e.g. Polygon)

let sdk = new TeleswapSDK()
// set default network
sdk.setDefaultNetwork({
  networkName: "polygon",
})

2) Bitcoin connection

The default Bitcoin connections are MempoolSpace and TeleportDAO for retrieving UTXOs and Bitcoin fee rates.

3) Add EVM connection

To interact with EVM networks, add network connection information to the SDK.

Option 1: TeleportDAO RPC (rate-limit applied)

// Initialize all networks with TeleportDAO RPC
await sdk.initNetworksConnection()

// Use this method to set custom RPCs for specific networks while keeping the default TeleportDAO RPCs for others.
await sdk.initNetworksConnection([
  {
    networkName: "ethereum",
    web3: {
      url: "https://example.com",
    },
  },
])

Option 2: your desired RPCs

// Add your custom RPC
sdk.addNetwork({
  networkName: "bsc",
  web3: {
    url: "https://example.com",
  },
})

4) Initialize with mnemonic (Optional)

To sign transactions on Bitcoin or EVM networks using a mnemonic, initialize the account with the mnemonic.

• If you only use EVM or Bitcoin, you can skip initialization for the other.

// Init Bitcoin account
let mnemonic = "..."
let bitcoinAddress = sdk.initBitcoinAccountUsingMnemonic(mnemonic)

// Init Polygon account
let polygonAddress = sdk.initEvmAccountUsingMnemonic(mnemonic)

Get the addresses of Bitcoin and EVM accounts using the following methods (need to initialize SDK first)

let bitcoinAddress = sdk.bitcoinAddress
let bitcoinAddressType = sdk.bitcoinAddressType
let targetNetworkAddress = sdk.evmAddress

5) Set Third Party Id (Optional)

To assign third-party ID requests and receive fees accordingly, initialize the SDK with your thirdPartyId.

Note: Please contact us on Discord to obtain your Third Party ID.

const thirdPartyId = 100
sdk.setThirdPartyId(thirdPartyId)

Estimate output amount

Estimate wrap (Bitcoin -> Base network)

let amountInBTC = 0.001
// for normal wrap networkName should be one of the base networks
let baseNetworkName:  = "polygon"

let estimateResponse = await sdk.wrapEstimate(
  amountInBTC,
  baseNetworkName,
)

Example response

// estimateResponse.fee : teleportdao bridge fee details
// estimateResponse.amount.receivedAmountBTC : received TELEBTC amount on base network
{
  message: '',
  success: true,
  fee: {
    networkFeeBTC: '0.00001000',
    protocolFeeBTC: '0.00000050',
    lockerFeeBTC: '0.00000150',
    thirdPartyFeeBTC: '0.00000000',
    totalFeeBTC: '0.00001200'
  },
  amount: {
    inputAmountBTC: '0.001',
    receivedAmountBTC: '0.00098800'
  }
}

Estimate wrapAndSwap (Bitcoin -> EVM)

let amountInBTC = 0.001
let networkName:  = "optimism"
let outputTokenAddress = "token contract address"
let estimateResponse = await sdk.wrapAndSwapEstimate(
  amountInBTC,
  outputTokenAddress,
  networkName,
)

Example response

// estimateResponse.fee : teleportdao bridge fee details
// estimateResponse.amount.receivedAmountBTC : received TELEBTC amount on base network
// estimateResponse.exchange.inputAmount : input TELEBTC amount
// estimateResponse.exchange.outputAmount : exchanged token amount on base network
// estimateResponse.exchange.bridgeFee : cross chain bridge fee
// final received amount = estimateResponse.exchange.outputAmount - bridgeFee
{
  message: '',
  success: true,
  fee: {
    networkFeeBTC: '0.00001000',
    protocolFeeBTC: '0.00000050',
    lockerFeeBTC: '0.00000150',
    thirdPartyFeeBTC: '0.00000000',
    totalFeeBTC: '0.00001200'
  },
  amount: {
    inputAmountBTC: '0.001',
    receivedAmountBTC: '0.00098800'
  },
  exchange: {
    inputAmount: '98800',
    outputAmount: '66379561'
  },
  bridgeFee: '41055'
}

Estimate unwrap (Base network -> Bitcoin)

let amountInBTC = 0.001
// for unwrap networkName should be one of the base networks
let baseNetworkName:  = "polygon"

let estimateResponse = await sdk.unwrapEstimate(
  amountInBTC,
  baseNetworkName,
)

Example response

// estimateResponse.fee : teleportdao bridge fee details
// estimateResponse.amount.receivedAmountBTC : received BTC amount on bitcoin network
{
  message: '',
  success: true,
  fee: {
    networkFeeBTC: '0.00001500',
    protocolFeeBTC: '0.00000050',
    lockerFeeBTC: '0.00000148',
    thirdPartyFeeBTC: '0.00000000',
    totalFeeBTC: '0.00001698'
  },
  amount: {
    inputAmountBTC: '0.001',
    receivedAmountBTC: '0.00098302'
  }
}

Estimate swapAndUnwrap (EVM -> Bitcoin)

let networkName:  = "optimism"
let exchangeInfo = {
  inputToken: "Token Contract Address",
  inputAmount: 50 * 1e18, // for example (50 WMatic)
}
let estimateResponse = await sdk.swapAndUnwrapEstimate(
 exchangeInfo,
  networkName,
)

Example response

// estimateResponse.fee : teleportdao bridge fee details
// estimateResponse.exchange.inputAmount : input token amount on evm network
// estimateResponse.exchange.outputAmount : TELEBTC amount on base network
// estimateResponse.amount.receivedAmountBTC : BTC amount on bitcoin network
{
  message: '',
  success: true,
  fee: {
    networkFeeBTC: '0.00001500',
    protocolFeeBTC: '0.00000009',
    lockerFeeBTC: '0.00000025',
    thirdPartyFeeBTC: '0.00000000',
    totalFeeBTC: '0.00001534'
  },
  amount: {
    inputAmountBTC: '0.00018374',
    receivedAmountBTC: '0.00016840'
  },
  exchange: {
    inputAmount: '5000000000000000',
    outputAmount: '18374'
  },
  bridgeFee: '2284954268366'
}

Create unsigned transaction

Use the methods below to create unsigned transactions or retrieve the inputs needed for direct contract calls.

Unsigned wrap (Bitcoin -> Base network)

This function enables wrapping BTC from Bitcoin to an EVM base network, receiving TELEBTC in return.

let amountInBTC = 0.001
let polygonRecipientAddress = "0x..."
let baseNetworkName:  = "polygon"

// You need to provide Bitcoin account details to create an unsigned transaction
const signerInfo: {
  addressType: "p2wpkh" | "p2pkh" | "p2sh-p2wpkh"
  publicKey: string
  address: string
}

let unsignedTxResponse = await sdk.wrapUnsigned(
  polygonRecipientAddress,
  amountInBTC,
  signerInfo,
  baseNetworkName,
)

const unsignedPSBT = unsignedTxResponse.unsignedTransaction

// Sign unsignedTx
let signedTx = ...

// Send signed Tx
let bitcoinTxId = await sdk.sendSignedTransaction(signedTx)

Unsigned wrapAndSwap (Bitcoin -> EVM)

This function enables swapping BTC on Bitcoin for tokens on EVM networks.

// You need to provide the relevant exchange information

let amountInBTC = 0.001
let evmAddress = "0x..."
let networkName = "ethereum"
let exchangeTokenAddress = "0x..."

// You need to provide Bitcoin account details to create an unsigned transaction
const signerInfo: {
  addressType: "p2wpkh" | "p2pkh" | "p2sh-p2wpkh"
  publicKey: string
  address: string
}

const unsignedResponse = await sdk.wrapAndSwapUnsigned(
  evmAddress,
  amountInBTC,
  exchangeTokenAddress,
  signerInfo,
  network,
)

Unsigned unwrap (Base network -> Bitcoin)

This function enables unwrapping TELEBTC on base networks to receive BTC in return.

Note: You can obtain the inputs for the unwrap function and call the BurnRouter contract directly.

• To interact with the contract directly, you must grant approval to the contract for an amount equal to the input value.
• TODO: how to get contract address and ABI

import { ABI } from "@teleportdao/contracts-helper"
import { teleswap } from "@teleportdao/configs"
// for base network use this abi
const ccBurnABI = ABI.CCBurnRouterABI

// base network contract addresses
const polygonCCBurnAddress = teleswap.contracts.polygon.mainnet.ccBurnAddress
const bscCCBurnAddress = teleswap.contracts.bsc.mainnet.ccBurnAddress
const bobCCBurnAddress = teleswap.contracts.bob.mainnet.ccBurnAddress
const bsquaredCCBurnAddress = teleswap.contracts.bsquared.mainnet.ccBurnAddress

//  ---------------
// for cross chain use this abi
const connectorABI = ABI.TeleswapEthConnectorABI
//  cross chain connector contract addresses
const ethereumConnectorAddress = teleswap.connectors.ethereum.mainnet.connectorAddress
const arbitrumConnectorAddress = teleswap.connectors.arbitrum.mainnet.connectorAddress
const optimismConnectorAddress = teleswap.connectors.optimism.mainnet.connectorAddress

// if sdk is initialized
let amountInBTC = 0.001
let recipientBitcoinAddress = "..."
let baseNetworkName = "polygon"

// If your account is not initialized, you can obtain the function inputs and interact with the contract directly
const unwrapInputsResponse = await sdk.unwrapInputs(amountInBTC, btcAddress, baseNetworkName)

Example response

// Check contract ABI to see params details
// unwrapInputsResponse.unwrapInputs.params are contract inputs in order. check contract abi to know
{
  locker: {
    sourceAddress: '3CAQAw7m95axbY761Xq8d9DADhjNaX9b8o',
    targetAddress: '0x13ffEe453a15E627Cd2aCbb23A735ab57c7C298f',
    lockingScript: '0xa91472df0f82c4bcfe01a274bd521e5d4c66586b7a5b87'
  },
  inputs: {
    params: [
      '100000',
      '0x7858574ca53954113221037a0f6a667ffa03babc',
      3,
      '0xa91472df0f82c4bcfe01a274bd521e5d4c66586b7a5b87',
      0
    ],
    value: '0'
  }
}

Unsigned swapAndUnwrap (EVM -> Bitcoin)

This function enables swapping EVM tokens to receive BTC in return.

Note: You can obtain the inputs for the swapAndUnwrap function and call the contract directly:

• To interact with the contract directly, you must grant approval to the contract for an amount equal to the input value.
• If your network is a base network, call the BurnRouter contract.
• If your network is a cross-chain network, call the EthConnector contract.
• TODO: how to get contract address and ABI

let recipientBitcoinAddress = "..."
let exchangeInfo = {
  inputToken: "Token Contract Address",
  inputAmount: 50 * 1e18, // for example (50 WMatic)
}
let network = "optimism"

// If the received amount is less than minimumExpectedBTCAmount, the transaction will fail
const minimumExpectedBTCAmount = "0"

// If your account is not initialized, you can obtain the function inputs and interact with the contract directly
const unwrapAndSwapInputs = await sdk.swapAndUnwrapInputs(
  exchangeInfo,
  btcAddress,
  network,
  minimumExpectedBTCAmount,
)

Example response

{
  "locker": {
    "sourceAddress": "3CAQAw7m95axbY761Xq8d9DADhjNaX9b8o",
    "targetAddress": "0x13ffEe453a15E627Cd2aCbb23A735ab57c7C298f",
    "lockingScript": "0xa91472df0f82c4bcfe01a274bd521e5d4c66586b7a5b87"
  },
  "inputs": {
    "params": [
      "0x4e3e1807aa17aed8d1FC580dDa552079d9427ece",
      [
        "5000000000000000",
        "0"
      ],
      true,
      [
        "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
        "0x1BFD67037B42Cf73acF2047067bd4F2C47D9BfD6",
        "0x3BF668Fe1ec79a84cA8481CEAD5dbb30d61cC685"
      ],
      1730308950,
      "0x7858574ca53954113221037a0f6a667ffa03babc",
      3,
      "0xa91472df0f82c4bcfe01a274bd521e5d4c66586b7a5b87",
      0
    ],
    "value": "0"
  }
}

Create and sign transaction

For the following functions, you must first initialize the SDK with a mnemonic.

Signed wrap (Bitcoin -> Base network)

This function enables wrapping BTC from Bitcoin to an EVM base network, receiving TELEBTC in return.

let amountInBTC = 0.001
let polygonRecipientAddress = "0x..."
let baseNetworkName:  = "polygon"

let bitcoinTxId = await sdk.wrap(polygonRecipientAddress, amountInBTC,networkName)

Signed wrapAndSwap (Bitcoin -> EVM)

This function enables swapping BTC on Bitcoin for tokens on EVM networks.

// You need to provide the relevant exchange information

// The exchange token address is the address of the token on the target chain
let amountInBTC = 0.001
let evmAddress = "0x..."
let networkName = "ethereum"

let exchangeTokenAddress = "0x..."
const response = await sdk.wrapAndSwap(evmAddress, amountInBTC, exchangeTokenAddress, networkName)

Signed unwrap (Base network -> Bitcoin)

This function enables unwrapping TELEBTC on base networks to receive BTC in return.

let amountInBTC = 0.001
let recipientBitcoinAddress = "..."
let baseNetworkName = "polygon"

let response = await sdk.unwrap(amountInBTC, recipientBitcoinAddress, baseNetworkName)

Signed swapAndUnwrap (EVM -> Bitcoin)

This function enables swapping EVM tokens to receive BTC in return.

let recipientBitcoinAddress = "..."
let exchangeInfo = {
  inputToken: "Token Contract Address",
  inputAmount: 50 * 1e18, // for example (50 WMatic)
}
let network = "optimism"
const minimumExpectedBTCAmount = "0"

let response = await sdk.swapAndUnwrap(
  exchangeInfo,
  recipientBitcoinAddress,
  network,
  minimumExpectedBTCAmount,
)

Examples

For more information, please check the example.