Lending Canister

Responsibilities

Account Management: Multi-chain wallet authentication and profile linking
Position Tracking: User collateral and debt positions using share-based accounting
Interest Accrual: Calculating and applying interest via global indices
Health Enforcement: Validating health factors before operations
Pool Coordination: Orchestrating deposits, withdrawals, borrows, and repayments
Price Integration: Fetching and caching asset prices from oracles
Liquidation API: Exposing interfaces for external liquidator bots

Account Management

Multi-Chain Authentication

Users authenticate using their existing blockchain wallets - no Internet Identity required:

A wallet is simply a (Chain, Address) tuple - for example (Bitcoin, "bc1q...") or (Ethereum, "0x..."). The account is derived by hashing the wallet, and the principal is derived from the first wallet's hash.

Benefits:

Use existing wallets (no new keys)
Strong cryptographic identity
Multi-wallet support per profile
Unified positions across wallets

Position Management

Each user's position in a pool is tracked using shares:

Field	Description
`user_profile`	Principal of the user
`pool_id`	Pool canister ID
`asset`	Asset type (BTC, ETH, USDC, etc.)
`deposit_scaled`	Supply shares
`debt_scaled`	Debt shares
`lending_index_snapshot`	Index at last update
`borrow_index_snapshot`	Index at last update

Core Operations

All operations follow the same pattern:

Sync pool indices to current time
Validate preconditions (caps, liquidity)
Update shares (mint or burn)
Validate postconditions (health factor)
Schedule async execution if needed

Operation	Share Action	Health Check
Deposit	Mint supply shares	No (improves health)
Withdraw	Burn supply shares	Yes (must stay healthy)
Borrow	Mint debt shares	Yes (must stay healthy)
Repay	Burn debt shares	No (improves health)

Pool Registry

The lending canister maintains a registry of all pools with their configuration:

Category	Fields
Identity	Principal, asset, chain
Caps	Supply cap, borrow cap
Share Totals	Total supply, total debt, treasury shares
Interest Rates	Base rate, slope before, slope after, optimal utilization
Indices	Borrow index, lending index
Risk Parameters	Reserve factor, liquidation threshold, liquidation bonus

Event Handling

The lending canister receives events from pool canisters via notify_pool_event(). Events include:

DepositConfirmed - triggers supply share minting
RepaymentConfirmed - triggers debt share burning

Each event includes a ledger transaction ID for idempotency - if the same transaction ID is processed twice, the duplicate is ignored.

Background Tasks

Task	Interval	Purpose
`sync_pools`	600s	Update pool indices
`update_prices`	300s	Refresh price cache
`process_wal_ops`	15s	Execute pending operations

Price Integration

Prices are fetched from the price oracle and cached with a 60-second expiry. The cache prevents price manipulation attacks and reduces request overhead.