How to use Chainflip SDK

Chainflip JavaScript SDK

The Chainflip Javascript SDK provides a simple way for JavaScript/TypeScript developers to interact with the Chainflip protocol. In this guide we’ll explain how to:

Get chains & assets: Use the getChains and getAssets methods to retrieve information about the available chains and their respective assets.
Get quotes: The getQuote method provides a quote for a proposed swap. This includes the expected exchange rate, expected fees and expected duration.
Swap assets: There are two ways to initiate a swap on Chainflip:
1. Request a deposit address: The requestDepositAddress method generates a deposit address on the source chain. The user sends funds to this address to initiate a swap.
2. Trigger a vault swap: The encodeVaultSwapData method returns an unsigned transaction that encodes the details of the swap. The user signs and submits this transaction to initiate the swap.
Get status: The getStatus method provides real-time updates about the status of a swap operation.

If you want to learn more about how Chainflip swaps work, check the Swapping Basics section

Swap Assets using the SDK

There are two ways to initiate a swap on Chainflip. Both options are fire-and-forget - once the assets are sent to a deposit channel or the vault swap transaction is submitted, the user doesn’t need to do anything for the swap to take place.

Request a deposit address: The requestDepositAddress method generates a deposit address on the source chain. The user sends funds to this address to initiate a swap.
Trigger a vault swap: The encodeVaultSwapData method returns an unsigned transaction that encodes the details of the swap. The user signs and submits this transaction to initiate the swap.

Check How Swapping Works and Swapping Basics for more information about how Chainflip swaps work.

Installation

The Chainflip SDK is a npm package:


npm install --save @chainflip/sdk

Set up

To start using the Chainflip SDK, you’ll first need to create an instance with the appropriate options:


import { SwapSDK } from "@chainflip/sdk/swap";
import { Wallet } from "ethers";
 
const options = {
  network: "perseverance", // Testnet
  broker: { url: "https://my.broker.io" },
};
 
const swapSDK = new SwapSDK(options);

The options object accepts the following properties:

Param	Description	Data type
`network`(optional)	The Chainflip network to interact with. Defaults to `perseverance`.	`'sisyphos' \| 'perseverance' \| 'mainnet'`
`backendServiceUrl`(optional)	The URL of the backend service . Defaults to the backend service run by Chainflip for the given network.	`string`
`broker`(optional)	The URL of the Broker API used for initiating swaps. Defaults to the Broker API run by Chainflip for the given network.	`{ url: string }`
`rpcUrl`(optional)	The URL of the Chainflip RPC node. Defaults to the public rpc node operated by Chainflip for the given network.	`String`
`enabledFeatures`(optional)	Features that must be explicitly opted into.	`{ dca?: boolean }`

Working Examples

Swap ETH to BTC via deposit channel


import { SwapSDK, Chains, Assets } from "@chainflip/sdk/swap";
 
// Initialize SDK
const swapSDK = new SwapSDK({
  network: "perseverance",
  enabledFeatures: { dca: true },
});
 
// Fetch quotes for swap
const { quotes } = await swapSDK.getQuoteV2({
  srcChain: Chains.Ethereum,
  srcAsset: Assets.ETH,
  destChain: Chains.Bitcoin,
  destAsset: Assets.BTC,
  amount: (0.1e18).toString(), // 0.1 ETH
});
 
// Find regular quote
const quote = quotes.find((quote) => quote.type === "REGULAR");
console.log("quote", quote);
 
// Request deposit address for swap
const depositAddress = await swapSDK.requestDepositAddressV2({
  quote,
  destAddress: "tb1p8p3xsgaeltylmvyrskt3mup5x7lznyrh7vu2jvvk7mn8mhm6clksl5k0sm",
  fillOrKillParams: {
    refundAddress: "0xa56A6be23b6Cf39D9448FF6e897C29c41c8fbDFF", // address to which assets are refunded
    retryDurationBlocks: 100, // 100 blocks * 6 seconds = 10 minutes before deposits are refunded
    slippageTolerancePercent: quote.recommendedSlippageTolerancePercent, // use recommended slippage tolerance from quote
    livePriceSlippageTolerancePercent:
      quote.recommendedLivePriceSlippageTolerancePercent, // use recommended live price slippage tolerance from quote
  },
});
console.log("depositAddress", depositAddress);
 
// Fetch swap status
const status = await swapSDK.getStatusV2({
  id: depositAddress.depositChannelId,
});
console.log("status", status);

Swap ETH to BTC via Vault swap


import { SwapSDK, Chains, Assets } from "@chainflip/sdk/swap";
import { getDefaultProvider, Wallet } from "ethers";
 
// Initialize SDK and Wallet
const swapSDK = new SwapSDK({
  network: "perseverance",
  enabledFeatures: { dca: true },
});
const wallet = new Wallet(
  process.env.SECRET_KEY,
  getDefaultProvider("sepolia")
);
 
// Fetch quote for swap
const { quotes } = await swapSDK.getQuoteV2({
  srcChain: Chains.Ethereum,
  srcAsset: Assets.ETH,
  destChain: Chains.Bitcoin,
  destAsset: Assets.BTC,
  isVaultSwap: true,
  amount: (0.1e18).toString(), // 0.1 ETH
});
 
// Find regular quote
const quote = quotes.find((quote) => quote.type === "REGULAR");
console.log("quote", quote);
 
// Encode vault swap transaction data
const transactionData = await swapSDK.encodeVaultSwapData({
  quote,
  srcAddress: wallet.address,
  destAddress: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
  fillOrKillParams: {
    refundAddress: wallet.address,
    retryDurationBlocks: 100,
    slippageTolerancePercent: quote.recommendedSlippageTolerancePercent,
    livePriceSlippageTolerancePercent:
      quote.recommendedLivePriceSlippageTolerancePercent,
  },
});
console.log("transactionData", transactionData);
 
// Sign and submit swap transaction
const transaction = await wallet.sendTransaction({
  to: transactionData.to,
  data: transactionData.calldata,
  value: transactionData.value,
});
const receipt = await transaction.wait(); // wait for transaction to be included in a block
console.log("receipt", receipt);
 
// Fetch swap status
const status = await swapSDK.getStatusV2({
  id: receipt.hash,
});
console.log("status", status);

Swap BTC to ETH with Cross-Chain Message


import { SwapSDK, Chains, Assets } from "@chainflip/sdk/swap";
 
// Initialize SDK
const swapSDK = new SwapSDK({
  network: "perseverance",
  enabledFeatures: { dca: true },
});
 
// Fetch quote for swap
const { quotes } = await swapSDK.getQuoteV2({
  srcChain: Chains.Bitcoin,
  srcAsset: Assets.BTC,
  destChain: Chains.Ethereum,
  destAsset: Assets.ETH,
  amount: (0.05e8).toString(), // 0.05 BTC
  // These values can be an estimation and don't need to exactly
  // match the values provided to requestDepositAddressV2.
  ccmParams: {
    messageLengthBytes: 4,
    gasBudget: (125000).toString(),
  },
});
 
// Find dca quote
const quote = quotes.find((quote) => quote.type === "DCA");
console.log("quote", quote);
 
// Request deposit address for swap
const depositAddress = await swapSDK.requestDepositAddressV2({
  quote,
  destAddress: "0xFcd3C82b154CB4717Ac98718D0Fd13EEBA3D2754",
  fillOrKillParams: {
    refundAddress:
      "tb1p8p3xsgaeltylmvyrskt3mup5x7lznyrh7vu2jvvk7mn8mhm6clksl5k0sm",
    retryDurationBlocks: 100,
    slippageTolerancePercent: quote.recommendedSlippageTolerancePercent,
    livePriceSlippageTolerancePercent:
      quote.recommendedLivePriceSlippageTolerancePercent,
  },
  ccmParams: {
    message: "0xdeadc0de",
    gasBudget: (125000).toString(),
  },
});
console.log("depositAddress", depositAddress);
 
// Fetch swap status
const status = await swapSDK.getStatusV2({
  id: depositAddress.depositChannelId,
});
console.log("status", status);

Support

If you are experiencing issues with the SDK, visit the #technical-discussion channel in Discord for assistance. Not in Discord yet? Join us .