Data types

These are the on-chain field names and numeric scales used by contract calls and views. Event-specific tuple layouts are defined in Events. For HTTP responses, use the SDK-owned types from @xoxno/sdk-js/stellar-lending/read. The integrator API returns display amounts and APYs, rather than the raw contract shares below.

Numeric scales

Scale	Value	Used for
RAY	`10^27`	Indexes, rates, utilization, and scaled share balances.
WAD	`10^18`	USD values, health factors, and price bounds.
Basis points (bps)	`10,000 = 100%`	LTV, liquidation parameters, and fees.
Raw asset units	Token decimals	Token transfers and supply or borrow caps.

Read token decimals from MarketParamsRaw.asset_decimals or the token contract. Timestamp units are specified per field.

`HubAssetKey`

HubAssetKey {
  hub_id: u32,
  asset: Address,
}

Identifies a market. The same token under two hubs is two independent markets.

Account model

There is no single Account struct on the wire. Account state is split across four controller records plus the position-NFT contract:

Record	Holds
`AccountMeta(account_id)`	`{ spoke_id: u32, mode: PositionMode }`
`SupplyPositions(account_id)`	`Map<HubAssetKey, AccountPositionRaw>`
`BorrowPositions(account_id)`	`Map<HubAssetKey, DebtPositionRaw>`
`Delegates(account_id)`	`DelegateGrant { granted_by: Address, delegates: Vec<Address> }`

The account_id is the position NFT’s token_id. The NFT contract supplies ownership for authorization checks. Controller ids use u64, but mintable NFT ids fit u32. Preserve account ids as decimal strings in JavaScript. The SDK’s accountNonce refers to the lending id; sourceSequence refers to the Stellar source account sequence. AccountAttributes is the view projection of AccountMeta: { spoke_id: u32, mode: PositionMode }. Accounts bind to a spoke id >= 1, and the binding never changes.

`PositionMode`

#[repr(u32)], so it is a plain u32 on the wire.

Variant	Value	Meaning
`Normal`	0	Standard supply and borrow.
`Multiply`	1	Leveraged collateral/debt loop.
`Long`	2	Directional long strategy.
`Short`	3	Directional short strategy.

Fixed at account creation and enforced on every later multiply or flash_position call against that account (#25 AccountModeMismatch).

`AccountPositionRaw`

Field	Scale	Meaning
`scaled_amount`	RAY	Supply shares.
`liquidation_threshold`	bps	Threshold stamped onto the position.
`liquidation_bonus`	bps	Bonus stamped onto the position.
`loan_to_value`	bps	LTV stamped onto the position.
`liquidation_fees`	bps	Protocol liquidation fee stamped onto the position.

`DebtPositionRaw`

Field	Scale	Meaning
`scaled_amount`	RAY	Debt shares.

`SpokeConfig`

Field	Scale	Meaning
`is_deprecated`	—	Blocks ordinary account creation and new asset listings. Existing accounts retain their spoke; liquidation can still create a `Credit(0)` receiver there.
`liquidation_target_hf_wad`	WAD	The health factor a liquidation aims to restore the account to.
`hf_for_max_bonus_wad`	WAD	The health factor at or below which the bonus is maximal.
`liquidation_bonus_factor_bps`	bps	Scaling factor applied to the bonus curve increment.

`SpokeAssetConfig`

Field	Scale	Meaning
`is_collateralizable`	—	Whether supply counts as collateral in this spoke.
`is_borrowable`	—	Whether accounts can borrow it.
`paused`	—	Blocks ordinary entry and exit; liquidation seizure checks `no_seize` instead.
`frozen`	—	Blocks entry only; exit remains open.
`no_seize`	—	Blocks only the liquidation seizure leg.
`loan_to_value`	bps	Borrowing power per unit of collateral.
`liquidation_threshold`	bps	Health-factor collateral weight.
`liquidation_bonus`	bps	Base liquidator discount.
`liquidation_fees`	bps	Protocol’s share of the bonus.
`supply_cap`	raw asset units	Spoke supply cap. Zero means no new exposure.
`borrow_cap`	raw asset units	Spoke borrow cap. Zero means no new exposure.

The three halt flags are independent. Their operation-specific effects are described in Risk parameters. SpokeAssetArgs is the write-side input shape. It uses different field names for the same values: can_collateral, can_borrow, ltv, threshold, bonus, plus hub_id, asset, spoke_id, the three flags, liquidation_fees, supply_cap, and borrow_cap. EditAssetInSpoke cannot clear a halt flag. Governance uses RelaxSpokeAssetFlagsArgs for that operation:

Field	Type	Meaning
`spoke_id`	`u32`	Risk spoke.
`hub_asset`	`HubAssetKey`	Hub and token together.
`expected_epoch`	`u64`	Current result of `get_spoke_asset_flags_epoch`. Checked at proposal and execution.
`paused`, `frozen`, `no_seize`	`bool`	Requested flag values after execution.

A subsequent flag change invalidates the scheduled epoch. Read the current epoch and propose again instead of reusing an obsolete payload.

`SpokeUsageRaw`

Field	Scale
`supplied_scaled_ray`	RAY
`borrowed_scaled_ray`	RAY

`MarketParamsRaw`

Defines a pool market. The field names do not include _ray or _bps suffixes; use the scales below. Supply and borrow caps belong to SpokeAssetConfig.

Field	Scale	Meaning
`max_borrow_rate`	RAY	Upper cap on the borrow-rate curve, at most `2 * RAY` (200% APR). The curve need not reach it.
`base_borrow_rate`	RAY	Borrow rate at zero utilization.
`slope1`	RAY	Rate contribution reached at the mid utilization breakpoint.
`slope2`	RAY	Rate contribution reached at the optimal breakpoint.
`slope3`	RAY	Rate contribution reached at 100% utilization.
`mid_utilization`	RAY	First utilization breakpoint.
`optimal_utilization`	RAY	Second utilization breakpoint.
`max_utilization`	RAY	Utilization ceiling for borrows and ordinary withdrawals; liquidation withdrawals skip it.
`reserve_factor`	bps	Share of borrow interest booked as protocol revenue.
`is_flashloanable`	—	Whether flash loans are enabled for this market.
`flashloan_fee`	bps	Flash-loan fee. Capped at `MAX_FLASHLOAN_FEE_BPS = 500`.
`asset_id`	—	The market’s underlying token contract.
`asset_decimals`	—	Token decimals, 0..=18. Use this to interpret every raw-asset-unit amount for this market.

InterestRateModel is the same set minus asset_id and asset_decimals; it is what upgrade_liquidity_pool_params takes. Markets below 3 decimals cannot enable borrowing or flash loans. Their spoke liquidation fee is zero, and their collateral must occupy the account’s only supply slot. Debt-bearing risk checks require at least 2 token base units in that leg: 2 tokens at 0 decimals, 0.2 at 1 decimal, or 0.02 at 2 decimals.

`PoolStateRaw`

Field	Scale	Meaning
`supplied`, `borrowed`, `revenue`	RAY	Scaled market totals; revenue is included in supply.
`supply_index`, `borrow_index`	RAY	Stored interest indexes.
`cash`	Token base units	Tracked market cash.
`last_timestamp`	Milliseconds	Last committed accrual time.

Liquidation types

`SeizeMode`

enum SeizeMode {
  Transfer,      // pool pays underlying, withholding the protocol fee
  Credit(u64),   // seized supply shares move to a controller account
}

Credit(0) creates the receiving account, owned by the liquidator and bound to the liquidated account’s spoke. A non-zero id must already satisfy all five of these:

it exists;
it is not the liquidated account itself (#133);
the liquidator owns it, or is a delegate on it;
it sits in the liquidated account’s spoke;
it is in PositionMode::Normal.

`LiquidationEstimate`

Field	Meaning
`seized_collaterals`	`Vec<PaymentTuple>` — gross of `protocol_fees`.
`protocol_fees`	`Vec<PaymentTuple>` — the protocol’s cut, taken from the bonus.
`refunds`	`Vec<PaymentTuple>` — unused offered debt-token amounts in the estimate. Partial repayment pulls the planned amounts; a full-close plan pulls the merged offers and the pool refunds excess.
`max_payment_wad`	WAD — the USD value of the accepted planned repayment.
`bonus_rate_bps`	bps — the applied bonus rate.

seized_collaterals and protocol_fees use native collateral units for Transfer, RAY-scaled supply shares for Credit. refunds always uses native debt-token units. PaymentTuple is { asset: Address, amount: i128 }.

`MarketIndexView`

Returned by get_market_indexes_detailed.

Field	Scale	Meaning
`asset`	—	Token contract.
`supply_index` / `borrow_index`	RAY	Current indexes.
`price_wad`	WAD	Resolved blended price.
`primary_price_wad` / `anchor_price_wad`	WAD	Individual legs.
`price_timestamp`	s	Timestamp of the older leg.
`stale` / `deviation` / `valid`	—	Failure flags.
`error_code`	—	`Option<u32>`: the `OracleError` discriminant that made the price unusable, if any.

Treat valid: false as unusable and inspect error_code for the cause. A resolution error can zero both stale and deviation; false flags alone do not prove a successful price read.

Oracle types

Oracle configuration is stored on the price aggregator, keyed by PriceKey:

enum PriceKey {
  Token(Address),   // a token contract
  Ref(Symbol),      // a synthetic reference used as an intermediate quote
}

`AssetOracle`

Field	Scale	Meaning
`asset_decimals`	—	Token amount decimals (0..=18), or 0 for a reference key. Normalized prices use WAD.
`max_price_stale_seconds`	s	Maximum age a blended price may have.
`sources`	—	`Vec<PriceSource>`, one or two entries.
`tolerance`	—	`OracleTolerance { upper_ratio_bps, lower_ratio_bps }`, the agreement band between two sources.
`independence`	—	`IndependencePolicy`: `RequireDisjoint` or `AllowShared(Vec<Address>)`.
`min_sanity_price_wad`	WAD	Lower bound a resolved price must fall within.
`max_sanity_price_wad`	WAD	Upper bound.

`PriceSource`

enum PriceSource {
  Feed(FeedSource),
  Scaled(ScaledSource),
  AquariusLp(AquariusLpSource),
  AquariusStableLp(AquariusLpSource),
}

FeedSource { provider: ProviderRef, decimals: u32, max_stale_seconds: u64 }, where ProviderRef is Reflector(ReflectorFeedRef), RedStone(MultiFeedRef), or Xoxno(MultiFeedRef). Reflector references carry an OracleReadMode of Spot or Twap(records); RedStone and Xoxno references carry a FeedNature of Market or Fundamental. See Oracles for how these compose.

Start here

Core concepts

Lending actions

Strategies and integrations

System behavior

Reference

Operations

Numeric scales

`HubAssetKey`

Account model

`PositionMode`

`AccountPositionRaw`

`DebtPositionRaw`

`SpokeConfig`

`SpokeAssetConfig`

`SpokeUsageRaw`

`MarketParamsRaw`

`PoolStateRaw`

Liquidation types

`SeizeMode`

`LiquidationEstimate`

`MarketIndexView`

Oracle types

`AssetOracle`

`PriceSource`

​Numeric scales

​HubAssetKey

​Account model

​PositionMode

​AccountPositionRaw

​DebtPositionRaw

​SpokeConfig

​SpokeAssetConfig

​SpokeUsageRaw

​MarketParamsRaw

​PoolStateRaw

​Liquidation types

​SeizeMode

​LiquidationEstimate

​MarketIndexView

​Oracle types

​AssetOracle

​PriceSource

Numeric scales

`HubAssetKey`

Account model

`PositionMode`

`AccountPositionRaw`

`DebtPositionRaw`

`SpokeConfig`

`SpokeAssetConfig`

`SpokeUsageRaw`

`MarketParamsRaw`

`PoolStateRaw`

Liquidation types

`SeizeMode`

`LiquidationEstimate`

`MarketIndexView`

Oracle types

`AssetOracle`

`PriceSource`