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

package/src/decoder/THREE_PHASE_EXAMPLE.md

@@ -0,0 +1,108 @@
+# Three-Phase Transaction Decoding
+
+The decoder now supports a three-phase approach for optimal performance and user experience:
+
+## Phase 1: Sync Decoding (Immediate)
+- Uses known ABIs to decode transactions instantly
+- Returns basic transaction information
+- Status: `decoded`
+
+## Phase 2: ABI Retrieval (Async Plugins)
+- Fetches unknown ABIs from external sources
+- Enhances transaction with additional context
+- Status: `enhanced`
+
+## Phase 3: Address Resolution (Batch)
+- Resolves address metadata (profiles, assets, etc.)
+- Batches requests across multiple transactions for efficiency
+- Status: `complete`
+
+## Usage Examples
+
+### Single Transaction
+```typescript
+import { decodeTransaction } from '@lukso/decoder'
+
+const result = await decodeTransaction(transaction, {
+  plugins: defaultPlugins,
+  schemaPlugins: defaultSchemaPlugins,
+  chain: lukso,
+  addressResolver: myAddressResolver, // Optional
+})
+
+// Immediate access to sync-decoded data
+console.log(result.immediate)
+
+// Subscribe to progressive updates
+result.signal.subscribe((state) => {
+  switch (state.decodingStatus) {
+    case 'decoded':
+      // Phase 1 complete - basic decoding done
+      updateUI(state.data)
+      break
+    case 'enhanced':
+      // Phase 2 complete - ABI retrieval done
+      updateUIWithEnhancedData(state.data)
+      break
+    case 'complete':
+      // Phase 3 complete - addresses resolved
+      updateUIWithFullData(state.data)
+      break
+  }
+})
+```
+
+### Batch Transactions (Optimal for Address Resolution)
+```typescript
+const transactions = [tx1, tx2, tx3, tx4, tx5]
+
+const results = await decodeTransaction(transactions, {
+  plugins: defaultPlugins,
+  schemaPlugins: defaultSchemaPlugins,
+  chain: lukso,
+  addressResolver: myAddressResolver,
+})
+
+// All addresses from all transactions are batched together
+// Much more efficient than decoding one by one
+
+results.forEach((result, index) => {
+  console.log(`Transaction ${index}:`, result.immediate)
+  
+  result.signal.subscribe((state) => {
+    updateTransactionUI(index, state)
+  })
+})
+```
+
+### Address Resolver Interface
+```typescript
+class MyAddressResolver implements AddressResolver {
+  async resolveAddresses(addresses: DataKey[]): Promise<void> {
+    // Batch fetch address metadata
+    const chunks = chunk(addresses, 20) // GraphQL batch size
+    
+    for (const batch of chunks) {
+      const results = await fetchAddressMetadata(batch)
+      // Update your cache/store with results
+    }
+  }
+}
+```
+
+## Benefits
+
+1. **Immediate Feedback**: Users see decoded transaction info instantly
+2. **Progressive Enhancement**: UI updates as more data becomes available
+3. **Efficient Batching**: Address resolution is optimized across transactions
+4. **No Blocking**: Address resolution doesn't block ABI retrieval results
+
+## Status Flow
+
+```
+raw → decoded → enhanced → complete
+         ↓          ↓          ↓
+      (sync)    (async)   (addresses)
+```
+
+Each phase provides value without waiting for the next, ensuring the best possible user experience.

package/src/decoder/aggregation.ts

@@ -0,0 +1,218 @@
+import createDebug from '../utils/debug'
+import type { Aggregation, DecoderResult } from './types'
+
+/**
+ * Helper function to create a typed aggregation configuration
+ * @param config The aggregation configuration
+ * @returns A frozen aggregation object
+ */
+export function standardAggregation<T>(config: {
+  key: string
+  map: (tx: DecoderResult) => T | undefined
+  reduce: (state: T | undefined, mapped: T) => T
+  finalize: (state: T) => Omit<import('./types').ResultAggregate, 'resultType'>
+}): Aggregation<T> {
+  return Object.freeze(config)
+}
+
+/**
+ * Aggregation engine for processing transactions with map/reduce pattern
+ */
+export interface AggregationState<T = unknown> {
+  data: T
+  lastTransaction: DecoderResult
+}
+
+const debug = createDebug('decoder:aggregation')
+
+export class PluginAggregationEngine {
+  private plugins = new Map<string, import('./types').DecoderPlugin>()
+  private states = new Map<string, Map<string, AggregationState>>() // plugin -> key -> state
+
+  /**
+   * Register a plugin with aggregations
+   */
+  registerPlugin(plugin: import('./types').DecoderPlugin) {
+    if (plugin.name && plugin.aggregations && plugin.aggregations.length > 0) {
+      debug(
+        `Registering plugin ${plugin.name} with ${plugin.aggregations.length} aggregations`
+      )
+      this.plugins.set(plugin.name, plugin)
+      this.states.set(plugin.name, new Map())
+    }
+  }
+
+  /**
+   * Process a transaction through relevant aggregations
+   */
+  processTransaction(tx: DecoderResult) {
+    // Skip if no aggregations needed
+    if (!tx.aggregationKeys || tx.aggregationKeys.length === 0) return
+
+    // Process aggregations based on the full aggregation keys
+    for (const fullKey of tx.aggregationKeys) {
+      // Split the full key to get plugin name and aggregation key
+      const [pluginName, ...keyParts] = fullKey.split(':')
+      const aggregationKey = keyParts.join(':') // Handle keys with colons
+
+      const plugin = this.plugins.get(pluginName)
+      if (!plugin || !plugin.aggregations) {
+        debug(`processTransaction: No plugin found for ${pluginName}`)
+        continue
+      }
+
+      const pluginStates = this.states.get(pluginName)
+      if (!pluginStates) {
+        debug(`processTransaction: No states for plugin ${pluginName}`)
+        continue
+      }
+
+      const agg = plugin.aggregations.find((a) => a.key === aggregationKey)
+      if (!agg) {
+        debug(
+          `processTransaction: No aggregation found for key ${aggregationKey} in plugin ${pluginName}`
+        )
+        continue
+      }
+
+      const mapped = agg.map(tx)
+      if (mapped !== undefined) {
+        const currentState = pluginStates.get(aggregationKey)
+        if (!currentState) {
+          // First transaction for this aggregation
+          debug(
+            `processTransaction: First transaction for ${pluginName}:${aggregationKey}`
+          )
+          pluginStates.set(aggregationKey, {
+            data: mapped,
+            lastTransaction: tx,
+          })
+        } else {
+          // Update existing state
+          const newData = agg.reduce(currentState.data, mapped)
+          pluginStates.set(aggregationKey, {
+            data: newData,
+            lastTransaction: tx, // Always update to latest transaction
+          })
+        }
+      } else {
+        debug(
+          `processTransaction: map returned undefined for ${pluginName}:${aggregationKey}`
+        )
+      }
+    }
+  }
+
+  /**
+   * Process a batch of transactions
+   */
+  processBatch(txs: DecoderResult[]) {
+    debug(`Processing batch of ${txs.length} transactions`)
+    let processedCount = 0
+    for (const tx of txs) {
+      this.processTransaction(tx)
+      if (tx.aggregationKeys && tx.aggregationKeys.length > 0) {
+        processedCount++
+      }
+    }
+    debug(`Processed ${processedCount} transactions with aggregationKeys`)
+  }
+
+  /**
+   * Get finalized result for a specific plugin and aggregation key
+   */
+  getResult(pluginName: string, key: string): DecoderResult | undefined {
+    const plugin = this.plugins.get(pluginName)
+    const pluginStates = this.states.get(pluginName)
+
+    if (!plugin || !pluginStates) return undefined
+
+    const agg = plugin.aggregations?.find((a) => a.key === key)
+    const state = pluginStates.get(key)
+
+    if (!agg || state === undefined) return undefined
+
+    // Merge aggregation result with last transaction metadata
+    const aggregationResult = agg.finalize(state.data)
+
+    return {
+      ...state.lastTransaction,
+      ...aggregationResult,
+      resultType: 'aggregate' as const,
+    } as DecoderResult
+  }
+
+  /**
+   * Get all aggregation results
+   */
+  getAllResults(): Array<{
+    plugin: string
+    key: string
+    result: DecoderResult
+  }> {
+    const results: Array<{
+      plugin: string
+      key: string
+      result: DecoderResult
+    }> = []
+
+    for (const [pluginName, plugin] of this.plugins) {
+      const pluginStates = this.states.get(pluginName)
+
+      // Skip if this plugin has no states (hasn't processed any transactions yet)
+      if (!pluginStates) {
+        continue
+      }
+
+      for (const agg of plugin.aggregations || []) {
+        const state = pluginStates.get(agg.key)
+        if (state !== undefined) {
+          results.push({
+            plugin: pluginName,
+            key: agg.key,
+            result: {
+              ...state.lastTransaction,
+              ...agg.finalize(state.data),
+              resultType: 'aggregate' as const,
+            } as DecoderResult,
+          })
+        }
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Clear all aggregation states
+   */
+  clear() {
+    for (const states of this.states.values()) {
+      states.clear()
+    }
+  }
+
+  /**
+   * Clear states for a specific plugin
+   */
+  clearPlugin(pluginName: string) {
+    this.states.get(pluginName)?.clear()
+  }
+
+  /**
+   * Get current state (for persistence)
+   */
+  getStates(): Map<string, Map<string, AggregationState>> {
+    return new Map(this.states)
+  }
+
+  /**
+   * Restore states (from persistence)
+   */
+  restoreStates(states: Map<string, Map<string, AggregationState>>) {
+    // Merge states instead of replacing to preserve plugin initialization
+    for (const [pluginName, pluginStates] of states) {
+      this.states.set(pluginName, new Map(pluginStates))
+    }
+  }
+}

package/src/decoder/browserCache.ts

@@ -0,0 +1,237 @@
+/**
+ * Browser Cache API implementation of DecoderCache interface
+ * Uses the standard Cache API available in browsers and service workers
+ */
+
+import type { CacheEntry, CacheOptions, DecoderCache } from './cache'
+
+/**
+ * Options for creating a browser cache instance
+ */
+export interface BrowserCacheOptions {
+  /** Name of the cache to open */
+  cacheName?: string
+  /** Default TTL in milliseconds */
+  ttl?: number
+  /** Default error TTL in milliseconds */
+  errorTTL?: number
+  /** Default stale-while-revalidate time in milliseconds */
+  staleWhileRevalidate?: number
+}
+
+/**
+ * Browser Cache API implementation of DecoderCache
+ */
+export class BrowserDecoderCache implements DecoderCache {
+  private cacheName: string
+  private cachePromise: Promise<Cache>
+  private promises: Map<string, Promise<unknown>>
+  private defaultTTL: number
+  private defaultErrorTTL: number
+  private defaultStaleWhileRevalidate?: number
+
+  constructor(options: BrowserCacheOptions = {}) {
+    this.cacheName = options.cacheName ?? 'decoder-cache-v1'
+    this.defaultTTL = options.ttl ?? 5 * 60 * 1000 // 5 minutes
+    this.defaultErrorTTL = options.errorTTL ?? 30 * 1000 // 30 seconds
+    this.defaultStaleWhileRevalidate = options.staleWhileRevalidate
+    this.promises = new Map()
+
+    // Check if Cache API is available
+    if (typeof caches === 'undefined') {
+      throw new Error('Cache API not available in this environment')
+    }
+
+    this.cachePromise = caches.open(this.cacheName)
+  }
+
+  private getUrl(key: string): string {
+    // Create a fake URL for cache storage
+    return `https://decoder.cache/${encodeURIComponent(key)}`
+  }
+
+  async get<T>(key: string): Promise<CacheEntry<T> | undefined> {
+    try {
+      const cache = await this.cachePromise
+      const response = await cache.match(this.getUrl(key))
+
+      if (!response) {
+        return undefined
+      }
+
+      const entry = (await response.json()) as CacheEntry<T>
+
+      // Check if expired
+      if (entry.expires && Date.now() > entry.expires) {
+        // Don't delete here as it might be used for stale-while-revalidate
+        return undefined
+      }
+
+      return entry
+    } catch (error) {
+      console.error('Browser cache get error:', error)
+      return undefined
+    }
+  }
+
+  async set<T>(key: string, value: T, options?: CacheOptions): Promise<void> {
+    const now = Date.now()
+    const ttl =
+      options?.ttl ?? (options?.errorTTL ? options.errorTTL : this.defaultTTL)
+    const isError = options?.errorTTL !== undefined
+
+    const entry: CacheEntry<T> = {
+      value,
+      expires: now + ttl,
+      isError,
+    }
+
+    const staleWhileRevalidate =
+      options?.staleWhileRevalidate ?? this.defaultStaleWhileRevalidate
+    if (staleWhileRevalidate) {
+      entry.stale = now + ttl + staleWhileRevalidate
+    }
+
+    try {
+      const cache = await this.cachePromise
+      const response = new Response(JSON.stringify(entry), {
+        headers: {
+          'Content-Type': 'application/json',
+          // Set cache control headers for browser caching
+          'Cache-Control': `private, max-age=${Math.ceil(ttl / 1000)}`,
+        },
+      })
+
+      await cache.put(this.getUrl(key), response)
+    } catch (error) {
+      console.error('Browser cache set error:', error)
+      throw error
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      const cache = await this.cachePromise
+      await cache.delete(this.getUrl(key))
+    } catch (error) {
+      console.error('Browser cache delete error:', error)
+    }
+  }
+
+  async getMany<T>(keys: string[]): Promise<Map<string, CacheEntry<T>>> {
+    const result = new Map<string, CacheEntry<T>>()
+
+    // Cache API doesn't support batch operations, so we do it in parallel
+    const promises = keys.map(async (key) => {
+      const entry = await this.get<T>(key)
+      if (entry) {
+        result.set(key, entry)
+      }
+    })
+
+    await Promise.all(promises)
+    return result
+  }
+
+  async setMany<T>(
+    entries: Array<{ key: string; value: T; options?: CacheOptions }>
+  ): Promise<void> {
+    // Cache API doesn't support batch operations, so we do it in parallel
+    const promises = entries.map(({ key, value, options }) =>
+      this.set(key, value, options)
+    )
+
+    await Promise.all(promises)
+  }
+
+  async clear(): Promise<void> {
+    // Clear in-flight promises
+    this.promises.clear()
+
+    try {
+      // Delete the entire cache
+      await caches.delete(this.cacheName)
+      // Re-open it
+      this.cachePromise = caches.open(this.cacheName)
+    } catch (error) {
+      console.error('Browser cache clear error:', error)
+    }
+  }
+
+  async getOrSet<T>(
+    key: string,
+    factory: (signal?: AbortSignal) => Promise<T>,
+    options?: CacheOptions & { signal?: AbortSignal }
+  ): Promise<T> {
+    // Check cache first
+    const cached = await this.get<T>(key)
+    const now = Date.now()
+
+    // If we have a valid (non-expired) entry, return it
+    if (cached && (!cached.expires || now < cached.expires)) {
+      return cached.value
+    }
+
+    // If we have a stale entry and stale-while-revalidate is enabled
+    if (
+      cached &&
+      cached.stale &&
+      now < cached.stale &&
+      !this.promises.has(key)
+    ) {
+      // Return stale value and revalidate in background
+      const backgroundPromise = factory(options?.signal)
+        .then(async (fresh) => {
+          await this.set(key, fresh, options)
+          return fresh
+        })
+        .catch(() => {
+          // On error, keep the stale value
+          return cached.value
+        })
+        .finally(() => {
+          this.promises.delete(key)
+        })
+
+      this.promises.set(key, backgroundPromise)
+      return cached.value
+    }
+
+    // Check if we have an in-flight promise
+    const existingPromise = this.promises.get(key) as Promise<T> | undefined
+    if (existingPromise) {
+      return existingPromise
+    }
+
+    // No valid cache entry, fetch new value
+    const promise = factory(options?.signal)
+      .then(async (value) => {
+        await this.set(key, value, options)
+        return value
+      })
+      .catch(async (error) => {
+        // Cache the error with shorter TTL
+        await this.set(key, error as T, {
+          ...options,
+          ttl: options?.errorTTL ?? this.defaultErrorTTL,
+          errorTTL: options?.errorTTL ?? this.defaultErrorTTL,
+        })
+        throw error
+      })
+      .finally(() => {
+        this.promises.delete(key)
+      })
+
+    this.promises.set(key, promise)
+    return promise as Promise<T>
+  }
+}
+
+/**
+ * Create a browser cache instance
+ */
+export function createBrowserCache(
+  options?: BrowserCacheOptions
+): DecoderCache {
+  return new BrowserDecoderCache(options)
+}

package/src/decoder/cache/README.md

@@ -0,0 +1,126 @@
+# Decoder Cache Implementations
+
+This directory contains three cache implementations for the decoder, all implementing the `DecoderCache` interface:
+
+## 1. LRU Cache (Memory-based)
+
+Best for Node.js environments and development.
+
+```typescript
+import { createLRUCache } from '@lukso/transaction-decoder'
+
+const cache = createLRUCache({
+  max: 1000,              // Maximum items in cache
+  ttl: 5 * 60 * 1000,     // 5 minutes TTL
+  errorTTL: 30 * 1000,    // 30 seconds for errors
+  staleWhileRevalidate: 60 * 1000  // 1 minute stale time
+})
+
+// Use with decoder
+const decoded = await decodeTransaction(tx, {
+  async: AsyncOperations.ENABLE_PLUGINS,
+  cache
+})
+```
+
+## 2. KV Cache (Key-Value Store)
+
+Perfect for Cloudflare Workers or other KV-based environments.
+
+```typescript
+import { createKVCache } from '@lukso/transaction-decoder'
+
+// Cloudflare Workers example
+const cache = createKVCache({
+  kv: env.MY_KV_NAMESPACE,  // Your KV namespace binding
+  prefix: 'decoder:',       // Key prefix
+  ttl: 5 * 60 * 1000,
+  errorTTL: 30 * 1000
+})
+
+// Deno KV example
+const kv = await Deno.openKv()
+const cache = createKVCache({
+  kv: {
+    get: (key) => kv.get([key]).then(r => r.value),
+    put: (key, value, opts) => kv.set([key], value, { 
+      expireIn: opts?.expirationTtl ? opts.expirationTtl * 1000 : undefined 
+    }),
+    delete: (key) => kv.delete([key])
+  }
+})
+```
+
+## 3. Browser Cache (Cache API)
+
+Ideal for Progressive Web Apps and Service Workers.
+
+```typescript
+import { createBrowserCache } from '@lukso/transaction-decoder'
+
+const cache = createBrowserCache({
+  cacheName: 'decoder-v1',  // Cache name
+  ttl: 5 * 60 * 1000,
+  errorTTL: 30 * 1000,
+  staleWhileRevalidate: 60 * 1000
+})
+
+// Works in service workers too!
+self.addEventListener('fetch', (event) => {
+  // Use cache for decoder operations
+})
+```
+
+## Features
+
+All cache implementations support:
+
+- **Promise deduplication**: Prevents duplicate requests for the same resource
+- **Stale-while-revalidate**: Serves stale content while fetching fresh data
+- **Error caching**: Caches errors with shorter TTL to allow retries
+- **AbortSignal support**: Cancellable operations for SSR timeouts
+- **Batch operations**: `getMany` and `setMany` for efficiency
+
+## SSR Example with Timeout
+
+```typescript
+import { createLRUCache, AsyncOperations } from '@lukso/transaction-decoder'
+
+// Create cache with SSR-friendly settings
+const cache = createLRUCache({
+  max: 500,
+  ttl: 60 * 1000,        // 1 minute
+  errorTTL: 10 * 1000,   // 10 seconds for errors
+  staleWhileRevalidate: 5 * 60 * 1000  // 5 minutes
+})
+
+// Decode with timeout
+const controller = new AbortController()
+const timeout = setTimeout(() => controller.abort(), 100) // 100ms timeout
+
+try {
+  const decoded = await decodeTransaction(tx, {
+    async: AsyncOperations.ENABLE_PLUGINS, // Only ABI fetching
+    cache,
+    signal: controller.signal
+  })
+  clearTimeout(timeout)
+  
+  // Continue with address resolution on client if needed
+} catch (error) {
+  if (error.name === 'AbortError') {
+    // Timeout reached, return partial result
+  }
+}
+```
+
+## Auto Cache Selection
+
+Use `createAutoCache()` to automatically select the best cache for your environment:
+
+```typescript
+import { createAutoCache } from '@lukso/transaction-decoder'
+
+const cache = createAutoCache()
+// Returns BrowserCache in browser, LRUCache in Node.js
+```