Intents & Batching

Paragon Flow upgrades swapping from “send a transaction and hope” to sign an intent, batch with others, settle with best execution, and share the surplus. It’s the engine behind Paragon Shield’s.

TL;DR

  • You sign an EIP-712 Intent (not a transaction).

  • A Batcher groups intents for a short window and asks Solvers to propose a settlement.

  • The best proposal is executed on-chain through FlowSettlement, which:

    • enforces your bounds (minOut, deadline, receiver),

    • computes surplus = amountOut − minOut,

    • splits surplus to Trader / LPs used / stXPGN lockers,

    • emits auditable events (Proof-of-Best-Execution).

If no solver can beat your bounds, the batch reverts for you (or, if you opted in, falls back to a normal router swap).

Why intents?

  • MEV resistance: batched clearing + private relay kills most sandwich vectors.

  • Better pricing: solvers can route multi-hop across multiple venues and cross-match flows.

  • Programmable refunds: surplus is shared to the right parties automatically.

Key actors

  • Trader: signs an Intent.

  • Batcher/Relay: groups intents, broadcasts to whitelisted solvers.

  • Solver(s): search for best settlement across Paragon pools (+ external DEXes later).

  • FlowSettlement: on-chain verifier/executor; distributes surplus to vaults.

The Intent (EIP-712)

// EIP-712 domain
const domain = {
  name: "ParagonFlow",
  version: "1",
  chainId, // BNB Testnet during beta
  verifyingContract: FLOW_SETTLEMENT_ADDRESS,
} as const;

// EIP-712 types
const types = {
  Intent: [
    { name: "sellToken", type: "address" },
    { name: "buyToken",  type: "address" },
    { name: "amountIn",  type: "uint256" },
    { name: "minOut",    type: "uint256" },
    { name: "deadline",  type: "uint256" },
    { name: "receiver",  type: "address" },
    { name: "prefs",     type: "uint256" }, // bitfield (privacy, fallback, slippage mode)
    { name: "nonce",     type: "uint256" },
  ],
} as const;

// Example value
const value = {
  sellToken, buyToken,
  amountIn,          // exact-in
  minOut,            // bound after fees
  deadline,          // block timestamp bound
  receiver: user,
  prefs,             // see "Preferences bitfield" below
  nonce,             // wallet-defined
};

Preferences bitfield (prefs)

  • 0..1 privacy: 0=Lite, 1=Private, 2=Stealth

  • 2 fallback: 0=No fallback (revert), 1=Fallback to router if solver fails

  • 3 cashback mode: 0=claim to wallet, 1=auto-stake to stXPGN

  • 4..7 reserved

You can cancel any outstanding intent by incrementing your nonce via FlowSettlement.cancel(nonce) or signing a replacement with a higher nonce.

Batching windows

  • Window: ~1 block on BNB (testnet setting), adaptive later.

  • Priority: FIFO within the same gas price band.

  • Max batch size: capped to keep gas predictable (configurable).

  • Liveness: if no valid solver submission before window end → optional fallback or revert.

Auction & scoring

Solvers submit a Settlement:

{ routeData, expectedOut, gasEstimate, lpTouchSet, proof }

Score = (expectedOut − minOut) − gasCostEquivalent − penalties

  • expectedOut − minOut → higher is better (more surplus).

  • gasCostEquivalent → convert gas to output token via oracle.

  • penalties → for unhealthy routes (too many hops, stale pools, unsafe external venues).

  • Tie-breakers: fewer hops → earlier timestamp → lower variance in sim.

Batcher picks the top-score, builds a bundle, and sends it to FlowSettlement.execute.

On-chain settlement (Solidity surface)

interface IFlowSettlement {
  struct Intent {
    address sellToken;
    address buyToken;
    uint256 amountIn;
    uint256 minOut;
    uint256 deadline;
    address receiver;
    uint256 prefs;
    uint256 nonce;
  }

  function execute(
    Intent calldata intent,
    bytes calldata signature,
    bytes calldata routeData // ABI-encoded hops & venues
  ) external returns (uint256 amountOut);

  function cancel(uint256 newNonce) external;

  event ShieldSubmitted(address indexed user, bytes32 intentHash);
  event ShieldSettled(
    address indexed user,
    bytes32 indexed intentHash,
    uint256 amountOut,
    uint256 surplus,        // amountOut - minOut (>=0)
    uint256 traderRebate,   // default 60%
    uint256 lpRebate,       // default 30%
    uint256 lockerCut       // default 10% -> stXPGN
  );
}

Settlement checks

  • signature & domain match

  • block.timestamp ≤ deadline

  • user allowance/transferFrom succeeds for amountIn

  • Router performs the routeData swaps atomically

  • amountOut ≥ minOut else revert (or fallback if allowed)

Surplus & payouts

  • Surplus: surplus = amountOut − minOut (0 if negative).

  • Splits (default):

    • 60% → Trader (instant claim or auto-stake to stXPGN)

    • 30% → LPRebateVault (credited to pairs actually touched by the route)

    • 10% → LockerVault (stXPGN / veFlow lockers)

  • Protocol can take a small cut (0–5%) of surplus before splits (DAO-governed).

LPRebateVault accounting

  • We snapshot pair, blockNumber, usedLiquidity for the settlement.

  • LPs claim proportionally to the liquidity they had in that block.

External venues (phased)

  • Phase 0 (testnet): Paragon pools only.

  • Phase 1: add whitelisted Pancake/Thena routes with per-venue caps and slashing bonds for executors.

  • Phase 2: open allow-list, higher caps, cross-DEX batch netting.

Fallbacks & failures

  • Revert (default) if no solver produces amountOut ≥ minOut.

  • Fallback to Router if the prefs bit is set. UI shows: “Shield unavailable, executed via Router.”

  • Partial batch failure: single intent revert doesn’t affect others; we isolate by executing intents independently (no shared state assumptions).

Security model

  • Permissions: FlowSettlement is upgrade-gated by timelock + multisig.

  • Solver bonds: executors post bonds and can be slashed (mis-pricing, invalid routing, griefing).

  • Replay protection: per-user nonces + domain separation.

  • Oracle usage: only for gas costing and sanity checks; user bound (minOut) is the real guard.

  • Emergency: Shield can be paused without affecting classic swaps.

Relay API (testnet draft)

Submit intent

POST {RELAY_URL}/v1/intent
{
  "intent": { ...EIP712 value... },
  "signature": "0x...",
  "hint": { "privacy": "lite|private|stealth", "fallback": true|false }
}
→ { "intentHash": "0x...", "batchEta": 1730000000 }

Status

GET {RELAY_URL}/v1/intent/{intentHash}
→ { "state": "pending|settled|failed|reverted", "txHash": "0x...", "savingsPct": "0.42" }

WebSocket feed wss://.../v1/stream → ShieldSubmitted / ShieldSettled notifications.

Frontend integration (quick guide)

  1. Prepare intent & sign

import { signTypedData } from "viem/actions";
const signature = await signTypedData(wallet, { domain, types, primaryType: "Intent", message: value });

  1. POST to relay (or call execute directly if you run a solver).

  2. Show live status (pending → settled).

    • If settled, extract surplus + rebate amounts from event or status and surface “You saved X%”.

  3. Claims

    • Trader: call TraderRebateVault.claim(user) if not auto-staked.

    • LPs: show accrued Flow earnings on the pool page (per-block snapshots).

Testnet parameters (current)

  • Chain: BNB Testnet

  • Batch window: ~1 block (adaptive 1–2 blocks if congestion)

  • Min trade size: none (UI may nudge > $5)

  • Max hops: 4 (Paragon pools only)

  • Surplus split: 60/30/10 (TBD via DAO for mainnet)

  • Contracts:

    • FlowSettlement: FLOW_SETTLEMENT_ADDRESS

    • TraderRebateVault: TRADER_REBATE_VAULT

    • LPRebateVault: LP_REBATE_VAULT

    • LockerVault: LOCKER_VAULT

Developer FAQs

Q: Can I cancel/replace an intent? Yes. Call cancel(newNonce) or sign a newer intent with a higher nonce.

Q: Does batching increase gas? Settlement for a batch is similar to one swap with comparable hops. Slightly higher overhead is typically offset by better price (surplus).

Q: How are LP rebates mapped to pairs? Solvers must provide lpTouchSet per hop; settlement verifies via router events and credits the vault.

Q: Can I force a public (non-Shield) swap? Yes—use classic Router or set prefs.fallback=true and toggle Shield off in the UI.

Roadmap hooks

  • Limit/RFQ intents

  • Time-weighted auctions for large orders

  • Cross-DEX netting (match internal flows to reduce market impact)

  • veFlow voting to steer surplus weights and utilization emissions

PreviousParagon Shield (MEV & Privacy)NextSurplus & Rebates

Last updated