Architecture
Deep dive into the canister architecture and system design
System Overview
Design Principles
1. Separation of Concerns
Canister | Responsibility |
|---|---|
Lending | Protocol logic (shares, health factor, liquidation) |
Pool | Asset custody (ckAsset operations, blockchain integration) |
This separation allows:
- Adding new assets without changing lending logic
- Asset-specific optimizations (BTC boosting, ERC fee fronting)
- Independent upgrades and auditing
2. Dual-Phase Execution
All critical operations follow a two-phase pattern:
Phase 1: Synchronous (Atomic)
- Validate request
- Update state
- Check invariants
Phase 2: Asynchronous (WAL-backed)
- Execute inter-canister calls
- Retry on failure
- Idempotent handlers
3. Event-Driven Communication
Pools notify the lending canister of state changes via events:
Event | Trigger | Action |
|---|---|---|
| User deposit detected | Mint supply shares |
| Debt repayment detected | Burn debt shares |
| Withdrawal completed | Update records |
| Borrow executed | Update records |
4. Subaccount Architecture
Each pool uses deterministic subaccounts for user isolation:
Subaccount Type | Purpose |
|---|---|
Inflow | For deposits and repayments (derived from principal + pool type) |
Outflow | For withdrawals and borrows (derived from address + index) |
BOOST_SUBACCOUNT | Small BTC withdrawal batching |
FEE_SUBACCOUNT | ETH gas fee management |
Communication Patterns
From | To | Method | Purpose |
|---|---|---|---|
User | Lending | | Request loan |
User | Lending | | Withdraw collateral |
Lending | Pool | | Execute withdrawal |
Pool | Lending | | Deposit/repayment confirmed |
Pool | ckMinter | | Burn ck tokens |
Lending | Price Oracle | Price query | Fetch prices |
ERC Pool | DEX | Token swap | Convert fees to ckETH |
Trust Boundaries
Boundary Protections
Boundary | Attack Vector | Mitigation |
|---|---|---|
User → Lending | Signature forgery | Native-chain signature verification |
User → Lending | Replay attacks | Nonce-based protection |
Lending → Pool | Unauthorized withdrawals | Caller validation |
Pool → ckMinter | Invalid burn amounts | Pre-flight validation |
Oracle → Lending | Price manipulation | Caching, deviation alerts |