Symbiosis & Emergencies
Last updated
Last updated
Let's consider a cross-chain swap: GNS on Polygon for AVAX on Avalanche, as an example of a cross-chain operation (Scheme 1).
That cross-chain swap consists of three transactions:
TXN0 on Polygon (the source chain of the cross-chain swap),
TXN1 on Boba BNB (S-chain),
TXN2 on Avalanche (the destination chain of the cross-chain swap).
Since every cross-chain operation is a sequence of transactions that should be executed one by one on different blockchains, there is always a chance that something could go wrong. For instance, the time set for a cross-chain operation may have expired, or the exchange rates in one of the DEXes may have changed, and the transaction cannot be executed due to an unacceptable slippage change.
An emergency means that the transaction has been processed on the source blockchain, but there is no transaction on the destination blockchain, or the transaction has failed.
There has to be a way to handle such cases. Moreover, users should be able to handle emergencies themselves, since the Symbiosis protocol is a DeFi protocol. A stuck cross-chain operation cannot be completed in most cases (the time is over, rates have changed, etc.). Therefore, the Symbiosis protocol does not have this functionality. Instead, the Symbiosis protocol allows users to revert stuck cross-chain operations. Let’s see how it works.
Notes common to all reverting cases
When a reverting operation is completed, the user receives tokens on the blockchain that was the source one of the initial cross-chain operation. The user will receive the tokens of the type :
Stablecoins if the initial operation used the bridging on stablecoins or
WETH if the initial operation used the bridging on WETH. So it will be of the token type that is used for bridging in the Symbiosis protocol (USDC on Polygon in our example), even if the initial token was different (Scheme 1).
The initial cross-chain operation contains an address from which transactions with reverting instructions must be sent (in most cases, this address is the same as the address from which the initial transaction was sent).
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.
If the initial transaction was routed using bridging on stablecoins then reverting will also use bridging on stablecoins. If the initial transaction was routed using bridging on WETH then reverting will also use bridging on WETH.
All explanations below are for the cases where the initial transaction was routed using bridging on stablecoins.
If a cross-chain operation looks like this TXN0 (on Chain1) → TXN2 (on S-chain) → TXN3 (on Chain2), then two emergency cases are possible:
Emergency Case 1: TXN0 X TXN1 -> TXN2 TXN0 completed successfully, TXN1 failed, and TXN2 was not even created.
Emergency Case 2: TXN0 -> TXN1 X TXN2 TXN0 and TXN1 completed successfully, TXN2 failed.
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 Boba BNB (S-chain).
The most natural way to initiate reverting is to send a transaction to Boba BNB, but the user may not know about the S-chain, has no native cryptocurrency there, and wants to know nothing about this blockchain. So to improve the UX, the scheme explained below was introduced.
Reverting workflow in a nutshell (Scheme 2)
portal.metaRevertRequest() on Chain1 -> synthesis.revertSynthesizeRequestByBridge() on S-chain -> portal.revertSynthesize() again on Chain1
If it fails, the user should send another transaction to Chain1 with revert instructions.
Important notes for Scheme 2
Step 1. The user signs a transaction that includes:
Calldata0: the sequence of steps to do on Polygon.
Calldata1: the sequence of steps to do on S-chain. This includes an estimated gas fee value in the USD equivalent for Polygon:GasEstimatedUSD
This case is the only case when users do not refund gas fee on S-chain.
Step 2. Calling portal.metaRevertRequest()
Step 6. Only BridgeV2 can call synthesis.revertSynthesizeRequestByBridge().
Step 8. The oracle request contains a call to portal.revertSynthesize()on Polygon. The parameters include the estimated gas fee value in the USD equivalent for Polygon:GasEstimatedUSD
Step 10. Only BridgeV2 can call portal.revertSynthesize()
Step 11. 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 9). The remaining stablecoins are deposited to the user’s address on Polygon.
If it fails, the user should send another transaction to Chain1 with revert instructions (Step 1).
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 Boba BNB (S-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 in a nutshell (Scheme 3)
portal.metaRevertRequest() on Chain2 ->
synthesis.revertMetaBurn() on S-chain ->
synthesis.metaBurnSyntheticToken() on S-chain ->
portal.metaUnsynthesize() on Chain1
If the reverting operation fails between Chain2 (Avalanche in our example) and S-chain, the user should send another transaction to Chain2 with revert instructions (Step 1).
If the reverting operation fails between S-chain and Chain1 (Polygon in our example), see the subcase.
Important notes for Scheme 3
If the initial transaction was routed using bridging on stablecoins then reverting will also use bridging on stablecoins. If the initial transaction was routed using bridging on WETH then reverting will also use bridging on WETH.
Step 1. The user signs a transaction that includes:
Calldata0: the sequence of steps to do on Avalanche.
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.
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.
The transaction is sent to Chain2 (Avalanche in our example).
Step 2. Calling portal.metaRevertRequest()
Step 6. Only BridgeV2 can 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 in the USD equivalent for Polygon:GasEstimatedUSD2
Step 14. Only BridgeV2 can call portal.metaUnsynthesize(). Stablecoins are released at a 1:1 ratio with 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 stablecoins are deposited to the user’s address on Polygon.
If the reverting operation fails between Chain2 (Avalanche in our example) and S-chain, the user should send another transaction to Chain2 with revert instructions (Step 1).
If the reverting operation fails between S-chain and Chain1 (Polygon in our example), see the subcase.
Conditions and restrictions
There was an attempt to revert a cross-chain operation (Case 2). That reverting operation was stuck on S-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 BOBA BNB (S-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 in a nutshell (Scheme 4)
portal.metaRevertRequest() on Chain2 ->
synthesis.revertBurnAndBurn() on S-chain ->
portal.unsynthesize() on Chain1
If it fails, the user should send another transaction to Chain2 with revert instructions.
Important notes for Scheme 4
Step 1. The user signs a transaction that includes:
Calldata0: the sequence of steps to do on Avalanche.
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.
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 4.
Step2. Calling portal.metaRevertRequest()
Step 6. Only BridgeV2 can 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 in the USD equivalent for Polygon:GasEstimatedUSD2
Step 11. Only BridgeV2 can 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 stablecoins 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).
If a cross-chain operation looks like this (Cheme 5) TXN0 (on Chain1) → TXN1 (on S-chain), then one emergency case is possible:
Emergency Case 4: TXN0 X TXN1 TXN0 completed successfully, TXN1 failed.
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 BOBA BNB (S-chain).
Reverting workflow in a nutshell (Scheme 6)
synthesis.revertSynthesizeRequest() on S-chain ->
portal.revertSynthesize() on Chain1
If it fails, the user should send another transaction to S-chain with revert instructions.
Important notes for Scheme 6
Step 1. The user signs a transaction that includes:
Calldata0: the sequence of steps to do on S-chain.
Calldata1: the sequence of steps to do on Chain1 (Polygon in our example). This calldata includes the estimated gas fee for the transaction execution on Chain1 in the stablecoin equivalent: GasEstimatedUSD1 in Scheme 6.
Step2. Calling synthesis.revertSynthesizeRequest().
Step 6. Only BridgeV2 can 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 stablecoins are deposited to the user’s address on Polygon.
If it fails, the user should send another transaction to S-chain with revert instructions (Step 1).
If a cross-chain operation looks like this (Cheme 6) TXN0 (on S-chain) → TXN1 (on Chain2), then one emergency case is possible:
Emergency Case 5: TXN0 X TXN1 TXN0 completed successfully, TXN1 failed.
Conditions and restrictions
The user’s tokens were exchanged for sTokens and burn on BOBA BNB.
Synthesis will only mint new sTokens if it receives a request from Portal, which is located on Chain2.
Reverting workflow in a nutshell (Scheme 7)
portal.revertBurnRequest() on Chain2 ->
synthesis.revertBurn() on S-chain
If it fails, the user should send another transaction to Chain2 with revert instructions.
Important notes for Scheme 7
If the initial transaction was routed using bridging on stablecoins then reverting will also use bridging on stablecoins. If the initial transaction was routed using bridging on WETH then reverting will also use bridging on WETH.
Step 1. The user signs a transaction that includes:
Calldata0: the sequence of steps to do on Avalanche.
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 7.
The transaction is sent to Chain2 (Avalanche in our example).
Step 2. Calling portal.revertBurnRequest()
Step 6. Only BridgeV2 can 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 stablecoins continue to participate in the intermediate steps of the reverting operation.
If it fails, the user should send another transaction to Chain2 with revert instructions (Step 1).
