Cowrie Research

settlement-envelope-truth-security-object

17 min read

Settlement Envelope Truth as a Single Security Object

  • Name: settlement envelope truth as a single security object
  • Category: settlement-systems reference / protocol-authored-context authenticity checklist / router-and-callback design note / execution-envelope reference
  • Summary: Healthy settlement does not ask downstream resolvers, adapters, pools, or callback consumers to trust whatever blob the router just handed me. It keeps one machine-readable settlement envelope intact from route selection through final token movement: the canonical counterparty or pool identity, the payer or inventory source, the exact asset and amount semantics, the execution stage or callback being settled, and the exact bytes that are supposed to be protocol-authored rather than attacker-authored. Just as importantly, if one narrower fallback or degraded settlement lane must stay live, that lane should inherit a smaller payer, destination, and inventory budget than healthy-mode routing rather than silently becoming ordinary spend authority because it is the only path left. This note exists to keep that positive design target explicit instead of making readers reconstruct it only by inverting incidents like 1inch Fusion V1 or fake-pool callback drains.
  • Why this note exists:
    • Several settlement incidents do not begin with victim contract forgot access control; they begin earlier, when a downstream consumer authenticated the wrong object.
    • The useful question is often not did the callback caller look right? but what exact settlement envelope was the downstream consumer allowed to treat as protocol truth?
    • Routers, resolvers, and callback-driven adapters stay safest when the answer is one explicit envelope whose author, shape, route stage, and decisive fields are all machine-checkable.

The six joints a healthy settlement envelope should keep fused

  1. Canonical settlement author

    • The system needs one unambiguous answer to who is allowed to author the envelope the downstream consumer will trust.
    • The router called me is not enough if the router can still forward attacker-shaped context as if it were its own authenticated truth.
    • This is the joint that fails when a consumer trusts bare caller identity but never proves which fields the caller was actually entitled to author.

  2. Counterparty / pool / market identity

    • The envelope must bind the exact pool, market, resolver, option series, or venue being settled.
    • A healthy system does not let some callback arrived stand in for the canonical pool for this exact route and stage called.
    • This is the joint that breaks in callback-origin-authentication-failure.

  3. Payer or inventory source identity

    • The envelope must bind who is paying: the user, the router, the resolver inventory, a flash-swap pair, or some other inventory bucket.
    • Settlement systems fail when they let an attacker smuggle who should fund this debt through route bytes, spoofed callback data, or corrupted appended suffixes.
    • A downstream consumer should be able to say exactly why this payer was entitled to become the funding source for this settlement step.

  4. Asset and amount semantics

    • The envelope must bind which tokens, deltas, or notional amounts are being settled and in what direction.
    • These bytes decode to token/amount pairs is weaker than these are the same token/amount semantics the protocol itself authenticated for this route.
    • This is where forged output lists, fake deltas, and impossible maker/taker economics become real token loss.

  5. Execution stage and callback meaning

    • The envelope must bind which stage of execution is happening: swap callback, resolver finalization, bridge release, flash-settlement payback, or some other bounded phase.
    • The same target or pool can be safe in one stage and dangerous in another if the meaning of the bytes changes.
    • Healthy systems do not let one generic execute settlement surface infer stage semantics from attacker-shaped calldata alone.

  6. Exact serialized layout and version

    • The envelope must keep one stable answer to which bytes are protocol-authored, where they live, and which parser version will consume them.
    • If user-controlled lengths, offsets, compatibility shims, or nested blobs can move those fields around, the protocol no longer has one trusted settlement envelope at all.
    • This is the joint that breaks in trusted-execution-envelope-corruption.

Three settlement-envelope questions healthy systems should answer separately

  1. What exact committed settlement envelope exists for this route or stage?
    • Teams should be able to name one concrete object covering author, counterparty, payer, token semantics, stage, parser version, and any route-local inventory bounds.
    • If different components answer with different mixtures of callback bytes, route state, suffix conventions, and local storage, the envelope is already split.
  2. What proves that envelope is still the canonical protocol-authored truth the downstream consumer is using?
    • The healthy question is not only did the bytes decode? but what proves the consumer is still reading the exact protocol-authored fields, in the exact layout and stage meaning the route committed?
    • Canonical-pool recomputation, precommitted payer state, parser-version checks, and bounds-safe suffix construction belong here because they decide whether the named envelope still describes reality.
  3. What authority budget does that accepted envelope still deserve right now?
    • Even once envelope authenticity holds, teams should still say what payer scope, approval reach, inventory bucket, destination set, and degraded-mode spend budget those bytes are allowed to exercise.
    • That last authority question is why degraded routing and fallback settlement should become deliberately smaller lanes instead of inheriting ordinary healthy-mode spend power just because the envelope is still syntactically valid.

What sound design looks like

  • One protocol-authored envelope, one downstream-consumed envelope

    • The bytes or typed fields a downstream consumer trusts should be the same object the protocol actually authenticated.
    • If the consumer must guess which parts are trustworthy, the security boundary has already split. Healthy systems keep separate answers for what envelope exists, what proves it is still canonical protocol truth, and what authority that accepted envelope still deserves now.

  • Critical settlement facts should be re-derived where possible

    • Canonical pool address, fee tier, token ordering, resolver identity, or allowed payer should be recomputed from trusted local state instead of merely decoded from callback bytes.
    • The safest settlement systems treat external bytes as claims to verify, not as finished truth.

  • Typed commitments beat ad hoc suffix folklore

    • Stronger designs keep settlement context in typed structures, hash-committed route objects, or other machine-checkable commitments rather than hand-built memory layouts and informal append-only suffix conventions.
    • If a protocol must append context dynamically, the downstream consumer still needs a way to prove that the live bytes match the intended committed object.

  • Stage-local context should be recorded before external control leaves

    • Callback consumers should trust data recorded in local state before the external pool or counterparty call, not data reconstructed afterward from attacker-controlled callback bytes.
    • The key property is that the system can still answer which exact settlement step are we paying for right now? after control returns from an adversarial environment.

  • Legacy or compatibility settlement paths should not survive on trust alone

    • Deprecated serializers, old route formats, and backward-compatibility adapters are high-risk precisely because humans stop looking at them while downstream consumers still trust them.
    • The healthy default is to retire them aggressively, not to let funded integrations keep treating them as equivalent to the current path.

  • A surviving fallback settlement lane should become a smaller lane, not the old lane in emergency mood

    • If one route, resolver family, or operator-assisted settlement path remains live during incident response or degraded mode, that lane should lose ordinary healthy-mode payer scope, destination reach, and inventory access.
    • This is the only path we still trust enough to keep running should mean this path has a smaller envelope and smaller loss budget, not this path may now spend against the same broad approvals or resolver inventory because it is all we have left.

Useful positive design shapes

1. Route-hash or envelope-hash commitment

  • The strongest settlement systems commit one route or settlement envelope hash before any callback-driven payment stage begins.
  • Later consumers can then prove that payer, pool, tokens, fee tier, and stage semantics still match the originally committed object.
  • This is the settlement-side cousin of making governance queue an exact action bundle instead of a mutable executor shell.

2. Canonical pool / market recomputation at callback time

  • When settlement depends on AMM callbacks, the consumer should recompute the canonical pool or pair from trusted factory, token ordering, fee tier, and route state.
  • msg.sender should be checked against that exact recomputed identity, not merely against bytes that arrived inside the callback.
  • This is the clean positive-design answer to fake-pool settlement spoofing.

3. Local recording of the payer and stage before external calls

  • If a later callback will need to know who owes funds, that payer should be written to trusted local state before the external call.
  • The callback should consume only that precommitted state, ideally once, rather than accept a free-form fromAddress or equivalent route-decoded payer.
  • This keeps approvals and resolver inventory from becoming generic debt-settlement pools.

4. Typed or length-safe protocol-authored context assembly

  • If a protocol truly needs dynamic suffixes or serialized wrappers, it should use encoding paths whose bounds and field ordering are enforced by construction.
  • Any user-controlled length or offset that decides where authenticated settlement fields land belongs inside the custody-critical threat model, not just inside low-level code review.
  • This is the cleaner positive-design answer to 1inch-style corrupted suffix construction.

5. Consumer-side distrust of ambient settlement context

  • A resolver or adapter should treat router called me with plausible token/amount bytes as insufficient on its own.
  • The safer question is what locally verifiable reason do I have to believe this exact settlement context belongs to the route, payer, and stage I agreed to fund?
  • Where practical, consumers should bound inventory exposure per route, per caller, per token set, and per versioned settlement path.

6. Degraded-mode settlement envelopes with narrower authority

  • If a protocol falls back to one emergency resolver, one manual route, one operator-assisted completion path, or one surviving settlement adapter, the committed envelope for that mode should shrink on purpose.
  • Healthy degraded mode usually means fewer destination classes, smaller per-window spend, no authority mutation, no broad approval reuse, and narrower payer / inventory semantics than ordinary routing.
  • The important design move is not merely keep settlement alive; it is keep only a consciously smaller settlement envelope alive while trust is weaker.

Design questions worth asking first

  • What exact machine-readable object is the downstream consumer trusting right now?
  • Which decisive fields inside that object are supposed to be protocol-authored rather than attacker-authored?
  • Could the same callback or resolver surface be reached with a different pool, market, or route stage than the consumer believes?
  • Is the payer / inventory source written to trusted state before external control leaves, or merely reconstructed from callback bytes afterward?
  • Can user-controlled lengths, offsets, nested payloads, or compatibility paths change where authenticated context is written or read?
  • If the protocol says a path is obsolete, what still proves no funded integration is relying on it as a live settlement surface?

Red flags that usually mean the protocol is authenticating the wrong settlement object

  • The caller is our router with no statement about which fields the router actually authenticated
  • The callback came from a pool without recomputing the canonical pool for the in-flight route
  • The route bytes contain the payer when that payer was never first committed in trusted local state
  • The suffix is appended by us even though attacker-controlled length math decides where it lands
  • This is only a legacy compatibility path even though resolver inventory or wallet approvals still make it economically live
  • Those bytes decode correctly used as if syntactic validity proved route authenticity

Failure-prevention checklist

  • Define one typed settlement envelope per funded route or settlement stage, and commit it before any external call, callback, or resolver handoff can ask a downstream consumer to trust bytes. Make the design review answer three separate questions for that envelope: what exact object exists, what proves the live consumer still sees the canonical protocol-authored version, and what payer / inventory / destination authority budget that accepted envelope is allowed to keep.
  • Recompute canonical pool, market, venue, fee tier, token ordering, resolver, and other route identity fields from trusted local state whenever practical instead of accepting them as opaque callback claims.
  • Write payer identity, inventory bucket, and execution stage into trusted local state before control leaves, and make downstream settlement consume only that precommitted state.
  • Treat every user-controlled length, offset, suffix, nested blob, and serializer compatibility shim as custody-critical logic; if those fields can move authenticated context, they are part of the money-moving threat model.
  • Keep parser versions explicit and fail closed on mixed-format or partially legacy envelopes; we can still decode something sensible is not a safe success condition.
  • Constrain funded resolvers, adapters, and approval-consuming paths by route version, caller, token set, and stage so a malformed or replayed envelope cannot become a generic spend authority.
  • Pre-commit degraded-mode envelope policy too: if only one fallback settlement path or resolver family remains live, automatically narrow payer scope, destination reach, approval use, and per-window inventory instead of preserving healthy-mode authority by default.
  • Retire deprecated settlement encodings aggressively once new formats exist; do not leave old envelope shapes live merely because some integration still knows how to call them.
  • Consume settlement envelopes once, clear any route-local settlement context on both success and failure, and refuse any late callback or second consumer that cannot prove it belongs to a fresh committed envelope.
  • Keep settlement spending tied to route-local deltas, escrow buckets, or explicitly authorized inventory sources rather than whatever allowance or balance is available now.
  • Fuzz malformed offsets, parser-version drift, counterfeit pool identities, stale stage reuse, and corrupted payer fields as first-class adversarial cases rather than low-level decoding edge cases.

Audit prompts

  • What exact machine-readable settlement envelope does each downstream consumer trust, and where is that envelope committed before external control leaves?
  • Which decisive fields are re-derived from trusted local state versus merely decoded from calldata, appended suffixes, route bytes, or callback payloads?
  • Can the same router, resolver, or callback surface be reached with a different pool, market, or stage than the downstream consumer believes it is settling?
  • Where is payer or inventory-source identity committed, and can attacker-shaped bytes rebind who owes this step after the route is already in flight?
  • Can any user-controlled length, offset, nested payload, or legacy parser path change which bytes the consumer interprets as protocol-authored truth?
  • Does the consumer authenticate the exact parser version and envelope layout, or merely succeed if some decoding path produces plausible fields?
  • If ordinary routing degrades to one emergency resolver, one manual completion path, or one surviving adapter, what exact payer scope, destination set, and approval/inventory budget disappear automatically?
  • If a route is obsolete or compatibility-only, what proves no live approvals, resolver balances, or funded integrations still make that path economically dangerous?
  • When settlement moves funds, is it paying a route-local authorized delta or dipping into a broader allowance / inventory surface that the envelope only weakly constrains?
  • What clears envelope-local context on revert, partial fill, retry, or callback failure, and can stale route state survive long enough to be consumed by the wrong path?
  • Which production telemetry would reveal envelope drift early: version-mismatch hits, unexpected parser fallbacks, resolver substitutions, wrong-pool callback attempts, or settlement spends outside expected route-local bounds?

Lessons that should already be standard

  • Real router is not the security property. The security property is real router, authentic envelope, exact stage, exact payer, exact counterparty, exact parser. The failure pattern gets flatter and harder to catch when teams collapse envelope exists, envelope is canonical truth, and envelope still deserves live spend authority into the same comfort claim.
  • Downstream consumers should distrust ambient settlement context the same way good systems distrust ambient balances or ambient callback liveness bits.
  • Callback-origin checks are necessary but incomplete. A real pool or router can still carry the wrong settlement meaning.
  • Serializer and parser code is money-moving code whenever it decides where authenticated fields live.
  • Compatibility paths are part of the live attack surface until they are actually deauthorized, not merely documented as legacy.
  • Only live settlement path left is not the same thing as this path still deserves ordinary spend authority. Weaker live workflow should imply a smaller settlement envelope, not continuity at the old budget.
  • Payer identity is a first-class security field. If the protocol cannot prove who is meant to fund the current step, approvals and resolver inventory turn into generic public spend pools.
  • Settlement-stage meaning belongs to the authenticated object. Reusing the same bytes across initiation, callback, finalization, and refund phases without a stage commitment invites cross-phase authority leakage.
  • The bytes decode is a parsing result, not a trust proof.

How to use this note with the exploit corpus

  • Start here when the sharper question is what should one healthy settlement system keep bound together before any downstream consumer treats a settlement blob as truth?
  • Quick routing rule for callback-heavy cousins: if the callback source may be real but the bug is that one still-live execution frame leaked actor / target / stage authority across callbacks, stay with callback frame truth as a single security object; if the decisive break is that a resolver, pool callback, or adapter trusted the wrong protocol-authored settlement object, stay here.
  • Quick routing rule for approval-drain cousins: if the main failure is the protocol paid the wrong pool / callback sender, stay with callback-origin authentication failure; if the main failure is the caller may be real but the protocol-authored settlement bytes got corrupted before use, stay with trusted execution-envelope corruption.
  • Drop into Trusted execution-envelope corruption when the decisive failure is that the protocol’s own authenticated settlement envelope was displaced, shadowed, or misparsed before use.
  • Drop into Callback-origin authentication failure when the decisive failure is that the downstream consumer mainly trusted the wrong pool, pair, or callback sender.
  • Drop into root-of-trust substitution when the earlier mistake is that the protocol accepted the wrong market, bank, jar, or other root object before any settlement-envelope machinery even mattered.
  • Pair with Execution-envelope identity pinning when the parallel question is not swap or callback settlement, but delayed privileged execution and governance.

Internal linkages

Negative exemplar cluster: what split settlement-envelope truth looks like

  • 1inch Fusion V1 preserves the clean protocol-authored suffix got corrupted before the downstream resolver consumed it cousin: the router stayed the real caller, but the bytes the resolver trusted were no longer the bytes the protocol meant to authenticate.
  • Sushi RouteProcessor2 preserves the route-selected pool became trusted callback origin cousin: the decisive break sits more on caller binding than on suffix corruption, but the broader lesson is still that settlement truth was never one pinned envelope.
  • ParaSwap Augustus V6 preserves the later gas-optimized direct callback path consumed spoofed pool context cousin, showing how approval-funded settlement remains dangerous even without a hand-rolled suffix underflow.

Control surface

Graph View

Backlinks