Crosschain packets: prove completion, timeout or pending status
An IBC acknowledgement can report an application error. A timeout deadline can pass before a timeout is processed. A refund can be described by the protocol while its actual receipt still needs verification. Crosschain asset research must therefore separate packet transport, application result and asset settlement.
Use a packet-level ledger rather than a single completed flag. The goal is to determine what happened to each original transfer amount without treating every ACK as successful delivery or every expired timestamp as recovered assets.
Fix the specification and deployment scope
This worksheet reads ICS-004 Channel and Packet Semantics and ICS-020 Fungible Token Transfer v1 at the complete pinned commit bdfe570beb5cec017da89ce08e7b87ae2bd34a38.
The documents are reference evidence, not a compatibility certificate for any live deployment. The ICS-20 page lists ibc-go v10.0.0 and ibc-rs v0.53.0, while the ICS-4 page lists ibc-go v7.0.0. A real investigation must match actual core and application implementations and the negotiated channel version instead of assuming those headers certify every combination.
ICS-4’s Synopsis treats channels as payload-agnostic. Its transport semantics do not independently establish what a token application’s acknowledgement means. The pinned ICS-20 Data Structures and Routing module callbacks provide the application layer used in the hypothetical examples below.
Give every packet a reproducible identity
Store source chain, source port, source channel and sequence, together with the destination identifiers and packet bytes. A sequence alone is not globally unique. Do not merge packets from different channels because their sequence numbers or amounts match.
Preserve denomination trace, raw amount, sender, receiver, timeout height and timeout timestamp. To compare quantities across chains, establish the applicable denomination and conversion relationship first. Matching symbols are insufficient.
Retain separate source and destination block references. Independently advancing chains do not offer one universal simultaneous timestamp. A research cutoff should describe which state was checked on each side and which messages or proofs remained outstanding.
Read acknowledgements at both layers
The pinned ICS-20 acknowledgement data structure distinguishes a success result from an error string. Keep the raw application acknowledgement and decode it under the actual application format. The presence of bytes or a transport acknowledgement event does not distinguish success from error by itself.
Also distinguish an acknowledgement written on the receiving side from its proof being processed on the sending side. The latter can trigger application logic relevant to a refund. A screenshot of a destination ACK does not establish that the source completed its related transition.
The reference document contains both a structured acknowledgement schema and illustrative callback pseudocode. For a real decoder, verify the deployed serialization and implementation; do not treat a pseudocode success member as the universal wire field. Preserve unknown or malformed messages instead of interpreting them optimistically.
A hypothetical four-packet reconciliation
Assume a fictional compatible setup implementing the relevant ICS-20 transfer behavior. All quantities below are normalized original-asset units with an established one-to-one relationship. No transfer tax, middleware fee or denomination mismatch is assumed. Four packets send a total of 100 units.
| Packet | Amount | Transport result at the cutoff | Application result | Verified asset outcome |
|---|---|---|---|---|
| P1 | 60 | ACK processed on source | Success acknowledgement | Receiver has 60 |
| P2 | 10 | ACK processed on source | Error acknowledgement | Sender’s 10-unit refund verified |
| P3 | 15 | Timeout processed with required evidence | Timeout callback | Sender’s 15-unit refund verified |
| P4 | 15 | No terminal result verified | Unresolved | Keep 15 pending |
There are two acknowledged packets, one timed-out packet and one unresolved packet. The corresponding amount totals are 70 acknowledged, 15 timed out and 15 pending. These are amounts attached to states, not seventy acknowledged packets.
The asset reconciliation is different: 60 delivered + 10 refunded after error + 15 refunded after timeout + 15 unresolved = 100. Completed refunds total 25, so delivered plus refunded is 85, leaving 15 unresolved.
Calling the 70 acknowledged units successfully received would overstate confirmed delivery by 10. Calling every non-delivered unit lost would wrongly include the 25 already refunded. The four-column ledger prevents both errors.
Trace the refund through application behavior
The pinned ICS-20 callbacks describe refund handling for an error acknowledgement and for timeout. Its refundTokens logic distinguishes returning escrowed source assets from restoring vouchers in the relevant direction. Inspect which branch applies rather than assuming every refund is a transfer of the same native token on every chain.
For P2 and P3, save the processed source transaction, application result and actual sender balance or receipt evidence for the appropriate denomination. A protocol-defined refund path is useful mechanism evidence, but the ledger’s verified-refund column needs the observed outcome too.
Do not add a refund and the original locked amount as two independent assets. When reconciling economic supply, preserve the technical stages and eliminate duplicated claims under the actual transfer mechanism. This packet worksheet establishes settlement status; it does not by itself audit the whole bridge’s backing.
Different boundary: the deadline passed, nothing was processed
Suppose P4’s stated deadline has passed on the relevant counterparty context, but no verified timeout transition or refund has been obtained. Keep it pending at the research cutoff. Clock passage is not the same event as a successful timeout transaction.
The pinned ICS-4 timeout discussion requires evidence that the packet cannot still be received under the applicable channel rules. The correct proof and state transition matter. An unavailable destination query or an explorer showing no event is not automatically a verified non-receipt proof.
If the deadline condition, timeout processing and refund occur at three different observations, save three dates. Do not backdate the refund to the deadline or extend a later recovery into a claim that assets were continuously accessible throughout the gap.
Different boundary: delivery succeeded but the acknowledgement lags
A packet can have destination application evidence before the corresponding acknowledgement is processed on the source. In such a case, report the destination asset receipt as observed and the source transport state as outstanding. Do not force them into a single success flag or count the same amount as two settlements.
Conversely, an error acknowledgement may be known while its source-side refund remains unverified. Keep error result and refund status separate. A mechanism that should refund is not a substitute for the missing receipt evidence.
Middleware can introduce further actions or acknowledgement semantics. If present, inspect the actual negotiated stack and implementation. Do not apply the simple four-packet quantities unchanged when fees, forwarding or other application behavior alters the relationship between sent and received units.
Keep evidence completeness separate from expected behavior
If P2 has a verified error acknowledgement but its ten-unit refund has not been observed, reduce verified refunds from 25 to 15. Delivered plus verified-refunded is then 75, with ten awaiting refund evidence and fifteen otherwise unresolved. Do not keep the original 85 resolved total merely because the protocol describes a refund path.
Build the cohort from original send records, not just current outstanding commitments. A missing commitment can reflect a later processed transition rather than a packet that never existed. Preserve the historical packet identity and terminal evidence together. Otherwise a query of only outstanding state can omit the very acknowledged or timed-out packets needed to reconcile the original hundred units.
Check serialization at the application boundary. The pinned ICS-20 text specifies JSON for its packet and acknowledgement data, while ICS-4 also discusses a suggested generic acknowledgement envelope. A single universal decoder should not silently replace the deployed application’s format. Retain bytes, selected schema and decode errors together.
A release checklist for packet evidence
| Action | Preserve | Stop condition |
|---|---|---|
| Match the implementation | Core, application and channel-version evidence | Reference headers are the only compatibility argument |
| Fix packet identity | Chains, ports, channels, sequence and bytes | Sequence is being treated as globally unique |
| Decode the application ACK | Raw result or error under the deployed schema | Any ACK is being called delivery |
| Verify source processing | ACK or timeout transition and supporting proof | Only a destination event or passed deadline exists |
| Verify the asset outcome | Correct denomination, recipient and amount | Refund or receipt is only expected |
| Reconcile the cohort | Delivered, refunded and unresolved original units | States overlap or quantities disappear |
Reopen the ledger after an acknowledgement is relayed, timeout evidence arrives, a refund is observed or denomination interpretation changes. Publish transport state, application outcome and actual asset location separately. A pending status is an actionable evidence gap, not a prediction of permanent loss or a guarantee of eventual recovery.
FAQ
Does any acknowledgement prove tokens arrived successfully?
No. The application acknowledgement can contain an error. Decode it and verify the asset outcome.
Does a passed timeout automatically mean the sender received a refund?
No. Timeout conditions, processing and observed refund are separate facts with their own evidence and dates.