feat(cutover): prepare cash wallet migration for bridge

dev/apollo-federation/supergraph.graphql

@@ -343,6 +343,7 @@ type BridgeWithdrawal
   amount: String!
   createdAt: String!
   currency: String!
+  failureReason: String
   id: ID!
   status: String!
 }
@@ -501,6 +502,29 @@ type CashoutOffer
   walletId: WalletId!
 }
 
+type CashWalletCutover
+  @join__type(graph: PUBLIC)
+{
+  completedAt: Timestamp
+  cutoverVersion: Int!
+  pauseReason: String
+  pausedAt: Timestamp
+  runId: String
+  scheduledAt: Timestamp
+  startedAt: Timestamp
+  state: CashWalletCutoverState!
+  updatedAt: Timestamp!
+  updatedBy: String
+}
+
+enum CashWalletCutoverState
+  @join__type(graph: PUBLIC)
+{
+  COMPLETE @join__enumValue(graph: PUBLIC)
+  IN_PROGRESS @join__enumValue(graph: PUBLIC)
+  PRE @join__enumValue(graph: PUBLIC)
+}
+
 """(Positive) Cent amount (1/100 of a dollar)"""
 scalar CentAmount
   @join__type(graph: PUBLIC)
@@ -1651,6 +1675,7 @@ type Query
   btcPrice(currency: DisplayCurrency! = "USD"): Price @deprecated(reason: "Deprecated in favor of realtimePrice")
   btcPriceList(range: PriceGraphRange!): [PricePoint]
   businessMapMarkers: [MapMarker!]!
+  cashWalletCutover: CashWalletCutover!
   currencyList: [Currency!]!
   globals: Globals
   isFlashNpub(input: IsFlashNpubInput!): IsFlashNpubPayload
@@ -2039,7 +2064,7 @@ type UsdtWallet implements Wallet
   @join__type(graph: PUBLIC)
 {
   accountId: ID!
-  balance: FractionalCentAmount!
+  balance: FractionalCentAmount
   id: ID!
   isExternal: Boolean!
   lnurlp: Lnurl

src/app/cash-wallet-cutover/amount-conversion.ts

@@ -0,0 +1,54 @@
+import { InvalidCashWalletCutoverAmountError } from "./errors"
+
+const USDT_MICROS_PER_USD_CENT = 10_000n
+
+const parseNonNegativeInteger = (
+  value: string,
+): bigint | InvalidCashWalletCutoverAmountError => {
+  if (!/^\d+$/.test(value)) {
+    return new InvalidCashWalletCutoverAmountError(
+      `Invalid non-negative integer amount: ${value}`,
+    )
+  }
+  return BigInt(value)
+}
+
+export const usdCentsToUsdtMicros = (
+  usdCents: string,
+): string | InvalidCashWalletCutoverAmountError => {
+  const parsed = parseNonNegativeInteger(usdCents)
+  if (parsed instanceof Error) return parsed
+  return (parsed * USDT_MICROS_PER_USD_CENT).toString()
+}
+
+export const feeUsdCentsToUsdtMicros = usdCentsToUsdtMicros
+
+export const usdtMicrosToUsdCentsCeil = (
+  usdtMicros: string,
+): string | InvalidCashWalletCutoverAmountError => {
+  const parsed = parseNonNegativeInteger(usdtMicros)
+  if (parsed instanceof Error) return parsed
+  if (parsed === 0n) return "0"
+  return ((parsed + USDT_MICROS_PER_USD_CENT - 1n) / USDT_MICROS_PER_USD_CENT).toString()
+}
+
+export const destinationShortfallUsdtMicros = ({
+  targetUsdtMicros,
+  startingUsdtMicros,
+  currentUsdtMicros,
+}: {
+  targetUsdtMicros: string
+  startingUsdtMicros: string
+  currentUsdtMicros: string
+}): string | InvalidCashWalletCutoverAmountError => {
+  const target = parseNonNegativeInteger(targetUsdtMicros)
+  if (target instanceof Error) return target
+  const starting = parseNonNegativeInteger(startingUsdtMicros)
+  if (starting instanceof Error) return starting
+  const current = parseNonNegativeInteger(currentUsdtMicros)
+  if (current instanceof Error) return current
+
+  const received = current > starting ? current - starting : 0n
+  if (received >= target) return "0"
+  return (target - received).toString()
+}

src/app/cash-wallet-cutover/client-capability.ts

@@ -0,0 +1,37 @@
+export const CASH_WALLET_USDT_CLIENT_CAPABILITY = "cash-wallet-usdt-v1"
+
+export type CashWalletPresentation = "legacy_compat" | "usdt"
+
+export type CashWalletClientCapabilities = {
+  cashWalletPresentation: CashWalletPresentation
+  hasUsdtCashWalletSupport: boolean
+}
+
+export const DEFAULT_CASH_WALLET_CLIENT_CAPABILITIES: CashWalletClientCapabilities = {
+  cashWalletPresentation: "legacy_compat",
+  hasUsdtCashWalletSupport: false,
+}
+
+export const parseCashWalletClientCapabilities = (
+  headers: Record<string, unknown>,
+): CashWalletClientCapabilities => {
+  const values = Object.entries(headers).flatMap(([key, raw]) => {
+    if (key.toLowerCase() !== "x-flash-client-capabilities") return []
+    if (typeof raw === "string") return [raw]
+    if (Array.isArray(raw))
+      return raw.filter((value): value is string => typeof value === "string")
+    return []
+  })
+
+  const capabilities = values
+    .flatMap((value) => value.split(","))
+    .map((value) => value.trim().toLowerCase())
+
+  const hasUsdtCashWalletSupport = capabilities.includes(
+    CASH_WALLET_USDT_CLIENT_CAPABILITY,
+  )
+
+  if (!hasUsdtCashWalletSupport) return DEFAULT_CASH_WALLET_CLIENT_CAPABILITIES
+
+  return { cashWalletPresentation: "usdt", hasUsdtCashWalletSupport }
+}

src/app/cash-wallet-cutover/discovery.ts

@@ -0,0 +1,78 @@
+import { WalletCurrency } from "@domain/shared"
+import { WalletType } from "@domain/wallets"
+
+export type CashWalletCutoverDiscoveryStatus =
+  | "legacy_default"
+  | "already_usdt"
+  | "residual_legacy_usd"
+  | "missing_legacy_usd"
+  | "missing_destination_usdt"
+
+export type CashWalletCutoverDiscovery = {
+  status: CashWalletCutoverDiscoveryStatus
+  accountId: AccountId
+  accountUuid?: AccountUuid
+  legacyUsdWalletId?: WalletId
+  destinationUsdtWalletId?: WalletId
+  previousDefaultWalletId: WalletId
+}
+
+export const classifyCashWalletsForCutover = ({
+  account,
+  wallets,
+}: {
+  account: Account
+  wallets: Wallet[]
+}): CashWalletCutoverDiscovery => {
+  const legacyUsdWallet = wallets.find(
+    (wallet) =>
+      wallet.type === WalletType.Checking && wallet.currency === WalletCurrency.Usd,
+  )
+  const destinationUsdtWallet = wallets.find(
+    (wallet) =>
+      wallet.type === WalletType.Checking && wallet.currency === WalletCurrency.Usdt,
+  )
+
+  const base = {
+    accountId: account.id,
+    accountUuid: account.uuid,
+    legacyUsdWalletId: legacyUsdWallet?.id,
+    destinationUsdtWalletId: destinationUsdtWallet?.id,
+    previousDefaultWalletId: account.defaultWalletId,
+  }
+
+  if (!legacyUsdWallet) return { ...base, status: "missing_legacy_usd" }
+  if (!destinationUsdtWallet) return { ...base, status: "missing_destination_usdt" }
+
+  if (account.defaultWalletId === legacyUsdWallet.id) {
+    return { ...base, status: "legacy_default" }
+  }
+
+  if (account.defaultWalletId === destinationUsdtWallet.id) {
+    return { ...base, status: "already_usdt" }
+  }
+
+  return { ...base, status: "residual_legacy_usd" }
+}
+
+export const discoverCashWalletCutoverAccounts = async ({
+  accountsRepo,
+  walletsRepo,
+}: {
+  accountsRepo: Pick<IAccountsRepository, "listUnlockedAccounts">
+  walletsRepo: Pick<IWalletsRepository, "listByAccountId">
+}): Promise<CashWalletCutoverDiscovery[] | RepositoryError> => {
+  const accounts = accountsRepo.listUnlockedAccounts()
+  if (accounts instanceof Error) return accounts
+
+  const discoveries: CashWalletCutoverDiscovery[] = []
+
+  for await (const account of accounts) {
+    const wallets = await walletsRepo.listByAccountId(account.id)
+    if (wallets instanceof Error) return wallets
+
+    discoveries.push(classifyCashWalletsForCutover({ account, wallets }))
+  }
+
+  return discoveries
+}

src/app/cash-wallet-cutover/errors.ts

@@ -0,0 +1,11 @@
+import { DomainError, ValidationError } from "@domain/shared"
+
+export class InvalidCashWalletCutoverAmountError extends ValidationError {}
+export class InvalidCashWalletMigrationTransitionError extends ValidationError {}
+export class InvalidCashWalletCutoverStateTransitionError extends ValidationError {}
+export class CashWalletCutoverInProgressError extends ValidationError {}
+export class CashWalletMigrationFailedError extends DomainError {}
+export class CashWalletMissingLegacyUsdWalletError extends DomainError {}
+export class CashWalletMissingUsdtWalletError extends DomainError {}
+export class CashWalletCutoverPreflightError extends DomainError {}
+export class CashWalletCutoverTreasuryInsufficientBalanceError extends DomainError {}

src/app/cash-wallet-cutover/executor.ts

@@ -0,0 +1,39 @@
+type RunnableCashWalletMigrationStatus = Exclude<
+  CashWalletMigrationStatus,
+  | "complete"
+  | "failed"
+  | "requires_operator_review"
+  | "skipped_already_migrated"
+  | "rollback_started"
+  | "rolled_back"
+>
+
+type CashWalletMigrationStepHandler = (
+  migration: CashWalletMigration,
+) => Promise<CashWalletMigration | ApplicationError>
+
+export type CashWalletMigrationStepHandlers = Record<
+  RunnableCashWalletMigrationStatus,
+  CashWalletMigrationStepHandler
+>
+
+const terminalStatuses: CashWalletMigrationStatus[] = [
+  "complete",
+  "failed",
+  "requires_operator_review",
+  "skipped_already_migrated",
+  "rollback_started",
+  "rolled_back",
+]
+
+export const executeCashWalletMigrationStep = async ({
+  migration,
+  handlers,
+}: {
+  migration: CashWalletMigration
+  handlers: CashWalletMigrationStepHandlers
+}): Promise<CashWalletMigration | ApplicationError> => {
+  if (terminalStatuses.includes(migration.status)) return migration
+
+  return handlers[migration.status as RunnableCashWalletMigrationStatus](migration)
+}

src/app/cash-wallet-cutover/guard.ts

@@ -0,0 +1,77 @@
+import {
+  CashWalletCutoverInProgressError,
+  CashWalletMigrationFailedError,
+} from "./errors"
+import { CashWalletClientCapabilities } from "./client-capability"
+
+export { CashWalletCutoverInProgressError, CashWalletMigrationFailedError }
+
+export type CashWalletCutoverRoute = "legacy_usd" | "usdt"
+export type CashWalletCutoverPresentation = "legacy_usd" | "legacy_usd_compat" | "usdt"
+
+export type CashWalletCutoverDecision = {
+  presentation: CashWalletCutoverPresentation
+}
+
+const ACTIVE_STATUSES: CashWalletMigrationStatus[] = [
+  "started",
+  "provisioned",
+  "balance_read",
+  "invoice_created",
+  "balance_move_sending",
+  "balance_move_sent",
+  "balance_move_verified",
+  "fee_reimbursement_invoice_created",
+  "fee_reimbursement_sending",
+  "fee_reimbursed",
+  "pointer_flipped",
+  "rollback_started",
+]
+
+export const evaluateCashWalletCutoverGuard = ({
+  cutover,
+  migration,
+}: {
+  cutover: CashWalletCutoverConfig
+  migration?: CashWalletMigration | null
+}): { route: CashWalletCutoverRoute } | ApplicationError => {
+  if (cutover.state === "pre") return { route: "legacy_usd" }
+  if (cutover.state === "complete") return { route: "usdt" }
+
+  if (!migration || migration.status === "not_started") return { route: "legacy_usd" }
+  if (
+    migration.status === "complete" ||
+    migration.status === "skipped_already_migrated"
+  ) {
+    return { route: "usdt" }
+  }
+  if (migration.status === "failed" || migration.status === "requires_operator_review") {
+    return new CashWalletMigrationFailedError()
+  }
+  if (ACTIVE_STATUSES.includes(migration.status)) {
+    return new CashWalletCutoverInProgressError()
+  }
+
+  return { route: "legacy_usd" }
+}
+
+export const evaluateCashWalletCutoverPresentation = ({
+  cutover,
+  migration,
+  client,
+}: {
+  cutover: CashWalletCutoverConfig
+  migration?: CashWalletMigration | null
+  client: CashWalletClientCapabilities
+}): CashWalletCutoverDecision | ApplicationError => {
+  const guard = evaluateCashWalletCutoverGuard({ cutover, migration })
+  if (guard instanceof Error) return guard
+
+  if (guard.route === "legacy_usd") {
+    return { presentation: "legacy_usd" }
+  }
+
+  return {
+    presentation: client.hasUsdtCashWalletSupport ? "usdt" : "legacy_usd_compat",
+  }
+}