Designing a Blockchain Project Architecture
Blockchain project architecture consists of decisions that are expensive to change later: choice of network, contract upgrade strategy, oracle integration, security model. A year of development and an audit make architecture refactoring practically impossible without a complete rewrite.
Architectural Layers
Layer 1: Protocol Core (Smart Contracts)
This is immutable or minimally changeable logic. Errors here are critical vulnerabilities.
Proxy Pattern Selection:
Transparent Proxy (OpenZeppelin):
+ Simple, battle-tested
- Admin cannot use protocol as a user
- Extra gas on selector check
UUPS (EIP-1822):
+ Less gas overhead
+ Upgrade logic in implementation
- If implementation deployed without upgradeToAndCall → locked forever
✓ Recommended for production
Diamond (EIP-2535):
+ No 24KB contract size limit
+ Multiple facets
- Complex to audit
- Only for complex protocols with >10 logical modules
Access Control Architecture:
Role hierarchy:
ROOT: 3-of-5 Gnosis Safe (founding team)
↓
TIMELOCK (48h): parameter management, upgrades
↓
GOVERNANCE: DAO votes (for mature protocols)
├── ADMIN: critical operations (pause, emergency)
├── OPERATOR: daily ops (setFee, setOracle)
└── RELAYER: automated operations (off-chain actors)
Layer 2: Data Layer (Oracles and Indexers)
Oracle Strategy:
Price data (token prices):
Primary: Chainlink Price Feeds
Secondary: Uniswap V3 TWAP (for tokens without Chainlink)
Fallback: Pyth Network
Manipulation protection:
- TWAP (Time-Weighted Average Price) instead of spot price
- Circuit breaker: reject price if deviation > 20% from previous
- Multiple oracle aggregation (median from 3 sources)
Custom oracle data (off-chain events):
- Chainlink Functions (HTTP requests in smart contracts)
- UMA Optimistic Oracle (for disputed data with dispute window)
Indexing:
The Graph Protocol:
- Subgraph for historical data
- GraphQL API for frontend and third-party integrations
- Decentralized hosting via Graph Network
Moralis / Alchemy Webhooks:
- Real-time event notifications
- Fast response (< 1 second)
- Backup source if subgraph lags
Self-hosted indexer:
- For protocol-specific data
- PostgreSQL + Node.js event listener
- Used when The Graph is not flexible enough
Layer 3: Off-chain Services
Backend (if needed):
- Relayer for gasless transactions (EIP-2771 + Gelato)
- Order matching (for DEX with off-chain orderbook)
- Notification service (email/push on events)
- Analytics API
Keeper/Automation:
- Chainlink Automation (Keepers) — automatic on-chain actions
- Gelato Network — alternative, more flexible
- Custom keeper — if custom logic needed
Layer 4: Frontend
Web3 stack:
- wagmi v2 + viem for Ethereum interactions
- RainbowKit / ConnectKit for wallet connection UI
- React Query for async state management
- The Graph for historical data
Performance:
- Multicall3 for batching RPC calls (1 request instead of 20)
- Local simulation (Tenderly / fork) before transaction
- Optimistic UI updates with rollback on error
Multi-chain Architecture
For protocols operating on multiple networks:
Hub-and-Spoke model:
Ethereum Mainnet: governance, treasury, canonical token
L2s (Arbitrum, Base, Optimism): execution, liquidity
Cross-chain messaging:
LayerZero: universal messaging, any networks
Wormhole: token bridge + messaging
Axelar: token transfer + contract calls
CCIP (Chainlink): enterprise-grade, stricter and more expensive
Token bridging:
Canonical bridge (safer, slow — 7 days for Optimism)
Third-party bridge (fast, but bridge hack risk)
Lock-and-mint on own bridge (full control, but high audit cost)
Security as an Architectural Principle
Defense in depth:
- Smart contract level: Reentrancy guard, access control, pausable
- Protocol level: rate limits, circuit breakers, caps
- Governance level: timelock, multisig, guardian veto
- Monitoring level: Forta alerts, Defender autotasks
Invariants (immutable system properties):
"Sum of all user balances ≤ totalDeposits"
"After every transaction collateral ratio ≥ minCollateral"
"Only whitelisted token addresses can be deposited"
Invariants are checked via Foundry invariant tests — they run thousands of random transaction sequences and verify that invariants are never violated.
Architecture Design Process
Week 1: Discovery — studying requirements, competitor analysis, threat modeling.
Week 2: Draft architecture — contract diagrams, data flows, sequence diagrams.
Week 3: Review and validation — discussion with team, attack vector checking, revision.
Week 4: Final documentation — Technical Architecture Document (TAD) with all decisions and rationale.
Result: Technical Architecture Document with contract diagrams, data flow diagrams, security model, and rationale for key decisions. Serves as foundation for specification and reference for auditors.