@ryanrfox/sdk 0.0.2 → 2.0.3

package/src/_esm/events/watchBlock.js

@@ -0,0 +1,162 @@
+/**
+ * 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 const DEFAULT_POLLING_INTERVAL_MS = 1000;
+/**
+ * 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 function watchBlockNumber(client, params) {
+    const watchParams = {
+        onBlockNumber: params.onBlockNumber,
+        onError: params.onError,
+        emitOnBegin: params.emitOnBegin,
+        pollingInterval: params.pollingInterval ?? DEFAULT_POLLING_INTERVAL_MS,
+    };
+    return client.watchBlockNumber(watchParams);
+}
+/**
+ * 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 function watchBlocks(client, params) {
+    // Only pass includeTransactions if explicitly set to true
+    const watchParams = {
+        onBlock: params.onBlock,
+        onError: params.onError,
+        emitOnBegin: params.emitOnBegin,
+        pollingInterval: params.pollingInterval ?? DEFAULT_POLLING_INTERVAL_MS,
+    };
+    // Type assertion needed because viem's type is very strict about false vs undefined
+    if (params.includeTransactions === true) {
+        watchParams.includeTransactions = true;
+    }
+    return client.watchBlocks(watchParams);
+}
+/**
+ * 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 function watchPendingTransactions(client, params) {
+    return client.watchPendingTransactions({
+        onTransactions: params.onTransactions,
+        onError: params.onError,
+        pollingInterval: params.pollingInterval,
+    });
+}
+//# sourceMappingURL=watchBlock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watchBlock.js","sourceRoot":"","sources":["../../events/watchBlock.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAgBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAoB,EAAE,MAA8B;IACpF,MAAM,WAAW,GAA+B;QAC/C,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,2BAA2B;KACtE,CAAC;IAEF,OAAO,MAAM,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;AAC7C,CAAC;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,UAAU,WAAW,CAAC,MAAoB,EAAE,MAAyB;IAC1E,0DAA0D;IAC1D,MAAM,WAAW,GAA0B;QAC1C,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,2BAA2B;KACtE,CAAC;IAEF,oFAAoF;IACpF,IAAI,MAAM,CAAC,mBAAmB,KAAK,IAAI,EAAE,CAAC;QACxC,WAAiD,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAC/E,CAAC;IAED,OAAO,MAAM,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;AACxC,CAAC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,wBAAwB,CACvC,MAAoB,EACpB,MAAsC;IAEtC,OAAO,MAAM,CAAC,wBAAwB,CAAC;QACtC,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe,EAAE,MAAM,CAAC,eAAe;KACvC,CAAC,CAAC;AACJ,CAAC"}

package/src/_esm/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/_esm/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/_esm/events/watchLogs.js

@@ -0,0 +1,100 @@
+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 function watchLogs(client, params) {
+    return watchContractEvent(client, params);
+}
+/**
+ * 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 function watchRawLogs(client, params) {
+    // Use viem's watchEvent action for raw logs
+    // This will use eth_subscribe for WebSocket or polling for HTTP
+    return client.watchEvent({
+        address: params.address,
+        onLogs: params.onLogs,
+        onError: params.onError,
+        pollingInterval: params.pollingInterval,
+    });
+}
+//# sourceMappingURL=watchLogs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watchLogs.js","sourceRoot":"","sources":["../../events/watchLogs.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,SAAS,CACxB,MAAoB,EACpB,MAAgD;IAEhD,OAAO,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,UAAU,YAAY,CAC3B,MAAoB,EACpB,MAA8B;IAE9B,4CAA4C;IAC5C,gEAAgE;IAChE,OAAO,MAAM,CAAC,UAAU,CAAC;QACxB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe,EAAE,MAAM,CAAC,eAAe;KACvC,CAAC,CAAC;AACJ,CAAC"}

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