feat: bridge reconciliation + USDT provisioning additions

dev/apollo-federation/supergraph.graphql

@@ -283,10 +283,12 @@ type BridgeCreateVirtualAccountPayload
 type BridgeExternalAccount
   @join__type(graph: PUBLIC)
 {
-  accountNumberLast4: String!
-  bankName: String!
-  id: ID!
-  status: String!
+  accountNumberLast4: String
+  bankName: String
+  expiresAt: Timestamp
+  id: ID
+  linkUrl: String
+  status: String
 }
 
 input BridgeInitiateKycInput

dev/bruno/Flash GraphQL API/environments/local.bru

@@ -8,6 +8,6 @@ vars {
   token:
   walletId:
   walletIdUsd: c593736e-5a58-42e4-93fa-dc895856c1f1
-  userEmail: maurienteso@gmail.com
-  userFullName: maurienteso
+  userEmail: mauriente@gmail.com
+  userFullName: maurientes
 }

src/app/authentication/login.ts

@@ -309,7 +309,10 @@ export const loginDeviceUpgradeWithPhone = async ({
   if (deviceWallets instanceof Error) return deviceWallets
   let deviceAccountHasBalance = false
   for (const wallet of deviceWallets) {
-    const balance = await getBalanceForWallet({ walletId: wallet.id })
+    const balance = await getBalanceForWallet({
+      walletId: wallet.id,
+      currency: wallet.currency,
+    })
     if (balance instanceof Error) return balance
     if (!balance.isZero()) {
       deviceAccountHasBalance = true

src/domain/pubsub/index.ts

@@ -5,6 +5,7 @@ export const PubSubDefaultTriggers = {
   UserPriceUpdate: "USER_PRICE_UPDATE",
   AccountUpdate: "ACCOUNT_UPDATE",
   LnPaymentStatus: "LN_PAYMENT_STATUS",
+  BridgeReconciliationUpdate: "BRIDGE_RECONCILIATION_UPDATE",
 } as const
 
 export const customPubSubTrigger = ({

src/graphql/admin/queries.ts

@@ -15,6 +15,7 @@ import AccountDetailsByAccountId from "./root/query/account-details-by-account-i
 import MerchantsPendingApprovalQuery from "./root/query/merchants-pending-approval-listing"
 import IdDocumentReadUrlQuery from "./root/query/id-document-read-url"
 import NotificationTopicsQuery from "./root/query/notification-topics"
+import BridgeReconciliationOrphansQuery from "./root/query/bridge-reconciliation-orphans"
 
 export const queryFields = {
   unauthed: {},
@@ -34,6 +35,7 @@ export const queryFields = {
     merchantsPendingApproval: MerchantsPendingApprovalQuery,
     idDocumentReadUrl: IdDocumentReadUrlQuery,
     notificationTopics: NotificationTopicsQuery,
+    bridgeReconciliationOrphans: BridgeReconciliationOrphansQuery,
   },
 }
 

src/graphql/admin/root/query/bridge-reconciliation-orphans.ts

@@ -0,0 +1,40 @@
+import { GT } from "@graphql/index"
+import BridgeReconciliationOrphanObject from "@graphql/admin/types/object/bridge-reconciliation-orphan"
+import { findOrphans } from "@services/mongoose/bridge-reconciliation-orphan"
+
+const BridgeReconciliationOrphansQuery = GT.Field({
+  type: GT.NonNullList(BridgeReconciliationOrphanObject),
+  args: {
+    status: { type: GT.String, defaultValue: null },
+    orphanType: { type: GT.String, defaultValue: null },
+    limit: { type: GT.Int, defaultValue: 50 },
+  },
+  resolve: async (
+    _: unknown,
+    {
+      status,
+      orphanType,
+      limit,
+    }: { status?: string; orphanType?: string; limit?: number },
+  ) => {
+    const result = await findOrphans({
+      status: status as "unmatched" | "resolved" | undefined,
+      orphanType: orphanType as
+        | "bridge_without_ibex"
+        | "ibex_without_bridge"
+        | undefined,
+      limit: limit ?? 50,
+    })
+
+    if (result instanceof Error) throw result
+
+    return result.map((o) => ({
+      ...o,
+      detectedAt: o.detectedAt.toISOString(),
+      resolvedAt: o.resolvedAt?.toISOString() ?? null,
+      triageContext: JSON.stringify(o.triageContext),
+    }))
+  },
+})
+
+export default BridgeReconciliationOrphansQuery

src/graphql/admin/schema.graphql

@@ -319,6 +319,7 @@ type Query {
   accountDetailsByUserPhone(phone: Phone!): AuditedAccount!
   accountDetailsByUsername(username: Username!): AuditedAccount!
   allLevels: [AccountLevel!]!
+  bridgeReconciliationOrphans(status: String, orphanType: String, limit: Int): [BridgeReconciliationOrphan!]!
   idDocumentReadUrl(
     """Storage key of the ID document file"""
     fileKey: String!
@@ -618,4 +619,19 @@ enum WalletCurrency {
 }
 
 """Unique identifier of a wallet"""
-scalar WalletId
+scalar WalletId
+
+type BridgeReconciliationOrphan {
+  id: ID!
+  orphanKey: String!
+  orphanType: String!
+  status: String!
+  txHash: String
+  transferId: String
+  customerId: String
+  amount: String
+  currency: String
+  detectedAt: String!
+  resolvedAt: String
+  triageContext: String!
+}

src/graphql/admin/types/index.ts

@@ -1,5 +1,6 @@
 import BtcWallet from "@graphql/shared/types/object/btc-wallet"
 import GraphQLApplicationError from "@graphql/shared/types/object/graphql-application-error"
 import UsdWallet from "@graphql/shared/types/object/usd-wallet"
+import UsdtWallet from "@graphql/shared/types/object/usdt-wallet"
 
-export const ALL_INTERFACE_TYPES = [GraphQLApplicationError, BtcWallet, UsdWallet]
+export const ALL_INTERFACE_TYPES = [GraphQLApplicationError, BtcWallet, UsdWallet, UsdtWallet]

src/graphql/admin/types/object/bridge-reconciliation-orphan.ts

@@ -0,0 +1,21 @@
+import { GT } from "@graphql/index"
+
+const BridgeReconciliationOrphanObject = GT.Object({
+  name: "BridgeReconciliationOrphan",
+  fields: () => ({
+    id: { type: GT.NonNullID },
+    orphanKey: { type: GT.NonNull(GT.String) },
+    orphanType: { type: GT.NonNull(GT.String) },
+    status: { type: GT.NonNull(GT.String) },
+    txHash: { type: GT.String },
+    transferId: { type: GT.String },
+    customerId: { type: GT.String },
+    amount: { type: GT.String },
+    currency: { type: GT.String },
+    detectedAt: { type: GT.NonNull(GT.String) },
+    resolvedAt: { type: GT.String },
+    triageContext: { type: GT.NonNull(GT.String) },
+  }),
+})
+
+export default BridgeReconciliationOrphanObject

src/graphql/public/root/mutation/onchain-payment-send-all.ts

@@ -10,7 +10,7 @@ import WalletId from "@graphql/shared/types/scalar/wallet-id"
 
 import { Wallets } from "@app"
 import { getBalanceForWallet } from "@app/wallets"
-import { USDAmount } from "@domain/shared"
+import { USDAmount, WalletCurrency } from "@domain/shared"
 
 const OnChainPaymentSendAllInput = GT.Input({
   name: "OnChainPaymentSendAllInput",
@@ -63,7 +63,10 @@ const OnChainPaymentSendAllMutation = GT.Field<
       return { errors: [{ message: speed.message }] }
     }
 
-    const amount = await getBalanceForWallet({ walletId })
+    const amount = await getBalanceForWallet({
+      walletId,
+      currency: WalletCurrency.Usd,
+    })
     if (amount instanceof Error) return amount
     if (!(amount instanceof USDAmount)) {
       return { errors: [{ message: "Onchain payments require a USD wallet" }] }

src/graphql/public/schema.graphql

@@ -254,10 +254,12 @@ type BridgeCreateVirtualAccountPayload {
 }
 
 type BridgeExternalAccount {
-  accountNumberLast4: String!
-  bankName: String!
-  id: ID!
-  status: String!
+  accountNumberLast4: String
+  bankName: String
+  expiresAt: Timestamp
+  id: ID
+  linkUrl: String
+  status: String
 }
 
 input BridgeInitiateKycInput {

src/graphql/shared/types/object/btc-wallet.ts

@@ -52,7 +52,10 @@ const BtcWallet = GT.Object<Wallet>({
       description: "A balance stored in BTC.",
       resolve: async (source) => {
         if (source.type === WalletType.External) return null
-        const balanceSats = await Wallets.getBalanceForWallet({ walletId: source.id })
+        const balanceSats = await Wallets.getBalanceForWallet({
+          walletId: source.id,
+          currency: source.currency,
+        })
         if (balanceSats instanceof Error) {
           throw mapError(balanceSats)
         }

src/scripts/reconcile-bridge-ibex-deposits.ts

@@ -9,14 +9,14 @@ import { reconcileBridgeAndIbexDeposits } from "@services/bridge/reconciliation"
 const args = yargs(hideBin(process.argv))
   .option("window-hours", {
     type: "number",
-    default: 24,
-    describe: "Reconciliation window in hours",
+    default: 0.25,
+    describe: "Reconciliation window in hours (default: 15 minutes)",
   })
   .option("configPath", { type: "string", demandOption: true })
   .parseSync()
 
 const main = async () => {
-  const windowMs = Math.max(1, Math.floor(args["window-hours"])) * 60 * 60 * 1000
+  const windowMs = args["window-hours"] * 60 * 60 * 1000
   const result = await reconcileBridgeAndIbexDeposits({ windowMs })
   if (result instanceof Error) throw result
   baseLogger.info(result, "Bridge↔IBEX reconciliation finished")

src/servers/cron.ts

@@ -65,10 +65,14 @@ const swapOutJob = async () => {
   if (swapResult instanceof Error) throw swapResult
 }
 
+// Window covers 15 min of events — real-time webhook reconciliation handles everything
+// else immediately. This batch pass is only a safety net for missed/delayed webhooks.
+const RECONCILE_WINDOW_MS = 15 * 60 * 1000
+
 const reconcileBridgeDepositsJob = async () => {
   if (!BridgeConfig.enabled) return
 
-  const result = await reconcileBridgeAndIbexDeposits()
+  const result = await reconcileBridgeAndIbexDeposits({ windowMs: RECONCILE_WINDOW_MS })
   if (result instanceof Error) throw result
 }
 

src/services/bridge/index.ts

@@ -17,6 +17,7 @@ import { RepositoryError } from "@domain/errors"
 import { toBridgeCustomerId } from "@domain/primitives/bridge"
 import { getBalanceForWallet } from "@app/wallets/get-balance-for-wallet"
 import { USDTAmount, WalletCurrency } from "@domain/shared"
+import { WalletType } from "@domain/wallets"
 import { WalletsRepository } from "@services/mongoose/wallets"
 
 import { IdentityRepository } from "@services/kratos"
@@ -91,6 +92,38 @@ type ExternalAccountResult = {
 export const deriveWithdrawalIdempotencyKey = (rowId: string): string =>
   crypto.createHash("sha256").update(`withdrawal:${rowId}`).digest("hex")
 
+const ensureEthUsdtCashWallet = async (
+  account: Account,
+): Promise<Wallet | ApplicationError> => {
+  const wallets = await WalletsRepository().listByAccountId(account.id)
+  if (wallets instanceof Error) return wallets
+
+  let usdtWallet = wallets.find(
+    (wallet) =>
+      wallet.currency === WalletCurrency.Usdt && wallet.type === WalletType.Checking,
+  )
+
+  if (!usdtWallet) {
+    const createdWallet = await WalletsRepository().persistNew({
+      accountId: account.id,
+      type: WalletType.Checking,
+      currency: WalletCurrency.Usdt,
+    })
+    if (createdWallet instanceof Error) return createdWallet
+    usdtWallet = createdWallet
+  }
+
+  if (account.defaultWalletId !== usdtWallet.id) {
+    const updatedAccount = await AccountsRepository().update({
+      ...account,
+      defaultWalletId: usdtWallet.id,
+    })
+    if (updatedAccount instanceof Error) return updatedAccount
+  }
+
+  return usdtWallet
+}
+
 // ============ Guards ============
 
 const checkBridgeEnabled = (): true | BridgeDisabledError => {
@@ -180,6 +213,16 @@ const initiateKyc = async ({
 
     return result
   } catch (error) {
+    const bridgeError = error as { statusCode?: number; response?: { existing_kyc_link?: { kyc_link: string; customer_id: string; tos_link: string } } }
+
+    if (bridgeError?.statusCode === 400 && bridgeError.response?.existing_kyc_link) {
+      return {
+        kycLink: bridgeError.response.existing_kyc_link.kyc_link,
+        customerId: bridgeError.response.existing_kyc_link.customer_id,
+        tosLink: bridgeError.response.existing_kyc_link.tos_link,
+      }
+    }
+
     baseLogger.error(
       { accountId, operation: "initiateKyc", error },
       "Bridge operation failed",
@@ -191,8 +234,9 @@ const initiateKyc = async ({
 /**
  * Creates a virtual account for receiving USD deposits
  * - Requires approved KYC
- * - Creates IBEX Tron USDT receive address
- * - Creates Bridge virtual account pointing to Tron address
+ * - Ensures an IBEX ETH-USDT Cash Wallet exists and is the account default
+ * - Creates IBEX Ethereum USDT receive address
+ * - Creates Bridge virtual account pointing to Ethereum address
  */
 const createVirtualAccount = async (
   accountId: AccountId,
@@ -227,7 +271,7 @@ const createVirtualAccount = async (
       return new BridgeKycPendingError("KYC not yet completed")
     }
 
-    // Idempotency guard: return the existing VA immediately without touching Bridge
+    // Idempotency guard first: do not mutate wallets/default when a VA already exists
     const existingVa = await BridgeAccountsRepo.findVirtualAccountByAccountId(
       accountId as string,
     )
@@ -241,26 +285,29 @@ const createVirtualAccount = async (
       }
     }
 
-    // Get or create Ethereum address
-    let ethereumAddress =
-      account.bridgeEthereumAddress || "0xaF095D35bfDd462165eA7eCF8AC75351a93d72bD"
+    const usdtCashWallet = await ensureEthUsdtCashWallet(account)
+    if (usdtCashWallet instanceof Error) return usdtCashWallet
+
+    // Get or create Ethereum USDT receive address for the ETH-USDT Cash Wallet
+    let ethereumAddress = account.bridgeEthereumAddress
 
     if (!ethereumAddress) {
-      const option = await IbexClient.getEthereumUsdtOption()
+      let option = await IbexClient.getEthereumUsdtOption()
       if (option instanceof Error) return new BridgeError(option.message)
 
+      option.name = `USDT-ETH ${account.username}-${crypto.randomBytes(4).toString("hex")}`
       const receiveInfo = await IbexClient.createCryptoReceiveInfo(
-        account.defaultWalletId as IbexAccountId,
+        usdtCashWallet.id as IbexAccountId,
         option,
       )
       if (receiveInfo instanceof Error) return new BridgeError(receiveInfo.message)
 
       const updateResult = await AccountsRepository().updateBridgeFields(accountId, {
-        bridgeEthereumAddress: receiveInfo.address,
+        bridgeEthereumAddress: receiveInfo.data.address,
       })
       if (updateResult instanceof Error) return updateResult
 
-      ethereumAddress = receiveInfo.address
+      ethereumAddress = receiveInfo.data.address
     }
 
     // Deterministic key so Bridge deduplicates on their side if two calls race past
@@ -407,7 +454,9 @@ const initiateWithdrawal = async (
 
     const wallets = await WalletsRepository().listByAccountId(accountId)
     if (wallets instanceof Error) return wallets
-    const usdtWallet = wallets.find((w) => w.currency === WalletCurrency.Usdt)
+    const usdtWallet = wallets.find(
+      (w) => w.currency === WalletCurrency.Usdt && w.type === WalletType.Checking,
+    )
     if (!usdtWallet) {
       return new BridgeInsufficientFundsError("No USDT wallet found on account")
     }