Swap aggregator ABI

The swap aggregator executes on-chain swap routes for controller strategies and direct callers. The Stellar Aggregator service builds the encoded route payloads. The contract has its own owner and two-step ownership transfer, separate from lending governance. Controller strategies constrain its authority and measure balance changes; see Strategies.

Execute a strategy

execute_strategy(sender: Address, total_in: i128, swap_xdr: Bytes) -> i128

It decodes and validates swap_xdr as a StrategyPayload, pulls total_in from sender, and credits the measured receipt. It applies any input fee, executes swaps and LP operations in their encoded order, applies any output fee, checks minimum output, and pays sender. Remaining token balances are settled as residual revenue before it returns the output amount. Anyone may call it. sender authorizes the pull. A payload that fails to decode raises #13 InvalidRouteXdr.

execute_strategy enforces the minimum output encoded in the payload. The controller does not enforce a separate exchange-rate floor. Falling short raises #5 SlippageExceeded; set the minimum output when requesting the quote.

Strategy payload

swap_xdr decodes from ScVal XDR into two registries and a packed program:

StrategyPayload {
    amounts: Vec<i128>,    // minimum output, fixed inputs, LP burn floors
    assets: Vec<Address>,  // tokens, pools, LP share tokens
    ops: Bytes,            // packed instruction stream
}

Instructions refer to registry entries by u8 index. Each instruction occupies five bytes. The ops stream begins with this ten-byte header:

Bytes	Field
`0`	Wire version.
`1`	Input token index in `assets`.
`2`	Output token index in `assets`.
`3`	Minimum output index in `amounts`.
`4..8`	Referral id, `u32` big-endian; `0` disables static and referral fees.
`8`	Instruction count.
`9`	Split-weight count.

Split weights are u24 big-endian parts per million, each in 1..=1_000_000. Each weight applies to the input token’s remaining balance at that instruction; the weights have no sum requirement. A 50/50 split uses 500_000, then All to spend the remainder, including rounding dust. Use the quote service to produce these bytes. The wire layout is reference material. The current wire version is 1. A program permits at most 48 instructions, 32 split weights, 256 assets, and 126 amounts. The packed stream length is 10 + 5 * instruction_count + 3 * split_weight_count bytes. Use the SDK’s public decodeStellarRouteBytes to inspect a route and verifyStellarRouteBytes to check your expected pair, input amount, and minimum output. Use mapQuoteResponseToStrategySwap when you have the quote response. Pass caller-owned values in expected; checking response fields alone does not prove the trade matches your request. Integrations forward the verified payload bytes without rebuilding the program.

Fees

Each configured fee is capped at FEE_CAP = 1000 basis points (10%). When fees apply, their combined rate must also be at most 1000 bps. Exceeding either limit raises #21 FeeTooHigh.

Fee	Set by	Paid to
Static fee	Contract owner, via `set_static_fee`	The contract owner’s fee bucket
Referral fee	Contract owner, via `add_referral` / `set_referral_fee`	That referral’s configured owner

A payload carries a referral id in its header (u32, where 0 means none). Both fees require an active referral. A zero, unknown, or inactive referral id charges neither the static fee nor the referral fee. Static and referral fees each round down in token base units. Their rounded amounts are added; the router does not round the combined rate once. Fees use the input token unless only the output token is fee-whitelisted; then they use the output token. The whitelist selects the fee side and does not restrict which tokens can be swapped. Fees accrue into per-token buckets and are claimed separately. After payout, residual balances accrue to the admin bucket independently of referral fees. Each token’s residual must be at most max(1000, floor(credited_amount / 1_000_000)) native units, or execution reverts with #29 ExcessiveResidual. The router retains permitted residuals as admin revenue; it does not refund unused input to the sender. The lending controller can refund input that the router never pulled, which is a separate balance check.

Claiming fees

Function	Auth	Notes
`claim_referral_fees(id, tokens)`	Anyone	Pays that referral’s accrued balances to its configured owner, not to the caller. The only claim path that is not owner-gated.
`claim_admin_fees(recipient, tokens)`	Owner only	Pays the admin bucket, including static fees and residual revenue, to `recipient`.

Owner-only administration

The contract owner authorizes these calls.

Function	Purpose
`set_static_fee(fee_bps)`	Sets the static rate for swaps with an active referral. Capped at 1000 bps.
`add_to_whitelist(token)` / `remove_from_whitelist(token)`	Manages the whitelist used to select the fee token.
`add_referral(owner, fee_bps) -> u64`	Registers a referral and returns its id. Capped at 1000 bps.
`set_referral_fee(id, fee_bps)`	Changes a referral’s rate.
`set_referral_active(id, active)`	Enables or disables a referral.
`set_referral_owner(id, new_owner)`	Changes the recipient of that referral’s fees.
`claim_admin_fees(recipient, tokens)`	Pays out the admin fee and residual-revenue bucket.
`sweep_balance(recipient, tokens)`	Recovers stray token balances. Leaves fee buckets intact.
`upgrade(new_wasm_hash)`	Replaces the contract Wasm.

Transfer ownership in two steps: call transfer_ownership(new_owner, live_until_ledger), then have the incoming owner call accept_ownership(). get_owner() returns None when no owner is set. The router exposes no renounce_ownership entrypoint.

Open reads

Function	Returns
`admin() -> Address`	Current owner; raises `#20 NotAdmin` if ownership is unset.
`get_owner() -> Option<Address>`	Current owner, or `None`.
`static_fee_bps() -> u32`	The static fee.
`referral(id) -> Option<ReferralConfig>`	A referral’s owner, rate, and active flag.
`referral_counter() -> u64`	How many referrals have been registered.
`is_whitelisted(token) -> bool`	Fee-whitelist membership.
`whitelisted_tokens() -> Vec<Address>`	The full fee whitelist.
`admin_fee_balance(token) -> i128`	Unclaimed static fees and residual revenue for one token.
`referral_fee_balance(id, token) -> i128`	Unclaimed referral balance for one token.

Error codes

Match these codes within the swap aggregator’s error domain. The lending contracts use a separate enum.

Code	Name	Meaning
`1`	`EmptyBatch`	Instruction count is zero or above 48, or split-weight count exceeds 32.
`3`	`InvalidAmount`	Non-positive amount, token-ledger overdraft, or spend mismatch.
`4`	`BrokenTokenChain`	A `Prev` instruction lacks a predecessor output or names a different input token.
`5`	`SlippageExceeded`	Minimum output is non-positive, or delivered output fell below it.
`7`	`ZeroOutput`	The route produced nothing.
`9`	`IntegerOverflow`	Arithmetic overflowed.
`11`	`ZeroSplitPpm`	A split weight was zero.
`12`	`SplitPpmMismatch`	An individual split weight exceeds `1_000_000`.
`13`	`InvalidRouteXdr`	Invalid payload XDR or malformed packed program.
`20`	`NotAdmin`	`admin()` was called when no Ownable owner is set.
`21`	`FeeTooHigh`	An individual fee or the combined static/referral rate exceeds 1000 bps.
`22`	`ReferralNotFound`	No referral registered under that id.
`25`	`SameToken`	The program or a swap hop uses the same input and output token.
`26`	`LpTokenMismatch`	The LP share token does not match the pool.
`27`	`MinSharesNotMet`	An LP mint produced fewer shares than required.
`28`	`MinAmountsNotMet`	An LP burn returned less than required.
`29`	`ExcessiveResidual`	Any token’s residual balance exceeds its allowance.
`30`	`InternalInvariant`	An internal invariant failed. Report it.

Strategies

How controller strategies authorize swaps and settle balance changes.

Stellar Aggregator

The quote service that builds the route bytes.

Security model

Why the controller treats this contract as untrusted.

Addresses

Swap-aggregator registry addresses and verification steps.

Start here

Core concepts

Lending actions

Strategies and integrations

System behavior

Reference

Operations

Execute a strategy

Strategy payload

Fees

Claiming fees

Owner-only administration

Open reads

Error codes

Next

Strategies

Stellar Aggregator

Security model

Addresses

​Execute a strategy

​Strategy payload

​Fees

​Claiming fees

​Owner-only administration

​Open reads

​Error codes

​Next

Strategies

Stellar Aggregator

Security model

Addresses

Execute a strategy

Strategy payload

Fees

Claiming fees

Owner-only administration

Open reads

Error codes

Next