Navina LangEvery new integration made the core harder to change — until one small feature required a full re-audit and delayed the release by weeks.
That's the pattern. And it compounds faster than most teams expect.
After integrating 10+ DeFi protocols across multiple chains into production systems handling millions in TVL, I've converged on one architectural principle that consistently contains the complexity: a stable core with swappable adapters.
The Problem With Tightly Coupled Integrations
The naive approach is simple: write integration logic directly into your core. It works for v1. Then you add a lending protocol. Then a DEX aggregator. Then a staking vault on a new chain where your existing integrations aren't deployed.
At some point you have conditional logic branching across core contracts, business logic entangled with protocol-specific calldata encoding, and a test suite that's testing your protocol and three external protocols simultaneously.
The complexity doesn't grow linearly — it compounds with each integration.
The deeper problem: when Aave upgrades their contracts — and they do — or when you want to add a new integration, you're touching your core. Every core change needs a new audit cycle. And each audit expands in scope as your core grows.
Adding a new integration to a tightly coupled codebase can require touching multiple core contracts. That single decision can trigger a full re-audit, delay the release by weeks, and multiply cost. The integration itself is often straightforward. The architectural coupling is not.
If your core knows about external protocols, your architecture is already drifting out of control.
The Core + Adapter Pattern
The solution is to draw a hard boundary between your business logic and your integration logic.
The core handles everything that is uniquely yours: your token mechanics, your fee logic, your access control, your state management. It knows nothing about Aave or Uniswap. It speaks in terms of abstract operations: deposit assets, withdraw assets, swap assets.
Adapters implement those operations for specific protocols. Each integration has its own parameters — Aave needs pool addresses and referral codes, Uniswap needs tick ranges and fee tiers. Rather than leaking those details into the core, adapters accept the operation plus encoded parameters and handle the decoding internally.
// Core only knows about the interface
interface IProtocolAdapter {
function deposit(address asset, uint256 amount, bytes calldata params) external returns (uint256);
function withdraw(address asset, uint256 amount, bytes calldata params) external returns (uint256);
function getBalance(address asset) external view returns (uint256);
}
// Core calls the adapter with encoded params - no protocol-specific logic here
function executeAdapter(address adapter, address asset, uint256 amount, bytes calldata params) external {
IProtocolAdapter(adapter).deposit(asset, amount, params);
}
// Each adapter decodes what it needs
contract AaveAdapter is IProtocolAdapter {
function deposit(
address asset,
uint256 amount,
bytes calldata params
) external returns (uint256) {
(address pool, uint16 referralCode) = abi.decode(params, (address, uint16));
IPool(pool).supply(asset, amount, address(this), referralCode);
return amount;
}
}Adding a new protocol integration becomes: write a new adapter, test it in isolation, register it with the core. No core changes. No new audit of your business logic.
Removing a protocol: deregister the adapter. The core is unchanged.
Note: The core should maintain a whitelist of approved adapters — only owner or multisig should be able to add or remove them. Allowing arbitrary adapter registration would let anyone point the core at a malicious contract. Adapter management is a privileged operation.
Note: In production, adapters should validate the decoded parameters before executing — checking for zero addresses, valid amounts, and expected state. They should also return meaningful state where needed, such as the amount of shares or tokens received from the external protocol, so the core can track positions accurately.
Common mistake: Passing arbitrary bytes params from frontend or user input directly into adapters without strict validation. If adapters interact with contracts where tokens are pre-approved, unvalidated calldata can become a fund-drain vector. Adapters should validate and whitelist the parameters they accept.
Why This Matters More Than It Looks
A concrete example: Venus is one of the leading lending protocols on BNB Chain. If you want to support it alongside Aave — which is also deployed on BNB — both expose similar concepts: supply, borrow, repay. But the interfaces, parameters, and return values differ. And Venus doesn't support flash loans — so if your protocol relies on flash loans from the lending protocol, you need to bring in an additional protocol to fill that gap, either within the Venus adapter itself or as a separate one.
Without adapters, your core accumulates protocol-specific handling for each: different function signatures, different parameter encoding, different return value parsing, and conditional logic for when flash loans are and aren't available. The core grows in complexity with every integration added.
That complexity has a direct security cost. The more logic lives in the core, the harder it becomes to reason about what it actually does — and the harder it is to spot vulnerabilities during development, code review, and audit. Adapters keep the core small and auditable. Each adapter can be reviewed in isolation against a known interface.
The Industry Is Converging on This
The best protocols in the space have independently arrived at the same conclusion.
MakerDAO applies the same principle — they explicitly implement this
as adapters. Each collateral type has its own GemJoin adapter that
translates between the external token and Maker's internal accounting
standard. The core Vat contract never touches the collateral token
directly. Adding a new collateral type means deploying a new adapter, not
touching the core. The boundary is enforced at the architecture level,
not just by convention.
Uniswap v4 introduced Hooks — external contracts written by third
parties that attach to individual pools and intercept execution at
specific lifecycle points. The core PoolManager doesn't change.
Customization happens at the boundary. It's the same principle: the core
stays stable, extensions live outside it. That's why Uniswap v4 can
support dynamic fees, on-chain limit orders, and custom AMM curves
without touching the core.
The pattern isn't just good practice for teams building on top of DeFi. It's how the protocols being integrated are built themselves.
The industry has also started standardizing the adapter layer itself. ERC-4626 defines a common interface for tokenized vaults — deposit, withdraw, mint, redeem — so integrations don't need to know the underlying protocol. Yearn Finance v3 is built around this model. When your adapter speaks ERC-4626, swapping the underlying strategy doesn't require interface changes.
The pattern starts to compound: once adapters share a standard interface, they become composable in the same way as the core.
Where It Gets Messy
Completely decoupling adapter changes from core is harder than it sounds. In practice there are leaks.
Return value standardization is harder than it looks. Aave's deposit returns aTokens. Compound returns cTokens. A yield vault returns shares with different precision. And token decimals compound the problem — USDC uses 6, most vaults use 18. Getting your core to treat these uniformly requires careful interface design upfront — and you'll probably get it wrong the first time.
Gas costs from indirection are real. Every external call through an adapter interface costs gas. On L1 with high-frequency operations this matters. Decide consciously which operations justify the abstraction.
State assumptions bleed through. Your core will make subtle assumptions about how external protocols behave — about atomicity, about when balances update, about what reverts. Surface those assumptions and make them explicit in the adapter interface rather than letting them hide in the core.
The adapter interface design is the hardest part. If you design it around your first integration, it won't fit the second as cleanly. Having two or three integrations in mind before you finalize the interface saves significant rework later.
What the Pattern Buys You
- Audit scope is smaller and cleaner. When you add a new integration, the audit scope is the new adapter plus its interaction with the core interface — not a re-audit of the entire core. This meaningfully reduces both cost and risk.
- Testing becomes more modular. You can test adapters against forked mainnet state in isolation without spinning up the entire protocol. Test surface area is naturally separated by concern.
- Failures are contained. When an external protocol has an issue, the blast radius is limited to whatever is routed through that adapter. You can pause or remove a single adapter without affecting the rest of the system.
- New chain deployments are easier. Write chain-specific adapters against the same core interface. The core deploys unchanged.
A Note on Upgradeability
The pattern pairs well with upgradeable proxy architecture. Your core should be upgradeable carefully — it holds the invariants and the user funds exposure. Your adapters can be more aggressively managed: deployed fresh for new versions, replaced when external protocols upgrade, or made immutable if the integration is stable and well-tested enough.
That said, the right approach depends on whether your adapters hold state or tokens. A stateless adapter that only translates calls can be replaced freely. An adapter that holds balances or tracks positions needs the same careful upgrade considerations as the core — you can't simply swap it out without migrating that state.
In DeFi, integrations evolve faster than your core logic. If your architecture doesn't account for that, your protocol won't just slow down — it will accumulate risk faster than you can audit or reason about it.
The projects that skip this tend to regret it around their third or fourth integration.
Building in DeFi and want to discuss architecture decisions? Happy to connect. And genuinely curious: what's the messiest protocol integration you've had to add to an existing codebase?