@switch-win/sdk 1.2.8 → 1.3.0

package/LIMIT-ORDERS.md

@@ -1,17 +1,21 @@
 # Switch Limit Orders — Integration Guide
 
-> **Gasless EIP-712 signed limit orders on PulseChain and Robinhood Chain**
-
-**Limit Order API:** `https://quote.switch.win`
-
-| API network | Chain ID | Native currency | Current limit-order contract | Native flow contract |
-|---|---:|---|---|---|
-| `pulsechain` | 369 | PLS | `0x2afBf0aB8d958a0227742F7a8BdA00c96372E4D7` | `0x0362177FF2ad25a33a879c881a5055575C63a4cE` |
-| `robinhood` | 4663 | ETH | `0x1E05115387f314398bbb1A808B25308E71150396` | `0x8170a3B0e2FD2e4333E0Ca9c9414B2D3dd6aF689` |
-
-Pass `network: "pulsechain"` or `network: "robinhood"` to every SDK API
-helper. Call `fetchLimitOrderConfig({ network })` at startup and treat its
-addresses and EIP-712 domain as the live source of truth.
+> **Gasless EIP-712 signed limit orders on PulseChain and Robinhood Chain**
+
+This guide describes ordinary limit orders. The dedicated GaslessSwitch swap
+option has a separate domain, contract, fee, payout cap and approval target;
+use [GASLESS.md](GASLESS.md) and the dedicated SDK helpers for that flow.
+
+**Limit Order API:** `https://quote.switch.win`
+
+| API network | Chain ID | Native currency | Current limit-order contract | Native flow contract |
+|---|---:|---|---|---|
+| `pulsechain` | 369 | PLS | `0x2afBf0aB8d958a0227742F7a8BdA00c96372E4D7` | `0x0362177FF2ad25a33a879c881a5055575C63a4cE` |
+| `robinhood` | 4663 | ETH | `0x1E05115387f314398bbb1A808B25308E71150396` | `0x8170a3B0e2FD2e4333E0Ca9c9414B2D3dd6aF689` |
+
+Pass `network: "pulsechain"` or `network: "robinhood"` to every SDK API
+helper. Call `fetchLimitOrderConfig({ network })` at startup and treat its
+addresses and EIP-712 domain as the live source of truth.
 
 ---
 
@@ -21,7 +25,7 @@ addresses and EIP-712 domain as the live source of truth.
 1. [Overview](#overview)
 2. [How It Works](#how-it-works)
 3. [Creating a Limit Order](#creating-a-limit-order)
-4. [Native Currency Limit Orders (SwitchPLSFlow)](#native-currency-limit-orders-switchplsflow)
+4. [Native Currency Limit Orders (SwitchPLSFlow)](#native-currency-limit-orders-switchplsflow)
 5. [Choosing `feeOnOutput`](#choosing-feeonoutput)
 6. [Querying Limit Orders](#querying-limit-orders)
 7. [Cancelling a Limit Order](#cancelling-a-limit-order)
@@ -60,37 +64,37 @@ Switch Limit Orders let users place **gasless, signed orders** that are filled a
 - **Nonce-based replay protection** — each order has a unique nonce per maker
 - **Optional expiry** — set a deadline or make the order valid forever
 - **Custom recipient** — output tokens can be sent to a different address
-- **Native unwrap** — WPLS can be unwrapped to PLS and Robinhood WETH can be
-  unwrapped to ETH by setting `unwrapOutput`
-
-> **⚠️ Important:** The `SWITCH_LIMIT_ORDER` address is the **current** default. The contract may be redeployed (e.g. when the router is upgraded). Each order returned by the API includes a `limitOrderContract` field — **always use the contract address from the order for on-chain interactions (approvals, cancellations), not a hardcoded constant.** This ensures your integration works seamlessly across contract versions without code changes.
-
-### Network-aware setup
-
-```ts
-import {
-  fetchLimitOrderConfig,
-  getLimitOrderApprovalTarget,
-  getNetworkEIP712SigningParams,
-  submitLimitOrder,
-} from "@switch-win/sdk/limit-orders";
-
-// `signer` and a completed `order` are assumed below.
-const network = "robinhood" as const;
-const live = await fetchLimitOrderConfig({ network });
-const { domain, types } = getNetworkEIP712SigningParams(
-  network,
-  live.limitOrderContract,
-);
-const approvalTarget = getLimitOrderApprovalTarget(network, order.feeOnOutput, {
-  limitOrderContract: live.limitOrderContract,
-});
-const signature = await signer.signTypedData(domain, types, order);
-await submitLimitOrder(
-  { ...order, signature, limitOrderContract: live.limitOrderContract },
-  { network },
-);
-```
+- **Native unwrap** — WPLS can be unwrapped to PLS and Robinhood WETH can be
+  unwrapped to ETH by setting `unwrapOutput`
+
+> **⚠️ Important:** The `SWITCH_LIMIT_ORDER` address is the **current** default. The contract may be redeployed (e.g. when the router is upgraded). Each order returned by the API includes a `limitOrderContract` field — **always use the contract address from the order for on-chain interactions (approvals, cancellations), not a hardcoded constant.** This ensures your integration works seamlessly across contract versions without code changes.
+
+### Network-aware setup
+
+```ts
+import {
+  fetchLimitOrderConfig,
+  getLimitOrderApprovalTarget,
+  getNetworkEIP712SigningParams,
+  submitLimitOrder,
+} from "@switch-win/sdk/limit-orders";
+
+// `signer` and a completed `order` are assumed below.
+const network = "robinhood" as const;
+const live = await fetchLimitOrderConfig({ network });
+const { domain, types } = getNetworkEIP712SigningParams(
+  network,
+  live.limitOrderContract,
+);
+const approvalTarget = getLimitOrderApprovalTarget(network, order.feeOnOutput, {
+  limitOrderContract: live.limitOrderContract,
+});
+const signature = await signer.signTypedData(domain, types, order);
+await submitLimitOrder(
+  { ...order, signature, limitOrderContract: live.limitOrderContract },
+  { network },
+);
+```
 
 ---
 
@@ -113,9 +117,9 @@ await submitLimitOrder(
 │       Tokens are pulled from the maker's wallet and swapped.            │
 │       Output is sent to the maker (or custom recipient).                │
 │                                                                         │
-│  5. CANCEL (optional)                                                   │
-│       invalidateNonce(nonce) on-chain — prevents execution              │
-│       The backend indexer observes the cancellation event.              │
+│  5. CANCEL (optional)                                                   │
+│       invalidateNonce(nonce) on-chain — prevents execution              │
+│       The backend indexer observes the cancellation event.              │
 └─────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -131,10 +135,12 @@ await submitLimitOrder(
 > Your integration must:
 > 1. Call `submitLimitOrder()` **immediately** after the user signs.
 > 2. **Await** the response and confirm `success: true` before showing "order created".
-> 3. **Retry** on transient failures — the backend is idempotent on `maker + nonce`.
+> 3. On a transient failure, look up that exact maker + nonce and verify its
+>    contract and signed fields. Duplicates return an error, not idempotent
+>    success. Retry only the original signed payload; never generate a new nonce.
 > 4. Do **not** navigate away or close the signing flow until the backend confirms.
 >
-> *Native PLS/ETH flow orders are the exception — they are recorded on-chain*
+> *Native PLS/ETH flow orders are the exception — they are recorded on-chain*
 > *first, so the backend discovers them via event indexing even if the POST*
 > *never arrives.*
 
@@ -146,28 +152,28 @@ The full lifecycle in code (ethers.js v6):
 
 ```ts
 import { ethers } from "ethers";
-import {
-  buildLimitOrder,
-  fetchLimitOrderConfig,
-  getLimitOrderApprovalTarget,
-  getNetworkEIP712SigningParams,
-  submitLimitOrder,
-} from "@switch-win/sdk/limit-orders";
+import {
+  buildLimitOrder,
+  fetchLimitOrderConfig,
+  getLimitOrderApprovalTarget,
+  getNetworkEIP712SigningParams,
+  submitLimitOrder,
+} from "@switch-win/sdk/limit-orders";
 import { ERC20_ABI } from "@switch-win/sdk/constants";
 
-const network = "robinhood" as const;
-const provider = new ethers.JsonRpcProvider("https://rpc.mainnet.chain.robinhood.com");
-const signer = new ethers.Wallet(PRIVATE_KEY, provider);
-const maker = await signer.getAddress();
-const live = await fetchLimitOrderConfig({ network });
+const network = "robinhood" as const;
+const provider = new ethers.JsonRpcProvider("https://rpc.mainnet.chain.robinhood.com");
+const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+const maker = await signer.getAddress();
+const live = await fetchLimitOrderConfig({ network });
 
 // ── Step 1: Build the order ──
 const order = buildLimitOrder({
   maker,
-  tokenIn: "0x0Bd7D308f8E1639FAb988Df18A8011f41EAcAD73",   // WETH
-  tokenOut: "0x5fc5360D0400a0Fd4F2aF552aDD042D716F1d168",  // USDG
-  amountIn: ethers.parseUnits("0.01", 18).toString(),
-  minAmountOut: ethers.parseUnits("30", 18).toString(),
+  tokenIn: "0x0Bd7D308f8E1639FAb988Df18A8011f41EAcAD73",   // WETH
+  tokenOut: "0x5fc5360D0400a0Fd4F2aF552aDD042D716F1d168",  // USDG
+  amountIn: ethers.parseUnits("0.01", 18).toString(),
+  minAmountOut: ethers.parseUnits("30", 18).toString(),
   deadline: Math.floor(Date.now() / 1000) + 86400,          // 24h expiry
   // nonce: auto-generated from Date.now()
   // feeOnOutput: false (default — fee taken from input)
@@ -176,11 +182,11 @@ const order = buildLimitOrder({
 });
 
 // ── Step 2: Approve the correct contract (one-time per token + fee mode) ──
-//   feeOnOutput=false (default) → approve this network's LO contract
-//   feeOnOutput=true            → approve this network's SwitchRouter
-const approvalTarget = getLimitOrderApprovalTarget(network, order.feeOnOutput, {
-  limitOrderContract: live.limitOrderContract,
-});
+//   feeOnOutput=false (default) → approve this network's LO contract
+//   feeOnOutput=true            → approve this network's SwitchRouter
+const approvalTarget = getLimitOrderApprovalTarget(network, order.feeOnOutput, {
+  limitOrderContract: live.limitOrderContract,
+});
 const token = new ethers.Contract(order.tokenIn, ERC20_ABI, signer);
 const allowance: bigint = await token.allowance(maker, approvalTarget);
 
@@ -190,23 +196,23 @@ if (allowance < BigInt(order.amountIn)) {
 }
 
 // ── Step 3: Sign via EIP-712 (gasless!) ──
-const { domain, types } = getNetworkEIP712SigningParams(
-  network,
-  live.limitOrderContract,
-);
-const signature = await signer.signTypedData(domain, types, order);
+const { domain, types } = getNetworkEIP712SigningParams(
+  network,
+  live.limitOrderContract,
+);
+const signature = await signer.signTypedData(domain, types, order);
 
 // ── Step 4: Submit to the Switch backend ──
 // ⚠️ CRITICAL: The signature is off-chain only — if this POST fails,
 // the order is lost. Submit IMMEDIATELY after signing, await the
 // response, and retry on network failure.
-const result = await submitLimitOrder(
-  { ...order, signature, limitOrderContract: live.limitOrderContract },
-  { network },
-);
+const result = await submitLimitOrder(
+  { ...order, signature, limitOrderContract: live.limitOrderContract },
+  { network },
+);
 
 if ("error" in result) {
-  // Retry logic recommended here — the backend is idempotent on maker+nonce
+  // Look up the exact order before retrying the identical signed payload.
   console.error("Failed:", result.error);
 } else {
   console.log("Order created:", result.order.id);
@@ -227,62 +233,68 @@ if ("error" in result) {
 | `nonce` | `number` | No | `Date.now()` | Unique per maker. Auto-generated if omitted |
 | `feeOnOutput` | `boolean` | No | `false` | Fee mode — see [Choosing `feeOnOutput`](#choosing-feeonoutput) below |
 | `recipient` | `string` | No | `maker` | Address to receive output tokens |
-| `unwrapOutput` | `boolean` | No | `false` | Unwrap wrapped native output to PLS/ETH on the selected network |
+| `unwrapOutput` | `boolean` | No | `false` | Unwrap wrapped native output to PLS/ETH on the selected network |
 
 ---
 
-## Native Currency Limit Orders (SwitchPLSFlow)
-
-When selling native **PLS** on PulseChain or native **ETH** on Robinhood
-(rather than WPLS/WETH), use the selected network's native-flow contract
-instead of the standard EIP-712 signing flow. The deployed contract retains
-the legacy `SwitchPLSFlow` name on both networks, but its behavior is
-native-currency neutral:
+## Native Currency Limit Orders (SwitchPLSFlow)
 
-- **No approval needed** — users send the native currency directly to the contract
+When selling native **PLS** on PulseChain or native **ETH** on Robinhood
+(rather than WPLS/WETH), use the selected network's native-flow contract
+instead of the standard EIP-712 signing flow. The deployed contract retains
+the legacy `SwitchPLSFlow` name on both networks, but its behavior is
+native-currency neutral:
+
+- **No approval needed** — users send the native currency directly to the contract
 - **No EIP-712 signature** — the contract creates the order on-chain immediately
 - **Single transaction** — wrap + approve + place order all in one tx
-- **Fully indexed** — the backend discovers orders via `PLSOrderCreated` events
-- **Drain-mode capable** — maintainers can disable new native deposits without
-  blocking fills or cancellations of existing orders
+- **Fully indexed** — the backend discovers orders via `PLSOrderCreated` events
+- **Drain-mode capable** — maintainers can disable new native deposits without
+  blocking fills or cancellations of existing orders
+
+> **Current ABI:** native-flow deployments use the seven-argument
+> `createOrder(tokenOut, minAmountOut, deadline, feeOnOutput, unwrapOutput,
+> partnerAddress, recipient)` signature. The `recipient` argument must be
+> present in calldata; pass the zero address to default it to `msg.sender`.
+> The older six-argument selector is not compatible with current deployments.
 
-### Native-flow contract address
+### Native-flow contract address
 
 ```ts
-import { getNativeFlowAddress, PLS_FLOW_ABI } from "@switch-win/sdk";
-
-const robinhoodNativeFlow = getNativeFlowAddress("robinhood");
-// "0x8170a3B0e2FD2e4333E0Ca9c9414B2D3dd6aF689"
+import { getNativeFlowAddress, PLS_FLOW_ABI } from "@switch-win/sdk";
+
+const robinhoodNativeFlow = getNativeFlowAddress("robinhood");
+// "0x8170a3B0e2FD2e4333E0Ca9c9414B2D3dd6aF689"
 ```
 
-### Creating a native ETH limit order on Robinhood
+### Creating a native ETH limit order on Robinhood
 
 ```ts
 import { ethers } from "ethers";
-import { getNativeFlowAddress, isNativeCurrency } from "@switch-win/sdk/limit-orders";
-import { PLS_FLOW_ABI } from "@switch-win/sdk/constants";
-
-const network = "robinhood" as const;
-const provider = new ethers.JsonRpcProvider("https://rpc.mainnet.chain.robinhood.com");
-const signer = new ethers.Wallet(PRIVATE_KEY, provider);
-
-const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
-if (isNativeCurrency(NATIVE)) {
-  const nativeFlow = new ethers.Contract(
-    getNativeFlowAddress(network),
-    PLS_FLOW_ABI,
-    signer,
-  );
+import { getNativeFlowAddress, isNativeCurrency } from "@switch-win/sdk/limit-orders";
+import { PLS_FLOW_ABI } from "@switch-win/sdk/constants";
+
+const network = "robinhood" as const;
+const provider = new ethers.JsonRpcProvider("https://rpc.mainnet.chain.robinhood.com");
+const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+
+const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+if (isNativeCurrency(NATIVE)) {
+  const nativeFlow = new ethers.Contract(
+    getNativeFlowAddress(network),
+    PLS_FLOW_ABI,
+    signer,
+  );
   
-  const tokenOut = "0x5fc5360D0400a0Fd4F2aF552aDD042D716F1d168"; // USDG
-  const amountIn = ethers.parseEther("0.01");
-  const minAmountOut = ethers.parseUnits("30", 18);
+  const tokenOut = "0x5fc5360D0400a0Fd4F2aF552aDD042D716F1d168"; // USDG
+  const amountIn = ethers.parseEther("0.01");
+  const minAmountOut = ethers.parseUnits("30", 18);
   const deadline = Math.floor(Date.now() / 1000) + 86400;         // 24h expiry
   const feeOnOutput = false;
   const unwrapOutput = false;
 
   // Single transaction — no approval, no signing
-  const tx = await nativeFlow.createOrder(
+  const tx = await nativeFlow.createOrder(
     tokenOut,
     minAmountOut,
     deadline,
@@ -294,65 +306,65 @@ if (isNativeCurrency(NATIVE)) {
   );
   
   const receipt = await tx.wait();
-  console.log("Native ETH limit order created in tx:", receipt.hash);
+  console.log("Native ETH limit order created in tx:", receipt.hash);
   
   // The backend will automatically detect this order via PLSOrderCreated event.
   // No POST to /limit-orders required (though it's harmless if you do).
 }
 ```
 
-### Native flow vs EIP-712 orders
+### Native flow vs EIP-712 orders
 
-| Aspect | Native flow (PLS/ETH) | EIP-712 (ERC-20) |
+| Aspect | Native flow (PLS/ETH) | EIP-712 (ERC-20) |
 |---|---|---|
-| **Input token** | Native currency | Any ERC-20 (including WPLS/WETH) |
+| **Input token** | Native currency | Any ERC-20 (including WPLS/WETH) |
 | **User experience** | Single transaction | Approve + Sign + Submit |
 | **Gas cost** | User pays gas | Gasless signing (user pays on fill) |
 | **Order discovery** | On-chain event | Requires successful POST |
-| **Maker address** | Native-flow contract | User's wallet |
+| **Maker address** | Native-flow contract | User's wallet |
 | **Recipient** | User's wallet (or custom) | User's wallet (or custom) |
 
 ### Important: Order Discovery
 
-For native-flow orders, the `maker` field in the order record is the
-**native-flow contract address**, not the user's address. The actual user is
-stored in the `recipient` field.
+For native-flow orders, the `maker` field in the order record is the
+**native-flow contract address**, not the user's address. The actual user is
+stored in the `recipient` field.
 
 When querying orders for a user, use the `owner` parameter instead of `maker`:
 
 ```ts
-// ✅ Correct — finds both EIP-712 and native-flow orders
-const { orders } = await fetchLimitOrders({
-  network: "robinhood",
+// ✅ Correct — finds both EIP-712 and native-flow orders
+const { orders } = await fetchLimitOrders({
+  network: "robinhood",
   owner: "0xUserAddress",  // matches maker OR recipient
   status: "ACTIVE",
 });
 
-// ❌ Won't find native-flow orders
-const { orders } = await fetchLimitOrders({
-  network: "robinhood",
+// ❌ Won't find native-flow orders
+const { orders } = await fetchLimitOrders({
+  network: "robinhood",
   maker: "0xUserAddress",  // only matches maker field
   status: "ACTIVE",
 });
 ```
 
-### Cancelling a native-flow order
+### Cancelling a native-flow order
 
-Native-flow orders can be cancelled by the original creator (`recipient`):
+Native-flow orders can be cancelled by the original creator (`recipient`):
 
 ```ts
-const nativeFlow = new ethers.Contract(
-  getNativeFlowAddress("robinhood"),
-  PLS_FLOW_ABI,
-  signer,
-);
+const nativeFlow = new ethers.Contract(
+  getNativeFlowAddress("robinhood"),
+  PLS_FLOW_ABI,
+  signer,
+);
 
 // Cancel on-chain (only the original creator can call this)
-const tx = await nativeFlow.cancelOrder(nonceToCancel);
+const tx = await nativeFlow.cancelOrder(nonceToCancel);
 await tx.wait();
 
 // The backend will detect the NonceCancelled event and update the order status.
-// No REST mutation is required.
+// No REST mutation is required.
 ```
 
 ---
@@ -383,23 +395,23 @@ When `feeOnOutput=false`, the LO contract pulls all tokens to itself first — o
 
 When `feeOnOutput=true`, the Router pulls tokens directly from the maker. If an operator also tries to take excess input via the LO contract, that requires a second approval the maker typically hasn't granted — the transaction would simply revert. The operator loses gas; the maker loses nothing and the order remains active for another operator. In practice, operators use output-side profit for `feeOnOutput=true` orders.
 
-> **Impact on fillability:** `feeOnOutput=true` orders are still fully fillable, but operators have less flexibility. In tight-margin or low-liquidity situations, this *could* reduce the likelihood of a fill since operators cannot optimize their profit-taking strategy on both sides.
-
-### Protected settlement
-
-The current PulseChain and Robinhood deployments charge a 30 bps (0.30%)
-limit-order fee. They are exempt from the Router's separate 10 bps regular-swap
-fee, so the two fees are not stacked.
-
-For routed fills, operator-retained surplus is capped at 5%. Input-side profit
-is capped at 5% of executable input; output-side profit is capped at 5% of the
-signed `minAmountOut`. Any additional routing improvement is returned to the
-maker.
-
-Direct fills are protected by the configured `directFillQuoter`. The maker must
-receive at least the greater of the signed `minAmountOut` and 95% of the best
-current direct-adapter quote. A missing or zero protected quote fails closed,
-and any post-fee output sent above the protected floor belongs to the maker.
+> **Impact on fillability:** `feeOnOutput=true` orders are still fully fillable, but operators have less flexibility. In tight-margin or low-liquidity situations, this *could* reduce the likelihood of a fill since operators cannot optimize their profit-taking strategy on both sides.
+
+### Protected settlement
+
+The current PulseChain and Robinhood deployments charge a 30 bps (0.30%)
+limit-order fee. They are exempt from the Router's separate 10 bps regular-swap
+fee, so the two fees are not stacked.
+
+For routed fills, operator-retained surplus is capped at 5%. Input-side profit
+is capped at 5% of executable input; output-side profit is capped at 5% of the
+signed `minAmountOut`. Any additional routing improvement is returned to the
+maker.
+
+Direct fills are protected by the configured `directFillQuoter`. The maker must
+receive at least the greater of the signed `minAmountOut` and 95% of the best
+current direct-adapter quote. A missing or zero protected quote fails closed,
+and any post-fee output sent above the protected floor belongs to the maker.
 
 ### Tax token decision guide
 
@@ -408,7 +420,7 @@ and any post-fee output sent above the protected floor belongs to the maker.
 | **Neither token is taxed** | `false` (default) | Maximum operator flexibility → best chance of fill |
 | **Input token is taxed** | `true` | Router sends tokens directly from maker → pool in one transfer (one tax). Default mode would do maker → LO → pool (two transfers, two taxes). |
 | **Output token is taxed** | `false` (default) | Output goes directly to recipient in one transfer. |
-| **Both tokens taxed** | `false` | Supported through tax-safe routes; fee on input avoids another output-token transfer. |
+| **Both tokens taxed** | `false` | Supported through tax-safe routes; fee on input avoids another output-token transfer. |
 
 > **Recommendation:** Use `feeOnOutput: false` (the default) unless the input token has a transfer tax. This gives operators the most flexibility and the best chance of filling your order.
 
@@ -468,18 +480,18 @@ const stats = await fetchLimitOrderStats();
 
 ## Cancelling a Limit Order
 
-Cancellation is an **on-chain operation**:
+Cancellation is an **on-chain operation**:
 
 1. **On-chain:** Call `invalidateNonce(nonce)` on the **order's** SwitchLimitOrder contract. This is the authoritative cancellation — it prevents any operator from executing the order even if the backend hasn't been notified yet.
 
    > **⚠️** Each order includes a `limitOrderContract` field. Always use that address — do not hardcode a single contract constant, as the contract may be redeployed across versions.
 
-The backend indexer observes `NonceCancelled` and updates the orderbook. No
-separate REST mutation is required.
+The backend indexer observes `NonceCancelled` and updates the orderbook. No
+separate REST mutation is required.
 
 ```ts
 import { ethers } from "ethers";
-import { LIMIT_ORDER_ABI } from "@switch-win/sdk/constants";
+import { LIMIT_ORDER_ABI } from "@switch-win/sdk/constants";
 
 const signer = new ethers.Wallet(PRIVATE_KEY, provider);
 const maker = await signer.getAddress();
@@ -491,7 +503,7 @@ const contract = new ethers.Contract(order.limitOrderContract, LIMIT_ORDER_ABI,
 const tx = await contract.invalidateNonce(nonceToCancel);
 await tx.wait();
 
-// The backend indexer observes the event and marks the order CANCELLED.
+// The backend indexer observes the event and marks the order CANCELLED.
 ```
 
 To cancel **multiple orders** at once, use `invalidateNonces(uint256[])`:
@@ -501,7 +513,7 @@ const nonces = [1717171717, 1717171718, 1717171719];
 const tx = await contract.invalidateNonces(nonces);
 await tx.wait();
 
-// The backend indexer observes each NonceCancelled event.
+// The backend indexer observes each NonceCancelled event.
 ```
 
 ---
@@ -530,9 +542,11 @@ Submit a signed limit order. The backend verifies the EIP-712 signature before s
 > Your integration must:
 > 1. Call `submitLimitOrder()` **immediately** after the user signs.
 > 2. **Await** the response and confirm `success: true` before showing "order created".
-> 3. **Retry** on transient failures — the backend is idempotent on `maker + nonce`.
+> 3. On a transient failure, look up that exact maker + nonce and verify its
+>    contract and signed fields. Duplicates return an error, not idempotent
+>    success. Retry only the original signed payload; never generate a new nonce.
 >
-> Native PLS/ETH flow orders are the exception — they are recorded on-chain first,
+> Native PLS/ETH flow orders are the exception — they are recorded on-chain first,
 > so the backend discovers them via event indexing even if the POST never arrives.
 
 **Request body:**
@@ -547,11 +561,11 @@ Submit a signed limit order. The backend verifies the EIP-712 signature before s
   "deadline": 1717257600,
   "nonce": 1717171717,
   "feeOnOutput": false,
-  "recipient": "0x...",
-  "unwrapOutput": false,
-  "limitOrderContract": "0x...",
-  "signature": "0x..."
-}
+  "recipient": "0x...",
+  "unwrapOutput": false,
+  "limitOrderContract": "0x...",
+  "signature": "0x..."
+}
 ```
 
 **Success response (201):**
@@ -593,7 +607,7 @@ Submit a signed limit order. The backend verifies the EIP-712 signature before s
 | `"Signature does not match maker"` | The recovered signer doesn't match the `maker` field |
 | `"Nonce N already used for maker 0x..."` | This nonce has already been used (filled or submitted) |
 
-### `GET /limit-orders`
+### `GET /limit-orders`
 
 List orders with optional query filters. See [Query Filters](#query-filters) above.
 
@@ -663,13 +677,13 @@ Summary statistics.
 | `LimitOrderParams` | Order fields for EIP-712 signing |
 | `SignedLimitOrder` | `LimitOrderParams` + `signature` |
 | `CreateLimitOrderRequest` | Alias for `SignedLimitOrder` (POST body) |
-| `LimitOrderStatus` | `"ACTIVE" \| "FILLED" \| "CANCELLED" \| "EXPIRED"` |
+| `LimitOrderStatus` | `"ACTIVE" \| "FILLED" \| "CANCELLED" \| "EXPIRED"` |
 | `LimitOrderRecord` | Full order record from the API (includes `partnerAddress`, `limitOrderContract`, status, and timestamps) |
 | `CreateLimitOrderResponse` | `{ success: true, order: LimitOrderRecord }` |
 | `ListLimitOrdersResponse` | `{ total, limit, offset, orders: LimitOrderRecord[] }` |
 | `LimitOrderPair` | Active pair with order count |
 | `LimitOrderStats` | Global order statistics |
-| `LimitOrderMutationResponse` | Submission response + `ErrorResponse` |
+| `LimitOrderMutationResponse` | Submission response + `ErrorResponse` |
 
 ---
 
@@ -680,23 +694,23 @@ Available from `@switch-win/sdk/limit-orders`:
 | Function | Description |
 |---|---|
 | `buildLimitOrder(options)` | Build a `LimitOrderParams` object with sensible defaults |
-| `getEIP712SigningParams()` | Get the `{ domain, types }` for `signTypedData()` |
-| `getNetworkEIP712SigningParams(network, contract?)` | Build the correct PulseChain or Robinhood EIP-712 domain |
-| `getLimitOrderNetworkConfig(network)` | Get static chain, router, LO, wrapped-native, and native-flow defaults |
-| `getLimitOrderApprovalTarget(network, feeOnOutput, overrides?)` | Resolve the correct maker approval target |
+| `getEIP712SigningParams()` | Get the `{ domain, types }` for `signTypedData()` |
+| `getNetworkEIP712SigningParams(network, contract?)` | Build the correct PulseChain or Robinhood EIP-712 domain |
+| `getLimitOrderNetworkConfig(network)` | Get static chain, router, LO, wrapped-native, and native-flow defaults |
+| `getLimitOrderApprovalTarget(network, feeOnOutput, overrides?)` | Resolve the correct maker approval target |
 | `getApprovalTarget()` | Get approval target for `feeOnOutput: false` orders → SwitchLimitOrder |
 | `getRouterApprovalTarget()` | Get approval target for `feeOnOutput: true` orders → SwitchRouter |
 | `shouldUnwrapOutput(tokenOut)` | Returns `true` if tokenOut is WPLS (should set `unwrapOutput: true`) |
-| `getPLSFlowAddress()` | Get the SwitchPLSFlow contract address for native PLS limit orders |
-| `getNativeFlowAddress(network)` | Get the native PLS/ETH flow address for either chain |
-| `isNativePLS(tokenIn)` | Returns `true` if tokenIn is native PLS (use PLSFlow instead of EIP-712) |
-| `isNativeCurrency(tokenIn)` | Network-neutral native sentinel check |
+| `getPLSFlowAddress()` | Get the SwitchPLSFlow contract address for native PLS limit orders |
+| `getNativeFlowAddress(network)` | Get the native PLS/ETH flow address for either chain |
+| `isNativePLS(tokenIn)` | Returns `true` if tokenIn is native PLS (use PLSFlow instead of EIP-712) |
+| `isNativeCurrency(tokenIn)` | Network-neutral native sentinel check |
 | `submitLimitOrder(signedOrder)` | POST a signed order to the Switch backend |
 | `fetchLimitOrders(options?)` | GET orders with optional filters |
 | `fetchLimitOrder(maker, nonce)` | GET a single order by maker + nonce |
-| `fetchLimitOrderPairs()` | GET active pairs with order counts |
-| `fetchLimitOrderConfig({ network })` | GET live deployments and EIP-712 domain |
-| `fetchLimitOrderStats()` | GET global order statistics |
+| `fetchLimitOrderPairs()` | GET active pairs with order counts |
+| `fetchLimitOrderConfig({ network })` | GET live deployments and EIP-712 domain |
+| `fetchLimitOrderStats()` | GET global order statistics |
 
 ---
 
@@ -723,12 +737,12 @@ The EIP-712 domain and types must match the on-chain contract exactly:
     { name: "minAmountOut", type: "uint256" },
     { name: "deadline",     type: "uint256" },
     { name: "nonce",        type: "uint256" },
-    { name: "feeOnOutput",  type: "bool"    },
-    { name: "recipient",    type: "address" },
-    { name: "unwrapOutput", type: "bool"    },
-    { name: "partnerAddress", type: "address" },
-  ]
-}
+    { name: "feeOnOutput",  type: "bool"    },
+    { name: "recipient",    type: "address" },
+    { name: "unwrapOutput", type: "bool"    },
+    { name: "partnerAddress", type: "address" },
+  ]
+}
 ```
 
 These are exported as `LIMIT_ORDER_EIP712_DOMAIN` and `LIMIT_ORDER_EIP712_TYPES` from `@switch-win/sdk/constants`.
@@ -746,16 +760,16 @@ These are exported as `LIMIT_ORDER_EIP712_DOMAIN` and `LIMIT_ORDER_EIP712_TYPES`
 | `InvalidTokens()` | tokenIn and tokenOut are the same, or zero address |
 | `NonceAlreadyUsed()` | This nonce has already been filled or invalidated |
 | `OrderExpired()` | `block.timestamp > deadline` (and deadline > 0) |
-| `RouteInputExceedsMax()` | Route's total input exceeds the order's `amountIn` |
-| `NativeFlowInputNotFullyConsumed()` | Native-flow output-surplus route did not consume all executable input |
-| `RouteTokenInMismatch()` | A route does not start with the signed input token |
-| `RouteTokenOutMismatch()` | A route does not end with the signed output token |
-| `DirectFillQuoteUnavailable()` | The protected direct-fill quote is missing or zero |
-| `DirectFillPriceTooLow()` | The maker would receive less than the protected direct-fill floor |
-| `TransferFailed()` | Token transfer failed (insufficient balance or allowance) |
+| `RouteInputExceedsMax()` | Route's total input exceeds the order's `amountIn` |
+| `NativeFlowInputNotFullyConsumed()` | Native-flow output-surplus route did not consume all executable input |
+| `RouteTokenInMismatch()` | A route does not start with the signed input token |
+| `RouteTokenOutMismatch()` | A route does not end with the signed output token |
+| `DirectFillQuoteUnavailable()` | The protected direct-fill quote is missing or zero |
+| `DirectFillPriceTooLow()` | The maker would receive less than the protected direct-fill floor |
+| `TransferFailed()` | Token transfer failed (insufficient balance or allowance) |
 
 ---
 
 *See also: [README.md](README.md) for swap API docs, constants, and general integration info.*
 
-*Last updated: August 2026*
+*Last updated: August 2026*