> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Stellar lending markets

> How Stellar Lending markets are addressed by hub and asset, listed in the controller, and accounted in the central pool.

A market is a `HubAssetKey`:

```rust theme={"system"}
HubAssetKey {
  hub_id: u32,
  asset: Address,
}
```

The controller uses that coordinate for user-facing market operations. The pool
uses the same coordinate for `Params(HubAssetKey)` and `State(HubAssetKey)`.
There is one central pool contract. Listing an asset creates rows in that pool;
it does not deploy a per-asset pool.

## Activation Model

There is no separate market-status enum. Price activation is controlled by the
token-rooted `AssetOracle(asset)` entry:

| State                 | On-chain shape                                                    | Effect                                                             |
| --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| Listed without oracle | Pool rows exist, `AssetOracle(asset)` missing                     | Oracle-dependent flows fail.                                       |
| Price-active          | Pool rows exist, `AssetOracle(asset)` exists and source validates | User flows proceed, subject to spoke flags and caps.               |
| Price-disabled        | `AssetOracle(asset)` removed                                      | Price reads fail until governance configures a valid source again. |

Spokes decide whether an account can use a hub asset as collateral or debt.
`SpokeAsset(spoke_id, HubAssetKey)` stores collateral flags, borrow flags, caps,
liquidation parameters, and optional oracle override.

## Listing Sequence

Listing is governance-controlled:

1. Approve the token for listing.
2. Deploy the central pool once if it does not exist.
3. Create the hub-asset pool rows.
4. Configure `AssetOracle(asset)` through governance.
5. Add or edit `SpokeAsset(spoke_id, HubAssetKey)` rows for the spokes that can
   use the asset.

`deploy_pool()` is protocol-wide. It is not called for each market.

## Pool Parameters

`MarketParamsRaw` lives in pool `Params(HubAssetKey)` storage.

| Field                     | Unit        | Meaning                                                |
| ------------------------- | ----------- | ------------------------------------------------------ |
| `base_borrow_rate_ray`    | RAY         | Rate at zero utilization.                              |
| `slope1_ray`              | RAY         | Slope below the first kink.                            |
| `slope2_ray`              | RAY         | Slope between first and optimal utilization.           |
| `slope3_ray`              | RAY         | Slope above optimal utilization.                       |
| `max_borrow_rate_ray`     | RAY         | Borrow-rate cap.                                       |
| `mid_utilization_ray`     | RAY         | First utilization kink.                                |
| `optimal_utilization_ray` | RAY         | Target utilization kink.                               |
| `max_utilization_ray`     | RAY         | Hard utilization cap.                                  |
| `reserve_factor_bps`      | BPS         | Share of borrower interest routed to protocol revenue. |
| `supply_cap`              | token units | Hub-level supply cap; zero or `i128::MAX` disables.    |
| `borrow_cap`              | token units | Hub-level borrow cap; zero or `i128::MAX` disables.    |
| `is_flashloanable`        | bool        | Whether flash loans can use this hub asset.            |
| `flashloan_fee`           | BPS         | Flash-loan fee.                                        |
| `asset_id`                | address     | Token contract.                                        |
| `asset_decimals`          | integer     | Token decimals used for conversions.                   |

Governance updates pool parameters through the timelock. The pool syncs accrued
interest under the old parameters before applying new values.

## Spoke Parameters

`SpokeAssetConfig` lives in controller `SpokeAsset(spoke_id, HubAssetKey)`
storage.

| Field                   | Unit            | Meaning                                          |
| ----------------------- | --------------- | ------------------------------------------------ |
| `is_collateralizable`   | bool            | Whether supply can count as collateral.          |
| `is_borrowable`         | bool            | Whether accounts on the spoke can borrow it.     |
| `paused`                | bool            | Blocks risk-increasing use for that spoke asset. |
| `frozen`                | bool            | Blocks position increases while allowing exits.  |
| `loan_to_value`         | BPS             | Borrow admission weight.                         |
| `liquidation_threshold` | BPS             | Health-factor collateral weight.                 |
| `liquidation_bonus`     | BPS             | Liquidator bonus.                                |
| `liquidation_fees`      | BPS             | Protocol fee from seized collateral.             |
| `supply_cap`            | token units     | Spoke-level supply cap.                          |
| `borrow_cap`            | token units     | Spoke-level borrow cap.                          |
| `oracle_override`       | optional config | Per-spoke price source override.                 |

## Configured Values

Configured market and spoke values live in this repository's `configs/` folder.
Do not treat those files as network state unless deployment evidence for the
target network has been published.

## Next

<CardGroup cols={2}>
  <Card title="Risk parameters" icon="sliders" href="/stellar-lending/dev/risk-parameters">
    Units, ranges, and configured values for market and spoke risk parameters.
  </Card>

  <Card title="Accounts and risk" icon="user-shield" href="/stellar-lending/dev/accounts-and-risk">
    Account storage, spoke binding, health factor, and position limits.
  </Card>

  <Card title="Oracles" icon="tower-broadcast" href="/stellar-lending/dev/oracles">
    Reflector and RedStone sources, tolerance bands, and flow policies.
  </Card>

  <Card title="Controller ABI" icon="code" href="/stellar-lending/dev/controller-abi">
    Controller entrypoints for listing, configuration, and user flows.
  </Card>
</CardGroup>