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

package/src/core/instance.ts

@@ -0,0 +1,33 @@
+import type { IDataModel, IDataModelConsumer } from '../types'
+import { createConsumerProxy, DataModel } from './dataModel'
+
+// Create the singleton instance
+const dataModelInstance = new DataModel()
+
+// Freeze the prototype and constructor to prevent prototype pollution
+Object.freeze(DataModel.prototype)
+Object.freeze(DataModel)
+
+// Export the full model for data providers to import
+// Note: We don't freeze dataModel as data providers need to modify it
+export const dataModel: IDataModel = dataModelInstance
+
+// Create consumer-only proxy for public API (frozen)
+export const consumerModel: IDataModelConsumer =
+  createConsumerProxy(dataModelInstance)
+
+// Export a function to optionally create global instance
+// This allows consumers to control when/if the global is created
+export function createGlobalInstance(): void {
+  if (typeof window !== 'undefined') {
+    // Create consumer-only proxy for window
+    const consumerProxy = createConsumerProxy(dataModelInstance)
+
+    Object.defineProperty(window, 'TransactionDecoder', {
+      value: consumerProxy,
+      writable: false,
+      configurable: false,
+      enumerable: true,
+    })
+  }
+}

package/src/core/integrateDecoder.ts

@@ -0,0 +1,325 @@
+import { effect } from '@preact/signals-core'
+import type { Address, Transaction } from 'viem'
+import { lukso } from 'viem/chains'
+import { decodeTransaction } from '../decoder/decodeTransaction'
+import { defaultPlugins, defaultSchemaPlugins } from '../decoder/plugins'
+import type { DecoderOptions, DecoderResult } from '../decoder/types'
+import type { DataKey, EnhancedInfo, IDataModel } from '../types'
+import { collectDataKeys } from './addressCollector'
+
+/**
+ * Configuration for decoder integration
+ */
+export interface DecoderIntegrationConfig {
+  dataModel: IDataModel
+  decoderOptions?: Partial<DecoderOptions>
+  addressCache?: AddressCache
+}
+
+/**
+ * External cache interface for address data
+ */
+export interface AddressCache {
+  get(key: DataKey): Promise<EnhancedInfo | undefined>
+  set(key: DataKey, value: EnhancedInfo): Promise<void>
+  has(key: DataKey): Promise<boolean>
+  delete(key: DataKey): Promise<void>
+  clear(): Promise<void>
+}
+
+/**
+ * Integrate the decoder with the data model
+ * Handles progressive transaction enhancement and address population
+ */
+export class DecoderIntegration {
+  private dataModel: IDataModel
+  private decoderOptions: DecoderOptions
+  private addressCache?: AddressCache
+
+  constructor(config: DecoderIntegrationConfig) {
+    this.dataModel = config.dataModel
+    this.addressCache = config.addressCache
+
+    // Set up default decoder options
+    this.decoderOptions = {
+      plugins: defaultPlugins,
+      schemaPlugins: defaultSchemaPlugins,
+      wrappers: [],
+      chain: config.decoderOptions?.chain || lukso,
+      ...config.decoderOptions,
+    }
+  }
+
+  /**
+   * Add and decode a transaction
+   * @param transaction - Raw transaction data
+   * @returns Transaction signal that updates as decoding progresses
+   */
+  async addAndDecodeTransaction(transaction: DecoderResult) {
+    // Add transaction to data model
+    const signal = this.dataModel.addTransactions(transaction)
+
+    // Create fresh wrappers array for this transaction
+    const transactionOptions: DecoderOptions = {
+      ...this.decoderOptions,
+      wrappers: [], // Fresh array for collecting wrappers in this decode hierarchy
+    }
+
+    // Start decoding process
+    const { signal: decodingSignal } = await decodeTransaction(
+      transaction,
+      transactionOptions
+    )
+
+    // Update transaction data as decoding progresses
+    effect(() => {
+      const state = decodingSignal.value
+      if (state.data) {
+        const decodedResult = state.data as DecoderResult
+
+        // Process any collected wrappers
+        if (transactionOptions.wrappers.length > 0) {
+          // Only certain result types support wrappers
+          if (
+            'wrappers' in decodedResult &&
+            typeof decodedResult === 'object'
+          ) {
+            ;(decodedResult as Record<string, unknown>).wrappers =
+              transactionOptions.wrappers
+          }
+
+          // Extract addresses from wrappers
+          for (const wrapper of transactionOptions.wrappers) {
+            this.updateAddressesFromDecoded(wrapper as DecoderResult)
+          }
+        }
+
+        // Flatten nested batch transactions if configured
+        const processedResult = this.flattenBatchTransactions(decodedResult)
+
+        if (transaction.hash) {
+          this.dataModel.updateTransactionData(
+            transaction.hash,
+            processedResult,
+            0 // decoder index
+          )
+        }
+
+        // Extract and update addresses from decoded data
+        this.updateAddressesFromDecoded(processedResult)
+      }
+    })
+
+    return signal
+  }
+
+  /**
+   * Add and decode multiple transactions
+   * @param transactions - Array of raw transactions
+   * @returns Array of transaction signals
+   */
+  async addAndDecodeTransactions(transactions: DecoderResult[]) {
+    // Add all transactions to data model
+    const signals = this.dataModel.addTransactions(transactions)
+
+    // Start decoding for each transaction
+    const decodingPromises = transactions.map(async (tx, index) => {
+      // Create fresh wrappers array for each transaction
+      const transactionOptions: DecoderOptions = {
+        ...this.decoderOptions,
+        wrappers: [], // Fresh array for collecting wrappers in this decode hierarchy
+      }
+
+      const { signal: decodingSignal } = await decodeTransaction(
+        tx,
+        transactionOptions
+      )
+
+      // Update transaction data as decoding progresses
+      effect(() => {
+        const state = decodingSignal.value
+        if (state.data) {
+          const decodedResult = state.data as DecoderResult
+
+          // Process any collected wrappers
+          if (transactionOptions.wrappers.length > 0) {
+            // Only certain result types support wrappers
+            if (
+              'wrappers' in decodedResult &&
+              typeof decodedResult === 'object'
+            ) {
+              ;(decodedResult as Record<string, unknown>).wrappers =
+                transactionOptions.wrappers
+            }
+
+            // Extract addresses from wrappers
+            for (const wrapper of transactionOptions.wrappers) {
+              this.updateAddressesFromDecoded(wrapper as DecoderResult)
+            }
+          }
+
+          // Flatten nested batch transactions if configured
+          const processedResult = this.flattenBatchTransactions(decodedResult)
+
+          if (tx.hash) {
+            this.dataModel.updateTransactionData(
+              tx.hash,
+              processedResult,
+              0 // decoder index
+            )
+          }
+
+          // Extract and update addresses from decoded data
+          this.updateAddressesFromDecoded(processedResult)
+        }
+      })
+
+      return decodingSignal
+    })
+
+    await Promise.all(decodingPromises)
+    return signals
+  }
+
+  /**
+   * Extract and register addresses from decoded transaction data
+   */
+  private async updateAddressesFromDecoded(decodedData: DecoderResult) {
+    const addresses = collectDataKeys(decodedData)
+
+    // Check cache and inject into data model
+    for (const address of addresses) {
+      // Check cache first
+      if (this.addressCache) {
+        const cached = await this.addressCache.get(address)
+        if (cached) {
+          // Inject into data model
+          this.dataModel.updateData(cached)
+        }
+      }
+
+      // Ensure the address signal exists (creates empty signal if not)
+      // This allows views to getAddress() without errors
+      this.dataModel.getAddress(address)
+    }
+  }
+
+  /**
+   * Flatten nested batch transactions
+   * If a batch contains another batch as a child, flatten all sub-transactions into the parent's children
+   *
+   * Structure:
+   * - Wrappers: The "invisible" execute functions (execute, executeRelayCall, etc.) that wrap the actual transaction
+   * - Children: The actual transactions being executed
+   *
+   * Result:
+   * - Single transaction: { resultType: 'execute', wrappers: [...] }
+   * - Batch transaction: { resultType: 'executeBatch', children: [flat list], wrappers: [...] }
+   *
+   * This ensures only ONE level of batch with all transactions flattened
+   */
+  private flattenBatchTransactions(result: DecoderResult): DecoderResult {
+    // Only process batch result types
+    if (
+      result.resultType !== 'executeBatch' &&
+      result.resultType !== 'setDataBatch'
+    ) {
+      return result
+    }
+
+    // Type guard to ensure we have children property
+    if (!('children' in result) || !Array.isArray(result.children)) {
+      return result
+    }
+
+    // Flatten children - if any child is also a batch, merge its children up
+    const flattenedChildren: unknown[] = []
+
+    for (const child of result.children) {
+      if (typeof child === 'object' && child && 'resultType' in child) {
+        const childResult = child as Record<string, unknown>
+        if (
+          childResult.resultType === 'executeBatch' ||
+          childResult.resultType === 'setDataBatch'
+        ) {
+          // This child is also a batch - flatten its children into our array
+          if (
+            'children' in childResult &&
+            Array.isArray(childResult.children)
+          ) {
+            flattenedChildren.push(...childResult.children)
+          }
+        } else {
+          // Regular child - keep as is
+          flattenedChildren.push(child)
+        }
+      }
+    }
+
+    // Return updated result with flattened children
+    return {
+      ...result,
+      children: flattenedChildren,
+    } as DecoderResult
+  }
+
+  /**
+   * Load missing address data
+   * This would be called by an external service that fetches address data
+   */
+  async loadAddressData(addressData: EnhancedInfo[]) {
+    // Update data model
+    this.dataModel.injectData(addressData)
+
+    // Update cache if available
+    if (this.addressCache) {
+      await Promise.all(
+        addressData.map((data) => {
+          const key: DataKey = data.tokenId
+            ? (`${data.address}:${data.tokenId}` as DataKey)
+            : (data.address as DataKey)
+          return this.addressCache?.set(key, data) ?? Promise.resolve()
+        })
+      )
+    }
+  }
+
+  /**
+   * Get addresses that need to be fetched
+   */
+  getMissingAddresses(): DataKey[] {
+    return this.dataModel.getMissingKeys()
+  }
+
+  /**
+   * Get addresses currently being loaded
+   */
+  getLoadingAddresses(): DataKey[] {
+    return this.dataModel.getLoadingKeys()
+  }
+}
+
+/**
+ * Create a simple in-memory address cache
+ */
+export function createMemoryAddressCache(): AddressCache {
+  const cache = new Map<string, EnhancedInfo>()
+
+  return {
+    async get(key: DataKey) {
+      return cache.get(key)
+    },
+    async set(key: DataKey, value: EnhancedInfo) {
+      cache.set(key, value)
+    },
+    async has(key: DataKey) {
+      return cache.has(key)
+    },
+    async delete(key: DataKey) {
+      cache.delete(key)
+    },
+    async clear() {
+      cache.clear()
+    },
+  }
+}

package/src/data.ts

@@ -0,0 +1,70 @@
+/**
+ * @lukso/transaction-decoder/data - Data Provider API
+ *
+ * This module exports functions for data providers to manage transaction and address data.
+ * Consumers should use the main '@lukso/transaction-decoder' import instead.
+ */
+
+import { dataModel } from './core/instance'
+
+// Export provider-specific types
+export type {
+  AddressState,
+  DataKey,
+  DataModelOptions,
+  DecoderResult,
+  EnhancedInfo,
+  IDataModel,
+  TransactionState,
+} from './types'
+
+// Export data management methods
+export const addTransactions = dataModel.addTransactions.bind(dataModel)
+export const updateTransactionData =
+  dataModel.updateTransactionData.bind(dataModel)
+
+// Address data management
+export const injectData = dataModel.injectData.bind(dataModel)
+export const updateData = dataModel.updateData.bind(dataModel)
+export const setLoading = dataModel.setLoading.bind(dataModel)
+export const setError = dataModel.setError.bind(dataModel)
+
+// Collection management
+export const getMissingKeys = dataModel.getMissingKeys.bind(dataModel)
+export const getLoadingKeys = dataModel.getLoadingKeys.bind(dataModel)
+
+// Maintenance methods
+export const clear = dataModel.clear.bind(dataModel)
+export const remove = dataModel.remove.bind(dataModel)
+
+// Also export the full data model for advanced usage
+export { dataModel }
+
+// Export factory function for creating new instances
+export { createDataModel } from './core/dataModel'
+// Export useful constants for plugin developers
+export { defaultSchema, IPFS_GATEWAY } from './decoder/constants'
+
+export { decodeTransaction } from './decoder/decodeTransaction'
+export { decodeEvent } from './decoder/events'
+export {
+  decodeKeyValue,
+  decodeKeyValueRaw,
+  standardSchemaPlugin,
+} from './decoder/plugins'
+// Export additional types for plugin development
+export type {
+  ArrayArgs,
+  CustomDecodeFunctionDataReturn,
+  Info,
+  NamedArgs,
+  ResultShared,
+  ResultType,
+} from './decoder/types'
+// Export plugin development utilities
+export {
+  createNamedArgs,
+  customDecodeFunctionData,
+  extractAddress,
+  getPublicClient,
+} from './decoder/utils'

package/src/decoder/GENERATOR_PROPOSAL.md

@@ -0,0 +1,182 @@
+# Generator-Based Transaction Decoder Proposal
+
+## Current Limitations
+
+1. **State Updates**: Currently only yields state at two points:
+   - Initial sync decode (partial)
+   - Final async decode (complete)
+
+2. **Address Batching**: Single transactions typically yield 1-5 addresses, making batch resolution inefficient
+
+## Proposed Generator Approach
+
+```typescript
+// Generator that yields intermediate states
+async function* decodeTransactionGenerator(
+  transaction: Transaction,
+  options: DecoderOptions
+): AsyncGenerator<DecoderState, DecoderResult, unknown> {
+  
+  // Phase 1: Initial sync decode
+  yield {
+    phase: 'initial',
+    status: 'decoding',
+    addresses: collectDataKeys(transaction),
+  }
+  
+  const syncResult = await decodeSyncPlugins(transaction, options)
+  
+  yield {
+    phase: 'sync-complete',
+    status: 'partial',
+    result: syncResult,
+    addresses: collectDataKeys(syncResult),
+  }
+  
+  // Phase 2: Async plugins one by one
+  for (const plugin of options.plugins.filter(p => p.async)) {
+    yield {
+      phase: 'async-plugin',
+      status: 'enhancing',
+      pluginName: plugin.name,
+      currentResult: syncResult,
+    }
+    
+    const enhanced = await plugin.enhance(syncResult, options)
+    if (enhanced) {
+      syncResult = enhanced
+      yield {
+        phase: 'async-plugin-complete',
+        status: 'partial',
+        result: enhanced,
+        addresses: collectDataKeys(enhanced),
+      }
+    }
+  }
+  
+  // Phase 3: Event decoding
+  if (transaction.logs?.length) {
+    yield {
+      phase: 'events',
+      status: 'decoding-events',
+      eventCount: transaction.logs.length,
+    }
+    
+    const decodedLogs = await decodeAllEvents(transaction.logs, options)
+    syncResult.logs = decodedLogs
+  }
+  
+  return syncResult
+}
+```
+
+## Batching Strategy for Address Resolution
+
+### Option 1: Transaction Accumulator
+```typescript
+class TransactionAccumulator {
+  private pendingAddresses = new Set<DataKey>()
+  private addressCallbacks = new Map<DataKey, Array<(data: EnhancedInfo) => void>>()
+  private batchTimer?: NodeJS.Timeout
+  
+  async addTransaction(addresses: DataKey[]): Promise<void> {
+    addresses.forEach(addr => this.pendingAddresses.add(addr))
+    
+    // Start batch timer if not running
+    if (!this.batchTimer) {
+      this.batchTimer = setTimeout(() => this.flush(), 50) // 50ms debounce
+    }
+    
+    // Force flush if batch is full
+    if (this.pendingAddresses.size >= 20) {
+      await this.flush()
+    }
+  }
+  
+  private async flush() {
+    if (this.pendingAddresses.size === 0) return
+    
+    const batch = Array.from(this.pendingAddresses)
+    this.pendingAddresses.clear()
+    
+    const results = await fetchAddressBatch(batch)
+    // Notify callbacks...
+  }
+}
+```
+
+### Option 2: Cross-Transaction Batching
+```typescript
+// In DecoderIntegration
+class DecoderIntegration {
+  private addressQueue = new BatchQueue<DataKey, EnhancedInfo>({
+    batchSize: 20,
+    batchDelay: 50,
+    fetchBatch: async (keys) => {
+      return this.addressResolver.resolveAddresses(keys)
+    }
+  })
+  
+  async decodeTransactions(transactions: Transaction[]): Promise<Signal<TransactionState>[]> {
+    // Collect all addresses upfront
+    const allAddresses = transactions.flatMap(tx => collectDataKeys(tx))
+    
+    // Pre-warm the cache
+    await this.addressQueue.addMany(allAddresses)
+    
+    // Now decode with cached data available
+    return Promise.all(transactions.map(tx => this.decodeTransaction(tx)))
+  }
+}
+```
+
+## Hybrid Approach Recommendation
+
+1. **Keep current two-phase approach** for single transactions
+   - Simpler API
+   - Less overhead for common case
+   
+2. **Add batch decoder** for multiple transactions
+   ```typescript
+   export async function decodeTransactionBatch(
+     transactions: Transaction[],
+     options: DecoderOptions
+   ): Promise<TransactionDecoderResult[]> {
+     // Pre-collect all addresses
+     const allAddresses = new Set<DataKey>()
+     transactions.forEach(tx => {
+       collectDataKeys(tx).forEach(addr => allAddresses.add(addr))
+     })
+     
+     // Pre-fetch in efficient batches
+     if (options.addressResolver) {
+       await options.addressResolver.preloadAddresses(Array.from(allAddresses))
+     }
+     
+     // Decode all with cached data
+     return Promise.all(transactions.map(tx => decodeTransaction(tx, options)))
+   }
+   ```
+
+3. **Optional generator API** for advanced use cases
+   ```typescript
+   export async function* decodeTransactionStream(
+     transaction: Transaction,
+     options: DecoderOptions & { yieldInterval?: number }
+   ): AsyncGenerator<TransactionState, void, unknown> {
+     // Yield states as decoding progresses
+   }
+   ```
+
+## Benefits
+
+1. **Efficiency**: Batch API optimizes address resolution across transactions
+2. **Simplicity**: Current API remains simple for single transaction use case  
+3. **Flexibility**: Generator API available for advanced real-time UI updates
+4. **Progressive**: Each API level builds on the previous
+
+## Implementation Priority
+
+1. First: Add `decodeTransactionBatch` for efficient multi-transaction decoding
+2. Second: Optimize `AddressResolver` to support pre-loading
+3. Third: Consider generator API based on real-world usage patterns