@switch-win/sdk 1.2.9 → 1.3.1

package/examples/gasless-swap.ts

@@ -0,0 +1,173 @@
+import { BrowserProvider, type Eip1193Provider } from "ethers";
+import {
+  GaslessSwapClient,
+  createGaslessBrowserStore,
+  type GaslessOrderOutcome,
+  type GaslessTrade,
+  type GaslessEligibility,
+  type PreparedGaslessSwap,
+} from "../src/gasless-index.js";
+import type { LimitOrderNetwork } from "../src/limit-orders.js";
+
+/** Opt-in gasless flow: fixed 0.1% protocol fee plus up to 0.05% operator payout
+ * including gas. To offer regular swaps only, leave this flow out and use the
+ * regular swap example instead. See GASLESS.md for fee policy and integration steps.
+ * Wire these callbacks to your existing swap form/modal. No action runs on import. */
+export async function createGaslessSwapFlow(
+  wallet: Eip1193Provider,
+  network: LimitOrderNetwork,
+  ui: {
+    /** Main amount: prepared.expectedOutput. Separate minimum: prepared.minAmountOut.
+     * Format both with output-token decimals. The SDK signs the exact raw minimum. */
+    showQuote(prepared: PreparedGaslessSwap): void;
+    showRegular(reason: string): void;
+    /** Optional PLS/ETH payout, gas reserve and reason-code display. */
+    showEligibility?(eligibility: GaslessEligibility | undefined): void;
+    showPending(): void;
+    showOutcome(result: GaslessOrderOutcome): void;
+    showError(message: string): void;
+  },
+) {
+  const provider = new BrowserProvider(wallet, "any");
+  const signer = await provider.getSigner();
+  const maker = await signer.getAddress();
+  const client = new GaslessSwapClient({
+    network,
+    provider,
+    quoteEndpoint: "/api/switch/swap/quote",
+    taxEndpoint: "/api/switch/swap/checkTax",
+    ordersEndpoint: "/api/switch/limit-orders",
+  });
+  const store = createGaslessBrowserStore(network, maker);
+  let displayed: PreparedGaslessSwap | undefined;
+  let busy = false;
+  let quotesPaused = Boolean(await store.load());
+  let quoteRequest: AbortController | undefined;
+  let signingRequest: AbortController | undefined;
+  let intent = 0;
+  let unlimited = true; // Explicit user toggle can set false.
+
+  async function quote(trade: Omit<GaslessTrade, "maker">) {
+    if (busy || quotesPaused || (await store.load())) return;
+    quoteRequest?.abort();
+    const controller = (quoteRequest = new AbortController());
+    const current = ++intent;
+    try {
+      const result = await client.quote({ ...trade, maker }, controller.signal);
+      if (controller.signal.aborted || current !== intent) return;
+      displayed = result.eligible ? result.prepared : undefined;
+      ui.showEligibility?.(result.eligibility);
+      if (result.eligible) ui.showQuote(result.prepared);
+      else ui.showRegular(result.reason);
+    } catch (error) {
+      if (!controller.signal.aborted && current === intent)
+        ui.showError(
+          error instanceof Error ? error.message : "Quote unavailable",
+        );
+    }
+  }
+
+  async function sign(trade: Omit<GaslessTrade, "maker">) {
+    if (busy || (await store.load())) return;
+    busy = true;
+    quotesPaused = true;
+    quoteRequest?.abort();
+    const controller = (signingRequest = new AbortController());
+    try {
+      await client.signAndSubmit({
+        trade: { ...trade, maker },
+        signer,
+        store,
+        displayed,
+        signal: controller.signal,
+        // Refresh both amounts before the wallet opens: main expected output
+        // stays on prepared.expectedOutput; the SDK signs prepared.minAmountOut.
+        onPrepared(prepared) {
+          displayed = prepared;
+          ui.showQuote(prepared);
+          ui.showEligibility?.(
+            prepared.quote.gaslessEligibility ?? prepared.preview.eligibility,
+          );
+        },
+        onPending() {
+          ui.showPending();
+        },
+      });
+    } catch (error) {
+      ui.showError(
+        error instanceof Error ? error.message : "Gasless submission failed.",
+      );
+    } finally {
+      busy = false;
+      signingRequest = undefined;
+    }
+  }
+
+  async function approve(
+    trade: Omit<GaslessTrade, "maker">,
+    resetToZero = false,
+  ) {
+    if (busy || (await store.load())) return;
+    busy = true;
+    quoteRequest?.abort();
+    try {
+      const transaction = await client.approve({ ...trade, maker }, signer, {
+        unlimited,
+        resetToZero,
+        quoteGasPriceWei: displayed?.gasPriceWei,
+      });
+      const receipt = await transaction.wait();
+      if (!receipt || receipt.status !== 1)
+        throw Error("Token approval failed.");
+      // Approval time can stale the quote. Fetch on the next explicit quote/sign action.
+      displayed = undefined;
+    } finally {
+      busy = false;
+    }
+  }
+
+  async function checkStatus() {
+    const result = await client.reconcile(store);
+    if (result) ui.showOutcome(result);
+    if (result && result.status !== "pending") {
+      displayed = undefined;
+      quotesPaused = true;
+      // Show settlementTxUrl when filled. Do not automatically fetch another quote.
+    }
+    return result;
+  }
+
+  // Call on accountsChanged/chainChanged and any user edit, including slippage/recipient.
+  // Recreate this flow for a new account/network; maker, signer and store are scoped to them.
+  function invalidateIntent() {
+    intent++;
+    displayed = undefined;
+    ui.showEligibility?.(undefined);
+    quoteRequest?.abort();
+    signingRequest?.abort();
+    // A signature already obtained retains its pending lock even after abort.
+  }
+
+  return {
+    quote,
+    sign,
+    approve,
+    checkStatus,
+    invalidateIntent,
+    setUnlimited(value: boolean) {
+      unlimited = value;
+    },
+    async assertNoPending() {
+      // Call before Regular/Wrap actions too; closing the gasless modal is not cancellation.
+      if (busy || (await store.load()))
+        throw Error("A gasless order can still execute.");
+    },
+    async startAnotherSwap() {
+      if (busy || (await store.load()))
+        throw Error("The previous order can still execute.");
+      quotesPaused = false;
+    },
+    // Use a non-overlapping timer (await checkStatus, then setTimeout >= 5000ms).
+    // A close/dismiss button hides the modal; it does not cancel the signed order.
+  };
+}

package/examples/limit-order-ethers.ts

@@ -0,0 +1,195 @@
+/**
+ * Switch Limit Orders — Complete Example (ethers.js v6)
+ *
+ * Demonstrates the full limit order lifecycle:
+ *   1. Build order parameters
+ *   2. Approve the selected network's current contract to spend input tokens
+ *   3. Sign the order via EIP-712
+ *   4. Submit the signed order to the Switch backend
+ *   5. Query your active orders
+ *   6. Cancel an order on-chain
+ *
+ * Usage:
+ *   npx tsx examples/limit-order-ethers.ts
+ *
+ * Prerequisites:
+ *   npm install ethers
+ *   Set PRIVATE_KEY environment variable.
+ */
+
+import { ethers } from "ethers";
+import {
+  buildLimitOrder,
+  getNetworkEIP712SigningParams,
+  getLimitOrderApprovalTarget,
+  fetchLimitOrderConfig,
+  submitLimitOrder,
+  fetchLimitOrders,
+  fetchLimitOrder,
+  fetchLimitOrderPairs,
+  fetchLimitOrderStats,
+} from "../src/limit-orders";
+import {
+  ERC20_ABI,
+  LIMIT_ORDER_ABI,
+} from "../src/constants";
+import type { LimitOrderNetwork } from "../src/limit-orders";
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+const PRIVATE_KEY = process.env.PRIVATE_KEY!;
+const NETWORK = (process.env.SWITCH_NETWORK ?? "pulsechain") as LimitOrderNetwork;
+if (NETWORK !== "pulsechain" && NETWORK !== "robinhood") {
+  throw new Error("SWITCH_NETWORK must be pulsechain or robinhood");
+}
+const RPC_URL = process.env.RPC_URL ?? (
+  NETWORK === "robinhood"
+    ? "https://rpc.mainnet.chain.robinhood.com"
+    : "https://pulsechain-rpc.publicnode.com"
+);
+
+if (!PRIVATE_KEY) throw new Error("Set PRIVATE_KEY env var");
+
+// ── Order parameters ────────────────────────────────────────────────────────
+
+const TOKEN_IN = process.env.TOKEN_IN ?? (
+  NETWORK === "robinhood"
+    ? "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168" // USDG
+    : "0xA1077a294dDE1B09bB078844df40758a5D0f9a27" // WPLS
+);
+const TOKEN_OUT = process.env.TOKEN_OUT ?? (
+  NETWORK === "robinhood"
+    ? "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73" // WETH
+    : "0x95B303987A60C71504D99Aa1b13B4DA07b0790ab" // PLSX
+);
+const AMOUNT_IN = process.env.AMOUNT_IN ?? "1000000";
+const MIN_AMOUNT_OUT = process.env.MIN_AMOUNT_OUT ?? "1";
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const provider = new ethers.JsonRpcProvider(RPC_URL);
+  const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+  const maker = await signer.getAddress();
+  const liveConfig = await fetchLimitOrderConfig({ network: NETWORK });
+
+  console.log(`Maker: ${maker}`);
+  console.log(`Limit order: ${AMOUNT_IN} wei of ${TOKEN_IN} → min ${MIN_AMOUNT_OUT} wei of ${TOKEN_OUT}\n`);
+
+  // ── Step 1: Build the order ───────────────────────────────────────────
+  console.log("── Step 1: Building order ──");
+  const order = buildLimitOrder({
+    maker,
+    tokenIn: TOKEN_IN,
+    tokenOut: TOKEN_OUT,
+    amountIn: AMOUNT_IN,
+    minAmountOut: MIN_AMOUNT_OUT,
+    deadline: Math.floor(Date.now() / 1000) + 86400, // 24-hour expiry
+    // nonce: auto-generated from Date.now()
+    // feeOnOutput: false (default)
+    // recipient: maker (default)
+    // unwrapOutput: false (default)
+  });
+
+  console.log(`Nonce:    ${order.nonce}`);
+  console.log(`Deadline: ${new Date(order.deadline * 1000).toISOString()}`);
+
+  // ── Step 2: Approve the correct contract for this fee mode ────────────
+  console.log("\n── Step 2: Approving token spend ──");
+  const approvalTarget = getLimitOrderApprovalTarget(
+    NETWORK,
+    order.feeOnOutput,
+    { limitOrderContract: liveConfig.limitOrderContract },
+  );
+  const token = new ethers.Contract(TOKEN_IN, ERC20_ABI, signer);
+  const currentAllowance: bigint = await token.allowance(maker, approvalTarget);
+
+  if (currentAllowance < BigInt(AMOUNT_IN)) {
+    console.log(`Approving ${approvalTarget} to spend ${AMOUNT_IN} wei...`);
+    const approveTx = await token.approve(approvalTarget, AMOUNT_IN);
+    const approveReceipt = await approveTx.wait();
+    console.log(`Approved in tx: ${approveReceipt.hash}`);
+  } else {
+    console.log("Sufficient allowance already granted");
+  }
+
+  // ── Step 3: Sign the order via EIP-712 ────────────────────────────────
+  console.log("\n── Step 3: Signing order (EIP-712) ──");
+  const { domain, types } = getNetworkEIP712SigningParams(
+    NETWORK,
+    liveConfig.limitOrderContract,
+  );
+  const signature = await signer.signTypedData(domain, types, order);
+  console.log(`Signature: ${signature.slice(0, 20)}...`);
+
+  // ── Step 4: Submit signedorder to the Switch backend ─────────────────
+  console.log("\n── Step 4: Submitting order to backend ──");
+  const result = await submitLimitOrder(
+    { ...order, signature, limitOrderContract: liveConfig.limitOrderContract },
+    { network: NETWORK },
+  );
+
+  if ("error" in result) {
+    throw new Error(`Submit failed: ${result.error}`);
+  }
+
+  console.log(`Order created! ID: ${result.order.id}`);
+  console.log(`Status: ${result.order.status}`);
+
+  // ── Step 5: Query orders ──────────────────────────────────────────────
+  console.log("\n── Step 5: Querying orders ──");
+
+  // Fetch all active orders for this maker
+  const { orders, total } = await fetchLimitOrders({
+    maker,
+    status: "ACTIVE",
+    network: NETWORK,
+  });
+  console.log(`Active orders for ${maker}: ${total}`);
+  for (const o of orders) {
+    console.log(`  [nonce=${o.nonce}] ${o.tokenIn} → ${o.tokenOut} | ${o.amountIn} → min ${o.minAmountOut}`);
+  }
+
+  // Fetch the specific order we just created
+  const fetched = await fetchLimitOrder(maker, order.nonce, { network: NETWORK });
+  if ("error" in fetched) {
+    console.log(`  Lookup failed: ${fetched.error}`);
+  } else {
+    console.log(`\nFetched order: nonce=${fetched.nonce}, status=${fetched.status}`);
+  }
+
+  // Check active pairs
+  const pairs = await fetchLimitOrderPairs({ network: NETWORK });
+  console.log(`\nActive pairs: ${pairs.length}`);
+  for (const p of pairs) {
+    console.log(`  ${p.pairKey} — ${p.activeOrders} orders`);
+  }
+
+  // Global stats
+  const stats = await fetchLimitOrderStats({ network: NETWORK });
+  console.log(`\nStats: active=${stats.active}, filled=${stats.filled}, cancelled=${stats.cancelled}, expired=${stats.expired}`);
+
+  // ── Step 6: Cancel the order ──────────────────────────────────────────
+  console.log("\n── Step 6: Cancelling order ──");
+
+  // Cancel on-chain (prevents the filler bot from executing it). Use the
+  // per-order contract so older orders remain cancellable after upgrades.
+  console.log("Invalidating nonce on-chain...");
+  const limitOrderContract = new ethers.Contract(
+    result.order.limitOrderContract ?? liveConfig.limitOrderContract,
+    LIMIT_ORDER_ABI,
+    signer,
+  );
+  const cancelTx = await limitOrderContract.invalidateNonce(order.nonce);
+  const cancelReceipt = await cancelTx.wait();
+  console.log(`Nonce invalidated in tx: ${cancelReceipt.hash}`);
+
+  // The backend indexer observes NonceCancelled and updates order status.
+
+  console.log("\nDone!");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/nextjs-proxy.ts

@@ -0,0 +1,82 @@
+/**
+ * Switch DEX Aggregator — Next.js API Route Proxy
+ *
+ * Keeps your API key server-side. Your frontend calls YOUR endpoint,
+ * which attaches the key and forwards the request to Switch.
+ *
+ * File: app/api/swap/[...path]/route.ts  (Next.js App Router catch-all)
+ *
+ * Proxied routes:
+ *   /api/swap/quote     → /swap/quote     (get a swap quote)
+ *   /api/swap/adapters  → /swap/adapters  (list DEX adapters)
+ *   /api/swap/checkTax  → /swap/checkTax  (check token buy/sell tax)
+ *
+ * Frontend usage:
+ *   const quote    = await fetch("/api/swap/quote?network=pulsechain&from=0x...&to=0x...&amount=1000&sender=0x...");
+ *   const adapters = await fetch("/api/swap/adapters?network=pulsechain");
+ *   const tax      = await fetch("/api/swap/checkTax?token=0x...&network=pulsechain");
+ */
+
+const SWITCH_API_KEY = process.env.SWITCH_API_KEY;
+const SWITCH_API_BASE =
+  process.env.SWITCH_API_BASE ?? "https://quote.switch.win";
+
+/** Allowed upstream paths (whitelist to prevent open-proxy abuse). */
+const ALLOWED_PATHS = new Set(["quote", "adapters", "checkTax"]);
+
+if (!SWITCH_API_KEY) {
+  console.warn(
+    "⚠️  SWITCH_API_KEY is not set — swap proxy will not work.",
+  );
+}
+
+export async function GET(
+  request: Request,
+  { params }: { params: { path: string[] } },
+) {
+  if (!SWITCH_API_KEY) {
+    return Response.json(
+      { error: "Server misconfiguration: API key not set" },
+      { status: 500 },
+    );
+  }
+
+  // Resolve the sub-path, e.g. ["quote"] or ["checkTax"]
+  const subPath = params.path?.join("/") ?? "";
+
+  if (!ALLOWED_PATHS.has(subPath)) {
+    return Response.json(
+      { error: `Unknown endpoint: /swap/${subPath}` },
+      { status: 404 },
+    );
+  }
+
+  const { searchParams } = new URL(request.url);
+
+  // Build the upstream URL and forward all query params
+  const url = new URL(`/swap/${subPath}`, SWITCH_API_BASE);
+  searchParams.forEach((value, key) => url.searchParams.set(key, value));
+
+  try {
+    const upstream = await fetch(url.toString(), {
+      headers: { "x-api-key": SWITCH_API_KEY },
+      // Don't cache on the edge — quote freshness matters
+      cache: "no-store",
+    });
+
+    const data = await upstream.json();
+
+    return Response.json(data, {
+      status: upstream.status,
+      headers: {
+        "Cache-Control": "no-store, max-age=0",
+      },
+    });
+  } catch (err) {
+    console.error("Switch API proxy error:", err);
+    return Response.json(
+      { error: "Failed to reach Switch API" },
+      { status: 502 },
+    );
+  }
+}