Supply and borrow

Supply and borrow go through the controller. For each call it resolves the account, loads the spoke configuration, gets a complete price snapshot, moves the tokens, and calls the central pool. Pool state is keyed by HubAssetKey. Prices are all-or-nothing. If any asset on the account cannot produce a trusted price, the whole call reverts — there is no lenient mode for one leg. Read first: Accounts and risk, Markets, and Health factor.

Supply

supply(
  caller: Address,
  account_id: u64,
  spoke_id: u32,
  assets: Vec<(HubAssetKey, i128)>,
) -> u64

Passing account_id = 0 creates a new account owned by caller and bound to spoke_id. Existing accounts keep their stored spoke; the supplied spoke_id must match that account.

Preconditions

caller authorizes the call and token transfers.
Each HubAssetKey names an existing market on an active hub.
A caller who is neither owner nor delegate may only add to hub assets the account already holds a supply position in. New accounts skip that check, because the caller becomes the owner.
The account’s spoke lists the hub asset.
The spoke asset is collateralizable and not blocked for increases.
Supply caps and position limits leave enough headroom.

Example

stellar contract invoke \
  --id <CONTROLLER> \
  --source-account <CALLER> \
  --network testnet \
  -- supply \
  --caller <CALLER> \
  --account_id 0 \
  --spoke_id 1 \
  --assets '[[{"hub_id":1,"asset":"<USDC>"}, "10000000000"]]'

Common errors

Error	Cause	Fix
`#104 NotCollateral`	Spoke asset cannot be used as collateral.	Use a collateralizable asset or another spoke.
`#311 SpokeSupplyCapReached`	Spoke supply cap exceeded.	Supply less or wait for cap headroom.
`#109 PositionLimitExceeded`	Account already holds max supply positions.	Consolidate positions or wait for a limit change.
`#315 SpokeAssetPaused`	Spoke asset is paused.	Wait for governance to unpause or use another asset.
`#316 SpokeAssetFrozen`	The listing is frozen: entry blocked, exit still open.	Withdraw and repay still work on a frozen asset.
`#51 SupplyRoundsToZeroShares`	The amount is too small to mint one scaled share.	Supply more.

Borrow

borrow(
  caller: Address,
  account_id: u64,
  borrows: Vec<(HubAssetKey, i128)>,
  to: Option<Address>,
)

Borrow records debt on account_id. Tokens go to to when set, otherwise to caller.

Preconditions

caller holds the account’s position NFT, or is an active delegate on it.
Each borrowed hub asset is listed by the account’s spoke and borrowable.
Borrow caps, liquidity, and utilization caps leave enough headroom.
Post-borrow LTV and health factor pass.
Every priced asset on the account resolves a valid price. One stale or disagreeing feed reverts the whole call.

Example

stellar contract invoke \
  --id <CONTROLLER> \
  --source-account <CALLER> \
  --network testnet \
  -- borrow \
  --caller <CALLER> \
  --account_id 42 \
  --borrows '[[{"hub_id":1,"asset":"<XLM>"}, "2000000000"]]' \
  --to null

Common errors

Error	Cause	Fix
`#107 AssetNotBorrowable`	Spoke asset is not borrowable.	Borrow an allowed asset.
`#312 SpokeBorrowCapReached`	Spoke borrow cap exceeded.	Borrow less or wait for cap headroom.
`#100 InsufficientCollateral`	LTV gate fails.	Add collateral or borrow less.
`#47 BorrowRoundsToZeroShares`	The amount is too small to mint one scaled debt share.	Borrow more.
`#112 InsufficientLiquidity`	Pool `cash` is below requested amount.	Borrow less or wait for liquidity.
`#126 MinBorrowCollateralNotMet`	Debt remains but collateral is below the configured floor.	Add collateral or reduce debt.
`#127 UtilizationAboveMax`	Post-borrow utilization is too high.	Borrow less or wait for more supply.

Verification

A successful supply or borrow emits UpdatePositionBatchEvent from the controller (["position", "batch_update"]) and PoolMarketStateBatchEvent from the pool (["market", "batch_state_update"]). Read back state through get_account_positions, get_collateral_amount(account_id, hub_asset), get_borrow_amount(account_id, hub_asset), and get_health_factor.

Withdraw and repay

Exit collateral and repay debt.

Flash loans

Borrow and repay inside one callback.

Start here

Concepts

Integration guides

Reference

Operations

Supply

Preconditions

Example

Common errors

Borrow

Preconditions

Example

Common errors

Verification

Next

Withdraw and repay

Flash loans

​Supply

​Preconditions

​Example

​Common errors

​Borrow

​Preconditions

​Example

​Common errors

​Verification

​Next

Withdraw and repay

Flash loans

Supply

Preconditions

Example

Common errors

Borrow

Preconditions

Example

Common errors

Verification

Next