@lukso/transaction-view-headless 0.2.2-dev.a8c9315

package/src/hooks/useAddressResolution.ts

@@ -0,0 +1,437 @@
+/**
+ * Framework-agnostic address resolution hook
+ * Can be adapted for Vue (composable), React (hook), or Lit (controller)
+ * Uses batching mechanism inspired by the decoder package
+ */
+
+import type {
+  AssetData,
+  EnhancedInfo,
+  ImageData,
+  LinkData,
+  ProfileData,
+  TokenData,
+} from '@lukso/transaction-decoder'
+import type { Chain } from 'viem'
+import {
+  cacheAddress,
+  currentChainSignal,
+  getCachedAddress,
+  getLuksoConfig,
+  initializeChainSignal,
+  isAddressResolutionEnabled,
+} from '../config/lukso-config'
+
+/**
+ * Union type of all possible resolved address data
+ * Combines Profile, Asset, and Token data structures
+ */
+export type ResolvedAddress = {
+  address: string
+  hasProfile: boolean
+  truncatedAddress: string
+  __gqltype?: 'Profile' | 'Asset' | 'Token' | 'Contract'
+} & Partial<ProfileData> &
+  Partial<AssetData> &
+  Partial<TokenData>
+
+/**
+ * Truncate address to 0x{first5}...{last4} format
+ */
+function truncateAddress(
+  address: string,
+  prefixLength = 5,
+  suffixLength = 4
+): string {
+  if (!address || address.length <= prefixLength + suffixLength + 2) {
+    return address
+  }
+
+  const prefix = address.slice(0, 2 + prefixLength) // 0x + first 5
+  const suffix = address.slice(-suffixLength) // last 4
+
+  return `${prefix}...${suffix}`
+}
+
+// Per-chain batching state
+interface ChainBatchState {
+  batchTimeout: NodeJS.Timeout | null
+  batchQueue: Set<string>
+  batchResolvers: Map<string, (result: ResolvedAddress) => void>
+  pendingResolutions: Map<string, Promise<ResolvedAddress>>
+  isProcessing: boolean // Prevent concurrent batch processing
+}
+
+const chainBatchStates = new Map<number, ChainBatchState>()
+const BATCH_DELAY = 0 // Just wait for next tick to batch addresses from the same render cycle
+const BATCH_SIZE = 50
+
+/**
+ * Get or create batch state for a specific chain
+ */
+function getBatchState(chainId: number): ChainBatchState {
+  let state = chainBatchStates.get(chainId)
+  if (!state) {
+    state = {
+      batchTimeout: null,
+      batchQueue: new Set<string>(),
+      batchResolvers: new Map<string, (result: ResolvedAddress) => void>(),
+      pendingResolutions: new Map<string, Promise<ResolvedAddress>>(),
+      isProcessing: false,
+    }
+    chainBatchStates.set(chainId, state)
+  }
+  return state
+}
+
+/**
+ * Process a batch of addresses using decoder package's GraphQL resolver
+ */
+async function processBatch(chainId: number): Promise<void> {
+  const state = getBatchState(chainId)
+  if (state.batchQueue.size === 0 || state.isProcessing) return
+
+  // Prevent concurrent processing for this chain
+  state.isProcessing = true
+
+  const addresses = Array.from(state.batchQueue)
+  state.batchQueue.clear()
+
+  try {
+    // Use decoder package's GraphQL resolver
+    // @ts-ignore - Declaration files may not be ready during development
+    const { fetchMultipleAddresses, getGraphQLEndpoint } = await import(
+      '@lukso/transaction-decoder'
+    )
+    const { lukso, luksoTestnet } = await import('viem/chains')
+
+    // Get the appropriate chain
+    const chain = chainId === 42 ? lukso : luksoTestnet
+    const graphqlEndpoint = getGraphQLEndpoint(chain)
+
+    // Convert addresses to DataKey format expected by decoder
+    const dataKeys = addresses as any[] // DataKey is a hex string type
+
+    // Fetch using decoder package
+    const results = await fetchMultipleAddresses(dataKeys, graphqlEndpoint)
+
+    // Process results and resolve promises
+    for (const address of addresses) {
+      const normalizedAddress = address.toLowerCase() as any
+      const enhanced: EnhancedInfo | undefined = results.get(normalizedAddress)
+
+      let result: ResolvedAddress
+
+      if (enhanced) {
+        // Just pass through the enhanced data as-is - no need to restructure
+        const profileImages = (enhanced as Record<string, any>).profileImages
+        const resolvedData = {
+          ...enhanced,
+          hasProfile: !!(enhanced.name || profileImages?.length),
+        }
+
+        // Cache the result with chainId
+        cacheAddressForChain(address, resolvedData, chainId)
+
+        result = {
+          ...resolvedData,
+          address,
+          truncatedAddress: truncateAddress(address),
+        }
+      } else {
+        // No profile found
+        result = {
+          address,
+          truncatedAddress: truncateAddress(address),
+          hasProfile: false,
+        }
+
+        // Cache negative result with chainId
+        cacheAddressForChain(address, { hasProfile: false }, chainId)
+      }
+
+      // Resolve the promise
+      const resolver = state.batchResolvers.get(normalizedAddress)
+      if (resolver) {
+        resolver(result)
+        state.batchResolvers.delete(normalizedAddress)
+      }
+    }
+  } catch (error) {
+    console.warn(
+      'Batch address resolution failed (falling back to API):',
+      error
+    )
+
+    // Fallback to original API approach if decoder package fails
+    try {
+      const response = await fetch('/api/resolveAddresses', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          addresses,
+          chainId: chainId,
+        }),
+      })
+
+      if (!response.ok) {
+        throw new Error(`API fallback failed: ${response.status}`)
+      }
+
+      const data = await response.json()
+
+      // Process API results
+      for (const address of addresses) {
+        const normalizedAddress = address.toLowerCase()
+        const resolved = data.resolved?.[normalizedAddress]
+
+        let result: ResolvedAddress
+
+        if (resolved) {
+          const resolvedData = {
+            name: resolved.name,
+            profileImage: resolved.profileImage,
+            hasProfile: !!(resolved.name || resolved.profileImage),
+          }
+
+          cacheAddressForChain(address, resolvedData, chainId)
+
+          result = {
+            address,
+            truncatedAddress: truncateAddress(address),
+            ...resolvedData,
+          }
+        } else {
+          result = {
+            address,
+            truncatedAddress: truncateAddress(address),
+            hasProfile: false,
+          }
+          cacheAddressForChain(address, { hasProfile: false }, chainId)
+        }
+
+        const resolver = state.batchResolvers.get(normalizedAddress)
+        if (resolver) {
+          resolver(result)
+          state.batchResolvers.delete(normalizedAddress)
+        }
+      }
+    } catch (fallbackError) {
+      console.warn('Both GraphQL and API resolution failed:', fallbackError)
+
+      // Return fallbacks for all addresses
+      for (const address of addresses) {
+        const fallback: ResolvedAddress = {
+          address,
+          truncatedAddress: truncateAddress(address),
+          hasProfile: false,
+        }
+
+        cacheAddressForChain(address, { hasProfile: false }, chainId)
+
+        const resolver = state.batchResolvers.get(address.toLowerCase())
+        if (resolver) {
+          resolver(fallback)
+          state.batchResolvers.delete(address.toLowerCase())
+        }
+      }
+    }
+  } finally {
+    // Always reset processing flag
+    state.isProcessing = false
+  }
+}
+
+/**
+ * Chain-aware address cache functions
+ */
+function cacheAddressForChain(
+  address: string,
+  data: any,
+  chainId: number
+): void {
+  const key = `${address.toLowerCase()}:${chainId}`
+  cacheAddress(key, data)
+}
+
+function getCachedAddressForChain(
+  address: string,
+  chainId: number
+): any | null {
+  const key = `${address.toLowerCase()}:${chainId}`
+  return getCachedAddress(key)
+}
+
+/**
+ * Get effective chain ID from parameter or current signal
+ */
+async function getEffectiveChainId(chainId?: number): Promise<number> {
+  if (chainId !== undefined) return chainId
+
+  // Initialize chain signal if needed
+  await initializeChainSignal()
+
+  // Get from signal or fall back to global config
+  const currentChain = currentChainSignal.value
+  if (currentChain) {
+    return currentChain.id
+  }
+
+  // Final fallback to global config
+  const config = getLuksoConfig()
+  return config.chainId
+}
+
+/**
+ * Resolve a single address using batched resolution
+ * Returns immediately with cached data or fallback, then updates with resolved data
+ * Handles both plain addresses and address-tokenId composite format (with - separator)
+ */
+export async function resolveAddress(
+  address: string,
+  chainId?: number
+): Promise<ResolvedAddress> {
+  const effectiveChainId = await getEffectiveChainId(chainId)
+  const normalizedAddress = address.toLowerCase()
+
+  // Always provide truncated fallback using the original address
+  const fallback: ResolvedAddress = {
+    address,
+    truncatedAddress: truncateAddress(address),
+    hasProfile: false,
+  }
+
+  // Return fallback immediately if resolution disabled
+  if (!isAddressResolutionEnabled()) {
+    return fallback
+  }
+
+  // Check cache first (chain-aware)
+  const cached = getCachedAddressForChain(address, effectiveChainId)
+  if (cached) {
+    return {
+      ...fallback,
+      ...cached,
+      hasProfile: !!(cached.name || cached.profileImage),
+    }
+  }
+
+  const state = getBatchState(effectiveChainId)
+
+  // Check if resolution is already pending for this chain
+  const existingPromise = state.pendingResolutions.get(normalizedAddress)
+  if (existingPromise) {
+    return existingPromise
+  }
+
+  // Safety check: if we already have this address in the batch queue, return a fast fallback
+  if (state.batchQueue.has(normalizedAddress)) {
+    return Promise.resolve(fallback)
+  }
+
+  // Create new resolution promise
+  const resolutionPromise = new Promise<ResolvedAddress>((resolve) => {
+    // Add full address to batch queue (supports address-tokenId format with -)
+    state.batchQueue.add(normalizedAddress)
+    state.batchResolvers.set(normalizedAddress, resolve)
+
+    // Clear existing timeout
+    if (state.batchTimeout) {
+      clearTimeout(state.batchTimeout)
+    }
+
+    // Set new timeout for batch processing (only if not already processing)
+    if (!state.isProcessing) {
+      state.batchTimeout = setTimeout(() => {
+        state.batchTimeout = null
+        processBatch(effectiveChainId)
+      }, BATCH_DELAY)
+
+      // Process immediately if batch is full
+      if (state.batchQueue.size >= BATCH_SIZE) {
+        if (state.batchTimeout) {
+          clearTimeout(state.batchTimeout)
+          state.batchTimeout = null
+        }
+        processBatch(effectiveChainId)
+      }
+    }
+  })
+
+  // Store the promise to avoid duplicate requests
+  state.pendingResolutions.set(normalizedAddress, resolutionPromise)
+
+  // Clean up after resolution
+  resolutionPromise.finally(() => {
+    state.pendingResolutions.delete(normalizedAddress)
+  })
+
+  return resolutionPromise
+}
+
+/**
+ * Resolve multiple addresses
+ */
+export async function resolveAddresses(
+  addresses: string[],
+  chainId?: number
+): Promise<Map<string, ResolvedAddress>> {
+  const results = new Map<string, ResolvedAddress>()
+
+  // Resolve all addresses in parallel using the batched resolver
+  const resolutionPromises = addresses.map(async (address) => {
+    const resolved = await resolveAddress(address, chainId)
+    results.set(address.toLowerCase(), resolved)
+  })
+
+  await Promise.all(resolutionPromises)
+  return results
+}
+
+/**
+ * Simple reactive state for frameworks to implement
+ * Each framework will wrap this with their reactivity system
+ */
+export interface AddressResolutionState {
+  resolved: ResolvedAddress | null
+  loading: boolean
+  error: string | null
+}
+
+/**
+ * Create initial state
+ */
+export function createAddressResolutionState(): AddressResolutionState {
+  return {
+    resolved: null,
+    loading: false,
+    error: null,
+  }
+}
+
+/**
+ * Framework-agnostic resolution function that updates state
+ */
+export async function resolveAddressWithState(
+  address: string,
+  _state: AddressResolutionState,
+  updateCallback: (newState: Partial<AddressResolutionState>) => void,
+  chainId?: number
+): Promise<void> {
+  // Start loading
+  updateCallback({ loading: true, error: null })
+
+  try {
+    const resolved = await resolveAddress(address, chainId)
+    updateCallback({
+      resolved,
+      loading: false,
+      error: null,
+    })
+  } catch (error) {
+    updateCallback({
+      loading: false,
+      error: error instanceof Error ? error.message : 'Resolution failed',
+    })
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// Main exports for the decoder-headless package
+
+export type {
+  AddressImageData,
+  AddressResolutionState,
+  ImageLoadOptions,
+  ImageResult,
+  LuksoConfig,
+  ResolvedAddress,
+  UseTransactionViewOptions,
+  UseTransactionViewResult,
+} from './composables'
+export * from './composables'
+export {
+  findBestTransactionView,
+  useTransactionView,
+} from './composables'
+// Configuration and address resolution (framework-agnostic)
+export * from './config/lukso-config'
+export * from './hooks/useAddressQuery'
+export * from './hooks/useAddressResolution'
+export * from './registry'
+// Convenience re-exports for common use cases
+export {
+  getGlobalLoader,
+  getGlobalRegistry,
+} from './registry'
+export type {
+  DecoderRecordForSelection,
+  ViewContext,
+  ViewDefinition,
+  ViewMatch,
+  ViewMatchCriteria,
+} from './types'
+export * from './types'
+export * from './utils'

package/src/registry/index.ts

@@ -0,0 +1,13 @@
+export {
+  getGlobalLoader,
+  LoaderHelpers,
+  setGlobalLoader,
+  UniversalViewLoader,
+  ViewLoadingError,
+} from './view-loader'
+export {
+  DefaultViewRegistry,
+  getGlobalRegistry,
+  resetGlobalRegistry,
+  setGlobalRegistry,
+} from './view-registry'