Cowrie Research

bridge-deposit-truth-binding

15 min read

Bridge Deposit Truth Binding

  • Name: bridge deposit truth binding
  • Category: bridge reference / source-side custody-authenticity design / deposit-semantics checklist / protocol-comparison note
  • Summary: Healthy bridges do not ask relayers to infer locked value from ambient transaction context, ambiguous logs, helper-path folklore, or same denom name therefore same backing shortcuts. They force one source-side deposit security object to stay intact: the canonical emitter or source endpoint, the canonical custody-changing path, the measured asset delta, the exact credited amount, and the destination-facing asset identity / redeemability domain must all still describe the same event. Most deposit signal / locked-value mismatch incidents happen because one of those fields is reconstructed later from weaker artifacts such as tx.value, a shared event signature, a wrapped-native shortcut, or a handler assumption that no longer matches reality. The same failure can also appear when a real packet arrives over the wrong route or channel, but the bridge keys redeemability by bare denom name instead of by the full source-path-and-backing object.
  • Why this note exists:
    • Bridge truth as a single security object is the right top-level frame, but bridges also need a narrower source-side checklist for the moment a deposit first becomes relayable truth.
    • Incident notes like Qubit, Meter Passport, the two July 2021 THORChain ETH-router exploits, and the Secret / Axelar channel-mix-up case show that source-side authenticity can fail before any proof, signature, or destination-side release logic is even consulted.
    • The practical design question is simple: what exact source-side post-condition is a relayer, scanner, or watcher allowed to convert into bridge authority?

The five joints a healthy deposit artifact should keep fused

  1. Canonical emitter / source endpoint
    • The deposit signal must come from the exact contract, state machine, channel, lane, or source endpoint the bridge intends to treat as authoritative.
    • A generic event shape, helper contract, wrapper, refund path, compatibility shim, or merely allow-listed denom / asset label is not good enough by itself.
  2. Canonical custody-changing path
    • The signal must be authored only from the code path that actually performs the lock, burn, escrow increase, or wrapped-asset intake the bridge relies on.
    • If deposit-looking artifacts can also be emitted from refund, return, migration, or helper flows, the bridge is already leaking source-side authority.
  3. Measured value movement
    • The credited amount must be derived from real post-condition evidence: native-asset balance delta, token balance delta, canonical burn amount, or equivalent custody mutation.
    • Outer transaction msg.value, user-supplied amount fields, wrapper assumptions, or low-level call success are not adequate stand-ins.
  4. Exact credited amount, asset identity, and redeemability domain
    • The emitted deposit artifact should already say which asset moved, how much moved, and which source endpoint, channel, lane, or backing domain that movement belongs to, in the same semantic domain the destination side will later honor.
    • If native aliases, address(0) sentinels, wrapper placeholders, resource remaps, or same bare denom across different channels shortcuts can silently reinterpret that meaning, the bridge is not authenticating one deposit object anymore.
    • In IBC-style systems, this means bare denom allow-lists are not enough. The redeemable object is asset on this exact source path with this exact escrow domain, not just token whose printed denom string matches something familiar.
  5. Relayability under one meaning only
    • Relayers, scanners, or guardians should have exactly one safe interpretation of the artifact.
    • If a listener needs offchain folklore such as when the router is wrapped, tx.value still means deposit value or this event usually comes from the lock path, the bridge is already depending on social reconstruction rather than onchain truth.

Three bridge questions reviewers should not collapse

  1. Did value actually move into the canonical custody domain?
    • This is the Qubit / Meter / THORChain 2021-07-15 question.
    • The healthy check is whether the credited amount still comes from the bridge’s own lock, burn, wrap, or balance-delta post-condition rather than from event shape, wrapper convenience, or transaction-shell context.
  2. Which exact source-side path was allowed to publish deposit truth at all?
    • This is the THORChain 2021-07-22 question.
    • A bridge can still fail even if value moved somewhere nearby, if refund, return, migration, or helper flows can emit an artifact that downstream components interpret as fresh inbound authority.
  3. Which route’s backing domain did that truthful-looking artifact belong to?
    • This is the Secret / Axelar question.
    • A real packet or real transfer over the wrong channel, lane, or endpoint is still unsafe bridge truth if the destination later lets it mint or redeem against a different reserve bucket.

Healthy design keeps all three answers fused inside one deposit object. Most incidents in this family happened because teams answered only one of them and let the other two drift into folklore.

What sound design looks like

  • Emit after custody change, not before
    • Deposit-significant events should be emitted only after the lock, burn, wrap, or escrow-increase post-condition has succeeded.
    • If the event is emitted before the value movement is irrevocably known, the bridge has created a time window where logs can say more than custody does.
  • Measure what moved instead of trusting what was requested
    • For native assets, the safest reference is the value actually received by the canonical bridge contract or vault path, not the surrounding transaction shell.
    • For ERC-20s, the safest reference is a measured balance delta or a tightly verified transfer / burn result on the canonical token contract.
  • Keep materially different paths on materially different event surfaces
    • Native deposit, ERC-20 deposit, wrapped-native convenience, refund, migration, and vault-return flows should not share one relay-authoritative event schema unless they also share identical custody semantics.
    • Distinct code paths need distinct relay meanings.
  • Make wrapper compatibility explicit, not ambient
    • If a router or bridge core intentionally supports wrapper contracts, the deposit truth object must still be defined at the router or bridge core itself.
    • Wrapper composability is safe only when outer-call context cannot be mistaken for inner custody change.
  • Treat resource mapping, endpoint binding, and asset aliases like custody code
    • Native-asset sentinels, resource IDs, wrapped-token placeholders, registry entries, and channel / lane bindings are part of deposit semantics, not harmless metadata.
    • A mapping change that alters what a deposit event means or which endpoint is allowed to share redeemability is a security-boundary change.
  • Keep redeemability route-local until equivalence is proved, not presumed
    • If the same nominal asset can arrive over multiple channels, peers, or wrappers, the bridge should assume those routes have separate backing until it has explicit, machine-checked proof that they share one escrow and one unwind path.
    • Real packet is not enough if it came from a source path that was never entitled to spend against the destination reserve later released.
  • Define the relay contract in words as well as code
    • Operators and relayers should be able to answer: which exact event from which exact contract after which exact post-condition proves bridge-owned value increased by this exact amount of this exact asset?
    • If that sentence cannot be written unambiguously, the bridge does not yet have a safe deposit truth object.

Design questions worth asking first

  • What exact onchain post-condition proves the bridge now controls the credited amount?
  • Does the same contract that emits the deposit artifact also own or directly witness the custody change?
  • Can any helper, wrapper, refund, or migration path emit a bridge-looking deposit artifact under different semantics?
  • Is the credited amount measured from balance or burn outcomes, or reconstructed from calldata / msg.value / transaction shell context?
  • Can resource mappings, token aliases, wrapped-native convenience routes, or channel / endpoint bindings silently change what an existing deposit event means?
  • If relayers saw only the canonical artifact and canonical contract address, would they still infer the right asset and amount without operational folklore?

Red flags that usually mean deposit truth is already split

  • deposit() and depositETH() emit the same event even though only one path enforces value intake
  • wrapper compatibility depends on reading outer tx.value instead of inner bridge-contract receipt
  • the bridge records the user-requested amount rather than measuring the amount that actually entered custody
  • generic token paths accept sentinel addresses, no-code token contracts, or placeholder aliases that only make sense on a special native-asset route
  • multiple channels, lanes, or source endpoints can emit artifacts for the same wrapped asset without proving they share the same backing domain
  • allow-lists key voucher acceptance by bare denom or symbol while ignoring the source channel / path that determines which escrow bucket actually backs redemption
  • refund, return, recovery, or migration helpers can still emit artifacts that downstream components interpret as fresh deposits
  • relayer docs say watch the logs without specifying the exact custody-changing state transition those logs are supposed to certify

Failure-prevention checklist

  • Define one canonical relay-authoritative deposit artifact per custody model, and document the exact post-condition that must already be true before that artifact may exist.
  • Emit that artifact only from the code path that directly performs or directly witnesses the custody change the bridge will later redeem against.
  • Measure credited amount from bridge-observed balance delta, canonical burn result, or equivalent escrow mutation at the bridge boundary; do not reconstruct it later from calldata, outer transaction shell, helper return values, or wrapper assumptions.
  • Split materially different custody semantics onto materially different event and handler surfaces. Native deposit, ERC-20 deposit, wrapped-native convenience, refund, rollback, migration, and cross-channel receive paths should not share one relay meaning unless they truly share one custody invariant.
  • Treat sentinels, resource IDs, denom traces, channel bindings, wrapper placeholders, and asset aliases as part of deposit truth. Generic paths should reject values that are only meaningful inside narrower special-case routes.
  • Force relayers, watchers, and proposal builders to parse the stronger object. If they need external folklore to infer whether value really moved, the artifact is too weak to be bridge authority.
  • Review handler remaps, wrapper toggles, endpoint changes, and source-channel updates as security-boundary changes, not maintenance chores. Any such change can silently redefine what an old-looking deposit artifact now means.
  • Add route-aware reconciliation between source-side escrow or burn totals and destination-side liabilities quickly enough to catch counterfeit deposit truth before downstream markets absorb the fake inventory.
  • Bound blast radius beneath the deposit layer too: per-route mint caps, per-asset throttles, relayer quarantine, and fast pauses should assume a source-side artifact can still lie once.
  • Test all convenience and exceptional paths adversarially: wrappers, refunds, rollbacks, migrations, and helper contracts should never be able to author an artifact that downstream systems treat as fresh bridge-owned value unless they also satisfy the canonical custody invariant.

Audit prompts

  • What exact source-side state transition proves the bridge now controls redeemable value, and where is that fact measured rather than inferred?
  • Which contract and which function are allowed to author the relay-visible deposit artifact, and do they always coincide with the canonical lock, burn, wrap, or escrow-increase path?
  • Can two paths with different custody assumptions emit the same event or write the same deposit record? If yes, how is relayability kept unambiguous?
  • Does any path still derive credited amount from calldata, memo fields, outer msg.value, or wrapper context instead of from balance or burn outcomes at the bridge boundary?
  • Which sentinels, aliases, resource mappings, or channel bindings are only valid in special cases, and can a generic path accidentally inherit their meaning?
  • Can refund, rollback, migration, recovery, or admin-helper flows emit artifacts that honest relayers would mistake for new deposits?
  • What configuration or upgrade change would silently alter what an existing deposit artifact means: handler remap, token alias swap, denom binding, wrapper enablement, or endpoint replacement?
  • If the bridge receives a real packet or log from the wrong source contract, helper path, or channel, where is redeemability denied before mint or release logic ever runs?
  • Can monitoring explain, per route, why each destination liability increase still corresponds to one measured source-side custody increase or burn?
  • If one counterfeit deposit artifact lands, what concrete control stops the next hundred before operators must halt the whole bridge?

Lessons that should already be standard

  • A deposit artifact is only as strong as the custody post-condition behind it. Event emitted is not bridge truth unless the bridge can already prove value moved on the canonical path.
  • Source-side ambiguity is still bridge-authenticity failure. Honest relayers and correct destination contracts cannot rescue a bridge whose first authoritative fact was under-constrained.
  • Convenience paths are part of the trust boundary. Wrapped-native helpers, generic token handlers, refund rails, and migration utilities routinely become counterfeit-deposit surfaces because teams treat them like ergonomics instead of custody code.
  • Asset identity is inseparable from deposit truth. A measured amount is not enough if aliases, channel drift, or endpoint remaps can later reinterpret what reserve or redeemability domain that amount belonged to.
  • In channel-based systems, a real packet over the wrong channel is still counterfeit deposit truth if the bridge lets that packet inherit redeemability against a different escrow bucket.
  • Distinct custody semantics deserve distinct relay semantics. Sharing one event surface across materially different paths usually shifts safety from code into folklore.
  • The right question is not can relayers see the deposit? but can any honest listener recover emitter, path, amount, asset, and backing domain from one canonical object without guessing?
  • Route-aware reconciliation and route-local brakes are part of deposit design, not just operations. By the time fake bridge inventory has spread into lending venues or AMMs, the source-side ambiguity has already become system-wide loss.
  • The safest source-side bridge design is boring: one canonical custody path, one measured post-condition, one unambiguous artifact, and no helper route that can author equivalent truth on cheaper terms.

Why this control matters

  • This control is where a bridge decides whether a user action becomes money-good bridge truth or stays just another call attempt. If the deposit artifact is weaker than the custody fact it is supposed to certify, every downstream verifier, relayer, and mint path inherits that lie.
  • The practical bridge failure is often upstream of proofs and signatures: honest relayers can still mint against fiction when the source-side deposit object overclaims what actually entered escrow, burned, or wrapped.
  • Deposit truth is also the seam where small convenience features become protocol-scale liabilities. Generic token paths, wrapped-native shortcuts, ambient msg.value, resource remaps, and route aliases all look ergonomic until one of them can still publish redeemable value without the canonical custody change.
  • The note matters most during route evolution and feature expansion. Every new helper path, wrapper, channel, or asset alias is really a question about whether the bridge still has one deposit object or has started reconstructing deposit truth from folklore again.
  • Route-local reconciliation and caps belong here for the same reason: by the time fake bridge inventory has spread into lending markets, AMMs, or offchain redemption queues, the deposit-control failure has already escaped the bridge boundary.

How to use this note with the exploit corpus

  • Start here when the question is what should a source-side bridge deposit artifact have proved before any relayer treated it as authority?
  • Drop into locked-value mismatch when you need the exploit-family anatomy for cases where source-side deposit bookkeeping drifted away from real locked value.
  • Narrow into Message-source authentication failure when the sharper failure is who was allowed to author the bridge-looking artifact at all?
  • Pair with Bridge source-provenance bundle and authoring-surface discipline when the sharper design question is not just did value move? but which exact contract, channel, and handler path was even allowed to publish deposit truth for this route?
  • Pair with Bridge canonical-path exclusivity and stale authoring-surface deauthorization when the sharper design question is why a stale generic path, wrapper, or helper rail could still emit the same deposit-significant artifact after the bridge had already identified a healthier canonical lane.
  • Pair with Bridge route-local redeemability domain discipline when the sharper design question is why a real packet, voucher, or deposit artifact from one route was allowed to inherit redeemability against another route’s reserve domain.
  • Go back up to Bridge truth as a single security object when the question expands from deposit semantics to the whole bridge authenticity object, including exact message commitment, asset identity, and verifier independence.
  • Pair with Bridge bounded release design when you want the separate containment question of how much one bad deposit-truth event should ever be able to release or mint.

Internal linkages

Control surface

Graph View

Backlinks