🟧
JS SDK Quick Start

What is JS SDK?

Symbiosis JS SDK is designed to integrate the Symbiosis protocol into external applications.
Please refer to Symbiosis documentation for how the Symbiosis protocol works and to Glossary for definitions of the terms used in this space.

Dependencies

Quick start

Installation

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

Version Upgrade

To upgrade versions, please use the npm versions command:
1
npm version major|minor|patch
Copied!

Initillasing JS SDK

To work with Symbiosis SDK you should init Symbiosis instance with config (check Config type here: JS SDK Types).
1
import { Symbiosis } from 'symbiosis-sdk'
2
import { CONFIG } from '@app/lib/config'
3
export const symbiosis = new Symbiosis({
4
chains: [{ ... }], // the array of used RPC and contract addresses on that chains
5
advisor: { url: 'https://...' }, // an url of advisor service
6
maxSwapAmountInUsd: ..., // the max amount of swap in USD
7
minSwapAmountInUsd: ..., // the min amount of swap in USD
8
})
Copied!

Bridging

Bridging allows you to swap stable cryptocurrencies between blockchains. Please refer to JS SDK Types for the definitions of the types.
1
// Create a new Bridging instance
2
const bridging = symbiosis.newBridging()
3
// Calculate the fee for bridging and get an execute function
4
const { execute, fee, tokenAmountOut } = await bridging.exactIn(
5
amountIn, // TokenAmount object
6
tokenOut, // Token object
7
address, // address
8
revertableAddress, //
9
signer // ethers Signer instance to sign transaction
10
)
11
// Execute the transaction
12
const { response, waitForMined } = await execute()
13
// Wait for transaction to be mined
14
const { receipt, waitForComplete } = await waitForMined()
15
// Wait for transaction to be completed on recipient chain
16
const log = await waitForComplete()
Copied!
Send a bridging transaction manually (the stateless mode, JS SDK v2.3)
1
const bridging = symbiosis.newBridging()
2
​
3
// transactionRequest contains everything you need to send a transaction by yourself
4
const { transactionRequest } = await bridging.exactIn(...)
5
​
6
// Send the transaction and get a receipt
7
const receipt = ...
8
​
9
// Wait for the transaction to be completed on the destination chain
10
const log = await bridging.waitForComplete(receipt)
Copied!

Swapping

A combination of uniswap 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.
1
// Create a new Swapping instance
2
const swapping = symbiosis.newSwapping()
3
// Calculate the fee for bridging between networks and get an execute function
4
const { execute, fee, tokenAmountOut, route, priceImpact } = await swapping.exactIn(
5
tokenAmountIn, // TokenAmount object
6
tokenOut, // Token object
7
from, // the sender's address
8
to, // the recipient's address
9
revertableAddress, //
10
signer, // a Signer instance to sign transaction
11
slippage, // slippage
12
deadline // the trade deadline in seconds
13
)
14
// Execute the transaction
15
const { response, waitForMined } = await execute()
16
// Wait for the transaction to be mined
17
const { receipt, waitForComplete } = await waitForMined()
18
// Wait for the transaction to be completed on the recipient chain
19
const log = await waitForComplete()
Copied!
Send a swapping transaction manually (the stateless mode, JS SDK v2.3)
1
const swapping = symbiosis.newSwapping()
2
​
3
// transactionRequest contains everything you need to send a transaction by yourself
4
const { transactionRequest } = await swapping.exactIn(...)
5
​
6
// Send the transaction and get a receipt
7
const receipt = ...
8
​
9
// Wait for the transaction to be completed on the destination chain
10
const log = await swapping.waitForComplete(receipt)
Copied!

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:

1
import { getPendingRequests } from 'symbiosis-sdk'
2
// Get pending requests
3
const pendingRequests = await getPendingRequests(
4
address // Address
5
)
Copied!

Revert stuck transaction:

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

Repository