@spacesops/wdk-react-native-core 1.0.0-beta.67 → 1.0.0-beta.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacesops/wdk-react-native-core",
-  "version": "1.0.0-beta.67",
+  "version": "1.0.0-beta.68",
   "description": "Core functionality for React Native wallets - wallet management, balance fetching, and worklet operations",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/utils/retryUtils.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Tests for retry utilities
+ */
+
+import {
+  delay,
+  isTransientBlockchainError,
+  withTransientRetry,
+} from '../../utils/retryUtils'
+
+describe('retryUtils', () => {
+  describe('isTransientBlockchainError', () => {
+    it('detects 429 rate limit errors', () => {
+      expect(isTransientBlockchainError(new Error('HTTP 429 Too Many Requests'))).toBe(true)
+      expect(isTransientBlockchainError(new Error('rate limit exceeded'))).toBe(true)
+    })
+
+    it('detects 5xx server errors', () => {
+      expect(isTransientBlockchainError(new Error('upstream returned 502 Bad Gateway'))).toBe(true)
+      expect(isTransientBlockchainError(new Error('status 503'))).toBe(true)
+    })
+
+    it('detects network and timeout errors', () => {
+      expect(isTransientBlockchainError(new Error('network request failed'))).toBe(true)
+      expect(isTransientBlockchainError(new Error('ETIMEDOUT'))).toBe(true)
+      expect(isTransientBlockchainError(new Error('408 Request Timeout'))).toBe(true)
+    })
+
+    it('does not treat client errors as transient', () => {
+      expect(isTransientBlockchainError(new Error('Invalid balance format: abc'))).toBe(false)
+      expect(isTransientBlockchainError(new Error('HTTP 400 Bad Request'))).toBe(false)
+      expect(isTransientBlockchainError(new Error('HTTP 404 Not Found'))).toBe(false)
+    })
+  })
+
+  describe('withTransientRetry', () => {
+    beforeEach(() => {
+      jest.useFakeTimers()
+    })
+
+    afterEach(() => {
+      jest.useRealTimers()
+    })
+
+    it('returns immediately on success', async () => {
+      const fn = jest.fn().mockResolvedValue('ok')
+      await expect(withTransientRetry(fn)).resolves.toBe('ok')
+      expect(fn).toHaveBeenCalledTimes(1)
+    })
+
+    it('retries transient errors with exponential backoff', async () => {
+      const fn = jest
+        .fn()
+        .mockRejectedValueOnce(new Error('HTTP 429 Too Many Requests'))
+        .mockRejectedValueOnce(new Error('HTTP 429 Too Many Requests'))
+        .mockResolvedValue('ok')
+
+      const promise = withTransientRetry(fn, { label: 'test' })
+
+      await jest.advanceTimersByTimeAsync(1000)
+      await jest.advanceTimersByTimeAsync(2000)
+
+      await expect(promise).resolves.toBe('ok')
+      expect(fn).toHaveBeenCalledTimes(3)
+    })
+
+    it('does not retry non-transient errors', async () => {
+      const fn = jest.fn().mockRejectedValue(new Error('Invalid balance format'))
+      await expect(withTransientRetry(fn)).rejects.toThrow('Invalid balance format')
+      expect(fn).toHaveBeenCalledTimes(1)
+    })
+
+    it('throws after exhausting retries', async () => {
+      const fn = jest.fn().mockRejectedValue(new Error('HTTP 429'))
+      const promise = withTransientRetry(fn, { maxAttempts: 3, initialBackoffMs: 100 })
+
+      await jest.advanceTimersByTimeAsync(100)
+      await jest.advanceTimersByTimeAsync(200)
+
+      await expect(promise).rejects.toThrow('HTTP 429')
+      expect(fn).toHaveBeenCalledTimes(3)
+    })
+  })
+
+  describe('delay', () => {
+    beforeEach(() => {
+      jest.useFakeTimers()
+    })
+
+    afterEach(() => {
+      jest.useRealTimers()
+    })
+
+    it('resolves after the specified duration', async () => {
+      const promise = delay(500)
+      jest.advanceTimersByTime(500)
+      await expect(promise).resolves.toBeUndefined()
+    })
+  })
+})

package/src/hooks/useBalance.ts

@@ -54,8 +54,10 @@ import {
   NATIVE_TOKEN_KEY,
   DEFAULT_QUERY_STALE_TIME_MS,
   DEFAULT_QUERY_GC_TIME_MS,
+  BALANCE_FETCH_STAGGER_MS,
 } from '../utils/constants'
 import { logError } from '../utils/logger'
+import { delay, withTransientRetry } from '../utils/retryUtils'
 import { validateWalletParams } from '../utils/validation'
 import type { BalanceFetchResult, TokenConfigProvider } from '../types'
 
@@ -203,11 +205,17 @@ async function fetchBalance(
     const methodName = isNative ? ACCOUNT_METHOD_GET_BALANCE : ACCOUNT_METHOD_GET_TOKEN_BALANCE
     const methodArg = isNative ? null : tokenAddress
 
-    const balanceResult = await AccountService.callAccountMethod<string>(
-      network,
-      accountIndex,
-      methodName,
-      methodArg
+    const balanceResult = await withTransientRetry(
+      () =>
+        AccountService.callAccountMethod<string>(
+          network,
+          accountIndex,
+          methodName,
+          methodArg
+        ),
+      {
+        label: `${network} ${methodName}`,
+      }
     )
 
     // Convert to string (handles BigInt values)
@@ -335,23 +343,70 @@ function buildBalanceQueryKeys(
 }
 
 /**
- * Fetch balances for all query keys
+ * Group balance query keys by network, preserving first-seen network order.
+ */
+function groupQueryKeysByNetwork(
+  queryKeys: ReturnType<typeof balanceQueryKeys.byToken>[]
+): ReturnType<typeof balanceQueryKeys.byToken>[][] {
+  const networkOrder: string[] = []
+  const byNetwork = new Map<string, ReturnType<typeof balanceQueryKeys.byToken>[]>()
+
+  for (const queryKey of queryKeys) {
+    const { network } = validateQueryKeyStructure(queryKey)
+    if (!byNetwork.has(network)) {
+      networkOrder.push(network)
+      byNetwork.set(network, [])
+    }
+    byNetwork.get(network)!.push(queryKey)
+  }
+
+  return networkOrder.map((network) => byNetwork.get(network)!)
+}
+
+function balanceQueryKeyId(queryKey: ReturnType<typeof balanceQueryKeys.byToken>): string {
+  return queryKey.join('\0')
+}
+
+/**
+ * Fetch balances for all query keys, staggering per-network to avoid RPC bursts.
  */
 async function fetchBalancesForQueryKeys(
   queryKeys: ReturnType<typeof balanceQueryKeys.byToken>[],
   walletId: string
 ): Promise<BalanceFetchResult[]> {
-  return Promise.all(
-    queryKeys.map(async (queryKey) => {
-      const validated = validateQueryKeyStructure(queryKey)
-      return fetchBalance(
-        validated.network,
-        validated.accountIndex,
-        validated.tokenAddress,
-        walletId
-      )
-    })
-  )
+  if (queryKeys.length === 0) {
+    return []
+  }
+
+  const networkGroups = groupQueryKeysByNetwork(queryKeys)
+  const results = new Map<string, BalanceFetchResult>()
+  let isFirstNetwork = true
+
+  for (const keys of networkGroups) {
+    if (!isFirstNetwork) {
+      await delay(BALANCE_FETCH_STAGGER_MS)
+    }
+    isFirstNetwork = false
+
+    const networkResults = await Promise.all(
+      keys.map(async (queryKey) => {
+        const validated = validateQueryKeyStructure(queryKey)
+        const result = await fetchBalance(
+          validated.network,
+          validated.accountIndex,
+          validated.tokenAddress,
+          walletId
+        )
+        return { id: balanceQueryKeyId(queryKey), result }
+      })
+    )
+
+    for (const { id, result } of networkResults) {
+      results.set(id, result)
+    }
+  }
+
+  return queryKeys.map((queryKey) => results.get(balanceQueryKeyId(queryKey))!)
 }
 
 /**

package/src/utils/constants.ts

@@ -67,6 +67,22 @@ export const DEFAULT_QUERY_STALE_TIME_MS = 30 * 1000
  */
 export const DEFAULT_QUERY_GC_TIME_MS = 5 * 60 * 1000
 
+/**
+ * Delay between per-network balance fetches on wallet load (ms).
+ * Spreads RPC load across chains instead of firing every network at once.
+ */
+export const BALANCE_FETCH_STAGGER_MS = 400
+
+/**
+ * Max attempts for transient blockchain/RPC errors (429, 5xx, network timeouts).
+ */
+export const TRANSIENT_ERROR_MAX_ATTEMPTS = 3
+
+/**
+ * Initial backoff for transient error retries (ms); doubled on each attempt.
+ */
+export const TRANSIENT_ERROR_INITIAL_BACKOFF_MS = 1000
+
 /**
  * Allowed account methods whitelist
  * Only these methods can be called through AccountService for security

package/src/utils/retryUtils.ts

@@ -0,0 +1,77 @@
+/**
+ * Retry helpers for transient blockchain/RPC failures (429, 5xx, network errors).
+ */
+
+import {
+  TRANSIENT_ERROR_INITIAL_BACKOFF_MS,
+  TRANSIENT_ERROR_MAX_ATTEMPTS,
+} from './constants'
+import { getErrorMessage } from './errorUtils'
+import { log } from './logger'
+
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Whether an error is likely transient and worth retrying with backoff.
+ * Matches Spaces API retry rules: 429, 408, 5xx, and common network failures.
+ */
+export function isTransientBlockchainError(error: unknown): boolean {
+  const message = getErrorMessage(error).toLowerCase()
+
+  if (
+    message.includes('429') ||
+    message.includes('too many requests') ||
+    message.includes('rate limit') ||
+    message.includes('408') ||
+    message.includes('request timeout') ||
+    message.includes('etimedout') ||
+    message.includes('econnreset') ||
+    message.includes('econnrefused') ||
+    message.includes('network request failed') ||
+    message.includes('network error') ||
+    message.includes('socket hang up')
+  ) {
+    return true
+  }
+
+  return /\b5\d{2}\b/.test(message)
+}
+
+export interface WithTransientRetryOptions {
+  maxAttempts?: number
+  initialBackoffMs?: number
+  /** Label for retry log messages */
+  label?: string
+}
+
+/**
+ * Run an async function with exponential backoff on transient errors.
+ */
+export async function withTransientRetry<T>(
+  fn: () => Promise<T>,
+  options: WithTransientRetryOptions = {}
+): Promise<T> {
+  const maxAttempts = options.maxAttempts ?? TRANSIENT_ERROR_MAX_ATTEMPTS
+  const initialBackoffMs = options.initialBackoffMs ?? TRANSIENT_ERROR_INITIAL_BACKOFF_MS
+  const label = options.label ?? 'operation'
+
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+      if (!isTransientBlockchainError(error) || attempt >= maxAttempts) {
+        throw error
+      }
+      const backoffMs = initialBackoffMs * (1 << (attempt - 1))
+      log(`[Balance] ${label}: retry in ${backoffMs}ms (${attempt}/${maxAttempts})`)
+      await delay(backoffMs)
+    }
+  }
+
+  throw lastError
+}