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

package/package.json

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

package/src/__tests__/services/transactionService.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Tests for TransactionService
+ */
+
+import { setIndexerConfig } from '../../store/indexerConfigStore'
+import { TransactionService } from '../../services/transactionService'
+
+const mockFetch = jest.fn()
+global.fetch = mockFetch as typeof fetch
+
+describe('TransactionService', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    setIndexerConfig({
+      baseUrl: 'https://wdk-api.tether.io',
+      apiKey: 'test-api-key',
+    })
+  })
+
+  afterEach(() => {
+    setIndexerConfig(null)
+  })
+
+  it('fetches and parses token transfers', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        transfers: [
+          {
+            blockchain: 'ethereum',
+            transactionHash: '0xabc',
+            token: 'xaut',
+            amount: '1.5',
+            timestamp: 1700000000,
+            from: '0xfrom',
+            to: '0xto',
+          },
+        ],
+      }),
+    })
+
+    const transfers = await TransactionService.fetchTokenTransfers(
+      'ethereum',
+      'xaut',
+      '0xWallet'
+    )
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://wdk-api.tether.io/api/v1/ethereum/xaut/0xWallet/token-transfers',
+      expect.objectContaining({
+        method: 'GET',
+        headers: expect.objectContaining({
+          'x-api-key': 'test-api-key',
+        }),
+      })
+    )
+    expect(transfers).toHaveLength(1)
+    expect(transfers[0].token).toBe('xaut')
+    expect(transfers[0].amount).toBe('1.5')
+  })
+
+  it('returns empty list on 404', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 404,
+      text: async () => 'not found',
+    })
+
+    const transfers = await TransactionService.fetchTokenTransfers(
+      'ethereum',
+      'usdt',
+      '0xWallet'
+    )
+    expect(transfers).toEqual([])
+  })
+
+  it('aggregates transfers across networks and dedupes', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ transfers: [] }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          transfers: [
+            {
+              blockchain: 'ethereum',
+              transactionHash: '0x1',
+              token: 'usdt',
+              amount: '10',
+              timestamp: 100,
+              from: '0xa',
+              to: '0xb',
+            },
+          ],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          transfers: [
+            {
+              blockchain: 'ethereum',
+              transactionHash: '0x2',
+              token: 'xaut',
+              amount: '0.5',
+              timestamp: 200,
+              from: '0xc',
+              to: '0xd',
+            },
+          ],
+        }),
+      })
+
+    const tokenConfigs = {
+      ethereum: {
+        native: { address: null, symbol: 'ETH', name: 'Ethereum', decimals: 18 },
+        tokens: [
+          {
+            address: '0xusdt',
+            symbol: 'USDT',
+            name: 'Tether USD',
+            decimals: 6,
+          },
+          {
+            address: '0xxaut',
+            symbol: 'XAUT',
+            name: 'Tether Gold',
+            decimals: 6,
+          },
+        ],
+      },
+    }
+
+    const list = await TransactionService.fetchWalletTransactions({
+      addresses: { ethereum: { 0: '0xWallet' } },
+      accountIndex: 0,
+      tokenConfigs,
+    })
+
+    expect(list).toHaveLength(2)
+    expect(list[0].transactionHash).toBe('0x2')
+    expect(list[1].transactionHash).toBe('0x1')
+  })
+
+  it('resolveWalletTransactions returns empty when indexer not configured', async () => {
+    setIndexerConfig(null)
+    const list = await TransactionService.resolveWalletTransactions({
+      addresses: { ethereum: { 0: '0xWallet' } },
+      accountIndex: 0,
+      tokenConfigs: {
+        ethereum: {
+          native: { address: null, symbol: 'ETH', name: 'Ethereum', decimals: 18 },
+          tokens: [],
+        },
+      },
+    })
+    expect(list).toEqual([])
+    expect(mockFetch).not.toHaveBeenCalled()
+  })
+})

package/src/hooks/useBalance.ts

@@ -55,6 +55,7 @@ import {
   DEFAULT_QUERY_STALE_TIME_MS,
   DEFAULT_QUERY_GC_TIME_MS,
   BALANCE_FETCH_STAGGER_MS,
+  BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS,
 } from '../utils/constants'
 import { logError } from '../utils/logger'
 import { delay, withTransientRetry } from '../utils/retryUtils'
@@ -388,18 +389,21 @@ async function fetchBalancesForQueryKeys(
     }
     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 }
-      })
-    )
+    const networkResults: Array<{ id: string; result: BalanceFetchResult }> = []
+    for (let i = 0; i < keys.length; i++) {
+      if (i > 0) {
+        await delay(BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS)
+      }
+      const queryKey = keys[i]
+      const validated = validateQueryKeyStructure(queryKey)
+      const result = await fetchBalance(
+        validated.network,
+        validated.accountIndex,
+        validated.tokenAddress,
+        walletId
+      )
+      networkResults.push({ id: balanceQueryKeyId(queryKey), result })
+    }
 
     for (const { id, result } of networkResults) {
       results.set(id, result)

package/src/hooks/useTransactions.ts

@@ -0,0 +1,98 @@
+/**
+ * Transaction hooks with TanStack Query
+ *
+ * Fetches wallet activity from the WDK Indexer (token-transfers per network/token/address).
+ * Requires indexerConfig on WdkAppProvider (typically from EXPO_PUBLIC_WDK_INDEXER_* in the app).
+ */
+
+import { useQuery } from '@tanstack/react-query'
+import { useShallow } from 'zustand/react/shallow'
+
+import { TransactionService } from '../services/transactionService'
+import { getWalletStore } from '../store/walletStore'
+import { getWorkletStore } from '../store/workletStore'
+import { isIndexerConfigured } from '../store/indexerConfigStore'
+import { resolveWalletId } from '../utils/storeHelpers'
+import {
+  DEFAULT_QUERY_GC_TIME_MS,
+  DEFAULT_QUERY_STALE_TIME_MS,
+} from '../utils/constants'
+import type { TokenConfigProvider, WalletTransaction } from '../types'
+
+export interface WalletTransactionsQueryOptions {
+  enabled?: boolean
+  staleTime?: number
+  refetchInterval?: number | false
+  walletId?: string
+}
+
+export const transactionQueryKeys = {
+  all: ['transactions'] as const,
+  byWallet: (walletId: string, accountIndex: number) =>
+    ['transactions', 'wallet', walletId, accountIndex] as const,
+}
+
+function resolveTokenConfigs(tokenConfigs: TokenConfigProvider) {
+  return typeof tokenConfigs === 'function' ? tokenConfigs() : tokenConfigs
+}
+
+function addressesFingerprint(
+  addresses: Record<string, Record<number, string>>,
+  accountIndex: number
+): string {
+  const parts: string[] = []
+  for (const network of Object.keys(addresses).sort()) {
+    const address = addresses[network]?.[accountIndex]
+    if (address) {
+      parts.push(`${network}:${address.toLowerCase()}`)
+    }
+  }
+  return parts.join('|')
+}
+
+async function fetchWalletTransactionsForAccount(
+  walletId: string,
+  accountIndex: number,
+  tokenConfigs: TokenConfigProvider
+): Promise<WalletTransaction[]> {
+  const walletStore = getWalletStore()
+  const addresses = walletStore.getState().addresses[walletId] ?? {}
+
+  return TransactionService.resolveWalletTransactions({
+    addresses,
+    accountIndex,
+    tokenConfigs: resolveTokenConfigs(tokenConfigs),
+  })
+}
+
+/**
+ * Fetch aggregated wallet transactions from the WDK Indexer.
+ */
+export function useWalletTransactions(
+  accountIndex: number,
+  tokenConfigs: TokenConfigProvider,
+  options?: WalletTransactionsQueryOptions
+) {
+  const workletStore = getWorkletStore()
+  const walletStore = getWalletStore()
+  const isInitialized = workletStore.getState().isInitialized
+  const walletId = resolveWalletId(options?.walletId)
+  const addresses = walletStore(
+    useShallow((state) => state.addresses[walletId] ?? {})
+  )
+  const addressKey = addressesFingerprint(addresses, accountIndex)
+  const indexerReady = isIndexerConfigured()
+
+  return useQuery({
+    queryKey: [...transactionQueryKeys.byWallet(walletId, accountIndex), addressKey],
+    queryFn: () => fetchWalletTransactionsForAccount(walletId, accountIndex, tokenConfigs),
+    enabled:
+      (options?.enabled !== false) &&
+      isInitialized &&
+      indexerReady &&
+      addressKey.length > 0,
+    staleTime: options?.staleTime ?? DEFAULT_QUERY_STALE_TIME_MS,
+    gcTime: DEFAULT_QUERY_GC_TIME_MS,
+    refetchInterval: options?.refetchInterval,
+  })
+}

package/src/index.ts

@@ -20,6 +20,9 @@ export type {
   TokenConfigProvider,
   TokenHelpers,
   WalletStore,
+  IndexerConfig,
+  WalletTransaction,
+  IndexerTokenTransfersResponse,
 } from './types'
 
 // HRPC Type Extensions (for extending HRPC functionality)
@@ -38,6 +41,8 @@ export { useWdkApp } from './hooks/useWdkApp'
 export { useWalletManager } from './hooks/useWalletManager'
 export type { UseWalletManagerResult, WalletInfo } from './hooks/useWalletManager'
 export { useBalance, useBalancesForWallet, useBalancesForWallets, useRefreshBalance, balanceQueryKeys } from './hooks/useBalance'
+export { useWalletTransactions, transactionQueryKeys } from './hooks/useTransactions'
+export type { WalletTransactionsQueryOptions } from './hooks/useTransactions'
 export type { AccountInfo } from './store/walletStore'
 
 // Validation Utilities (for validating configs before use)
@@ -84,6 +89,7 @@ export { WorkletLifecycleService } from './services/workletLifecycleService'
 export { AddressService } from './services/addressService'
 export { AccountService } from './services/accountService'
 export { BalanceService } from './services/balanceService'
+export { TransactionService } from './services/transactionService'
 export { WalletSetupService } from './services/walletSetupService'
 export { WalletSwitchingService } from './services/walletSwitchingService'
 

package/src/provider/WdkAppProvider.tsx

@@ -48,7 +48,8 @@ import { log, logError } from '../utils/logger'
 import { validateNetworkConfigs, validateTokenConfigs } from '../utils/validation'
 import { DEFAULT_QUERY_STALE_TIME_MS, DEFAULT_QUERY_GC_TIME_MS } from '../utils/constants'
 import { InitializationStatus, AppStatus, isAppReadyStatus, isAppInProgressStatus, getCombinedStatus, getWorkletStatus } from '../utils/initializationState'
-import type { NetworkConfigs, TokenConfigs } from '../types'
+import type { IndexerConfig, NetworkConfigs, TokenConfigs } from '../types'
+import { setIndexerConfig } from '../store/indexerConfigStore'
 
 
 
@@ -134,6 +135,11 @@ export interface WdkAppProviderProps {
   networkConfigs: NetworkConfigs
   /** Token configurations for balance fetching */
   tokenConfigs: TokenConfigs
+  /**
+   * WDK Indexer configuration for transaction history.
+   * Apps typically pass EXPO_PUBLIC_WDK_INDEXER_BASE_URL and EXPO_PUBLIC_WDK_INDEXER_API_KEY.
+   */
+  indexerConfig?: IndexerConfig
   /** Enable automatic wallet initialization on app restart (default: true) */
   enableAutoInitialization?: boolean
   /**
@@ -190,6 +196,7 @@ const deepEqualityFn = (a: any, b: any) => {
 export function WdkAppProvider({
   networkConfigs,
   tokenConfigs,
+  indexerConfig,
   enableAutoInitialization = true,
   currentUserId,
   children,
@@ -267,6 +274,11 @@ export function WdkAppProvider({
     }
   }, [networkConfigs, tokenConfigs])
 
+  useEffect(() => {
+    setIndexerConfig(indexerConfig ?? null)
+    return () => setIndexerConfig(null)
+  }, [indexerConfig])
+
   // Worklet state - read from workletStore via hook
   const workletHookState = useWorklet()
   const {

package/src/services/transactionService.ts

@@ -0,0 +1,194 @@
+/**
+ * Transaction Service
+ *
+ * Fetches wallet transaction history from the WDK Indexer API.
+ * Endpoint: GET /api/v1/{network}/{token}/{address}/token-transfers
+ */
+
+import { getIndexerConfig } from '../store/indexerConfigStore'
+import { BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS, BALANCE_FETCH_STAGGER_MS } from '../utils/constants'
+import { logError, logWarn } from '../utils/logger'
+import { delay, withTransientRetry } from '../utils/retryUtils'
+import type { IndexerTokenTransfersResponse, TokenConfigs, WalletTransaction } from '../types'
+
+export interface FetchWalletTransactionsParams {
+  addresses: Record<string, Record<number, string>>
+  accountIndex: number
+  tokenConfigs: TokenConfigs
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/$/, '')
+}
+
+function tokenSlugFromConfig(symbol: string): string {
+  return symbol.toLowerCase()
+}
+
+function transactionDedupeKey(tx: WalletTransaction): string {
+  return [
+    tx.blockchain,
+    tx.transactionHash,
+    tx.token,
+    tx.transferIndex ?? '',
+    tx.logIndex ?? '',
+    tx.from,
+    tx.to,
+    tx.amount,
+  ].join('|')
+}
+
+function parseIndexerTransfers(payload: unknown): WalletTransaction[] {
+  if (!payload || typeof payload !== 'object') {
+    return []
+  }
+  const transfers = (payload as IndexerTokenTransfersResponse).transfers
+  if (!Array.isArray(transfers)) {
+    return []
+  }
+
+  const parsed: WalletTransaction[] = []
+  for (const item of transfers) {
+    if (!item || typeof item !== 'object') continue
+    const tx = item as Partial<WalletTransaction>
+    if (
+      typeof tx.transactionHash !== 'string' ||
+      typeof tx.token !== 'string' ||
+      typeof tx.amount !== 'string' ||
+      typeof tx.timestamp !== 'number' ||
+      typeof tx.from !== 'string' ||
+      typeof tx.to !== 'string'
+    ) {
+      continue
+    }
+    parsed.push({
+      blockchain: typeof tx.blockchain === 'string' ? tx.blockchain : '',
+      blockNumber: typeof tx.blockNumber === 'number' ? tx.blockNumber : undefined,
+      transactionHash: tx.transactionHash,
+      transferIndex: typeof tx.transferIndex === 'number' ? tx.transferIndex : undefined,
+      token: tx.token.toLowerCase(),
+      amount: tx.amount,
+      timestamp: tx.timestamp,
+      transactionIndex: typeof tx.transactionIndex === 'number' ? tx.transactionIndex : undefined,
+      logIndex: typeof tx.logIndex === 'number' ? tx.logIndex : undefined,
+      from: tx.from,
+      to: tx.to,
+      label: typeof tx.label === 'string' ? tx.label : undefined,
+    })
+  }
+  return parsed
+}
+
+export class TransactionService {
+  /**
+   * Fetch token transfers for one network/token/address from the indexer.
+   */
+  static async fetchTokenTransfers(
+    network: string,
+    tokenSlug: string,
+    address: string
+  ): Promise<WalletTransaction[]> {
+    const config = getIndexerConfig()
+    if (!config?.baseUrl || !config.apiKey) {
+      throw new Error('WDK Indexer is not configured')
+    }
+
+    const url = `${normalizeBaseUrl(config.baseUrl)}/api/v1/${encodeURIComponent(network)}/${encodeURIComponent(tokenSlug)}/${encodeURIComponent(address)}/token-transfers`
+
+    const response = await withTransientRetry(
+      async () => {
+        const res = await fetch(url, {
+          method: 'GET',
+          headers: {
+            'x-api-key': config.apiKey,
+            Accept: 'application/json',
+          },
+        })
+
+        if (res.status === 404) {
+          return { ok: true as const, transfers: [] as WalletTransaction[] }
+        }
+
+        if (!res.ok) {
+          const text = await res.text().catch(() => '')
+          throw new Error(
+            `Indexer token-transfers failed (${res.status}) for ${network}/${tokenSlug}: ${text.slice(0, 200)}`
+          )
+        }
+
+        const json: unknown = await res.json()
+        return { ok: true as const, transfers: parseIndexerTransfers(json) }
+      },
+      { label: `${network}/${tokenSlug} token-transfers` }
+    )
+
+    return response.transfers
+  }
+
+  /**
+   * Fetch transfers for all configured networks/tokens for one account index.
+   */
+  static async fetchWalletTransactions(
+    params: FetchWalletTransactionsParams
+  ): Promise<WalletTransaction[]> {
+    const { addresses, accountIndex, tokenConfigs } = params
+    const networks = Object.keys(tokenConfigs)
+    const deduped = new Map<string, WalletTransaction>()
+    let isFirstNetwork = true
+
+    for (const network of networks) {
+      const address = addresses[network]?.[accountIndex]
+      if (!address) {
+        continue
+      }
+
+      if (!isFirstNetwork) {
+        await delay(BALANCE_FETCH_STAGGER_MS)
+      }
+      isFirstNetwork = false
+
+      const networkTokens = tokenConfigs[network]
+      if (!networkTokens) continue
+
+      const tokens = [networkTokens.native, ...networkTokens.tokens]
+      for (let i = 0; i < tokens.length; i++) {
+        if (i > 0) {
+          await delay(BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS)
+        }
+
+        const token = tokens[i]
+        const tokenSlug = tokenSlugFromConfig(token.symbol)
+        try {
+          const transfers = await this.fetchTokenTransfers(network, tokenSlug, address)
+          for (const tx of transfers) {
+            const withBlockchain = tx.blockchain
+              ? tx
+              : { ...tx, blockchain: network }
+            deduped.set(transactionDedupeKey(withBlockchain), withBlockchain)
+          }
+        } catch (error) {
+          logError(
+            `Failed to fetch token transfers for ${network}/${tokenSlug}:`,
+            error
+          )
+        }
+      }
+    }
+
+    return Array.from(deduped.values()).sort((a, b) => b.timestamp - a.timestamp)
+  }
+
+  /**
+   * Resolve wallet transactions (alias for fetchWalletTransactions).
+   * Matches the legacy resolveWalletTransactions name used by consuming apps.
+   */
+  static async resolveWalletTransactions(
+    params: FetchWalletTransactionsParams
+  ): Promise<WalletTransaction[]> {
+    if (!getIndexerConfig()) {
+      logWarn('[TransactionService] Indexer not configured — returning empty transaction list')
+      return []
+    }
+    return this.fetchWalletTransactions(params)
+  }
+}

package/src/store/indexerConfigStore.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime WDK Indexer configuration (set by WdkAppProvider from app env).
+ */
+
+import type { IndexerConfig } from '../types'
+
+let indexerConfig: IndexerConfig | null = null
+
+export function setIndexerConfig(config: IndexerConfig | null): void {
+  indexerConfig = config
+}
+
+export function getIndexerConfig(): IndexerConfig | null {
+  return indexerConfig
+}
+
+export function isIndexerConfigured(): boolean {
+  return Boolean(indexerConfig?.baseUrl && indexerConfig?.apiKey)
+}

package/src/types.ts

@@ -157,6 +157,42 @@ export interface BalanceFetchResult {
  */
 export type TokenConfigProvider = TokenConfigs | (() => TokenConfigs)
 
+/**
+ * WDK Indexer API configuration (balance/transaction history).
+ */
+export interface IndexerConfig {
+  /** Base URL, e.g. https://wdk-api.tether.io */
+  baseUrl: string
+  /** API key sent as x-api-key header */
+  apiKey: string
+}
+
+/**
+ * Token transfer from the WDK Indexer token-transfers endpoint.
+ */
+export interface WalletTransaction {
+  blockchain: string
+  blockNumber?: number
+  transactionHash: string
+  transferIndex?: number
+  token: string
+  amount: string
+  /** Unix timestamp in seconds (indexer convention) */
+  timestamp: number
+  transactionIndex?: number
+  logIndex?: number
+  from: string
+  to: string
+  label?: string
+}
+
+/**
+ * Raw indexer response for token-transfers.
+ */
+export interface IndexerTokenTransfersResponse {
+  transfers?: WalletTransaction[]
+}
+
 /**
  * Token Helpers
  * 

package/src/utils/constants.ts

@@ -73,6 +73,12 @@ export const DEFAULT_QUERY_GC_TIME_MS = 5 * 60 * 1000
  */
 export const BALANCE_FETCH_STAGGER_MS = 400
 
+/**
+ * Delay between token balance fetches within the same network (ms).
+ * TON jetton balances issue multiple RPC calls each; serializing avoids 429 bursts.
+ */
+export const BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS = 300
+
 /**
  * Max attempts for transient blockchain/RPC errors (429, 5xx, network timeouts).
  */