rubic-sdk

Rubic SDK

API Documentation

Latest API Documentation

Installation

Installation with cdn

<script src="https://unpkg.com/rubic-sdk@latest/dist/rubic-sdk.min.js"></script>

Installation with npm and webpack (React, ...)

• npm install rubic-sdk

ℹ️️ Skip the rest of the steps if your have already installed web3 in your project.

• npm install --save-dev http-browserify https-browserify stream-browserify crypto-browserify
• modify webpack.config.js. If you use create-react-app, run npm run eject to extract config
  • add to plugins

    new webpack.ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
      process: 'process/browser'
    })
    

  • add resolve.fallback

    "fallback": {
      "fs": false,
      "constants": false,
      "querystring": false,
      "url": false,
      "path": false,
      "os": false,
      "http": require.resolve("http-browserify"),
      "https": require.resolve("https-browserify"),
      "zlib": false,
      "stream": require.resolve("stream-browserify"),
      "crypto": require.resolve("crypto-browserify"),
      "zlib": require.resolve('browserify-zlib')
    }
    

Installation with npm for Angular

• npm install rubic-sdk

ℹ️️ Skip the rest of the steps if your have already installed web3 in your project.

• npm install --save-dev stream-browserify assert https-browserify os-browserify stream-http crypto-browserify process buffer
• Modify tsconfig.json

  {
    "compilerOptions": {
      ...
      "paths" : {
        ...
        "stream": ["./node_modules/stream-browserify"],
        "assert": ["./node_modules/assert"],
        "https": ["./node_modules/https-browserify"],
        "os": ["./node_modules/os-browserify"],
        "http": ["./node_modules/stream-http"],
        "crypto": ["./node_modules/crypto-browserify"]
    }
  }
  

• Modify polyfills.ts

  import Process = NodeJS.Process;
  
  export interface AppWindow extends Window {
    process: Process;
    Buffer: Buffer;
    global?: unknown;
  }
  
  (window as AppWindow).global = window;
  (window as AppWindow).process = window.process || require('process');
  (window as AppWindow).Buffer = (window as any).Buffer || require('buffer').Buffer;
  

Trades usage

Get started after cdn installation

 <script>
        // you have to declare rpc links only for networks you will use
        const configuration = {
            rpcProviders: {
                ETH: {
                    rpcList: ['<your ethereum rpc>']
                },
                BSC: {
                    rpcList: ['<your bsc rpc>']
                },
                ...
                TRON: {
                    rpcList: [
                      {
                        fullHost: '<tron-api>',
                        headers: { "TRON-PRO-API-KEY": 'your api key' }
                      }
                    ]
                }
            },
            // if you are whitelisted integrator, provide your wallet address here
           providerAddress: {
              [CHAIN_TYPE.EVM]: {
                 crossChain: '0x0000000000000000000000000000000000000000', // Address for cross chain fee
                 onChain: '0x0000000000000000000000000000000000000000' // Address for on chain fee
              }
           }
        }
        
        async function main() {
            // create SDK instance
            const sdk = await RubicSDK.SDK.createSDK(configuration);
            
            // define example trade parameters
            const blockchain = 'ETH';
            const fromTokenAddress = '0x0000000000000000000000000000000000000000';
            const fromAmount = 1;
            const toTokenAddress = '0xdac17f958d2ee523a2206206994597c13d831ec7';
            
            // calculate trades
            const trades = await sdk.onChainManager
                .calculateTrade({blockchain, address: fromTokenAddress}, fromAmount, toTokenAddress);
            
            console.log(trades);
        }
        main();
    </script>

Get started after npm installation

• Create configuration

  import { Configuration, BLOCKCHAIN_NAME } from 'rubic-sdk';
  
  // you have to declare rpc links only for networks you will use
  export const configuration: Configuration = {
      rpcProviders: {
          [BLOCKCHAIN_NAME.ETHEREUM]: {
              rpcList: ['<your ethereum rpc #1>', '<your ethereum rpc #2>', ...]
          },
          [BLOCKCHAIN_NAME.BINANCE_SMART_CHAIN]: {
              rpcList: ['<your bsc rpc>']
          },
          ...
          [BLOCKCHAIN_NAME.TRON]: {
              rpcList: [
                  {
                      fullHost: '<tron api>',
                      headers: { "TRON-PRO-API-KEY": 'your api key' }
                  }
              ]
          }
      },
      // if you are whitelisted integrator, provide your wallet address here
      providerAddress: {
            [CHAIN_TYPE.EVM]: {
               crossChain: '0x0000000000000000000000000000000000000000', // Address for cross chain fee
               onChain: '0x0000000000000000000000000000000000000000' // Address for on chain fee
            }
      }
  }
  

• Create sdk instance

  import { SDK } from 'rubic-sdk';
  
  const sdk = await SDK.createSDK(configuration);
  

• Use sdk instance for trade calculation

  import { BLOCKCHAIN_NAME, TradeType, OnChainTrade, EvmOnChainTrade } from 'rubic-sdk';
  
  const blockchain = BLOCKCHAIN_NAME.ETHEREUM;
  const fromTokenAddress = '0x0000000000000000000000000000000000000000'; // ETH
  const fromAmount = 1;
  const toTokenAddress = '0xdac17f958d2ee523a2206206994597c13d831ec7'; // USDT
  
  const trades = await sdk.onChainManager.calculateTrade(
      { blockchain, address: fromTokenAddress }, 
      fromAmount,
      toTokenAddress
  );
  const bestTrade = trades[0];
  
  trades.forEach(trade => {
      const tradeType: TradeType = trade.type;
      console.log(`trade type: ${tradeType}`);
  
      if (trade instanceof OnChainTrade) {
          console.log(`to amount: ${trade.to.tokenAmount.toFormat(3)}`);
      } else {
         console.log(`error: ${trade.error}`);
      }
      
      // explore trades info
      if (trade instanceof EvmOnChainTrade) {
          console.log(`Gas fee: ${bestTrade.gasFeeInfo}`);
      }
      ...
  });
  

• When user connects wallet (e.g. MetaMask) you should change configuration to use trade swap method.
  ⚠️ Recalculate trades after this.

  import { WalletProvider, CHAIN_TYPE, Configuration } from 'rubic-sdk';
  
  const walletProvider: WalletProvider = {
      [CHAIN_TYPE.EVM]: {
          address: '0x123...', // user wallet address
          core: window.ethereum
      },
      [CHAIN_TYPE.TRON]: {
          address: 'T123...', // user wallet address
          core: window.tronLink.tronWeb // or window.tronWeb
      }
  };
  
  // initial configuration example
  const configuration: Configuration = {
      ...
      walletProvider
  }
  const sdk = await SDK.createSDK(configuration);
  
  // after user's wallet address changed
  // Example #1: 
  sdk.updateWalletProvider(walletProvider);
  
  // Example #2:
  sdk.updateWalletAddress(CHAIN_TYPE.EVM, address);
  
  

• Now you can use swap method of trade instance. Approve transaction will be sent automatically if needed.

  const onConfirm = (hash: string) => console.log(hash);
  
  // check that trade is defined
  сonst bestTrade = trades[0];
  const receipt = await bestTrade.swap({ onConfirm });
  

Get started with cross-chain swaps

Steps 1. and 2. are the same. You can use single sdk instance for on-chain trades and cross-chain swaps calculations.

• Use sdk instance for trade calculation

  import { BLOCKCHAIN_NAME } from 'rubic-sdk'; 
  import { EvmCrossChainTrade } from "./evm-cross-chain-trade";
  
  const fromBlockchain = BLOCKCHAIN_NAME.ETHEREUM;
  const fromTokenAddress = '0x0000000000000000000000000000000000000000'; // ETH
  const fromAmount = 1;
  const toBlockchain = BLOCKCHAIN_NAME.BINANCE_SMART_CHAIN;
  const toTokenAddress = '0xe9e7cea3dedca5984780bafc599bd69add087d56'; // BUSD
  
  const wrappedTrades = await sdk.crossChainManager.calculateTrade(
      { blockchain: fromBlockchain, address: fromTokenAddress }, 
      fromAmount,
      { blockchain: toBlockchain, address: toTokenAddress }
  );
  
  wrappedTrades.forEach(wrappedTrade => {
      const tradeType: TradeType = wrappedTrade.type;
      console.log(`trade type: ${tradeType}`);
      
      if (wrappedTrade.error) {
          console.log(`error: ${wrappedTrade.error}`);
      } else {
          const trade = wrappedTrade.trade!;
          console.log(`to amount: ${trade.to.tokenAmount.toFormat(3)}`);
  
          // explore trades info
          if (trade instanceof EvmCrossChainTrade) {
              console.log(trade.gasData)
          }
          ...
      }
  }) 
  

• Same as in on-chain.

• Now you can use swap method of trade instance. Approve transaction will be sent automatically if needed.

  const onConfirm = (hash: string) => console.log(hash);
  
  // check, that trade is defined
  const bestTrade = wrappedTrades[0].trade;
  const receipt = await bestTrade.swap({ onConfirm });
  

Token classes

You can use specific sdk Token classes to work with tokens.

Token

import { BLOCKCHAIN_NAME } from 'rubic-sdk';

const token: Token = await Token.createToken({ 
    blockchain: BLOCKCHAIN_NAME.ETHEREUM,
    address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
});

console.log(token.symbol); // USDT
console.log(token.name); // Tether USD
console.log(token.decimals); // 6

You can also use constructor directly.

import { BLOCKCHAIN_NAME } from 'rubic-sdk';

const token = new Token({
   blockchain: BLOCKCHAIN_NAME.ETHEREUM,
   address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
   name: 'USD Coin',
   symbol: 'USDC',
   decimals: 6
})

PriceToken

import { BLOCKCHAIN_NAME } from 'rubic-sdk';

const token: PriceToken = await PriceToken.createToken({ 
    blockchain: BLOCKCHAIN_NAME.ETHEREUM,
    address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
});

console.log(token.price);

PriceTokenAmount

import { BLOCKCHAIN_NAME } from 'rubic-sdk';

const token: PriceTokenAmount = await PriceTokenAmount.createToken({ 
    blockchain: BLOCKCHAIN_NAME.ETHEREUM,
    address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
    tokenAmount: new BigNumber(1)
});

console.log(token.weiAmount);