feat(spark): add Stable Balance and BTC - USD conversion flow

__mocks__/@breeztech/breez-sdk-spark-react-native.js

@@ -70,7 +70,32 @@ module.exports = {
   Seed: { Mnemonic: jest.fn().mockImplementation((args) => args) },
   StableBalanceActiveLabel: {
     Set: jest.fn().mockImplementation((args) => ({ tag: "Set", inner: args })),
-    Unset: jest.fn().mockReturnValue({ tag: "Unset" }),
+    Unset: jest.fn().mockImplementation(() => ({ tag: "Unset" })),
+  },
+  ConversionType: {
+    FromBitcoin: jest.fn().mockImplementation(() => ({ tag: "FromBitcoin" })),
+    ToBitcoin: jest
+      .fn()
+      .mockImplementation((args) => ({ tag: "ToBitcoin", inner: args })),
+  },
+  AmountAdjustmentReason: {
+    FlooredToMinLimit: "FlooredToMinLimit",
+    IncreasedToAvoidDust: "IncreasedToAvoidDust",
+  },
+  PrepareSendPaymentRequest: { create: (p) => p },
+  SendPaymentRequest: { create: (p) => p },
+  ReceivePaymentRequest: { create: (p) => p },
+  ReceivePaymentMethod: {
+    SparkAddress: jest.fn().mockImplementation(() => ({ tag: "SparkAddress" })),
+    SparkInvoice: jest
+      .fn()
+      .mockImplementation((args) => ({ tag: "SparkInvoice", inner: args })),
+    Bolt11Invoice: jest
+      .fn()
+      .mockImplementation((args) => ({ tag: "Bolt11Invoice", inner: args })),
+    BitcoinAddress: jest
+      .fn()
+      .mockImplementation((args) => ({ tag: "BitcoinAddress", inner: args })),
   },
   SdkEvent_Tags,
   PaymentMethod: {

__tests__/components/balance-header/balance-header.spec.tsx

@@ -0,0 +1,125 @@
+import React from "react"
+import { fireEvent, render } from "@testing-library/react-native"
+import { ThemeProvider } from "@rn-vui/themed"
+
+import theme from "@app/rne-theme/theme"
+import { BalanceMode } from "@app/hooks/use-balance-mode"
+
+import { BalanceHeader } from "@app/components/balance-header/balance-header"
+
+const mockSwitchMemoryHideAmount = jest.fn()
+
+jest.mock("@app/graphql/hide-amount-context", () => ({
+  useHideAmount: () => ({
+    hideAmount: false,
+    switchMemoryHideAmount: mockSwitchMemoryHideAmount,
+  }),
+}))
+
+jest.mock("@app/i18n/i18n-react", () => ({
+  useI18nContext: () => ({
+    LL: {
+      StableBalance: {
+        balanceLabelBtc: () => "Balance · SATS",
+        balanceLabelUsd: () => "Balance · USD",
+      },
+      SelfCustodialBalance: {
+        staleLabel: () => "STALE",
+        staleRetryHint: () => "Balance may be out of date. Tap to refresh.",
+      },
+    },
+  }),
+}))
+
+const renderHeader = (props: Partial<React.ComponentProps<typeof BalanceHeader>> = {}) =>
+  render(
+    <ThemeProvider theme={theme}>
+      <BalanceHeader loading={false} formattedBalance="$10" {...props} />
+    </ThemeProvider>,
+  )
+
+describe("BalanceHeader", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it("renders the formatted balance", () => {
+    const { getByText } = renderHeader({ formattedBalance: "$42.00" })
+
+    expect(getByText("$42.00")).toBeTruthy()
+  })
+
+  it("does not render the Stable Balance toggle when showStableBalanceToggle is false", () => {
+    const { queryByTestId } = renderHeader({ showStableBalanceToggle: false })
+
+    expect(queryByTestId("balance-mode-toggle")).toBeNull()
+  })
+
+  it("renders the SATS label when mode is Btc and toggle is enabled", () => {
+    const onModeChange = jest.fn()
+    const { getByText } = renderHeader({
+      showStableBalanceToggle: true,
+      mode: BalanceMode.Btc,
+      onModeChange,
+    })
+
+    expect(getByText("Balance · SATS")).toBeTruthy()
+  })
+
+  it("renders the USD label when mode is Usd and toggle is enabled", () => {
+    const { getByText } = renderHeader({
+      showStableBalanceToggle: true,
+      mode: BalanceMode.Usd,
+      onModeChange: jest.fn(),
+    })
+
+    expect(getByText("Balance · USD")).toBeTruthy()
+  })
+
+  it("calls onModeChange when the toggle is pressed", () => {
+    const onModeChange = jest.fn()
+    const { getByTestId } = renderHeader({
+      showStableBalanceToggle: true,
+      mode: BalanceMode.Btc,
+      onModeChange,
+    })
+
+    fireEvent.press(getByTestId("balance-mode-toggle"))
+
+    expect(onModeChange).toHaveBeenCalledTimes(1)
+  })
+
+  it("hides the toggle when onModeChange is not provided even if the flag is true", () => {
+    const { queryByTestId } = renderHeader({
+      showStableBalanceToggle: true,
+      mode: BalanceMode.Btc,
+      onModeChange: undefined,
+    })
+
+    expect(queryByTestId("balance-mode-toggle")).toBeNull()
+  })
+
+  it("does not render the status badge by default", () => {
+    const { queryByTestId } = renderHeader()
+
+    expect(queryByTestId("balance-status-badge")).toBeNull()
+  })
+
+  it("renders the status badge with the given label and status when provided", () => {
+    const { getByTestId, getByText } = renderHeader({
+      statusBadge: { label: "STALE", status: "warning" },
+    })
+
+    expect(getByTestId("balance-status-badge")).toBeTruthy()
+    expect(getByText("STALE")).toBeTruthy()
+  })
+
+  it("does not render the status badge while loading (avoids flicker during initial load)", () => {
+    const { queryByTestId } = renderHeader({
+      statusBadge: { label: "STALE", status: "warning" },
+      loading: true,
+    })
+
+    expect(queryByTestId("balance-status-badge")).toBeNull()
+  })
+})

__tests__/components/stable-balance-first-time-modal.spec.tsx

@@ -0,0 +1,61 @@
+import React from "react"
+import { fireEvent, render } from "@testing-library/react-native"
+import { ThemeProvider } from "@rn-vui/themed"
+
+import theme from "@app/rne-theme/theme"
+
+import { StableBalanceFirstTimeModal } from "@app/components/stable-balance-first-time-modal"
+
+jest.mock("@app/i18n/i18n-react", () => ({
+  useI18nContext: () => ({
+    LL: {
+      StableBalance: {
+        firstTimeModal: {
+          title: () => "About Convert",
+          dualBalance: () => "BTC and USD are two independent balances.",
+          trustDisclosure: () => "USD mode uses USDB tokens on Spark.",
+          acknowledge: () => "I understand",
+        },
+      },
+    },
+  }),
+}))
+
+const renderModal = (
+  props: Partial<React.ComponentProps<typeof StableBalanceFirstTimeModal>> = {},
+) =>
+  render(
+    <ThemeProvider theme={theme}>
+      <StableBalanceFirstTimeModal isVisible onAcknowledge={jest.fn()} {...props} />
+    </ThemeProvider>,
+  )
+
+describe("StableBalanceFirstTimeModal", () => {
+  it("renders both explanation paragraphs when visible", () => {
+    const { getByText } = renderModal()
+
+    expect(getByText("BTC and USD are two independent balances.")).toBeTruthy()
+    expect(getByText("USD mode uses USDB tokens on Spark.")).toBeTruthy()
+  })
+
+  it("renders the acknowledge CTA text", () => {
+    const { getByText } = renderModal()
+
+    expect(getByText("I understand")).toBeTruthy()
+  })
+
+  it("exposes the modal testID for targeting from the Convert flow", () => {
+    const { getByTestId } = renderModal()
+
+    expect(getByTestId("stable-balance-first-time-modal")).toBeTruthy()
+  })
+
+  it("calls onAcknowledge when the CTA is tapped", () => {
+    const onAcknowledge = jest.fn()
+    const { getByText } = renderModal({ onAcknowledge })
+
+    fireEvent.press(getByText("I understand"))
+
+    expect(onAcknowledge).toHaveBeenCalledTimes(1)
+  })
+})

__tests__/components/status-pill.spec.tsx

@@ -0,0 +1,52 @@
+import React from "react"
+import { render } from "@testing-library/react-native"
+import { ThemeProvider } from "@rn-vui/themed"
+
+import theme from "@app/rne-theme/theme"
+import { StatusPill, type StatusPillVariant } from "@app/components/status-pill"
+
+const renderPill = (props: React.ComponentProps<typeof StatusPill>) =>
+  render(
+    <ThemeProvider theme={theme}>
+      <StatusPill {...props} />
+    </ThemeProvider>,
+  )
+
+describe("StatusPill", () => {
+  it("renders the provided label", () => {
+    const { getByText } = renderPill({ label: "STALE", status: "warning" })
+
+    expect(getByText("STALE")).toBeTruthy()
+  })
+
+  const VARIANTS: StatusPillVariant[] = ["warning", "error", "success", "primary"]
+
+  VARIANTS.forEach((variant) => {
+    it(`renders without crashing for variant ${variant}`, () => {
+      const { getByText } = renderPill({ label: "TAG", status: variant })
+
+      expect(getByText("TAG")).toBeTruthy()
+    })
+  })
+
+  it("exposes the testID when provided", () => {
+    const { getByTestId } = renderPill({
+      label: "STALE",
+      status: "warning",
+      testID: "balance-stale-pill",
+    })
+
+    expect(getByTestId("balance-stale-pill")).toBeTruthy()
+  })
+
+  it("hides itself from accessibility and ignores the testID when ghost", () => {
+    const { queryByTestId } = renderPill({
+      label: "STALE",
+      status: "warning",
+      ghost: true,
+      testID: "should-not-appear",
+    })
+
+    expect(queryByTestId("should-not-appear")).toBeNull()
+  })
+})

__tests__/custodial/adapters/payment-adapter.spec.ts

@@ -174,7 +174,8 @@ describe("createCustodialClaimDeposit", () => {
 describe("createCustodialConvert", () => {
   it("returns failed status", async () => {
     const result = await createCustodialConvert({
-      amount: { amount: 1000, currency: WalletCurrency.Btc, currencyCode: "BTC" },
+      fromAmount: { amount: 1000, currency: WalletCurrency.Btc, currencyCode: "BTC" },
+      toAmount: { amount: 0, currency: WalletCurrency.Usd, currencyCode: "USD" },
       direction: ConvertDirection.BtcToUsd,
     })
 

__tests__/hooks/use-balance-mode.spec.ts

@@ -0,0 +1,90 @@
+import { act, renderHook, waitFor } from "@testing-library/react-native"
+
+import { BalanceMode, useBalanceMode } from "@app/hooks/use-balance-mode"
+
+const mockGetItem = jest.fn()
+const mockSetItem = jest.fn()
+
+jest.mock("@react-native-async-storage/async-storage", () => ({
+  __esModule: true,
+  default: {
+    getItem: (...args: unknown[]) => mockGetItem(...args),
+    setItem: (...args: unknown[]) => mockSetItem(...args),
+  },
+}))
+
+describe("useBalanceMode", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    mockGetItem.mockResolvedValue(null)
+    mockSetItem.mockResolvedValue(undefined)
+  })
+
+  it("defaults to BTC when nothing has been persisted", async () => {
+    const { result } = renderHook(() => useBalanceMode())
+
+    await waitFor(() => {
+      expect(result.current.loaded).toBe(true)
+    })
+    expect(result.current.mode).toBe(BalanceMode.Btc)
+  })
+
+  it("restores a previously persisted USD mode on mount", async () => {
+    mockGetItem.mockResolvedValue(BalanceMode.Usd)
+
+    const { result } = renderHook(() => useBalanceMode())
+
+    await waitFor(() => {
+      expect(result.current.mode).toBe(BalanceMode.Usd)
+    })
+  })
+
+  it("ignores corrupted storage values and keeps the default", async () => {
+    mockGetItem.mockResolvedValue("garbage")
+
+    const { result } = renderHook(() => useBalanceMode())
+
+    await waitFor(() => {
+      expect(result.current.loaded).toBe(true)
+    })
+    expect(result.current.mode).toBe(BalanceMode.Btc)
+  })
+
+  it("persists a mode change via setMode", async () => {
+    const { result } = renderHook(() => useBalanceMode())
+    await waitFor(() => expect(result.current.loaded).toBe(true))
+
+    act(() => {
+      result.current.setMode(BalanceMode.Usd)
+    })
+
+    expect(result.current.mode).toBe(BalanceMode.Usd)
+    expect(mockSetItem).toHaveBeenCalledWith("selfCustodialBalanceMode", "usd")
+  })
+
+  it("toggleMode flips BTC → USD → BTC and persists each change", async () => {
+    const { result } = renderHook(() => useBalanceMode())
+    await waitFor(() => expect(result.current.loaded).toBe(true))
+
+    act(() => {
+      result.current.toggleMode()
+    })
+    expect(result.current.mode).toBe(BalanceMode.Usd)
+    expect(mockSetItem).toHaveBeenLastCalledWith("selfCustodialBalanceMode", "usd")
+
+    act(() => {
+      result.current.toggleMode()
+    })
+    expect(result.current.mode).toBe(BalanceMode.Btc)
+    expect(mockSetItem).toHaveBeenLastCalledWith("selfCustodialBalanceMode", "btc")
+  })
+
+  it("survives an AsyncStorage read failure without crashing", async () => {
+    mockGetItem.mockRejectedValue(new Error("storage down"))
+
+    const { result } = renderHook(() => useBalanceMode())
+
+    await waitFor(() => expect(result.current.loaded).toBe(true))
+    expect(result.current.mode).toBe(BalanceMode.Btc)
+  })
+})