Why bridge integrations should separate settlement from delivery

A bridge integration should record settlement on the source chain separately from delivery on the destination chain, because those events can happen at different times. Settlement means the source transfer has met the bridge’s rules for acceptance; delivery means the destination chain has completed the corresponding action. Treating them as one event hides delays and failures from both the app and the person waiting for funds.

What is the difference between settlement and delivery?

Settlement confirms that a transfer is accepted by the source side of a bridge, while delivery confirms that its effect has arrived on the destination side. Depending on the bridge, that effect may be a token transfer, a message to a contract, or both. A source transaction can be settled even when the destination transaction has not yet run.

The gap exists because chains do not share one transaction system. A bridge or its relayers (services that pass messages between chains) must observe the source event, meet the bridge’s verification rules, then submit or execute the destination action. Each step has its own timing and failure conditions.

That distinction matters even when the user sees one “bridge” button. A confirmation on the source chain is evidence that the transfer started and passed a particular stage; it is not proof that the destination wallet can already use the asset. For a route-specific overview, the mantle bridge guide covers choices users face when moving funds. An integration still needs to show the progress of the chosen route clearly.

Why should an app track the two stages separately?

Separate states let an app tell users what has happened and what remains. If the source transaction settles but the destination transaction is delayed, the app can show “sent, awaiting delivery” instead of calling the transfer complete or making it look lost.

It also gives support teams and monitoring systems a useful point to investigate. A settled transfer with no delivery calls for checking message processing or destination execution. A transfer that never settles points back to the source transaction, its confirmations, or the bridge’s acceptance rules. Those are different problems and need different responses.

Apps can represent the stages with a small set of explicit states:

• Submitted: the source transaction was sent, but settlement is not yet confirmed.
• Settled: the source-side transfer passed the required checks.
• Delivering: the destination action is pending or being attempted.
• Delivered or failed: the destination effect completed, or the app needs to explain the failure and next step.

The exact labels can vary. The important part is that “complete” means the destination effect actually happened, not merely that the source transaction was accepted. If a bridge defines settlement differently, the integration should use that bridge’s documented lifecycle rather than assuming every route uses the same checkpoints.

What can go wrong if the stages are combined?

If an app marks a transfer complete at settlement, users may see a successful status before funds are available on the destination chain. They may try to spend tokens that have not arrived, repeat the transfer, or contact support because the app’s claim conflicts with their wallet.

The reverse mistake is also costly: keeping a transfer in a generic pending state until delivery hides useful progress. A user cannot tell whether the source chain has accepted the transaction or whether it is still waiting for confirmation. The app also loses the ability to show where a delay occurred.

Delivery can fail after settlement for reasons that are specific to the destination step. A destination contract might reject a call, a transaction might run out of gas, or the route may require another action. The integration should distinguish a failed delivery from an unsettled transfer and show whether a retry is possible. It should not promise that every failure can be retried or that a retry is safe.

Retries need care because the same message can be submitted more than once. Integrations should use the bridge’s identifiers and replay protections so that retrying delivery does not accidentally credit or execute the same transfer twice. They should also avoid treating a timeout alone as proof of failure: the destination action may still be processing.

How should teams design the integration?

Teams should model source settlement and destination delivery as separate, linked records. Each record needs a stable reference to the transfer and enough information to look up its status, such as the source transaction and the bridge’s message identifier when available.

Build the user-facing status around what the system can verify. Show the source transaction while it is awaiting settlement, then keep the transfer visible as it moves toward destination delivery. If delivery fails, explain what failed and provide the next supported action. Avoid suggesting that users resubmit the whole transfer unless the bridge’s rules say that is the right remedy.

For most integrations, the clearest design is to treat settlement as a milestone and delivery as the completion condition. That keeps the internal model honest, gives support a way to locate delays, and lets users understand whether their funds have arrived. The bridge handles cross-chain mechanics; the app’s job is to report each stage accurately.