Cowrie Research

interface-conformance-semantic-compatibility-failure

16 min read

Interface Conformance / Semantic Compatibility Failure

  • Name: interface conformance / semantic compatibility failure
  • Category: exploit pattern / integration failure / asset-admission failure / token-semantics mismatch
  • Summary: Smart contracts often treat supports the expected interface as if it also means behaves with the economic and control-flow semantics this accounting path assumes. That is a stronger claim than standards like ERC-20 or a nominal market / strategy / helper interface actually provide. Once a protocol lists, whitelists, or caller-injects a token or integration endpoint whose semantics include callbacks, transfer fees, rebases, upgradeable logic, attacker-chosen return values, or other non-vanilla behavior, ordinary mint, borrow, harvest, burn, and swap code can start reasoning over false assumptions. The exploit surface is not only in the token. It is in the protocol’s decision to admit that token or endpoint into a path whose invariants were written for something stricter than the interface guarantees.
  • What it is:
    • A protocol admits a token or token-like contract into a security-critical path because it implements the expected methods or because the code lets the caller supply any token address.
    • The protocol’s accounting silently assumes stronger semantics than the interface guarantees: transfer is inert, nominal amount equals amount received, no callback can run mid-flow, balances move only in expected ways, and the admitted asset set is narrower than anything with the right ABI.
    • A hostile or unsupported token violates one of those assumptions.
    • The protocol then mints shares, pays out reserves, computes collateral, or settles debt against behavior it never modeled.
    • Real loss occurs when those false assumptions are monetized elsewhere: draining reserves, borrowing stronger assets, over-minting claims, or creating bad debt.
  • Typical preconditions:
    • The protocol accepts user-supplied token addresses, permissionless listings, or governance / admin listings without a deep compatibility review.
    • Core accounting paths assume vanilla ERC-20 behavior rather than measuring and containing token-specific semantics.
    • External token transfers happen before accounting is finalized, or accounting trusts nominal transfer amounts instead of measured post-conditions.
    • The admitted token can trigger callbacks, burn on transfer, present elastic balances, or otherwise make token moved mean something different from what the protocol expects.
    • The resulting false state can be cashed out into real assets, deeper-liquidity markets, or redeemable protocol claims.
  • Common vulnerable surfaces:
    • lending markets that list callback-capable or otherwise non-vanilla collateral / borrow assets
    • vault and pool mint paths that let callers supply arbitrary token addresses
    • AMMs and pool contracts that treat nominal amountIn as actual inventory received
    • routers and periphery helpers whose validation stops at token address supplied or interface call succeeded
    • permissionless market, strategy, staking, or helper registration flows whose downstream accounting assumes honest callback behavior once the interface matches
    • rebasing or elastic-supply systems where a later accounting path can re-read balances created by an earlier unsupported-asset transfer
    • governance or admin listing flows that approve assets faster than the protocol’s accounting assumptions are re-checked
  • Exploit sequence:
    1. The attacker identifies a protocol path whose safety depends on stronger token semantics than the interface actually guarantees.
    2. They introduce or target a token with hostile, unsupported, or merely incompatible behavior: callback hooks, transfer fees, elastic balances, upgradable logic, or a fake interface-compatible contract.
    3. They route that token through the vulnerable path.
    4. The token’s real behavior breaks one of the protocol’s hidden assumptions about transfers, balances, or control flow.
    5. The protocol mints, lends, redeems, or prices value against that broken assumption.
    6. The attacker converts the resulting false claim or accounting gap into real assets.
  • Variants:
    • Callback-capable token admitted — a listed or caller-supplied token turns what looked like a passive transfer into an attacker-controlled callback window. Uniswap V1 imBTC, Lendf.Me imBTC, and C.R.E.A.M. AMP are the clean lending / AMM exemplars.
    • Fee-on-transfer token admitted — the protocol books nominal input as if it were actual received inventory, and reserve / solvency math drifts away from reality. Balancer STA is the canonical AMM case.
    • Non-reverting failed transfer admitted — the protocol assumes a failed token pull will revert, but the integrated asset instead returns false, so issuance continues after no assets moved at all. ForceDAO xFORCE is the clean vault-share exemplar.
    • Unsupported fake-token injection — a path that should only accept a small supported asset set instead accepts an attacker-controlled interface-compatible token, which then composes missing validation with reentrancy or accounting ambiguity. SpankChain, Akropolis, Origin Dollar OUSD, and Grim Finance are the sharp refund- and vault-side examples.
    • Interface-compatible fake market/helper injection — the protocol accepts a contract that looks enough like the expected token, market, strategy, staking, or helper surface and then reasons over attacker-authored return values or callbacks as if they came from a canonical or semantically safe integration endpoint. NFTLiquidation is the sharp liquidation-helper exemplar, while Penpie and Clober show the same seam in permissionless market-registration and strategy-plugin form.
    • Semantic mismatch after listing — the asset is genuinely listed, but the protocol still models it as if transfer behavior were vanilla ERC-20. C.R.E.A.M. AMP preserves the listed asset, wrong semantics branch particularly well.

Three compatibility promotions reviewers should not collapse

  1. An interface-compatible object exists at all

    • A token address answers the right selectors, a market or strategy contract exposes the expected methods, or a listing / calldata slot accepts the object without immediate rejection.
    • That is only the weakest fact: something callable and shape-compatible is present.

  2. That object counts as semantically safe for this exact accounting role

    • The harder question is whether the object’s real behavior matches what the path assumes about callbacks, balance semantics, nominal-versus-actual receipt, upgradeability, canonical endpoint identity, and who is allowed to supply it.
    • Most failures in this family happen here: the protocol promoted ABI matches or listing approved into safe to reason over as collateral, backing, reserve inventory, reward market, or helper truth.

  3. That accepted role-compatible object deserves this much monetary authority

    • Even semantically reviewed objects should not automatically inherit unlimited mint, borrow, withdrawal, liquidation, or reserve-release authority across every path.
    • This is where wrappers, isolated markets, quarantines, per-asset adapters, and narrower role binding start to matter.

Healthy systems keep those three promotions separate instead of flattening them into one vague comfort claim like the token is supported or the interface matches.

  • Detection heuristics:
    • Ask what the protocol assumes about a token beyond its ABI: no callbacks, exact transfer amounts, fixed balance presentation, immutable code, or a closed supported-asset set.
    • Review any path that accepts arbitrary token addresses or any newly listed asset without per-asset semantic gating.
    • Compare nominal amountIn / amountOut accounting to measured balance deltas and then ask whether those deltas are themselves provenance-safe.
    • Trace whether token transfers happen before debt, reserve, or share-accounting writes are finalized.
    • Treat ERC-777 / ERC-1820 hooks, fee-on-transfer logic, rebasing, upgradeable tokens, and wrapper-specific side effects as security properties, not compatibility trivia.
    • Re-run threat models with a hostile but interface-conforming token in every user-supplied token slot.
  • Defenses:
    • Maintain explicit allowlists or adapter layers for assets whose semantics have actually been reviewed against the target accounting path.
    • Distinguish ERC-20 compatible enough to call from economically safe to list.
    • Finalize critical accounting before external token transfers when possible, and otherwise use reentrancy protection around token-interaction boundaries.
    • Measure actual received amounts where that matters, but do not confuse amount measurement with provenance; a measured balance delta still needs source-safe attribution.
    • Add asset-compatibility test matrices covering hooks, fee-on-transfer behavior, rebases, missing return values, and upgrade or admin mutability.
    • Use wrappers or isolation layers for weird assets instead of letting the core solvency engine ingest raw semantics directly.
    • Treat caller-supplied token addresses as part of the trust boundary, not a convenience parameter.

What sound design looks like

  • Healthy protocols keep three facts separate on purpose: an interface-compatible object exists, that object is semantically safe for this exact accounting role, and that admitted object deserves this much mint / borrow / withdrawal / liquidation authority here. ABI matches or listing approved is only the start of review, not the end of it.
  • The protocol defines an explicit semantic contract for every asset or integration endpoint it admits into a high-value path: how transfer success is proven, whether callbacks are possible, whether nominal amount and received amount may diverge, whether balances can rebase, whether return values or hook behavior can be attacker-authored, whether code can change under the same address, and who is allowed to choose the endpoint at all.
  • Asset compatibility is path-specific rather than global. A token that is safe to custody, price, or wrap is not automatically safe to use as raw lending collateral, direct vault backing, router inventory, or mint-side deposit input. Healthy systems evaluate the exact accounting boundary the asset will touch and isolate the asset if that boundary expects stricter semantics.
  • Supported assets are narrow, named, and machine-checkable. If a core solvency path only works for vanilla semantics, the architecture should enforce a closed list or a per-asset adapter instead of leaving a generic token address slot open and hoping reviewers remember every semantic footgun.
  • The protocol proves asset receipt and accounting finality with the same object. Share minting, debt repayment, collateral credit, and reserve accounting should bind to measured and authenticated post-conditions rather than to optimistic assumptions that a transfer succeeded and meant the usual thing.
  • Weird assets are quarantined, wrapped, or derecognized quickly once their semantics drift outside what the core engine was designed to tolerate, and even semantically safe assets do not automatically inherit every downstream role. Wrapper semantic price revocation and collateral derecognition is the adjacent positive-design companion when the next question becomes how to stop treating a semantically broken wrapper or token as live collateral truth.

Failure-prevention checklist

  • Write down, per admitted asset path, which promotion is happening and where: object is callable, object is semantically safe for this role, and object may now carry mint / borrow / withdrawal / liquidation authority. Do not let one success flag or listing step silently stand in for all three.
  • Write down, per admitted asset path, the semantic assumptions the code actually needs: revert-on-failure versus false, callback absence, exact transfer amounts, stable balance presentation, immutable code, and whether the asset can be chosen dynamically by users.
  • Enforce admission policy in code, not only in docs or reviewer memory. If a path is only safe for a closed asset set, make that set explicit or route through per-asset adapters.
  • Prove receipt before minting claims, releasing credit, or clearing debt. Raw transfer() / transferFrom() success should never be treated as enough when the token’s semantics can legally do something weaker.
  • Separate supported interface testing from supported semantics testing. Add harnesses for false-return transfers, fee-on-transfer behavior, callback-capable tokens, rebases, paused tokens, mutable proxy-backed tokens, and caller-supplied fake endpoints.
  • Finalize accounting before any token interaction that could invoke callbacks or otherwise change execution order, and place reentrancy protection on the real authority boundary rather than on one happy-path function.
  • Treat governance and admin asset listings as constitutional changes to the solvency model, not as metadata updates. A new listed token can silently invalidate assumptions embedded all over the accounting engine.
  • Isolate weird assets behind wrappers or dedicated markets whose failure cannot directly poison the protocol’s core reserve, solvency, or share-issuance logic.
  • Track asset mutability after listing. Proxy upgrades, wrapper-operator changes, and semantic drift over time can turn an originally safe integration into an unsafe one without changing the address.
  • Make it easy to derecognize or quarantine assets quickly once semantics are found to be unsafe for a given path.
  • Rehearse incident response for asset-semantics failures: pause paths, wrapper shutdowns, price-source removal, market quarantine, user messaging, and claim accounting for already-issued receipts.

Audit prompts

  • What stronger assumptions does this path make beyond the interface itself: exact transfer amount, revert-on-failure, no callbacks, non-rebasing balances, immutable code, or canonical endpoint identity?
  • Who is allowed to choose the asset or token-like endpoint for this path: governance, admin, users, routers, helpers, or untrusted calldata?
  • If transferFrom() returns false, transfers less than requested, rebases mid-flow, invokes hooks, or resolves to upgraded logic tomorrow, what exact invariant breaks first?
  • Does the protocol measure post-transfer reality, or does it continue from nominal parameters and optimistic control-flow assumptions?
  • Which other functions become unsafe if an admitted asset can callback or change execution order during a transfer?
  • Are the path’s assumptions documented and tested per asset, or are they only implied by inherited code patterns such as xSUSHI-style vaults or generic ERC-20 wrappers?
  • Can a user-supplied token, market, helper, or wrapper address enter a path that was really designed for a small reviewed set of canonical endpoints?
  • If the integrated token is upgradeable or wrapper-governed, what process revalidates semantic compatibility after code or operator changes?
  • What is the fastest safe quarantine action if this asset is discovered to violate the protocol’s assumptions in production?
  • Would an outside reviewer looking only at the asset-listing policy understand which semantics are required for each path, or would they have to infer them from scattered code assumptions?

Lessons that should already be standard

  • The object implements the interface, the object is semantically safe for this accounting role, and the object deserves live monetary authority here are three different claims.

  • Interface compatibility is not semantic compatibility. The ABI tells you how to call the object, not whether your accounting model survives the answer.

  • Asset admission is solvency design. Listing the wrong token, or letting the wrong caller choose one, is often equivalent to shipping new core logic without saying so.

  • Battle-tested pattern is not a defense when the new deployment quietly changed the asset semantics underneath it. ForceDAO is the compact reminder that familiar vault code can become an unbacked-mint rail if the integrated token answers failure differently.

  • Measuring balance deltas helps, but only after the protocol has decided which deltas are legitimate and which call frame or asset meaning they belong to. Amount measurement alone does not solve semantic drift.

  • Weird assets should be isolated on purpose, not discovered accidentally in the main solvency engine.

  • Semantic drift is not just a launch-time problem. Upgradeable tokens, mutable wrappers, and operator-managed assets can become incompatible later without changing their addresses.

  • The safest question at listing time is blunt: what exactly must be true about this asset or endpoint for this path to stay solvent, and where is that truth enforced?

  • Permissionless market or strategy registration is still asset admission in disguise if downstream harvest, burn, or withdrawal code assumes the registered endpoint will behave like an honest implementation rather than a merely interface-compatible one.

  • Design contrasts worth preserving:

    • Token semantics as control-flow risk — the decisive problem is that the asset can call back or alter execution order. Uniswap V1 imBTC, Lendf.Me imBTC, and C.R.E.A.M. AMP belong here.
    • Token semantics as reserve-accounting risk — the decisive problem is not callback control but that nominal transfer amounts and actual inventory diverge. Balancer STA is the clean exemplar.
    • Token semantics as admission risk — the protocol should never have let that token enter the path at all. SpankChain, Akropolis, Origin Dollar OUSD, and Grim Finance preserve this branch, with SpankChain being the clean user-chosen token in a refund path example and Grim the clean caller-controlled token parameter inside a vault deposit router example.
    • Interface shape as false compatibility proof — the contract implements the expected methods, but the protocol needed something stronger than ABI matches: canonical market identity, trusted callback behavior, and accounting semantics consistent with the helper’s assumptions. NFTLiquidation preserves this seam between looks like the right object and is safe to reason over as the right object, while Penpie and Clober preserve the same seam for market- and strategy-shaped endpoints that were syntactically valid but semantically hostile.

  • Routing seam with balance-delta provenance failure:

    • Stay here when the analytical question is why was this token or token-like endpoint unsafe to admit into this path at all? The preserved mistake is that the protocol treated has the right methods as if it also meant has the right transfer, callback, and balance semantics.
    • Pivot to balance-delta-provenance-failure when the sharper question is how did one genuine balance increase get credited to the wrong call frame, position, or claim? In those cases the hostile token matters mainly because it opens the accounting window or injects the wrong balance source, while the payout primitive is the later provenance mistake.
    • Akropolis, Grim Finance, and Origin Dollar OUSD are the cleanest seam cases: the unsupported token admission is the reason the path became unsafe, but the monetizable invariant break is that one real inflow was later counted twice or more across different accounting frames. Akropolis is the simple two-frame version, Grim is the repeated-checkpoint-reset multi-frame vault version, and Origin is the rebasing-balance amplification cousin.

  • Best concrete case studies:

    • Uniswap V1 imBTC — callback-capable token treated as inert AMM inventory.
    • Lendf.Me imBTC — listed asset whose transfer semantics were unsafe for lending-market accounting.
    • Balancer STA — fee-on-transfer semantics breaking reserve truth.
    • ForceDAO xFORCE — false-return transfer semantics on issuance boundary.
    • Akropolis — user-supplied fake token as accounting-window opener.
    • C.R.E.A.M. AMP — listed asset, wrong integration semantics.
    • Penpie — permissionless market registration widened the admitted endpoint surface until factory-valid no longer implied reward-accounting-safe.
    • Clober — a user-installed strategy ABI was treated like harmless extensibility until it became live withdrawal-time custody logic.
    • NFTLiquidation — interface shape mistaken for canonical trusted object.

Internal linkages

Control surface

Graph View

Backlinks