Links
🛠

Symbiosis JS SDK

Symbiosis JS SDK intro, Quick Start, repository
Please use this JS SDK to integrate with Symbiosis protocol V2.
Check out the new features of Symbiosis protocol V2: Symbiosis V1 vs. Symbiosis V2

What is Symbiosis JS SDK

Symbiosis JS SDK is designed to provide access to the functionalities of the Symbiosis protocol. We use Symbiosis JS SDK to build our own desktop application: Symbiosis WebApp. The application can be used as a reference for existing functionalities.
Checklist to do before deploying to production (Mainnet)
If any of these checks fail, you put the assets of your users at risk. Therefore, you must not go to Mainnet with real assets and real users. This could result in the loss of your users' assets.
  1. 1.
    You approve users’ ERC20 tokens only for one contract, and this contract is metaRouterGateway on each blockchain. You can check the addresses of the contracts for all blockchains supported by Symbiosis protocol V2 in this configuration.
  2. 2.
    All contracts you use in your software exist on the corresponding blockchains, and their addresses on each blockchain correspond to the addresses in this configuration.
  3. 3.
    You do not modify, reuse, or cash the calldata you get by calling methods of the Symbiosis SDKs and API.
  4. 4.
    After deployment to Mainnet, run at least one transaction.
Please do these checks for the initial deployment AND each software update.
Using Symbiosis JS SDK, you can integrate and use the functionalities of the Symbiosis Protocol within your application, platform, protocol. And then, your users will be able to:
These functionalities are available on the blockchains supported by the Symbiosis protocol. The list of supported blockchains is growing and can be found here: Supported Blockchains
We do not have any restrictions on the tokens to operate. You may consider creating your own list of supported tokens if you need to.
The most crucial parts for understanding the Symbiosis protocol are:
Looking for API? It's right here: Symbiosis API

Dependencies

Quick start

Installation

  1. 1.
    Install Symbiosis JS SDK:
npm i symbiosis-js-sdk
2. Install dependencies:
npm i
3. Run tests:
npm run test

Version Upgrade

To upgrade versions, use the npm versions command:
npm version major|minor|patch

Initillasing JS SDK

To work with Symbiosis SDK you should init Symbiosis instance with config (check Config type here: JS SDK Types).
import { Symbiosis } from 'symbiosis-sdk'
import { CONFIG } from '@app/lib/config'
export const symbiosis = new Symbiosis('mainnet', CLIENT_ID)
CLIENT_ID is a unique string that identifies your project. For example, awesome-app, partner-name. That is, any string of your choice.

Bridging

Bridging allows you to swap stablecoins between blockchains. Refer to JS SDK Types for the definitions of the types.
// Create a new Bridging instance
const bridging = symbiosis.newBridging()
// Calculate the fee for bridging and get an execute function
const { execute, fee, tokenAmountOut } = await bridging.exactIn(
amountIn, // TokenAmount object
tokenOut, // Token object
address, // address
revertableAddress, //
signer // ethers Signer instance to sign transaction
)
// Execute the transaction
const { response, waitForMined } = await execute()
// Wait for transaction to be mined
const { receipt, waitForComplete } = await waitForMined()
// Wait for transaction to be completed on recipient chain
const log = await waitForComplete()
Send a bridging transaction manually (the stateless mode, JS SDK v2.3)
const bridging = symbiosis.newBridging()
// transactionRequest contains everything you need to send a transaction by yourself
const { transactionRequest } = await bridging.exactIn(...)
// Send the transaction and get a receipt
const receipt = ...
// Wait for the transaction to be completed on the destination chain
const log = await bridging.waitForComplete(receipt)

Swapping

A combination of UNI-like DEXes, 1inch or OpenOcean and bridging allows you to perform cross-chain swaps of any supported tokens between networks. Please refer to JS SDK Types for the definitions of the types.
You can find examples of swaps here
// Create a new Swapping instance
const swapping = symbiosis.newSwapping()
// Calculate the fee for bridging between networks and get an execute function
const { execute, fee, tokenAmountOut, route, priceImpact } = await swapping.exactIn(
tokenAmountIn, // TokenAmount object
tokenOut, // Token object
from, // the sender's address
to, // the recipient's address
revertableAddress, //
signer, // a Signer instance to sign transaction
slippage, // slippage
deadline // the trade deadline in seconds
)
// Execute the transaction
const { response, waitForMined } = await execute()
// Wait for the transaction to be mined
const { receipt, waitForComplete } = await waitForMined()
// Wait for the transaction to be completed on the recipient chain
const log = await waitForComplete()
Send a swapping transaction manually (the stateless mode, JS SDK v2.3)
const swapping = symbiosis.newSwapping()
// transactionRequest contains everything you need to send a transaction by yourself
const { transactionRequest } = await swapping.exactIn(...)
// Send the transaction and get a receipt
const receipt = ...
// Wait for the transaction to be completed on the destination chain
const log = await swapping.waitForComplete(receipt)

Reverting Stuck (pending) Transactions

A cross-chain swap may get stuck due to multiple reasons. For example, this could happen if you set a small fee, send an invalid calldata, or the deadline for the trade is too short.
Such requests can be found and reverted.

Find stuck transactions:

import { getPendingRequests } from 'symbiosis-sdk'
// Get pending requests
const pendingRequests = await getPendingRequests(
address // Address
)

Revert stuck transaction:

// Create RevertPending instance
const revertPending = symbiosis.newRevertPending({
chainId, // Receiver Chain ID
internalId, // The internal ID of the request
otherChainId, // Sender Chain ID
type, // Type of transaction ('burn' or 'synthesize')
})
// Calculate the fee for the revert and get execute function
const { fee, execute } = await revertPending.revert()
// Execute the the transaction using signer
const { waitForMined } = await execute(signer)
// Wait for the transaction to be mined
const { receipt, waitForComplete } = await waitForMined()
// Wait for the transaction to be fully reverted on original sender chain
const log = await waitForComplete()
Send Revert transaction manually (stateless mode, since v2.3)
const revertPending = symbiosis.newRevertPending(request)
// transactionRequest contains everything you need to send a transaction by yourself
const { transactionRequest } = await revertPending.revert()
... // Send transaction
// Wait for transaction to be completed on recipient chain
const log = await revertPending.waitForComplete()

Repository