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

package/src/decoder/utils.ts

@@ -0,0 +1,212 @@
+import {
+  type Abi,
+  type AbiFunction,
+  AbiFunctionSignatureNotFoundError,
+  type AbiParameter,
+  type Address,
+  type Chain,
+  createPublicClient,
+  type DecodeFunctionDataParameters,
+  decodeAbiParameters,
+  Hex,
+  http,
+  type PublicClient,
+  slice,
+  toFunctionSelector,
+} from 'viem'
+import { formatAbiItem } from 'viem/utils'
+import type {
+  ArrayArgs,
+  AsyncOperations,
+  CustomDecodeFunctionDataReturn,
+  DecoderResult,
+  EnhancedInfo,
+} from './types'
+
+/**
+ * Custom decoder for function data with additional named args support
+ * It's essentially the same code as decodeFunctionData, but also
+ * returning a namedArgs where we zip together the args and the inputs.
+ */
+export function customDecodeFunctionData<
+  const abi extends Abi | readonly unknown[],
+  preferError = false,
+>(
+  parameters: Partial<
+    DecodeFunctionDataParameters<abi> & {
+      namedArgs?:
+        | Record<number, AbiParameter & { value?: unknown }>
+        | Record<string, unknown>
+    }
+  >,
+  preferError?: boolean
+) {
+  try {
+    const { abi, data } = parameters as DecodeFunctionDataParameters
+    const signature = slice(data, 0, 4)
+    const description: AbiFunction | undefined = (abi.find(
+      (x) =>
+        x.type === (preferError ? 'error' : 'function') &&
+        signature === toFunctionSelector(formatAbiItem(x))
+    ) || undefined) as AbiFunction | undefined
+    if (!description)
+      throw new AbiFunctionSignatureNotFoundError(signature, {
+        docsPath: '/docs/contract/decodeFunctionData',
+      })
+    const args = (
+      'inputs' in description &&
+      description.inputs &&
+      description.inputs.length > 0
+        ? decodeAbiParameters(description.inputs, slice(data, 4))
+        : undefined
+    ) as readonly unknown[] | undefined
+    const result: {
+      functionName: string
+      sig: Hex
+      input: Hex
+      args?: ArrayArgs
+    } = {
+      functionName: (description as { name: string }).name,
+      sig: signature,
+      input: data,
+    }
+    if (args) {
+      const { args: namedArgs } = createNamedArgs(args, description.inputs)
+      result.args = namedArgs
+    }
+    return result as CustomDecodeFunctionDataReturn<abi>
+  } catch {}
+}
+
+export function createNamedArgs(
+  args: unknown[] | readonly unknown[],
+  inputs?: AbiParameter[] | readonly AbiParameter[]
+): { args: ArrayArgs } {
+  const array = args.map((value, index) => {
+    return {
+      name: `args${index + 1}`,
+      ...inputs?.[index],
+      value,
+    } as AbiParameter & { value: unknown }
+  })
+  return { args: array }
+}
+
+/**
+ * Get an argument value by its name from the args array.
+ * This utility function allows accessing arguments by name without needing namedArgs.
+ *
+ * @param args - The array of arguments with their metadata
+ * @param name - The name of the argument to find
+ * @returns The value of the argument if found, undefined otherwise
+ */
+export function getArgByName(
+  args: ArrayArgs | undefined,
+  name: string
+): unknown {
+  if (!args) return undefined
+
+  const arg = args.find((arg) => arg.name === name)
+  return arg?.value
+}
+
+export function extractAddress(address?: Address | EnhancedInfo) {
+  if (typeof address === 'object') {
+    return address.address
+  }
+  return address
+}
+
+const clients: Record<number, PublicClient> = {} as Record<number, PublicClient>
+export function getPublicClient(chain: Chain): PublicClient {
+  const { id } = chain
+  if (!id) {
+    throw new Error('Chain ID is required to create a public client')
+  }
+  if (!clients[id]) {
+    clients[id] = createPublicClient({
+      chain,
+      transport: http(),
+      batch: {
+        multicall: {
+          batchSize: 100,
+        },
+      },
+    })
+  }
+  const result = clients[id]
+  if (!result) {
+    throw new Error(`Public client for chain ID ${id} not found`)
+  }
+  return result
+}
+
+/**
+ * Helper to check if a specific async operation is enabled
+ */
+export function isAsyncOperationEnabled(
+  asyncOption: boolean | AsyncOperations | undefined,
+  operation: AsyncOperations
+): boolean {
+  // Handle backward compatibility
+  if (typeof asyncOption === 'boolean') {
+    return asyncOption
+  }
+  // If not specified, default to DISABLED
+  if (asyncOption === undefined) {
+    return false
+  }
+  // Check bitmap
+  return (asyncOption & operation) !== 0
+}
+
+/**
+ * Check if a single decoded item needs enhancement
+ * @param item - A single decoded result (not checking children)
+ * @returns true if this specific item needs enhancement
+ */
+function needsEnhancementSingle(item: DecoderResult): boolean {
+  // If sig is "0x", there's no function signature to decode
+  if ('sig' in item && item.sig === '0x') {
+    return false
+  }
+
+  // If it has a standard, it's already identified
+  if (item.standard) {
+    return false
+  }
+
+  // Otherwise it needs enhancement
+  return true
+}
+
+/**
+ * Check if a decoded result needs enhancement
+ * Returns true if the result OR any of its children need enhancement
+ */
+export function needsEnhancement(result: DecoderResult): boolean {
+  // Check if the main result needs enhancement
+  if (needsEnhancementSingle(result)) {
+    return true
+  }
+
+  // Check if any children need enhancement
+  if ('children' in result && Array.isArray(result.children)) {
+    return result.children.some((child) => {
+      // Children might be ResultType or ResultSetData, which don't have all DecoderResult fields
+      // We only check for standard property which is common to all
+      if (child.standard) {
+        return false
+      }
+      // If sig is "0x", there's no function signature to decode
+      if ('sig' in child && child.sig === '0x') {
+        return false
+      }
+      // Otherwise it needs enhancement
+      return true
+    })
+  }
+
+  // Nothing needs enhancement
+  return false
+}

package/src/example/usage.ts

@@ -0,0 +1,172 @@
+import debug from 'debug'
+import type { Transaction } from 'viem'
+import { lukso } from 'viem/chains'
+import { createDataModel } from '../data'
+import {
+  AddressResolver,
+  createMemoryAddressCache,
+  DecoderIntegration,
+  DecoderResult,
+} from '../index'
+
+const setupDecoderLog = debug('app:setupDecoder')
+
+/**
+ * Example of how to connect all the decoder pieces together
+ */
+export async function setupDecoder() {
+  // 1. Create data model with callbacks
+  const dataModel = createDataModel({
+    onMissingKeys: (keys) => {
+      setupDecoderLog('Missing address data for:', keys)
+      // Could trigger address resolution here
+    },
+    onNewTransaction: (tx) => {
+      setupDecoderLog('New transaction added:', tx)
+    },
+  })
+
+  // 2. Create address cache (could be IndexedDB, localStorage, etc)
+  const addressCache = createMemoryAddressCache()
+
+  // Alternative: Create IndexedDB cache
+  // const addressCache = createIndexedDBCache('decoder-addresses')
+
+  // 3. Create decoder integration
+  const decoder = new DecoderIntegration({
+    dataModel,
+    decoderOptions: {
+      chain: lukso,
+      preferError: false,
+    },
+    addressCache,
+  })
+
+  // 4. Create address resolver for GraphQL
+  const addressResolver = new AddressResolver({
+    dataModel,
+    graphqlEndpoint: 'https://api.universalprofile.cloud/graphql',
+    chain: lukso,
+    batchSize: 50,
+    batchDelay: 100,
+  })
+
+  // 5. Start watching for missing addresses
+  addressResolver.startWatching()
+
+  return {
+    dataModel,
+    decoder,
+    addressResolver,
+    addressCache,
+  }
+}
+
+/**
+ * Example of adding and decoding transactions
+ */
+export async function handleTransaction(tx: DecoderResult) {
+  const { decoder } = await setupDecoder()
+
+  // Add and decode transaction
+  const signal = await decoder.addAndDecodeTransaction(tx)
+
+  // React to updates
+  signal.subscribe((state) => {
+    setupDecoderLog('Transaction state updated:', {
+      loading: state.loading,
+      decodingStatus: state.decodingStatus,
+      addresses: state.addresses,
+      data: state.data,
+    })
+  })
+
+  // Get immediate data
+  const currentState = signal.value
+  setupDecoderLog('Current transaction data:', currentState.data)
+
+  return signal
+}
+
+/**
+ * Example of batch processing
+ */
+export async function handleTransactionBatch(transactions: DecoderResult[]) {
+  const { decoder, dataModel } = await setupDecoder()
+
+  // Add and decode all transactions
+  const signals = await decoder.addAndDecodeTransactions(transactions)
+
+  // Monitor overall progress
+  let completed = 0
+  for (const signal of signals) {
+    signal.subscribe((state) => {
+      if (
+        state.decodingStatus === 'complete' ||
+        state.decodingStatus === 'failed'
+      ) {
+        completed++
+        setupDecoderLog(`Progress: ${completed}/${transactions.length}`)
+      }
+    })
+  }
+
+  // Get all transaction data
+  const allTransactions = dataModel.getAllTransactions()
+  setupDecoderLog('All transactions:', allTransactions)
+
+  return signals
+}
+
+/**
+ * Example of manual address resolution
+ */
+export async function resolveAddresses() {
+  const { dataModel, decoder } = await setupDecoder()
+
+  // Get missing addresses
+  const missing = decoder.getMissingAddresses()
+  setupDecoderLog('Missing addresses:', missing)
+
+  // Manually fetch and inject address data
+  // (normally handled by AddressResolver automatically)
+  const addressData = await fetchAddressDataFromAPI(missing)
+  await decoder.loadAddressData(addressData)
+
+  // Check if all resolved
+  const stillMissing = decoder.getMissingAddresses()
+  setupDecoderLog('Still missing:', stillMissing)
+}
+
+// Mock function for example
+async function fetchAddressDataFromAPI(addresses: unknown[]) {
+  // This would be your actual API call
+  return []
+}
+
+/**
+ * Example of using with a UI framework (e.g., Vue)
+ */
+export function useInVueComponent() {
+  // In a Vue component
+  /*
+  import { computed, onMounted } from 'vue'
+  import { getAddress, getTransaction } from '@lukso/decoder'
+  
+  export default {
+    props: ['address', 'txHash'],
+    setup(props) {
+      const addressSignal = getAddress(props.address)
+      const txSignal = getTransaction({ hash: props.txHash })
+      
+      const addressName = computed(() => addressSignal.value.data?.name || 'Unknown')
+      const txStatus = computed(() => txSignal?.value.decodingStatus || 'loading')
+      
+      return {
+        addressName,
+        txStatus
+      }
+    }
+  }
+  */
+}

package/src/index.ts

@@ -0,0 +1,174 @@
+/**
+ * @lukso/decoder - Consumer API
+ *
+ * This is the main entry point for consumers of the decoder.
+ * Import data provider functions from '@lukso/transaction-decoder/data' instead.
+ */
+
+import { consumerModel, createGlobalInstance } from './core/instance'
+
+// Export all types that consumers need
+export type {
+  AddressState,
+  DataKey,
+  EnhancedInfo,
+  IDataModelConsumer,
+  TransactionState,
+} from './types'
+// DecoderResult is exported from decoder/types via the decoder imports below
+
+// Export all consumer methods directly
+export const getTransaction = consumerModel.getTransaction.bind(consumerModel)
+export const getTransactionByKey =
+  consumerModel.getTransactionByKey.bind(consumerModel)
+export const getTransactionsByIndex =
+  consumerModel.getTransactionsByIndex.bind(consumerModel)
+export const getTransactionHashByIndex =
+  consumerModel.getTransactionHashByIndex.bind(consumerModel)
+export const getTransactionCount =
+  consumerModel.getTransactionCount.bind(consumerModel)
+export const getDecodedCount = consumerModel.getDecodedCount.bind(consumerModel)
+export const getDecodedTransactions =
+  consumerModel.getDecodedTransactions.bind(consumerModel)
+export const getTransactionsInOrder =
+  consumerModel.getTransactionsInOrder.bind(consumerModel)
+
+// Address methods
+export const getAddress = consumerModel.getAddress.bind(consumerModel)
+export const getSignal = consumerModel.getSignal.bind(consumerModel)
+export const subscribe = consumerModel.subscribe.bind(consumerModel)
+export const getState = consumerModel.getState.bind(consumerModel)
+export const hasData = consumerModel.hasData.bind(consumerModel)
+export const getData = consumerModel.getData.bind(consumerModel)
+export const isLoading = consumerModel.isLoading.bind(consumerModel)
+export const getError = consumerModel.getError.bind(consumerModel)
+
+// Collection methods
+export const getAllKeys = consumerModel.getAllKeys.bind(consumerModel)
+export const getAllData = consumerModel.getAllData.bind(consumerModel)
+export const getAllTransactions =
+  consumerModel.getAllTransactions.bind(consumerModel)
+
+// Also export the consumer model instance for advanced usage
+export { consumerModel }
+
+// Export the function to create global instance (for manual setup)
+export { createGlobalInstance }
+
+// Export client utilities
+export {
+  createApiAddressResolver,
+  type ResolveAddressesOptions,
+  type ResolveAddressesResponse,
+  resolveAddresses,
+} from './client/resolveAddresses'
+// Export address collection utilities from core
+export { collectDataKeys } from './core/addressCollector'
+export {
+  AddressResolver,
+  type AddressResolverConfig,
+} from './core/addressResolver'
+// Export integration classes
+export {
+  type AddressCache,
+  createMemoryAddressCache,
+  DecoderIntegration,
+  type DecoderIntegrationConfig,
+} from './core/integrateDecoder'
+// Export aggregation utilities
+export {
+  type AggregationState,
+  PluginAggregationEngine,
+  standardAggregation,
+} from './decoder/aggregation'
+export type {
+  AddressResolver as TransactionAddressResolver,
+  TransactionDecoderResult,
+} from './decoder/decodeTransaction'
+// Export decoder integration utilities
+export {
+  decodeTransaction,
+  decodeTransactionAsync,
+} from './decoder/decodeTransaction'
+// Export plugin development utilities
+// Export default plugins to ensure they're imported and register themselves
+export {
+  createAggregationKey,
+  defaultPlugins,
+  defaultSchemaPlugins,
+  standardPlugin,
+  standardSchemaPlugin,
+} from './decoder/plugins'
+export type {
+  PluginMetadata,
+  SchemaPluginMetadata,
+} from './decoder/registry'
+export {
+  createNamedPlugin,
+  createNamedSchemaPlugin,
+  pluginRegistry,
+  registerPlugin,
+  registerSchemaPlugin,
+} from './decoder/registry'
+export type {
+  Aggregation,
+  DecodeEventCallback,
+  DecodeEventResult,
+  DecoderPlugin,
+  DecoderResult,
+  EnhancerCallback,
+  PluginOptions,
+  ResultAggregate,
+  ResultCreate,
+  ResultError,
+  ResultExecute,
+  ResultExecuteBatch,
+  ResultFollowProfile,
+  ResultGrafitti,
+  ResultRaw,
+  ResultSetData,
+  ResultSetDataBatch,
+  ResultWrapper,
+  SchemaPlugin,
+} from './decoder/types'
+// Export utility functions
+export { getArgByName, needsEnhancement } from './decoder/utils'
+// Export LSP23 deployment resolver utilities
+// Note: Actual Hypersync querying should be done via wallet-app API to protect HYPERSYNC_TOKEN
+export {
+  buildLSP23DeploymentQuery,
+  DEPLOY_ERC1167_PROXIES_SELECTOR,
+  decodeDeploymentCalldata,
+  decodeDeploymentOutput,
+  extractControllersFromInitCalldata,
+  type HypersyncQueryConfig,
+  LSP23_FACTORY_ADDRESS,
+  type LSP23DeploymentData,
+  parseLSP23DeploymentsFromHypersync,
+} from './server/lsp23Resolver'
+// Export shared address resolver utilities
+export {
+  type AssetData,
+  fetchMultipleAddresses,
+  fetchProfilesByControllers,
+  getGraphQLEndpoint,
+  getImage,
+  type ImageData,
+  type ImageURL,
+  type LinkData,
+  type ProfileData,
+  type TFetchAddressData,
+  type TokenData,
+} from './shared/addressResolver'
+// Export cache utilities
+export {
+  type AddressIdentityCache,
+  createMemoryAddressIdentityCache,
+  dataKeyToString,
+  getDataKeyCacheKey,
+  parseDataKey,
+} from './shared/cache'
+// Export debug utility for edge/worker environments
+export { createDebug } from './utils/debug'
+// Export JSON BigInt serializer/deserializer
+export { JSONbigString } from './utils/json-bigint'

package/src/server/addressResolver.ts

@@ -0,0 +1,68 @@
+import type { Chain } from 'viem'
+import { fetchMultipleAddresses } from '../shared/addressResolver'
+import type { AddressIdentityCache } from '../shared/cache'
+import type { DataKey, EnhancedInfo } from '../types'
+import type { ServerDecoderCaches } from './caches'
+
+/**
+ * Server-side address resolver with caching
+ */
+export class ServerAddressResolver {
+  private cacheAdapter: AddressIdentityCache
+
+  constructor(
+    private graphqlEndpoint: string,
+    private chain: Chain,
+    private caches: ServerDecoderCaches
+  ) {
+    // Create adapter to use ServerDecoderCaches as AddressIdentityCache
+    this.cacheAdapter = {
+      get: (key: DataKey) => this.caches.getAddress(key),
+      set: (key: DataKey, value: EnhancedInfo) =>
+        this.caches.setAddress(key, value),
+      has: (key: DataKey) => this.caches.hasAddress(key),
+      getMany: (keys: DataKey[]) => this.caches.getAddresses(keys),
+    }
+  }
+
+  /**
+   * Resolve addresses, using cache when possible
+   */
+  async resolveAddresses(
+    addresses: readonly DataKey[]
+  ): Promise<Map<DataKey, EnhancedInfo>> {
+    // Use the shared implementation with cache adapter
+    return fetchMultipleAddresses(
+      addresses,
+      this.graphqlEndpoint,
+      this.cacheAdapter
+    )
+  }
+
+  /**
+   * Resolve addresses with timeout
+   */
+  async resolveAddressesWithTimeout(
+    addresses: DataKey[],
+    timeoutMs: number
+  ): Promise<Map<DataKey, EnhancedInfo>> {
+    return Promise.race([
+      this.resolveAddresses(addresses),
+      new Promise<Map<DataKey, EnhancedInfo>>((resolve) => {
+        setTimeout(() => {
+          // On timeout, return whatever we have cached
+          const results = this.caches.getAddresses(addresses)
+          resolve(results)
+        }, timeoutMs)
+      }),
+    ])
+  }
+
+  /**
+   * Warm the cache with specific addresses
+   */
+  async warmCache(addresses: DataKey[]): Promise<void> {
+    // Simply call resolveAddresses which will cache any uncached addresses
+    await this.resolveAddresses(addresses)
+  }
+}