🟪
Symbiosis & Emergencies
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).
Scheme 1. A cross-chain swap of GNS on Polygon for AVAX on Avalanche.
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 stablecoins on the blockchain that was the source one of the initial cross-chain operation. It will be of the stablecoin type that is used in the Symbiosis protocol on that blockchain (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 have to be sent (in most cases, this address is the same as the address from which the initial transaction was sent).
- Portal and Synthesis 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 within a single transaction.
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 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.
Reverting workflow in a nutshell (Scheme 2)
portal.metaRevertRequest() on Chain1 -> synthesis.revertSynthesizeRequestByBridge() on S-chain -> portal.revertSynthesize() again on Chain1If it fails, the user should send another transaction to Chain1 with revert instructions.
Scheme 2. Revert scheme for Emergency Case 1.
Important notes for Scheme 2
Step 1. The user signs a transaction that includes:
- 1.Calldata0: the sequence of steps to do on Polygon.
- 2.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:GasEstimatedUSDStep 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 Chain1If 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.
Scheme 3. Revert scheme for Emergency Case 2.
Important notes for Scheme 3
Step 1. The user signs a transaction that includes:
- 1.Calldata0: the sequence of steps to do on Avalanche.
- 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:
GasEstimatedUSD1in Scheme 3. - 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:
GasEstimatedUSD2in 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:GasEstimatedUSD2Step 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 Chain1If it fails, the user should send another transaction to Chain2 with revert instructions.
Scheme 4. Completing revert for Emergency Case 3.
Important notes for Scheme 4
Step 1. The user signs a transaction that includes:
- 1.Calldata0: the sequence of steps to do on Avalanche.
- 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:
GasEstimatedUSD1in Scheme 4. - 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:
GasEstimatedUSD2in 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:GasEstimatedUSD2Step 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).
Scheme 5. A cross-chain swap of GNS on Polygon for BOBA BNB on BOBA BNB.
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 Chain1If it fails, the user should send another transaction to S-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 do on S-chain.
- 2.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:
GasEstimatedUSD1in 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).
Scheme 6. A cross-chain swap of USDT on BOBA BNB for AVAX on Avalanche.
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-chainIf it fails, the user should send another transaction 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 do on Avalanche.
- 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:
GasEstimatedUSD1in 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).