feat(LIVE-29443): add swap status wallet api

Author: philipptpunkt

libs/exchange-module/src/index.ts

@@ -12,6 +12,8 @@ import {
   SwapLiveError,
   type GetQuotesResponse,
   type GetQuotesWireArgs,
+  type GetTransactionStatusResponse,
+  type GetTransactionStatusWireArgs,
 } from "./types";
 
 export * from "./types";
@@ -187,6 +189,18 @@ export class ExchangeModule extends CustomModule {
     return this.request<GetQuotesWireArgs, GetQuotesResponse>("custom.exchange.getQuotes", params);
   }
 
+  /**
+   * Fetch swap transaction status from the Wallet API host.
+   */
+  async getTransactionStatus(
+    params: GetTransactionStatusWireArgs,
+  ): Promise<GetTransactionStatusResponse> {
+    return this.request<GetTransactionStatusWireArgs, GetTransactionStatusResponse>(
+      "custom.exchange.getTransactionStatus",
+      params,
+    );
+  }
+
   /**
    * Complete an exchange sell process by passing by the exchange content and its signature.
    * User will be prompted on its device to approve the sell exchange operation.

libs/exchange-module/src/types.ts

@@ -137,6 +137,43 @@ export type GetQuotesArgs = {
 
 export type GetQuotesWireArgs = Omit<GetQuotesArgs, "signal">;
 
+// Swap transaction status (`custom.exchange.getTransactionStatus`).
+
+export type TransactionStatusInput = {
+  swapId: string;
+  provider?: string;
+};
+
+export type TransactionStatusValue =
+  | "pending"
+  | "onhold"
+  | "expired"
+  | "finished"
+  | "refunded"
+  | "unknown";
+
+export type GetTransactionStatusArgs = TransactionStatusInput & {
+  signal?: AbortSignal;
+};
+
+export type GetTransactionStatusWireArgs = Omit<GetTransactionStatusArgs, "signal">;
+
+export type GetTransactionStatusResponse = {
+  kind: "swap";
+  swapId: string;
+  provider?: string;
+  status?: TransactionStatusValue;
+  finalAmount?: string;
+  fromAccountId?: string;
+  toAccountId?: string;
+  sentAmount?: string;
+  receivedAmount?: string;
+  feesAmount?: string;
+  operationHash?: string;
+  createdAt?: number;
+  providerRequired?: boolean;
+};
+
 export type TradeMethod = "fixed" | "float";
 
 export type ProviderTypes = "DEX" | "CEX";

libs/ledger-live-common/src/exchange/swap/types.ts

@@ -165,7 +165,7 @@ export type GetExchangeRates = (
   exchangeObject: ExchangeObject,
 ) => Promise<(ExchangeRate & { expirationDate?: Date })[]>;
 
-type ValidSwapStatus = "pending" | "onhold" | "expired" | "finished" | "refunded";
+type ValidSwapStatus = "pending" | "onhold" | "expired" | "finished" | "refunded" | "unknown";
 
 export type SwapStatusRequest = {
   provider: string;

libs/ledger-live-common/src/exchange/transactionStatus/fetchSwapStatus.test.ts

@@ -0,0 +1,58 @@
+import { getMultipleStatus } from "../swap/getStatus";
+import { fetchTransactionSwapStatus } from "./fetchSwapStatus";
+
+jest.mock("../swap/getStatus", () => ({
+  getMultipleStatus: jest.fn(),
+}));
+
+const mockGetMultipleStatus = getMultipleStatus as jest.MockedFunction<typeof getMultipleStatus>;
+
+describe("fetchTransactionSwapStatus", () => {
+  beforeEach(() => {
+    mockGetMultipleStatus.mockReset();
+  });
+
+  it("calls the batch status endpoint for a single swap id", async () => {
+    mockGetMultipleStatus.mockResolvedValueOnce([
+      { provider: "lifi", swapId: "swap-1", status: "finished" },
+    ]);
+
+    await expect(
+      fetchTransactionSwapStatus({ provider: "lifi", swapId: "swap-1" }),
+    ).resolves.toEqual({ provider: "lifi", swapId: "swap-1", status: "finished" });
+
+    expect(mockGetMultipleStatus).toHaveBeenCalledWith([
+      { provider: "lifi", swapId: "swap-1" },
+    ]);
+  });
+
+  it("forwards optional transaction and operation ids", async () => {
+    mockGetMultipleStatus.mockResolvedValueOnce([
+      { provider: "lifi", swapId: "swap-1", status: "pending" },
+    ]);
+
+    await fetchTransactionSwapStatus({
+      provider: "lifi",
+      swapId: "swap-1",
+      transactionId: "0xhash",
+      operationId: "operation-id",
+    });
+
+    expect(mockGetMultipleStatus).toHaveBeenCalledWith([
+      {
+        provider: "lifi",
+        swapId: "swap-1",
+        transactionId: "0xhash",
+        operationId: "operation-id",
+      },
+    ]);
+  });
+
+  it("returns undefined when the backend returns no row", async () => {
+    mockGetMultipleStatus.mockResolvedValueOnce([]);
+
+    await expect(
+      fetchTransactionSwapStatus({ provider: "lifi", swapId: "swap-1" }),
+    ).resolves.toBeUndefined();
+  });
+});

libs/ledger-live-common/src/exchange/transactionStatus/fetchSwapStatus.ts

@@ -0,0 +1,9 @@
+import { getMultipleStatus } from "../swap/getStatus";
+import type { SwapStatus, SwapStatusRequest } from "../swap/types";
+
+export async function fetchTransactionSwapStatus(
+  request: SwapStatusRequest,
+): Promise<SwapStatus | undefined> {
+  const [status] = await getMultipleStatus([request]);
+  return status;
+}

libs/ledger-live-common/src/exchange/transactionStatus/fromSwapOperation.test.ts

@@ -0,0 +1,37 @@
+import BigNumber from "bignumber.js";
+import type { Account, Operation } from "@ledgerhq/types-live";
+import type { MappedSwapOperation } from "../swap/types";
+import { fromSwapOperation } from "./fromSwapOperation";
+
+function makeAccount(id: string): Account {
+  return { type: "Account", id } as unknown as Account;
+}
+
+describe("fromSwapOperation", () => {
+  it("maps a swap-history operation to the reduced transaction status request", () => {
+    const operation = {
+      hash: "0xhash",
+      fee: new BigNumber("21000"),
+      date: new Date("2026-01-02T03:04:05.000Z"),
+    } as unknown as Operation;
+
+    const mapped: MappedSwapOperation = {
+      provider: "lifi",
+      swapId: "swap-1",
+      status: "finished",
+      fromAccount: makeAccount("from"),
+      toAccount: makeAccount("to"),
+      toExists: true,
+      operation,
+      fromAmount: new BigNumber("-100000"),
+      toAmount: new BigNumber("200000"),
+      finalAmount: new BigNumber("250000"),
+    };
+
+    expect(fromSwapOperation(mapped)).toEqual({
+      kind: "swap",
+      swapId: "swap-1",
+      provider: "lifi",
+    });
+  });
+});

libs/ledger-live-common/src/exchange/transactionStatus/fromSwapOperation.ts

@@ -0,0 +1,14 @@
+import type { MappedSwapOperation } from "../swap/types";
+import type { SwapTransactionStatusParams } from "./types";
+
+export function fromSwapOperation(
+  mappedSwapOperation: MappedSwapOperation,
+): SwapTransactionStatusParams {
+  const { provider, swapId } = mappedSwapOperation;
+
+  return {
+    kind: "swap",
+    swapId,
+    provider,
+  };
+}

libs/ledger-live-common/src/exchange/transactionStatus/index.ts

@@ -0,0 +1,5 @@
+export * from "./fetchSwapStatus";
+export * from "./fromSwapOperation";
+export * from "./parseParams";
+export * from "./statusController";
+export * from "./types";

libs/ledger-live-common/src/exchange/transactionStatus/parseParams.test.ts

@@ -0,0 +1,66 @@
+import {
+  parseSwapTransactionStatusParams,
+  sanitizeRedirectUrl,
+} from "./parseParams";
+
+describe("sanitizeRedirectUrl", () => {
+  it("keeps https and ledgerlive urls", () => {
+    expect(sanitizeRedirectUrl("https://ledger.com/swap")).toBe("https://ledger.com/swap");
+    expect(sanitizeRedirectUrl("ledgerlive://swap/history")).toBe("ledgerlive://swap/history");
+  });
+
+  it("drops unsafe or malformed urls", () => {
+    expect(sanitizeRedirectUrl("javascript:alert(1)")).toBeUndefined();
+    expect(sanitizeRedirectUrl("/relative")).toBeUndefined();
+    expect(sanitizeRedirectUrl("not a url")).toBeUndefined();
+  });
+});
+
+describe("parseSwapTransactionStatusParams", () => {
+  it("parses the minimal swap deeplink payload", () => {
+    expect(
+      parseSwapTransactionStatusParams({
+        swapId: "swap-1",
+        provider: "changelly_v2",
+      }),
+    ).toEqual({
+      ok: true,
+      params: {
+        kind: "swap",
+        swapId: "swap-1",
+        provider: "changelly_v2",
+        redirectUrl: undefined,
+      },
+    });
+  });
+
+  it("allows provider to be omitted and trims optional public fields", () => {
+    expect(
+      parseSwapTransactionStatusParams({
+        swapId: " swap-1 ",
+        redirectUrl: " https://example.com/continue ",
+      }),
+    ).toEqual({
+      ok: true,
+      params: {
+        kind: "swap",
+        swapId: "swap-1",
+        provider: undefined,
+        redirectUrl: "https://example.com/continue",
+      },
+    });
+  });
+
+  it("rejects missing required fields", () => {
+    expect(parseSwapTransactionStatusParams({ provider: "lifi" })).toMatchObject({
+      ok: false,
+      error: { code: "missing_swap_id" },
+    });
+  });
+
+  it("rejects unsupported kind", () => {
+    expect(
+      parseSwapTransactionStatusParams({ kind: "unknown" as never, swapId: "swap-1", provider: "lifi" }),
+    ).toMatchObject({ ok: false, error: { code: "unsupported_kind" } });
+  });
+});

libs/ledger-live-common/src/exchange/transactionStatus/parseParams.ts

@@ -0,0 +1,74 @@
+import type { SwapStatus } from "../swap/types";
+import type {
+  SwapTransactionStatusParseResult,
+  SwapTransactionStatusParamsError,
+  SwapTransactionStatusRawParams,
+} from "./types";
+
+const VALID_SWAP_STATUSES: ReadonlySet<SwapStatus["status"]> = new Set([
+  "pending",
+  "onhold",
+  "expired",
+  "finished",
+  "refunded",
+  "unknown",
+]);
+
+function error(
+  code: SwapTransactionStatusParamsError["code"],
+  message: string,
+  value?: string,
+): SwapTransactionStatusParseResult {
+  return { ok: false, error: { code, message, value } };
+}
+
+export function sanitizeRedirectUrl(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return undefined;
+  }
+
+  if (parsed.protocol !== "https:" && parsed.protocol !== "ledgerlive:") {
+    return undefined;
+  }
+  return trimmed;
+}
+
+export function isValidSwapStatus(status: string): status is SwapStatus["status"] {
+  return VALID_SWAP_STATUSES.has(status as SwapStatus["status"]);
+}
+
+export function parseSwapTransactionStatusParams(
+  raw: SwapTransactionStatusRawParams,
+): SwapTransactionStatusParseResult {
+  const kind = raw.kind ?? "swap";
+  if (kind !== "swap") {
+    return error("unsupported_kind", "Only swap transaction status is supported", kind);
+  }
+
+  const swapId = raw.swapId?.trim();
+  if (!swapId) {
+    return error("missing_swap_id", "Missing swapId", raw.swapId);
+  }
+
+  return {
+    ok: true,
+    params: {
+      kind,
+      swapId,
+      provider: optionalTrim(raw.provider),
+      redirectUrl: sanitizeRedirectUrl(raw.redirectUrl),
+    },
+  };
+}
+
+function optionalTrim(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}