Integration risk
Integration risk is the possibility that individually functioning components interact through incompatible assumptions, interfaces, units, callbacks, or lifecycle rules.
Category: RiskWarning cross category cue
System record
Start with the economic purpose, participants, resources, and entitlements before studying implementation detail.
Why it exists
DeFi products compose tokens, protocols, routers, oracles, bridges, and adapters, so correctness at each component boundary does not guarantee correctness of the combined position.
Traditional-finance analogy
Vendor, interface, and operational-dependency risk is the closest comparison recorded for this concept.
Where the analogy stops
- Permissionless contracts can call and hold one another's claims atomically, creating fast recursive dependencies without bilateral onboarding or coordinated change management.
- Token hooks, reverts, upgrades, decimal conventions, approvals, and composable collateral can make interface compatibility economically unsafe.
Main actors
- ActorIntegrating protocol and adapter developer
- ActorUpstream protocol, token, oracle, bridge, or router
- ActorKeeper, governance, or upgrade authority
- ActorUser and downstream claim holder
Assets and claims
Assets — controlled or transformed resources
Assets are resources the mechanism moves, holds, values, or transforms.
- AssetApproved, transferred, wrapped, deposited, or collateralized assets
- AssetUpstream positions held by the integration
Claims — entitlements and corresponding dependencies
Claims are rights to value, repayment, redemption, control, or another party's performance; each depends on an obligation or system that must honor it.
- ClaimDownstream shares or debts whose value depends on upstream behavior
Integration risk is the possibility that components work separately but fail when one protocol, token, oracle, bridge, router, or adapter depends on another.
Why it exists
Section titled “Why it exists”DeFi products compose callable contracts and transferable claims. An integrator must translate asset identity, units, decimals, approvals, return values, callbacks, pricing, limits, pauses, queues, upgrades, and failure semantics. Interface compatibility alone does not make those economic assumptions compatible.
Traditional-finance analogy
Section titled “Traditional-finance analogy”Vendor, interface, and operational-dependency risk is the closest analogy. Permissionless and atomic composition can create recursive dependencies without bilateral onboarding, coordinated maintenance, or a shared incident process. An upstream change can reach downstream claims within one transaction.
Actors, assets, and claims
Section titled “Actors, assets, and claims”| Boundary | Question |
|---|---|
| Token to protocol | Are identity, decimals, transfer behavior, hooks, and approvals handled? |
| Protocol to adapter | Are returned values, reverts, caps, queues, and lifecycle states translated? |
| Strategy to upstream position | Are value, liquidity, loss, pause, migration, and exit assumptions preserved? |
| Downstream claim holder | Which upstream components determine value and redemption? |
The assets are whatever the integration approves, transfers, wraps, deposits, or pledges. Upstream positions become assets of the integration, while downstream shares or debts become layered claims on those positions.
Mechanism and flows
Section titled “Mechanism and flows”- An integration approves or calls an upstream component.
- It transforms units, routes assets, and records a returned balance or claim.
- The upstream component invokes callbacks or later changes value and lifecycle state.
- The integration translates that outcome into downstream accounting and exits.
- A mismatched assumption corrupts value, blocks recovery, or creates an extraction path.
Capital flow crosses the contract boundary. Claim flow layers a downstream entitlement on an upstream position. Information flow includes prices, return values, events, and status. Return flow inherits the upstream payer. Risk flow can amplify through every downstream product using the integration.
State and loss allocation
Section titled “State and loss allocation”| Upstream event | Correct downstream handling | Failure path |
|---|---|---|
| Transfer fee, rebase, or unusual return | Measure actual balance change and supported semantics | Overstate received assets or create excess claims |
| Pause, cap, queue, or loss | Record impairment and enter an explicit exit state | Continue quoting unavailable or overstated value |
| Upgrade or migration | Verify compatibility and migrate deliberately | Strand assets or corrupt interface and accounting assumptions |
An integration creates no new external return. It passes through or transforms borrower interest, trading fees, network payments, issuance, or price changes from upstream. Unless an adapter owner, reserve, or insurer explicitly absorbs loss, downstream claim holders inherit the integration failure.
Protocol and engineering context
Section titled “Protocol and engineering context”ERC-4626 is a concrete integration surface: it standardizes vault methods while warning integrators that estimates, previews, fees, slippage, limits, rounding, and malicious implementations require care. A standard interface does not standardize strategy, liquidity, solvency, or trust assumptions.
An engineer or auditor should inventory transitive dependencies and test actual balance deltas, zero and unusual return values, decimals, fee-on-transfer and rebasing tokens, callbacks, reentrancy, allowance scope, recipients, upstream reverts, caps, queues, loss reports, migrations, and emergency unwinds.
Common misunderstandings
Section titled “Common misunderstandings”- “Both components are audited, so the composition is safe.” Each audit may assume behavior the other component violates.
- “The interface compiles, so the semantics match.” Types do not encode price, unit, lifecycle, liquidity, or loss behavior.
- “Composability only improves efficiency.” It also creates propagation paths and correlated dependencies.
See smart-contract risk and accounting risk.
Machine-readable model
Key equations
Canonical expressions come from the structured concept record. KaTeX renders the notation, while the plain-text expression and variable table keep its meaning and units inspectable without JavaScript. Read the narrative above for the model's domain, assumptions, and rounding rules.
This concept does not require one canonical equation. Its mechanism and state transitions remain the authoritative explanation; do not invent a formula merely to make the topic look quantitative.
Assurance contract
Security properties
These structured statements define desired behavior. Their stable IDs can bind tests, invariants, specifications, audit findings, or proof results without turning descriptive review advice into an assurance claim.
Desired · not evaluated: No test, audit, or proof result is implied until scoped evidence is linked to this property.
Every boundary validates asset identity, chain, unit, decimals, authorization, recipient, returned value, and resulting balance change
Upstream revert, pause, cap, queue, loss, migration, and upgrade states cannot silently corrupt downstream accounting or strand user assets
Callbacks and composable execution preserve global invariants under adversarial ordering rather than only isolated component assumptions
Dependency graphs, version constraints, emergency exits, and maximum loss paths remain explicit and testable for every supported integration
Knowledge check
Quiz
Answer in your own words, then open the model answer.
What problem does Integration risk exist to address?
Model answer
DeFi products compose tokens, protocols, routers, oracles, bridges, and adapters, so correctness at each component boundary does not guarantee correctness of the combined position.