⚙️JS SDK

Orbiter SDK Document

🌕 Overview

• The Orbiter SDK package provides a simplest, out-of-the-box approach to access the Orbiter API to find and execute the best on-chain and cross-chain swapping and bridging.

• For more information about API, please see page: Orbiter REST API.

📦 Installation

You can use following ways to get the latest version of Orbiter SDK.

• npm

  npm install @orbiter-finance/bridge-sdk

• yarn

  yarn add @orbiter-finance/bridge-sdk

• pnpm

  pnpm add @orbiter-finance/bridge-sdk

Feel free to report if you encounter any problems.

👾 Quick Start

• Set up the SDK

  import {  OrbiterClient, ENDPOINT } from "@orbiter-finance/bridge-sdk";
  const orbiter = await OrbiterClient.create({
    apiEndpoint: ENDPOINT.TESTNET,
    apiKey: 'xxxxxx', //optional
    channelId: 'xxxxxx' //optional
  });

• Check Available TradePair

  const chains: Chain[] = orbiter.getAllChains();
  
  // choose a chain from list to get availabletokens
  const chain: Chain = { 
    id: '11155111', 
    name: 'Sepolia' 
  };
  const tokens: Token[] = orbiter.getAvailableTokens(chain.id);
  
  // choose a chain and a token symbol to get available
  const token: Token = { 
    name: "ETH", 
    symbol: "ETH", 
    decimals: 18, 
    address: "0x0000000000000000000000000000000000000000", 
    isNative: true
  };
  const tradePairs: TradePair[] = orbiter.getAvailableTradePairs(chain.id, token.symbol);
  
  // or directly get all available trade pair
  
  const tradePairs: TradePair[] = getAllTradePairs();

  💡Tips:

  • For tradePairs that source chain is EVM type may have 2 kind of router, both EOA and CONTRACT.

  • For tradePairs that source chain is Starknet and TRON only has CONTRACT router.

  • For other tardePairs only has EAO router.

• Create Router and Send Transaction

  From EVM Chains

  import { Wallet, JsonRpcProvider } from "ethers";
  
  // choose a tradePair to create router
  const tradePair: TradePair = {
    srcChainId: '11155111',
    dstChainId: '421614',
    srcTokenSymbol: 'ETH',
    dstTokenSymbol: 'ETH',
    routerType: RouterType.EOA
  }
  const router = orbiter.createRouter(tradePair);
  
  // check min and max value
  const min = router.getMinSendValue();
  const max = router.getMaxSendValue();
  
  // simulationAmount
  const { sendValue, receiveValue } = router.simulationAmount(min);
  
  // connect wallet
  const provider = new JsonRpcProvider('https://ethereum-sepolia-rpc.publicnode.com');
  const wallet = new Wallet('privateKey', provider);
  // check if balance sufficient
  const balance = (await provider.getBalance(wallet)).toString();
  
  // if is erc20 token, need approve
  // const approve = await router.createApprove(account.address, sendValue);
  // const approveResponce = await wallet.sendTransaction(approve);
  // const approveReceipt = await approveRes.wait();
  
  // create transaction
  const transaction = router.createTransaction(wallet.address, 'receiver', sendValue);
  // send transaction
  const transactionResponce = await wallet.sendTransaction(transaction);
  const transactionReceipt = await transferResponce.wait();
  

  From BTC Chains

  import * as bitcoin from 'bitcoinjs-lib'
  import * as ecc from 'tiny-secp256k1';
  import { ECPairFactory, networks } from 'ecpair';
  
  // choose a tradePair to create router
  const tradePair: TradePair = {
    srcChainId: 'FRACTAL_TEST',
    dstChainId: '11155111',
    srcTokenSymbol: 'BTC',
    dstTokenSymbol: 'BTC',
    routerType: RouterType.EOA
  }
  const router = orbiter.createRouter(tradePair);
  
  // check min and max value
  const min = router.getMinSendValue();
  const max = router.getMaxSendValue();
  
  // simulationAmount
  const { sendValue, receiveValue } = router.simulationAmount(min);
  
  // creat payment
  const network = networks.bitcoin;
  const ECPair = ECPairFactory(ecc); 
  const keyPair = ECPair.fromWIF(btcPrivateKey, network);
  const payment = bitcoin.payments.p2wpkh({
    pubkey: keyPair.publicKey,
    network,
  });
  
  // create transaction and add output
  const psbt = await router.createTransaction(payment.address, 'receiver', sendValue);
  expect(psbt).toBeDefined();
  
  // get utxos from chain
  const utxos = ...
  
  // add inputs
  const script = payment.output;
  utxos.forEach((utxo: any) => {
    const inputData = {
      hash: utxo.txid, 
      index: utxo.vout,
      witnessUtxo: {
        script, 
        value: utxo.satoshi
      },
    }
    psbt.addInput(inputData);
  });
  
  // estimate fee from oracle or explorer
  const fee = ...
  
  // add change !!!important!!!
  const change = totalAmount - Number(sendValue) - fee;
  if (change > 0) {
    psbt.addOutput({
      script,
      value: change
    });
  }
  
  // sign inputs
  for (let i = 0; i < psbt.inputCount; i++) {
    psbt.signInput(i, keyPair);
    psbt.validateSignaturesOfInput(i, (
      pubkey: Buffer,
      msghash: Buffer,
      signature: Buffer,
    ) => ECPair.fromPublicKey(pubkey).verify(msghash, signature));
  }
  psbt.finalizeAllInputs();
  
  // broadcast
  const broadcastResult = ...
  

  From Tron Chains

  import { TronWeb } from 'tronweb';
  
  // choose a tradePair to create router
  const tradePair: TradePair = {
    srcChainId: '3448148188',
    dstChainId: '11155111',
    srcTokenSymbol: 'JST',
    dstTokenSymbol: 'JST',
    routerType: RouterType.CONTRACT
  }
  const router = orbiter.createRouter(tradePair);
  
  // check min and max value
  const min = router.getMinSendValue();
  const max = router.getMaxSendValue();
  
  // simulationAmount
  const { sendValue, receiveValue } = router.simulationAmount(min);
  
  
  // connect to tronweb
  const tronWeb = new TronWeb({
    fullHost: 'https://nile.trongrid.io',
    headers: { "TRON-PRO-API-KEY": 'API key' },
    privateKey: 'privateKey'
  })
  
  // create approve
  const approve = await router.createApprove(address, sendValue);
  // sign and send approve
  const signedApprove = await tronWeb.trx.sign(approve.transaction);
  const approveRes = await tronWeb.trx.sendRawTransaction(signedApprove);
  
  // create transaction
  const transaction = await router.createTransaction(address, evmAddress, sendValue);
  // sign and send transaction
  const signedTransaction = await tronWeb.trx.sign(transaction.transaction);
  const transferRes = await tronWeb.trx.sendRawTransaction(signedTransaction);
  

  From Starknet Chains

  import { Account, Provider, constants, } from 'starknet';
  
  // choose a tradePair to create router
  const tradePair: TradePair = {
    srcChainId: 'SN_SEPOLIA',
    dstChainId: '11155111',
    srcTokenSymbol: 'ETH',
    dstTokenSymbol: 'ETH',
    routerType: RouterType.CONTRACT
  }
  const router = orbiter.createRouter(tradePair);
  
  // check min and max value
  const min = router.getMinSendValue();
  const max = router.getMaxSendValue();
  
  // simulationAmount
  const { sendValue, receiveValue } = router.simulationAmount(min);
  
  // connect account
  const provider = new Provider({ nodeUrl: constants.NetworkName.SN_SEPOLIA });
  const account = new Account(provider, starknetAddress, privateKey);
  
  // create approve
  const approve = await router.createApprove(account.address, sendValue);
  
  // create transaction
  const transaction = router.createTransaction(wallet.address, 'receiver', sendValue);
  
  // send approve and transaction
  const transactionResponce = await account.execute([approve,transaction]);
  const transactionReceipt = await provider.waitForTransaction(transactionResponce.transaction_hash);
  

  From Solana Chains

  import bs58 from "bs58"
  import { Connection, Keypair, TransactionMessage, VersionedTransaction, LAMPORTS_PER_SOL } from '@solana/web3.js'
  
  // choose a tradePair to create router
  const tradePair: TradePair = {
    srcChainId: 'SOLANA_DEV',
    dstChainId: '11155111',
    srcTokenSymbol: 'USDC',
    dstTokenSymbol: 'USDC',
    routerType: RouterType.EOA
  }
  const router = orbiter.createRouter(tradePair);
  
  // check min and max value
  const min = router.getMinSendValue();
  const max = router.getMaxSendValue();
  
  // simulationAmount
  const { sendValue, receiveValue } = router.simulationAmount(min);
  
  // connect wallet
  const connection = new Connection('solana-endpoint', "confirmed");
  const sender = Keypair.fromSecretKey(bs58.decode('privateKey'));
  
  // create transaction
  const transfers = await router.createTransaction(sender.publicKey.toString(), 'receiver', sendValue);
  
  // process transaction
  const blockhash = await connection.getLatestBlockhash();
  const messageV0 = new TransactionMessage({
    payerKey: sender.publicKey,
    recentBlockhash: blockhash.blockhash,
    instructions: [...transfers],
  }).compileToV0Message();
  const transaction = new VersionedTransaction(messageV0);
  transaction.sign([sender]);
  const serializedTransaction = Buffer.from(transaction.serialize());
  
  // send transaction
  const signature = await connection.sendRawTransaction(
    serializedTransaction
  );
  
  //check transaction status
  const status = await connection.getSignatureStatus(signature, {
    searchTransactionHistory: false,
  });
  

  💡Tips:

  • The function [createTransfer] will return deferent type of transfer structure which depends on source chain type, for EVM it will be TransactionRequest, for BTC will be a PSBT for Starknet will be Call, etc. For more information please see their official document.

• Check Bridge Status

  const transactionStatus = await orbiter.checkTransactionStatus(hash);

• Check User Opoints and Transaction History

  // get user Opoints
  const opoints = await orbiter.getUserOpoint(wallet.address);
  
  // get user transaction history
  const history = await orbiter.getTransactionHistory(wallet.address, 0);

  💡Tips:

  • For structure of result on these two function, please check Orbiter REST API.