Controller

Controller

The controller is the entry point for lending accounts. It checks authority, applies account and listing rules, requests prices when needed, and coordinates settlement with the central pool and external contracts.

For the user-facing position lifecycle, start with Managing Positions. This page explains the integration boundary; exact signatures, return types, and gates belong in the endpoint reference.

Choose the operation

Purpose	Controller operations	Guide
Manage balances	supply, borrow, repay, withdraw	Managing Positions
Delegate management	add_delegate, remove_delegate	Managing Positions
Liquidate or remove eligible bad debt	liquidate, clean_bad_debt	Risk and Liquidations
Borrow and repay within one transaction	flash_loan	Flash Loans
Open or rebalance debt-bearing accounts	multiply, flash_position, swap_debt, swap_collateral, repay_debt_with_collateral, migrate_from_blend	Strategies
Accrue indexes and send protocol revenue	update_indexes, claim_revenue	Central Pool
Refresh stored risk values	update_account_threshold	Health Factor and Collateral
Fill a market's backing shortfall	recapitalize	Central Pool
Renew an account's storage	renew_account	Managing Positions

Maintenance callers authenticate their own invocation. Index updates, revenue claims, threshold refreshes, eligible cleanup, and recapitalization do not require a keeper role. Account renewal requires the NFT owner. Revenue goes to the configured accumulator, not the caller.

Identity, units, and authorization

An account ID identifies a position NFT. The controller reads its current owner when checking authority. A delegate needs both that owner's account grant and active position-manager registration.

A market argument uses HubAssetKey, containing hub_id and asset. Token amounts use the token's native decimals. USD values and health factors use WAD; shares and indexes use RAY. Mixing these units changes transaction amounts and risk calculations; see Accounting and Numeric Domains.

Administrative mutations require the controller's owner, except ownership acceptance, which requires the pending owner. The normal deployment uses governance as owner. Read Governance and Timelock for the scheduled and immediate authority paths.

Read state before building transactions

Account views expose positions, attributes, balances, and health. Market views expose accrued indexes, spoke listings, usage, and oracle status. Use the view reference to select exact calls.

A health value alone does not establish account existence: a missing or debt-free account can return the maximum health sentinel. Check account_exists when existence matters. Likewise, is_liquidatable indicates the health condition, not that every price, listing, receiver, or liquidity requirement for execution passes.

Views can read external contracts and renew storage TTL. A successful view is a snapshot, not a transaction guarantee. Simulate the exact intended transaction against the selected network before signing; execution rechecks its own ledger state.

Settlement and transaction results

The controller authorizes pool accounting and token settlement. The pool's public accounting mutations require its owner; users cannot bypass account risk checks by calling them directly.

Inbound operations credit measured receipts on supported paths. Swaps measure controller input and output balances. Cash flash loans use exact pool-balance checks. These checks depend on supported token behavior and do not make arbitrary external contracts safe.

Soroban rolls back contract state changes and token transfers when the invocation fails. A failed transaction can still incur network fees. Global pause, listing restrictions, pricing, cash, storage, and resource limits each affect whether an operation succeeds.

Use the event reference to reconcile execution, including gross liquidation seizure versus net receiver credit. Use the error reference to interpret failures.