LiquidiumTechnicalArchitecture
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 |
|---|---|---|
DepositConfirmed | User deposit detected | Mint supply shares |
RepaymentConfirmed | Debt repayment detected | Burn debt shares |
WithdrawalConfirmed | Withdrawal completed | Update records |
BorrowConfirmed | 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 | borrow_assets() | Request loan |
| User | Lending | withdraw() | Withdraw collateral |
| Lending | Pool | withdraw() | Execute withdrawal |
| Pool | Lending | notify_pool_event() | Deposit/repayment confirmed |
| Pool | ckMinter | retrieve_btc() | 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 |