DeFi protocol architecture design
A team comes with an idea: "we want a lending protocol with yield farming and our own token." Two months into development, it turns out that the vault contract can't upgrade without losing state, tokenomics creates an inflationary spiral at first unlock, and the oracle reads spot price from a $50k liquidity pool — manipulated by one transaction. This is the cost of architectural decisions made in 20 minutes at project start.
Architecture design is a separate phase, resulting in a document: contract diagrams, storage layout, economic model with simulations, risk matrix. Then comes the code.
What's included in architectural design
Tokenomics: where most protocols break
The most common mistake — emission schedule without accounting for sell pressure. Protocol emits 1000 tokens per day as LP provider rewards. If there's no utility (why hold the token except for more farming), all rewards are immediately sold. Price falls, APY in dollars falls, LPs leave, liquidity falls — death spiral.
Sustainable models are built differently: reward token needs to be necessary for protocol access (fee discount, governance weight, boosted yields via veToken model). Curve Finance's veCRV is textbook example: to get maximum boost, you must lock CRV for up to 4 years. This creates organic demand and reduces circulating supply.
During design we build Python simulation of emission vs. demand 12-24 months forward with several scenarios (bull market, bear market, flat). Result — concrete numbers: at what TVL volume does the token have positive buy pressure.
Contract architecture: modularity vs. complexity
Monolithic contract is easier to audit but not extensible. Diamond Pattern (EIP-2535) is maximally flexible but significantly complicates audit and creates storage collision risks between facets. Right choice depends on roadmap.
Typical architectural patterns:
| Pattern | When to use | Risks |
|---|---|---|
| Monolithic + UUPS | Simple protocols, fast audit | 24 KB bytecode limit |
| Module system (Gnosis Safe style) | Extensible functionality | Module integration complexity |
| Diamond (EIP-2535) | 10+ functional blocks | Storage collision, complex audit |
| Immutable + migration | Maximum trust, no upgrades | No bug fixes possible |
| Proxy factory | Many similar instances | Clone initialization risks |
For DeFi protocols with TVL goal >$1M we recommend UUPS with namespaced storage (ERC-7201). Upgradeability is necessary at early stage (bugs happen), but must be protected by multisig with timelock: changes take effect in 48-72 hours, community can notice and react.
Liquidity management
Protocol-owned liquidity (POL) vs. incentivized liquidity — fundamental choice. If protocol pays LP rewards, it rents liquidity. Stop paying — liquidity leaves. OlympusDAO and Tokemak explored POL models: protocol owns its own liquidity and doesn't depend on mercenary capital.
For AMM protocols critical: on which DEX to build liquidity. Uniswap v3 concentrated liquidity gives better capital efficiency but requires active range management. Curve v2 optimal for correlated pairs. Balancer weighted pools — for non-standard weights (80/20 vs 50/50 reduces impermanent loss for governance token).
Risk management: matrix from start
Before writing first line of code, we compile risk matrix:
- Oracle risk: what happens with price manipulation? Circuit breaker? Pausing?
- Liquidity risk: what if bank run (everyone withdraws)? Reserve factor?
- Smart contract risk: action plan if critical vulnerability found?
- Admin key risk: multisig, timelock, eventually moving to DAO governance
- Regulatory risk: KYC/AML requirements in target jurisdictions
How design process goes
Week 1: analytics and benchmarking. We break down analogues: Aave v3, Compound v3, Euler Finance, Morpho. Look at incidents (rekt.news, immunefi post-mortems). Fix what we do differently and why.
Week 2: architectural document. Diagrams of contracts (Mermaid/draw.io), storage layout tables, interfaces (Solidity interface files without implementation). At this stage we conduct internal review: "what breaks in each attack scenario".
Week 3: economic model. Python simulation of tokenomics, TVL stress tests, breakeven analysis on fee revenue. Result — concrete recommendations on parameters: collateral factor, fee rate, emission schedule.
Output: technical document 30-50 pages + Solidity interfaces + simulation scripts. This is the input material for development and audit.
Typical mistakes revealed at design stage
Circular dependency in contracts. A calls B, B calls A. In reentrancy attack this becomes infinite recursive call. Visible on dependency diagram before code is written.
Underestimating gas cost of governance operations. If voting on proposal costs $50 in gas, no one votes. Need either gasless voting (EIP-712 signatures + relayer) or snapshot off-chain + on-chain execution via multisig.
Wrong order of operations in multi-step flows. Classic: transfer token first, then check allowance. Should be opposite. On sequence diagram this is visible.
Missing pause mechanism. When critical vulnerability discovered, you need to stop protocol in seconds. Pausable contract with multisig as guardian — standard. Without it, only option is wait governance vote 48 hours while funds drain.
Timeline estimates
Architectural design for medium complexity protocol — 2-3 weeks. Output: documentation, interfaces, simulations. This phase reduces development time by 30-40% and audit cost — because auditors work from documentation, not figuring out code from scratch.
Cost calculated individually.