@lukso/transaction-decoder 1.0.1-dev.0f1bea5

package/src/server/caches.ts

@@ -0,0 +1,209 @@
+import { LRUCache } from 'lru-cache'
+import type { Abi } from 'viem'
+import type { DecoderResult, Info } from '../decoder/types'
+import type { DataKey, EnhancedInfo } from '../types'
+import type { CacheStats } from './types'
+
+/**
+ * Multi-level caching system for server-side decoder
+ */
+export class ServerDecoderCaches {
+  // Level 1: Decoded transaction cache (keyed by transaction hash)
+  private transactionCache: LRUCache<string, DecoderResult>
+  private transactionStats = { hits: 0, misses: 0 }
+
+  // Level 2: Address metadata cache (keyed by address or address:tokenId)
+  private addressCache: LRUCache<string, EnhancedInfo>
+  private addressStats = { hits: 0, misses: 0 }
+
+  // Level 3: Contract ABI cache (keyed by address)
+  private abiCache: LRUCache<string, Abi>
+  private abiStats = { hits: 0, misses: 0 }
+
+  // Level 4: Schema decode cache (keyed by key:value)
+  private schemaCache: LRUCache<string, Info>
+  private schemaStats = { hits: 0, misses: 0 }
+
+  constructor(
+    options: {
+      transactionCacheSize?: number
+      addressCacheSize?: number
+      abiCacheSize?: number
+      schemaCacheSize?: number
+    } = {}
+  ) {
+    // Transaction cache - store complete decoded results
+    this.transactionCache = new LRUCache<string, DecoderResult>({
+      max: options.transactionCacheSize || 10000,
+      ttl: 1000 * 60 * 60, // 1 hour TTL
+      updateAgeOnGet: true,
+      updateAgeOnHas: true,
+    })
+
+    // Address cache - store profile/asset metadata
+    this.addressCache = new LRUCache<string, EnhancedInfo>({
+      max: options.addressCacheSize || 50000,
+      ttl: 1000 * 60 * 60 * 24, // 24 hour TTL
+      updateAgeOnGet: true,
+      updateAgeOnHas: true,
+    })
+
+    // ABI cache - store contract ABIs
+    this.abiCache = new LRUCache<string, Abi>({
+      max: options.abiCacheSize || 5000,
+      ttl: 1000 * 60 * 60 * 24 * 7, // 7 day TTL (ABIs rarely change)
+      updateAgeOnGet: true,
+      updateAgeOnHas: true,
+    })
+
+    // Schema cache - store decoded schema values
+    this.schemaCache = new LRUCache<string, Info>({
+      max: options.schemaCacheSize || 10000,
+      ttl: 1000 * 60 * 60, // 1 hour TTL
+      updateAgeOnGet: true,
+      updateAgeOnHas: true,
+    })
+  }
+
+  /**
+   * Get cache key for a data key (address or address:tokenId)
+   */
+  private getDataKeyCacheKey(key: DataKey): string {
+    return key.toLowerCase()
+  }
+
+  // Transaction cache methods
+  getTransaction(hash: string): DecoderResult | undefined {
+    const result = this.transactionCache.get(hash.toLowerCase())
+    if (result) {
+      this.transactionStats.hits++
+      return { ...result, cached: true }
+    }
+    this.transactionStats.misses++
+    return undefined
+  }
+
+  setTransaction(hash: string, result: DecoderResult): void {
+    this.transactionCache.set(hash.toLowerCase(), result)
+  }
+
+  // Address cache methods
+  getAddress(key: DataKey): EnhancedInfo | undefined {
+    const cacheKey = this.getDataKeyCacheKey(key)
+    const result = this.addressCache.get(cacheKey)
+    if (result) {
+      this.addressStats.hits++
+      return result
+    }
+    this.addressStats.misses++
+    return undefined
+  }
+
+  setAddress(key: DataKey, data: EnhancedInfo): void {
+    const cacheKey = this.getDataKeyCacheKey(key)
+    this.addressCache.set(cacheKey, data)
+  }
+
+  hasAddress(key: DataKey): boolean {
+    return this.addressCache.has(this.getDataKeyCacheKey(key))
+  }
+
+  getAddresses(keys: DataKey[]): Map<DataKey, EnhancedInfo> {
+    const results = new Map<DataKey, EnhancedInfo>()
+    for (const key of keys) {
+      const data = this.getAddress(key)
+      if (data) {
+        results.set(key, data)
+      }
+    }
+    return results
+  }
+
+  // ABI cache methods
+  getAbi(address: string): Abi | undefined {
+    const result = this.abiCache.get(address.toLowerCase())
+    if (result) {
+      this.abiStats.hits++
+      return result
+    }
+    this.abiStats.misses++
+    return undefined
+  }
+
+  setAbi(address: string, abi: Abi): void {
+    this.abiCache.set(address.toLowerCase(), abi)
+  }
+
+  hasAbi(address: string): boolean {
+    return this.abiCache.has(address.toLowerCase())
+  }
+
+  // Schema cache methods
+  getSchema(key: string, value: string): Info | undefined {
+    const cacheKey = `${key}:${value}`
+    const result = this.schemaCache.get(cacheKey)
+    if (result) {
+      this.schemaStats.hits++
+      return result
+    }
+    this.schemaStats.misses++
+    return undefined
+  }
+
+  setSchema(key: string, value: string, info: Info): void {
+    const cacheKey = `${key}:${value}`
+    this.schemaCache.set(cacheKey, info)
+  }
+
+  // Cache management
+  clear(): void {
+    this.transactionCache.clear()
+    this.addressCache.clear()
+    this.abiCache.clear()
+    this.schemaCache.clear()
+
+    // Reset stats
+    this.transactionStats = { hits: 0, misses: 0 }
+    this.addressStats = { hits: 0, misses: 0 }
+    this.abiStats = { hits: 0, misses: 0 }
+    this.schemaStats = { hits: 0, misses: 0 }
+  }
+
+  getStats(): CacheStats {
+    const calculateHitRate = (stats: { hits: number; misses: number }) => {
+      const total = stats.hits + stats.misses
+      return total > 0 ? stats.hits / total : 0
+    }
+
+    return {
+      transactions: {
+        size: this.transactionCache.size,
+        maxSize: this.transactionCache.max,
+        hits: this.transactionStats.hits,
+        misses: this.transactionStats.misses,
+        hitRate: calculateHitRate(this.transactionStats),
+      },
+      addresses: {
+        size: this.addressCache.size,
+        maxSize: this.addressCache.max,
+        hits: this.addressStats.hits,
+        misses: this.addressStats.misses,
+        hitRate: calculateHitRate(this.addressStats),
+      },
+      abis: {
+        size: this.abiCache.size,
+        maxSize: this.abiCache.max,
+        hits: this.abiStats.hits,
+        misses: this.abiStats.misses,
+        hitRate: calculateHitRate(this.abiStats),
+      },
+      schemas: {
+        size: this.schemaCache.size,
+        maxSize: this.schemaCache.max,
+        hits: this.schemaStats.hits,
+        misses: this.schemaStats.misses,
+        hitRate: calculateHitRate(this.schemaStats),
+      },
+    }
+  }
+}

package/src/server/decodeTransactionSync.ts

@@ -0,0 +1,156 @@
+import type { Transaction } from 'viem'
+import { collectDataKeys } from '../core/addressCollector'
+import { pluginRegistry } from '../decoder/registry'
+import { decodeTransaction as decodeTransactionCore } from '../decoder/transaction'
+import type { DecoderResult } from '../decoder/types'
+import { needsEnhancement } from '../decoder/utils'
+import type { ServerDecoderCaches } from './caches'
+import type { ServerDecoderOptions } from './types'
+
+/**
+ * Decode a single transaction with time-bounded enhancement
+ */
+export async function decodeTransactionSync(
+  transaction: DecoderResult,
+  options: ServerDecoderOptions,
+  caches: ServerDecoderCaches
+): Promise<DecoderResult> {
+  const startTime = Date.now()
+  const { timeoutMs = 800, enableEnhancement = true, chain } = options
+
+  // Check transaction cache first
+  if (transaction.hash) {
+    const cached = caches.getTransaction(transaction.hash)
+    if (cached) {
+      return cached
+    }
+  }
+
+  try {
+    // Phase 1: Immediate decode (sync plugins only)
+    const phase1Start = Date.now()
+    const plugins = await pluginRegistry.getAll({ syncOnly: true })
+    const schemaPlugins = pluginRegistry.getAllSchema()
+
+    const immediateOptions = {
+      chain,
+      plugins,
+      schemaPlugins,
+      wrappers: [],
+      async: false,
+    }
+    const immediateResult = await decodeTransactionCore(
+      transaction,
+      immediateOptions
+    )
+
+    if (!immediateResult) {
+      return {
+        ...createErrorResult(transaction),
+        phase: 'immediate',
+        cached: false,
+        timeTaken: Date.now() - startTime,
+      }
+    }
+
+    let currentResult: DecoderResult = immediateResult
+    let phase: 'immediate' | 'enhanced' | 'complete' = 'immediate'
+
+    // Transfer collected wrappers if any
+    if (immediateOptions.wrappers.length > 0) {
+      ;(currentResult as any).wrappers = immediateOptions.wrappers
+    }
+
+    // Collect addresses from the decoded result
+    const addresses = collectDataKeys(currentResult)
+    currentResult.addresses = addresses
+
+    // Check if we have time for enhancement
+    const phase1Time = Date.now() - phase1Start
+    if (enableEnhancement && phase1Time < timeoutMs * 0.6) {
+      // Check if enhancement is actually needed
+      if (!needsEnhancement(currentResult)) {
+        // Already fully decoded during immediate phase
+        phase = 'enhanced'
+      } else {
+        // Phase 2: Enhancement with async plugins
+        try {
+          const allPlugins = await pluginRegistry.getAll()
+          const enhancedOptions = {
+            chain,
+            plugins: allPlugins,
+            schemaPlugins,
+            wrappers: [],
+            async: true,
+          }
+          const enhancedResult = await Promise.race([
+            decodeTransactionCore(transaction, enhancedOptions),
+            // Timeout for phase 2
+            new Promise<null>((resolve) =>
+              setTimeout(() => resolve(null), timeoutMs * 0.6 - phase1Time)
+            ),
+          ])
+
+          if (enhancedResult) {
+            currentResult = enhancedResult
+            phase = 'enhanced'
+
+            // Merge wrappers from both phases (immediate + enhanced)
+            const allWrappers = [
+              ...((immediateOptions.wrappers || []) as any[]),
+              ...(enhancedOptions.wrappers || []),
+            ].filter(
+              (w, i, arr) =>
+                // Deduplicate by checking if this is the first occurrence
+                arr.findIndex(
+                  (x) => JSON.stringify(x) === JSON.stringify(w)
+                ) === i
+            )
+
+            if (allWrappers.length > 0) {
+              ;(currentResult as any).wrappers = allWrappers
+            }
+
+            // Re-collect addresses from enhanced result
+            currentResult.addresses = collectDataKeys(currentResult)
+          }
+        } catch (error) {
+          console.error('Enhancement failed:', error)
+        }
+      }
+    }
+
+    const result: DecoderResult = {
+      ...currentResult,
+      phase,
+      cached: false,
+      timeTaken: Date.now() - startTime,
+    }
+
+    // Cache the result if we have a hash
+    if (transaction.hash) {
+      caches.setTransaction(transaction.hash, result)
+    }
+
+    return result
+  } catch (error) {
+    console.error('Failed to decode transaction:', error)
+    return {
+      ...createErrorResult(transaction),
+      phase: 'immediate',
+      cached: false,
+      timeTaken: Date.now() - startTime,
+    }
+  }
+}
+
+function createErrorResult(transaction: DecoderResult): DecoderResult {
+  return {
+    ...transaction,
+    isDecoded: false,
+    resultType: 'error',
+    errorType: 'UNKNOWN',
+    sig: '0x' as `0x${string}`,
+    addresses: [],
+  } as DecoderResult
+}

package/src/server/decodeTransactionsBatch.ts

@@ -0,0 +1,207 @@
+import { collectDataKeys } from '../core/addressCollector'
+import { pluginRegistry } from '../decoder/registry'
+import { decodeTransaction as decodeTransactionCore } from '../decoder/transaction'
+import type { DecoderResult, ResultShared } from '../decoder/types'
+import { needsEnhancement } from '../decoder/utils'
+import type { ServerDecoderCaches } from './caches'
+import type { BatchDecodeResult, ServerDecoderOptions } from './types'
+
+/**
+ * Decode multiple transactions with batching and time budget
+ */
+export async function decodeTransactionsBatch(
+  transactions: DecoderResult[],
+  options: ServerDecoderOptions,
+  caches: ServerDecoderCaches
+): Promise<BatchDecodeResult> {
+  const startTime = Date.now()
+  const { timeoutMs = 800, enableEnhancement = true, chain } = options
+
+  // Step 1: Check cache for all transactions
+  const results: (DecoderResult | null)[] = transactions.map((tx) => {
+    if (tx.transactionHash) {
+      const cached = caches.getTransaction(tx.transactionHash)
+      if (cached) return cached
+    }
+    return null
+  })
+
+  // Find uncached transactions
+  const uncachedIndexes: number[] = []
+  const uncachedTransactions: DecoderResult[] = []
+  results.forEach((result, index) => {
+    if (!result) {
+      uncachedIndexes.push(index)
+      uncachedTransactions.push(transactions[index])
+    }
+  })
+
+  // If all are cached, return early
+  if (uncachedTransactions.length === 0) {
+    return {
+      results: results as DecoderResult[],
+    }
+  }
+
+  try {
+    // Get plugins once for all transactions
+    const syncPlugins = await pluginRegistry.getAll({ syncOnly: true })
+    const allPlugins = await pluginRegistry.getAll()
+    const schemaPlugins = pluginRegistry.getAllSchema()
+
+    // Phase 1: Immediate decode for all uncached transactions
+    const phase1Start = Date.now()
+    const immediateOptionsArray = uncachedTransactions.map(() => ({
+      chain,
+      plugins: syncPlugins,
+      schemaPlugins,
+      wrappers: [],
+      async: false,
+    }))
+
+    const immediateResults: DecoderResult[] = (
+      await Promise.all(
+        uncachedTransactions.map(async (tx, i) => {
+          return await decodeTransactionCore(tx, immediateOptionsArray[i])
+        })
+      )
+    ).filter(Boolean) as DecoderResult[]
+
+    // Create result objects and collect addresses
+    const newResults: DecoderResult[] = immediateResults
+      .map((result, i) => {
+        const data = result || createErrorResult(uncachedTransactions[i])
+
+        // Transfer wrappers from immediate phase options
+        if (immediateOptionsArray[i].wrappers.length > 0) {
+          ;(data as any).wrappers = immediateOptionsArray[i].wrappers
+        }
+
+        // Collect addresses from the decoded result
+        data.addresses = collectDataKeys(data)
+        ;(data as ResultShared).timeTaken = Date.now() - startTime
+        return data
+      })
+      .filter(Boolean) as DecoderResult[]
+
+    // Check if we have time for enhancement
+    const phase1Time = Date.now() - phase1Start
+    if (enableEnhancement && phase1Time < timeoutMs * 0.6) {
+      // Phase 2: Enhancement with async plugins (batch all transactions)
+      try {
+        const enhancedOptionsArray = uncachedTransactions.map(() => ({
+          chain,
+          plugins: allPlugins,
+          schemaPlugins,
+          wrappers: [],
+          async: true,
+        }))
+
+        const enhancePromises = uncachedTransactions.map((tx, i) => {
+          // Only enhance if immediate decode succeeded
+          if (!immediateResults[i]) return null
+
+          // Check if enhancement is actually needed
+          if (!needsEnhancement(immediateResults[i])) {
+            // Already fully decoded during immediate phase
+            return null
+          }
+
+          return decodeTransactionCore(tx, enhancedOptionsArray[i])
+        })
+
+        // Wait for all enhancements with remaining time budget
+        const remainingTime = timeoutMs * 0.6 - phase1Time
+        const enhancedResults = await Promise.all(enhancePromises)
+
+        // Update results with enhanced data
+        enhancedResults.forEach((enhanced, i) => {
+          if (enhanced) {
+            // Merge wrappers from both phases (immediate + enhanced)
+            const immediateWrappers = immediateOptionsArray[i].wrappers || []
+            const enhancedWrappers = enhancedOptionsArray[i].wrappers || []
+            const allWrappers = [
+              ...immediateWrappers,
+              ...enhancedWrappers,
+            ].filter(
+              (w, idx, arr) =>
+                // Deduplicate by checking if this is the first occurrence
+                arr.findIndex(
+                  (x) => JSON.stringify(x) === JSON.stringify(w)
+                ) === idx
+            )
+
+            // Enhancement returned a new result
+            newResults[i] = enhanced
+
+            // Add merged wrappers if any
+            if (allWrappers.length > 0) {
+              ;(newResults[i] as any).wrappers = allWrappers
+            }
+
+            // Re-collect addresses from enhanced result
+            newResults[i].addresses = collectDataKeys(enhanced)
+            newResults[i].phase = 'enhanced'
+          } else if (
+            immediateResults[i] &&
+            !needsEnhancement(immediateResults[i])
+          ) {
+            // Enhancement was skipped because already fully decoded
+            newResults[i].phase = 'enhanced'
+          }
+        })
+      } catch (error) {
+        console.error('Batch enhancement failed:', error)
+      }
+    }
+
+    // Update timings
+    const totalTime = Date.now() - startTime
+    newResults.forEach((result) => {
+      result.timeTaken = totalTime
+    })
+
+    // Cache all new results
+    newResults.forEach((result, i) => {
+      const tx = uncachedTransactions[i]
+      if (tx.hash) {
+        caches.setTransaction(tx.hash, result)
+      }
+    })
+
+    // Merge cached and new results
+    uncachedIndexes.forEach((originalIndex, i) => {
+      results[originalIndex] = newResults[i]
+    })
+
+    return {
+      results: results as DecoderResult[],
+    }
+  } catch (error) {
+    console.error('Batch decode failed:', error)
+    // Return error results for uncached transactions
+    uncachedIndexes.forEach((originalIndex) => {
+      results[originalIndex] = {
+        ...createErrorResult(transactions[originalIndex]),
+        phase: 'immediate',
+        cached: false,
+        timeTaken: Date.now() - startTime,
+      }
+    })
+
+    return {
+      results: results as DecoderResult[],
+    }
+  }
+}
+
+function createErrorResult(transaction: DecoderResult): DecoderResult {
+  return {
+    ...transaction,
+    isDecoded: false,
+    resultType: 'error',
+    errorType: 'UNKNOWN',
+    sig: '0x' as `0x${string}`,
+    addresses: [],
+  } as DecoderResult
+}

package/src/server/finishDecoding.ts

@@ -0,0 +1,116 @@
+import { collectDataKeys } from '../core/addressCollector'
+import { pluginRegistry } from '../decoder/registry'
+import { decodeTransaction as decodeTransactionCore } from '../decoder/transaction'
+import type { DecoderResult, ResultShared } from '../decoder/types'
+import { createDebug } from '../utils/debug'
+import type { ServerDecoderCaches } from './caches'
+import type { ServerDecoderOptions } from './types'
+
+const debug = createDebug('decoder:finishDecoding')
+
+/**
+ * Finish decoding a transaction by running enhancement phase
+ * This only does phase 2 (async plugins) - address resolution should be done separately
+ */
+export async function finishDecoding(
+  transaction: DecoderResult,
+  options: ServerDecoderOptions,
+  caches: ServerDecoderCaches
+): Promise<DecoderResult> {
+  const startTime = Date.now()
+  const {
+    timeoutMs = 5000, // Give more time for finishing
+    chain,
+  } = options
+
+  try {
+    // Check cache first
+    const txHash = transaction.hash || transaction.transactionHash
+    if (txHash) {
+      const cached = caches.getTransaction(txHash)
+      if (cached && cached.enhancementAttempted) {
+        return {
+          ...cached,
+          cached: true,
+          timeTaken: 0,
+        } as DecoderResult
+      }
+    }
+
+    // Get all plugins
+    const allPlugins = await pluginRegistry.getAll()
+    const schemaPlugins = pluginRegistry.getAllSchema()
+
+    const enhancedOptions = {
+      chain,
+      plugins: allPlugins,
+      schemaPlugins,
+      wrappers: [],
+      async: true,
+    }
+
+    // Wrappers and children must be removed when finishing decoding, because otherwise
+    // the decoder will build hierarchical structures which are infinite.
+    const {
+      wrappers,
+      children: _children,
+      addresses: _addresses,
+      ...transactionWithoutWrappers
+    } = transaction as DecoderResult & {
+      children?: unknown[]
+      wrappers?: unknown[]
+      addresses?: unknown[]
+    }
+
+    // Simply pass the entire transaction hierarchy to decodeTransactionCore
+    // It will handle children properly and return a fully enhanced copy
+    const enhancedResult = await decodeTransactionCore(
+      transactionWithoutWrappers as DecoderResult,
+      enhancedOptions
+    )
+
+    if (!enhancedResult) {
+      if (txHash) {
+        caches.setTransaction(txHash, {
+          ...transaction,
+          enhancementAttempted: true,
+        })
+      }
+      return transaction
+    }
+
+    const result = {
+      ...enhancedResult,
+      // Only add wrappers if there are any
+      ...((wrappers?.length || 0) > 0 ? { wrappers } : {}),
+      cached: false,
+      timeTaken: Date.now() - startTime,
+      enhancementAttempted: true,
+    } as DecoderResult
+
+    // Always update cache with the enhanced result
+    if (txHash) {
+      caches.setTransaction(txHash, result)
+    }
+
+    return result
+  } catch (error) {
+    console.error('Failed to finish decoding transaction:', error)
+    return {
+      ...createErrorResult(transaction),
+      phase: 'immediate',
+      cached: false,
+      timeTaken: Date.now() - startTime,
+    }
+  }
+}
+
+function createErrorResult(transaction: DecoderResult): DecoderResult {
+  return {
+    ...transaction,
+    resultType: 'error',
+    errorType: 'UNKNOWN',
+    sig: '0x' as `0x${string}`,
+    addresses: [],
+  } as DecoderResult
+}