Symbiosis & Emergencies

Failed Cross-chain Operations

A cross-chain swap consists of several transactions executed on different blockchains (Scheme 1):

• TXN0 — on the source chain (e.g., Polygon)

• TXN1 — on the Symbiosis Host Chain

• TXN2 — on the destination chain (e.g., Avalanche)

Scheme 1. A cross-chain swap of GNS on Polygon for AVAX on Avalanche.

Since these transactions depend on each other and happen across different chains, there’s always a chance something might go wrong. For example:

• The operation timeout may expire

• The price on a DEX may change too much, causing the transaction to exceed the allowed slippage

• A network error may occur

When this happens, it’s called an emergency — the cross-chain operation was started, but couldn't be completed. Usually this means that TXN0 (on the source chain) was successful, but the transaction on the intermediate — the Host Chain (TXN1) or the destination chain (TXN2) either failed or never happened.

Revert Introduction

If a cross-chain operation cannot be completed, it is reverted.

How does reverting work?

• After February 9, 2025: Cross-chain swaps labeled "Stuck" are automatically reverted within 12 hours.

• Before February 8, 2025: Users need to manually revert the swap using Symbiosis WebApp.

General Notes

Who Can Revert

The revert transaction must be sent from the same address used in the original operation — or, in special cases, from a specifically designated address stored in the transaction data.

Important

• Portal and Synthesis contracts keep records and states of cross-chain operations and revert requests that go through the smart contracts. A specific state is set for each record to eliminate double spending.

• Each reverting operation is a cross-chain operation, so it can also get stuck.

• All steps within a blockchain are performed in a single transaction.

Revert Result: Address, Token Type and Chain

When a cross-chain operation is reverted, the user receives tokens back the source address on the source blockchain — the one where the original operation began.

Reverts always follow the same transit token type used in the original route:

• If the initial swap used stablecoins, the revert will also use stablecoins

• If it used WETH, the revert will use WETH

• If it used WBTC, the revert will use WBTC

For example, if USDC was the transit token on Polygon, the user will receive USDC on Polygon, even if they originally sent another token (see Scheme 1).

Cross-chain Operation Structure: TXN0 (Chain1) → TXN1 (Host Chain) → TXN2 (Chain2)

A standard cross-chain operation includes three transactions:

• TXN0 — on the source chain (Chain1)

• TXN1 — on the Symbiosis Host Chain

• TXN2 — on the destination chain (Chain2)

Two failure scenarios are possible:

• Emergency Case 1: TXN0 X TXN1 -> TXN2

  • TXN0 (on Chain1) was successful

  • TXN1 (on Host Chain) failed

  • TXN2 (on Chain2) did not happen

• Emergency Case 2: TXN0 -> TXN1 X TXN2

  • TXN0 and TXN1 were successful

  • TXN2 failed

Emergency Case 1: TXN0 X TXN1 -> TXN2

Conditions

• The user’s tokens were locked in Portal on Chain1 (Polygon in our example).

• These tokens can only be unlocked if Synthesis on the Symbiosis Host Chain sends a valid revert request.

Challenge

The straightforward way to revert would be to send a transaction directly to the Host Chain. However, this creates friction for the user:

• They may not know the Host Chain exists

• They likely don’t hold its native token to pay gas fees

• They probably don’t want to deal with it at all

UX-Friendly Solution

To solve this, Symbiosis introduced a flow that lets users initiate the revert entirely from Chain1, without having to interact with the Host Chain directly.

Reverting Workflow (Scheme 2)

portal.metaRevertRequest() on Chain1 -> synthesis.revertSynthesizeRequestByBridge() on the Host Chain -> portal.revertSynthesize() back on Chain1

If this process fails (e.g., due to timing or gas issues), the user may need to send another revert transaction on Chain1.

Scheme 2. Revert scheme for Emergency Case 1.

Important notes for Scheme 2 (Case 1)

Step 1. The user signs a transaction that includes:

1. Calldata0: the sequence of steps to be executed on Polygon.

2. Calldata1: the sequence of steps to be executed on the Symbiosis Host Chain. This includes an estimated gas fee value for Polygon:GasEstimatedUSD

This is the only case where the user does not reimburse gas fees on the Symbiosis Host Chain.

Step 2. Calling portal.metaRevertRequest()

Step 6. Only the BridgeV2 contract is allowed to call synthesis.revertSynthesizeRequestByBridge().

Step 8. The emitted Oracle request includes a call to portal.revertSynthesize()on Polygon. It also includes the gas fee value:GasEstimatedUSD for Polygon, as approved in Step 1.

Step 10. Only the BridgeV2 is allowed to call portal.revertSynthesize()

Step 11. From the amount being released:

• The gas fee approved in Step 1 is deducted to reimburse the relayers (who paid for the transaction in Step 9)

• The remaining tokens are transferred to the user's wallet on Polygon.

If it fails, another transaction should be sent Chain1 with revert instructions (Step 1).

Emergency Case 2: TXN0 -> TXN1 X TXN2

Conditions and restrictions

• The user’s tokens were locked in Portal on Chain1 (Polygon in our example).

• These tokens can only be unlocked if Synthesis on the Symbiosis Host Chain sends a valid revert request. In its turn, Synthesis will only send such a request if it receives instructions from the Portal, which is located on Chain2 (Avalanche in our example).

Reverting Workflow (Scheme 3)

portal.metaRevertRequest() on Chain2 -> synthesis.revertMetaBurn() on the Host Chain -> synthesis.metaBurnSyntheticToken() on the Host Chain -> portal.metaUnsynthesize() on Chain1

If the reverting operation fails between Chain2 (Avalanche in our example) and the Host Chain, another transaction should be sent to Chain2 with revert instructions (Step 1).

If the reverting operation fails between the Host Chain and Chain1 (Polygon in our example), see the subcase.

Scheme 3. Revert scheme for Emergency Case 2.

Important notes for Scheme 3 (Case 2)

Step 1. The user signs a transaction that includes:

1. Calldata0: the sequence of steps to be executed on Avalanche.

2. Calldata1: the sequence of steps to be executed on the Host Chain. This calldata includes the estimated gas fee for the transaction execution on the Host Chain in the stablecoin equivalent: GasEstimatedUSD1 in Scheme 3.

3. Calldata2: the sequence of steps to be executed on the destination blockchain. This calldata includes the estimated gas fee for the transaction execution on the destination blockchain: GasEstimatedUSD2.

The transaction is sent to Chain2 (Avalanche in our example).

Step 2. Calling portal.metaRevertRequest()

Step 6. Only BridgeV2 is allowed to call synthesis.revertMetaBurn()

Step 7. The amount approved in Step 1 is deducted from the amount of minted tokens (Step 6) to refund the transaction fee paid by the relayers (Step 5). The remaining stablecoins continue to participate in the intermediate steps of the reverting operation.

Step 12. The Oracle request contains a call to portal.revertSynthesize()on Polygon. The parameters include the estimated gas fee value for Polygon:GasEstimatedUSD2

Step 14. Only BridgeV2 is allowed to call portal.metaUnsynthesize(). Stablecoins are released at a 1:1 ratio to the sTokens burned by Synthesis (Step 10).

Step 15. The amount approved in Step 1 is deducted from the amount of released tokens (Step 14) to refund the transaction fee paid by the relayers (Step 13). The remaining tokens are deposited to the user’s address on Polygon.

If the reverting operation fails between Chain2 (Avalanche in our example) and S-chain, another transaction should be sent to Chain2 with revert instructions (Step 1).

If the reverting operation fails between the Host Chain and Chain1 (Polygon in our example), see the subcase.

Emergency Case 3: Subcase of Emergency Case 2

Conditions and restrictions

• There was an attempt to revert a cross-chain operation (Case 2). That reverting operation was stuck on the Host Chain.

• The user’s tokens are still locked in Portal on Chain1 (Polygon in our example)

• Portal will only release the tokens if it receives a request from Synthesis, which is located on the Host Chain. Synthesis will only send such a request if it receives instructions from the Portal, which is located on Chain2 (Avalanche in our example).

Reverting Workflow (Scheme 4)

portal.metaRevertRequest() on Chain2 -> synthesis.revertBurnAndBurn() on the Host Chain -> portal.unsynthesize() on Chain1

If it fails, another transaction should be sent to Chain2 with revert instructions.

Scheme 4. Completing revert for Emergency Case 3.

Important notes for Scheme 4 (Case 3)

Step 1. The user signs a transaction that includes:

1. Calldata0: the sequence of steps to be executed on Avalanche.

2. Calldata1: the sequence of steps to be executed on the Host Chain. This calldata includes the estimated gas fee for the transaction execution on the Host Chain: GasEstimatedUSD1 .

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

Step2. Calling portal.metaRevertRequest()

Step 6. Only BridgeV2 is allowed to call synthesis.revertBurnAndBurn().

Step 7. Synthesis mints the number of sTokens equaling to GasEstimatedUSD1 approver in Step 1.

Step 9. The Oracle request contains a call to portal.unsynthesize()on Polygon. The parameters include the estimated gas fee value for Polygon:GasEstimatedUSD2

Step 11. Only BridgeV2 is allowed to call portal.unsynthesize().

Step 12. The amount approved in Step 1 is deducted from the amount of released tokens (Step 11) to refund the transaction fee paid by the relayers (Step 10). The remaining tokens are deposited to the user’s address on Polygon.

If it fails, the user should send another transaction to Chain2 with revert instructions (Step 1).

Cross-chain Operation: TXN0 (Chain1) → TXN1 (Host Chain)

If the Host Chain is the destination chain of a cross-chain operation (Cheme 5), then there are two transactions:

• TXN0 — on the source chain (Chain1)

• TXN1 — on the Symbiosis Host Chain

One failure scenario is possible:

• Emergency Case 4: TXN0 X TXN1

  • TXN0 completed successfully,

  • TXN1 failed.

Scheme 5. A cross-chain swap of GNS on Polygon for tokens on the Host Chain.

Emergency Case 4: TXN0 (Chain1) X TXN1 (S-chain)

Conditions and restrictions

• The user’s tokens are locked in Portal on Chain1 (Polygon in our example).

• Portal will only release the tokens if it receives a request from Synthesis, which is located on the Host Chain.

Reverting Workflow (Scheme 6)

synthesis.revertSynthesizeRequest() on the Host Chain -> portal.revertSynthesize() on Chain1

If it fails, another transaction should be sent to Host Chain with revert instructions.

Scheme 6. Revert scheme for Emergency Case 4.

Important notes for Scheme 6

Step 1. The user signs a transaction that includes:

1. Calldata0: the sequence of steps to be executed on the Host Chain.

2. Calldata1: the sequence of steps to be executed on Chain1 (Polygon in our example). This calldata includes the estimated gas fee for the transaction execution on Chain1: GasEstimatedUSD1.

Step2. Calling synthesis.revertSynthesizeRequest().

Step 6. Only BridgeV2 is allowed to call portal.revertSynthesize().

Step 7. The amount approved in Step 1 is deducted from the amount of released tokens (Step 6) to refund the transaction fee paid by the relayers (Step 5). The remaining tokens are deposited to the user’s address on Polygon.

If it fails, another transaction should be sent to the Host Chain with revert instructions (Step 1).

Cross-chain Operation: TXN0 (Host Chain) → TXN1 (Chain2)

If the Host Chain is the source chain of a cross-chain operation (Cheme 7), then there are two transactions:

• TXN0 — on the source chain (the Host Chain)

• TXN1 — on the destination chain (Chain2)

One failure scenario is possible:

• Emergency Case 5: TXN0 X TXN1

  • TXN0 completed successfully,

  • TXN1 failed.

Scheme 7. A cross-chain swap of USDT on the Host Chain for AVAX on Avalanche.

Emergency Case 5: TXN0 (Host Chain) X TXN1 (Chain2)

Conditions and restrictions

• The user’s tokens were exchanged for sTokens and burn on the Host Chain.

• Synthesis will only mint new sTokens if it receives a request from Portal, which is located on Chain2.

Reverting Workflow (Scheme 7)

portal.revertBurnRequest() on Chain2 -> synthesis.revertBurn() on the Host Chain

If it fails, another transaction should be sent to Chain2 with revert instructions.

Scheme 7. Revert scheme for Emergency Case 5.

Important notes for Scheme 7

Step 1. The user signs a transaction that includes:

1. Calldata0: the sequence of steps to be executed on Avalanche.

2. Calldata1: the sequence of steps to be executed on the Host Chain. This calldata includes the estimated gas fee for the transaction execution on the Host Chain.

The transaction is sent to Chain2 (Avalanche in our example).

Step 2. Calling portal.revertBurnRequest()

Step 6. Only BridgeV2 is allowed to call synthesis.revertBurn()

Step 7. The amount approved in Step 1 is deducted from the amount of minted tokens (Step 6) to refund the transaction fee paid by the relayers (Step 5). The remaining tokens continue to participate in the intermediate steps of the reverting operation.

If it fails, another transaction should be sent to Chain2 with revert instructions (Step 1).