@ryanrfox/sdk 0.0.2 → 2.0.3

package/src/_esm/events/decodeEventLogs.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Event log decoding utilities for Radius SDK.
+ * Provides convenient wrappers around viem's decodeEventLog.
+ */
+import { type Abi, type DecodeEventLogReturnType, type Log } from 'viem';
+/**
+ * A decoded event log with the original log data preserved.
+ */
+export interface DecodedEventLog<TAbi extends Abi = Abi> {
+    /** The decoded event name */
+    eventName: string;
+    /** The decoded event arguments */
+    args: DecodeEventLogReturnType<TAbi>['args'];
+    /** The original raw log */
+    log: Log;
+}
+/**
+ * Parameters for decodeEventLogs.
+ */
+export interface DecodeEventLogsParameters<TAbi extends Abi = Abi> {
+    /** The contract ABI containing event definitions */
+    abi: TAbi;
+    /** The logs to decode */
+    logs: Log[];
+    /** If true, skip logs that fail to decode instead of throwing (default: false) */
+    strict?: boolean;
+}
+/**
+ * Result when strict mode is disabled and some logs fail to decode.
+ */
+export interface DecodeEventLogsResult<TAbi extends Abi = Abi> {
+    /** Successfully decoded logs */
+    decoded: DecodedEventLog<TAbi>[];
+    /** Logs that failed to decode (only present when strict: false) */
+    failed?: Array<{
+        log: Log;
+        error: Error;
+    }>;
+}
+/**
+ * Decodes an array of event logs using the provided ABI.
+ *
+ * This is a convenience wrapper around viem's `decodeEventLog` that handles
+ * multiple logs at once and provides options for error handling.
+ *
+ * @param params - The parameters for decoding
+ * @returns Array of decoded event logs (or result object if strict: false)
+ * @throws Error if any log fails to decode and strict mode is enabled (default)
+ *
+ * @example
+ * ```typescript
+ * import { decodeEventLogs } from '@radiustechsystems/sdk/events';
+ *
+ * const erc20Abi = [
+ *   {
+ *     type: 'event',
+ *     name: 'Transfer',
+ *     inputs: [
+ *       { indexed: true, name: 'from', type: 'address' },
+ *       { indexed: true, name: 'to', type: 'address' },
+ *       { indexed: false, name: 'value', type: 'uint256' },
+ *     ],
+ *   },
+ * ] as const;
+ *
+ * // Decode logs from a transaction receipt
+ * const decoded = decodeEventLogs({
+ *   abi: erc20Abi,
+ *   logs: receipt.logs,
+ * });
+ *
+ * for (const event of decoded) {
+ *   if (event.eventName === 'Transfer') {
+ *     console.log(`Transfer: ${event.args.from} -> ${event.args.to}: ${event.args.value}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With strict: false to handle mixed logs from multiple contracts
+ * const result = decodeEventLogs({
+ *   abi: erc20Abi,
+ *   logs: mixedLogs,
+ *   strict: false,
+ * });
+ *
+ * console.log(`Decoded ${result.decoded.length} logs`);
+ * console.log(`Failed to decode ${result.failed?.length ?? 0} logs`);
+ * ```
+ */
+export declare function decodeEventLogs<TAbi extends Abi>(params: DecodeEventLogsParameters<TAbi> & {
+    strict: false;
+}): DecodeEventLogsResult<TAbi>;
+export declare function decodeEventLogs<TAbi extends Abi>(params: DecodeEventLogsParameters<TAbi> & {
+    strict?: true;
+}): DecodedEventLog<TAbi>[];
+export declare function decodeEventLogs<TAbi extends Abi>(params: DecodeEventLogsParameters<TAbi>): DecodedEventLog<TAbi>[] | DecodeEventLogsResult<TAbi>;
+/**
+ * Parameters for filterEventLogs.
+ */
+export interface FilterEventLogsParameters<TAbi extends Abi = Abi, TEventName extends string = string> {
+    /** The contract ABI containing event definitions */
+    abi: TAbi;
+    /** The logs to filter and decode */
+    logs: Log[];
+    /** The event name to filter for */
+    eventName: TEventName;
+}
+/**
+ * Filters and decodes logs for a specific event type.
+ *
+ * This is useful when you only care about a specific event from a receipt
+ * or log array that may contain multiple event types.
+ *
+ * @param params - The parameters for filtering
+ * @returns Array of decoded logs matching the event name
+ *
+ * @example
+ * ```typescript
+ * import { filterEventLogs } from '@radiustechsystems/sdk/events';
+ *
+ * // Get only Transfer events from a receipt
+ * const transfers = filterEventLogs({
+ *   abi: erc20Abi,
+ *   logs: receipt.logs,
+ *   eventName: 'Transfer',
+ * });
+ *
+ * for (const transfer of transfers) {
+ *   console.log(`${transfer.args.from} sent ${transfer.args.value} to ${transfer.args.to}`);
+ * }
+ * ```
+ */
+export declare function filterEventLogs<TAbi extends Abi, TEventName extends string>(params: FilterEventLogsParameters<TAbi, TEventName>): DecodedEventLog<TAbi>[];
+//# sourceMappingURL=decodeEventLogs.d.ts.map

package/src/_esm/events/decodeEventLogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decodeEventLogs.d.ts","sourceRoot":"","sources":["../../events/decodeEventLogs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACN,KAAK,GAAG,EAER,KAAK,wBAAwB,EAE7B,KAAK,GAAG,EACR,MAAM,MAAM,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,IAAI,SAAS,GAAG,GAAG,GAAG;IACtD,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,IAAI,EAAE,wBAAwB,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC;IAC7C,2BAA2B;IAC3B,GAAG,EAAE,GAAG,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,IAAI,SAAS,GAAG,GAAG,GAAG;IAChE,oDAAoD;IACpD,GAAG,EAAE,IAAI,CAAC;IACV,yBAAyB;IACzB,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,GAAG,GAAG,GAAG;IAC5D,gCAAgC;IAChC,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;IACjC,mEAAmE;IACnE,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,GAAG,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,GAAG,EAC/C,MAAM,EAAE,yBAAyB,CAAC,IAAI,CAAC,GAAG;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACzD,qBAAqB,CAAC,IAAI,CAAC,CAAC;AAC/B,wBAAgB,eAAe,CAAC,IAAI,SAAS,GAAG,EAC/C,MAAM,EAAE,yBAAyB,CAAC,IAAI,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,IAAI,CAAA;CAAE,GACzD,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;AAC3B,wBAAgB,eAAe,CAAC,IAAI,SAAS,GAAG,EAC/C,MAAM,EAAE,yBAAyB,CAAC,IAAI,CAAC,GACrC,eAAe,CAAC,IAAI,CAAC,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;AA2CzD;;GAEG;AACH,MAAM,WAAW,yBAAyB,CACzC,IAAI,SAAS,GAAG,GAAG,GAAG,EACtB,UAAU,SAAS,MAAM,GAAG,MAAM;IAElC,oDAAoD;IACpD,GAAG,EAAE,IAAI,CAAC;IACV,oCAAoC;IACpC,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,mCAAmC;IACnC,SAAS,EAAE,UAAU,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,GAAG,EAAE,UAAU,SAAS,MAAM,EAC1E,MAAM,EAAE,yBAAyB,CAAC,IAAI,EAAE,UAAU,CAAC,GACjD,eAAe,CAAC,IAAI,CAAC,EAAE,CAiCzB"}

package/src/_esm/events/decodeEventLogs.js

@@ -0,0 +1,93 @@
+/**
+ * Event log decoding utilities for Radius SDK.
+ * Provides convenient wrappers around viem's decodeEventLog.
+ */
+import { decodeEventLog, } from 'viem';
+export function decodeEventLogs(params) {
+    const { abi, logs, strict = true } = params;
+    const decoded = [];
+    const failed = [];
+    for (const log of logs) {
+        try {
+            const result = decodeEventLog({
+                abi,
+                data: log.data,
+                topics: log.topics,
+            });
+            decoded.push({
+                eventName: result.eventName,
+                args: result.args,
+                log,
+            });
+        }
+        catch (error) {
+            if (strict) {
+                throw error;
+            }
+            failed.push({
+                log,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    if (strict) {
+        return decoded;
+    }
+    return {
+        decoded,
+        failed: failed.length > 0 ? failed : undefined,
+    };
+}
+/**
+ * Filters and decodes logs for a specific event type.
+ *
+ * This is useful when you only care about a specific event from a receipt
+ * or log array that may contain multiple event types.
+ *
+ * @param params - The parameters for filtering
+ * @returns Array of decoded logs matching the event name
+ *
+ * @example
+ * ```typescript
+ * import { filterEventLogs } from '@radiustechsystems/sdk/events';
+ *
+ * // Get only Transfer events from a receipt
+ * const transfers = filterEventLogs({
+ *   abi: erc20Abi,
+ *   logs: receipt.logs,
+ *   eventName: 'Transfer',
+ * });
+ *
+ * for (const transfer of transfers) {
+ *   console.log(`${transfer.args.from} sent ${transfer.args.value} to ${transfer.args.to}`);
+ * }
+ * ```
+ */
+export function filterEventLogs(params) {
+    const { abi, logs, eventName } = params;
+    // Find the event in the ABI to get its signature
+    const eventAbi = abi.find((item) => item.type === 'event' && item.name === eventName);
+    if (!eventAbi) {
+        throw new Error(`Event "${eventName}" not found in ABI`);
+    }
+    const result = [];
+    for (const log of logs) {
+        try {
+            const decoded = decodeEventLog({
+                abi,
+                data: log.data,
+                topics: log.topics,
+            });
+            if (decoded.eventName === eventName) {
+                result.push({
+                    eventName: decoded.eventName,
+                    args: decoded.args,
+                    log,
+                });
+            }
+        }
+        catch { }
+    }
+    return result;
+}
+//# sourceMappingURL=decodeEventLogs.js.map

package/src/_esm/events/decodeEventLogs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decodeEventLogs.js","sourceRoot":"","sources":["../../events/decodeEventLogs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAIN,cAAc,GAEd,MAAM,MAAM,CAAC;AAiGd,MAAM,UAAU,eAAe,CAC9B,MAAuC;IAEvC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IAE5C,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAsC,EAAE,CAAC;IAErD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,cAAc,CAAC;gBAC7B,GAAG;gBACH,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;aAClB,CAAC,CAAC;YAEH,OAAO,CAAC,IAAI,CAAC;gBACZ,SAAS,EAAE,MAAM,CAAC,SAAmB;gBACrC,IAAI,EAAE,MAAM,CAAC,IAA8C;gBAC3D,GAAG;aACH,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,MAAM,EAAE,CAAC;gBACZ,MAAM,KAAK,CAAC;YACb,CAAC;YACD,MAAM,CAAC,IAAI,CAAC;gBACX,GAAG;gBACH,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aAChE,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IAED,IAAI,MAAM,EAAE,CAAC;QACZ,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,OAAO;QACN,OAAO;QACP,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;KAC9C,CAAC;AACH,CAAC;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAmD;IAEnD,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAExC,iDAAiD;IACjD,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CACxB,CAAC,IAAI,EAAoB,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAC5E,CAAC;IAEF,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,UAAU,SAAS,oBAAoB,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,cAAc,CAAC;gBAC9B,GAAG;gBACH,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;aAClB,CAAC,CAAC;YAEH,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC;oBACX,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,IAAI,EAAE,OAAO,CAAC,IAA8C;oBAC5D,GAAG;iBACH,CAAC,CAAC;YACJ,CAAC;QACF,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACX,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/src/_esm/events/getLogs.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Historical log querying utilities for Radius SDK.
+ * Provides pagination helpers for eth_getLogs with Radius-specific block range handling.
+ */
+import type { Address, Log, PublicClient } from 'viem';
+/**
+ * Parameters for paginated log retrieval.
+ */
+export interface GetLogsParams {
+    /** The contract address(es) to query logs from (required on Radius) */
+    address: Address | Address[];
+    /** Starting block number (inclusive) */
+    fromBlock: bigint;
+    /** Ending block number (inclusive) */
+    toBlock: bigint;
+    /** Maximum number of blocks to query per request (default: 1000) */
+    chunkSize?: number;
+    /** Callback invoked after each chunk is fetched (for progress tracking) */
+    onProgress?: (params: {
+        /** Current block being processed */
+        currentBlock: bigint;
+        /** Total blocks to process */
+        totalBlocks: bigint;
+        /** Number of chunks processed so far */
+        chunksProcessed: number;
+        /** Logs fetched so far */
+        logsFetched: number;
+    }) => void;
+}
+/**
+ * Fetches historical logs from Radius with automatic pagination.
+ * Handles Radius's block range restrictions by splitting large queries into smaller chunks.
+ *
+ * @param client - The PublicClient to use
+ * @param params - Log query parameters with pagination
+ * @returns Array of all logs matching the query
+ * @throws Error if any chunk request fails
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, http } from 'viem';
+ * import { getLogs } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: http(),
+ * });
+ *
+ * // Fetch logs for a large block range
+ * const logs = await getLogs(client, {
+ *   address: '0x...', // Contract address (required)
+ *   fromBlock: 1000000n,
+ *   toBlock: 1010000n, // 10,000 blocks
+ *   chunkSize: 1000, // Query 1000 blocks at a time
+ *   onProgress: ({ currentBlock, totalBlocks, logsFetched }) => {
+ *     const percent = (Number(currentBlock) / Number(totalBlocks) * 100).toFixed(1);
+ *     console.log(`Progress: ${percent}% (${logsFetched} logs)`);
+ *   },
+ * });
+ *
+ * console.log(`Found ${logs.length} total logs`);
+ * ```
+ *
+ * @remarks
+ * - Radius requires the address parameter (cannot query all contracts)
+ * - Radius restricts eth_getLogs to narrow block ranges
+ * - This function automatically splits large queries into smaller chunks
+ * - Default chunk size is 1000 blocks (adjust based on your needs)
+ * - If you get "block range is too wide" errors, reduce chunkSize
+ * - Progress callback is optional but useful for long-running queries
+ * - All requests are sequential to avoid rate limiting
+ * - Consider using WebSocket subscriptions for real-time monitoring instead
+ */
+export declare function getLogs(client: PublicClient, params: GetLogsParams): Promise<Log[]>;
+/**
+ * Parameters for fetching logs with automatic chunk size detection.
+ */
+export interface GetLogsAdaptiveParams {
+    /** The contract address(es) to query logs from (required on Radius) */
+    address: Address | Address[];
+    /** Starting block number (inclusive) */
+    fromBlock: bigint;
+    /** Ending block number (inclusive) */
+    toBlock: bigint;
+    /** Initial chunk size to try (default: 1000) */
+    initialChunkSize?: number;
+    /** Minimum chunk size (default: 10) */
+    minChunkSize?: number;
+    /** Callback invoked after each chunk is fetched (for progress tracking) */
+    onProgress?: (params: {
+        currentBlock: bigint;
+        totalBlocks: bigint;
+        chunksProcessed: number;
+        logsFetched: number;
+        currentChunkSize: number;
+    }) => void;
+}
+/**
+ * Fetches historical logs with adaptive chunk sizing.
+ * Automatically reduces chunk size if "block range too wide" errors occur.
+ *
+ * @param client - The PublicClient to use
+ * @param params - Log query parameters with adaptive sizing
+ * @returns Array of all logs matching the query
+ * @throws Error if minimum chunk size is reached or other errors occur
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, http } from 'viem';
+ * import { getLogsAdaptive } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: http(),
+ * });
+ *
+ * // Fetch logs with automatic chunk size adjustment
+ * const logs = await getLogsAdaptive(client, {
+ *   address: '0x...',
+ *   fromBlock: 1000000n,
+ *   toBlock: 1010000n,
+ *   onProgress: ({ currentBlock, totalBlocks, currentChunkSize }) => {
+ *     console.log(`Block ${currentBlock}/${totalBlocks} (chunk: ${currentChunkSize})`);
+ *   },
+ * });
+ * ```
+ *
+ * @remarks
+ * - Starts with a large chunk size and reduces it if errors occur
+ * - Useful when you don't know the optimal chunk size for a network
+ * - Slower than getLogs with a known good chunk size
+ * - Use getLogs directly if you know a reliable chunk size
+ */
+export declare function getLogsAdaptive(client: PublicClient, params: GetLogsAdaptiveParams): Promise<Log[]>;
+//# sourceMappingURL=getLogs.d.ts.map

package/src/_esm/events/getLogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getLogs.d.ts","sourceRoot":"","sources":["../../events/getLogs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,GAAG,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,uEAAuE;IACvE,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAAC;IAC7B,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QACrB,oCAAoC;QACpC,YAAY,EAAE,MAAM,CAAC;QACrB,8BAA8B;QAC9B,WAAW,EAAE,MAAM,CAAC;QACpB,wCAAwC;QACxC,eAAe,EAAE,MAAM,CAAC;QACxB,0BAA0B;QAC1B,WAAW,EAAE,MAAM,CAAC;KACpB,KAAK,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAgEzF;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,uEAAuE;IACvE,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAAC;IAC7B,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;KACzB,KAAK,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,eAAe,CACpC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,qBAAqB,GAC3B,OAAO,CAAC,GAAG,EAAE,CAAC,CA8ChB"}

package/src/_esm/events/getLogs.js

@@ -0,0 +1,171 @@
+/**
+ * Fetches historical logs from Radius with automatic pagination.
+ * Handles Radius's block range restrictions by splitting large queries into smaller chunks.
+ *
+ * @param client - The PublicClient to use
+ * @param params - Log query parameters with pagination
+ * @returns Array of all logs matching the query
+ * @throws Error if any chunk request fails
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, http } from 'viem';
+ * import { getLogs } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: http(),
+ * });
+ *
+ * // Fetch logs for a large block range
+ * const logs = await getLogs(client, {
+ *   address: '0x...', // Contract address (required)
+ *   fromBlock: 1000000n,
+ *   toBlock: 1010000n, // 10,000 blocks
+ *   chunkSize: 1000, // Query 1000 blocks at a time
+ *   onProgress: ({ currentBlock, totalBlocks, logsFetched }) => {
+ *     const percent = (Number(currentBlock) / Number(totalBlocks) * 100).toFixed(1);
+ *     console.log(`Progress: ${percent}% (${logsFetched} logs)`);
+ *   },
+ * });
+ *
+ * console.log(`Found ${logs.length} total logs`);
+ * ```
+ *
+ * @remarks
+ * - Radius requires the address parameter (cannot query all contracts)
+ * - Radius restricts eth_getLogs to narrow block ranges
+ * - This function automatically splits large queries into smaller chunks
+ * - Default chunk size is 1000 blocks (adjust based on your needs)
+ * - If you get "block range is too wide" errors, reduce chunkSize
+ * - Progress callback is optional but useful for long-running queries
+ * - All requests are sequential to avoid rate limiting
+ * - Consider using WebSocket subscriptions for real-time monitoring instead
+ */
+export async function getLogs(client, params) {
+    const { address, fromBlock, toBlock, chunkSize = 1000, onProgress } = params;
+    // Validate parameters
+    if (fromBlock > toBlock) {
+        throw new Error('fromBlock must be less than or equal to toBlock');
+    }
+    if (chunkSize <= 0) {
+        throw new Error('chunkSize must be greater than 0');
+    }
+    const allLogs = [];
+    const totalBlocks = toBlock - fromBlock + 1n;
+    let chunksProcessed = 0;
+    // Process in chunks
+    for (let currentFrom = fromBlock; currentFrom <= toBlock; currentFrom += BigInt(chunkSize)) {
+        const currentTo = currentFrom + BigInt(chunkSize) - 1n > toBlock
+            ? toBlock
+            : currentFrom + BigInt(chunkSize) - 1n;
+        // Build filter parameters
+        const filterParams = {
+            address,
+            fromBlock: currentFrom,
+            toBlock: currentTo,
+        };
+        try {
+            // Fetch logs for this chunk
+            const chunkLogs = await client.getLogs(filterParams);
+            allLogs.push(...chunkLogs);
+            chunksProcessed++;
+            // Report progress
+            if (onProgress) {
+                onProgress({
+                    currentBlock: currentTo,
+                    totalBlocks,
+                    chunksProcessed,
+                    logsFetched: allLogs.length,
+                });
+            }
+        }
+        catch (error) {
+            // Provide helpful error message
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            if (errorMessage.includes('block range is too wide')) {
+                throw new Error(`Block range too wide. Current chunk size: ${chunkSize}. ` +
+                    `Try reducing chunkSize. Range: ${currentFrom}-${currentTo}`);
+            }
+            throw new Error(`Failed to fetch logs for blocks ${currentFrom}-${currentTo}: ${errorMessage}`);
+        }
+    }
+    return allLogs;
+}
+/**
+ * Fetches historical logs with adaptive chunk sizing.
+ * Automatically reduces chunk size if "block range too wide" errors occur.
+ *
+ * @param client - The PublicClient to use
+ * @param params - Log query parameters with adaptive sizing
+ * @returns Array of all logs matching the query
+ * @throws Error if minimum chunk size is reached or other errors occur
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, http } from 'viem';
+ * import { getLogsAdaptive } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: http(),
+ * });
+ *
+ * // Fetch logs with automatic chunk size adjustment
+ * const logs = await getLogsAdaptive(client, {
+ *   address: '0x...',
+ *   fromBlock: 1000000n,
+ *   toBlock: 1010000n,
+ *   onProgress: ({ currentBlock, totalBlocks, currentChunkSize }) => {
+ *     console.log(`Block ${currentBlock}/${totalBlocks} (chunk: ${currentChunkSize})`);
+ *   },
+ * });
+ * ```
+ *
+ * @remarks
+ * - Starts with a large chunk size and reduces it if errors occur
+ * - Useful when you don't know the optimal chunk size for a network
+ * - Slower than getLogs with a known good chunk size
+ * - Use getLogs directly if you know a reliable chunk size
+ */
+export async function getLogsAdaptive(client, params) {
+    let currentChunkSize = params.initialChunkSize ?? 1000;
+    const minChunkSize = params.minChunkSize ?? 10;
+    while (currentChunkSize >= minChunkSize) {
+        try {
+            return await getLogs(client, {
+                address: params.address,
+                fromBlock: params.fromBlock,
+                toBlock: params.toBlock,
+                chunkSize: currentChunkSize,
+                onProgress: params.onProgress
+                    ? (progress) => {
+                        params.onProgress?.({
+                            ...progress,
+                            currentChunkSize,
+                        });
+                    }
+                    : undefined,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : '';
+            if (errorMessage.includes('block range is too wide') ||
+                errorMessage.includes('Try reducing chunkSize')) {
+                // Reduce chunk size and retry
+                currentChunkSize = Math.floor(currentChunkSize / 2);
+                if (currentChunkSize < minChunkSize) {
+                    throw new Error(`Cannot fetch logs: minimum chunk size (${minChunkSize}) reached. Network requires smaller block ranges than supported.`);
+                }
+                // Continue loop with smaller chunk size
+                continue;
+            }
+            // Re-throw non-range-related errors
+            throw error;
+        }
+    }
+    throw new Error('Failed to fetch logs: minimum chunk size reached');
+}
+//# sourceMappingURL=getLogs.js.map

package/src/_esm/events/getLogs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getLogs.js","sourceRoot":"","sources":["../../events/getLogs.ts"],"names":[],"mappings":"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"}

package/src/_esm/events/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Event subscription and log querying utilities for Radius SDK.
+ *
+ * This module provides WebSocket-based event subscriptions and historical log queries
+ * with Radius-specific optimizations and limitations handling.
+ *
+ * @packageDocumentation
+ * @module events
+ */
+export { createWebSocketTransport, type WebSocketTransportConfig, } from '../transport/websocket.js';
+export { type DecodedEventLog, type DecodeEventLogsParameters, type DecodeEventLogsResult, decodeEventLogs, type FilterEventLogsParameters, filterEventLogs, } from './decodeEventLogs.js';
+export { type GetLogsAdaptiveParams, type GetLogsParams, getLogs, getLogsAdaptive, } from './getLogs.js';
+export { type ApprovalEvent, type WatchApprovalForAddressParameters, type WatchApprovalParameters, watchApproval, watchApprovalForAddress, } from './watchApproval.js';
+export { DEFAULT_POLLING_INTERVAL_MS, type WatchBlockNumberParams, type WatchBlocksParams, type WatchPendingTransactionsParams, watchBlockNumber, watchBlocks, watchPendingTransactions, } from './watchBlock.js';
+export { type WatchRawLogsParameters, watchLogs, watchRawLogs, } from './watchLogs.js';
+export { type TransferEvent, type WatchTransferForAddressParameters, type WatchTransferParameters, watchTransfer, watchTransferForAddress, } from './watchTransfer.js';
+//# sourceMappingURL=index.d.ts.map

package/src/_esm/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACN,wBAAwB,EACxB,KAAK,wBAAwB,GAC7B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,eAAe,EACf,KAAK,yBAAyB,EAC9B,eAAe,GACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,OAAO,EACP,eAAe,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,iCAAiC,EACtC,KAAK,uBAAuB,EAC5B,aAAa,EACb,uBAAuB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,2BAA2B,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,8BAA8B,EACnC,gBAAgB,EAChB,WAAW,EACX,wBAAwB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACN,KAAK,sBAAsB,EAC3B,SAAS,EACT,YAAY,GACZ,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,iCAAiC,EACtC,KAAK,uBAAuB,EAC5B,aAAa,EACb,uBAAuB,GACvB,MAAM,oBAAoB,CAAC"}

package/src/_esm/events/index.js

@@ -0,0 +1,24 @@
+/**
+ * Event subscription and log querying utilities for Radius SDK.
+ *
+ * This module provides WebSocket-based event subscriptions and historical log queries
+ * with Radius-specific optimizations and limitations handling.
+ *
+ * @packageDocumentation
+ * @module events
+ */
+// WebSocket transport
+export { createWebSocketTransport, } from '../transport/websocket.js';
+// Event decoding utilities
+export { decodeEventLogs, filterEventLogs, } from './decodeEventLogs.js';
+// Historical log queries
+export { getLogs, getLogsAdaptive, } from './getLogs.js';
+// ERC-20 Approval events
+export { watchApproval, watchApprovalForAddress, } from './watchApproval.js';
+// Block watching
+export { DEFAULT_POLLING_INTERVAL_MS, watchBlockNumber, watchBlocks, watchPendingTransactions, } from './watchBlock.js';
+// Generic log watching
+export { watchLogs, watchRawLogs, } from './watchLogs.js';
+// ERC-20 Transfer events
+export { watchTransfer, watchTransferForAddress, } from './watchTransfer.js';
+//# sourceMappingURL=index.js.map

package/src/_esm/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sBAAsB;AACtB,OAAO,EACN,wBAAwB,GAExB,MAAM,2BAA2B,CAAC;AACnC,2BAA2B;AAC3B,OAAO,EAIN,eAAe,EAEf,eAAe,GACf,MAAM,sBAAsB,CAAC;AAC9B,yBAAyB;AACzB,OAAO,EAGN,OAAO,EACP,eAAe,GACf,MAAM,cAAc,CAAC;AACtB,yBAAyB;AACzB,OAAO,EAIN,aAAa,EACb,uBAAuB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,iBAAiB;AACjB,OAAO,EACN,2BAA2B,EAI3B,gBAAgB,EAChB,WAAW,EACX,wBAAwB,GACxB,MAAM,iBAAiB,CAAC;AACzB,uBAAuB;AACvB,OAAO,EAEN,SAAS,EACT,YAAY,GACZ,MAAM,gBAAgB,CAAC;AACxB,yBAAyB;AACzB,OAAO,EAIN,aAAa,EACb,uBAAuB,GACvB,MAAM,oBAAoB,CAAC"}