JS SDK Types

Symbiosis JS SDK Types

Checklist Before Going to Production (Mainnet)

Warning: 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. Approval of ERC20 Tokens: Always approve users' ERC20 tokens for only one contract — the metaRouterGateway — on each blockchain. Verify the contract addresses for all supported blockchains in this configuration.

2. Contract Existence and Address Validation: Ensure that the contracts used in your integration are deployed on the respective blockchains, and that their addresses on each blockchain match those listed in this configuration.

3. Handling of Calldata: Do not modify, reuse, or cache calldata retrieved from Symbiosis SDKs or API methods.

4. Testing: After deployment to Mainnet, conduct at least one cross-chain operation to ensure proper functionality.

Reminder: Perform this checklist during the initial deployment and after every software update.

Types

Symbiosis JS SDK defines the following types:

Type	Use
ChainId	Lists identifiers of supported blockchains.
ChainConfig	Defines the network configuration for building cross-chain routes.
OmniPoolConfig	Defines an Octopool containing sTokens. For more information on Octopools, see Symbiosis Octopools
AdvisorConfig and Config	Defines details of the Microservice Advisor. For more information on Advisor, seeSymbiosis & Fees
TokenConstructor	Specifies parameters for creating an instance of the Token class.
PendingRequestState and PendingRequest	Used for reverting stuck cross-chain operations.

ChainId type

The ChainId type lists named constants that represent integer identifiers for supported blockchains.

Example:

export enum ChainId {
    ETH_MAINNET = 1,
    ETH_RINKEBY = 4,
    ETH_GOERLI = 5,
    ETH_KOVAN = 42,
    BSC_MAINNET = 56,
    BSC_TESTNET = 97,
    MATIC_MAINNET = 137,
    MATIC_MUMBAI = 80001,
    AVAX_MAINNET = 43114,
    AVAX_TESTNET = 43113,
    HECO_MAINNET = 128,
    HECO_TESTNET = 256,
    OKEX_MAINNET = 66,
    OKEX_TESTNET = 65,
    BOBA_MAINNET = 288,
    BOBA_BNB = 56288,
    BOBA_AVALANCHE = 43288,
    BOBA_RINKEBY = 28,
    MILKOMEDA_MAINNET = 2001,
    MILKOMEDA_DEVNET = 200101,
    BTC_MAINNET = 5555,
    BTC_TESTNET = 55555,
    AURORA_MAINNET = 1313161554,
    AURORA_TESTNET = 1313161555,
    TELOS_MAINNET = 40,
    TELOS_TESTNET = 41,
}

ChainConfig type

The ChainConfig type defines the network configuration used to build cross-chain routes.

Example:

export type ChainConfig = {
    id: ChainId
    rpc: string
    dexFee: number
    filterBlockOffset: number
    stables: TokenConstructor[]
    metaRouter: string
    metaRouterGateway: string
    multicallRouter: string
    router: string
    bridge: string
    synthesis: string
    portal: string
    fabric: string
    waitForBlocksCount: number
}

Where:

Property	Description
id	The identifier of the blockchain.
rpc	The HTTP RPC endpoint of the blockchain. Used to retrieve information about liquidity pools' reserves for this blockchain.
dexFee	The liquidity provider fee for the selected DEX, expressed as an integer value. For example, 30 represents a fee of 0.3%.
filterBlockOffset	The range of blocks used to retrieve logs from the blockchain. Used for: Getting a list of stuck transactions. Checking the status of current cross-chain swap, bridging, or reverting operations.
stables	The list of stablecoins used to build cross-chain routes. This list should include at least one stablecoin of this blockchain and N sToken that connect this blockchain to others.
router	The address of a DEX router for this blockchain. For example, UniSwap for Ethereum.
metaRouter	The address of the Metarouter contract. ------------------ IMPORTANT: The metaRouter contract can only interact with ERC20 tokens approved by the metaRouterGateway contract. Do not approve ERC20 tokens directly for the metaRouter contract. ------------------ For more information, see Symbiosis Routing Contracts
metaRouterGateway	The address of the MetarouterGateway contract.
multicallRouterGateway	The address of the MulticallRouter contract.
bridge	The address of the BridgeV2 contract. ------------------ For more information, see Symbiosis Routing Contracts
synthesis	The address of the Synthesis contract. ------------------ For more information, see Symbiosis Routing Contracts
portal	The address of the Portal contract. ------------------ For more information, see Symbiosis Routing Contracts
fabric	The address of the Fabric contract that stores a list of {sToken <-> Token} pairs.
waitForBlocksCount	The number of blocks for the destination blockchain to wait for a transaction to be mined.

OmniPoolConfig type

The OmniPoolConfig type defines an Octopool.

Example:

export type OmniPoolConfig = {
    chainId: ChainId
    address: string
    oracle: string
}

AdvisorConfig and Config types

The AdvisorConfig and Config types define details of the Advisor service.

For more information on Advisor, see Symbiosis & Fees

AdvisorConfig type

This type contains the address of the Advisor service.

export type AdvisorConfig = {
    url: string
}

Config type

This type defines the configuration for the Advisor service.

export type Config = {
    advisor: AdvisorConfig
    chains: ChainConfig[]
    minSwapAmountInUsd: number
    maxSwapAmountInUsd: number
    omniPool: OmniPoolConfig
}

Property	Description
advisor	The configuration to access the Advisor service.
chains	The list of networks' configurations.
minSwapAmountInUsd	The minimum sum of cross-chain swap in the USD equivalent.
maxSwapAmountInUsd	The maximal sum of cross-chain swap in the USD equivalent.
omniPool	The Octopool config.

TokenConstructor type

The TokenConstructor type defines parameters for creating an instance of the Token class.

export type TokenConstructor = {
    name?: string
    symbol?: string
    address: string
    decimals: number
    chainId: ChainId
    isNative?: boolean
    isStable?: boolean
    chainFromId?: ChainId
    icons?: Icons
    userToken?: boolean
}

Where:

Property	Description
name	The full name of the cryptocurrency.
symbols	The ticker symbol of the cryptocurrency (e.g., BTC, ETH).
address	The cryptocurrency address.
decimals	The number of decimal places supported by the cryptocurrency.
isNative	A flag indicating whether the cryptocurrency is native to the blockchain or is an ERC20 token.
isStable	A flag indicating whether the cryptocurrency is a stablecoin used in cross-chain swaps.
chainFromId	The identifier of the blockchain network where the cryptocurrency (or sToken) originated.
icons	A list of icon URLs or paths associated with the cryptocurrency for UI purposes.
userToken	A flag indicating whether the cryptocurrency was manually added by a user.

Example:

export class Token {
   ....

    /**
     * Constructs an instance of the base class `Token`.
     * @param params TokenConstructor
     */
    constructor(params: TokenConstructor) {
        validateSolidityTypeInstance(JSBI.BigInt(params.decimals), SolidityType.uint8)

        this.decimals = params.decimals
        this.symbol = params.symbol
        this.name = params.name
        this.chainId = params.chainId
        this.address = validateAndParseAddress(params.address)
        this.isNative = !!params.isNative
        this.icons = params.icons
        this.chainFromId = params.chainFromId
        this.isStable = params.isStable
        this.userToken = params.userToken
    }
    ...
}

export class TokenAmount extends Fraction {

    ...

    public constructor(token: Token, amount: BigintIsh) {
        const parsedAmount = parseBigintIsh(amount)
        validateSolidityTypeInstance(parsedAmount, SolidityType.uint256)

        super(parsedAmount, JSBI.exponentiate(TEN, JSBI.BigInt(token.decimals)))
        this.token = token

    }

    ...
}

PendingRequestState and PendingRequest types

The PendingRequestState and PendingRequest types are used for reverting stuck cross-chain operations.

For more information, see Symbiosis & Emergencies

Example:

enum PendingRequestState {
    Default = 0,
    Reverted,
}

export type PendingRequestType = 'burn' | 'synthesize'

export interface PendingRequest {
    fromTokenAmount: TokenAmount
    transactionHash: string
    state: PendingRequestState
    internalId: string
    externalId: string
    type: PendingRequestType
    from: string
    to: string
    revertableAddress: string
    chainIdFrom: ChainId
    chainIdTo: ChainId
    revertChainId: ChainId
}

Where:

Property	Description
fromTokenAmount	The amount of tokens of the stuck cross-chain operation.
transactionHash	The hash of the transaction associated with the stuck operation.
state	The current state of the revert operation: Default: No attempt to revert the operation was made. Reverted: An attempt to revert the operation was made.
internalId	The internal identifier of the cross-chain operation. internalID = keccak256( abi.encodePacked(this, requestCount, block.chainid) );
externalId	The external identifier of the cross-chain operation. The identifier is derived from the internalId and calculated together with the destination network id, the destination contract address, and the address that revert this transaction. externalID = keccak256(abi.encodePacked(internalID, _receiveSide, _revertableAddress, _chainID)
type	The type of the operation: burn: The operation burns sTokens, synthesize: The operation mints sTokens.
from	The sender's address.
to	The recipient's address.
revertableAddress	The address authorized to perform a revert operation for the stuck transaction.
chainIdFrom	The identifier of the source blockchain.
chainIdTo	The identifier of the destination blockchain.
revertChainId	The identifier of the blockchain where the revert transaction will be sent.