🛠
Symbiosis JS SDK
Symbiosis JS SDK intro, Quick Start, repository
Currently, we support two versions of the Symbiosis protocol: V1 and V2, to allow our liquidity providers and integrators to shift from V1 to V2 smoothly.
Please use this JS SDK to integrate with Symbiosis protocol V2.
Symbiosis JS SDK was created to provide access to the functionalities of the Symbiosis protocol. Symbiosis JS SDK is our primary tool to build our own desktop application: Symbiosis WebApp (Mainnet). The application can be used as a reference for existing functionalities. Also, we have Symbiosis WebApp on Testnet; it can be a little bit behind Symbiosis WebApp on Mainnet.
Checklist to do before deploying to production (Mainnet)
If any of these checks fail, you put the assets of your users at risk. Thus, you must not go to Mainnet with real assets and real users. This can result in the loss of your users' assets.
- 1.You approve users’ ERC20 tokens only for one contract and this contract is
metaRouterGatewayon each blockchain. You can check contracts’ addresses for all blockchains supported by Symbiosis protocol V2 in this configuration. - 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.You do not modify, reuse, or cash the calldata you get by calling methods of Symbiosis SDKs and API.
- 4.After deployment to Mainnet, run at least one transaction.
Please do these checks for the initial deployment AND every 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:
- Perform cross-chain operations:
- Interchain communicating (any token to a third-party lending protocol) Explanation of interchain communicating
- Cross-chain zapping (any token to a liquidity pool owned by Symbiosis) Explanation of cross-chain zapping
- Get statuses of cross-chain operations,
- Get a list of stuck cross-chain operations,
- Generate calldata to perform reverting operation.
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 composing your own list of supported tokens if you need it.
The most crucial parts for understanding the Symbiosis Protocol are:
- 1.Install Symbiosis JS SDK:
npm i symbiosis-js-sdk
2. Install dependencies:
npm i
3. Run tests:
npm run test
npm version major|minor|patch
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 allows you to swap stable cryptocurrencies between blockchains. Please 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)
A combination of UNI-like DEXes or 1inch 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.
// 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)
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.
import { getPendingRequests } from 'symbiosis-sdk'
// Get pending requests
const pendingRequests = await getPendingRequests(
address // Address
)
// 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()
Last modified 11d ago