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

package/src/decoder/plugins/schemaDefault.ts

@@ -0,0 +1,318 @@
+import {
+  type DecodeDataOutput,
+  decodeData,
+  decodeMappingKey,
+  decodePermissions,
+  decodeValueContent,
+  type ERC725JSONSchema,
+  isDynamicKeyName,
+  type Permissions,
+} from '@erc725/erc725.js'
+import { type Hex, isHex } from 'viem'
+import { ARRAY_MAX, defaultSchema, IPFS_GATEWAY } from '../constants'
+import { getDataFromExternalSources } from '../getDataFromExternalSources'
+import type { Info } from '../types'
+
+export const schemaDefaultPlugin = decodeKeyValuePlugin(defaultSchema)
+export default schemaDefaultPlugin
+
+/**
+ * Decode key/value pair as per erc725 schema
+ * @param key
+ * @param value
+ * @returns
+ */
+export function decodeKeyValuePlugin(
+  defaultSchema: ERC725JSONSchema[],
+  process?: (output: Info) => Promise<Info>
+) {
+  const preProcess = async (key: Hex, value: Hex): Promise<Info> => {
+    // Search for the schema entry.
+    const schema =
+      defaultSchema.find((item) => {
+        if (key === item.key) {
+          return true
+        }
+        const index = item.key.indexOf('<')
+        if (index !== -1) {
+          return key.slice(0, index) === item.key.slice(0, index)
+        }
+        return false
+      }) ||
+      defaultSchema.find((item) => {
+        if (key.slice(0, 34) === item.key.slice(0, 34)) {
+          return true
+        }
+        return false
+      })
+    if (schema) {
+      try {
+        // Get the raw name.
+        const name = schema.name.replace(/[:\[\]]|<.*?>/g, '')
+        if (schema.keyType === 'Array') {
+          if (schema.key === key) {
+            // Convert hex string to Uint8Array without using Buffer
+            const hexString = value.slice(2)
+            const all = new Uint8Array(hexString.length / 2)
+            for (let i = 0; i < hexString.length; i += 2) {
+              all[i / 2] = Number.parseInt(hexString.substring(i, i + 2), 16)
+            }
+            // Figure out the first and last byte of the value (this is to allow
+            // the older and newer ways to store the array length i.e. uint256, uint128 and so on.)
+            const [{ start, end } = { start: 0, end: 0 }] = all.reduce(
+              (
+                acc: Array<{ isZero: boolean; start: number; end: number }>,
+                byte,
+                index_
+              ) => {
+                let isZero = byte === 0 || index_ === 0
+                const last = acc.at(-1)
+                let index = index_
+                if (
+                  !last ||
+                  last.isZero !== isZero ||
+                  index === all.length - 1
+                ) {
+                  if (index === all.length - 1) {
+                    index = all.length
+                  } else if (index === 0) {
+                    isZero = true
+                  }
+                  if (last) {
+                    last.end = index
+                    last.isZero = isZero
+                  }
+                  if (isZero) {
+                    acc.push({
+                      isZero,
+                      start: index,
+                      end: index === 0 ? index + 1 : index,
+                    })
+                  }
+                }
+                return acc
+              },
+              []
+            )
+            const picked =
+              Math.abs(end - all.length + 1) <= 4
+                ? all.length + 1
+                : Math.abs(end - all.length / 2 + 1) <= 4
+                  ? all.length / 2
+                  : end
+            const segment = value.slice(0, picked * 2 + 2)
+            const length = BigInt(segment)
+            if (length > ARRAY_MAX) {
+              // We don't support arrays larger than 1000. Inside of the indexer it's a problem because of a single array column
+              // and we had to pick some kind of maximum size to prevent the SQL from crashing.
+              return {
+                ...schema,
+                type: 'Error',
+                key,
+                value: 'Array length too large',
+              }
+            }
+            return {
+              ...schema,
+              type: 'ArrayLength',
+              pretty: name,
+              value: Number(length),
+            }
+          }
+          // Extract array index.
+          const index = BigInt(`0x${key.slice(34)}`)
+          if (index > ARRAY_MAX) {
+            return {
+              ...schema,
+              type: 'Error',
+              key,
+              value: 'Array index too large',
+            }
+          }
+          let data =
+            value !== '0x'
+              ? decodeValueContent(schema.valueContent, value)
+              : undefined
+          if (schema.valueContent.startsWith('0x')) {
+            data = data === schema.valueContent
+          }
+          return {
+            ...schema,
+            type: 'ArrayItem',
+            pretty: name,
+            dynamic: Number(index),
+            value: data,
+          }
+        }
+        // Decode dynamic parts.
+        let dynamicKeyParts: string[] | string | undefined = undefined
+        if (isDynamicKeyName(schema.name)) {
+          dynamicKeyParts = decodeMappingKey(key, schema).map(({ value }) =>
+            isHex(value) ? (value as string).toLowerCase() : `${value}`
+          )
+        }
+        // Decode value
+        let rawData =
+          value !== '0x'
+            ? (decodeData(
+                [
+                  dynamicKeyParts
+                    ? {
+                        keyName: schema.name,
+                        dynamicKeyParts,
+                        value,
+                      }
+                    : { keyName: schema.name, value },
+                ],
+                defaultSchema
+              ) as unknown as Record<string, unknown>[])
+            : [{ value: undefined }]
+        type Params = Parameters<typeof getDataFromExternalSources>
+        let data = rawData?.[0]?.value
+        // Some special cases.
+        if (schema.name === 'LSP8TokenMetadataBaseURI') {
+          const { url: _url } = (data as { url: string | undefined }) || {}
+          const url = _url?.replace(/\0*$/g, '')
+          if (!url && url?.includes('\0')) {
+            return {
+              ...schema,
+              pretty: name,
+              type: 'Error',
+              key,
+              value: 'Invalid URL (contains \\0)',
+            }
+          }
+          return { ...schema, type: 'Value', name, value: url }
+        }
+        if (data && typeof data === 'object' && !Array.isArray(data)) {
+          const { url: _url } = (data as { url: string | undefined }) || {}
+          const url = _url?.replace(/\0*$/g, '')
+          if (!url || url?.includes('\0')) {
+            const newURL = url?.replace(/\0/g, '\\0')
+            const { error, data, method } = rawData?.[0] as {
+              error: string
+              data?: string
+              method?: string
+              url?: string
+            }
+            return {
+              ...schema,
+              pretty: name,
+              type: 'Error',
+              key,
+              value: `${error ? `${error} ` : ''}Invalid URL (contains \\0 ${newURL})`,
+              data,
+              method,
+              url: newURL,
+            }
+          }
+          const newURL = (data as { url: string }).url.replace(
+            'https://2eff.lukso.dev/ipfs/',
+            'ipfs://'
+          )
+          if (newURL !== (data as { url: string }).url) {
+            ;(data as { url: string }).url = newURL
+          }
+          rawData = (await getDataFromExternalSources(
+            defaultSchema,
+            rawData as unknown as DecodeDataOutput[],
+            IPFS_GATEWAY,
+            false
+          )) as unknown as Record<string, unknown>[]
+          if (rawData?.[0]?.error) {
+            const { error, data, method, url } = rawData?.[0] as {
+              error: string
+              data?: string
+              method?: string
+              url?: string
+            }
+            return {
+              ...schema,
+              type: 'Error',
+              pretty: name,
+              value: error,
+              data,
+              method,
+              url,
+            }
+          }
+          data =
+            (rawData?.[0]?.value as Record<string, unknown>)?.[schema.name] ||
+            (rawData?.[0]?.value as Record<string, unknown>)
+        } else if (schema.valueContent.startsWith('0x')) {
+          data = data === schema.valueContent
+        }
+        const {
+          data: _data,
+          method,
+          src,
+          url,
+        } = rawData?.[0] as {
+          data?: string
+          method?: string
+          url?: string
+          src?: string
+        }
+        if (schema.name === 'AddressPermissions:Permissions:<address>') {
+          let _value: string | object = data as string | object
+          try {
+            const {
+              ERC4337_PERMISSION: _ignore1,
+              ALL_PERMISSIONS: _ignore2,
+              ...rest
+            } = decodePermissions(data as Hex) as unknown as Permissions & {
+              ISRECOVERY?: boolean
+            }
+            if (Object.keys('rest').length === 1 && rest.ADDCONTROLLER) {
+              rest.ISRECOVERY = true
+            }
+            _value = rest
+          } catch {
+            // Ignore
+          }
+          return {
+            ...schema,
+            type: 'Value',
+            pretty: name,
+            value: _value,
+            dynamic:
+              dynamicKeyParts?.length === 1
+                ? dynamicKeyParts[0]
+                : dynamicKeyParts,
+            data: _data,
+            method,
+            src,
+            url,
+          }
+        }
+        return {
+          ...schema,
+          type: 'Value',
+          pretty: name,
+          value: data,
+          dynamic:
+            dynamicKeyParts?.length === 1
+              ? dynamicKeyParts[0]
+              : dynamicKeyParts,
+          data: _data,
+          method,
+          src,
+          url,
+        }
+      } catch (error) {
+        return { ...schema, type: 'Error', key, value: error as Error }
+      }
+    }
+    return { type: 'Undecoded', name: undefined, key, value }
+  }
+  return async (key: Hex, value: Hex) => {
+    try {
+      const result = await preProcess(key, value)
+      if (process) {
+        return await process(result)
+      }
+      return result
+    } catch {}
+    return undefined
+  }
+}

package/src/decoder/plugins/standardPlugin.ts

@@ -0,0 +1,202 @@
+import type { ERC725JSONSchema } from '@erc725/erc725.js'
+import type { Abi, AbiParameter, Hex, Log, Transaction } from 'viem'
+import { pluginRegistry } from '../registry'
+import type {
+  Aggregation,
+  DecodeEventCallback,
+  DecodeEventResult,
+  DecoderOptions,
+  DecoderPlugin,
+  DecoderResult,
+  EnhancerAggregationKeyCallback,
+  EnhancerCallback,
+  EnhancerSummarizeCallback,
+  Info,
+  PluginOptions,
+  ResultType,
+  SchemaPlugin,
+} from '../types'
+import { customDecodeFunctionData } from '../utils'
+import { decodeKeyValuePlugin } from './schemaDefault'
+
+/**
+ * Helper to create aggregation keys with plugin prefix
+ */
+export function createAggregationKey(
+  pluginOptions: PluginOptions,
+  key: string
+): string {
+  return `${pluginOptions.name || pluginOptions.decoderName || 'unknown'}:${key}`
+}
+
+/**
+ *
+ * @param abi abi to use for decoding
+ * @param pluginOptions options to name abi, decoder or module (optional since the enhancer can provide some or all)
+ * @param enhance callback to do the actual enhancement once the abi function was decoded.
+ * @returns enhanced transaction
+ */
+export function standardPlugin<T extends Abi | readonly unknown[]>(
+  abi: T,
+  pluginOptions: PluginOptions,
+  callbacks: {
+    enhance: EnhancerCallback
+    decodeEvent: DecodeEventCallback
+    overrideEnhance?: EnhancerCallback
+    getAggregationKey?: EnhancerAggregationKeyCallback
+    summarize?: EnhancerSummarizeCallback
+    aggregations?: Aggregation[]
+  }
+): DecoderPlugin {
+  const {
+    abiName,
+    decoderName = 'unknown',
+    moduleHint,
+    required,
+    priority,
+    name,
+    usesAsync,
+  } = pluginOptions
+  const plugin: DecoderPlugin = {
+    enhance: async (transaction: DecoderResult, options: DecoderOptions) => {
+      if (callbacks.overrideEnhance) {
+        return await callbacks.overrideEnhance(
+          transaction,
+          pluginOptions,
+          options
+        )
+      }
+      const { preferError } = options
+      const {
+        to: _to,
+        from: _from,
+        value: _value,
+        input,
+        blockNumber: _blockNumber,
+        // logs,
+      } = transaction as Partial<Transaction> & {
+        data?: `0x${string}`
+        logs?: Log[]
+      }
+      const to = _to || undefined
+      const from = _from || undefined
+      const value = _value ? BigInt(_value) : 0n
+      const decoded = customDecodeFunctionData(
+        {
+          abi,
+          data: input || '0x',
+        },
+        preferError
+      )
+      if (!decoded) {
+        // Most of the time decoded will through an error,
+        // but if the result is undefined, then assume it also
+        // didn't work.
+        return
+      }
+      const { functionName, sig, args } = decoded as ResultType & {
+        sig?: `0x${string}`
+        functionName?: string
+        args: Array<AbiParameter & { value?: unknown }>
+      }
+      const output: DecoderResult = {
+        isDecoded: true,
+        ...transaction,
+        resultType: 'execute',
+        functionName,
+        sig,
+        input,
+        __decoder: decoderName,
+        standard: abiName || 'unknown',
+        moduleHint,
+        args,
+        to,
+        from,
+        value,
+      } as DecoderResult
+      const enhanced = await callbacks.enhance(output, pluginOptions, options)
+      if (enhanced) {
+        return enhanced
+      }
+      return // This enhancement was denied by the enhancer so we need to re-try.
+    },
+    decodeEvent: async (log: DecodeEventResult, options: DecoderOptions) => {
+      return callbacks.decodeEvent(log, options)
+    },
+    getAggregationKey: async (result, pluginOptions, options) => {
+      if (!callbacks.getAggregationKey) {
+        return
+      }
+      return callbacks.getAggregationKey(result, pluginOptions, options)
+    },
+    summarize: async (aggregationKey, result, pluginOptions, options) => {
+      if (!callbacks.summarize) {
+        return
+      }
+      return callbacks.summarize(aggregationKey, result, pluginOptions, options)
+    },
+  }
+
+  // Add optional properties to the plugin
+  if (name !== undefined) {
+    plugin.name = name
+  }
+  if (required !== undefined) {
+    plugin.required = required
+  }
+  if (priority !== undefined) {
+    plugin.priority = priority
+  }
+
+  if (usesAsync !== undefined) {
+    plugin.usesAsync = usesAsync
+  }
+
+  if (callbacks.aggregations !== undefined) {
+    plugin.aggregations = callbacks.aggregations
+  }
+
+  // Freeze the plugin to prevent modifications
+  const frozenPlugin = Object.freeze(plugin)
+
+  // Auto-register the plugin if it has a name
+  // Use direct import of registry to avoid circular dependency
+  if (name) {
+    pluginRegistry.register(name, frozenPlugin, {
+      priority,
+      required,
+      usesAsync, // Include async flag for registration
+    })
+  }
+
+  return frozenPlugin
+}
+
+/**
+ * Creates a standard schema plugin from ERC725 schemas
+ * @param schemas Array of ERC725JSONSchema objects
+ * @param pluginOptions Options including name, required, priority
+ * @param process Optional post-processing function
+ * @returns SchemaPlugin
+ */
+export function standardSchemaPlugin(
+  schemas: ERC725JSONSchema[],
+  pluginOptions?: {
+    name?: string
+    required?: boolean
+    priority?: number
+  },
+  process?: (output: Info) => Promise<Info>
+): SchemaPlugin {
+  const basePlugin = decodeKeyValuePlugin(schemas, process)
+
+  // Create a proper SchemaPlugin by assigning properties to the function
+  const plugin = Object.assign(basePlugin, {
+    name: pluginOptions?.name,
+    required: pluginOptions?.required,
+    priority: pluginOptions?.priority ?? 50,
+  })
+
+  // Freeze the plugin to prevent modifications
+  return Object.freeze(plugin)
+}