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

package/src/decoder/transaction.ts

@@ -0,0 +1,198 @@
+import { type Hex, isAddress, isAddressEqual, slice, zeroAddress } from 'viem'
+import {
+  type DecodeEventResult,
+  type DecoderOptions,
+  type DecoderResult,
+  ErrorType,
+} from './types'
+import { createNamedArgs } from './utils'
+
+/**
+ * Decode transaction
+ * @param transaction Transaction to decode (should have data/input)
+ * @param options Decoder options
+ * @returns Promise<DecoderResult>
+ */
+export async function decodeTransaction(
+  fullTransaction: DecoderResult,
+  options: DecoderOptions & {
+    preferError?: boolean
+  }
+): Promise<DecoderResult | undefined> {
+  const { preferError } = options
+  // Normalize input field - ensure we only have input, not data
+  const {
+    to,
+    from,
+    value,
+    input: rawInput,
+    data: rawData,
+    ...restTransaction
+  } = fullTransaction as DecoderResult & { data?: Hex }
+  const { logs, ...transaction } = {
+    ...restTransaction,
+    to,
+    from,
+    value,
+    input: rawInput || rawData,
+  }
+  const data = rawInput || rawData
+  if (!data || data === '0x') {
+    if (preferError) {
+      return {
+        ...transaction,
+        isDecoded: true,
+        functionName: undefined,
+        __decoder: undefined,
+        sig: slice(data || '0x', 0, 4),
+        resultType: 'error',
+        errorType: ErrorType.INVALID,
+        ...createNamedArgs([], []),
+        standard: undefined,
+        phase: 'enhanced',
+      } as DecoderResult
+    }
+    return {
+      ...transaction,
+      isDecoded: true,
+      functionName: undefined,
+      __decoder: undefined,
+      standard: undefined,
+      sig: slice(data || '0x', 0, 4),
+      ...createNamedArgs([], []),
+      resultType: 'execute',
+      phase: 'enhanced',
+    } as DecoderResult
+  }
+  let lastError: Error | undefined
+
+  // The caller is responsible for providing the appropriate plugin set
+  // For sync-only decoding, use pluginRegistry.getAll({ syncOnly: true })
+  // For full decoding, use pluginRegistry.getAll()
+  const activePlugins = options.plugins
+
+  for (const plugin of activePlugins) {
+    if (to && isAddress(to) && isAddressEqual(to, zeroAddress)) {
+      return {
+        ...transaction,
+        isDecoded: true,
+        ...createNamedArgs([], []),
+        resultType: 'create',
+        to,
+        from,
+        value,
+        logs,
+        phase: 'immediate',
+      } as DecoderResult
+    }
+
+    try {
+      const check = await plugin.enhance(transaction, options)
+      if (check) {
+        const output: DecodeEventResult[] = []
+        if (logs) {
+          for (const log of logs) {
+            const data = await plugin.decodeEvent(log, options)
+            if (data) {
+              output.push(data)
+              continue
+            }
+            let done = false
+            for (const eventPlugin of activePlugins) {
+              if (eventPlugin !== plugin) {
+                const data = await eventPlugin.decodeEvent(log, options)
+                if (data) {
+                  output.push(data)
+                  done = true
+                  break
+                }
+              }
+            }
+            if (!done) {
+              output.push(log as DecodeEventResult)
+            }
+          }
+          check.logs = output
+        }
+        let phase: 'immediate' | 'enhanced' | 'complete' =
+          plugin.usesAsync ||
+          ('functionName' in check && check.functionName && check.standard) ||
+          check.input === '0x' ||
+          !check.input
+            ? 'enhanced'
+            : 'immediate'
+
+        // If result has children, check if ALL children are enhanced
+        // If any child is not enhanced, downgrade parent to 'immediate'
+        const resultWithChildren = check as { children?: DecoderResult[] }
+        if (
+          phase === 'enhanced' &&
+          resultWithChildren.children &&
+          Array.isArray(resultWithChildren.children) &&
+          resultWithChildren.children.length > 0
+        ) {
+          const allChildrenEnhanced = resultWithChildren.children.every(
+            (child: DecoderResult) => (child as any).phase === 'enhanced'
+          )
+          if (!allChildrenEnhanced) {
+            phase = 'immediate'
+          }
+        }
+
+        const result = {
+          ...transaction,
+          ...check,
+          phase,
+        } as DecoderResult
+        return result
+      }
+    } catch (e) {
+      console.error(e)
+      continue
+    }
+  }
+  let phase: 'immediate' | 'enhanced' | 'complete' =
+    ('functionName' in transaction &&
+      transaction.functionName &&
+      transaction.standard) ||
+    transaction.input === '0x' ||
+    !transaction.input
+      ? 'enhanced'
+      : 'immediate'
+
+  // If result has children, check if ALL children are enhanced
+  // If any child is not enhanced, downgrade parent to 'immediate'
+  const transactionWithChildren = transaction as { children?: DecoderResult[] }
+  if (
+    phase === 'enhanced' &&
+    transactionWithChildren.children &&
+    Array.isArray(transactionWithChildren.children) &&
+    transactionWithChildren.children.length > 0
+  ) {
+    const allChildrenEnhanced = transactionWithChildren.children.every(
+      (child: DecoderResult) => (child as any).phase === 'enhanced'
+    )
+    if (!allChildrenEnhanced) {
+      phase = 'immediate'
+    }
+  }
+
+  const result = {
+    ...transaction,
+    standard: undefined,
+    __decoder: undefined,
+    resultType: 'raw',
+    phase,
+    sig: slice(
+      fullTransaction.input ||
+        ('data' in fullTransaction && (fullTransaction.data as Hex)) ||
+        '0x',
+      0,
+      4
+    ),
+    ...createNamedArgs([], []),
+    ...(options.wrappers.length ? { wrappers: options.wrappers } : {}),
+    logs,
+  } as DecoderResult
+  return result
+}

package/src/decoder/types.ts

@@ -0,0 +1,465 @@
+import type { ERC725JSONSchema } from '@erc725/erc725.js'
+import type {
+  Abi,
+  AbiParameter,
+  Address,
+  Chain,
+  DecodeFunctionDataReturnType,
+  Hex,
+  Log,
+  Transaction,
+} from 'viem'
+import type { DataKey } from '../types'
+import type { DecoderCache } from './cache'
+
+/**
+ * Array length item: Represents the length of an ERC725 Array schema item.
+ */
+export type ArrayLengthInfo = ERC725JSONSchema & {
+  type: 'ArrayLength'
+  value: number
+  pretty?: string
+}
+
+/**
+ * Array item: Represents the value of an ERC725 Array schema item.
+ */
+export type ArrayItemInfo = ERC725JSONSchema & {
+  type: 'ArrayItem'
+  dynamic: number
+  value: unknown
+  pretty?: string
+}
+
+/**
+ * Value item: Represents the value of an ERC725 schema item.
+ */
+export type ValueInfo = ERC725JSONSchema & {
+  type: 'Value'
+  dynamic?: string | string[]
+  value: unknown
+  data?: string
+  method?: string
+  url?: string
+  src?: string
+  pretty?: string
+}
+
+/**
+ * Undecoded item: Represents an undecoded ERC725 schema item (unknown, raw data).
+ */
+export type UndecodedInfo = {
+  type: 'Undecoded'
+  key: string
+  name: undefined
+  value: string
+}
+
+/**
+ * Error item: Error happened during decoding or retrieval (404 or exception due to invalid data)
+ */
+export type ErrorInfo = ERC725JSONSchema & {
+  type: 'Error'
+  key: string
+  value: string | Error
+  data?: string
+  method?: string
+  url?: string
+  src?: string
+  pretty?: string
+}
+
+/**
+ * Info item: Results of the decoded schema.
+ */
+export type Info =
+  | ArrayLengthInfo
+  | ArrayItemInfo
+  | ValueInfo
+  | UndecodedInfo
+  | ErrorInfo
+
+/**
+ * Add address as a property to the record so that obj.address instead of obj['address'] can be used
+ */
+export type EnhancedInfo = {
+  address: `0x${string}`
+  standard?: string
+  tokenId?: `0x${string}`
+  name?: string
+  __gqltype?: 'Profile' | 'Asset' | 'Token'
+  [key: string]: unknown
+}
+
+export type NamedArgs = Record<
+  string | number,
+  AbiParameter & { value?: unknown }
+>
+export type ArrayArgs = Array<
+  AbiParameter & {
+    value?: unknown
+  }
+>
+
+export type ResultShared = {
+  resultType?: string
+  standard?: string
+  type?: string
+  sig?: `0x${string}` | null
+  graphqlData?: Record<Hex, EnhancedInfo>
+  /**
+   * Decoding phase - added by server-side decoder
+   */
+  phase?: 'immediate' | 'enhanced'
+  /**
+   * Whether this result was served from cache - added by server-side decoder
+   */
+  cached?: boolean
+  /**
+   * Time taken to decode (milliseconds)
+   */
+  timeTaken?: number
+
+  moduleHint?: string
+  logs?: DecodeEventResult[]
+  isDecoded?: boolean
+  error?: {
+    code: string
+    message: string
+    details: Error
+  }
+  processingError?: { message: string; code: unknown }
+  blockTimestamp?: number
+
+  /**
+   * List of addresses found in the transaction (to, from, args, namedArgs, wrappers)
+   */
+  addresses?: DataKey[]
+
+  transactionHash?: Hex
+
+  /**
+   * Custom data for view matching and extensibility.
+   * Populated by enhancers to provide additional context for view selection.
+   *
+   * Common use cases:
+   * - tokenType: 0 (token) | 1 (NFT) | 2 (collection)
+   * - isToken, isNFT, isCollection: boolean flags
+   * - operationType: 'mint' | 'burn' | 'transfer'
+   * - hasMetadata: boolean
+   * - customFlags: any enhancer-specific data
+   *
+   * This field is NOT typed to allow for plugin extensibility.
+   */
+  custom?: Record<string, unknown>
+  enhancementAttempted?: boolean
+}
+
+/*
+ * The following types are used to represent the different result types of a transaction.
+ * They are used in the decodeTransaction function to determine the type of transaction
+ * and the corresponding properties.
+ */
+export type ResultError = {
+  resultType: 'error'
+  functionName?: string
+  errorType: ErrorType
+  sig: `0x${string}`
+  input?: `0x${string}` | null
+  args?: ArrayArgs
+  summary?: string
+  devdocs?: string
+}
+
+export type ResultAggregate = {
+  resultType: 'aggregate'
+  aggregate: {
+    count: number
+    blockRange: { from: number; to: number }
+    [key: string]: unknown
+  }
+  functionName?: string
+  args?: ArrayArgs
+  wrappers?: Array<ResultType>
+  devdocs?: string
+}
+export type ResultExecute = {
+  resultType: 'execute'
+  functionName?: string
+  args?: ArrayArgs
+  wrappers?: Array<ResultType>
+  devdocs?: string
+}
+
+export type ResultCreate = {
+  resultType: 'create'
+  wrappers?: Array<ResultType>
+  args?: ArrayArgs
+}
+
+export type ResultWrapper = {
+  resultType: 'wrapper'
+  functionName?: string
+  args?: ArrayArgs
+  devdocs?: string
+}
+
+export type ResultFollowProfile = {
+  resultType: 'followProfile'
+  functionName?: string
+  address: Address
+}
+
+export type ResultExecuteBatch = {
+  resultType: 'executeBatch'
+  functionName: string
+  args?: ArrayArgs
+  children: Array<ResultType & ResultShared>
+  wrappers?: Array<ResultType & ResultShared>
+  devdocs?: string
+}
+
+export type ResultSetDataBatch = {
+  resultType: 'setDataBatch'
+  functionName?: string
+  standard?: string
+  args?: ArrayArgs
+  children: Array<ResultSetData & ResultShared>
+  wrappers?: Array<ResultType & ResultShared>
+  devdocs?: string
+}
+
+export type ResultGrafitti = {
+  resultType: 'grafitti'
+  standard?: string
+  graffiti: string
+  devdocs?: string
+  functionName?: string
+}
+
+export type ResultSetData = {
+  resultType: 'setData'
+  functionName?: string
+  tokenId?: `0x${string}`
+  args?: ArrayArgs
+  wrappers?: Array<ResultType & ResultShared>
+  info?: Info
+  devdocs?: string
+}
+
+export type ResultRaw = {
+  resultType: 'raw'
+  standard?: string
+  input?: `0x${string}`
+}
+
+/**
+ * DecodeFunctionDataReturn: Represents the return type of a decodeTransaction function.
+ * There are extra properties added to the return type to make it more useful.
+ * Internally some of the properties are used to decode the data so in some places
+ * we use "any" to avoid type errors during the decoding process.
+ * The main offenders here are isDecoded: boolean and __decoder: string and so on.
+ * Rather than mixing those into the type, then it would make the types unnecessarily complex.
+ */
+export type ResultComponent =
+  | ResultExecute
+  | ResultCreate
+  | ResultWrapper
+  | ResultSetDataBatch
+  | ResultExecuteBatch
+  | ResultSetData
+  | ResultGrafitti
+  | ResultRaw
+  | ResultError
+  | ResultAggregate
+  | ResultFollowProfile
+
+/**
+ * The main result type returned by decodeTransaction.
+ */
+export type ResultType = Partial<
+  Omit<Transaction, 'type' | 'logs' | 'blobVersionedHashes'>
+> &
+  ResultShared &
+  ResultComponent & {
+    __decoder?: string
+    __decoderVerifiedContract?: boolean
+    type?: string
+    logs?: DecodeEventResult[]
+    blobVersionedHashes?: readonly Hex[]
+  }
+
+/**
+ * CustomDecodeFunctionDataReturn: Represents the return type of a customDecodeFunctionData function.
+ * Basically the normal decodeFunctionData doesn't return the abi entry, so that
+ * we can't decode argument names and types.
+ */
+export type CustomDecodeFunctionDataReturn<
+  abi extends Abi | readonly unknown[],
+> = DecodeFunctionDataReturnType<abi> & {
+  args?: ArrayArgs
+}
+
+/**
+ * This is the modification record used to patch address values into any
+ * data structure. It will allow iterating through the data structure,
+ * collecting all things that look like addresses and pass isAddress.
+ * This will also include 0x00000000000ADDRESS.
+ */
+export type AddressModifier = {
+  address: Address
+  path: Array<string | number>
+  tokenId?: `0x${string}`
+  root: Array<Record<string, unknown>> | Record<string, unknown> | unknown
+}
+
+export enum ErrorType {
+  EMPTY_REVERT = 'EMPTY_REVERT',
+  INVALID = 'INVALID',
+  PANIC = 'PANIC',
+  ERROR = 'ERROR',
+  CUSTOM_ERROR = 'CUSTOM_ERROR',
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * The output of the enhancer
+ */
+export type DecoderResult = ResultType &
+  ResultShared & {
+    /** Which aggregations apply (just keys, no plugin prefix) */
+    aggregationKeys?: string[]
+  }
+
+/**
+ * Aggregation configuration for map/reduce operations
+ */
+export interface Aggregation<T = any> {
+  /** Unique key for this aggregation within the plugin */
+  key: string
+  /** Extract/transform data from a single transaction */
+  map: (tx: DecoderResult) => T | undefined
+  /** Combine mapped data with existing state */
+  reduce: (state: T | undefined, mapped: T) => T
+  /** Transform state for final output */
+  finalize: (state: T) => Omit<ResultAggregate, 'resultType'>
+}
+
+/**
+ * Bitmap enum for controlling which async operations are enabled
+ */
+export enum AsyncOperations {
+  /** No async operations (default) */
+  DISABLED = 0, // 0b000
+  /** Enable async plugins (ABI fetching, function signatures) */
+  ENABLE_PLUGINS = 1 << 0, // 0b001
+  /** Enable address resolution (profile/address metadata) */
+  ENABLE_ADDRESS_RESOLVE = 1 << 1, // 0b010
+  /** Enable external data fetching (IPFS, external JSON) */
+  ENABLE_EXTERNAL_DATA = 1 << 2, // 0b100
+}
+
+/**
+ * Options to modify operations which now also have to be sent down to the enhancer and plugin
+ */
+export type DecoderOptions = {
+  plugins: ReadonlyArray<DecoderPlugin>
+  schemaPlugins: ReadonlyArray<SchemaPlugin>
+  preferError?: boolean
+  wrappers: Array<ResultType & ResultShared>
+  chain: Chain
+  /**
+   * Controls which async operations are enabled.
+   * Can be a boolean for backward compatibility (true = all async, false = none)
+   * or AsyncOperations enum for fine-grained control
+   */
+  async?: boolean | AsyncOperations
+  /** Cache implementation for async operations */
+  cache?: DecoderCache
+  /** Timeout for async operations in milliseconds */
+  timeout?: number
+  /** AbortSignal for cancelling async operations */
+  signal?: AbortSignal
+}
+
+/**
+ * Generic plugin into decoder (most of the time this will be wrapped with the standard plugin to provide
+ * additional or existing abis)
+ */
+export type DecoderPlugin = {
+  enhance: (
+    transaction: DecoderResult,
+    options: DecoderOptions
+  ) => Promise<DecoderResult | undefined>
+  decodeEvent: (
+    log: DecodeEventResult,
+    options: DecoderOptions
+  ) => Promise<DecodeEventResult>
+  getAggregationKey?: EnhancerAggregationKeyCallback
+  summarize?: EnhancerSummarizeCallback
+  name?: string // Optional name for override detection
+  required?: boolean // Cannot be overridden, always runs first
+  priority?: number // Higher number = runs earlier (default: 0)
+  usesAsync?: boolean
+  /** Aggregations supported by this plugin */
+  aggregations?: Aggregation[]
+}
+
+export type PluginOptions = {
+  abiName: string
+  decoderName?: string
+  moduleHint?: string
+  name?: string // Plugin name for override detection
+  required?: boolean // Cannot be overridden, always runs first
+  priority?: number // Higher number = runs earlier (default: 0)
+  usesAsync?: boolean // Whether this plugin performs async operations
+}
+/**
+ * Type for the actual enhancement logic
+ */
+export type EnhancerCallback = (
+  result: DecoderResult,
+  pluginOptions: PluginOptions,
+  options: DecoderOptions
+) => Promise<DecoderResult | undefined>
+
+export type EnhancerAggregationKeyCallback = (
+  result: DecoderResult,
+  pluginOptions: PluginOptions,
+  options: DecoderOptions
+) => Promise<string | undefined>
+
+export type EnhancerSummarizeCallback = (
+  aggregateKey: string,
+  result: DecoderResult[],
+  pluginOptions: PluginOptions,
+  options: DecoderOptions
+) => Promise<DecoderResult | undefined> // Most likely ResultAggregate
+
+/**
+ * Plugins to execute decodeData with custom schema tables.
+ * The passed in data will contain the abi name, functionName and so on.
+ */
+export type SchemaPlugin = ((
+  key: Hex,
+  value: Hex
+) => Promise<Info | undefined>) & {
+  name?: string // Optional name for override detection
+  required?: boolean // Cannot be overridden, always runs first
+  priority?: number // Higher number = runs earlier (default: 0)
+}
+
+/**
+ * Plugin callback function to decode events.
+ */
+export type DecodeEventCallback = (
+  log: DecodeEventResult,
+  options: DecoderOptions
+) => Promise<DecodeEventResult>
+
+export type DecodeEventResult =
+  | ({
+      eventName: string
+      args: ArrayArgs
+    } & Log)
+  | undefined