@0xsquid/deposit-widget 0.0.2-beta.0 → 0.1.0

package/src/hooks/use-transaction-history.ts

@@ -0,0 +1,198 @@
+import { useCallback, useMemo } from "react";
+import { useQueries } from "@tanstack/react-query";
+import {
+  useWallet,
+  useHistoryStore,
+  useSquidTokens,
+  useSquidChains,
+  useConfigStore,
+  HistoryTxType,
+  parseToBigInt,
+} from "@0xsquid/react-hooks";
+import { getWalletHistory } from "../services/wallet-history/get-wallet-history";
+import {
+  groupAndSortByDay,
+  pendingSwapToFormattedTx,
+  toFormattedTx,
+  type DayGroup,
+} from "../services/wallet-history/format";
+import type { SquidTransaction } from "../services/wallet-history/types";
+import {
+  useDepositStore,
+  useIsPaymentMode,
+  usePaymentAmount,
+} from "../store/use-deposit-store";
+import {
+  isPaymentTx,
+  isSameAddress,
+  isSameTx,
+  matchesDestinationToken,
+} from "../utils/transaction";
+
+export function useTransactionHistory(): {
+  isLoading: boolean;
+  isError: boolean;
+  groups: DayGroup[];
+} {
+  const { connectedAddresses } = useWallet();
+  const config = useDepositStore((s) => s.config);
+  const integratorId = config?.integrator.id;
+  const apiUrl = useConfigStore((s) => s.config.apiUrl);
+  const pendingFromStore = useHistoryStore((s) => s.transactions);
+  const { findToken, tokens } = useSquidTokens();
+  const { findChain } = useSquidChains();
+
+  const destinationToken = config?.destinationToken;
+  const isPaymentMode = useIsPaymentMode();
+  const paymentAmount = usePaymentAmount();
+
+  const destinationTokenDecimals = destinationToken
+    ? tokens.find(
+        (t) =>
+          t.chainId === destinationToken.chainId &&
+          isSameAddress(t.address, destinationToken.address),
+      )?.decimals
+    : null;
+
+  const addresses = useMemo(
+    () =>
+      Array.from(
+        new Set(
+          Object.values(connectedAddresses).filter(
+            (a): a is string => a != null && a.length > 0,
+          ),
+        ),
+      ),
+    [connectedAddresses],
+  );
+
+  // Memoized so TanStack Query doesn't re-run the filter on every render.
+  const select = useCallback(
+    (data: SquidTransaction[]) => {
+      if (!destinationToken) return [];
+
+      if (
+        isPaymentMode &&
+        (!paymentAmount || destinationTokenDecimals == null)
+      ) {
+        return [];
+      }
+
+      return data.filter((tx) => {
+        // validate destination token
+        if (
+          !matchesDestinationToken(
+            tx.quote.route.estimate.toToken,
+            destinationToken,
+          )
+        ) {
+          return false;
+        }
+
+        if (isPaymentMode) {
+          return isPaymentTx(tx, paymentAmount!, destinationTokenDecimals!);
+        }
+
+        return true;
+      });
+    },
+    [destinationToken, isPaymentMode, paymentAmount, destinationTokenDecimals],
+  );
+
+  const queries = useQueries({
+    queries: addresses.map((address) => ({
+      queryKey: ["deposit-widget", "tx-history", address, integratorId, apiUrl],
+      queryFn: () => {
+        if (!integratorId || !apiUrl) {
+          throw new Error(
+            "integratorId and apiUrl are required to fetch wallet history",
+          );
+        }
+        return getWalletHistory(address, integratorId, apiUrl);
+      },
+      select,
+      enabled: !!address && !!integratorId && !!apiUrl,
+      staleTime: 30_000,
+    })),
+  });
+
+  const isLoading = queries.some((q) => q.isLoading);
+  const isError = queries.length > 0 && queries.every((q) => q.isError);
+
+  return useMemo(() => {
+    if (!destinationToken) {
+      return { isLoading, isError, groups: [] };
+    }
+
+    const backendTxs: SquidTransaction[] = queries
+      .map((q) => q.data)
+      .flatMap((data) => data ?? []);
+
+    // Overlay local pendings for the brief window where a tx resolved locally
+    // but Squid's backend hasn't indexed it yet.
+    const formatted = backendTxs.map((tx) =>
+      toFormattedTx(tx, findChain(tx.fromChainId)),
+    );
+
+    const connectedAddressSet = new Set(addresses.map((a) => a.toLowerCase()));
+    const expectedPayment =
+      paymentAmount && destinationTokenDecimals != null
+        ? parseToBigInt(paymentAmount, destinationTokenDecimals).toString()
+        : undefined;
+
+    for (const { data: pendingTx, txType } of pendingFromStore) {
+      if (txType !== HistoryTxType.SWAP) continue;
+
+      // validate source address
+      if (!connectedAddressSet.has(pendingTx.fromAddress.toLowerCase())) {
+        continue;
+      }
+
+      // validate destination token
+      if (
+        !matchesDestinationToken(
+          { address: pendingTx.toToken, chainId: pendingTx.toChain },
+          destinationToken,
+        )
+      ) {
+        continue;
+      }
+
+      // skip if already indexed
+      if (backendTxs.some((tx) => isSameTx(tx, pendingTx))) continue;
+
+      const isPayment =
+        expectedPayment != null && pendingTx.toAmount === expectedPayment;
+
+      if (isPaymentMode !== isPayment) continue;
+
+      formatted.unshift(
+        pendingSwapToFormattedTx(pendingTx, findToken, findChain),
+      );
+    }
+
+    return {
+      isLoading,
+      isError,
+      groups: groupAndSortByDay(formatted),
+    };
+    // `useQueries` returns a fresh outer array every render, so depending on
+    // `queries` directly would bust this memo on every render. Spreading the
+    // individual `q.data` refs sidesteps that — they're kept stable by
+    // React Query's structural sharing across renders when the data is equal.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    destinationToken,
+    addresses,
+    isPaymentMode,
+    paymentAmount,
+    destinationTokenDecimals,
+    findChain,
+    findToken,
+    pendingFromStore,
+    isLoading,
+    isError,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    ...queries.map((q) => q.data),
+  ]);
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { DepositWidget } from "./DepositWidget";
+export type { DepositConfig, WidgetView, WidgetViewId } from "./types";
+export type { Theme, ThemeType } from "@0xsquid/ui";

package/src/services/assets-service.ts

@@ -0,0 +1,21 @@
+import type { Token } from "@0xsquid/squid-types";
+
+export type TokenWithBalance = Token & { balance: string };
+
+export function sortTokensByBalance(
+  tokens: TokenWithBalance[],
+): TokenWithBalance[] {
+  return tokens.toSorted((a, b) => {
+    const aUsd = +a.balance * +(a.usdPrice ?? 0);
+    const bUsd = +b.balance * +(b.usdPrice ?? 0);
+    if (aUsd !== bUsd) return bUsd - aUsd;
+    return +(b.balance ?? 0) - +(a.balance ?? 0);
+  });
+}
+
+export function filterTokensByChain(
+  tokens: TokenWithBalance[],
+  chainId: string | null,
+): TokenWithBalance[] {
+  return chainId ? tokens.filter((token) => token.chainId === chainId) : tokens;
+}

package/src/services/wallet-history/format.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { groupAndSortByDay } from "./format";
+import type { FormattedTx } from "./types";
+
+function makeTx(id: string, timestamp: string): FormattedTx {
+  return {
+    id,
+    timestamp,
+    status: "success",
+    fromAmount: "1",
+    toAmount: "1",
+    fromToken: { symbol: "USDC", logo: "" },
+    fromChain: { logo: "" },
+    toToken: { symbol: "USDC" },
+  };
+}
+
+describe("groupAndSortByDay", () => {
+  it("returns an empty array when given no transactions", () => {
+    expect(groupAndSortByDay([])).toEqual([]);
+  });
+
+  it("groups transactions into buckets keyed by UTC YYYY-MM-DD", () => {
+    const groups = groupAndSortByDay([
+      makeTx("a", "2026-04-14T10:00:00.000Z"),
+      makeTx("b", "2026-04-14T23:59:00.000Z"),
+      makeTx("c", "2026-04-13T12:00:00.000Z"),
+    ]);
+
+    expect(groups.map((g) => g.day)).toEqual(["2026-04-14", "2026-04-13"]);
+    expect(groups[0]!.transactions.map((t) => t.id)).toEqual(["b", "a"]);
+    expect(groups[1]!.transactions.map((t) => t.id)).toEqual(["c"]);
+  });
+
+  it("sorts day groups newest-first", () => {
+    const groups = groupAndSortByDay([
+      makeTx("old", "2026-01-01T00:00:00.000Z"),
+      makeTx("new", "2026-04-14T00:00:00.000Z"),
+      makeTx("mid", "2026-03-10T00:00:00.000Z"),
+    ]);
+
+    expect(groups.map((g) => g.day)).toEqual([
+      "2026-04-14",
+      "2026-03-10",
+      "2026-01-01",
+    ]);
+  });
+
+  it("sorts transactions within a day newest-first", () => {
+    const groups = groupAndSortByDay([
+      makeTx("morning", "2026-04-14T08:00:00.000Z"),
+      makeTx("evening", "2026-04-14T20:00:00.000Z"),
+      makeTx("noon", "2026-04-14T12:00:00.000Z"),
+    ]);
+
+    expect(groups).toHaveLength(1);
+    expect(groups[0]!.transactions.map((t) => t.id)).toEqual([
+      "evening",
+      "noon",
+      "morning",
+    ]);
+  });
+});

package/src/services/wallet-history/format.ts

@@ -0,0 +1,128 @@
+import {
+  formatTokenAmount,
+  formatBNToReadable,
+  getTokenImage,
+  type SwapTransactionHistory,
+} from "@0xsquid/react-hooks";
+import type { ChainData, Token } from "@0xsquid/squid-types";
+import { getMainExplorerUrl } from "./get-main-explorer-url";
+import type { FormattedTx, SquidTransaction, TransactionStatus } from "./types";
+
+export interface DayGroup {
+  day: string; // YYYY-MM-DD
+  transactions: FormattedTx[];
+}
+
+function formatAmount(raw: string, decimals: number): string {
+  const readable = formatBNToReadable(raw, decimals);
+  return formatTokenAmount(readable, { compact: true });
+}
+
+// Maps react-hooks' TransactionStatus (+ error variants) to our 3-state display.
+function mapLocalStatusToDisplayStatus(status: string): TransactionStatus {
+  if (status === "success" || status === "partial_success") return "success";
+  if (status === "refunded" || status === "error") return "refunded";
+  return "ongoing";
+}
+
+function fallbackId(tx: SquidTransaction): string {
+  const { estimate } = tx.quote.route;
+  return `${tx.createdAt}-${estimate.fromToken.address}-${estimate.toToken.address}-${estimate.fromAmount}`;
+}
+
+export function toFormattedTx(
+  tx: SquidTransaction,
+  sourceChain: ChainData | undefined,
+): FormattedTx {
+  const { estimate } = tx.quote.route;
+  const { fromToken, toToken } = estimate;
+
+  return {
+    id: tx.transactionId ?? fallbackId(tx),
+    timestamp: tx.createdAt,
+    status: tx.statusResponse.squidTransactionStatus,
+    fromAmount: formatAmount(estimate.fromAmount, fromToken.decimals),
+    toAmount: formatAmount(estimate.toAmount, toToken.decimals),
+    fromToken: {
+      symbol: fromToken.symbol,
+      logo: getTokenImage({
+        address: fromToken.address,
+        chainId: tx.fromChainId,
+      }),
+    },
+    fromChain: { logo: sourceChain?.chainIconURI ?? "" },
+    toToken: { symbol: toToken.symbol },
+    explorer: getMainExplorerUrl({
+      transactionId: tx.transactionId,
+      routeType: tx.routeType,
+      sourceTxExplorerUrl: tx.sourceTxExplorerUrl,
+      statusResponse: tx.statusResponse,
+      actions: tx.actions,
+      sourceChain,
+    }),
+  };
+}
+
+export function pendingSwapToFormattedTx(
+  pending: SwapTransactionHistory,
+  findToken: (address?: string, chainId?: string) => Token | undefined,
+  findChain: (chainId: string | undefined) => ChainData | undefined,
+): FormattedTx {
+  const fromTokenMeta = findToken(pending.fromToken, pending.fromChain);
+  const toTokenMeta = findToken(pending.toToken, pending.toChain);
+
+  const fromReadable = fromTokenMeta
+    ? formatBNToReadable(pending.fromAmount, fromTokenMeta.decimals)
+    : pending.fromAmount;
+  const toReadable = toTokenMeta
+    ? formatBNToReadable(pending.toAmount, toTokenMeta.decimals)
+    : pending.toAmount;
+
+  return {
+    id: pending.transactionId,
+    timestamp: new Date(pending.timestamp).toISOString(),
+    status: mapLocalStatusToDisplayStatus(pending.status),
+    fromAmount: formatTokenAmount(fromReadable, { compact: true }),
+    toAmount: formatTokenAmount(toReadable, { compact: true }),
+    fromToken: {
+      symbol: fromTokenMeta?.symbol ?? "",
+      logo: getTokenImage({
+        address: pending.fromToken,
+        chainId: pending.fromChain,
+      }),
+    },
+    fromChain: { logo: findChain(pending.fromChain)?.chainIconURI ?? "" },
+    toToken: { symbol: toTokenMeta?.symbol ?? "" },
+    explorer: getMainExplorerUrl({
+      transactionId: pending.transactionId,
+      routeType: pending.routeType,
+      sourceTxExplorerUrl: pending.sourceTxExplorerUrl,
+      statusResponse: pending.statusResponse,
+      actions: pending.actions,
+      sourceChain: findChain(pending.fromChain),
+    }),
+  };
+}
+
+export function groupAndSortByDay(txs: FormattedTx[]): DayGroup[] {
+  const byDay = new Map<string, FormattedTx[]>();
+
+  for (const tx of txs) {
+    const dayKey = new Date(tx.timestamp).toISOString().slice(0, 10);
+    const bucket = byDay.get(dayKey) ?? [];
+    bucket.push(tx);
+    byDay.set(dayKey, bucket);
+  }
+
+  const groups: DayGroup[] = [];
+  for (const [day, transactions] of byDay.entries()) {
+    transactions.sort(
+      (a, b) =>
+        new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime(),
+    );
+    groups.push({ day, transactions });
+  }
+
+  groups.sort((a, b) => new Date(b.day).getTime() - new Date(a.day).getTime());
+  return groups;
+}

package/src/services/wallet-history/get-main-explorer-url.ts

@@ -0,0 +1,74 @@
+import { isChainflipBridgeTransaction } from "@0xsquid/react-hooks";
+import type { ChainData } from "@0xsquid/squid-types";
+import type { RouteAction } from "./types";
+
+// Ported from squid-widget's getMainExplorerUrl (richer than the one in @0xsquid/react-hooks).
+// Source: squid-widget repo — packages/widget/src/widget/services/internal/transactionService.ts
+// TODO: consolidate into @0xsquid/react-hooks when that version picks up coral + chainflip support.
+
+export interface ExplorerStatusResponse {
+  coralTransactionUrl?: string;
+  axelarTransactionUrl?: string;
+  transactionUrl?: string;
+  toChain?: { transactionUrl?: string };
+}
+
+export interface ExplorerInput {
+  transactionId?: string;
+  routeType?: string;
+  sourceTxExplorerUrl?: string;
+  statusResponse?: ExplorerStatusResponse;
+  actions?: RouteAction[];
+  sourceChain?: ChainData | undefined;
+}
+
+export interface MainExplorer {
+  url: string;
+  name: string;
+}
+
+export function getMainExplorerUrl(
+  transaction: ExplorerInput,
+): MainExplorer | undefined {
+  if (transaction.statusResponse?.coralTransactionUrl) {
+    return {
+      url: transaction.statusResponse.coralTransactionUrl,
+      name: "Squidscan",
+    };
+  }
+
+  if (transaction.statusResponse?.axelarTransactionUrl) {
+    return {
+      url: transaction.statusResponse.axelarTransactionUrl,
+      name: "Axelarscan",
+    };
+  }
+
+  const chainflipScanUrl = transaction.statusResponse?.toChain?.transactionUrl;
+  if (
+    chainflipScanUrl &&
+    isChainflipBridgeTransaction(transaction.actions ?? [])
+  ) {
+    return { url: chainflipScanUrl, name: "Chainflip" };
+  }
+
+  if (transaction.sourceTxExplorerUrl) {
+    return {
+      url: transaction.sourceTxExplorerUrl,
+      name: transaction.sourceChain?.networkName
+        ? `${transaction.sourceChain.networkName} explorer`
+        : "Source explorer",
+    };
+  }
+
+  if (transaction.statusResponse?.transactionUrl) {
+    return {
+      url: transaction.statusResponse.transactionUrl,
+      name: transaction.sourceChain?.networkName
+        ? `${transaction.sourceChain.networkName} explorer`
+        : "Source explorer",
+    };
+  }
+
+  return undefined;
+}

package/src/services/wallet-history/get-wallet-history.ts

@@ -0,0 +1,24 @@
+import type { SquidTransaction } from "./types";
+import { isSquidTransaction } from "./validation";
+
+export async function getWalletHistory(
+  address: string,
+  integratorId: string,
+  apiUrl: string,
+): Promise<SquidTransaction[]> {
+  const url = new URL("/v2/history/wallet", apiUrl);
+  url.searchParams.append("address", address);
+
+  const response = await fetch(url, {
+    headers: { "X-Integrator-Id": integratorId },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch wallet history: ${response.status}`);
+  }
+
+  const data: unknown = await response.json();
+  if (!Array.isArray(data)) return [];
+
+  return data.filter(isSquidTransaction);
+}

package/src/services/wallet-history/types.ts

@@ -0,0 +1,66 @@
+import type { isChainflipBridgeTransaction } from "@0xsquid/react-hooks";
+
+export type TransactionStatus = "ongoing" | "success" | "refunded";
+
+export type RouteAction = NonNullable<
+  Parameters<typeof isChainflipBridgeTransaction>[0]
+>[number];
+
+export interface SquidTransactionToken {
+  address: string;
+  symbol: string;
+  decimals: number;
+  chainId: string;
+}
+
+export interface SquidTransaction {
+  createdAt: string;
+  fromChainId: string;
+  toChainId: string;
+  transactionId?: string;
+  routeType?: string;
+  sourceTxExplorerUrl?: string;
+  actions?: RouteAction[];
+  quote: {
+    route: {
+      params?: {
+        toAddress?: string;
+        fromAmount?: string;
+        toAmount?: string;
+      };
+      estimate: {
+        fromAmount: string;
+        fromToken: SquidTransactionToken;
+        toAmount: string;
+        toToken: SquidTransactionToken;
+      };
+    };
+  };
+  statusResponse: {
+    squidTransactionStatus: TransactionStatus;
+    coralTransactionUrl?: string;
+    axelarTransactionUrl?: string;
+    transactionUrl?: string;
+    fromChain?: { transactionUrl?: string };
+    toChain?: { transactionUrl?: string };
+  };
+}
+
+export interface FormattedTx {
+  fromToken: {
+    symbol: string;
+    logo: string;
+  };
+  fromChain: {
+    logo: string;
+  };
+  toToken: {
+    symbol: string;
+  };
+  fromAmount: string;
+  toAmount: string;
+  timestamp: string;
+  status: TransactionStatus;
+  explorer?: { url: string; name: string };
+  id: string;
+}

package/src/services/wallet-history/validation.ts

@@ -0,0 +1,60 @@
+import type { SquidTransaction, TransactionStatus } from "./types";
+
+const VALID_STATUSES: Set<string> = new Set<TransactionStatus>([
+  "ongoing",
+  "success",
+  "refunded",
+]);
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isSquidTransactionToken(value: unknown): boolean {
+  if (!isObject(value)) return false;
+  return (
+    typeof value.address === "string" &&
+    typeof value.symbol === "string" &&
+    typeof value.decimals === "number" &&
+    typeof value.chainId === "string"
+  );
+}
+
+export function isSquidTransaction(tx: unknown): tx is SquidTransaction {
+  if (!isObject(tx)) return false;
+
+  if (
+    typeof tx.createdAt !== "string" ||
+    typeof tx.fromChainId !== "string" ||
+    typeof tx.toChainId !== "string"
+  ) {
+    return false;
+  }
+
+  if (!isObject(tx.quote)) return false;
+  const quote = tx.quote;
+  if (!isObject(quote.route)) return false;
+  const route = quote.route;
+  if (!isObject(route.estimate)) return false;
+  const estimate = route.estimate;
+
+  if (
+    typeof estimate.fromAmount !== "string" ||
+    typeof estimate.toAmount !== "string" ||
+    !isSquidTransactionToken(estimate.fromToken) ||
+    !isSquidTransactionToken(estimate.toToken)
+  ) {
+    return false;
+  }
+
+  if (!isObject(tx.statusResponse)) return false;
+  const status = tx.statusResponse;
+  if (
+    typeof status.squidTransactionStatus !== "string" ||
+    !VALID_STATUSES.has(status.squidTransactionStatus)
+  ) {
+    return false;
+  }
+
+  return true;
+}

package/src/store/use-deposit-store.ts

@@ -0,0 +1,20 @@
+import { create } from "zustand";
+import type { DepositConfig } from "../types";
+
+interface DepositState {
+  config: DepositConfig | null;
+  setConfig: (config: DepositConfig) => void;
+}
+
+export const useDepositStore = create<DepositState>((set) => ({
+  config: null,
+  setConfig: (config) => set({ config }),
+}));
+
+export const useIsPaymentMode = (): boolean =>
+  useDepositStore((s) => s.config?.mode === "payment");
+
+export const usePaymentAmount = (): string | null =>
+  useDepositStore((s) =>
+    s.config?.mode === "payment" ? s.config.amount : null,
+  );

package/src/store/use-input-mode.ts

@@ -0,0 +1,10 @@
+import { UserInputType } from "@0xsquid/ui";
+import { create } from "zustand";
+
+export const useInputMode = create<{
+  mode: UserInputType;
+  setMode: (_mode: UserInputType) => void;
+}>((set) => ({
+  mode: UserInputType.USD,
+  setMode: (mode) => set({ mode }),
+}));