# Rubic SDK
## API Documentation
[Latest API Documentation](https://cryptorubic.github.io/rubic-sdk)
## Installation
### Installation with cdn
```html
```
### Installation with npm and webpack (React, ...)
1. `npm install rubic-sdk`
ℹ️️ Skip the rest of the steps if your have already installed [web3](https://github.com/ChainSafe/web3.js) in your project.
2. `npm install --save-dev http-browserify https-browserify stream-browserify crypto-browserify`
3. modify webpack.config.js. If you use create-react-app, run `npm run eject` to extract config
1. add to `plugins`
```javascript
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'],
process: 'process/browser'
})
```
2. add `resolve.fallback`
```json
"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
1. `npm install rubic-sdk`
ℹ️️ Skip the rest of the steps if your have already installed [web3](https://github.com/ChainSafe/web3.js) in your project.
2. `npm install --save-dev stream-browserify assert https-browserify os-browserify stream-http crypto-browserify process buffer`
3. Modify tsconfig.json
```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"]
}
}
```
4. Modify polyfills.ts
```typescript
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
```html
```
### Get started after npm installation
1. Create configuration
```typescript
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: ['', '', ...]
},
[BLOCKCHAIN_NAME.BINANCE_SMART_CHAIN]: {
rpcList: ['']
},
...
[BLOCKCHAIN_NAME.TRON]: {
rpcList: [
{
fullHost: '',
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
}
}
}
```
2. Create sdk instance
```typescript
import { SDK } from 'rubic-sdk';
const sdk = await SDK.createSDK(configuration);
```
3. Use sdk instance for trade calculation
```typescript
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}`);
}
...
});
```
4. When user connects wallet (e.g. MetaMask) you should change configuration to use trade `swap` method.
**⚠️ Recalculate trades after this**.
```typescript
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);
```
5. Now you can use `swap` method of trade instance. Approve transaction will be sent automatically if needed.
```typescript
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.
3. Use sdk instance for trade calculation
```typescript
import { BLOCKCHAIN_NAME } from 'rubic-sdk';
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)
}
...
}
})
```
4. Same as in on-chain.
5. Now you can use `swap` method of trade instance. Approve transaction will be sent automatically if needed.
```typescript
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
```typescript
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.
```typescript
import { BLOCKCHAIN_NAME } from 'rubic-sdk';
const token = new Token({
blockchain: BLOCKCHAIN_NAME.ETHEREUM,
address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
name: 'USD Coin',
symbol: 'USDC',
decimals: 6
})
```
### PriceToken
```typescript
import { BLOCKCHAIN_NAME } from 'rubic-sdk';
const token: PriceToken = await PriceToken.createToken({
blockchain: BLOCKCHAIN_NAME.ETHEREUM,
address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
});
console.log(token.price);
```
### PriceTokenAmount
```typescript
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);
```