@lukso/transaction-decoder 1.3.6-dev.ea75859 → 1.3.7-dev.2df3eae

package/src/decoder/plugins/universalReceiverTypeIds.ts

@@ -0,0 +1,277 @@
+import type { AbiParameter, Address, Hex } from 'viem'
+import {
+  decodeAbiParameters,
+  encodeAbiParameters,
+  getAddress,
+  keccak256,
+  slice,
+  toHex,
+} from 'viem'
+import type { ArrayArgs } from '../types'
+import { createNamedArgs } from '../utils'
+
+/**
+ * Result of unwrapping a UniversalReceiver event based on its typeId.
+ * Contains the inner event that was wrapped by the UniversalReceiver notification,
+ * including rewritten topics and data fields matching the inner event's ABI.
+ */
+export type UnwrapResult = {
+  eventName: string
+  args: ArrayArgs
+  standard?: string
+  topics: [Hex, ...Hex[]]
+  data: Hex
+}
+
+type UnwrapFn = (
+  receivedData: Hex,
+  from: Address,
+  profileAddress: Address,
+  eventName: string
+) => UnwrapResult | undefined
+
+/**
+ * Compute topic0 (event signature hash) and ABI-encode the data field
+ * for an event with all non-indexed parameters.
+ */
+function encodeEventLog(
+  eventName: string,
+  params: AbiParameter[],
+  values: unknown[]
+): { topics: [Hex, ...Hex[]]; data: Hex } {
+  const sig = `${eventName}(${params.map((p) => p.type).join(',')})`
+  const topic0 = keccak256(toHex(sig))
+  const data = encodeAbiParameters(params, values)
+  return { topics: [topic0], data }
+}
+
+// --- LSP26 FollowerSystem ---
+
+// keccak256('LSP26FollowerSystem_FollowNotification')
+const TYPEID_LSP26_FOLLOW: Hex =
+  '0x71e02f9f05bcd5816ec4f3134aa2e5a916669537ec6c77fe66ea595fabc2d51a'
+
+// keccak256('LSP26FollowerSystem_UnfollowNotification')
+const TYPEID_LSP26_UNFOLLOW: Hex =
+  '0x9d3c0b4012b69658977b099bdaa51eff0f0460f421fba96d15669506c00d1c4f'
+
+// --- LSP7 DigitalAsset ---
+
+// keccak256('LSP7Tokens_SenderNotification')
+const TYPEID_LSP7_TOKENSSENDER: Hex =
+  '0x429ac7a06903dbc9c13dfcb3c9d11df8194581fa047c96d7a4171fc7402958ea'
+
+// keccak256('LSP7Tokens_RecipientNotification')
+const TYPEID_LSP7_TOKENSRECIPIENT: Hex =
+  '0x20804611b3e2ea21c480dc465142210acf4a2485947541770ec1fb87dee4a55c'
+
+// --- LSP8 IdentifiableDigitalAsset ---
+
+// keccak256('LSP8Tokens_SenderNotification')
+const TYPEID_LSP8_TOKENSSENDER: Hex =
+  '0xb23eae7e6d1564b295b4c3e3be402d9a2f0776c57bdf365903496f6fa481ab00'
+
+// keccak256('LSP8Tokens_RecipientNotification')
+const TYPEID_LSP8_TOKENSRECIPIENT: Hex =
+  '0x0b084a55ebf70fd3c06fd755269dac2212c4d3f0f4d09079780bfa50c1b2984d'
+
+// --- Event parameter definitions ---
+
+const followParams: AbiParameter[] = [
+  { name: 'follower', type: 'address' },
+  { name: 'addr', type: 'address' },
+]
+
+const unfollowParams: AbiParameter[] = [
+  { name: 'unfollower', type: 'address' },
+  { name: 'addr', type: 'address' },
+]
+
+const lsp7TransferParams: AbiParameter[] = [
+  { name: 'operator', type: 'address' },
+  { name: 'from', type: 'address' },
+  { name: 'to', type: 'address' },
+  { name: 'amount', type: 'uint256' },
+  { name: 'force', type: 'bool' },
+  { name: 'data', type: 'bytes' },
+]
+
+const lsp8TransferParams: AbiParameter[] = [
+  { name: 'operator', type: 'address' },
+  { name: 'from', type: 'address' },
+  { name: 'to', type: 'address' },
+  { name: 'tokenId', type: 'bytes32' },
+  { name: 'force', type: 'bool' },
+  { name: 'data', type: 'bytes' },
+]
+
+const notificationParams: AbiParameter[] = [
+  { name: 'from', type: 'address' },
+  { name: 'typeId', type: 'bytes32' },
+  { name: 'data', type: 'bytes' },
+]
+
+/**
+ * Decode LSP26 Follow notification.
+ * receivedData is abi.encodePacked(followerAddress) — raw 20 bytes.
+ */
+function unwrapLSP26Follow(
+  receivedData: Hex,
+  _from: Address,
+  profileAddress: Address,
+  _eventName: string
+): UnwrapResult | undefined {
+  if (!receivedData || receivedData.length < 42) {
+    return undefined
+  }
+  const followerAddress = getAddress(slice(receivedData, 0, 20))
+  const values = [followerAddress, profileAddress]
+  return {
+    eventName: 'URDFollow',
+    ...createNamedArgs(values, followParams),
+    ...encodeEventLog('URDFollow', followParams, values),
+    standard: 'LSP26FollowerSystem',
+  }
+}
+
+/**
+ * Decode LSP26 Unfollow notification.
+ * receivedData is abi.encodePacked(unfollowerAddress) — raw 20 bytes.
+ */
+function unwrapLSP26Unfollow(
+  receivedData: Hex,
+  _from: Address,
+  profileAddress: Address,
+  _eventName: string
+): UnwrapResult | undefined {
+  if (!receivedData || receivedData.length < 42) {
+    return undefined
+  }
+  const unfollowerAddress = getAddress(slice(receivedData, 0, 20))
+  const values = [unfollowerAddress, profileAddress]
+  return {
+    eventName: 'URDUnfollow',
+    ...createNamedArgs(values, unfollowParams),
+    ...encodeEventLog('URDUnfollow', unfollowParams, values),
+    standard: 'LSP26FollowerSystem',
+  }
+}
+
+/**
+ * Decode LSP7 token transfer notification.
+ * receivedData is abi.encode(operator, from, to, amount, data).
+ */
+function unwrapLSP7Transfer(
+  receivedData: Hex,
+  _from: Address,
+  _profileAddress: Address,
+  eventName: string
+): UnwrapResult | undefined {
+  try {
+    const [operator, sender, recipient, amount, data] = decodeAbiParameters(
+      [
+        { name: 'operator', type: 'address' },
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'amount', type: 'uint256' },
+        { name: 'data', type: 'bytes' },
+      ],
+      receivedData
+    )
+    const values = [operator, sender, recipient, amount, true, data]
+    return {
+      eventName,
+      ...createNamedArgs(values, lsp7TransferParams),
+      ...encodeEventLog(eventName, lsp7TransferParams, values),
+      standard: 'LSP7DigitalAsset',
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Decode LSP8 token transfer notification.
+ * receivedData is abi.encode(operator, from, to, tokenId, data).
+ */
+function unwrapLSP8Transfer(
+  receivedData: Hex,
+  _from: Address,
+  _profileAddress: Address,
+  eventName: string
+): UnwrapResult | undefined {
+  try {
+    const [operator, sender, recipient, tokenId, data] = decodeAbiParameters(
+      [
+        { name: 'operator', type: 'address' },
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'tokenId', type: 'bytes32' },
+        { name: 'data', type: 'bytes' },
+      ],
+      receivedData
+    )
+    const values = [operator, sender, recipient, tokenId, true, data]
+    return {
+      eventName,
+      ...createNamedArgs(values, lsp8TransferParams),
+      ...encodeEventLog(eventName, lsp8TransferParams, values),
+      standard: 'LSP8IdentifiableDigitalAsset',
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Registry mapping typeId → unwrap function.
+ */
+const typeIdUnwrappers: Record<Hex, { fn: UnwrapFn; eventName: string }> = {
+  [TYPEID_LSP26_FOLLOW]: { fn: unwrapLSP26Follow, eventName: 'Follow' },
+  [TYPEID_LSP26_UNFOLLOW]: { fn: unwrapLSP26Unfollow, eventName: 'Unfollow' },
+  [TYPEID_LSP7_TOKENSSENDER]: {
+    fn: unwrapLSP7Transfer,
+    eventName: 'URDTokensSent',
+  },
+  [TYPEID_LSP7_TOKENSRECIPIENT]: {
+    fn: unwrapLSP7Transfer,
+    eventName: 'URDTokensReceived',
+  },
+  [TYPEID_LSP8_TOKENSSENDER]: {
+    fn: unwrapLSP8Transfer,
+    eventName: 'URDTokensSent',
+  },
+  [TYPEID_LSP8_TOKENSRECIPIENT]: {
+    fn: unwrapLSP8Transfer,
+    eventName: 'URDTokensReceived',
+  },
+}
+
+/**
+ * Unwrap a UniversalReceiver event based on its typeId.
+ * For known typeIds, decodes receivedData into specific event args.
+ * For unknown typeIds, returns a generic Notification with raw receivedData.
+ * Always rewrites topics and data to match the inner event's ABI.
+ */
+export function unwrapUniversalReceiver(
+  typeId: Hex,
+  receivedData: Hex,
+  from: Address,
+  profileAddress: Address
+): UnwrapResult {
+  const entry = typeIdUnwrappers[typeId]
+  if (entry) {
+    const result = entry.fn(receivedData, from, profileAddress, entry.eventName)
+    if (result) {
+      return result
+    }
+  }
+
+  // Fallback: generic notification with raw data
+  const values = [from, typeId, receivedData]
+  return {
+    eventName: 'URDNotification',
+    ...createNamedArgs(values, notificationParams),
+    ...encodeEventLog('Notification', notificationParams, values),
+  }
+}

package/src/decoder/types.ts

@@ -461,5 +461,7 @@ export type DecodeEventResult =
   | ({
       eventName: string
       args: ArrayArgs
+      wrappers?: Array<{ eventName: string; args: ArrayArgs } & Log>
+      standard?: string
     } & Log)
   | undefined

package/src/server/decodeEventLogs.ts

@@ -0,0 +1,71 @@
+import type { Hex } from 'viem'
+import { decodeKeyValueRaw } from '../decoder/plugins'
+import { pluginRegistry } from '../decoder/registry'
+import type { DecodeEventResult, DecoderOptions } from '../decoder/types'
+import type { ServerDecoderCaches } from './caches'
+import type { ServerDecoderOptions } from './types'
+
+/**
+ * Decode an array of raw log events using the registered decoder plugins.
+ *
+ * Uses the same plugin iteration pattern as transaction.ts:
+ * try each plugin's `decodeEvent`, first match wins, raw log kept as fallback.
+ *
+ * For DataChanged events, also decodes the ERC725Y key-value pair using
+ * the schema plugin system (same as setData transaction decoding).
+ */
+export async function decodeEventLogs(
+  logs: DecodeEventResult[],
+  options: ServerDecoderOptions,
+  _caches: ServerDecoderCaches
+): Promise<DecodeEventResult[]> {
+  const { chain } = options
+  const plugins = await pluginRegistry.getAll({ syncOnly: true })
+  const schemaPlugins = pluginRegistry.getAllSchema()
+
+  const decoderOptions: DecoderOptions = {
+    chain,
+    plugins,
+    schemaPlugins,
+    wrappers: [],
+    async: false,
+  }
+
+  const results: DecodeEventResult[] = []
+
+  for (const log of logs) {
+    let decoded: DecodeEventResult
+    for (const plugin of plugins) {
+      decoded = await plugin.decodeEvent(log, decoderOptions)
+      if (decoded) break
+    }
+    const result = decoded ?? log
+
+    // For DataChanged events, decode the ERC725Y key-value pair
+    if (result?.eventName === 'DataChanged' && result.args) {
+      try {
+        const dataKey = result.args.find((a) => a.name === 'dataKey')?.value as
+          | Hex
+          | undefined
+        const dataValue = result.args.find((a) => a.name === 'dataValue')
+          ?.value as Hex | undefined
+        if (dataKey) {
+          const info = await decodeKeyValueRaw(
+            dataKey,
+            dataValue ?? '0x',
+            decoderOptions
+          )
+          if (info) {
+            ;(result as Record<string, unknown>).info = info
+          }
+        }
+      } catch {
+        // Schema decoding failed — keep event without info
+      }
+    }
+
+    results.push(result)
+  }
+
+  return results
+}

package/src/server/index.ts

@@ -1,5 +1,6 @@
 import { ServerAddressResolver } from './addressResolver'
 import { ServerDecoderCaches } from './caches'
+import { decodeEventLogs } from './decodeEventLogs'
 import { decodeTransactionSync } from './decodeTransactionSync'
 import { decodeTransactionsBatch } from './decodeTransactionsBatch'
 import { finishDecoding } from './finishDecoding'
@@ -77,5 +78,14 @@ export function createServerDecoder(
     async resolveAddresses(addresses, timeoutMs = 3000) {
       return addressResolver.resolveAddressesWithTimeout(addresses, timeoutMs)
     },
+
+    async decodeEventLogs(logs, options) {
+      const opts: ServerDecoderOptions = {
+        chain: config.defaultChain,
+        timeoutMs: config.defaultTimeout,
+        ...options,
+      }
+      return decodeEventLogs(logs, opts, caches)
+    },
   }
 }

package/src/server/types.ts

@@ -1,5 +1,10 @@
 import type { Chain } from 'viem'
-import type { DataKey, DecoderResult, EnhancedInfo } from '../types'
+import type {
+  DataKey,
+  DecodeEventResult,
+  DecoderResult,
+  EnhancedInfo,
+} from '../types'
 
 /**
  * Options for server-side decoding
@@ -165,4 +170,12 @@ export interface ServerDecoder {
     addresses: DataKey[],
     timeoutMs?: number
   ) => Promise<Map<DataKey, EnhancedInfo>>
+
+  /**
+   * Decode an array of raw log events using registered decoder plugins
+   */
+  decodeEventLogs: (
+    logs: DecodeEventResult[],
+    options?: Partial<ServerDecoderOptions>
+  ) => Promise<DecodeEventResult[]>
 }

package/src/server.ts

@@ -10,6 +10,7 @@
 
 export { ServerAddressResolver } from './server/addressResolver'
 export { ServerDecoderCaches } from './server/caches'
+export { decodeEventLogs } from './server/decodeEventLogs'
 export { decodeTransactionSync } from './server/decodeTransactionSync'
 export { decodeTransactionsBatch } from './server/decodeTransactionsBatch'
 export { createServerDecoder } from './server/index'

package/src/types/index.ts

@@ -7,7 +7,11 @@ import type { Hex } from 'viem'
 import type { DecoderResult, EnhancedInfo } from '../decoder/types'
 
 // Re-export decoder types
-export type { DecoderResult, EnhancedInfo } from '../decoder/types'
+export type {
+  DecodeEventResult,
+  DecoderResult,
+  EnhancedInfo,
+} from '../decoder/types'
 export { AsyncOperations } from '../decoder/types'
 
 // Key is always a hex string - for tokens it's in the format "address:tokenId"