@switch-win/sdk 1.2.9 → 1.3.0

package/src/gasless-index.ts

@@ -0,0 +1,4 @@
+export * from "./gasless.js";
+export * from "./gasless-client.js";
+export * from "./gasless-store.js";
+export * from "./gasless-operators.js";

package/src/gasless-operators.ts

@@ -0,0 +1,227 @@
+import { Contract, Interface, verifyTypedData, type Provider } from "ethers";
+import type { LimitOrderConfigResponse, LimitOrderRecord } from "./types.js";
+import type {
+  GaslessDeployment,
+  GaslessOrder,
+  GaslessRoute,
+} from "./gasless-types.js";
+import {
+  GASLESS_OPERATOR_ROLE,
+  GASLESS_SWITCH_ABI,
+  GaslessError,
+  gaslessAddress,
+  gaslessUint,
+  getGaslessSigningParams,
+  readGaslessChainState,
+  sameAddress,
+  validateGaslessConfig,
+} from "./gasless.js";
+
+/** Never infer gasless from a symbol, short deadline, orderType label, or legacy array. */
+export function classifySwitchOrder(
+  order: Pick<LimitOrderRecord, "limitOrderContract">,
+  config: LimitOrderConfigResponse,
+  deployment: GaslessDeployment,
+): "gasless" | "limit-order" | "unsupported" {
+  validateGaslessConfig(config, deployment);
+  if (sameAddress(order.limitOrderContract, deployment.contract))
+    return "gasless";
+  if (sameAddress(order.limitOrderContract, config.limitOrderContract))
+    return "limit-order";
+  return "unsupported";
+}
+
+export function selectGaslessPriorityOrders(
+  orders: readonly LimitOrderRecord[],
+  config: LimitOrderConfigResponse,
+  deployment: GaslessDeployment,
+  chainTimestamp: number,
+): LimitOrderRecord[] {
+  if (!Number.isSafeInteger(chainTimestamp) || chainTimestamp <= 0)
+    throw new GaslessError(
+      "INVALID_TIMESTAMP",
+      "A chain timestamp is required.",
+    );
+  const seen = new Set<string>();
+  return orders
+    .filter((order) => {
+      const key = `${order.limitOrderContract?.toLowerCase()}:${order.maker.toLowerCase()}:${order.nonce}`;
+      if (
+        classifySwitchOrder(order, config, deployment) !== "gasless" ||
+        order.status !== "ACTIVE" ||
+        !Number.isSafeInteger(order.deadline) ||
+        order.deadline <= chainTimestamp ||
+        seen.has(key)
+      )
+        return false;
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) => a.deadline - b.deadline || a.nonce - b.nonce);
+}
+
+/** Gasless V2 fixes the excess side from the maker's signed fee mode. */
+export function gaslessExcessOnInput(feeOnOutput: boolean): boolean {
+  if (typeof feeOnOutput !== "boolean")
+    throw new GaslessError(
+      "INVALID_FEE_MODE",
+      "The signed fee mode is required.",
+    );
+  return !feeOnOutput;
+}
+
+/** Nominal cap before payout transfer tax. Gas is part of this payout, never an add-on. */
+export function cappedGaslessPayout(
+  availableSurplus: bigint,
+  afterFeeBase: bigint,
+): bigint {
+  if (afterFeeBase <= 0n || availableSurplus <= 0n) return 0n;
+  const cap = (afterFeeBase * 5n) / 10000n;
+  return availableSurplus < cap ? availableSurplus : cap;
+}
+
+/** Use measured after-tax payout valued via an executable payout-token/native route. */
+export function assessGaslessOperatorProfit(
+  payoutNative: bigint,
+  gasLimit: bigint,
+  gasPrice: bigint,
+  minimumNetNative = 0n,
+) {
+  if (
+    payoutNative < 0n ||
+    gasLimit <= 0n ||
+    gasPrice <= 0n ||
+    minimumNetNative < 0n
+  )
+    throw new GaslessError("INVALID_GAS", "Invalid payout or full gas budget.");
+  const gasBudgetNative = gasLimit * gasPrice;
+  const netNative = payoutNative - gasBudgetNative;
+  return {
+    eligible: netNative > 0n && netNative >= minimumNetNative,
+    gasBudgetNative,
+    netNative,
+  };
+}
+
+export async function assertGaslessOperator(
+  provider: Provider,
+  deployment: GaslessDeployment,
+  operator: string,
+): Promise<void> {
+  const state = await readGaslessChainState(provider, deployment);
+  const c = new Contract(deployment.contract, GASLESS_SWITCH_ABI, provider);
+  if (
+    !(await c.hasRole(GASLESS_OPERATOR_ROLE, gaslessAddress(operator), {
+      blockTag: state.blockNumber,
+    }))
+  )
+    throw new GaslessError(
+      "OPERATOR_NOT_APPROVED",
+      "This operator is not registered on the gasless settlement contract.",
+    );
+}
+
+/** Encode already-built execution routes. This does NOT quote, simulate, or establish profitability. */
+export function encodeGaslessFill(input: {
+  deployment: GaslessDeployment;
+  order: GaslessOrder;
+  signature: string;
+  routes: readonly GaslessRoute[];
+  /** Actual maker -> settlement balance delta, required for an input-fee fill. */
+  receivedInput?: string;
+  chainTimestamp: number;
+}): { to: string; data: string; value: string } {
+  const { deployment, order, signature, routes } = input;
+  if (
+    !Number.isSafeInteger(order.nonce) ||
+    order.nonce < 0 ||
+    !Number.isSafeInteger(order.deadline) ||
+    !Number.isSafeInteger(input.chainTimestamp) ||
+    order.deadline <= input.chainTimestamp ||
+    order.deadline === 0 ||
+    typeof order.unwrapOutput !== "boolean" ||
+    (order.unwrapOutput &&
+      !sameAddress(order.tokenOut, deployment.wrappedNative))
+  )
+    throw new GaslessError(
+      "INVALID_ORDER",
+      "Invalid or expired gasless order.",
+    );
+  [order.maker, order.tokenIn, order.tokenOut, order.recipient].forEach((a) =>
+    gaslessAddress(a),
+  );
+  gaslessAddress(order.partnerAddress, true);
+  gaslessUint(order.minAmountOut);
+  if (
+    sameAddress(order.tokenIn, order.tokenOut) ||
+    sameAddress(order.recipient, deployment.contract)
+  )
+    throw new GaslessError(
+      "INVALID_ORDER",
+      "Invalid gasless token pair or recipient.",
+    );
+  const { domain, types } = getGaslessSigningParams(deployment);
+  if (
+    !sameAddress(verifyTypedData(domain, types, order, signature), order.maker)
+  )
+    throw new GaslessError(
+      "INVALID_SIGNATURE",
+      "Gasless signature does not match the maker.",
+    );
+  let total = 0n;
+  if (!routes.length || routes.length > 16)
+    throw new GaslessError("INVALID_ROUTE", "Execution routes are required.");
+  for (const route of routes) {
+    const amount = gaslessUint(String(route.amountIn));
+    total += amount;
+    if (
+      !route.hops.length ||
+      route.hops.length > 8 ||
+      !sameAddress(route.hops[0].tokenIn, order.tokenIn) ||
+      !sameAddress(route.hops[route.hops.length - 1].tokenOut, order.tokenOut)
+    )
+      throw new GaslessError(
+        "INVALID_ROUTE",
+        "Route endpoints do not match the order.",
+      );
+    let previous = order.tokenIn;
+    for (const hop of route.hops) {
+      if (!sameAddress(hop.tokenIn, previous) || !hop.legs.length)
+        throw new GaslessError(
+          "INVALID_ROUTE",
+          "Disconnected execution route.",
+        );
+      previous = gaslessAddress(hop.tokenOut);
+      for (const leg of hop.legs) {
+        gaslessAddress(leg.adapter);
+        gaslessUint(String(leg.amountIn));
+      }
+    }
+  }
+  const amountIn = gaslessUint(order.amountIn);
+  if (order.feeOnOutput) {
+    if (total !== amountIn)
+      throw new GaslessError(
+        "INVALID_ROUTE",
+        "Output-fee gasless orders route the full signed input.",
+      );
+  } else {
+    const received = gaslessUint(input.receivedInput);
+    const available = received - (received * 10n) / 10000n;
+    if (received > amountIn || total > available)
+      throw new GaslessError(
+        "INVALID_ROUTE",
+        "Input-fee routes exceed the measured after-fee input.",
+      );
+  }
+  return {
+    to: deployment.contract,
+    data: new Interface(GASLESS_SWITCH_ABI).encodeFunctionData("fillOrder", [
+      order,
+      signature,
+      routes,
+      gaslessExcessOnInput(order.feeOnOutput),
+    ]),
+    value: "0",
+  };
+}

package/src/gasless-store.ts

@@ -0,0 +1,137 @@
+import type { LimitOrderNetwork } from "./limit-orders.js";
+import type {
+  GaslessPendingStore,
+  PendingGaslessOrder,
+} from "./gasless-types.js";
+import {
+  GASLESS_DEPLOYMENTS,
+  GaslessError,
+  gaslessAddress,
+  gaslessUint,
+  sameAddress,
+} from "./gasless.js";
+
+export interface GaslessStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface GaslessLockManager {
+  request<T>(name: string, callback: () => T | PromiseLike<T>): Promise<T>;
+}
+
+function identity(p: PendingGaslessOrder): string {
+  return `${p.chainId}:${p.contract.toLowerCase()}:${p.order.maker.toLowerCase()}:${p.order.nonce}`;
+}
+
+/** Invalid storage must block new orders rather than silently discarding a live signature. */
+export function parseGaslessPending(
+  value: string,
+  network: LimitOrderNetwork,
+  maker: string,
+): PendingGaslessOrder {
+  try {
+    const p = JSON.parse(value) as PendingGaslessOrder;
+    if (
+      p.network !== network ||
+      p.chainId !== GASLESS_DEPLOYMENTS[network].chainId ||
+      !sameAddress(p.order.maker, maker) ||
+      !Number.isSafeInteger(p.order.nonce) ||
+      p.order.nonce < 0 ||
+      !Number.isSafeInteger(p.order.deadline) ||
+      p.order.deadline <= 0 ||
+      typeof p.order.feeOnOutput !== "boolean" ||
+      typeof p.order.unwrapOutput !== "boolean" ||
+      !["signing", "submitting", "submitted", "uncertain"].includes(p.state) ||
+      (p.state !== "signing" && !p.signature) ||
+      (p.signature !== undefined && !/^0x[\da-f]{130}$/i.test(p.signature))
+    )
+      throw Error();
+    [
+      p.contract,
+      p.order.maker,
+      p.order.tokenIn,
+      p.order.tokenOut,
+      p.order.recipient,
+    ].forEach((a) => gaslessAddress(a));
+    gaslessAddress(p.order.partnerAddress, true);
+    gaslessUint(p.order.amountIn);
+    gaslessUint(p.order.minAmountOut);
+    return p;
+  } catch {
+    throw new GaslessError(
+      "PENDING_STORAGE_INVALID",
+      "Saved gasless order data is invalid. Recover its status before starting another swap.",
+    );
+  }
+}
+
+/** Browser store serializes tabs using Web Locks and persists orders across reloads. */
+export function createGaslessBrowserStore(
+  network: LimitOrderNetwork,
+  makerInput: string,
+  options: {
+    storage?: GaslessStorage;
+    locks?: GaslessLockManager;
+  } = {},
+): GaslessPendingStore {
+  const maker = gaslessAddress(makerInput);
+  const storage = options.storage ?? globalThis.localStorage;
+  const locks = options.locks ?? globalThis.navigator?.locks;
+  if (!storage || !locks)
+    throw new GaslessError(
+      "PENDING_STORAGE_UNAVAILABLE",
+      "Durable storage and Web Locks are required. Supply an atomic application store in this environment.",
+    );
+  const key = `switch:sdk:gasless-pending:${GASLESS_DEPLOYMENTS[network].chainId}:${maker.toLowerCase()}`;
+  const load = () => {
+    const value = storage.getItem(key);
+    return value === null ? null : parseGaslessPending(value, network, maker);
+  };
+  const check = (p: PendingGaslessOrder) =>
+    parseGaslessPending(JSON.stringify(p), network, maker);
+  return {
+    async load() {
+      return load();
+    },
+    async reserve(pending) {
+      await locks.request(key, () => {
+        if (load())
+          throw new GaslessError(
+            "ORDER_PENDING",
+            "Another gasless order is pending in this browser.",
+          );
+        storage.setItem(key, JSON.stringify(check(pending)));
+      });
+    },
+    async update(pending) {
+      await locks.request(key, () => {
+        const current = load();
+        if (!current || identity(current) !== identity(pending))
+          throw new GaslessError(
+            "PENDING_ORDER_CHANGED",
+            "Saved pending order changed.",
+          );
+        if (JSON.stringify(current.order) !== JSON.stringify(pending.order))
+          throw new GaslessError(
+            "PENDING_ORDER_CHANGED",
+            "Cannot change a pending order's signed fields.",
+          );
+        if (current.signature && current.signature !== pending.signature)
+          throw new GaslessError(
+            "PENDING_ORDER_CHANGED",
+            "Cannot replace a saved signature.",
+          );
+        storage.setItem(key, JSON.stringify(check(pending)));
+      });
+    },
+    async release(pending) {
+      await locks.request(key, () => {
+        const current = load();
+        if (current && identity(current) === identity(pending))
+          storage.removeItem(key);
+      });
+    },
+  };
+}

package/src/gasless-types.ts

@@ -0,0 +1,258 @@
+import type {
+  BestPathResponse,
+  LimitOrderParams,
+  LimitOrderRecord,
+} from "./types.js";
+import type { LimitOrderNetwork } from "./limit-orders.js";
+
+export interface GaslessDeployment {
+  network: LimitOrderNetwork;
+  chainId: number;
+  contract: string;
+  router: string;
+  wrappedNative: string;
+  explorer: string;
+}
+
+export type GaslessEligibilityReason =
+  | "READY"
+  | "NOT_REQUESTED"
+  | "EXECUTION_UNVERIFIED"
+  | "PAYOUT_UNVALUED"
+  | "GAS_NOT_COVERED"
+  | "INSUFFICIENT_SAFETY_MARGIN"
+  | "OPERATOR_GAS_UNAVAILABLE"
+  | "NO_APPROVED_OPERATOR"
+  | "SLIPPAGE_BUFFER_TOO_SMALL"
+  | "STALE_PREVIEW";
+
+/** Server recommendation; all native Wei values are decimal strings. */
+export interface GaslessEligibility {
+  policyVersion: 1;
+  status: "eligible" | "ineligible" | "unavailable" | "not_checked";
+  eligible: boolean;
+  recommendation: "gasless" | "regular";
+  reasonCode: GaslessEligibilityReason;
+  reason: string;
+  nativeSymbol: "PLS" | "ETH";
+  protocolFeeBps: 10;
+  maxOperatorPayoutBps: 5;
+  requiredGasCoverageBps: 20000;
+  payoutValuationHaircutBps: 1000;
+  minimumSlippageBps: 50;
+  /** Registration and a funded wallet do not prove a worker is online. */
+  operatorLivenessVerified: false;
+  /** Milliseconds since the Unix epoch. */
+  checkedAt: number;
+  /** Milliseconds since the Unix epoch. */
+  expiresAt: number;
+  economics?: {
+    estimatedGasUnits: string;
+    gasLimit: string;
+    gasPriceWei: string;
+    estimatedGasCostNativeWei: string;
+    estimatedGasCostNative: string;
+    operatorPayoutNativeWei: string;
+    operatorPayoutNative: string;
+    gasBudgetNativeWei: string;
+    gasBudgetNative: string;
+    conservativeGasBudgetNativeWei: string;
+    conservativeGasBudgetNative: string;
+    stressedOperatorPayoutNativeWei: string;
+    requiredOperatorPayoutNativeWei: string;
+    requiredOperatorPayoutNative: string;
+    payoutToGasCoverageBps: string;
+    /** Signed: negative values mean the payout does not cover the budget. */
+    netAfterGasBudgetNativeWei: string;
+    shortfallNativeWei: string;
+    gasCovered: boolean;
+    safetyMarginCovered: boolean;
+  };
+  operator?: {
+    address: string;
+    nativeBalanceWei: string;
+    gasAvailable: boolean;
+  };
+}
+
+/** Amounts are uint256 decimal strings; timestamps are Unix seconds except checkedAt. */
+export interface GaslessExecutionPreview {
+  status: "ready";
+  version: 2;
+  settlementVersion: 2;
+  maker: string;
+  chainId: number;
+  contract: string;
+  tokenIn: string;
+  tokenOut: string;
+  amountIn: string;
+  recipient: string;
+  unwrapOutput: boolean;
+  feeOnOutput: boolean;
+  excessOnInput: boolean;
+  payoutToken: string;
+  routeHash: string;
+  quoteBlockNumber: number;
+  /** Milliseconds since the Unix epoch. */
+  checkedAt: number;
+  slippageBps: number;
+  expectedOutputAmount: string;
+  minAmountOut: string;
+  recipientAmountOut: string;
+  /** Actual payout received after any transfer tax. */
+  operatorPayout: string;
+  nominalOperatorPayout: string;
+  payoutCapBase: string;
+  operatorPayoutNative: string;
+  estimatedGas: string;
+  gasLimit: string;
+  gasPriceWei: string;
+  gasBudgetNative: string;
+  gasPriceBoostBps: number;
+  gasLimitBps: number;
+  headroomBps: number;
+  eligible: boolean;
+  reason?: string;
+  /** Additive API metadata. A ready simulation can still be economically ineligible. */
+  eligibility?: GaslessEligibility;
+}
+
+export type GaslessPreviewResult =
+  | GaslessExecutionPreview
+  | {
+      status: "unavailable";
+      reason: string;
+      eligibility?: GaslessEligibility;
+    };
+
+export interface GaslessQuoteResponse extends BestPathResponse {
+  protocolFeeBps: number;
+  feeOnOutput: boolean;
+  quoteGasPrice: string;
+  quoteBlockNumber: number;
+  gaslessExecution: GaslessPreviewResult;
+}
+
+export interface GaslessTrade {
+  maker: string;
+  tokenIn: string;
+  /** Native sentinel is supported on output; signed orders use wrapped native. */
+  tokenOut: string;
+  amountIn: string;
+  recipient?: string;
+  partnerAddress?: string;
+  /** User price tolerance only. It never increases the contract's payout cap. 0–100. */
+  slippageBps?: number;
+}
+
+export interface GaslessTaxInfo {
+  isTaxToken: boolean;
+  buyTaxBps: number;
+  sellTaxBps: number;
+}
+
+export interface GaslessChainState {
+  checkedAt: number;
+  blockNumber: number;
+  blockTimestamp: number;
+  rawGasPriceWei: string;
+}
+
+export interface PreparedGaslessSwap {
+  deployment: GaslessDeployment;
+  trade: Required<GaslessTrade>;
+  quote: GaslessQuoteResponse;
+  preview: GaslessExecutionPreview;
+  feeOnOutput: boolean;
+  expectedOutput: string;
+  minAmountOut: string;
+  payoutToken: string;
+  operatorPayout: string;
+  gasPriceWei: string;
+  gasLimit: string;
+  gasBudgetNative: string;
+  chainState: GaslessChainState;
+}
+
+export type GaslessUnavailableCode =
+  | "NATIVE_INPUT_REQUIRES_WRAP"
+  | "CONFIGURATION_CHANGED"
+  | "TAX_CHECK_UNAVAILABLE"
+  | "QUOTE_UNAVAILABLE"
+  | "PREVIEW_UNAVAILABLE"
+  | "STALE_QUOTE"
+  | "INVALID_PREVIEW"
+  | "SERVER_INELIGIBLE"
+  | "INSUFFICIENT_OPERATOR_PAYOUT";
+
+export type GaslessQuoteDecision =
+  | {
+      eligible: true;
+      prepared: PreparedGaslessSwap;
+      eligibility?: GaslessEligibility;
+    }
+  | {
+      eligible: false;
+      code: GaslessUnavailableCode;
+      reason: string;
+      retryable: boolean;
+      /** Server economics are available even when this swap cannot use gasless. */
+      eligibility?: GaslessEligibility;
+    };
+
+/** The API currently stores nonces as safe JSON integers, even though Solidity uses uint256. */
+export interface GaslessOrder extends LimitOrderParams {}
+
+export interface SignedGaslessOrder extends GaslessOrder {
+  limitOrderContract: string;
+  signature: string;
+}
+
+export interface PendingGaslessOrder {
+  network: LimitOrderNetwork;
+  chainId: number;
+  contract: string;
+  order: GaslessOrder;
+  state: "signing" | "submitting" | "submitted" | "uncertain";
+  signature?: string;
+}
+
+/** Implement atomically, scoped to network + maker. Persist before opening the wallet. */
+export interface GaslessPendingStore {
+  load(): Promise<PendingGaslessOrder | null>;
+  /** Must reject if another pending order already occupies this maker's slot. */
+  reserve(pending: PendingGaslessOrder): Promise<void>;
+  /** Must update only the same contract + maker + nonce; preserve the signature. */
+  update(pending: PendingGaslessOrder): Promise<void>;
+  /** Must release only the matching order. Never clear a different tab's order. */
+  release(pending: PendingGaslessOrder): Promise<void>;
+}
+
+export type GaslessOrderOutcome =
+  | { status: "pending"; pending: PendingGaslessOrder }
+  | {
+      status: "filled";
+      pending: PendingGaslessOrder;
+      record: LimitOrderRecord;
+      settlementTxUrl?: string;
+    }
+  | {
+      status: "cancelled";
+      pending: PendingGaslessOrder;
+      record: LimitOrderRecord;
+    }
+  | { status: "closed"; pending: PendingGaslessOrder; reason: string };
+
+export interface GaslessRoute {
+  amountIn: string | bigint;
+  hops: {
+    tokenIn: string;
+    tokenOut: string;
+    legs: {
+      adapter: string;
+      amountIn: string | bigint;
+      fee: number;
+      data: string;
+    }[];
+  }[];
+}