@ryanrfox/sdk 0.0.2 → 2.0.3

package/src/_types/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/_types/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/_types/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/_types/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"}

package/src/_types/events/watchLogs.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Generic log watching utilities for Radius SDK.
+ * Provides real-time event subscription capabilities using WebSocket.
+ *
+ * @remarks Radius-Specific Limitations and Requirements
+ *
+ * **WebSocket Subscriptions (eth_subscribe)**:
+ * - BOTH address AND topics are mandatory when using `eth_subscribe` with "logs" type
+ * - Partial filtering (address-only or topics-only) may not work as expected
+ * - Currently supported only via WebSocket transport (not HTTP)
+ * - WebSocket is NOT currently enabled on Radius testnet
+ *
+ * **Recommended Approach**:
+ * - For now, use HTTP polling with eth_getLogs (see watchLogs and watchRawLogs functions)
+ * - HTTP polling is the most reliable approach until WebSocket is enabled
+ * - When WebSocket becomes available on testnet, these functions can leverage native subscriptions
+ *
+ * **Important Note**:
+ * - The address parameter is mandatory in all log filters on Radius
+ * - Filters without address will fail with error "Filters without addresses are not supported"
+ */
+import type { Address, Hash, Log, PublicClient, WatchContractEventReturnType } from 'viem';
+import { watchContractEvent } from 'viem/actions';
+/**
+ * Watches for contract events in real-time using WebSocket subscriptions.
+ * Uses viem's watchContractEvent under the hood, which leverages eth_subscribe for "logs".
+ *
+ * @param client - The PublicClient to use (must be configured with WebSocket transport)
+ * @param params - Event watching parameters including address, ABI, event name, and callback
+ * @returns An unwatch function to stop the subscription
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchLogs } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * // Create client with WebSocket transport
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch for events
+ * const unwatch = watchLogs(client, {
+ *   address: '0x...',
+ *   abi: contractAbi,
+ *   eventName: 'Transfer',
+ *   onLogs: (logs) => {
+ *     console.log('Transfer events:', logs);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - Requires WebSocket transport for real-time subscriptions
+ * - Radius supports eth_subscribe with type "logs" only
+ * - Address parameter is mandatory on Radius
+ * - Subscriptions consume gas from your RPC key (10 GAS/sec)
+ * - Automatically cleaned up on disconnect
+ * - For HTTP transport, consider using getLogs with polling instead
+ */
+export declare function watchLogs(client: PublicClient, params: Parameters<typeof watchContractEvent>[1]): WatchContractEventReturnType;
+/**
+ * Parameters for watching raw logs without ABI decoding.
+ */
+export interface WatchRawLogsParameters {
+    /** The contract address to watch */
+    address: Address | Address[];
+    /** Optional event signature hashes to filter by */
+    topics?: Hash[][];
+    /** Callback function invoked when logs are received */
+    onLogs: (logs: Log[]) => 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 raw logs without ABI decoding.
+ * Useful when you want to receive raw log data or watch multiple event types.
+ *
+ * @param client - The PublicClient to use (WebSocket transport recommended)
+ * @param params - Raw log watching parameters
+ * @returns An unwatch function to stop the subscription
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchRawLogs } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch for all events from a contract
+ * const unwatch = watchRawLogs(client, {
+ *   address: '0x...',
+ *   onLogs: (logs) => {
+ *     logs.forEach(log => {
+ *       console.log('Log:', log.topics, log.data);
+ *     });
+ *   },
+ *   onError: (error) => {
+ *     console.error('Subscription error:', error);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - Does not decode log data; returns raw topics and data
+ * - Useful for monitoring multiple event types from same contract
+ * - Requires address parameter (mandatory on Radius)
+ * - WebSocket transport provides real-time updates
+ * - HTTP transport falls back to polling (less efficient)
+ */
+export declare function watchRawLogs(client: PublicClient, params: WatchRawLogsParameters): WatchContractEventReturnType;
+//# sourceMappingURL=watchLogs.d.ts.map

package/src/_types/events/watchLogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchLogs.d.ts","sourceRoot":"","sources":["../../events/watchLogs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,MAAM,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,SAAS,CACxB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,GAC9C,4BAA4B,CAE9B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,oCAAoC;IACpC,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAAC;IAC7B,mDAAmD;IACnD,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;IAClB,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9B,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,sBAAsB,GAC5B,4BAA4B,CAS9B"}

package/src/_types/events/watchTransfer.d.ts

@@ -0,0 +1,164 @@
+/**
+ * ERC-20 Transfer event watching utilities for Radius SDK.
+ * Provides convenient wrappers for watching Transfer events in real-time.
+ */
+import type { Address, Log, PublicClient, WatchContractEventReturnType } from 'viem';
+/**
+ * Decoded Transfer event data.
+ */
+export interface TransferEvent {
+    /** The address that sent the tokens */
+    from: Address;
+    /** The address that received the tokens */
+    to: Address;
+    /** The amount of tokens transferred (in smallest unit) */
+    value: bigint;
+    /** The raw log data */
+    log: Log;
+}
+/**
+ * Parameters for watching Transfer events.
+ */
+export interface WatchTransferParameters {
+    /** The ERC-20 token contract address to watch */
+    address: Address;
+    /** Optional: Filter by sender address */
+    from?: Address;
+    /** Optional: Filter by recipient address */
+    to?: Address;
+    /** Callback function invoked when Transfer events are received */
+    onTransfer: (events: TransferEvent[]) => 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 Transfer events in real-time.
+ * Automatically decodes Transfer events and provides type-safe callbacks.
+ *
+ * @param client - The PublicClient to use (WebSocket transport recommended)
+ * @param params - Transfer event watching parameters
+ * @returns An unwatch function to stop the subscription
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchTransfer } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch all transfers for a token
+ * const unwatch = watchTransfer(client, {
+ *   address: '0x...', // Token address
+ *   onTransfer: (events) => {
+ *     events.forEach(event => {
+ *       console.log(`Transfer: ${event.value} from ${event.from} to ${event.to}`);
+ *     });
+ *   },
+ * });
+ *
+ * // Watch transfers to a specific address
+ * const unwatchToAddress = watchTransfer(client, {
+ *   address: '0x...', // Token address
+ *   to: '0x...', // Recipient address
+ *   onTransfer: (events) => {
+ *     console.log(`Received ${events.length} transfers`);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - Requires WebSocket transport for real-time subscriptions
+ * - Automatically decodes Transfer events using ERC-20 ABI
+ * - Filters by from/to addresses if provided
+ * - Event signature: Transfer(address indexed from, address indexed to, uint256 value)
+ * - Subscriptions consume gas from your RPC key on Radius (10 GAS/sec)
+ */
+export declare function watchTransfer(client: PublicClient, params: WatchTransferParameters): WatchContractEventReturnType;
+/**
+ * Parameters for watching Transfer events for a specific address (as sender or receiver).
+ */
+export interface WatchTransferForAddressParameters {
+    /** The ERC-20 token contract address to watch */
+    tokenAddress: Address;
+    /** The address to watch (as sender or receiver) */
+    watchAddress: Address;
+    /** Whether to watch as sender only (default: false, watches both sender and receiver) */
+    senderOnly?: boolean;
+    /** Whether to watch as receiver only (default: false, watches both sender and receiver) */
+    receiverOnly?: boolean;
+    /** Callback function invoked when Transfer events are received */
+    onTransfer: (events: TransferEvent[]) => 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 Transfer events involving a specific address (as sender or receiver).
+ * Convenience wrapper around watchTransfer for monitoring a single address.
+ *
+ * @param client - The PublicClient to use (WebSocket transport recommended)
+ * @param params - Transfer watching parameters for specific address
+ * @returns An unwatch function to stop the subscription
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient } from 'viem';
+ * import { createWebSocketTransport, watchTransferForAddress } from '@radiustechsystems/sdk/events';
+ * import { radiusTestnet } from '@radiustechsystems/sdk/chains';
+ *
+ * const client = createPublicClient({
+ *   chain: radiusTestnet,
+ *   transport: createWebSocketTransport(radiusTestnet),
+ * });
+ *
+ * // Watch all transfers involving an address (sent or received)
+ * const unwatch = watchTransferForAddress(client, {
+ *   tokenAddress: '0x...', // Token address
+ *   watchAddress: '0x...', // Address to monitor
+ *   onTransfer: (events) => {
+ *     events.forEach(event => {
+ *       if (event.from === watchAddress) {
+ *         console.log(`Sent ${event.value} to ${event.to}`);
+ *       } else {
+ *         console.log(`Received ${event.value} from ${event.from}`);
+ *       }
+ *     });
+ *   },
+ * });
+ *
+ * // Watch only transfers sent from an address
+ * const unwatchSent = watchTransferForAddress(client, {
+ *   tokenAddress: '0x...',
+ *   watchAddress: '0x...',
+ *   senderOnly: true,
+ *   onTransfer: (events) => {
+ *     console.log(`Sent ${events.length} transfers`);
+ *   },
+ * });
+ *
+ * // Stop watching
+ * unwatch();
+ * ```
+ *
+ * @remarks
+ * - If neither senderOnly nor receiverOnly is set, watches both directions
+ * - Cannot set both senderOnly and receiverOnly to true
+ * - More efficient than watching all transfers and filtering client-side
+ * - Server-side filtering reduces network traffic and processing
+ */
+export declare function watchTransferForAddress(client: PublicClient, params: WatchTransferForAddressParameters): WatchContractEventReturnType;
+//# sourceMappingURL=watchTransfer.d.ts.map

package/src/_types/events/watchTransfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchTransfer.d.ts","sourceRoot":"","sources":["../../events/watchTransfer.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,IAAI,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,0DAA0D;IAC1D,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,yCAAyC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;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,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;IACtB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2FAA2F;IAC3F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,iCAAiC,GACvC,4BAA4B,CAyF9B"}