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

package/dist/index-BzXh7poJ.d.ts

@@ -0,0 +1,524 @@
+import { Signal } from '@preact/signals-core';
+import { Transaction, Hex, AbiParameter, Log, Address, Chain, Abi, DecodeFunctionDataReturnType } from 'viem';
+import { ERC725JSONSchema } from '@erc725/erc725.js';
+
+/**
+ * Cache interface for decoder with support for different backends
+ * (LRU, Cloudflare KV, Redis, etc.)
+ */
+
+/**
+ * Cache entry with metadata
+ */
+interface CacheEntry<T> {
+    /** The cached value */
+    value: T;
+    /** Timestamp when the entry expires (ms since epoch) */
+    expires?: number;
+    /** Timestamp when the entry becomes stale (for stale-while-revalidate) */
+    stale?: number;
+    /** Whether this entry resulted from an error */
+    isError?: boolean;
+}
+/**
+ * Options for cache operations
+ */
+interface CacheOptions {
+    /** Time to live in milliseconds */
+    ttl?: number;
+    /** TTL for error responses (typically shorter) */
+    errorTTL?: number;
+    /** Time in ms after which the value is stale but still usable */
+    staleWhileRevalidate?: number;
+}
+/**
+ * Generic cache interface that can be implemented by different backends
+ */
+interface DecoderCache {
+    /**
+     * Get a value from the cache
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | undefined>;
+    /**
+     * Set a value in the cache
+     */
+    set<T>(key: string, value: T, options?: CacheOptions): Promise<void>;
+    /**
+     * Delete a value from the cache
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Get multiple values at once (for batch operations)
+     */
+    getMany?<T>(keys: string[]): Promise<Map<string, CacheEntry<T>>>;
+    /**
+     * Set multiple values at once (for batch operations)
+     */
+    setMany?<T>(entries: Array<{
+        key: string;
+        value: T;
+        options?: CacheOptions;
+    }>): Promise<void>;
+    /**
+     * Clear all entries (optional)
+     */
+    clear?(): Promise<void>;
+    /**
+     * Get or set with automatic promise deduplication
+     * This is the main method for async operations
+     */
+    getOrSet<T>(key: string, factory: (signal?: AbortSignal) => Promise<T>, options?: CacheOptions & {
+        signal?: AbortSignal;
+    }): Promise<T>;
+}
+
+/**
+ * Array length item: Represents the length of an ERC725 Array schema item.
+ */
+type ArrayLengthInfo = ERC725JSONSchema & {
+    type: 'ArrayLength';
+    value: number;
+    pretty?: string;
+};
+/**
+ * Array item: Represents the value of an ERC725 Array schema item.
+ */
+type ArrayItemInfo = ERC725JSONSchema & {
+    type: 'ArrayItem';
+    dynamic: number;
+    value: unknown;
+    pretty?: string;
+};
+/**
+ * Value item: Represents the value of an ERC725 schema item.
+ */
+type ValueInfo = ERC725JSONSchema & {
+    type: 'Value';
+    dynamic?: string | string[];
+    value: unknown;
+    data?: string;
+    method?: string;
+    url?: string;
+    src?: string;
+    pretty?: string;
+};
+/**
+ * Undecoded item: Represents an undecoded ERC725 schema item (unknown, raw data).
+ */
+type UndecodedInfo = {
+    type: 'Undecoded';
+    key: string;
+    name: undefined;
+    value: string;
+};
+/**
+ * Error item: Error happened during decoding or retrieval (404 or exception due to invalid data)
+ */
+type ErrorInfo = ERC725JSONSchema & {
+    type: 'Error';
+    key: string;
+    value: string | Error;
+    data?: string;
+    method?: string;
+    url?: string;
+    src?: string;
+    pretty?: string;
+};
+/**
+ * Info item: Results of the decoded schema.
+ */
+type Info = ArrayLengthInfo | ArrayItemInfo | ValueInfo | UndecodedInfo | ErrorInfo;
+/**
+ * Add address as a property to the record so that obj.address instead of obj['address'] can be used
+ */
+type EnhancedInfo = {
+    address: `0x${string}`;
+    standard?: string;
+    tokenId?: `0x${string}`;
+    name?: string;
+    __gqltype?: 'Profile' | 'Asset' | 'Token';
+    [key: string]: unknown;
+};
+type NamedArgs = Record<string | number, AbiParameter & {
+    value?: unknown;
+}>;
+type ArrayArgs = Array<AbiParameter & {
+    value?: unknown;
+}>;
+type ResultShared = {
+    resultType?: string;
+    standard?: string;
+    type?: string;
+    sig?: `0x${string}` | null;
+    graphqlData?: Record<Hex, EnhancedInfo>;
+    /**
+     * Decoding phase - added by server-side decoder
+     */
+    phase?: 'immediate' | 'enhanced';
+    /**
+     * Whether this result was served from cache - added by server-side decoder
+     */
+    cached?: boolean;
+    /**
+     * Time taken to decode (milliseconds)
+     */
+    timeTaken?: number;
+    moduleHint?: string;
+    logs?: DecodeEventResult[];
+    isDecoded?: boolean;
+    error?: {
+        code: string;
+        message: string;
+        details: Error;
+    };
+    processingError?: {
+        message: string;
+        code: unknown;
+    };
+    blockTimestamp?: number;
+    /**
+     * List of addresses found in the transaction (to, from, args, namedArgs, wrappers)
+     */
+    addresses?: DataKey[];
+    transactionHash?: Hex;
+    /**
+     * Custom data for view matching and extensibility.
+     * Populated by enhancers to provide additional context for view selection.
+     *
+     * Common use cases:
+     * - tokenType: 0 (token) | 1 (NFT) | 2 (collection)
+     * - isToken, isNFT, isCollection: boolean flags
+     * - operationType: 'mint' | 'burn' | 'transfer'
+     * - hasMetadata: boolean
+     * - customFlags: any enhancer-specific data
+     *
+     * This field is NOT typed to allow for plugin extensibility.
+     */
+    custom?: Record<string, unknown>;
+    enhancementAttempted?: boolean;
+};
+type ResultError = {
+    resultType: 'error';
+    functionName?: string;
+    errorType: ErrorType;
+    sig: `0x${string}`;
+    input?: `0x${string}` | null;
+    args?: ArrayArgs;
+    summary?: string;
+    devdocs?: string;
+};
+type ResultAggregate = {
+    resultType: 'aggregate';
+    aggregate: {
+        count: number;
+        blockRange: {
+            from: number;
+            to: number;
+        };
+        [key: string]: unknown;
+    };
+    functionName?: string;
+    args?: ArrayArgs;
+    wrappers?: Array<ResultType>;
+    devdocs?: string;
+};
+type ResultExecute = {
+    resultType: 'execute';
+    functionName?: string;
+    args?: ArrayArgs;
+    wrappers?: Array<ResultType>;
+    devdocs?: string;
+};
+type ResultCreate = {
+    resultType: 'create';
+    wrappers?: Array<ResultType>;
+    args?: ArrayArgs;
+};
+type ResultWrapper = {
+    resultType: 'wrapper';
+    functionName?: string;
+    args?: ArrayArgs;
+    devdocs?: string;
+};
+type ResultFollowProfile = {
+    resultType: 'followProfile';
+    functionName?: string;
+    address: Address;
+};
+type ResultExecuteBatch = {
+    resultType: 'executeBatch';
+    functionName: string;
+    args?: ArrayArgs;
+    children: Array<ResultType & ResultShared>;
+    wrappers?: Array<ResultType & ResultShared>;
+    devdocs?: string;
+};
+type ResultSetDataBatch = {
+    resultType: 'setDataBatch';
+    functionName?: string;
+    standard?: string;
+    args?: ArrayArgs;
+    children: Array<ResultSetData & ResultShared>;
+    wrappers?: Array<ResultType & ResultShared>;
+    devdocs?: string;
+};
+type ResultGrafitti = {
+    resultType: 'grafitti';
+    standard?: string;
+    graffiti: string;
+    devdocs?: string;
+    functionName?: string;
+};
+type ResultSetData = {
+    resultType: 'setData';
+    functionName?: string;
+    tokenId?: `0x${string}`;
+    args?: ArrayArgs;
+    wrappers?: Array<ResultType & ResultShared>;
+    info?: Info;
+    devdocs?: string;
+};
+type ResultRaw = {
+    resultType: 'raw';
+    standard?: string;
+    input?: `0x${string}`;
+};
+/**
+ * DecodeFunctionDataReturn: Represents the return type of a decodeTransaction function.
+ * There are extra properties added to the return type to make it more useful.
+ * Internally some of the properties are used to decode the data so in some places
+ * we use "any" to avoid type errors during the decoding process.
+ * The main offenders here are isDecoded: boolean and __decoder: string and so on.
+ * Rather than mixing those into the type, then it would make the types unnecessarily complex.
+ */
+type ResultComponent = ResultExecute | ResultCreate | ResultWrapper | ResultSetDataBatch | ResultExecuteBatch | ResultSetData | ResultGrafitti | ResultRaw | ResultError | ResultAggregate | ResultFollowProfile;
+/**
+ * The main result type returned by decodeTransaction.
+ */
+type ResultType = Partial<Omit<Transaction, 'type' | 'logs' | 'blobVersionedHashes'>> & ResultShared & ResultComponent & {
+    __decoder?: string;
+    __decoderVerifiedContract?: boolean;
+    type?: string;
+    logs?: DecodeEventResult[];
+    blobVersionedHashes?: readonly Hex[];
+};
+/**
+ * CustomDecodeFunctionDataReturn: Represents the return type of a customDecodeFunctionData function.
+ * Basically the normal decodeFunctionData doesn't return the abi entry, so that
+ * we can't decode argument names and types.
+ */
+type CustomDecodeFunctionDataReturn<abi extends Abi | readonly unknown[]> = DecodeFunctionDataReturnType<abi> & {
+    args?: ArrayArgs;
+};
+declare enum ErrorType {
+    EMPTY_REVERT = "EMPTY_REVERT",
+    INVALID = "INVALID",
+    PANIC = "PANIC",
+    ERROR = "ERROR",
+    CUSTOM_ERROR = "CUSTOM_ERROR",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * The output of the enhancer
+ */
+type DecoderResult = ResultType & ResultShared & {
+    /** Which aggregations apply (just keys, no plugin prefix) */
+    aggregationKeys?: string[];
+};
+/**
+ * Aggregation configuration for map/reduce operations
+ */
+interface Aggregation<T = any> {
+    /** Unique key for this aggregation within the plugin */
+    key: string;
+    /** Extract/transform data from a single transaction */
+    map: (tx: DecoderResult) => T | undefined;
+    /** Combine mapped data with existing state */
+    reduce: (state: T | undefined, mapped: T) => T;
+    /** Transform state for final output */
+    finalize: (state: T) => Omit<ResultAggregate, 'resultType'>;
+}
+/**
+ * Bitmap enum for controlling which async operations are enabled
+ */
+declare enum AsyncOperations {
+    /** No async operations (default) */
+    DISABLED = 0,// 0b000
+    /** Enable async plugins (ABI fetching, function signatures) */
+    ENABLE_PLUGINS = 1,// 0b001
+    /** Enable address resolution (profile/address metadata) */
+    ENABLE_ADDRESS_RESOLVE = 2,// 0b010
+    /** Enable external data fetching (IPFS, external JSON) */
+    ENABLE_EXTERNAL_DATA = 4
+}
+/**
+ * Options to modify operations which now also have to be sent down to the enhancer and plugin
+ */
+type DecoderOptions = {
+    plugins: ReadonlyArray<DecoderPlugin>;
+    schemaPlugins: ReadonlyArray<SchemaPlugin>;
+    preferError?: boolean;
+    wrappers: Array<ResultType & ResultShared>;
+    chain: Chain;
+    /**
+     * Controls which async operations are enabled.
+     * Can be a boolean for backward compatibility (true = all async, false = none)
+     * or AsyncOperations enum for fine-grained control
+     */
+    async?: boolean | AsyncOperations;
+    /** Cache implementation for async operations */
+    cache?: DecoderCache;
+    /** Timeout for async operations in milliseconds */
+    timeout?: number;
+    /** AbortSignal for cancelling async operations */
+    signal?: AbortSignal;
+};
+/**
+ * Generic plugin into decoder (most of the time this will be wrapped with the standard plugin to provide
+ * additional or existing abis)
+ */
+type DecoderPlugin = {
+    enhance: (transaction: DecoderResult, options: DecoderOptions) => Promise<DecoderResult | undefined>;
+    decodeEvent: (log: DecodeEventResult, options: DecoderOptions) => Promise<DecodeEventResult>;
+    getAggregationKey?: EnhancerAggregationKeyCallback;
+    summarize?: EnhancerSummarizeCallback;
+    name?: string;
+    required?: boolean;
+    priority?: number;
+    usesAsync?: boolean;
+    /** Aggregations supported by this plugin */
+    aggregations?: Aggregation[];
+};
+type PluginOptions = {
+    abiName: string;
+    decoderName?: string;
+    moduleHint?: string;
+    name?: string;
+    required?: boolean;
+    priority?: number;
+    usesAsync?: boolean;
+};
+/**
+ * Type for the actual enhancement logic
+ */
+type EnhancerCallback = (result: DecoderResult, pluginOptions: PluginOptions, options: DecoderOptions) => Promise<DecoderResult | undefined>;
+type EnhancerAggregationKeyCallback = (result: DecoderResult, pluginOptions: PluginOptions, options: DecoderOptions) => Promise<string | undefined>;
+type EnhancerSummarizeCallback = (aggregateKey: string, result: DecoderResult[], pluginOptions: PluginOptions, options: DecoderOptions) => Promise<DecoderResult | undefined>;
+/**
+ * Plugins to execute decodeData with custom schema tables.
+ * The passed in data will contain the abi name, functionName and so on.
+ */
+type SchemaPlugin = ((key: Hex, value: Hex) => Promise<Info | undefined>) & {
+    name?: string;
+    required?: boolean;
+    priority?: number;
+};
+/**
+ * Plugin callback function to decode events.
+ */
+type DecodeEventCallback = (log: DecodeEventResult, options: DecoderOptions) => Promise<DecodeEventResult>;
+type DecodeEventResult = ({
+    eventName: string;
+    args: ArrayArgs;
+} & Log) | undefined;
+
+/**
+ * Core types for @lukso/decoder
+ */
+
+type DataKey = Hex;
+type DeepReadonly<T> = T extends (infer R)[] ? DeepReadonlyArray<R> : T extends (...args: unknown[]) => unknown ? T : T extends object ? DeepReadonlyObject<T> : T;
+interface DeepReadonlyArray<T> extends ReadonlyArray<DeepReadonly<T>> {
+}
+type DeepReadonlyObject<T> = {
+    readonly [P in keyof T]: DeepReadonly<T[P]>;
+};
+/**
+ * State wrapper for address/asset information
+ */
+interface AddressState {
+    loading: boolean;
+    data?: DeepReadonly<EnhancedInfo>;
+    error?: string;
+    lastUpdated?: number;
+}
+/**
+ * Transaction decoding status
+ * - raw: No decoding attempted yet
+ * - decoded: Sync decoding complete (phase 1)
+ * - enhanced: ABI retrieval complete (phase 2)
+ * - complete: Address resolution complete (phase 3)
+ * - failed: Decoding failed
+ */
+type DecodingStatus = 'raw' | 'decoded' | 'enhanced' | 'complete' | 'failed';
+/**
+ * State wrapper for decoded transactions
+ */
+interface TransactionState {
+    loading: boolean;
+    data: DeepReadonly<DecoderResult>;
+    addresses: ReadonlyArray<DataKey>;
+    error?: string;
+    lastUpdated?: number;
+    decodingStatus?: DecodingStatus;
+    addressesResolved?: boolean;
+    resolvedData?: DeepReadonly<DecoderResult>;
+}
+/**
+ * Options for creating a data model instance
+ */
+interface DataModelOptions {
+    onMissingKeys?: (keys: DataKey[]) => void;
+    onNewTransaction?: (transaction: unknown) => void;
+}
+/**
+ * Read-only interface for consumers (views, components)
+ * This is the interface available on window.transactionDecoder
+ */
+interface IDataModelConsumer {
+    getTransaction(jsonTransaction: unknown): Signal<TransactionState> | undefined;
+    getTransactionByKey(hash: Hex, decoderIndex?: number): Signal<TransactionState> | undefined;
+    getTransactionsByIndex(index: number): Map<number | null, Signal<TransactionState>> | undefined;
+    getTransactionHashByIndex(index: number): Hex | undefined;
+    getTransactionCount(): number;
+    getDecodedCount(hash: Hex): number;
+    getDecodedTransactions(hash: Hex): Array<Signal<TransactionState>>;
+    getTransactionsInOrder(): Array<{
+        hash: Hex;
+        transactions: Array<Signal<TransactionState>>;
+    }>;
+    getAddress(address: DataKey): Signal<AddressState>;
+    getSignal(key: DataKey): Signal<AddressState>;
+    subscribe(key: DataKey, callback: (state: AddressState) => void): () => void;
+    getState(key: DataKey): AddressState;
+    hasData(key: DataKey): boolean;
+    getData(key: DataKey): DeepReadonly<EnhancedInfo> | undefined;
+    isLoading(key: DataKey): boolean;
+    getError(key: DataKey): string | undefined;
+    getAllKeys(): ReadonlyArray<DataKey>;
+    getAllData(): Readonly<Record<string, AddressState>>;
+    getAllTransactions(): Readonly<Record<string, TransactionState>>;
+}
+/**
+ * Full interface for data management (used by data providers)
+ * Includes all consumer methods plus data modification methods
+ */
+interface IDataModel extends IDataModelConsumer {
+    addTransactions<T extends unknown | unknown[]>(jsonTransactions: T): T extends unknown[] ? Array<Signal<TransactionState>> : Signal<TransactionState>;
+    updateTransactionData(hash: Hex, newData: DecoderResult, decoderIndex?: number): void;
+    injectData(dataList: EnhancedInfo[]): void;
+    updateData(data: EnhancedInfo): void;
+    setLoading(keys: DataKey[]): void;
+    setError(key: DataKey, error: string): void;
+    getMissingKeys(): DataKey[];
+    getLoadingKeys(): DataKey[];
+    clear(): void;
+    remove(keys: DataKey[]): void;
+}
+declare global {
+    interface Window {
+        TransactionDecoder?: IDataModelConsumer;
+    }
+}
+
+export type { ArrayArgs as A, CustomDecodeFunctionDataReturn as C, DataModelOptions as D, EnhancedInfo as E, IDataModel as I, NamedArgs as N, PluginOptions as P, ResultShared as R, SchemaPlugin as S, TransactionState as T, DecodeEventResult as a, DecoderResult as b, DataKey as c, AddressState as d, Info as e, ResultType as f, IDataModelConsumer as g, DecoderOptions as h, EnhancerCallback as i, DecodeEventCallback as j, EnhancerAggregationKeyCallback as k, EnhancerSummarizeCallback as l, Aggregation as m, DecoderPlugin as n, ResultSetData as o, ResultAggregate as p, ResultCreate as q, ResultError as r, ResultExecute as s, ResultExecuteBatch as t, ResultFollowProfile as u, ResultGrafitti as v, ResultRaw as w, ResultSetDataBatch as x, ResultWrapper as y };