Architecture Overview

Market Manager admin

Protocol-level administrator that deploys new lending markets and maintains the registry of deployed markets (controlled via multisig). Admin transfer follows a 2-step process (propose_new_admin → accept_proposed_admin).

Market admin

Operator of a specific market who sets parameters, controls operating status, and manages fees for that market. Market configuration changes (pool creation, pool config updates, market config updates) are time-locked: changes are queued first and applied after the time-lock period (queue_in_pool_set → apply_pool_set, queue_in_market_update → apply_market_update).

User

Anyone who deposits to earn yield, borrows against posted assets, manages positions, or views market information. Users can compose multiple operations atomically via submit_requests_batch (e.g., flash borrow + swap + deposit + borrow). Each user position is identified by an ObligationKey { user: Address, seed: Option<BytesN<32>> }, allowing a single address to maintain multiple isolated positions.

Market Manager (smart contract)

Factory and registry contract that creates new markets and keeps a discoverable directory of deployed markets. Pool creation and configuration are unified under a time-locked pool set flow (queue_in_pool_set → apply_pool_set).

Market (smart contract)

The contract where lending and borrowing occur. It manages asset pools, enforces market rules, tracks user positions, and coordinates with external price feeds and exchanges, including liquidations and other safeguards. Markets support 7 statuses (Active, BorrowFrozen, BorrowFrozenByAdmin, DepositFrozen, DepositFrozenByAdmin, Frozen, FrozenByAdmin), and individual pools carry per-pool status flags (4-bit bitfield) for fine-grained operation control.

Insurance fund (smart contract)

A per-market safety buffer funded by fees. It absorbs residual losses after liquidations before any shortfall is socialized to lenders. Bad debt coverage follows a two-phase process (issue_cover_bad_debt → claim_cover_bad_debt_results). The insurance fund can also freeze a market via fund_update_market_status.

INFO

Learn more in Insurance Fund

Asset pool

A per-asset liquidity pool (e.g., XLM, USD) that holds data about total deposits, plain collateral supplied, and total loans for that asset.

Pool structure (pool config → pool state)

The market's policy and accounting layer. It defines pool rules and tracks live totals such as available liquidity, borrowed amounts, collateral, and fees. Each pool includes a reactive interest rate modifier (ir_reactivity_constant, target_utilization_ratio_bps, interest_rate_modifier) that dynamically adjusts rates based on utilization.

User obligations

A user's position record in a market, keyed by ObligationKey, that summarizes deposits, collateral, and borrows, and is used to assess whether the position remains safe. The optional seed in the key allows a single address to hold multiple isolated positions.

Cross-pool

Shared risk engine that evaluates positions across assets, allows collateral in one pool to support borrowing in another, and determines when liquidations are permitted.

AMM DEX

External exchange used for token swaps when needed during composable batch operations (e.g., flash borrow + swap + deposit).

Oracle

External price service that provides current asset prices so the market can value collateral and debt and run risk checks.

Liquidator

Permissionless third party that repays debt on unhealthy positions in exchange for collateral at a discount (liquidation bonus).

---

Detailed Component Reference

Component	What it is	What it does	How it interacts
Market Manager admin	Protocol-level administrative role controlled via a multisig	Deploys new market contracts through the manager Reads the list of deployed markets	Calls the Market Manager contract Operates only at the "which markets exist" layer Does not touch pools or user obligations directly
Market Admin	Administrative actor for a specific (owned) market	Manages pools with time-locked queue_in_pool_set → apply_pool_set Manages market config with time-locked queue_in_market_update → apply_market_update Controls market status with update_market_status (7 statuses including *ByAdmin variants) Controls per-pool status with update_pool_status (bitfield flags) Configures fee beneficiaries with set_take_rate_fees_beneficiaries, set_operation_fees_beneficiaries Updates swap provider with update_swap_provider Transfers admin role via propose_new_admin → accept_proposed_admin	Calls the target Market contract directly Changes are persisted in the market's pool structure
User	Standard protocol participant (lender/borrower/reader)	Identifies via ObligationKey (user address + optional seed for different obligation types) Supplies and earns with deposit Borrows with borrow and repays with repay Exits with withdraw Manages collateral with add_collateral, remove_collateral Composes advanced strategies via submit_requests_batch (flash borrow + swap + deposit/borrow in one atomic tx) Reads state with view methods (e.g. get_user_obligation, get_pool)	Sends transactions to the Market contract Market updates the user's obligation and relevant asset pool Market applies current pool config/state to the action
Market Manager	Registry and factory for markets	Deploys new markets (constructor invoked via manager) Stores and returns the list of deployed markets Serves as protocol-level entry point for market creation	Receives calls from Market Manager admin Produces new Market instances Exposes deployed market addresses to other actors
Markets	Main functional contract of the protocol	There are 2 types of markets: Owned markets: Markets whose config can be modified by the admin via putting a config update to the update queue. After the update has been in the queue for a required amount of time, the admin can apply it. Ungoverned markets: markets with permanently immutable config. Admins of this type of market can only configure fee beneficiaries. Functions Maintains per-asset pools created via time-locked queue_in_pool_set → apply_pool_set Maintains pool config and pool state Stores and updates all user obligations (identified by ObligationKey) on calls like deposit, borrow, repay, withdraw, add_collateral, remove_collateral Executes composable batch operations via submit_requests_batch Provides service functions: liquidate, issue_cover_bad_debt, claim_cover_bad_debt_results Provides fee distribution via distribute_pool_fees, distribute_all_pools_fees Enforces market status and per-pool status flags	Receives calls from User and Market Admin Is created by the Market Manager Calls external DEX (swap provider) for swaps in batch operations Queries external oracle for prices Accepts liquidation calls from external liquidators Applies cross-pool decisions to obligations
Asset pool	Per-asset loan pools inside a market (e.g. XLM, USD)	Hold supply and borrow balances for their asset Act as targets for user deposits and borrows Can participate in collateral relationships between assets Have per-pool status flags controlling which operations are enabled	Their balances and utilization are tracked in pool state User obligations record into specific asset pools Pool structure consumes their data for interest/fees
Insurance fund	A per-market safety buffer implemented as a smart contract, funded primarily by protocol fees (take rate and configured portions of operation fees), with optional inflows from high-utilization exit fees and donations	Covers residual bad debt after liquidations via two-phase flow: issue_cover_bad_debt → claim_cover_bad_debt_results Can freeze the market via fund_update_market_status (but cannot override *ByAdmin states)	Receives top-ups from protocol fee distribution When an insolvent obligation remains under-collateralized after liquidations, the market issues cover requests to the fund Can proactively freeze market operations in emergencies
Pool structure (pool config → pool state)	Internal representation of pool rules and live figures	Pool config stores status, fee, health, interest rate model, accrual model, and reactivity params; updated via time-locked queue_in_pool_set → apply_pool_set Pool state stores live numbers: available, total borrowed, total jTokens/dTokens, collateral, accumulated fees, interest rate modifier	Receives updates from market-admin actions Receives operational updates from user actions processed by the market Tracks asset pools as the single source of truth for totals and fees
User obligations	Unified storage for all user positions in a market, keyed by ObligationKey	Stores deposits (jTokens + plain collateral), borrows (dTokens), and position counts Supports different obligation types via seed: standard (no seed), earn (earn seed), pair (pair seed) Enforces limits such as MaxPositions and MinCollateralValue Tracks active Insurance Fund cover requests	Updated whenever a user calls market methods (deposit, borrow, repay, withdraw, add_collateral, remove_collateral, batch operations) Records into the corresponding asset pools Evaluated by cross-pool logic for health and liquidation Target of liquidations initiated through the market
Cross-pool	Shared risk and health logic across pools	Performs cross-pool collateral evaluation Computes position health using pool/oracle data, open/close LTV, and liability factors Determines liquidation conditions for unhealthy obligations	Operates on user obligations (all types via ObligationKey) Decisions are enforced when a liquidator calls liquidate on the market Relies on pool state and oracle prices made available by the market
AMM DEX (Swap Provider)	External swap venue (configurable via update_swap_provider)	Executes swaps as part of composable batch operations Supports flash-loan-based operations that need token conversion	Called by the market during submit_requests_batch when swap requests are included Does not initiate interactions on its own
Oracle	External SEP-40 price oracle	Returns current asset prices for pools Enables valuation of collateral and debt Supports health checks and liquidation decisions	Queried by the market whenever up-to-date prices are needed (borrow, withdraw, liquidate) Provides price inputs used by cross-pool logic
Liquidator	External, permissionless actor (not the borrower)	Calls the market's liquidate method on unhealthy positions Repays debt and receives discounted collateral (subject to liquidation incentive limits) Can also liquidate within batch operations via LiquidateRequest	Sends liquidation transactions to the market Market applies cross-pool liquidation rules Market updates user obligations and affected asset pools