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 in the Symbiosis protocol consists of multiple intermediate steps executed across different blockchains.
Let’s walk through how this works.
The Symbiosis protocol supports the following types of cross-chain operations:
Bridging
Cross-chain swap
Cross-chain zap
Interchain messaging
Bridging refers to a cross-chain operation in which:
Scenario 1: Minting A user deposits stablecoins or other transit tokens (such as WETH or WBTC) on one blockchain and receives wrapped representations — sTokens — on another blockchain (Scheme 1).
Scenario 2: Burning A user burns sTokens on one blockchain and receives the underlying assets (stablecoins, WETH, WBTC, etc.) on another supported chain (Scheme 2)
Important notices for Scheme 1
Step 2. The initial transaction includes two separate calldatas:
Calldata0: the sequence of steps to be executed on the source blockchain.
Calldata1: the sequence of steps to be executed on the Symbiosis Host Chain.
Both calldatas may include additional constraints, such as a deadline for completing the cross-chain operation.
All of this information is finalized at the time of the initial transaction signing and cannot be changed afterward. By signing the transaction, the user agrees to: all intermediate steps; any specified restrictions; the estimated fees.
The user pays the gas fee for executing the transaction on the source blockchain (Polygon in the example).
Steps 3 — 5. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
Steps 5. The contract emits an Oracle request containing all the data required to validate, route, and complete the cross-chain operation.
Step 6. The Relayers Network validates the Oracle request, signs and sends data for the newt chain. Relayers cover the gas fee for this transaction. Later, in Step 8, the user reimburses this expense. For more details about the Symbiosis Relayers Network, see Relayers network.
Steps 7 — 9. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
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 the Relayers Network (Step 6). The remaining sTokens are sent to the user's address on the destination blockchain of the bridging operation.
Important notices for Scheme 2
Step 1. The initial transaction includes two separate calldatas:
Calldata0: the sequence of steps to be executed on the source blockchain (the Symbiosis Host Chain).
Calldata1: the sequence of steps to be executed on the destination blockchain.
Both calldatas may include additional constraints, such as a deadline for completing the cross-chain operation.
All of this information is finalized at the time of the initial transaction signing and cannot be changed afterward. By signing the transaction, the user agrees to: all intermediate steps; any specified restrictions; the estimated fees.
The user pays the gas fee for executing the transaction on the source blockchain.
Steps 2 — 4. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
Steps 4. The contract emits an Oracle request containing all the data required to validate, route, and complete the cross-chain operation.
Step 5. The Relayers Network validates the Oracle request, signs and sends data for the newt chain. Relayers cover the gas fee for this transaction. Later, in Step 7, the user reimburses this expense. For more details about the Symbiosis Relayers Network, see Relayers network.
Steps 6 — 8. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
Step 6. Tokens are released at a 1:1 ratio to the sTokens burned in Step 2.
Step 7. The amount approved in Step 1 is deducted from the amount of released tokens (Step 5) to refund the transaction fee paid by the Relayers Network (Step 5). The remaining tokens are sent to the user's address on the destination blockchain of the bridging operation.
Thansit Tokens To perform cross-chain swaps, the Symbiosis protocol uses transit tokens — highly liquid assets like stablecoins, WETH, and WBTC — available on supported blockchains. These tokens are used because their value is uniform across chains, making them ideal for cross-chain routing and minimizing price slippage.
Multirouting When a swap is requested between two blockchains, Symbiosis checks which transit tokens are available for that pair — this can be one, two, or all three (stablecoins, WETH, WBTC). For each available option, the protocol builds a route and then selects the most efficient one — the route that provides the highest output for the user.
Scheme 3 shows an example of routing via stablecoins. Routing via WETH or WBTC works the same way.
Important notices for Scheme 3
Step 1.
Users approve ERC-20 tokens only for the MetarouterGateway contract. Approving tokens for any other contract may result in loss of funds.
If the source token is the native currency of the source blockchain, this step is skipped.
Step 2. The initial transaction includes three separate calldatas:
Calldata0: the sequence of steps to be performed on the source blockchain.
Calldata1: the sequence of steps on the Symbiosis Host Chain. This calldata includes the estimated gas fee for the transaction execution on the Symbiosis Host Chain in the stablecoin equivalent: GasEstimatedUSD1 in Scheme 3. If routing is via another transit token, the fee will be denominated in that transit token.
Calldata2: the sequence of steps to be performed 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 via another transit token, the fee will be denominated in that transit token.
The calldatas may include additional constraints, such as a deadline for completing the cross-chain operation.
All of this information is finalized at the time of the initial transaction signing and cannot be changed afterward. By signing the transaction, the user agrees to: all intermediate steps; any specified restrictions; the estimated fees.
The user pays the gas fee for executing the transaction on the source blockchain.
Steps 3 — 7. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
Step 4. In this example, USDC is used as the transit token on Polygon. If the input token is not USDC, it is exchanged for USDC via a third-party DEX (or multiple DEXs) selected during the transaction composition (Step 2).
Steps 5 and 15. The contract emits an Oracle request containing all the data required to validate, route, and complete the cross-chain operation.
Steps 8 and 16. Relayers validate the Oracle request, sign and send the data to the appropriate blockchain. They cover the gas fees for these transactions. Users reimburse these fees later (Step 14 and Step 18). For more details about the Symbiosis Relayers Network, see Relayers network.
Step 9. sTokens are minted at a 1:1 ratio to 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 the Relayers (Step 8). The remaining tokens continue to participate in the intermediate steps of the cross-chain swap.
Step 12. sTokens backed by assets on the source chain are exchanged for sTokens backed by assets on the destination chain via the Octopool. This swap enables further bridging into the destination chain. This is the step where the logical cross-chain transition takes place.
Step 13. Synthesis burns the sTokens for the destination chain.
Steps 9 — 15. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
Steps 17 — 20. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
Step 17. Tokens are released at a 1:1 ratio to the sTokens burned by Synthesis (Step 13).
Step 18. The gas fee approved in Step 2 is deducted from the released amount to reimburse the Relayers (Step 8). The remaining tokens proceed through the intermediate swap steps.
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.
Each cross-chain swap has a slippage tolerance defined in Step 2. This value is distributed across all transactions that make up the swap, ensuring that each segment of the operation stays within its allocated share of the total slippage. This mechanism guarantees that the cumulative price impact does not exceed the overall slippage threshold.
If the transaction on the first (source) network surpasses the accepted price change, then the swap is not initiated and the assets remain in the user's wallet.
If the transaction on Symbiosis Host Chain surpasses the accepted price change, then the cross-chain swap is halted. Please see Symbiosis & Emergencies for more details.
If the transaction on the destination blockchain exceeds the slippage tolerance, Step 20 is skipped, and the user receives the transit token instead of the final token.
Cross-chain zapping has been implemented to facilitate liquidity supplying to Symbiosis Octopools located on the Symbiosis Host Chain. Having any assets on any (supported) blockchain, liquidity providers can supply the assets to this pool via cross-chain zapping (Scheme 4).
Important notices for Scheme 4
Step 1.
Users approve ERC-20 tokens only for the MetarouterGateway contract. Approving tokens for any other contract may result in loss of funds.
If the source token is the native currency of the source blockchain, this step is skipped.
Step 2. The initial transaction includes two separate calldatas:
Calldata0: the sequence of steps to be performed on the source blockchain.
Calldata1: the sequence of steps on the Symbiosis Host Chain. This calldata includes the estimated gas fee for the transaction execution on the Symbiosis Host Chain in the stablecoin equivalent: GasEstimatedUSD1 in Scheme 4. If routing is via another transit token, the fee will be denominated in that transit token.
The calldatas may include additional constraints, such as a deadline for completing the cross-chain operation.
All of this information is finalized at the time of the initial transaction signing and cannot be changed afterward. By signing the transaction, the user agrees to: all intermediate steps; any specified restrictions; the estimated fees.
The user pays the gas fee for executing the transaction on the source blockchain.
Steps 3 — 7. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
Steps 7. The Oracle request contains all the information needed to verify and route the cross-chain operation.
Step 8. Relayers validate the Oracle request, sign and send the data to the appropriate blockchain. For more details about the Symbiosis Relayers Network, see Relayers network.
Steps 9 — 11. These steps are executed within a single transaction. This ensures atomicity — if any check or step fails, all changes are rolled back.
Step 9. sTokens are minted at a 1:1 ratio to 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 the Relayers (Step 8).
Step 11. Tokens are added to the liquidity pool, and the LP tokens are sent to the user's address on the blockchain.
The interchain communication routine closely follows the structure of a cross-chain swap (see Scheme 3), with one key difference: an additional step is included on the destination blockchain — depositing assets into a third-party protocol, and transferring LP tokens (or other protocol-issued proofs) to the user's address.
Scheme 5 shows an example of a cross-chain swap followed by depositing tokens into the BENQI protocol. Routing in this example is performed via stablecoins; routing via WETH or WBTC works in the same way.
Important notices for Scheme 5
Steps 1 — 18. These steps follow the standard cross-chain swap flow.
Steps 19 — 21. In some cases, Steps 20 and 21 may be skipped. When this happens, transit tokens are sent directly to the user's address on the destination blockchain instead of performing the final swap and depositing assets into a third-party protocol. Please see the section below for more details.
Each cross-chain swap has a slippage tolerance defined in Step 2. This value is distributed across all transactions that make up the swap, ensuring that each segment of the operation stays within its allocated share of the total slippage. This mechanism guarantees that the cumulative price impact does not exceed the overall slippage threshold.
If the transaction on the first (source) network surpasses the accepted price change, then the swap is not initiated and the assets remain in the user's wallet.
If the transaction on Symbiosis Host Chain surpasses the accepted price change, then the cross-chain swap is halted. Please see Symbiosis & Emergencies for more details.
If the transaction on the destination blockchain exceeds the slippage tolerance, Step 20 and 21 are skipped, and the user receives the transit token on the destination chain.
