In cross-chain transfers, failures are inevitable. They can be caused by network issues, smart contract errors, or insufficient gas fees, which may prevent the transaction's completion.

This lesson will explore common failure scenarios and how to handle them properly.

1. Why Can Cross-Chain Transfers Fail?

A Wormhole cross-chain transfer involves several steps, and a failure at any stage can result in an incomplete transaction.

Common failure causes include:

1.Missing VAA – The Guardian network hasn’t confirmed the message, so the destination chain can’t process it.

2.Insufficient gas – The user didn’t provide enough gas, leading to transaction stalling or reversion.

3.Execution failure on the destination chain – Smart contract errors, such as wrong contract address or insufficient balance.

4.RPC timeout – Network congestion or overloaded nodes prevent broadcasting or confirmation.

2. How Can We Detect a Failed Transaction?

Currently, our API initiates the cross-chain transfer and staking but does not confirm the transaction status.

We can use the Wormhole API to query the VAA status after submission to make the system more reliable.

📌 Optimization Strategy:

●Poll the VAA status every 5 seconds to check if it has been confirmed

●If not confirmed after 60 seconds, treat it as a failure and trigger a retry

3. Code Optimization: Checking Wormhole Transaction Status

We can enhance our API by adding a VAA status check after each transfer, ensuring the transaction is complete before moving forward.

📌 Modify executeCrossChainTransfer() to include Wormhole status verification:

💡 This logic will:

●Check the status every 5 seconds (up to 60 seconds total)

●If VAA is still not confirmed, treat the transaction as failed

4. What to Do When a Transfer Fails

When a failure is detected, consider these strategies:

✅ Notify the user to wait (if the issue is due to temporary network delay)

✅ Trigger a retry mechanism (e.g., automatically increase gas and retry if applicable)

✅ Log the failure reason (for future debugging and analytics)

📌 Example: How to Handle a Failed Transfer in an API Endpoint