From 91371e16015c2cbd031ead9de007790003d92853 Mon Sep 17 00:00:00 2001 From: Manank Patni Date: Sun, 28 Jun 2026 02:23:47 +0530 Subject: [PATCH 1/2] Document routingAndLiquidityOptions across SDK and widget guides. Add preset reference, integration examples, and widget prop documentation for filler vs external routing flows. Co-authored-by: Cursor --- integration-examples.md | 2 +- integration-guides/sdk-integration-guide.md | 34 +++++++++++++++++++-- integration-guides/sdk-reference.md | 20 ++++++++++++ integration-guides/skills.md | 4 +-- integration-guides/swap-and-bridge.md | 30 ++++++++++++++++++ integration-guides/widget-integration.md | 14 +++++++++ 6 files changed, 99 insertions(+), 5 deletions(-) diff --git a/integration-examples.md b/integration-examples.md index b6182e9..2bce10f 100644 --- a/integration-examples.md +++ b/integration-examples.md @@ -43,7 +43,7 @@ Full-featured web UI demonstrating swap, bridge, Compact deposits, balance queri | `src/config/web3.ts` | Token/chain discovery from SDK graphs | | `src/config/api.ts` | `VITE_API_BASE_URL` helper | | `src/hooks/useAllocatorAPI.ts` | Health check, allocator address | -| `src/pages/BalancePage.tsx` | Full swap flow: quote → solve → status | +| `src/pages/BalancePage.tsx` | Full swap flow: routing preset picker, quote → solve → status | | `src/components/UserBalancesList.tsx` | `getDepositedBalances` | | `src/components/WalletWithdrawDialog.tsx` | Forced withdrawal flow | diff --git a/integration-guides/sdk-integration-guide.md b/integration-guides/sdk-integration-guide.md index 3baa886..7490ed9 100644 --- a/integration-guides/sdk-integration-guide.md +++ b/integration-guides/sdk-integration-guide.md @@ -55,8 +55,8 @@ Full chain and token tables: [Supported Chains & Tokens](../supported-chains-and ``` → getHealthCheck() → getTaskData({ taskType, intentData }) -→ getIntentQuote({ sponsorAddress, taskTypeString, intentData }) -→ solveIntent({ ...params, quoteResult, onExecutionStatus }) +→ getIntentQuote({ sponsorAddress, taskTypeString, intentData, routingAndLiquidityOptions? }) +→ solveIntent({ ...params, quoteResult, routingAndLiquidityOptions?, onExecutionStatus }) → getIntentStatus(userAddress, nonce) ``` @@ -135,6 +135,36 @@ if (nonce) { See [epoch-integration-demo](../integration-examples.md#epoch-integration-demo) for a runnable Node.js script. +### Routing & liquidity options (optional) + +Use `routingAndLiquidityOptions` when you want to control **how** the swap is filled — single-transaction filler liquidity vs multi-transaction external routing vs best-of-all. + +```typescript +import type { RoutingAndLiquidityOptions } from "@epoch-protocol/epoch-intents-sdk"; + +const routingAndLiquidityOptions: RoutingAndLiquidityOptions = { + preset: "filler-single-transaction", +}; + +const quoteResult = await sdk.getIntentQuote({ + sponsorAddress: account.address, + taskTypeString, + intentData, + routingAndLiquidityOptions, +}); + +await sdk.solveIntent({ + isNative: false, + sponsorAddress: account.address, + taskTypeString, + intentData, + quoteResult, + routingAndLiquidityOptions, // same as quote +}); +``` + +Presets: `any` (default), `filler-single-transaction`, `external-multi-transactions`, `custom` (with `solvers: [\`0x…\`]`). See [SDK Reference](./sdk-reference.md#getintentquoteparams). + *** ## React + wagmi Pattern (from compact-demo-epoch) diff --git a/integration-guides/sdk-reference.md b/integration-guides/sdk-reference.md index de091bb..32ed37d 100644 --- a/integration-guides/sdk-reference.md +++ b/integration-guides/sdk-reference.md @@ -59,9 +59,28 @@ getIntentQuote(params: { taskTypeString: string; intentData: unknown; isNative?: boolean; + routingAndLiquidityOptions?: RoutingAndLiquidityOptions; }): Promise ``` +**`RoutingAndLiquidityOptions`** (optional) — controls which solver liquidity paths SIO may quote. Mapped server-side to `constraint.preferredSolvers`. Use the **same** value in `getIntentQuote` and `solveIntent`. + +| Preset | UX | Behavior | +|--------|-----|----------| +| `{ preset: "any" }` | Best quote (default) | All registered solvers | +| `{ preset: "filler-single-transaction" }` | Single-transaction flow | Epoch filler treasury only | +| `{ preset: "external-multi-transactions" }` | Multi-transaction flow | External aggregators only | +| `{ preset: "custom"; solvers: [\`0x…\`] }` | Pin specific solver(s) | Explicit solver address(es) | + +```typescript +await sdk.getIntentQuote({ + sponsorAddress, + taskTypeString, + intentData, + routingAndLiquidityOptions: { preset: "filler-single-transaction" }, +}); +``` + **`IntentQuoteResult` fields:** | Field | Type | Description | @@ -88,6 +107,7 @@ solveIntent(params: { taskTypeString: string; intentData: unknown; quoteResult?: IntentQuoteResult; // optional; fetched internally if omitted + routingAndLiquidityOptions?: RoutingAndLiquidityOptions; onExecutionStatus?: (status: TransactionExecutionStatus) => void; collateralType?: CollateralType; // EVM | Miden — partner flows }): Promise diff --git a/integration-guides/skills.md b/integration-guides/skills.md index b2af0da..8d1077a 100644 --- a/integration-guides/skills.md +++ b/integration-guides/skills.md @@ -86,8 +86,8 @@ Full chain/token tables and API details: [reference.md](reference.md) ``` GET /health → getTaskData({ taskType, intentData }) - → getIntentQuote({ sponsorAddress, taskTypeString, intentData }) - → solveIntent({ ...params, quoteResult, onExecutionStatus }) + → getIntentQuote({ sponsorAddress, taskTypeString, intentData, routingAndLiquidityOptions? }) + → solveIntent({ ...params, quoteResult, routingAndLiquidityOptions?, onExecutionStatus }) → getIntentStatus(userAddress, nonce) ``` diff --git a/integration-guides/swap-and-bridge.md b/integration-guides/swap-and-bridge.md index 42f2347..b319e3c 100644 --- a/integration-guides/swap-and-bridge.md +++ b/integration-guides/swap-and-bridge.md @@ -99,6 +99,36 @@ Always require explicit user confirmation before calling `solveIntent`. *** +## Routing & liquidity options + +Optional `routingAndLiquidityOptions` lets integrators choose **how** the swap is filled: + +| Preset | When to use | +|--------|-------------| +| `any` | Default — best quote across all solvers | +| `filler-single-transaction` | Prefer Epoch filler liquidity (single wallet flow) | +| `external-multi-transactions` | External aggregators only (multi-step signing) | +| `custom` | Pin specific solver address(es) | + +Pass the **same** options to `getIntentQuote` and `solveIntent`: + +```typescript +const routingAndLiquidityOptions = { preset: "filler-single-transaction" as const }; + +const quote = await sdk.getIntentQuote({ + sponsorAddress, + taskTypeString, + intentData, + routingAndLiquidityOptions, +}); + +await sdk.solveIntent({ ...params, quoteResult: quote, routingAndLiquidityOptions }); +``` + +See [SDK Reference](./sdk-reference.md#getintentquoteparams). + +*** + ## Chain and token selection * Source chain: where the user's wallet is connected and input tokens exist. diff --git a/integration-guides/widget-integration.md b/integration-guides/widget-integration.md index 93d6b6e..294185b 100644 --- a/integration-guides/widget-integration.md +++ b/integration-guides/widget-integration.md @@ -240,6 +240,20 @@ api={{ baseUrl: 'https://allocator.example.com', positionsBaseUrl: 'https://posi By default the destination is **pinned**. Set `lockDestinationToken={false}` to let the user re-pick it. Scope the source side with `sourceChainIds`, `defaultSourceChainId`, `defaultSourceTokenAddress`, `sourceTokenFilter`. +**Routing & liquidity** — restrict which solver paths are quoted (pay, swap, and earn): + +```tsx + +``` + +Presets: `any`, `filler-single-transaction`, `external-multi-transactions`, `custom` (with `solvers: [\`0x…\`]`). Use the same value for quote and submit — the widget forwards it to the SDK automatically. + ### Swap `mode="swap"` — classic exchange UX; the user picks **both** sides. Provide an initial destination intent (`lockDestinationToken` is forced off internally so the user can always change what they receive): From 14be8f750adcc1dbbaebc0e1f44af9a4e05e559b Mon Sep 17 00:00:00 2001 From: Manank Patni Date: Mon, 29 Jun 2026 17:04:19 +0530 Subject: [PATCH 2/2] Clarify filler-single-transaction as one seamless user transaction. Document that this preset gives end-to-end execution in a single signature, with protocol interactions handled behind the scenes. Co-authored-by: Cursor --- integration-guides/sdk-integration-guide.md | 4 ++-- integration-guides/sdk-reference.md | 2 +- integration-guides/swap-and-bridge.md | 2 +- integration-guides/widget-integration.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/integration-guides/sdk-integration-guide.md b/integration-guides/sdk-integration-guide.md index 7490ed9..7e6a317 100644 --- a/integration-guides/sdk-integration-guide.md +++ b/integration-guides/sdk-integration-guide.md @@ -137,7 +137,7 @@ See [epoch-integration-demo](../integration-examples.md#epoch-integration-demo) ### Routing & liquidity options (optional) -Use `routingAndLiquidityOptions` when you want to control **how** the swap is filled — single-transaction filler liquidity vs multi-transaction external routing vs best-of-all. +Use `routingAndLiquidityOptions` when you want to control **how** the swap is filled — single-transaction filler liquidity (one user signature, seamless end-to-end execution including protocol interactions) vs multi-transaction external routing vs best-of-all. ```typescript import type { RoutingAndLiquidityOptions } from "@epoch-protocol/epoch-intents-sdk"; @@ -163,7 +163,7 @@ await sdk.solveIntent({ }); ``` -Presets: `any` (default), `filler-single-transaction`, `external-multi-transactions`, `custom` (with `solvers: [\`0x…\`]`). See [SDK Reference](./sdk-reference.md#getintentquoteparams). +Presets: `any` (default), `filler-single-transaction` (one transaction, seamless end-to-end execution for the user — protocol interactions handled by the filler), `external-multi-transactions`, `custom` (with `solvers: [\`0x…\`]`). See [SDK Reference](./sdk-reference.md#getintentquoteparams). *** diff --git a/integration-guides/sdk-reference.md b/integration-guides/sdk-reference.md index 32ed37d..4705132 100644 --- a/integration-guides/sdk-reference.md +++ b/integration-guides/sdk-reference.md @@ -68,7 +68,7 @@ getIntentQuote(params: { | Preset | UX | Behavior | |--------|-----|----------| | `{ preset: "any" }` | Best quote (default) | All registered solvers | -| `{ preset: "filler-single-transaction" }` | Single-transaction flow | Epoch filler treasury only | +| `{ preset: "filler-single-transaction" }` | One user transaction; seamless end-to-end execution | Epoch filler treasury only — protocol interactions bundled behind a single signature | | `{ preset: "external-multi-transactions" }` | Multi-transaction flow | External aggregators only | | `{ preset: "custom"; solvers: [\`0x…\`] }` | Pin specific solver(s) | Explicit solver address(es) | diff --git a/integration-guides/swap-and-bridge.md b/integration-guides/swap-and-bridge.md index b319e3c..ff850ca 100644 --- a/integration-guides/swap-and-bridge.md +++ b/integration-guides/swap-and-bridge.md @@ -106,7 +106,7 @@ Optional `routingAndLiquidityOptions` lets integrators choose **how** the swap i | Preset | When to use | |--------|-------------| | `any` | Default — best quote across all solvers | -| `filler-single-transaction` | Prefer Epoch filler liquidity (single wallet flow) | +| `filler-single-transaction` | Prefer Epoch filler liquidity — the user signs **one** transaction for seamless end-to-end execution (protocol interactions are handled behind the scenes) | | `external-multi-transactions` | External aggregators only (multi-step signing) | | `custom` | Pin specific solver address(es) | diff --git a/integration-guides/widget-integration.md b/integration-guides/widget-integration.md index 294185b..c5c5385 100644 --- a/integration-guides/widget-integration.md +++ b/integration-guides/widget-integration.md @@ -252,7 +252,7 @@ By default the destination is **pinned**. Set `lockDestinationToken={false}` to /> ``` -Presets: `any`, `filler-single-transaction`, `external-multi-transactions`, `custom` (with `solvers: [\`0x…\`]`). Use the same value for quote and submit — the widget forwards it to the SDK automatically. +Presets: `any`, `filler-single-transaction` (one user transaction with seamless end-to-end execution — protocol interactions handled behind the scenes), `external-multi-transactions`, `custom` (with `solvers: [\`0x…\`]`). Use the same value for quote and submit — the widget forwards it to the SDK automatically. ### Swap