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

package/src/decoder/getDataFromExternalSources.ts

@@ -0,0 +1,248 @@
+import type {
+  DecodeDataOutput,
+  ERC725JSONSchema,
+  GetDataExternalSourcesOutput,
+  URLDataWithHash,
+} from '@erc725/erc725.js'
+import { isDataAuthentic, patchIPFSUrlsIfApplicable } from '@erc725/erc725.js'
+
+export async function loadFile(
+  _url: string,
+  ipfsGateway: string
+): Promise<ArrayBuffer | null> {
+  let url = _url
+  if (url.startsWith('data:')) {
+    // Handle data URLs
+    const base64Data = url.split(',')[1]
+    const binaryString = atob(base64Data)
+    const len = binaryString.length
+    const bytes = new Uint8Array(len)
+    for (let i = 0; i < len; i++) {
+      bytes[i] = binaryString.charCodeAt(i)
+    }
+    return Promise.resolve(bytes.buffer)
+  }
+  if (url.startsWith('ipfs://')) {
+    // Handle IPFS URLs
+    const ipfsHash = url.replace('ipfs://', '')
+    url = `${ipfsGateway}${ipfsHash}`
+  }
+  return fetch(url)
+    .then((response) => {
+      if (!response.ok) {
+        throw new Error('Network response was not ok')
+      }
+      return response.arrayBuffer()
+    })
+    .catch(() => null)
+}
+
+export const getDataFromExternalSources = (
+  schemas: ERC725JSONSchema[],
+  dataFromChain: DecodeDataOutput[],
+  ipfsGateway: string,
+  throwException = true
+): Promise<
+  Array<
+    GetDataExternalSourcesOutput & {
+      error?: string
+      method?: string
+      data?: string
+      url?: string
+      src?: string
+    }
+  >
+> => {
+  const promises = dataFromChain.map(async (dataEntry) => {
+    const schemaElement = schemas.find((schema) => schema.key === dataEntry.key)
+
+    if (!schemaElement) {
+      // It is weird if we can't find the schema element for the key...
+      // Let's simply ignore and return it...
+      return dataEntry
+    }
+
+    if (
+      !['jsonurl', 'asseturl', 'verifiableuri'].includes(
+        schemaElement.valueContent.toLowerCase()
+      )
+    ) {
+      return dataEntry
+    }
+
+    const urlDataWithHash: URLDataWithHash = dataEntry.value as URLDataWithHash // Type URLDataWithHash
+    let url: string | undefined
+    let src: string | undefined
+    try {
+      // At this stage, value should be of type jsonurl, verifiableuri or asseturl
+      if (typeof dataEntry.value === 'string') {
+        throw new Error(
+          `Value is string instead of ${schemaElement.valueContent}`
+        )
+      }
+
+      if (!dataEntry.value) {
+        throw new Error(`${schemaElement.valueContent} empty`)
+      }
+
+      if (Array.isArray(dataEntry.value)) {
+        throw new Error(
+          `Value is Array instead of ${schemaElement.valueContent}`
+        )
+      }
+
+      url = urlDataWithHash.url
+      ;({ url: src } = patchIPFSUrlsIfApplicable(
+        urlDataWithHash as URLDataWithHash,
+        ipfsGateway
+      ))
+      let length = 'unknown'
+      if (!url.startsWith('data:') && /[=?/]$/.test(url)) {
+        // this URL is not verifiable and the URL ends with a / or ? or = meaning it's not a file
+        // and more likely to be some kind of directory or query BaseU=== "errorRI
+        return dataEntry
+      }
+      const receivedData = /^data:|^ipfs:\/\/|\/ipfs\//.test(url)
+        ? await loadFile(src, ipfsGateway).then((buffer) =>
+            buffer
+              ? new Uint8Array(buffer)
+              : Promise.reject(new Error('No Data'))
+          )
+        : await fetch(src).then(async (response) => {
+            if (!response.ok) {
+              throw new Error(response.statusText)
+            }
+            return response
+              .arrayBuffer()
+              .then((buffer) => new Uint8Array(buffer))
+          })
+      length = receivedData.length.toString()
+      const captureHashes: Record<string, string> = {}
+      const captureErrors: string[] = []
+      if (receivedData.length >= 2) {
+        // JSON data cannot be less than 2 characters long.
+        try {
+          // - Build a string containing the first and last byte of the received data
+          //   and try to convert it to utf8. If that succeeds then
+          // - check whether those could represent valid JSON data.
+          // - then validate the data as JSON
+          // - then verfiy the data against the verification method
+          // Improved JSON detection. We now check the first and up to the last 3 bytes.
+          // The 3 bytes can be `]` or '}' with either SPACE, LF or CRLF at the end.
+          // When editing JSON using a text editor, a lot of time it's pretty printed
+          // and an empty line added to the end. This is a common pattern.
+          const capture: number[] = []
+          capture.push(receivedData[0])
+          if (receivedData.length > 3) {
+            capture.push(receivedData[receivedData.length - 3])
+          }
+          if (receivedData.length > 2) {
+            capture.push(receivedData[receivedData.length - 2])
+          }
+          if (receivedData.length > 1) {
+            capture.push(receivedData[receivedData.length - 1])
+          }
+          const key = String.fromCharCode.apply(null, capture)
+          // Currently not supported even though they could be added and can represent valid JSON.
+          // " " => JSON.stringify("") NOT SUPPORTED as valid JSON
+          // t or f and e => JSON.stringify(true) or JSON.stringify(false) NOT SUPPORTED as valid JSON
+          // 0-9 => JSON.stringify(0) integer or float (note .5 is not legitimate JSON) NOT SUPPORTED as valid JSON
+          // if (/^(\[\]|\{\}|(tf)e|\d\d)$/.test(key)) {
+          // Check if the beginning or end are
+          // { and } => JSON.stringify({...}) => pretty much 100% of our JSON will be this.
+          // [ and ] => JSON.stringify([...])
+          if (/^(\[.*\]|\{.*\})\s*$/s.test(key)) {
+            const json = new TextDecoder().decode(new Uint8Array(receivedData))
+            const value = JSON.parse(json)
+            if (
+              isDataAuthentic(
+                value,
+                urlDataWithHash.verification,
+                captureErrors
+              )
+            ) {
+              return {
+                ...dataEntry,
+                value,
+                data: urlDataWithHash.verification?.data,
+                method: urlDataWithHash.verification?.method,
+                url,
+                src,
+              }
+            }
+            captureHashes[captureErrors.pop() || ''] =
+              urlDataWithHash.verification?.data || ''
+            if (
+              isDataAuthentic(
+                receivedData,
+                urlDataWithHash.verification,
+                captureErrors
+              )
+            ) {
+              return {
+                ...dataEntry,
+                value,
+                data: urlDataWithHash.verification?.data,
+                method: urlDataWithHash.verification?.method,
+                url,
+                src,
+              }
+            }
+            captureHashes[captureErrors.pop() || ''] =
+              urlDataWithHash.verification?.data || ''
+            throw new Error(
+              `Data does not validate, ignored ${Object.entries(captureHashes)
+                .map(
+                  ([expected, got]) =>
+                    `calculated(${got}) != expected(${expected})`
+                )
+                .join(', ')}`
+            )
+          }
+        } catch {
+          // ignore
+        }
+      }
+      if (
+        isDataAuthentic(
+          receivedData,
+          urlDataWithHash.verification,
+          captureErrors
+        )
+      ) {
+        return {
+          ...dataEntry,
+          value: receivedData,
+          data: urlDataWithHash.verification?.data,
+          method: urlDataWithHash.verification?.method,
+          url,
+          src,
+        }
+      }
+      captureHashes[captureErrors.pop() || ''] =
+        urlDataWithHash.verification?.data || ''
+      throw new Error(
+        `Data does not validate, ignored ${Object.entries(captureHashes)
+          .map(
+            ([expected, got]) => `calculated(${got}) != expected(${expected})`
+          )
+          .join(', ')}`
+      )
+    } catch (error) {
+      const message = (error as { message: string }).message
+      if (throwException) {
+        throw error
+      }
+      return {
+        ...dataEntry,
+        value: null,
+        error: message,
+        data: urlDataWithHash.verification?.data,
+        method: urlDataWithHash.verification?.method,
+        url,
+        src,
+      }
+    }
+  })
+  return Promise.all(promises)
+}

package/src/decoder/graphqlWS.ts

@@ -0,0 +1,22 @@
+import { type Client, createClient } from 'graphql-ws'
+import type { Chain } from 'viem'
+import { lukso } from 'viem/chains'
+
+const wsClients: Record<string, Client> = {}
+
+/**
+ * Get web socket graphql client for a given chain
+ *
+ * @param chain Chain to use
+ * @returns web socket graphql client
+ */
+export function getWSClient(chain: Chain) {
+  if (wsClients[chain.id]) return wsClients[chain.id]
+  wsClients[chain.id] = createClient({
+    url:
+      chain.id === lukso.id
+        ? 'wss://envio.lukso-mainnet.universal.tech/v1/graphql'
+        : 'wss://envio.lukso-testnet.universal.tech/v1/graphql',
+  })
+  return wsClients[chain.id]
+}

package/src/decoder/interfaces.ts

@@ -0,0 +1,185 @@
+import { abi as KeyManager } from '@lukso/lsp6-contracts/artifacts/LSP6KeyManager.json'
+import { LRUCache } from 'lru-cache'
+import {
+  type Chain,
+  type ChainContract,
+  encodeFunctionData,
+  getContract,
+} from 'viem'
+import { ITEMS } from './constants'
+import type { AddressModifier } from './types'
+import { getPublicClient } from './utils'
+
+const TARGETS = new LRUCache<string, Promise<`0x${string}` | undefined>>({
+  max: 1000,
+  ttl: 1000 * 60 * 60,
+})
+
+/**
+ * Get the profile from the key manager.
+ *
+ * @param chain which chain to use
+ * @param address address of key manager
+ * @returns
+ */
+export async function getKMTarget(
+  chain: Chain,
+  address?: `0x${string}` | null
+): Promise<`0x${string}` | undefined> {
+  if (!address) {
+    return undefined
+  }
+  const info = TARGETS.get(address)
+  if (info) {
+    return info
+  }
+  const client = getPublicClient(chain)
+  const out = client
+    .readContract({
+      address,
+      abi: KeyManager,
+      functionName: 'target',
+    })
+    .catch(() => undefined) as Promise<`0x${string}` | undefined>
+  TARGETS.set(address, out)
+  return out
+}
+
+const INTERFACE_INFO = new LRUCache<string, Promise<string | undefined>>({
+  max: 1000,
+  ttl: 1000 * 60 * 60,
+})
+
+/**
+ * Retrieve interface information, LSP7/8/0 for an address
+ *
+ * @param address
+ * @param blockNumber
+ * @param log
+ * @returns
+ */
+export async function retrieveInterfaces(
+  chain: Chain,
+  modifier: AddressModifier
+): Promise<string | undefined> {
+  const info = INTERFACE_INFO.get(modifier.address)
+  if (info) {
+    return info
+  }
+  const out = _retrieveInterfaces(chain, modifier)
+  INTERFACE_INFO.set(modifier.address, out)
+  return out
+}
+
+const LSP2Fetcher = [
+  {
+    inputs: [
+      {
+        internalType: 'bytes4',
+        name: 'interfaceId',
+        type: 'bytes4',
+      },
+    ],
+    name: 'supportsInterface',
+    outputs: [
+      {
+        internalType: 'bool',
+        name: '',
+        type: 'bool',
+      },
+    ],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    type: 'function',
+    name: 'aggregate3',
+    inputs: [
+      {
+        name: 'calls',
+        type: 'tuple[]',
+        internalType: 'struct LSP2FetcherWithMulticall3.Call3[]',
+        components: [
+          { name: 'target', type: 'address', internalType: 'address' },
+          { name: 'allowFailure', type: 'bool', internalType: 'bool' },
+          { name: 'callData', type: 'bytes', internalType: 'bytes' },
+        ],
+      },
+    ],
+    outputs: [
+      {
+        name: 'returnData',
+        type: 'tuple[]',
+        internalType: 'struct LSP2FetcherWithMulticall3.Result[]',
+        components: [
+          { name: 'success', type: 'bool', internalType: 'bool' },
+          { name: 'returnData', type: 'bytes', internalType: 'bytes' },
+        ],
+      },
+    ],
+    stateMutability: 'payable',
+  },
+]
+
+/**
+ * Lowlevel function to retrieve interface information
+ *
+ * @param address
+ * @returns
+ */
+async function _retrieveInterfaces(
+  chain: Chain,
+  modifier: AddressModifier
+): Promise<string | undefined> {
+  const { multicall3 } = chain.contracts as Record<string, ChainContract>
+  if (!multicall3) {
+    return undefined
+  }
+  const client = getPublicClient(chain)
+  const contract = getContract({
+    client,
+    address: multicall3.address,
+    abi: LSP2Fetcher,
+  })
+  const args = ITEMS.map(({ key }) => {
+    return {
+      target: modifier.address,
+      allowFailure: true,
+      callData: encodeFunctionData({
+        abi: LSP2Fetcher,
+        functionName: 'supportsInterface',
+        args: [key],
+      }),
+    }
+  })
+  return client
+    .readContract({
+      address: multicall3.address,
+      abi: LSP2Fetcher,
+      functionName: 'aggregate3',
+      args: [args],
+    })
+    .catch((error) => {
+      console.error(error)
+      return []
+    })
+    .then((val) => {
+      const response = val as Array<{ success: boolean; returnData: boolean }>
+      for (const [index, value] of response.map(
+        ({ success, returnData }, index: number) =>
+          [index, success && Number(returnData)] as [number, boolean]
+      )) {
+        const item = ITEMS[index]
+        if (!item) {
+          continue
+        }
+        if (value) {
+          return item.standard
+        }
+      }
+      return undefined
+    })
+    .then((type) => {
+      return type
+    })
+}

package/src/decoder/keyValue.ts

@@ -0,0 +1,5 @@
+import { defaultSchema } from './constants'
+import { decodeKeyValuePlugin } from './plugins/schemaDefault'
+
+export const defaultSchemaPlugin = decodeKeyValuePlugin(defaultSchema)
+export default defaultSchemaPlugin

package/src/decoder/kvCache.ts

@@ -0,0 +1,241 @@
+/**
+ * KV (Key-Value store) implementation of DecoderCache interface
+ * Suitable for Cloudflare Workers KV, Deno KV, or similar
+ */
+
+import type { CacheEntry, CacheOptions, DecoderCache } from './cache'
+
+/**
+ * KV store interface that implementations must provide
+ */
+export interface KVStore {
+  get<T = unknown>(key: string): Promise<T | null>
+  put(
+    key: string,
+    value: string,
+    options?: { expirationTtl?: number }
+  ): Promise<void>
+  delete(key: string): Promise<void>
+  list?(options?: {
+    prefix?: string
+  }): Promise<{ keys: Array<{ name: string }> }>
+}
+
+/**
+ * Options for creating a KV cache instance
+ */
+export interface KVCacheOptions {
+  /** KV store instance (e.g., Cloudflare KV namespace) */
+  kv: KVStore
+  /** Prefix for all keys */
+  prefix?: string
+  /** Default TTL in milliseconds */
+  ttl?: number
+  /** Default error TTL in milliseconds */
+  errorTTL?: number
+  /** Default stale-while-revalidate time in milliseconds */
+  staleWhileRevalidate?: number
+}
+
+/**
+ * KV implementation of DecoderCache
+ */
+export class KVDecoderCache implements DecoderCache {
+  private kv: KVStore
+  private prefix: string
+  private promises: Map<string, Promise<unknown>>
+  private defaultTTL: number
+  private defaultErrorTTL: number
+  private defaultStaleWhileRevalidate?: number
+
+  constructor(options: KVCacheOptions) {
+    this.kv = options.kv
+    this.prefix = options.prefix ?? 'decoder:'
+    this.defaultTTL = options.ttl ?? 5 * 60 * 1000 // 5 minutes
+    this.defaultErrorTTL = options.errorTTL ?? 30 * 1000 // 30 seconds
+    this.defaultStaleWhileRevalidate = options.staleWhileRevalidate
+    this.promises = new Map()
+  }
+
+  private getKey(key: string): string {
+    return `${this.prefix}${key}`
+  }
+
+  async get<T>(key: string): Promise<CacheEntry<T> | undefined> {
+    try {
+      const data = await this.kv.get<CacheEntry<T>>(this.getKey(key))
+      if (!data) {
+        return undefined
+      }
+
+      // Check if expired
+      if (data.expires && Date.now() > data.expires) {
+        // Don't delete here as it might be used for stale-while-revalidate
+        return undefined
+      }
+
+      return data
+    } catch (error) {
+      console.error('KV get error:', error)
+      return undefined
+    }
+  }
+
+  async set<T>(key: string, value: T, options?: CacheOptions): Promise<void> {
+    const now = Date.now()
+    const ttl =
+      options?.ttl ?? (options?.errorTTL ? options.errorTTL : this.defaultTTL)
+    const isError = options?.errorTTL !== undefined
+
+    const entry: CacheEntry<T> = {
+      value,
+      expires: now + ttl,
+      isError,
+    }
+
+    const staleWhileRevalidate =
+      options?.staleWhileRevalidate ?? this.defaultStaleWhileRevalidate
+    if (staleWhileRevalidate) {
+      entry.stale = now + ttl + staleWhileRevalidate
+    }
+
+    try {
+      // Calculate actual TTL for KV store (including stale time)
+      const kvTtl = entry.stale ? entry.stale - now : ttl
+
+      await this.kv.put(
+        this.getKey(key),
+        JSON.stringify(entry),
+        { expirationTtl: Math.ceil(kvTtl / 1000) } // KV usually wants seconds
+      )
+    } catch (error) {
+      console.error('KV set error:', error)
+      throw error
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      await this.kv.delete(this.getKey(key))
+    } catch (error) {
+      console.error('KV delete error:', error)
+    }
+  }
+
+  async getMany<T>(keys: string[]): Promise<Map<string, CacheEntry<T>>> {
+    const result = new Map<string, CacheEntry<T>>()
+
+    // Most KV stores don't support batch get, so we do it in parallel
+    const promises = keys.map(async (key) => {
+      const entry = await this.get<T>(key)
+      if (entry) {
+        result.set(key, entry)
+      }
+    })
+
+    await Promise.all(promises)
+    return result
+  }
+
+  async setMany<T>(
+    entries: Array<{ key: string; value: T; options?: CacheOptions }>
+  ): Promise<void> {
+    // Most KV stores don't support batch set, so we do it in parallel
+    const promises = entries.map(({ key, value, options }) =>
+      this.set(key, value, options)
+    )
+
+    await Promise.all(promises)
+  }
+
+  async clear(): Promise<void> {
+    // Clear in-flight promises
+    this.promises.clear()
+
+    // If KV supports listing, delete all with prefix
+    if (this.kv.list) {
+      try {
+        const { keys } = await this.kv.list({ prefix: this.prefix })
+        const deletePromises = keys.map(({ name }) => this.kv.delete(name))
+        await Promise.all(deletePromises)
+      } catch (error) {
+        console.error('KV clear error:', error)
+      }
+    }
+  }
+
+  async getOrSet<T>(
+    key: string,
+    factory: (signal?: AbortSignal) => Promise<T>,
+    options?: CacheOptions & { signal?: AbortSignal }
+  ): Promise<T> {
+    // Check cache first
+    const cached = await this.get<T>(key)
+    const now = Date.now()
+
+    // If we have a valid (non-expired) entry, return it
+    if (cached && (!cached.expires || now < cached.expires)) {
+      return cached.value
+    }
+
+    // If we have a stale entry and stale-while-revalidate is enabled
+    if (
+      cached &&
+      cached.stale &&
+      now < cached.stale &&
+      !this.promises.has(key)
+    ) {
+      // Return stale value and revalidate in background
+      const backgroundPromise = factory(options?.signal)
+        .then(async (fresh) => {
+          await this.set(key, fresh, options)
+          return fresh
+        })
+        .catch(() => {
+          // On error, keep the stale value
+          return cached.value
+        })
+        .finally(() => {
+          this.promises.delete(key)
+        })
+
+      this.promises.set(key, backgroundPromise)
+      return cached.value
+    }
+
+    // Check if we have an in-flight promise
+    const existingPromise = this.promises.get(key) as Promise<T> | undefined
+    if (existingPromise) {
+      return existingPromise
+    }
+
+    // No valid cache entry, fetch new value
+    const promise = factory(options?.signal)
+      .then(async (value) => {
+        await this.set(key, value, options)
+        return value
+      })
+      .catch(async (error) => {
+        // Cache the error with shorter TTL
+        await this.set(key, error as T, {
+          ...options,
+          ttl: options?.errorTTL ?? this.defaultErrorTTL,
+          errorTTL: options?.errorTTL ?? this.defaultErrorTTL,
+        })
+        throw error
+      })
+      .finally(() => {
+        this.promises.delete(key)
+      })
+
+    this.promises.set(key, promise)
+    return promise as Promise<T>
+  }
+}
+
+/**
+ * Create a KV cache instance
+ */
+export function createKVCache(options: KVCacheOptions): DecoderCache {
+  return new KVDecoderCache(options)
+}