Flash loans

Borrow one pool asset for the span of a single transaction, do arbitrary work in your receiver contract, and repay amount + fee before the call returns. Read first: Strategies, Security model. Call the controller; it issues one pool flash_loan. The pool sends amount to your receiver, runs the callback, then pulls amount + fee back in the same call. The controller emits FlashLoanEvent.

Goal

Obtain amount of a flashloanable asset, run your logic in a receiver contract, and have the pool reclaim amount + fee in the same transaction.

// Controller entrypoint
flash_loan(
    caller: Address,
    asset: HubAssetKey,
    amount: i128,
    receiver: Address,
    data: Bytes,
)

The controller forwards to the pool’s single settlement call, which computes the fee itself and returns it:

// Pool — one atomic call, controller-only
flash_loan(
    hub_asset: HubAssetKey,
    initiator: Address,
    receiver: Address,
    amount: i128,
    data: Bytes,
) -> i128   // the fee charged

Preconditions

asset names a listed market whose is_flashloanable is true (else #401 FlashloanNotEnabled), and whose hub is active.
receiver is a deployed Wasm contract (else #412 InvalidFlashloanReceiver) that exports execute_flash_loan.
The pool holds at least amount of free liquidity.
amount > 0 (else #14 AmountMustBePositive).
No flash loan is already in progress for this transaction (the FlashLoanOngoing reentry guard, else #400).

Inputs

Address

required

Initiator. Authorizes the flash loan. Need not be the receiver.

HubAssetKey

required

The market to borrow from: { hub_id, asset }. The same token under two hubs is two independent markets with independent flash-loan settings.

i128

required

Borrowed amount in asset-native units. Must be positive.

Address

required

The contract that receives amount, runs execute_flash_loan, and approves repayment.

Bytes

required

Opaque payload forwarded verbatim to the receiver’s callback. Encode whatever your receiver needs.

Fee

The fee is flashloan_fee bps of amount from the market’s MarketParamsRaw, rounded half-up and raised to 1 unit whenever a positive fee would otherwise round to zero. It is capped at MAX_FLASHLOAN_FEE_BPS = 500 (5%) at configuration time. The fee is retained by the pool as protocol revenue, later claimable through the controller’s claim_revenue.

Receiver contract

Your receiver is a separate contract that must export:

execute_flash_loan(
    initiator: Address,
    asset: Address,
    amount: i128,
    fee: i128,
    pool: Address,
    data: Bytes,
)

The pool calls it after transferring amount to the receiver. Before the callback returns, the receiver must approve the pool to pull amount + fee of asset — repayment is a transfer_from the pool performs, not an ERC-20-style allowance you set ahead of time. Authorize that approval as the current contract.

#![no_std]
use soroban_sdk::{
    contract, contractimpl, token, Address, Bytes, Env,
    auth::{ContractContext, InvokerContractAuthEntry, SubContractInvocation},
    symbol_short, IntoVal, Vec,
};

#[contract]
pub struct Receiver;

#[contractimpl]
impl Receiver {
    pub fn execute_flash_loan(
        env: Env,
        _initiator: Address,
        asset: Address,
        amount: i128,
        fee: i128,
        pool: Address,
        _data: Bytes,
    ) {
        // ... do work with `amount` of `asset` (must end holding amount + fee) ...

        let total = amount + fee;
        let me = env.current_contract_address();
        let expiry = env.ledger().sequence() + 1;

        // Authorize the pool's transfer_from by pre-approving as this contract.
        let approve = InvokerContractAuthEntry::Contract(SubContractInvocation {
            context: ContractContext {
                contract: asset.clone(),
                fn_name: symbol_short!("approve"),
                args: (me.clone(), pool.clone(), total, expiry).into_val(&env),
            },
            sub_invocations: Vec::new(&env),
        });
        let mut entries = Vec::new(&env);
        entries.push_back(approve);
        env.authorize_as_current_contract(entries);

        token::Client::new(&env, &asset).approve(&me, &pool, &total, &expiry);
    }
}

If the receiver does not approve enough, the pool’s transfer_from reclaims less than amount + fee and the call reverts with #402 InvalidFlashloanRepay. The pool also asserts the receiver did not otherwise change the pool balance during the callback.

Build the call

# Flash-borrow 10,000 USDC (7 decimals) to your receiver contract.
stellar contract invoke \
  --id <CONTROLLER> \
  --source-account caller \
  --network testnet \
  -- flash_loan \
  --caller C... \
  --asset '{"hub_id":1,"asset":"CUSDC..."}' \
  --amount 100000000000 \
  --receiver CRECEIVER... \
  --data <xdr-bytes>

import { Contract, nativeToScVal, Address, xdr } from "@stellar/stellar-sdk";

const controller = new Contract("C...");

const op = controller.call(
  "flash_loan",
  new Address(callerPublicKey).toScVal(),
  nativeToScVal(
    { hub_id: 1, asset: new Address("CUSDC...") },
    { type: { hub_id: ["symbol", "u32"], asset: ["symbol", "address"] } },
  ),
  nativeToScVal(100_000_000_000n, { type: "i128" }),
  new Address("CRECEIVER...").toScVal(),
  xdr.ScVal.scvBytes(payload), // opaque data for your receiver
);
// build, prepareTransaction (simulate — auto-discovers the receiver's auth), sign with caller, send

Authorize

caller.require_auth() runs inside the controller’s flash_loan. The cross-contract authorization that matters is the receiver authorizing the pool’s transfer_from during the callback — handled inside execute_flash_loan with authorize_as_current_contract, not by the top-level signer. The payout (pool → receiver) is pool-internal. Simulating the transaction discovers and attaches the auth tree; sign the outer call with the caller key. Reentry. While the callback runs, the controller holds the FlashLoanOngoing guard. Any attempt to call back into a mutating controller entrypoint — supply, borrow, withdraw, repay, liquidate, a strategy, or another flash_loan — reverts with #400 FlashLoanOngoing.

Verify

On success the controller emits FlashLoanEvent — topics ["position", "flash_loan"], data { hub_id, asset, receiver, caller, amount, fee } — and the pool emits PoolMarketStateBatchEvent (["market", "batch_state_update"]) reflecting the fee booked as revenue. Confirm the fee landed with the pool view get_revenue(hub_asset) (up by fee), and check your receiver’s token balance returned to its pre-loan level (it paid back amount + fee).

Failure modes

Error	Cause	Fix
`#401 FlashloanNotEnabled`	The market’s `is_flashloanable` is false	Use a flash-loan-enabled market; read `is_flashloanable` from `PoolMarketParamsBatchEvent` or `get_sync_data`.
`#412 InvalidFlashloanReceiver`	`receiver` is not a deployed Wasm contract	Pass a deployed contract address that exports `execute_flash_loan`.
`#402 InvalidFlashloanRepay`	Receiver approved less than `amount + fee`, or changed the pool balance	Approve exactly `amount + fee` to the pool before the callback returns.
`#400 FlashLoanOngoing`	Reentry into a mutating controller entrypoint during the callback	Do not call back into the controller; do your work, then repay.
`#14 AmountMustBePositive`	`amount` is zero or negative	Borrow a positive amount.

`flash_position` — the collateralized cousin

flash_position is a distinct entrypoint with different semantics. It mints strategy debt onto an account with no flash fee, forwards the measured tokens to receiver, invokes its execute_flash_position callback, and deposits measured controller-balance increases of the declared collaterals. It does not repay. The debt stands at its full minted amount.

flash_position(
    caller: Address,
    account_id: u64,              // 0 creates the account
    spoke_id: u32,
    mode: PositionMode,
    debt: HubAssetKey,
    amount: i128,
    receiver: Address,
    data: Bytes,
    collaterals: Vec<(HubAssetKey, i128)>,
    refund_assets: Vec<Address>,
) -> u64

receiver must be a deployed Wasm contract, and must be neither the controller nor the pool. The position must remain open: the account must end with live debt in debt and at least one supply position, else #505 FlashPositionClosed.

The two declaration lists

Soroban has no way to list every token an address holds. A contract can only ask a named token contract for a balance. So the controller cannot discover what your receiver sent back. It can only check the assets you told it to check. These two lists are how you tell it. Each list does two jobs:

It bounds the work. Every entry costs two cross-contract balance() calls, so both lists are capped at max_supply_positions.
It bounds the trust. Every entry is checked against the spoke’s listing before your callback runs, so the controller never calls an arbitrary address you picked.

The controller takes two balance snapshots inside the flash guard, right before calling you. Everything after that is measured as a difference from those snapshots.

`collaterals` — the amount is a minimum

The i128 is a slippage floor, not a cap and not an exact expectation. The measured delta is what gets deposited, never the declared figure.

Receiver delivers	Result
More than declared	All of it becomes collateral
Less than declared	Revert `#504 CollateralMinimumNotMet`
Zero, where the minimum is 0	Leg silently skipped
Zero on every declared asset	Revert `#504` — the deposit set is empty

All of this is checked before your callback runs:

The list is not empty.
It holds at most max_supply_positions entries.
Every minimum is zero or positive.
No duplicate HubAssetKey, and no duplicate underlying token address either — the same token can be listed under two hubs.
Every asset is listed on the account’s spoke, is collateralizable, and is not halted.
At least one minimum is above zero, else #503 CollateralRequired.
The usual supply gates pass: caps and position-count limits.

`refund_assets` — delta only, paid to the caller

The refund leg transfers balance − baseline, and only when that difference is positive. It is never the controller’s gross balance. The recipient is caller, not the receiver and not the account owner.

Rule	Error
At most `max_supply_positions` entries	`#16 InvalidPayments`
No duplicates	`#16 InvalidPayments`
Must be listed and active in the account’s spoke	listing error
Must not overlap any declared collateral asset	`#16 InvalidPayments`

Why must a refund asset be listed? Because the refund step hands an address you chose to a token contract after the flash guard has closed. Requiring it to be listed keeps that call on a contract governance already approved.

Returning the debt token does not repay. flash_position has no repay leg. Debt tokens handed back by the receiver are refunded to the caller and the debt stands at its full minted amount. The debt asset may appear in refund_assets, and the overlap check is only against collaterals.Refunds are silent, and there is no dry run. No view or return value tells you in advance whether a refund will occur; no refund event exists, and FlashPositionEvent carries no refund field. The only on-chain trace is the token contract’s own transfer event, controller to caller.Unlisted leftovers are stranded. An asset that is neither a declared collateral nor in refund_assets stays in the controller permanently, and no later caller can sweep it — a subsequent user’s baseline already contains it. There is no sweep or rescue entrypoint, deliberately: it would be exactly the primitive the measured-delta discipline exists to eliminate.

Receiver author checklist

Set each minimum to a real slippage floor — it is the only post-callback protection against a bad route.
At least one minimum must be positive.
List in refund_assets every asset the callback might return, including the debt asset if it might not be fully spent.
refund_assets may not overlap collaterals, may not duplicate, and every entry must be listed in the account’s spoke.
Do not expect a returned debt token to repay anything.
End the callback with the position still open: live debt in debt and at least one supply position.

Observer note: the strategy-debt mint is tagged FlashPos (16) in the position batch; collateral deposited from the callback is tagged Supply, identically to an ordinary deposit. FlashPositionEvent.fee is always 0.

Strategy borrow vs flash loan

Strategy flows (multiply, migrate_from_blend) borrow through pool.create_strategy, not the flash-loan receiver pattern:

Mechanism	`flash_loan`	`flash_position`	Strategy borrow
Pool call	`pool.flash_loan` → receiver callback	`pool.create_strategy` + receiver callback	`pool.create_strategy`
Fee	Configured bps	0	0 for migration; configured for multiply
Debt outcome	Repaid in same callback	Permanent account debt	Permanent account debt
Collateral	None	Measured deltas of declared assets	Swap proceeds
Solvency check	At callback end	At `strategy_finalize`	At `strategy_finalize`

See Strategies for the full contrast.

Strategies

Leverage and swap flows that build on the flash loan plus the swap aggregator.

Controller ABI

Every controller entrypoint, grouped by access control.

Start here

Concepts

Integration guides

Reference

Operations

Goal

Preconditions

Inputs

Fee

Receiver contract

Build the call

Authorize

Verify

Failure modes

`flash_position` — the collateralized cousin

The two declaration lists

`collaterals` — the amount is a minimum

`refund_assets` — delta only, paid to the caller

Receiver author checklist

Strategy borrow vs flash loan

Next

Strategies

Controller ABI

​Goal

​Preconditions

​Inputs

​Fee

​Receiver contract

​Build the call

​Authorize

​Verify

​Failure modes

​flash_position — the collateralized cousin

​The two declaration lists

​collaterals — the amount is a minimum

​refund_assets — delta only, paid to the caller

​Receiver author checklist

​Strategy borrow vs flash loan

​Next

Strategies

Controller ABI

Goal

Preconditions

Inputs

Fee

Receiver contract

Build the call

Authorize

Verify

Failure modes

`flash_position` — the collateralized cousin

The two declaration lists

`collaterals` — the amount is a minimum

`refund_assets` — delta only, paid to the caller

Receiver author checklist

Strategy borrow vs flash loan

Next