@ryanrfox/sdk 0.0.2 → 2.0.3

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

@@ -0,0 +1,184 @@
+/**
+ * ERC-20 Approval event watching utilities for Radius SDK.
+ * Provides convenient wrappers for watching Approval events in real-time.
+ */
+import type { Address, Log, PublicClient, WatchContractEventReturnType } from 'viem';
+/**
+ * Decoded Approval event data.
+ */
+export interface ApprovalEvent {
+    /** The address that owns the tokens */
+    owner: Address;
+    /** The address that is approved to spend the tokens */
+    spender: Address;
+    /** The amount of tokens approved (in smallest unit) */
+    value: bigint;
+    /** The raw log data */
+    log: Log;
+}
+/**
+ * Parameters for watching Approval events.
+ */
+export interface WatchApprovalParameters {
+    /** The ERC-20 token contract address to watch */
+    address: Address;
+    /** Optional: Filter by owner address */
+    owner?: Address;
+    /** Optional: Filter by spender address */
+    spender?: Address;
+    /** Callback function invoked when Approval events are received */
+    onApproval: (events: ApprovalEvent[]) => void;
+    /** Callback function invoked when an error occurs */
+    onError?: (error: Error) => void;
+    /** Whether to emit logs from the latest block on subscription start */
+    sync?: boolean;
+    /** Polling interval in milliseconds (for HTTP transport fallback) */
+    pollingInterval?: number;
+}
+/**
+ * Watches for ERC-20 Approval events in real-time.
+ * Automatically decodes Approval events and provides type-safe callbacks.
+ *
+ * @param client - The PublicClient to use (WebSocket transport recommended)
+ * @param params - Approval event watching parameters
+ * @returns An unwatch function to stop the subscription
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchApproval } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch all approvals for a token
+ * const unwatch = watchApproval(client, {
+ *   address: '0x...', // Token address
+ *   onApproval: (events) => {
+ *     events.forEach(event => {
+ *       console.log(`Approval: ${event.owner} approved ${event.spender} for ${event.value}`);
+ *     });
+ *   },
+ * });
+ *
+ * // Watch approvals from a specific owner
+ * const unwatchOwner = watchApproval(client, {
+ *   address: '0x...', // Token address
+ *   owner: '0x...', // Owner address
+ *   onApproval: (events) => {
+ *     console.log(`Owner granted ${events.length} approvals`);
+ *   },
+ * });
+ *
+ * // Watch approvals for a specific spender
+ * const unwatchSpender = watchApproval(client, {
+ *   address: '0x...', // Token address
+ *   spender: '0x...', // Spender address
+ *   onApproval: (events) => {
+ *     console.log(`Spender received ${events.length} approvals`);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - Requires WebSocket transport for real-time subscriptions
+ * - Automatically decodes Approval events using ERC-20 ABI
+ * - Filters by owner/spender addresses if provided
+ * - Event signature: Approval(address indexed owner, address indexed spender, uint256 value)
+ * - Subscriptions consume gas from your RPC key on Radius (10 GAS/sec)
+ * - An approval value of 0 revokes the approval
+ */
+export declare function watchApproval(client: PublicClient, params: WatchApprovalParameters): WatchContractEventReturnType;
+/**
+ * Parameters for watching Approval events for a specific address (as owner or spender).
+ */
+export interface WatchApprovalForAddressParameters {
+    /** The ERC-20 token contract address to watch */
+    tokenAddress: Address;
+    /** The address to watch (as owner or spender) */
+    watchAddress: Address;
+    /** Whether to watch as owner only (default: false, watches both owner and spender) */
+    ownerOnly?: boolean;
+    /** Whether to watch as spender only (default: false, watches both owner and spender) */
+    spenderOnly?: boolean;
+    /** Callback function invoked when Approval events are received */
+    onApproval: (events: ApprovalEvent[]) => void;
+    /** Callback function invoked when an error occurs */
+    onError?: (error: Error) => void;
+    /** Whether to emit logs from the latest block on subscription start */
+    sync?: boolean;
+    /** Polling interval in milliseconds (for HTTP transport fallback) */
+    pollingInterval?: number;
+}
+/**
+ * Watches for Approval events involving a specific address (as owner or spender).
+ * Convenience wrapper around watchApproval for monitoring a single address.
+ *
+ * @param client - The PublicClient to use (WebSocket transport recommended)
+ * @param params - Approval watching parameters for specific address
+ * @returns An unwatch function to stop the subscription
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchApprovalForAddress } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch all approvals involving an address (as owner or spender)
+ * const unwatch = watchApprovalForAddress(client, {
+ *   tokenAddress: '0x...', // Token address
+ *   watchAddress: '0x...', // Address to monitor
+ *   onApproval: (events) => {
+ *     events.forEach(event => {
+ *       if (event.owner === watchAddress) {
+ *         console.log(`Approved ${event.spender} for ${event.value}`);
+ *       } else {
+ *         console.log(`Received approval from ${event.owner} for ${event.value}`);
+ *       }
+ *     });
+ *   },
+ * });
+ *
+ * // Watch only approvals granted by an address (as owner)
+ * const unwatchAsOwner = watchApprovalForAddress(client, {
+ *   tokenAddress: '0x...',
+ *   watchAddress: '0x...',
+ *   ownerOnly: true,
+ *   onApproval: (events) => {
+ *     console.log(`Granted ${events.length} approvals`);
+ *   },
+ * });
+ *
+ * // Watch only approvals received by an address (as spender)
+ * const unwatchAsSpender = watchApprovalForAddress(client, {
+ *   tokenAddress: '0x...',
+ *   watchAddress: '0x...',
+ *   spenderOnly: true,
+ *   onApproval: (events) => {
+ *     console.log(`Received ${events.length} approvals`);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - If neither ownerOnly nor spenderOnly is set, watches both roles
+ * - Cannot set both ownerOnly and spenderOnly to true
+ * - More efficient than watching all approvals and filtering client-side
+ * - Server-side filtering reduces network traffic and processing
+ */
+export declare function watchApprovalForAddress(client: PublicClient, params: WatchApprovalForAddressParameters): WatchContractEventReturnType;
+//# sourceMappingURL=watchApproval.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watchApproval.d.ts","sourceRoot":"","sources":["../../events/watchApproval.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,MAAM,CAAC;AAGrF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,GAAG,EAAE,GAAG,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,UAAU,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IAC9C,qDAAqD;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,uBAAuB,GAC7B,4BAA4B,CA+C9B;AAED;;GAEG;AACH,MAAM,WAAW,iCAAiC;IACjD,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC;IACtB,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC;IACtB,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wFAAwF;IACxF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kEAAkE;IAClE,UAAU,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IAC9C,qDAAqD;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,iCAAiC,GACvC,4BAA4B,CAyF9B"}

package/src/_esm/events/watchApproval.js

@@ -0,0 +1,254 @@
+import { decodeEventLog, erc20Abi } from 'viem';
+/**
+ * Watches for ERC-20 Approval events in real-time.
+ * Automatically decodes Approval events and provides type-safe callbacks.
+ *
+ * @param client - The PublicClient to use (WebSocket transport recommended)
+ * @param params - Approval event watching parameters
+ * @returns An unwatch function to stop the subscription
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchApproval } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch all approvals for a token
+ * const unwatch = watchApproval(client, {
+ *   address: '0x...', // Token address
+ *   onApproval: (events) => {
+ *     events.forEach(event => {
+ *       console.log(`Approval: ${event.owner} approved ${event.spender} for ${event.value}`);
+ *     });
+ *   },
+ * });
+ *
+ * // Watch approvals from a specific owner
+ * const unwatchOwner = watchApproval(client, {
+ *   address: '0x...', // Token address
+ *   owner: '0x...', // Owner address
+ *   onApproval: (events) => {
+ *     console.log(`Owner granted ${events.length} approvals`);
+ *   },
+ * });
+ *
+ * // Watch approvals for a specific spender
+ * const unwatchSpender = watchApproval(client, {
+ *   address: '0x...', // Token address
+ *   spender: '0x...', // Spender address
+ *   onApproval: (events) => {
+ *     console.log(`Spender received ${events.length} approvals`);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - Requires WebSocket transport for real-time subscriptions
+ * - Automatically decodes Approval events using ERC-20 ABI
+ * - Filters by owner/spender addresses if provided
+ * - Event signature: Approval(address indexed owner, address indexed spender, uint256 value)
+ * - Subscriptions consume gas from your RPC key on Radius (10 GAS/sec)
+ * - An approval value of 0 revokes the approval
+ */
+export function watchApproval(client, params) {
+    // Build event filter args based on owner/spender parameters
+    const args = {};
+    if (params.owner)
+        args.owner = params.owner;
+    if (params.spender)
+        args.spender = params.spender;
+    return client.watchContractEvent({
+        address: params.address,
+        abi: erc20Abi,
+        eventName: 'Approval',
+        args: Object.keys(args).length > 0 ? args : undefined,
+        onLogs: (logs) => {
+            // Decode and transform logs to ApprovalEvent format
+            const events = logs
+                .map((log) => {
+                try {
+                    const decoded = decodeEventLog({
+                        abi: erc20Abi,
+                        data: log.data,
+                        topics: log.topics,
+                    });
+                    return {
+                        owner: decoded.args.owner,
+                        spender: decoded.args.spender,
+                        value: decoded.args.value,
+                        log: log,
+                    };
+                }
+                catch (error) {
+                    // Skip logs that can't be decoded
+                    if (params.onError) {
+                        params.onError(error instanceof Error ? error : new Error('Failed to decode Approval event'));
+                    }
+                    return null;
+                }
+            })
+                .filter((event) => event !== null);
+            if (events.length > 0) {
+                params.onApproval(events);
+            }
+        },
+        onError: params.onError,
+        pollingInterval: params.pollingInterval,
+    });
+}
+/**
+ * Watches for Approval events involving a specific address (as owner or spender).
+ * Convenience wrapper around watchApproval for monitoring a single address.
+ *
+ * @param client - The PublicClient to use (WebSocket transport recommended)
+ * @param params - Approval watching parameters for specific address
+ * @returns An unwatch function to stop the subscription
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchApprovalForAddress } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch all approvals involving an address (as owner or spender)
+ * const unwatch = watchApprovalForAddress(client, {
+ *   tokenAddress: '0x...', // Token address
+ *   watchAddress: '0x...', // Address to monitor
+ *   onApproval: (events) => {
+ *     events.forEach(event => {
+ *       if (event.owner === watchAddress) {
+ *         console.log(`Approved ${event.spender} for ${event.value}`);
+ *       } else {
+ *         console.log(`Received approval from ${event.owner} for ${event.value}`);
+ *       }
+ *     });
+ *   },
+ * });
+ *
+ * // Watch only approvals granted by an address (as owner)
+ * const unwatchAsOwner = watchApprovalForAddress(client, {
+ *   tokenAddress: '0x...',
+ *   watchAddress: '0x...',
+ *   ownerOnly: true,
+ *   onApproval: (events) => {
+ *     console.log(`Granted ${events.length} approvals`);
+ *   },
+ * });
+ *
+ * // Watch only approvals received by an address (as spender)
+ * const unwatchAsSpender = watchApprovalForAddress(client, {
+ *   tokenAddress: '0x...',
+ *   watchAddress: '0x...',
+ *   spenderOnly: true,
+ *   onApproval: (events) => {
+ *     console.log(`Received ${events.length} approvals`);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - If neither ownerOnly nor spenderOnly is set, watches both roles
+ * - Cannot set both ownerOnly and spenderOnly to true
+ * - More efficient than watching all approvals and filtering client-side
+ * - Server-side filtering reduces network traffic and processing
+ */
+export function watchApprovalForAddress(client, params) {
+    // Validate parameters
+    if (params.ownerOnly && params.spenderOnly) {
+        throw new Error('Cannot set both ownerOnly and spenderOnly to true');
+    }
+    // Determine filter parameters
+    let owner;
+    let spender;
+    if (params.ownerOnly) {
+        owner = params.watchAddress;
+    }
+    else if (params.spenderOnly) {
+        spender = params.watchAddress;
+    }
+    else {
+        // Watch both: need to create two separate subscriptions
+        // This is a limitation of eth_subscribe - can't do OR filters
+        // Use deduplication to prevent duplicate callbacks for the same event
+        const seenEvents = new Set();
+        const MAX_SEEN_EVENTS = 10000;
+        // Create a unique key for each event (using tx hash + log index)
+        const getEventKey = (event) => {
+            const txHash = event.log.transactionHash ?? 'pending';
+            const logIndex = event.log.logIndex ?? 0;
+            return `${txHash}-${logIndex}`;
+        };
+        // Wrapper that deduplicates events before calling the callback
+        const deduplicatedCallback = (events) => {
+            const newEvents = events.filter((event) => {
+                const key = getEventKey(event);
+                if (seenEvents.has(key)) {
+                    return false;
+                }
+                seenEvents.add(key);
+                return true;
+            });
+            // Bound the cache size to prevent memory leaks for long-running subscriptions
+            if (seenEvents.size > MAX_SEEN_EVENTS) {
+                // Remove oldest half of entries
+                const iterator = seenEvents.values();
+                for (let i = 0; i < MAX_SEEN_EVENTS / 2; i++) {
+                    const next = iterator.next();
+                    if (next.done)
+                        break;
+                    seenEvents.delete(next.value);
+                }
+            }
+            if (newEvents.length > 0) {
+                params.onApproval(newEvents);
+            }
+        };
+        const unwatchOwner = watchApproval(client, {
+            address: params.tokenAddress,
+            owner: params.watchAddress,
+            onApproval: deduplicatedCallback,
+            onError: params.onError,
+            sync: params.sync,
+            pollingInterval: params.pollingInterval,
+        });
+        const unwatchSpender = watchApproval(client, {
+            address: params.tokenAddress,
+            spender: params.watchAddress,
+            onApproval: deduplicatedCallback,
+            onError: params.onError,
+            sync: params.sync,
+            pollingInterval: params.pollingInterval,
+        });
+        // Return combined unwatch function
+        return () => {
+            unwatchOwner();
+            unwatchSpender();
+        };
+    }
+    return watchApproval(client, {
+        address: params.tokenAddress,
+        owner,
+        spender,
+        onApproval: params.onApproval,
+        onError: params.onError,
+        sync: params.sync,
+        pollingInterval: params.pollingInterval,
+    });
+}
+//# sourceMappingURL=watchApproval.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watchApproval.js","sourceRoot":"","sources":["../../events/watchApproval.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiC,cAAc,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAoC/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,UAAU,aAAa,CAC5B,MAAoB,EACpB,MAA+B;IAE/B,4DAA4D;IAC5D,MAAM,IAAI,GAA2C,EAAE,CAAC;IACxD,IAAI,MAAM,CAAC,KAAK;QAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC5C,IAAI,MAAM,CAAC,OAAO;QAAE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAElD,OAAO,MAAM,CAAC,kBAAkB,CAAC;QAChC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,GAAG,EAAE,QAAQ;QACb,SAAS,EAAE,UAAU;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QACrD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YAChB,oDAAoD;YACpD,MAAM,MAAM,GAAoB,IAAI;iBAClC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;gBACZ,IAAI,CAAC;oBACJ,MAAM,OAAO,GAAG,cAAc,CAAC;wBAC9B,GAAG,EAAE,QAAQ;wBACb,IAAI,EAAE,GAAG,CAAC,IAAI;wBACd,MAAM,EAAE,GAAG,CAAC,MAAM;qBAClB,CAA0D,CAAC;oBAE5D,OAAO;wBACN,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK;wBACzB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO;wBAC7B,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK;wBACzB,GAAG,EAAE,GAAU;qBACf,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAChB,kCAAkC;oBAClC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;wBACpB,MAAM,CAAC,OAAO,CACb,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAC7E,CAAC;oBACH,CAAC;oBACD,OAAO,IAAI,CAAC;gBACb,CAAC;YACF,CAAC,CAAC;iBACD,MAAM,CAAC,CAAC,KAAK,EAAsC,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;YAExE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC3B,CAAC;QACF,CAAC;QACD,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe,EAAE,MAAM,CAAC,eAAe;KACvC,CAAC,CAAC;AACJ,CAAC;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,UAAU,uBAAuB,CACtC,MAAoB,EACpB,MAAyC;IAEzC,sBAAsB;IACtB,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACtE,CAAC;IAED,8BAA8B;IAC9B,IAAI,KAA0B,CAAC;IAC/B,IAAI,OAA4B,CAAC;IAEjC,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC;IAC7B,CAAC;SAAM,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QAC/B,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC;IAC/B,CAAC;SAAM,CAAC;QACP,wDAAwD;QACxD,8DAA8D;QAC9D,sEAAsE;QACtE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACrC,MAAM,eAAe,GAAG,KAAK,CAAC;QAE9B,iEAAiE;QACjE,MAAM,WAAW,GAAG,CAAC,KAAoB,EAAU,EAAE;YACpD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,eAAe,IAAI,SAAS,CAAC;YACtD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC;YACzC,OAAO,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC;QAChC,CAAC,CAAC;QAEF,+DAA+D;QAC/D,MAAM,oBAAoB,GAAG,CAAC,MAAuB,EAAQ,EAAE;YAC9D,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;gBACzC,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;gBAC/B,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzB,OAAO,KAAK,CAAC;gBACd,CAAC;gBACD,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACpB,OAAO,IAAI,CAAC;YACb,CAAC,CAAC,CAAC;YAEH,8EAA8E;YAC9E,IAAI,UAAU,CAAC,IAAI,GAAG,eAAe,EAAE,CAAC;gBACvC,gCAAgC;gBAChC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;gBACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC9C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;oBAC7B,IAAI,IAAI,CAAC,IAAI;wBAAE,MAAM;oBACrB,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC/B,CAAC;YACF,CAAC;YAED,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YAC9B,CAAC;QACF,CAAC,CAAC;QAEF,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,EAAE;YAC1C,OAAO,EAAE,MAAM,CAAC,YAAY;YAC5B,KAAK,EAAE,MAAM,CAAC,YAAY;YAC1B,UAAU,EAAE,oBAAoB;YAChC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,eAAe,EAAE,MAAM,CAAC,eAAe;SACvC,CAAC,CAAC;QAEH,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,EAAE;YAC5C,OAAO,EAAE,MAAM,CAAC,YAAY;YAC5B,OAAO,EAAE,MAAM,CAAC,YAAY;YAC5B,UAAU,EAAE,oBAAoB;YAChC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,eAAe,EAAE,MAAM,CAAC,eAAe;SACvC,CAAC,CAAC;QAEH,mCAAmC;QACnC,OAAO,GAAG,EAAE;YACX,YAAY,EAAE,CAAC;YACf,cAAc,EAAE,CAAC;QAClB,CAAC,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAC,MAAM,EAAE;QAC5B,OAAO,EAAE,MAAM,CAAC,YAAY;QAC5B,KAAK;QACL,OAAO;QACP,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,eAAe,EAAE,MAAM,CAAC,eAAe;KACvC,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,192 @@
+/**
+ * Block watching utilities for Radius SDK.
+ * Provides wrappers for watching new blocks in real-time.
+ *
+ * @remarks Radius-Specific Limitations
+ *
+ * **HTTP Polling (Current Implementation)**:
+ * - Radius does NOT support `newHeads` WebSocket subscriptions
+ * - `eth_subscribe` only supports "logs" type subscriptions (not newHeads, not newPendingTransactions)
+ * - WebSocket is NOT currently enabled on Radius testnet
+ * - Default polling interval: 1000ms (1 second)
+ * - Uses HTTP-based polling to detect new blocks as a fallback mechanism
+ *
+ * **Future Considerations**:
+ * - When WebSocket is enabled on Radius, this module can be updated to use native subscriptions
+ * - Review implementation in watchLogs.ts as a reference for WebSocket usage patterns
+ */
+import type { Block, PublicClient } from 'viem';
+/**
+ * Default polling interval for block watching in milliseconds.
+ * Used when polling is required (e.g., HTTP transport fallback).
+ * Can be overridden per watch call via pollingInterval parameter.
+ */
+export declare const DEFAULT_POLLING_INTERVAL_MS = 1000;
+/**
+ * Parameters for watching new block numbers.
+ */
+export interface WatchBlockNumberParams {
+    /** Callback function invoked when a new block number is detected */
+    onBlockNumber: (blockNumber: bigint) => void;
+    /** Callback function invoked when an error occurs */
+    onError?: (error: Error) => void;
+    /** Whether to emit the current block number on subscription start */
+    emitOnBegin?: boolean;
+    /** Polling interval in milliseconds (default: 1000ms for HTTP, real-time for WebSocket) */
+    pollingInterval?: number;
+}
+/**
+ * Watches for new block numbers.
+ * Uses WebSocket subscriptions when available, falls back to polling for HTTP transport.
+ *
+ * @param client - The PublicClient to use
+ * @param params - Block number watching parameters
+ * @returns An unwatch function to stop watching
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchBlockNumber } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch for new blocks
+ * const unwatch = watchBlockNumber(client, {
+ *   onBlockNumber: (blockNumber) => {
+ *     console.log('New block:', blockNumber);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Error:', error);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - WebSocket transport provides real-time block notifications
+ * - HTTP transport falls back to polling (default 1s interval)
+ * - Radius does not support eth_newBlockFilter (traditional filter API)
+ * - WebSocket subscriptions are more efficient than polling
+ * - For HTTP clients, consider increasing pollingInterval to reduce load
+ */
+export declare function watchBlockNumber(client: PublicClient, params: WatchBlockNumberParams): () => void;
+/**
+ * Parameters for watching new blocks (full block data).
+ */
+export interface WatchBlocksParams {
+    /** Callback function invoked when a new block is detected */
+    onBlock: (block: Block) => void;
+    /** Callback function invoked when an error occurs */
+    onError?: (error: Error) => void;
+    /** Whether to emit the current block on subscription start */
+    emitOnBegin?: boolean;
+    /** Whether to include transactions in the block (default: false) */
+    includeTransactions?: boolean;
+    /** Polling interval in milliseconds (default: 1000ms for HTTP, real-time for WebSocket) */
+    pollingInterval?: number;
+}
+/**
+ * Watches for new blocks with full block data.
+ * Uses WebSocket subscriptions when available, falls back to polling for HTTP transport.
+ *
+ * @param client - The PublicClient to use
+ * @param params - Block watching parameters
+ * @returns An unwatch function to stop watching
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchBlocks } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch for new blocks
+ * const unwatch = watchBlocks(client, {
+ *   onBlock: (block) => {
+ *     console.log('New block:', block.number);
+ *     console.log('Timestamp:', block.timestamp);
+ *     console.log('Transactions:', block.transactions.length);
+ *   },
+ * });
+ *
+ * // Watch blocks with full transaction data
+ * const unwatchWithTxs = watchBlocks(client, {
+ *   includeTransactions: true,
+ *   onBlock: (block) => {
+ *     console.log('New block with', block.transactions.length, 'transactions');
+ *     // block.transactions contains full transaction objects
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - WebSocket transport provides real-time block notifications
+ * - HTTP transport falls back to polling (default 1s interval)
+ * - includeTransactions=true fetches full transaction data (slower)
+ * - includeTransactions=false only includes transaction hashes (faster, default)
+ * - WebSocket is recommended for real-time block monitoring
+ * - Polling with includeTransactions=true can be expensive
+ */
+export declare function watchBlocks(client: PublicClient, params: WatchBlocksParams): () => void;
+/**
+ * Parameters for watching pending transactions.
+ */
+export interface WatchPendingTransactionsParams {
+    /** Callback function invoked when new pending transactions are detected */
+    onTransactions: (hashes: `0x${string}`[]) => void;
+    /** Callback function invoked when an error occurs */
+    onError?: (error: Error) => void;
+    /** Polling interval in milliseconds (required for HTTP transport) */
+    pollingInterval?: number;
+}
+/**
+ * Watches for pending transactions in the mempool.
+ *
+ * @param client - The PublicClient to use
+ * @param params - Pending transaction watching parameters
+ * @returns An unwatch function to stop watching
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchPendingTransactions } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch for pending transactions
+ * const unwatch = watchPendingTransactions(client, {
+ *   onTransactions: (hashes) => {
+ *     console.log('New pending transactions:', hashes);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - LIMITATION: Radius does not support eth_newPendingTransactionFilter
+ * - This function may not work as expected on Radius
+ * - WebSocket transport with "pendingTransactions" subscription is not supported
+ * - Consider using block watching and filtering confirmed transactions instead
+ * - This is provided for API completeness but may have limited functionality
+ */
+export declare function watchPendingTransactions(client: PublicClient, params: WatchPendingTransactionsParams): () => void;
+//# sourceMappingURL=watchBlock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watchBlock.d.ts","sourceRoot":"","sources":["../../events/watchBlock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAqD,MAAM,MAAM,CAAC;AAEnG;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,oEAAoE;IACpE,aAAa,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,qDAAqD;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,sBAAsB,GAAG,MAAM,IAAI,CASjG;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,6DAA6D;IAC7D,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,qDAAqD;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAevF;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC9C,2EAA2E;IAC3E,cAAc,EAAE,CAAC,MAAM,EAAE,KAAK,MAAM,EAAE,EAAE,KAAK,IAAI,CAAC;IAClD,qDAAqD;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,wBAAwB,CACvC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,8BAA8B,GACpC,MAAM,IAAI,CAMZ"}