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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacesops/wdk-react-native-core",
-  "version": "1.0.0-beta.66",
+  "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/__tests__/utils/typeGuards.test.ts

@@ -13,6 +13,7 @@ import {
   isValidAccountIndex,
   isValidNetworkName,
   isValidBalanceString,
+  isValidAddress,
 } from '../../utils/typeGuards'
 import type { NetworkConfig, NetworkConfigs, TokenConfig, TokenConfigs } from '../../types'
 
@@ -160,6 +161,14 @@ describe('typeGuards', () => {
     })
   })
 
+  describe('isValidAddress', () => {
+    it('should accept TON, Tron, and Solana wallet addresses', () => {
+      expect(isValidAddress('UQCt4XDZ_rgMu14lE5ENox6yqHxx3c9df-gHLynhEEKbTRV0')).toBe(true)
+      expect(isValidAddress('TVKDsaESudgCQReXPNvStw2n2BXnmodyeC')).toBe(true)
+      expect(isValidAddress('Ed9f9Koh6rqMvFXccVJp5bNuxFs8rYdbVibW9JXRskLU')).toBe(true)
+    })
+  })
+
   describe('isValidAccountIndex', () => {
     it('should return true for valid account indices', () => {
       expect(isValidAccountIndex(0)).toBe(true)

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/index.ts

@@ -62,6 +62,9 @@ export {
   balanceStringSchema,
   ethereumAddressSchema,
   tokenContractAddressSchema,
+  tonAddressSchema,
+  tronAddressSchema,
+  solanaAddressSchema,
   sparkAddressSchema,
   bitcoinAddressSchema,
   addressSchema,

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
+}

package/src/utils/schemas.ts

@@ -49,9 +49,37 @@ export const bitcoinAddressSchema = z.string().regex(
 )
 
 /**
- * Address schema (Ethereum, Spark, or Bitcoin)
+ * TON user-friendly wallet address (EQ/UQ + base64url).
  */
-export const addressSchema = z.union([ethereumAddressSchema, sparkAddressSchema, bitcoinAddressSchema])
+export const tonAddressSchema = z.string().regex(/^(EQ|UQ)[A-Za-z0-9_-]{46}$/, {
+  message: 'Must be a valid TON address (EQ/UQ user-friendly format)',
+})
+
+/**
+ * Tron Base58Check wallet address.
+ */
+export const tronAddressSchema = z.string().regex(/^T[1-9A-HJ-NP-Za-km-z]{33}$/, {
+  message: 'Must be a valid Tron address',
+})
+
+/**
+ * Solana Base58 wallet address.
+ */
+export const solanaAddressSchema = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, {
+  message: 'Must be a valid Solana address',
+})
+
+/**
+ * Address schema (Ethereum, Spark, Bitcoin, TON, Tron, or Solana)
+ */
+export const addressSchema = z.union([
+  ethereumAddressSchema,
+  sparkAddressSchema,
+  bitcoinAddressSchema,
+  tonAddressSchema,
+  tronAddressSchema,
+  solanaAddressSchema,
+])
 
 /**
  * Network configuration schema

package/src/utils/typeGuards.ts

@@ -21,6 +21,7 @@ import {
   accountIndexSchema,
   networkNameSchema,
   balanceStringSchema,
+  addressSchema,
 } from './schemas'
 import type {
   NetworkConfig,
@@ -104,10 +105,10 @@ export function isBitcoinAddress(value: unknown): value is string {
 }
 
 /**
- * Type guard to check if a value is a valid address (Ethereum, Spark, or Bitcoin)
+ * Type guard to check if a value is a valid address (Ethereum, Spark, Bitcoin, TON, Tron, or Solana)
  */
 export function isValidAddress(value: unknown): value is string {
-  return isEthereumAddress(value) || isSparkAddress(value) || isBitcoinAddress(value)
+  return addressSchema.safeParse(value).success
 }
 
 /**