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

package/src/decoder/cache/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Cache implementations for the decoder
+ */
+
+export {
+  type BrowserCacheOptions,
+  BrowserDecoderCache,
+  createBrowserCache,
+} from '../browserCache'
+// Re-export cache interface and types
+export * from '../cache'
+export {
+  createKVCache,
+  type KVCacheOptions,
+  KVDecoderCache,
+  type KVStore,
+} from '../kvCache'
+// Export cache implementations
+export {
+  createLRUCache,
+  type LRUCacheOptions,
+  LRUDecoderCache,
+} from '../lruCache'
+
+import { createBrowserCache } from '../browserCache'
+import type { DecoderCache } from '../cache'
+import { createLRUCache } from '../lruCache'
+
+/**
+ * Create a cache instance based on the environment
+ */
+export function createAutoCache(): DecoderCache {
+  // Check for browser environment
+  if (typeof window !== 'undefined' && typeof caches !== 'undefined') {
+    try {
+      return createBrowserCache()
+    } catch {
+      // Fall through to LRU
+    }
+  }
+
+  // Default to LRU cache
+  return createLRUCache()
+}

package/src/decoder/cache.ts

@@ -0,0 +1,139 @@
+/**
+ * Cache interface for decoder with support for different backends
+ * (LRU, Cloudflare KV, Redis, etc.)
+ */
+
+import type { Hex } from 'viem'
+
+/**
+ * Cache entry with metadata
+ */
+export interface CacheEntry<T> {
+  /** The cached value */
+  value: T
+  /** Timestamp when the entry expires (ms since epoch) */
+  expires?: number
+  /** Timestamp when the entry becomes stale (for stale-while-revalidate) */
+  stale?: number
+  /** Whether this entry resulted from an error */
+  isError?: boolean
+}
+
+/**
+ * Options for cache operations
+ */
+export interface CacheOptions {
+  /** Time to live in milliseconds */
+  ttl?: number
+  /** TTL for error responses (typically shorter) */
+  errorTTL?: number
+  /** Time in ms after which the value is stale but still usable */
+  staleWhileRevalidate?: number
+}
+
+/**
+ * Generic cache interface that can be implemented by different backends
+ */
+export interface DecoderCache {
+  /**
+   * Get a value from the cache
+   */
+  get<T>(key: string): Promise<CacheEntry<T> | undefined>
+
+  /**
+   * Set a value in the cache
+   */
+  set<T>(key: string, value: T, options?: CacheOptions): Promise<void>
+
+  /**
+   * Delete a value from the cache
+   */
+  delete(key: string): Promise<void>
+
+  /**
+   * Get multiple values at once (for batch operations)
+   */
+  getMany?<T>(keys: string[]): Promise<Map<string, CacheEntry<T>>>
+
+  /**
+   * Set multiple values at once (for batch operations)
+   */
+  setMany?<T>(
+    entries: Array<{ key: string; value: T; options?: CacheOptions }>
+  ): Promise<void>
+
+  /**
+   * Clear all entries (optional)
+   */
+  clear?(): Promise<void>
+
+  /**
+   * Get or set with automatic promise deduplication
+   * This is the main method for async operations
+   */
+  getOrSet<T>(
+    key: string,
+    factory: (signal?: AbortSignal) => Promise<T>,
+    options?: CacheOptions & { signal?: AbortSignal }
+  ): Promise<T>
+}
+
+/**
+ * In-flight promise tracking for deduplication
+ */
+export class PromiseTracker<T> {
+  private promises = new Map<string, Promise<T>>()
+
+  /**
+   * Get or create a promise for the given key
+   */
+  async getOrCreate(key: string, factory: () => Promise<T>): Promise<T> {
+    const existing = this.promises.get(key)
+    if (existing) {
+      return existing
+    }
+
+    const promise = factory().finally(() => {
+      // Clean up after completion
+      this.promises.delete(key)
+    })
+
+    this.promises.set(key, promise)
+    return promise
+  }
+
+  /**
+   * Check if a promise is in flight
+   */
+  has(key: string): boolean {
+    return this.promises.has(key)
+  }
+
+  /**
+   * Clear all tracked promises
+   */
+  clear(): void {
+    this.promises.clear()
+  }
+}
+
+/**
+ * Helper to create cache keys
+ */
+export function makeCacheKey(type: string, ...parts: (string | Hex)[]): string {
+  return `${type}:${parts.join(':')}`
+}
+
+/**
+ * Cache key prefixes for different resource types
+ */
+export enum CacheKeyPrefix {
+  ABI = 'abi',
+  FUNCTION_SIGNATURE = 'sig',
+  ADDRESS = 'addr',
+  TOKEN = 'token',
+  PROFILE = 'profile',
+  EXTERNAL_DATA = 'ext',
+  SCHEMA = 'schema',
+  CONTRACT_METADATA = 'contract-meta',
+}

package/src/decoder/constants.ts

@@ -0,0 +1,125 @@
+import type { ERC725JSONSchema } from '@erc725/erc725.js'
+import LSP1Schema from '@erc725/erc725.js/schemas/LSP1UniversalReceiverDelegate.json' with {
+  type: 'json',
+}
+import LSP3Schema from '@erc725/erc725.js/schemas/LSP3ProfileMetadata.json' with {
+  type: 'json',
+}
+import LSP4Schema from '@erc725/erc725.js/schemas/LSP4DigitalAsset.json' with {
+  type: 'json',
+}
+import LSP4LegacySchema from '@erc725/erc725.js/schemas/LSP4DigitalAssetLegacy.json' with {
+  type: 'json',
+}
+import LSP5Schema from '@erc725/erc725.js/schemas/LSP5ReceivedAssets.json' with {
+  type: 'json',
+}
+import LSP6Schema from '@erc725/erc725.js/schemas/LSP6KeyManager.json' with {
+  type: 'json',
+}
+import LSP8Schema from '@erc725/erc725.js/schemas/LSP8IdentifiableDigitalAsset.json' with {
+  type: 'json',
+}
+import LSP9Schema from '@erc725/erc725.js/schemas/LSP9Vault.json' with {
+  type: 'json',
+}
+import LSP10Schema from '@erc725/erc725.js/schemas/LSP10ReceivedVaults.json' with {
+  type: 'json',
+}
+import LSP12Schema from '@erc725/erc725.js/schemas/LSP12IssuedAssets.json' with {
+  type: 'json',
+}
+import LSP17Schema from '@erc725/erc725.js/schemas/LSP17ContractExtension.json' with {
+  type: 'json',
+}
+
+export const IPFS_GATEWAY = 'https://api.universalprofile.cloud/ipfs/'
+export const FUNCTION_DICTIONARY_URL =
+  'https://4bytesdictionary.universalprofile.cloud'
+export const OPENCHAIN_DICTIONARY_URL =
+  'https://api.openchain.xyz/signature-database/v1/lookup'
+export const ARRAY_MAX = 1000
+
+/**
+ * Concatenation of all the schemas
+ */
+export const defaultSchema: ERC725JSONSchema[] = [
+  ...LSP8Schema,
+  ...LSP4Schema,
+  ...LSP5Schema,
+  ...LSP3Schema,
+  ...LSP1Schema,
+  ...LSP4LegacySchema,
+  ...LSP6Schema,
+  ...LSP9Schema,
+  ...LSP10Schema,
+  ...LSP12Schema,
+  ...LSP17Schema,
+  {
+    name: 'LSP28TheGrid',
+    key: '0x724141d9918ce69e6b8afcf53a91748466086ba2c74b94cab43c649ae2ac23ff',
+    keyType: 'Singleton',
+    valueType: 'bytes',
+    valueContent: 'VerifiableURI',
+  },
+]
+
+/**
+ * The important standards for profile, lsp7 and lsp8
+ */
+type Standards =
+  | 'LSP0ERC725Account'
+  | 'LSP7DigitalAsset'
+  | 'LSP8IdentifiableDigitalAsset'
+
+/**
+ * Interface id entry for interface id items.
+ */
+type StandardID = {
+  key: `0x${string}`
+  name: string
+  standard: Standards
+}
+
+/**
+ * Array of our standard interfaceIDs
+ */
+export const ITEMS: StandardID[] = [
+  {
+    key: '0x24871b3d' as `0x${string}`,
+    name: 'isProfile',
+    standard: 'LSP0ERC725Account' as Standards,
+  },
+
+  {
+    key: '0xc52d6008' as `0x${string}`,
+    name: 'isLSP7',
+    standard: 'LSP7DigitalAsset' as Standards,
+  },
+  {
+    key: '0xb3c4928f' as `0x${string}`,
+    name: 'isLSP7',
+    standard: 'LSP7DigitalAsset' as Standards,
+  },
+  {
+    key: '0xdaa746b7' as `0x${string}`,
+    name: 'isLSP7',
+    standard: 'LSP7DigitalAsset' as Standards,
+  },
+
+  {
+    key: '0x3a271706' as `0x${string}`,
+    name: 'isLSP8',
+    standard: 'LSP8IdentifiableDigitalAsset' as Standards,
+  },
+  {
+    key: '0xecad9f75' as `0x${string}`,
+    name: 'isLSP8',
+    standard: 'LSP8IdentifiableDigitalAsset' as Standards,
+  },
+  {
+    key: '0x30dc5278' as `0x${string}`,
+    name: 'isLSP8',
+    standard: 'LSP8IdentifiableDigitalAsset' as Standards,
+  },
+]

package/src/decoder/decodeTransaction.ts

@@ -0,0 +1,292 @@
+import { type Signal, signal } from '@preact/signals-core'
+import type { Hex, Transaction } from 'viem'
+import { collectDataKeys } from '../core/addressCollector'
+import { deepFreeze } from '../core/dataModel'
+import { pluginRegistry } from '../decoder/registry'
+import { decodeTransaction as decodeTransactionCore } from '../decoder/transaction'
+import {
+  AsyncOperations,
+  type DecoderOptions,
+  type DecoderResult,
+  ErrorType,
+} from '../decoder/types'
+import { isAsyncOperationEnabled } from '../decoder/utils'
+import { ERROR_CODES } from '../shared/constants'
+import type { DataKey, TransactionState } from '../types'
+
+/**
+ * Address resolver interface for batch resolution
+ */
+export interface AddressResolver {
+  resolveAddresses(addresses: DataKey[]): Promise<void>
+}
+
+/**
+ * Result from decoding a transaction
+ */
+export interface TransactionDecoderResult {
+  // Immediate sync result
+  immediate: DecoderResult
+
+  // Signal that updates as async decoding progresses
+  signal: Signal<TransactionState>
+}
+
+/**
+ * Decode a transaction with progressive enhancement
+ * @param transaction - Raw transaction data or array of transactions
+ * @param options - Decoder options
+ * @returns Immediate result and reactive signal (or array of them)
+ */
+export async function decodeTransaction<
+  T extends DecoderResult | DecoderResult[],
+>(
+  transaction: T,
+  options: DecoderOptions & { addressResolver?: AddressResolver }
+): Promise<
+  T extends Transaction[]
+    ? TransactionDecoderResult[]
+    : TransactionDecoderResult
+> {
+  const isBatch = Array.isArray(transaction)
+  const transactions: DecoderResult[] = isBatch
+    ? (transaction as unknown as DecoderResult[])
+    : [transaction as DecoderResult]
+
+  const results = await decodeTransactionBatch(transactions, options)
+
+  // Return single result if single input
+  if (isBatch) {
+    return results as T extends Transaction[]
+      ? TransactionDecoderResult[]
+      : TransactionDecoderResult
+  }
+  return results[0] as T extends Transaction[]
+    ? TransactionDecoderResult[]
+    : TransactionDecoderResult
+}
+
+/**
+ * Internal batch decoder with three-phase approach
+ */
+async function decodeTransactionBatch(
+  transactions: DecoderResult[],
+  options: DecoderOptions & { addressResolver?: AddressResolver }
+): Promise<TransactionDecoderResult[]> {
+  // Extract names of plugins provided in options (these will override registered ones)
+  const overridePluginNames =
+    options.plugins
+      ?.map((p) => p.name)
+      .filter((name): name is string => typeof name === 'string') || []
+
+  const overrideSchemaNames =
+    options.schemaPlugins
+      ?.map((p) => p.name)
+      .filter((name): name is string => typeof name === 'string') || []
+
+  // Get registered plugins, excluding those being overridden
+  const registeredPlugins = await pluginRegistry.getAll({
+    excludeNames: overridePluginNames,
+  })
+  const registeredSchemaPlugins =
+    pluginRegistry.getAllSchema(overrideSchemaNames)
+
+  // Merge: provided plugins override registered ones
+  const allPlugins = [...registeredPlugins, ...(options.plugins || [])]
+  const allSchemaPlugins = [
+    ...registeredSchemaPlugins,
+    ...(options.schemaPlugins || []),
+  ]
+
+  // Phase 1: Sync decode
+  const syncOptions: DecoderOptions = {
+    ...options,
+    plugins: allPlugins.filter(({ usesAsync }) => !usesAsync),
+    schemaPlugins: allSchemaPlugins,
+    async: false,
+  }
+
+  const results = await Promise.all(
+    transactions.map(async (tx) => {
+      const initialResult = await decodeTransactionCore(tx, syncOptions)
+      const initialData = deepFreeze(initialResult || createErrorResult(tx))
+
+      // Create signal with frozen data
+      const txSignal = signal<TransactionState>({
+        loading: false,
+        data: initialData as DecoderResult,
+        decodingStatus: initialResult ? 'decoded' : 'failed',
+        addresses: collectDataKeys(tx),
+        addressesResolved: false,
+        lastUpdated: Date.now(),
+      })
+
+      return {
+        transaction: tx,
+        immediate: initialData,
+        signal: txSignal,
+      }
+    })
+  )
+
+  // Check if we have any async plugins for phase 2
+  // For now, assume we have async plugins if async operations are enabled
+  // since plugins themselves no longer have the async property
+  const hasAsyncPlugins = true
+  const pluginsEnabled = isAsyncOperationEnabled(
+    options.async,
+    AsyncOperations.ENABLE_PLUGINS
+  )
+
+  if (hasAsyncPlugins && pluginsEnabled) {
+    // Phase 2: ABI retrieval (async plugins)
+    const asyncOptions: DecoderOptions = {
+      ...options,
+      plugins: allPlugins,
+      schemaPlugins: allSchemaPlugins,
+      async: true,
+    }
+
+    // Run async decoding for all transactions
+    for (const { transaction, signal: txSignal } of results) {
+      decodeTransactionCore(transaction, asyncOptions)
+        .then((enhanced) => {
+          if (enhanced) {
+            txSignal.value = {
+              ...txSignal.value,
+              data: deepFreeze(enhanced) as DecoderResult,
+              decodingStatus: 'enhanced',
+              addresses: collectDataKeys(enhanced),
+              lastUpdated: Date.now(),
+            }
+          }
+        })
+        .catch((error) => {
+          console.error('Async decode error:', error)
+          txSignal.value = {
+            ...txSignal.value,
+            decodingStatus: 'failed',
+            error: error instanceof Error ? error.message : 'Unknown error',
+            loading: false,
+          }
+        })
+    }
+  }
+
+  // Phase 3: Address resolution (if resolver provided and enabled)
+  const addressResolveEnabled = isAsyncOperationEnabled(
+    options.async,
+    AsyncOperations.ENABLE_ADDRESS_RESOLVE
+  )
+
+  if (options.addressResolver && addressResolveEnabled) {
+    // Collect all unique addresses from all transactions
+    const allAddresses = new Set<DataKey>()
+    for (const { signal: txSignal } of results) {
+      for (const addr of txSignal.value.addresses) {
+        allAddresses.add(addr)
+      }
+    }
+
+    // Batch resolve addresses
+    if (allAddresses.size > 0) {
+      options.addressResolver
+        .resolveAddresses(Array.from(allAddresses))
+        .then(() => {
+          // Update all signals to indicate addresses are resolved
+          for (const { signal: txSignal } of results) {
+            if (txSignal.value.decodingStatus !== 'failed') {
+              txSignal.value = {
+                ...txSignal.value,
+                addressesResolved: true,
+                decodingStatus: 'complete',
+                lastUpdated: Date.now(),
+              }
+            }
+          }
+        })
+        .catch((error) => {
+          console.error('Address resolution error:', error)
+          // Don't fail the transaction, just log the error
+        })
+    }
+  } else if (!hasAsyncPlugins || (!pluginsEnabled && !addressResolveEnabled)) {
+    // No async operations enabled, mark as complete
+    for (const { signal: txSignal } of results) {
+      if (txSignal.value.decodingStatus !== 'failed') {
+        txSignal.value = {
+          ...txSignal.value,
+          decodingStatus: 'complete',
+        }
+      }
+    }
+  }
+
+  return results.map((r) => ({
+    immediate: r.immediate,
+    signal: r.signal,
+  }))
+}
+
+function createErrorResult(transaction: DecoderResult): DecoderResult {
+  return {
+    ...transaction,
+    resultType: 'error' as const,
+    isDecoded: false,
+    errorType: ErrorType.ERROR,
+    sig: transaction.input?.slice(0, 10) as Hex,
+    error: {
+      code: ERROR_CODES.DECODING_FAILED,
+      message: 'Failed to decode transaction',
+      details: new Error('Decoder returned undefined'),
+    },
+  }
+}
+
+/**
+ * Decode a transaction and wait for complete result
+ * Convenience wrapper for when you need a promise
+ */
+export async function decodeTransactionAsync<
+  T extends DecoderResult | DecoderResult[],
+>(
+  transaction: T,
+  options: DecoderOptions & { addressResolver?: AddressResolver }
+): Promise<T extends Transaction[] ? DecoderResult[] : DecoderResult> {
+  const isBatch = Array.isArray(transaction)
+  const result = await decodeTransaction(transaction, options)
+  const results = isBatch
+    ? (result as TransactionDecoderResult[])
+    : [result as TransactionDecoderResult]
+
+  // Wait for all decodings to complete
+  const finalResults = await Promise.all(
+    results.map(
+      ({ signal }) =>
+        new Promise<DecoderResult>((resolve) => {
+          const checkComplete = () => {
+            const state = signal.value
+            if (
+              state.decodingStatus === 'complete' ||
+              state.decodingStatus === 'failed'
+            ) {
+              resolve(state.data as DecoderResult)
+            } else {
+              // Check again on next tick
+              setTimeout(checkComplete, 10)
+            }
+          }
+          checkComplete()
+        })
+    )
+  )
+
+  if (isBatch) {
+    return finalResults as T extends Transaction[]
+      ? DecoderResult[]
+      : DecoderResult
+  }
+  return finalResults[0] as T extends Transaction[]
+    ? DecoderResult[]
+    : DecoderResult
+}

package/src/decoder/errors.ts

@@ -0,0 +1,95 @@
+import { type Chain, decodeAbiParameters, slice } from 'viem'
+import defaultPlugins from './plugins'
+import { decodeTransaction } from './transaction'
+import {
+  DecoderResult,
+  ErrorType,
+  type ResultError,
+  type SchemaPlugin,
+} from './types'
+import { createNamedArgs } from './utils'
+
+const ERROR = {
+  STRING: '0x08c379a0', // keccak256('Error(string)').slice(0, 10)
+  PANIC: '0x4e487b71', // keccak256('Panic(uint)').slice(0, 10)
+  EMPTY_REVERT: '0xd8b98391', // keccak256('Revert()').slice(0, 10)
+}
+
+export const ErrorTypeMap: {
+  [ErrorType.INVALID]: 'transaction.error.types.invalid'
+  [ErrorType.PANIC]: 'transaction.error.types.panic'
+  [ErrorType.ERROR]: 'transaction.error.types.error'
+  [ErrorType.CUSTOM_ERROR]: 'transaction.error.types.custom_error'
+  [ErrorType.EMPTY_REVERT]: 'transaction.error.types.empty_revert'
+  [key: string]: string
+} = {
+  [ErrorType.INVALID]: 'transaction.error.types.invalid',
+  [ErrorType.PANIC]: 'transaction.error.types.panic',
+  [ErrorType.ERROR]: 'transaction.error.types.error',
+  [ErrorType.CUSTOM_ERROR]: 'transaction.error.types.custom_error',
+  [ErrorType.EMPTY_REVERT]: 'transaction.error.types.empty_revert',
+}
+
+const CONTRACT_ERROR_THROWN = 'transactions.error.contract_error_thrown'
+
+function populateEmptyRevertInfo(
+  input: `0x${string}`
+): ResultError | undefined {
+  const sig = slice(input, 0, 4)
+  switch (sig) {
+    case ERROR.EMPTY_REVERT:
+      return {
+        resultType: 'error',
+        errorType: ErrorType.EMPTY_REVERT,
+        summary: '',
+        input,
+        sig,
+        ...createNamedArgs([], []),
+        functionName: 'Revert',
+        devdocs: '',
+      }
+    case ERROR.STRING:
+      return {
+        resultType: 'error',
+        errorType: ErrorType.ERROR,
+        summary: 'Transaction reverted with string',
+        input,
+        sig,
+        ...createNamedArgs([], []),
+        functionName: 'Error',
+        devdocs: '',
+      }
+    case ERROR.PANIC: {
+      const value = decodeAbiParameters([{ type: 'uint' }], slice(input, 4))
+      return {
+        resultType: 'error',
+        errorType: ErrorType.PANIC,
+        summary: 'Transaction reverted due to Panic',
+        input,
+        sig,
+        ...createNamedArgs([value[0]], [{ type: 'uint', name: 'code' }]),
+        functionName: 'Panic',
+        devdocs: '',
+      }
+    }
+  }
+}
+
+export async function decodeError(chain: Chain, input: `0x${string}`) {
+  const decoded = populateEmptyRevertInfo(input)
+  if (decoded) {
+    return decoded
+  }
+  return decodeTransaction(
+    {
+      input,
+    } as DecoderResult,
+    {
+      chain,
+      preferError: true,
+      plugins: defaultPlugins,
+      schemaPlugins: [] as SchemaPlugin[],
+      wrappers: [], // Wrappers will be ignored because there are none.
+    }
+  )
+}