🟧Symbiosis Routing Contracts

Symbiosis core smart contracts: MetaRouterGateway, metaRouter, and multicallRouter.

• If you are curious to see the Symbiosis protocol in action, check out Symbiosis WebApp.

• Symbiosis core smart contracts are open source and available at https://github.com/symbiosis-finance/core-contracts

• For security audits of Symbiosis core smart contract, please refer to Security Audits of Symbiosis.

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.

Bridging

To enable cross-chain operations the Symbiosis protocol works with chosen transit tokens on every supported blockchain. Please refer to sTokens in Symbiosis for more details.

Transit tokens: WETH and specific stablecoins can be seen as transit tokens in the Symbiosis protocol, since they are used to enable cross-chain operations within the protocol.

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: 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 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 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: 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 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 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.

Cross-chain Swap

To enable cross-chain operations the Symbiosis protocol works with chosen transit tokens on every supported blockchain. Please refer to sTokens in Symbiosis for more details.

Transit tokens: WETH and specific stablecoins can be seen as transit tokens in the Symbiosis protocol, since they are used to enable cross-chain operations within the protocol.

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.

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. 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: 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.

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 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.

In some cases Step 20 may be omitted. In this case, transit tokens will be sent to the user's address. Please check the Guaranteed Transit Tokens section.

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.

Guaranteed Transit Tokens

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.

1. If the transaction on the first (source) network surpasses the accepted price change, then assets stay in the wallet.

2. 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.

3. 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.

Cross-chain Zap

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: 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 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 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.

Interchain Communication

To enable cross-chain operations the Symbiosis protocol works with chosen transit tokens on every supported blockchain. Please refer to sTokens in Symbiosis for more details.

Transit tokens: WETH and specific stablecoins can be seen as transit tokens in the Symbiosis protocol, since they are used to enable cross-chain operations within the protocol.

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.

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).

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.

Guaranteed Transit Tokens

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.

1. If the transaction on the first (source) network surpasses the accepted price change, then assets stay in the wallet.

2. 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.

3. 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.