🟪
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.
The Symbiosis protocol 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.
To enable cross-chain operations the Symbiosis protocol works with a chosen stablecoin on every supported blockchain; for example, it's USDC on Ethereum and BUSD on the BNB chain. The sToken for USDC is sUSDC, and the sToken for BUSD is sBUSD.
The Symbiosis protocol also works with WETH for some blockchains. The sToken for WETH is sWETH.
sTokens are minted and burned on Boba BNB (the Symbiosis host chain) during cross-chain operations. More about the sToken concept can be found in sTokens in Symbiosis.
Bridging is a cross-chain operation when:
- 1.A user gives away particular stablecoins or WETH (if supported) on one of the supported blockchains, and receives their wrapped representations (sTokens) on Boba BNB. Such an operation involves minting. (Scheme 1) - OR -
- 2.A user burns sTokens on Boba BNB and receives stablecoins or WETH tokens 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 or WETH equivalent:
GasEstimatedUSD1in 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 the transaction on the source blockchain (on Polygon in the example).
Steps 5. The Oracle request contains all the information needed to validate, route, and accomplish the cross-chain operation.
Steps 3-5. These steps are performed in a single transaction. If any step or 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 Relayers network.
Step 7. sTokens are minted at a 1:1 ratio with the tokens 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 sTokens are sent to the user's address on the destination blockchain of the bridging operation.
Steps 7-9. These steps are performed in a single transaction. If any step or check fails, all changes made during the transaction are undone.
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 or WETH equivalent:
GasEstimatedUSD1in 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 the transaction on the source blockchain (on Boba BNB in the example).
Steps 4. The Oracle request contains all the information needed to validate, route, and accomplish the cross-chain operation.
Steps 2-4. These steps are performed in a single transaction. If any step or 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 Relayers network.
Step 7. Tokens 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 in a single transaction. If any step or check fails, all changes made during the transaction are undone.
Symbiosis supports two types of bridging:
- On stablecoins: for all supported blockchains,
- And WETH: for some supported blockchains.
If a pair of blockchains supports bridging on stablecoins and on WETH, then Symbiosis finds 2 routes (a sequence of intermediate swaps) for each swap between these blockchains:
- The best route using bridging on stablecoins.
- The best route using bridging on WETH.
Symbiosis then compares these two routes and offers the best one for the user. The best route means that the user gets the maximum amount of tokens and pays less on-chain and cross-chain fees.
Scheme 3 shows the sequence of steps for routing on stablecoins. Routing on WETH is quite similar.
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:
GasEstimatedUSD1in Scheme 3. If routing on WETH, then the estimated gas fee will be in WETH. - 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:
GasEstimatedUSD2in Scheme 3. If routing is on WETH, then the estimated gas fee will be in WETH.
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 the transaction on the source blockchain (on 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).
The same routine will be done via Symbiosis Octopool with sWETH tokens, if bridging on WETH is used.
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 in a single transaction. If any step or 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 Relayers network.
Step 9. sTokens are minted at a 1:1 ratio with the tokens 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 tokens 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 in a single transaction. If any step or check fails, all changes made during the transaction are undone.
Step 17. Tokens 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 tokens 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 in a single transaction. If any step or check fails, all changes made during the transaction are undone.
Cross-chain zapping has been implemented to facilitate liquidity supplying to Symbiosis Octopools located on Boba BNB. Having any assets on any (supported) blockchain, liquidity providers can supply the assets to this pool via cross-chain zapping (Scheme 4).
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
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:
GasEstimatedUSD1in Scheme 4. If a user supplies tokens to Symbiosis Octopool with sWETH tokens, the routing will be on WETH, and the estimated gas fee will also be in the WETH equivalent.
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 (on 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 Relayers network.
Step 9. sTokens are minted at a 1:1 ratio with the tokens 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 in a single transaction. If any step or check fails, all changes made during the transaction are undone.
Symbiosis supports two types of bridging:
- On stablecoins: for all supported blockchains,
- And WETH: for some supported blockchains.
If a pair of blockchains supports bridging on stablecoins and on WETH, then Symbiosis finds 2 routes (a sequence of intermediate swaps) for each cross-chain operation between these blockchains:
- The best route using bridging on stablecoins.
- The best route using bridging on WETH.
Symbiosis then compares these two routes and offers the best one for the user. The best route means that the user gets the maximum amount of tokens and pays less on-chain and cross-chain fees.
Scheme 5 shows the sequence of steps for routing on stablecoins. Routing on WETH is quite similar.
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).