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

package/src/decoder/events.ts

@@ -0,0 +1,192 @@
+import {
+  type Abi,
+  AbiDecodingDataSizeTooSmallError,
+  AbiEventSignatureEmptyTopicsError,
+  AbiEventSignatureNotFoundError,
+  type AbiParameter,
+  BaseError,
+  type Chain,
+  type ContractEventName,
+  type DecodeEventLogParameters,
+  type DecodeEventLogReturnType,
+  DecodeLogDataMismatch,
+  DecodeLogTopicsMismatch,
+  decodeAbiParameters,
+  type EventDefinition,
+  type Hex,
+  type Log,
+  size,
+  toEventSelector,
+} from 'viem'
+import { formatAbiItem } from 'viem/utils'
+import type { ArrayArgs, DecodeEventResult } from './types'
+import { createNamedArgs } from './utils'
+
+const docsPath = '/docs/contract/decodeEventLog'
+
+function decodeTopic({ param, value }: { param: AbiParameter; value: Hex }) {
+  if (
+    param.type === 'string' ||
+    param.type === 'bytes' ||
+    param.type === 'tuple' ||
+    param.type.match(/^(.*)\[(\d+)?\]$/)
+  )
+    return value
+  const decodedArg = decodeAbiParameters([param], value) || []
+  return decodedArg[0]
+}
+
+export type PositionOutOfBoundsErrorType = PositionOutOfBoundsError & {
+  name: 'PositionOutOfBoundsError'
+}
+export class PositionOutOfBoundsError extends BaseError {
+  constructor({ length, position }: { length: number; position: number }) {
+    super(
+      `Position \`${position}\` is out of bounds (\`0 < position < ${length}\`).`,
+      { name: 'PositionOutOfBoundsError' }
+    )
+  }
+}
+
+/**
+ * Custom copy of decodeEventLog which can assemble named args.
+ * @param parameters
+ * @returns
+ */
+export function customDecodeEventLog<
+  const abi extends Abi | readonly unknown[],
+  eventName extends ContractEventName<abi> | undefined = undefined,
+  topics extends Hex[] = Hex[],
+  data extends Hex | undefined = undefined,
+  strict extends boolean = true,
+>(
+  parameters: DecodeEventLogParameters<abi, eventName, topics, data, strict>
+): DecodeEventLogReturnType<abi, eventName, topics, data, strict> {
+  const {
+    abi,
+    data,
+    strict: strict_,
+    topics,
+  } = parameters as DecodeEventLogParameters
+
+  const strict = strict_ ?? true
+  const [signature, ...argTopics] = topics
+  if (!signature) throw new AbiEventSignatureEmptyTopicsError({ docsPath })
+
+  const abiItem = (() => {
+    if (abi.length === 1) return abi[0]
+    return abi.find(
+      (x) =>
+        x.type === 'event' &&
+        signature === toEventSelector(formatAbiItem(x) as EventDefinition)
+    )
+  })()
+
+  if (!(abiItem && 'name' in abiItem) || abiItem.type !== 'event')
+    throw new AbiEventSignatureNotFoundError(signature, { docsPath })
+
+  const { name, inputs } = abiItem
+  const isUnnamed = inputs?.some((x) => !('name' in x && x.name))
+
+  let args: unknown[] | Record<string, unknown> = isUnnamed ? [] : {}
+
+  // Decode topics (indexed args).
+  const indexedInputs = inputs.filter((x) => 'indexed' in x && x.indexed)
+  for (let i = 0; i < indexedInputs.length; i++) {
+    const param = indexedInputs[i]
+    const topic = argTopics[i]
+    if (!topic)
+      throw new DecodeLogTopicsMismatch({
+        abiItem,
+        param: param as AbiParameter & { indexed: boolean },
+      })
+    if (isUnnamed && Array.isArray(args)) {
+      args[i] = decodeTopic({ param, value: topic })
+    } else if (!isUnnamed && !Array.isArray(args)) {
+      args[param.name || i] = decodeTopic({ param, value: topic })
+    }
+  }
+
+  // Decode data (non-indexed args).
+  const nonIndexedInputs = inputs.filter((x) => !('indexed' in x && x.indexed))
+  if (nonIndexedInputs.length > 0) {
+    if (data && data !== '0x') {
+      try {
+        const decodedData = decodeAbiParameters(nonIndexedInputs, data)
+        if (decodedData) {
+          if (isUnnamed && Array.isArray(args)) {
+            args = [...args, ...decodedData]
+          } else if (!isUnnamed && !Array.isArray(args)) {
+            for (let i = 0; i < nonIndexedInputs.length; i++) {
+              const name = nonIndexedInputs[i].name
+              if (name) {
+                args[name] = decodedData[i]
+              }
+            }
+          }
+        }
+      } catch (err) {
+        if (strict) {
+          if (
+            err instanceof AbiDecodingDataSizeTooSmallError ||
+            (err as { name?: string }).name === 'PositionOutOfBoundsError' // Unfortunately, this is not exported from viem
+          )
+            throw new DecodeLogDataMismatch({
+              abiItem,
+              data: data,
+              params: nonIndexedInputs,
+              size: size(data),
+            })
+          throw err
+        }
+      }
+    } else if (strict) {
+      throw new DecodeLogDataMismatch({
+        abiItem,
+        data: '0x',
+        params: nonIndexedInputs,
+        size: 0,
+      })
+    }
+  }
+  const { args: namedArgs } = createNamedArgs(
+    Array.isArray(args) ? args : Object.values(args),
+    inputs
+  )
+  return {
+    eventName: name,
+    args: namedArgs,
+  } as unknown as DecodeEventLogReturnType<abi, eventName, topics, data, strict>
+}
+
+/**
+ * Decode events
+ *
+ * @param log Transaction to decode (should have data/input)
+ * @returns Promise<ResultType>
+ */
+export function decodeEvent<abi extends Abi | readonly unknown[] = Abi>(
+  chain: Chain,
+  abi: abi,
+  log: DecodeEventResult
+):
+  | ({
+      eventName: string
+      args: ArrayArgs
+    } & DecodeEventResult)
+  | undefined {
+  const { data: _data, address, ...rest } = log as Log
+
+  let lastError: Error | undefined
+  try {
+    const result = customDecodeEventLog({
+      abi,
+      data: _data,
+      topics: (log as Log).topics || [],
+    })
+    return { ...log, ...result } as unknown as {
+      eventName: string
+      args: ArrayArgs
+    } & DecodeEventResult
+  } catch {}
+}

package/src/decoder/functionSignature.ts

@@ -0,0 +1,344 @@
+import {
+  type Abi,
+  type AbiParameter,
+  type Address,
+  type Chain,
+  decodeAbiParameters,
+  encodeAbiParameters,
+  getAddress,
+  isAddress,
+  isAddressEqual,
+  parseAbiParameters,
+  zeroAddress,
+} from 'viem'
+import { CacheKeyPrefix, makeCacheKey } from './cache'
+import { FUNCTION_DICTIONARY_URL, OPENCHAIN_DICTIONARY_URL } from './constants'
+import { createLRUCache } from './lruCache'
+import type { DecoderOptions, ResultType } from './types'
+import { createNamedArgs, customDecodeFunctionData } from './utils'
+
+// Default cache for backward compatibility
+const defaultCache = createLRUCache({
+  max: 500,
+  ttl: 60 * 1000, // 1 minute
+  errorTTL: 30 * 1000, // 30 seconds
+})
+
+/**
+ * Decode function parameter types from a function signature
+ *
+ * @param signature Function signature
+ * @returns Array of parameter types
+ * @throws Error if the signature is invalid
+ */
+function generateNamedAbiParameters(signature: string): AbiParameter[] {
+  const start = signature.indexOf('(')
+  const end = signature.lastIndexOf(')')
+  if (start === -1 || end === -1 || end <= start) {
+    throw new Error(`Invalid signature: ${signature}`)
+  }
+
+  const paramString = signature.slice(start + 1, end)
+
+  const rawParams = parseAbiParameters(paramString) as AbiParameter[]
+
+  const assignNames = (params: AbiParameter[], prefix: string) => {
+    return params.map((param: AbiParameter, index: number) => {
+      const name = `${prefix}${index + 1}`
+      if (param.type === 'tuple' && 'components' in param) {
+        const components: AbiParameter[] = assignNames(
+          param.components as AbiParameter[],
+          `${name}_`
+        )
+        return { ...param, name, components } as AbiParameter
+      }
+      return { ...param, name } as AbiParameter
+    })
+  }
+
+  return assignNames(rawParams, 'arg')
+}
+
+export async function fetchAbi(
+  chain: Chain,
+  address: Address,
+  options?: DecoderOptions
+) {
+  const explorer = chain.blockExplorers?.default?.apiUrl
+  if (!explorer) return undefined
+
+  const cache = options?.cache ?? defaultCache
+  let key = getAddress(address)
+  const cacheKey = makeCacheKey(CacheKeyPrefix.ABI, key, String(chain.id))
+
+  return cache.getOrSet(
+    cacheKey,
+    async (signal) => {
+      let isProxy = false
+      let decoderVerifiedContract = false
+      let factoryName: string | undefined
+      const originalKey = key
+
+      const addressUrl = new URL(`/api/v2/addresses/${key}`, explorer)
+      const addressRes = await fetch(addressUrl, { signal })
+      if (addressRes.ok) {
+        const data = (await addressRes.json()) as {
+          implementations?: { address?: Address; address_hash?: Address }[]
+          is_contract?: boolean
+          is_verified?: boolean
+          proxy_type?: string
+          name?: string
+        }
+        const {
+          implementations: [
+            { address: _address, address_hash: _addressHash } = {},
+          ] = [],
+          is_contract,
+          is_verified: __decoderVerifiedContract,
+          proxy_type,
+          name: __factoryName,
+        } = data
+        const address = _address || _addressHash
+        factoryName = __factoryName
+        decoderVerifiedContract = Boolean(__decoderVerifiedContract || false)
+        if (
+          address &&
+          is_contract &&
+          proxy_type !== 'null' &&
+          proxy_type != null
+        ) {
+          key = address as `0x${string}`
+          isProxy = true // We resolved from proxy to implementation
+        }
+      }
+
+      if (!decoderVerifiedContract) {
+        // If the address is not a verified contract, return undefined
+        return undefined
+      }
+
+      const url = new URL(`/api/v2/smart-contracts/${key}`, explorer)
+      const res = await fetch(url, { signal })
+
+      if (!res.ok) {
+        return undefined
+      }
+
+      const result = await res.json()
+      const {
+        name = factoryName || 'UnknownName',
+        abi,
+        is_verified,
+      } = result || {}
+
+      if (abi && is_verified) {
+        return {
+          abi,
+          __decoderVerifiedContract: decoderVerifiedContract, // If we have an ABI, treat it as verified
+          __decoderIsProxy: isProxy,
+          name,
+          explorer,
+        }
+      }
+      return undefined
+    },
+    { signal: options?.signal }
+  ) as Promise<
+    | {
+        abi: Abi
+        __decoderVerifiedContract: boolean
+        __decoderIsProxy: boolean
+        name: string
+        explorer: string
+      }
+    | undefined
+  >
+}
+
+/**
+ * Gets a function signature. Returns an empty string if hexSignature
+ * is not provided or an error is thrown.
+ * If hexSignature is provided, it checks the cache storage.
+ * If the signature is not found, it fetches 4bytes dictionary and stores
+ * the result in the cache storage.
+ *
+ * @param string hexSignature - first 4 bytes of a payload
+ * @param boolean preferError - if true, prefer error signatures
+ * @returns function signature as a string
+ */
+export const getFunctionSignature = async (
+  chain: Chain,
+  input?: `0x${string}`,
+  to?: `0x${string}`,
+  preferError = false,
+  options?: DecoderOptions
+): Promise<
+  ResultType & {
+    __decoder: string
+    __decoderVerifiedContract?: boolean
+    __decoderIsProxy?: boolean
+    standard?: string
+  }
+> => {
+  // Remove 0x prefix
+  if (to && isAddress(to) && isAddressEqual(to, zeroAddress)) {
+    return {
+      __decoder: 'none',
+      standard: 'unknown',
+      to,
+      input,
+      resultType: 'raw',
+    }
+  }
+  const data = input?.slice(2) as string
+  // Get the first 8 chars (4 bytes) of the data
+  const selector = data.slice(0, 8)
+  if (selector) {
+    if (to) {
+      // Wait for cached or new promise to resolve
+      const info = await fetchAbi(chain, to, options)
+      if (info) {
+        // The explorer returned it as a verified abi.
+        // Use the returned abi to decode the function signature.
+        const decoded = customDecodeFunctionData({
+          abi: info.abi,
+          data: input || '0x',
+        }) as ResultType & {
+          sig?: `0x${string}`
+          functionName?: string
+          args: readonly unknown[]
+        }
+        if (decoded) {
+          return {
+            ...decoded,
+            __decoder: info.explorer,
+            __decoderVerifiedContract: info.__decoderVerifiedContract,
+            __decoderIsProxy: info.__decoderIsProxy,
+            standard: info.name,
+          }
+        }
+      }
+    }
+    // If we didn't resolve it yet, then try to fetch from one of the 4bytes dictionaries.
+    const cache = options?.cache ?? defaultCache
+    const cacheKey = makeCacheKey(CacheKeyPrefix.FUNCTION_SIGNATURE, selector)
+
+    const signatureEntry = cache.getOrSet(
+      cacheKey,
+      async (signal) => {
+        // Try our proxy first.
+        const url = `${OPENCHAIN_DICTIONARY_URL}?function=0x${selector}`
+        let __decoder = new URL(OPENCHAIN_DICTIONARY_URL).hostname
+
+        try {
+          const res = await fetch(url, { signal })
+          if (res.ok) {
+            const result = await res.json()
+            if (result) {
+              result.__decoder = __decoder
+              return result
+            }
+          }
+        } catch {
+          // Continue to fallback
+        }
+
+        // Fallback to function dictionary
+        __decoder = new URL(FUNCTION_DICTIONARY_URL).hostname
+        const fallbackRes = await fetch(
+          `${FUNCTION_DICTIONARY_URL}/${selector}`,
+          { signal }
+        )
+        if (!fallbackRes.ok) {
+          return undefined
+        }
+        const fallbackResult = await fallbackRes.json()
+        if (fallbackResult) {
+          fallbackResult.__decoder = __decoder
+        }
+        return fallbackResult
+      },
+      { signal: options?.signal }
+    )
+    // Wait for cached or new promise to resolve
+    // biome-ignore lint/suspicious/noExplicitAny: any is easier in this particular case
+    const methods = (await signatureEntry) as any
+    if (methods?.results?.length > 0) {
+      // We got one or more results.
+      let search = methods.results.reverse()
+      if (preferError) {
+        // In case we're preferring Errors,
+        // then look for all methods containing Error
+        // and put them first.
+        const withError = search.filter((result: Record<string, unknown>) =>
+          /Error/.test(result.text_signature as string)
+        )
+        const withoutError = search.filter(
+          (result: Record<string, unknown>) =>
+            !/Error/.test(result.text_signature as string)
+        )
+        search = [...withError, ...withoutError]
+      }
+      // Go through each one and try to encode/decode the data
+      // to make sure it works.
+      for (const result of search) {
+        try {
+          const params: AbiParameter[] = generateNamedAbiParameters(
+            result.text_signature || result.name
+          )
+          // Decode arguments according to function spec
+          const args = decodeAbiParameters(params, `0x${data.slice(8)}`)
+
+          // Build arg list (if there are bool values which are no 0 or 1 we can assume it's invalid)
+          // Other values are validated in encodeParameters.
+          const encodeArgs = Array.from({ length: params.length }).map(
+            (_val, index) => {
+              if (params[index].type === 'bool') {
+                const val = args[`${index}`]
+                if (val !== 1 && val !== 0 && val !== true && val !== false) {
+                  // Due to javascript truthyness any non-empty or non-zero value is encoded as true without a problem.
+                  // The output packet won't match but there is really no reason to even try.
+                  throw new Error('Invalid boolean value')
+                }
+              }
+              if (params[index].type === 'address') {
+                const val = args[`${index}`] as `0x${string}`
+                if (!isAddress(val)) {
+                  throw new Error(`Invalid address value ${val}`)
+                }
+              }
+              return args[`${index}`] ?? '0x'
+            }
+          )
+
+          // Re-encode according to function spec.
+          const newData = encodeAbiParameters(
+            params,
+            encodeArgs as never
+          ).slice(2)
+
+          if (data.slice(8) === newData) {
+            return {
+              resultType: 'execute',
+              standard: 'unknown',
+              sig: `0x${selector}`,
+              functionName: result.text_signature.replace(/\(.*$/, ''),
+              ...(args
+                ? {
+                    ...createNamedArgs(encodeArgs, params),
+                  }
+                : {}),
+              __decoder: methods.__decoder || FUNCTION_DICTIONARY_URL,
+            } as ResultType & {
+              __decoder: string
+              __decoderVerifiedContract?: boolean
+            }
+          }
+        } catch (error) {
+          // Ignore to try next record
+        }
+      }
+    }
+  }
+  return undefined
+}