Surplus & Rebates

Surplus is the extra value your trade earns when Paragon Flow settles your intent above your own bound (minOut). We don’t keep that win for the house — we share it programmatically with the people who created it:

  • Trader (you) — instant cashback

  • LPs actually used by the winning route — “flow earnings”

  • stXPGN / veFlow lockers — protocol-aligned share

This page explains the math, distribution, accounting, and how to claim.

1) Definitions

  • Intent fields (recap): sellToken, buyToken, amountIn, minOut, deadline, receiver, prefs, nonce.

  • Amount Out (amountOut): what FlowSettlement actually delivers.

  • Surplus (S): S = max(amountOut − minOut, 0).

    • If amountOut < minOut the settlement must revert (or fallback to Router if you opted in), so S is never negative.

2) Split rules (default, testnet)

Let S be paid in the buy token of the trade.

  • Trader rebate (Rᴛ): 60% · S

  • LP rebate (Rˡᵖ): 30% · S

  • Lockers (Rˡᵒᶜᵏ): 10% · S → stXPGN / veFlow vault

  • (Optional) Protocol skim before split: p% · S (e.g., 5%) for the treasury, then apply the 60/30/10 to the remainder. DAO-configurable. Testnet starts at 0%.

All values are emitted in the ShieldSettled event for full auditability.

3) Example

You sign an intent: swap 1,000 USDT → BNB with minOut = 3.0000 BNB.

  • FlowSettlement executes a route and gets amountOut = 3.0120 BNB.

  • Surplus S = 0.0120 BNB.

Split (no protocol skim):

  • Trader: 0.60 × 0.0120 = 0.0072 BNB

  • LPs touched: 0.30 × 0.0120 = 0.0036 BNB

  • Lockers: 0.10 × 0.0120 = 0.0012 BNB

You see “You saved 0.40% — 0.0072 BNB credited.” LP dashboards show their pro-rata share of 0.0036 BNB under Flow Earnings.

4) LP rebate accounting (multi-hop routes)

LP rebates are allocated only to pools used in the winning route and only to LPs who were providing liquidity in that block.

4.1 Hop weights

For a route with n hops, we compute a weight for each hop i:

notional_i = amount_in_on_hop_i  (converted to buyToken units via hop mid-price)
w_i        = notional_i / Σ notional_j
rebate_to_hop_i = Rˡᵖ * w_i

Using buyToken units avoids mixing different tokens/decimals across hops.

4.2 Within a hop (per pool)

At block B (the settlement block), we take a supply snapshot from the pool’s LP token:

user_share_on_pool = userLPBalance_at_B / totalLPSupply_at_B
user_flow_earnings_from_pool = rebate_to_hop_i * user_share_on_pool

  • No snapshots are stored per account. We store a checkpoint per pool per settlement with (block, rebate_to_hop_i) and read historical LP balances via standard pool events (gas-efficient rolling windows on mainnet; simple on testnet).

  • LPs who joined after the settlement don’t get past rebates.

  • LPs who left before the settlement also don’t get that rebate.

On testnet we use a straightforward checkpoint list; on mainnet we’ll roll into a ring buffer to keep gas bounded.

5) Claiming

5.1 Trader rebates

  • Instant credit to TraderRebateVault under your address.

  • Claim modes:

    • Cashback: claim(address to) (default UI shows a Claim button).

    • Auto-stake: set prefs.cashbackMode=1 to auto-stake your rebate into stXPGN (gas-efficient).

  • Gasless option: meta-transactions with a relayer (testnet behind a toggle).

5.2 LP flow earnings

  • Accrue in LPRebateVault per pool you provide liquidity to.

  • Claim per pool or claimAll across pools:

    • claim(pool, to) or claimAll(to)

  • UI shows Flow Earnings separate from swap fees/normal rewards.

5.3 Lockers

  • LockerVault receives its cut each settlement and accounts it to stXPGN / veFlow according to the active emission schedule.

  • If you’re locked, you’ll see Execution Yield alongside other rewards.

6) Events & transparency

Settlement emits:

event ShieldSettled(
  address indexed user,
  bytes32 indexed intentHash,
  uint256 amountOut,
  uint256 surplus,
  uint256 traderRebate,
  uint256 lpRebate,
  uint256 lockerCut,
  address buyToken,
  uint256 blockNumber
);

Vaults emit standard Claim events, and LP checkpoints are queryable by index. Frontend surfaces a “Proof-of-Best-Execution” modal with:

  • Route & venues used

  • Your bound (minOut) vs achieved (amountOut)

  • Surplus split breakdown

  • Tx hash & block

7) Edge cases & guards

  • Zero surplus (amountOut == minOut): no rebates (nothing to split).

  • Below bound: settlement reverts (or Router fallback if you opted in).

  • Rounding dust: any tiny remainder after splits accumulates in the vault and is distributed in the next claim cycle.

  • Abuse protection:

    • Fake bounds: solvers are scored on excess over minOut net of gas; we also apply per-venue sanity checks and slashing bonds for executors.

    • Venue risk: external venues are allow-listed with per-venue caps on testnet; invalid quotes → solver slashed, settlement rejected.

    • Reorgs: settlement checks pool reserves immediately before routing; if state changed materially, re-simulate or revert.

8) Parameters (testnet defaults)

  • Surplus split: 60 / 30 / 10

  • Protocol skim: 0% (DAO-governed)

  • Max hops per route: 4

  • External venues: Paragon pools only (Phase 0)

  • Vault addresses (replace once deployed):

    • TraderRebateVault: TRADER_REBATE_VAULT

    • LPRebateVault: LP_REBATE_VAULT

    • LockerVault: LOCKER_VAULT

9) Developer quick reference

Get user trader rebate (read):

function pending(address user, address token) external view returns (uint256);

Claim trader rebate (write):

function claim(address token, address to) external;

Get LP pending flow earnings:

function pending(address pool, address user, address token) external view returns (uint256);

Claim LP flow earnings:

function claim(address pool, address token, address to) external;

Checkpoint structure (per pool, per settlement):

struct Checkpoint {
  uint32  blockNumber;
  address buyToken;
  uint224 amount; // rebate_to_hop in buyToken units
}

10) FAQ

Is surplus guaranteed? No. It depends on market conditions and solver quality. Your minOut guarantees you never settle worse than your bound.

What token are rebates paid in? In the buy token of the trade (the one you receive).

Do LP rebates replace trading fees? No. They’re additional to pool swap fees and any farm rewards.

What if a route touches the same pool twice? We add both notional legs into that pool’s weight for the batch.

Can I opt out? Yes. Swap using the classic Router, or set prefs.fallback=true and toggle Shield off.

What’s next

  • Cross-DEX rebates: when external venues are enabled, their in-Paragon LPs still get flow earnings; external LPs do not.

  • Dynamic split voting: veFlow can direct a portion of the split weights toward specific pool categories.

  • Insurance mode: a tiny slice of surplus can fund a slippage-band protection pool (opt-in).

PreviousIntents & BatchingNextParagon Swap

Last updated