🟪
Symbiosis Routing Contracts
Symbiosis core smart contracts: MetaRouterGateway, metaRouter, and multicallRouter.
Symbiosis core smart contracts are open source and available at
https://github.com/symbiosis-finance/core-contracts
Each cross-chain operation consists of multiple intermediate steps executed on different blockchains. Moreover, multiple intermediate operations are executed on different contracts within one blockchain. Let's see how it works.
Symbiosis protocol V2 implements the following cross-chain operations:
- 1.Bridging,
- 2.Cross-chain swap,
- 3.Cross-chain zap,
- 4.Interchain communication messaging.
As you will see below, all the operations look very similar.
All the operations involve the routine of minting/burning of sTokens. See Symbiosis Mint-Burn Process for more information.
The Symbiosis protocol works with a particular stablecoin on each supported blockchain to perform cross-chain operations. For example, this is the USDC on Polygon and the USDT on Avalanche.
Such a stablecoin has its wrapped representation (sToken) on another blockchain with a ratio of 1:1 to its locked original. For example, the wrapped representation of USDC from Polygon is the sUSDC on BOBA BNB (S-chain).
Bridging is a cross-chain operation when:
- 1.A user gives away particular stablecoins on one of the supported blockchains, and receives their wrapped representations (sToken) on another blockchain. Such an operation involves minting. (Scheme 1) - OR -
- 2.A user gives away sTokens on one blockchain and receives stablecoins on a corresponding blockchain (Scheme 2). Such an operation involves burning.

Scheme 1. Bridging routine that involves minting.
Important notices for Scheme 1
Step 2. The initial transaction consists of 2 calldatas:
- 1.Calldata0: the sequence of steps to do on the source blockchain.
- 2.Calldata1: the sequence of steps to do on S-chain. This calldata includes the estimated gas fee for the transaction execution on S-chain in the stablecoin equivalent:
GasEstimatedUSD1
in Scheme 1.
In addition, the calldatas contain some restrictions, such as the slippage tolerance and the deadline for the cross-chain operation.
All of this information is defined at the time of the initial transaction signing and cannot be modified later. By signing, the user accepts all these intermediate steps, restrictions, and fees. The user pays the gas fee for this transaction on the source blockchain (it’s Polygon in the example).
Steps 5. The oracle request contains all the information needed to verify and route the cross-chain operation.
Steps 3-5. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.
Step 6. Relayers perform some checks, sign a transaction and send it to an appropriate blockchain. The relayers pay for the transaction, and the user refunds these expenses (Step 8). For information on the Symbiosis relayers network, please see Symbiosis RelayersNetwork.
Step 7. sTokens are minted at a 1:1 ratio with the stablecoins locked in Portal (Step 3).
Step 8. The amount approved in Step 2 is deducted from the amount of minted tokens (Step 7) to refund the transaction fee paid by relayers (Step 6). The remaining stablecoins are sent to the user's address on the destination blockchain of the bridging operation.
Steps 7-9. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.
.png?alt=media&token=6df17f48-e66a-4745-af3a-0124b0522eb2)
Scheme 2. Bridging routine that involves burning.
Important notices for Scheme 2
Step 1. The initial transaction consists of 2 calldatas:
- 1.Calldata0: the sequence of steps to do on the source blockchain.
- 2.Calldata1: the sequence of steps to do on the destination blockchain. This calldata includes the estimated gas fee for the transaction execution in the stablecoin equivalent:
GasEstimatedUSD1
in Scheme 2.
In addition, the calldatas contain some restrictions, such as the slippage tolerance and the deadline for the cross-chain operation.
All of this information is defined at the time of the initial transaction signing and cannot be modified later. By signing, the user accepts all these intermediate steps, restrictions, and fees. The user pays the gas fee for this transaction on the source blockchain (it’s BOBA BNB in the example).
Steps 4. The oracle request contains all the information needed to verify and route the cross-chain operation.
Steps 2-4. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.
Step 5. Relayers perform some checks, sign a transaction and send it to an appropriate blockchain. The relayers pay for the transaction, and the user refunds these expenses (Step 8). For information on the Symbiosis relayers network, please see Symbiosis RelayersNetwork.
Step 7. Stablecoins are released at a 1:1 ratio with the sTokens burned by Synthesis (Step 2).
Step 8. The amount approved in Step 1 is deducted from the amount of released tokens (Step 5) to refund the transaction fee paid by relayers (Step 5). The remaining stablecoins are sent to the user's address on the destination blockchain of the bridging operation.
Steps 6-8. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.

Scheme 3. Contract interactions during a cross-chain swap: GNS on Polygon for AVAX on Avalanche.
Important notices for Scheme 3
Step 1.
- Users should approve ERC20 tokens only for the MetarouterGateway contract. If users approve tokens for any other contract, their tokens can be stolen.
- If the source token is native currency for the source blockchain this step is omitted.
Step 2. The initial transaction consists of 3 calldatas:
- 1.Calldata0: the sequence of steps to do on the source blockchain.
- 2.Calldata1: the sequence of steps to do on S-chain. This calldata includes the estimated gas fee for the transaction execution on S-chain in the stablecoin equivalent:
GasEstimatedUSD1
in Scheme 3. - 3.Calldata2: the sequence of steps to do on the destination blockchain. This calldata includes the estimated gas fee for the transaction execution on the destination blockchain in the stablecoin equivalent:
GasEstimatedUSD2
in Scheme 3.
In addition, the calldatas contain some restrictions, such as the slippage tolerance and the deadline for the cross-chain operation.
All of this information is defined at the time of the initial transaction signing and cannot be modified later. By signing, the user accepts all these intermediate steps, restrictions, and fees. The user pays the gas fee for this transaction on the source blockchain (it’s Polygon in the example).
Step 4. The Symbiosis protocol works with a specific stablecoin on each supported blockchain. For Polygon, this is the USDC. So having USDCs, the protocol can bridge the stablecoin from Polygon to another blockchain. If the initial token differs from the needed stablecoin, it will be exchanged for the stablecoin in the DEX at the best price. The DEX is selected during the initial transaction composing (Step 2).
Steps 5 and 15. The oracle request contains all the information needed to verify and route the cross-chain operation.
Steps 3-7. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.
Steps 8 and 16. Relayers perform some checks, sign a transaction and send to to an appropriate blockchain. The relayers pay for the transactions that they sign and send, and users refund these expenses (Steps 14 and 18). For information on the Symbiosis relayers network, please see Symbiosis RelayersNetwork.
Step 9. sTokens are minted at a 1:1 ratio with the stablecoins locked in Portal (Step 5).
Step 10. The amount approved in Step 2 is deducted from the amount of minted tokens (Step 9) to refund the transaction fee paid by relayers (Step 8). The remaining stablecoins continue to participate in the intermediate steps of the cross-chain swap.
Step 13. Synthesis burns the sTokens.
Steps 9-15. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.
Step 17. Stablecoins are released at a 1:1 ratio with the sTokens burned by Synthesis (Step 13).
Step 10. The amount approved in Step 2 is deducted from the amount of released tokens (Step 17) to refund the transaction fee paid by relayers (Step 16). The remaining stablecoins continue to participate in the intermediate steps of the cross-chain swap.
Step 20. Once the last intermediate swap is completed, the tokens are sent to the user's address on the destination blockchain of the cross-chain operation.
Steps 17-20. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.

Scheme 4. Contract interactions during a cross-chain zap: GNS on Polygon to Symbiosis Octopool on BOBA NBN (S-chain).
Important notices for Scheme 4
The main idea behind cross-chain zapping is to allow users who can have any token on any supported blockchain to add that token to Symbiosis Octopool.
Step 1.
- Users should approve ERC20 tokens only for the MetarouterGateway contract. If users approve tokens for any other contract, their tokens can be stolen.
- If the source token is native currency for the source blockchain this step is omitted.
Step 2. The initial transaction consists of 2 calldatas:
- 1.Calldata0: the sequence of steps to do on the source blockchain.
- 2.Calldata1: the sequence of steps to do on S-chain. This calldata includes the estimated gas fee for the transaction execution on S-chain in the stablecoin equivalent:
GasEstimatedUSD1
in Scheme 4.
In addition, the calldatas contain some restrictions, such as the slippage tolerance and the deadline for the cross-chain operation.
All of this information is defined at the time of the initial transaction signing and cannot be modified later. By signing, the user accepts all these intermediate steps, restrictions, and fees. The user pays the gas fee for this transaction on the source blockchain (it’s Polygon in the example).
Steps 7. The oracle request contains all the information needed to verify and route the cross-chain operation.
Steps 3-7. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.
Step 8. Relayers perform some checks, sign a transaction and send it to an appropriate blockchain. The relayers pay for the transaction, and the user refunds these expenses (Step 10). For information on the Symbiosis relayers network, please see Symbiosis RelayersNetwork.
Step 9. sTokens are minted at a 1:1 ratio with the stablecoins locked in Portal (Step 3).
Step 10. The amount approved in Step 2 is deducted from the amount of minted tokens (Step 9) to refund the transaction fee paid by relayers (Step 8).
Step 11. Tokens are added to the liquidity pool and LP tokens sent to the user's address on this blockchain.
Steps 9-11. These steps are performed during a single transaction. If any of the steps or any check fails, all changes made during the transaction are undone.
.png?alt=media&token=307fe25e-1b08-45fe-9193-1ee9032837de)
Scheme 5. Contract interactions during interchain communication: swapping GNS on Polygon for DAI on Avalanche and adding to BENQI on Avalanche.
Important notices for Scheme 5
The interchain communication routine is very similar to the routine of the cross-chain swap (Scheme 3), except for one additional step: adding liquidity to a third-party protocol on the destination blockchain and sending LP tokens (or any other proofs issued by the protocol) to the user's address on the destination blockchain (Step 21 in the Scheme 5).