Architecture Overview

Architecture Overview

XOXNO Lending connects suppliers and borrowers through lending markets. Markets hold liquidity and track balances; accounts hold collateral and debt under a spoke's risk rules.

Markets and hubs

A market is identified by a hub ID and a token address. It has its own recorded cash, supply and debt shares, interest indexes, revenue, and interest-rate parameters. A hub groups these market identities.

The same token can appear in more than one hub. Those markets have separate accounting, so borrowing and bad-debt losses belong to the affected market. All markets use one central pool contract for custody. Listings of the same token therefore share its physical token balance and exposure to that token contract.

Suppliers earn interest through the market's supply index. Borrowers accrue interest through its borrow index. Withdrawals and borrowing require available market cash; an account's healthy collateral balance does not guarantee immediate liquidity.

Spokes and risk rules

A spoke defines which hub-asset markets an account can use and the rules for each listing. These include collateral and borrowing permissions, loan-to-value (LTV), liquidation thresholds, fees, supply and borrow caps, and restrictions on entry, exit, or seizure.

Spokes can list the same market with different risk parameters while sharing that market's liquidity and indexes. Different spoke rules do not create separate cash balances or separate bad-debt protection within the shared market.

An account is bound to its spoke when created. Its spoke cannot be changed by passing another ID in a later transaction. Some risk values are stored with positions, so a listing update does not automatically replace every held position's risk values. Health Factor and Collateral explains how those values affect borrowing and health.

Accounts and ownership

An account groups supply positions and debt positions. A position is the account's balance in one market on one side: supply or debt. An account can hold several assets within the configured position limits.

Each account has a position NFT that determines its owner. Transferring the NFT transfers control of the entire lending account, including collateral and debt. Delegated management also requires an active protocol-approved manager and a grant from the account owner. See Managing Positions before transferring or delegating an account.

Contract responsibilities

The controller coordinates lending actions. The pool holds tokens and maintains market books. Governance administers the system, and a separate price aggregator supplies validated prices.

flowchart LR
    User[Account owner or integrator] --> Controller
    Governance -->|administration| Controller
    Governance -->|source configuration| Prices[Price aggregator]
    Controller -->|ownership lookup| NFT[Position NFT]
    Controller -->|valuation| Prices
    Controller -->|accounting and settlement| Pool[Central pool]
    Controller -->|strategy swaps| Router[Swap aggregator]
    Pool --> Tokens[Token contracts]
    Prices --> Sources[Price sources]

Loading

Component	Responsibility
Controller	Account authorization, risk checks, position actions, liquidation, and strategies
Central Pool	Token custody, market cash, shares, indexes, and revenue
Governance and Timelock	Typed administrative proposals, delayed execution, roles, and restricted immediate actions
Position NFT	Account ownership, transfers, and NFT approvals
Oracle System	Validated prices from configured sources and dependencies
Swap aggregator	Route execution and route-level fees and output limits
Vault Integration	Supply-only lending accounts for DeFindex vaults

The repository's deployment helpers set governance as controller and price-aggregator owner, and the controller as pool and NFT authority. Controller ownership can be transferred. The swap aggregator and XOXNO oracle have separately configured owners; their addresses alone do not establish shared governance or a timelock.

Risk boundaries

Collateral, interest, liquidation, and supplier losses follow the configured markets and account rules. Shared custody also creates shared exposure to pool code and authorized upgrades. Prices, external contracts, token behavior, and storage availability remain trust and availability boundaries.

Continue with Health Factor and Collateral. For contract authority and custody details, use the architecture reference.