Skip to main content

Fees and Surplus

A quote identifies both the user’s token amounts and the accounts that fund them. Fees, reserves, and Surplus have distinct accounting roles.

Receive fees​

Each receiving Reserve Asset has a configured fee. The engine first computes its gross receive amount, then separates the user’s net receive quote and a fee quote.

The receive quote is already net. Subtracting the fee again understates the user’s output. The scale change for the gross reserve action is recorded separately from how the token payout is divided.

Where trading income accrues​

Settlement transfers the receive fee to the receiving asset’s Rewards account. With Surplus settlement, the fee can be funded by both reserves and Surplus. The total fee is credited to Rewards in token units.

Rewards accrual identifies the income generated by trading. A pool’s payout mechanism and published terms determine LP distribution or reinvestment. Treasury has its own allocation and protocol-level purpose.

See Portfolio Exposure and Trading Income for the relationship between these balances and LP yield.

Surplus inventory​

Surplus is held outside an asset’s trading reserve. Eligible settlement can use it to keep the direct user payout while reducing how much of the trade passes through reserves.

The current implementation follows this sequence:

  1. Compute the direct reserve quote for the full order.
  2. Check every receive asset’s Surplus against a conservative top-up bound for both user output and fee.
  3. If any asset fails, use the direct reserve quote for the whole basket. This branch completes with the direct quote.
  4. If all qualify, quote again with 70% of each pay amount entering reserves, rounded up in token units.
  5. Allocate 15% of each pay amount to Rewards and the remainder to Treasury.
  6. Use receive-side Surplus to supply the difference between the direct and reduced-reserve outputs and fees.

The top-up precheck uses the 30% complement of the reserve share, with user and fee coverage rounded separately. The actual top-up is the difference produced by the second quote.

What the user sees​

The user receives the direct quote’s net token amounts. The resulting reserve balances and relative prices can differ from direct reserve-only settlement.

Available Surplus is part of current state. Execution recomputes the quote atomically; the available inventory is read at execution.

Accounting fields​

reserves, surplus, rewards, and treasury are token movement buckets. Their direction follows their pay-side or receive-side role. valueFlow is signed; valueChange records scale change.

Use Quote a Trade for conversion and minimum-receive guidance.