Cross-Chain Swap Tracking: Build Reliable Status Updates
Cross-chain swap tracking is the process of turning activity across multiple blockchains into one clear status for an application or user. The key condition is that a source-chain transaction can succeed while a later destination-chain step is still pending or fails.
Represent Each Leg, Not One Boolean
A cross-chain swap is a sequence of events, so store its progress as a state machine rather than a single “done” flag. A practical model includes route accepted, source transaction submitted, source transaction confirmed, intermediate transfer pending, destination transaction observed, and completed or failed; use “needs review” for cases your system cannot resolve automatically.
Keep a record for each leg with its chain identifier, transaction hash or protocol message identifier, observed status, and observation time. The user-facing swap can then be derived from those records: “source confirmed; destination pending” is more informative than “processing,” and it does not claim the funds arrived before you have evidence.
For example, imagine an integrator’s customer sends tokens from an EVM chain to a Cosmos chain through an aggregated route. The source transaction gets a successful receipt, but the destination transfer has not completed. The app should preserve the source success and report the transfer as pending, rather than retrying the original swap and risking a duplicate action.
Polling: Simple and Easy to Recover
Polling means periodically querying a chain node or indexer for the transaction or event you expect. It is a good fit for low-volume integrations, prototypes, and recovery jobs because it is straightforward to implement and can resume after a process restart; it becomes inefficient when many swaps require frequent checks.
On Ethereum-compatible chains, query eth_getTransactionReceipt using the source transaction hash. The official Ethereum JSON-RPC documentation says a pending transaction has no receipt and the method returns null when no receipt is found; a receipt’s status distinguishes success from failure. Treat a receipt as evidence for that transaction only. It does not prove that a bridge or destination execution has finished.
Poll with a bounded backoff, such as checking after a few seconds, then waiting longer between later checks. Those intervals are implementation examples, not chain guarantees: tune them to the user experience you need and your RPC provider’s limits. Set a deadline for active polling, then move the swap to a delayed state and continue through a background reconciliation job instead of polling indefinitely.
Events and Indexers: Better at Scale
An event-driven tracker consumes new blocks or indexed contract events and updates affected swaps as soon as relevant activity appears. It suits production services with many concurrent swaps, since one stream can update many records without repeatedly asking about each transaction; it takes more work to operate and recover reliably.
Persist a cursor such as the last processed block number, and make event handling idempotent: processing the same event twice must not complete a swap twice. If the stream disconnects, replay from the saved cursor and deduplicate by chain, transaction hash, and log index. Also reconcile periodically against chain data; a WebSocket connection can miss updates while your service is offline.
When an aggregated route is involved, the integration still needs its own consistent status model across route steps. A Rango bridge swap is one way to handle a cross-chain transfer through a routing service; your application should show what it has verified about the source and destination legs, rather than infer completion from the initial submission.
Protocol Signals: Use Them as Evidence
Protocol-specific messages can provide stronger evidence of progress than a source-chain receipt alone. For IBC transfers, track the packet lifecycle and acknowledgement: an acknowledgement communicates the receiving application’s result, while a timeout signals that the packet was not acknowledged within its allowed window. This approach is best when your route uses IBC and you can reliably associate the packet with the user’s swap.
Protocol signals do not replace transaction tracking. A packet event or acknowledgement belongs to a particular transfer; it may not cover a later swap or execution step in a multi-hop route. The IBC-Go documentation on packets and acknowledgements is a useful reference for those semantics. For other bridges, identify the specific message or event that constitutes delivery, and do not assume all protocols use IBC’s acknowledgement model.
Keep one short safety rule in the implementation: verify events against the expected chain, contract, and swap identifiers before changing user-visible status. Reorganizations can also change recently observed chain data, so distinguish an included transaction from one your application considers sufficiently final. Define that threshold per chain and risk tolerance; there is no single confirmation count suitable for every network.
For the next step, implement the per-leg state record and choose a tracking source for each chain: polling for a small integration, or an event stream with replay and reconciliation for higher volume. Then test the slow path, including a successful source transaction with a delayed destination leg, before presenting “completed” to users.