Symbiosis Routing Contracts
Symbiosis core smart contracts: MetaRouterGateway, metaRouter, and multicallRouter.
Last updated
Was this helpful?
Symbiosis core smart contracts: MetaRouterGateway, metaRouter, and multicallRouter.
Last updated
Was this helpful?
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:
Bridging,
Cross-chain swap,
Cross-chain zap,
Interchain communication messaging.
As you will see below, all the operations look very similar.
To enable cross-chain operations the Symbiosis protocol works with chosen transit tokens on every supported blockchain. Please refer to Symbiosis sTokens for more details.
Bridging is a cross-chain operation when:
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 -
A user burns sTokens on Boba BNB and receives stablecoins or WETH tokens on a corresponding blockchain (Scheme 2). Such an operation involves burning.
Important notices for Scheme 1
Step 2. The initial transaction consists of 2 calldatas:
Calldata0: the sequence of steps to do on the source blockchain.
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: GasEstimatedUSD1 in Scheme 1.
In addition, the calldatas may contain some restrictions, such 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 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.
Important notices for Scheme 2
Step 1. The initial transaction consists of 2 calldatas:
Calldata0: the sequence of steps to do on the source blockchain.
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: GasEstimatedUSD1 in Scheme 2.
In addition, the calldatas may contain some restrictions, such 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 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.
To enable cross-chain operations the Symbiosis protocol works with chosen transit tokens on every supported blockchain. Please refer to Symbiosis sTokens for more details.
If a pair of blockchains supports stablecoins and WETH as transit tokens, then Symbiosis finds 2 routes (a sequence of intermediate swaps) for each swap between these blockchains:
The best route using stablecoins as transit tokens.
The best route using WETH as a transit token.
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.
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:
Calldata0: the sequence of steps to do on the source blockchain.
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. If routing on WETH, then the estimated gas fee will be in WETH.
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. 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 transit token 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 token, it will be exchanged for the transit token 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 WETH is used as an transit token.
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.
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.
Each cross-chain swap has a slippage tolerance limit that is set in Step 2. This value is distributed across all transactions of a cross-chain swap. This ensures that each individual transaction remains within its specified slippage tolerance fraction, guaranteeing that the cumulative price change doesn't exceed the overall slippage tolerance threshold.
If the transaction on the first (source) network surpasses the accepted price change, then assets stay in the wallet.
If the transaction on Symbiosis host chain surpasses the accepted price change, then the cross-chain swap gets halted. Please see Symbiosis & Emergencies for more details.
If the transaction on the destination blockchain surpasses the accepted price change, then the user will receive an appropriate amount of the transit token: Step 20 will be omitted and transit tokens will be sent to the user's address.
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:
Calldata0: the sequence of steps to do on the source blockchain.
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. 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 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.
To enable cross-chain operations the Symbiosis protocol works with chosen transit tokens on every supported blockchain. Please refer to Symbiosis sTokens for more details.
If a pair of blockchains supports stablecoins and WETH as transit tokens, then Symbiosis finds 2 routes (a sequence of intermediate swaps) for each swap between these blockchains:
The best route using stablecoins as transit tokens.
The best route using WETH as a transit token.
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.
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).
Steps 19, 20 and 21. In some cases Step 20 and 21 may be omitted. In this case, transit tokens will be sent to the user's address. Please check the section.
Each cross-chain operation has a slippage tolerance limit that is set in the transaction signed by user. This value is distributed across all transactions of a cross-chain operation. This ensures that each individual transaction remains within its specified slippage tolerance fraction, guaranteeing that the cumulative price change doesn't exceed the overall slippage tolerance threshold.
If the transaction on the first (source) network surpasses the accepted price change, then assets stay in the wallet.
If the transaction on Symbiosis host chain surpasses the accepted price change, then the cross-chain swap gets halted. Please see Symbiosis & Emergencies for more details.
If the transaction on the destination blockchain surpasses the accepted price change, then the user will receive an appropriate amount of the transit token: Step 20 and 21 will be omitted and transit tokens will be sent to the user's address.
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 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.
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 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.
