@ryanrfox/sdk 0.0.2 → 2.0.3

package/src/_types/errors/contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Contract-related errors
+ */
+import type { Address, Hex } from 'viem';
+import { RadiusError, type RadiusErrorOptions } from './base';
+/**
+ * Error thrown when a contract call fails.
+ */
+export declare class ContractCallError extends RadiusError {
+    readonly name = "ContractCallError";
+    /** The contract address */
+    readonly contractAddress?: Address;
+    /** The function name that was called */
+    readonly functionName?: string;
+    /** The arguments passed to the function */
+    readonly args?: readonly unknown[];
+    constructor(message: string, options?: RadiusErrorOptions & {
+        contractAddress?: Address;
+        functionName?: string;
+        args?: readonly unknown[];
+    });
+}
+/**
+ * Error thrown when contract deployment fails.
+ */
+export declare class ContractDeploymentError extends RadiusError {
+    readonly name = "ContractDeploymentError";
+    /** The contract bytecode */
+    readonly bytecode?: Hex;
+    /** The constructor arguments */
+    readonly constructorArgs?: readonly unknown[];
+    constructor(message: string, options?: RadiusErrorOptions & {
+        bytecode?: Hex;
+        constructorArgs?: readonly unknown[];
+    });
+}
+/**
+ * Error thrown when ABI encoding/decoding fails.
+ */
+export declare class AbiError extends RadiusError {
+    readonly name = "AbiError";
+    constructor(message: string, options?: RadiusErrorOptions);
+}
+/**
+ * Error thrown when a required contract ABI is missing.
+ */
+export declare class MissingAbiError extends RadiusError {
+    readonly name = "MissingAbiError";
+    constructor(message?: string, options?: RadiusErrorOptions);
+}
+//# sourceMappingURL=contract.d.ts.map

package/src/_types/errors/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../errors/contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAE9D;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IACjD,SAAkB,IAAI,uBAAuB;IAE7C,2BAA2B;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,wCAAwC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;gBAGlC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAkB,GAAG;QAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;KACrB;CAUP;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,WAAW;IACvD,SAAkB,IAAI,6BAA6B;IAEnD,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC;IACxB,gCAAgC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;gBAG7C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAkB,GAAG;QAC7B,QAAQ,CAAC,EAAE,GAAG,CAAC;QACf,eAAe,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;KAChC;CASP;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,WAAW;IACxC,SAAkB,IAAI,cAAc;gBAExB,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAM7D;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC/C,SAAkB,IAAI,qBAAqB;gBAE/B,OAAO,SAA6B,EAAE,OAAO,GAAE,kBAAuB;CAMlF"}

package/src/_types/errors/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Radius SDK Error Types
+ *
+ * This module provides a rich error hierarchy for better error handling
+ * and debugging. All errors extend RadiusError which provides:
+ * - Short messages for quick understanding
+ * - Detailed error information
+ * - Documentation links
+ * - Error cause chain traversal via .walk()
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   RadiusError,
+ *   TransactionFailedError,
+ *   InsufficientBalanceError,
+ * } from '@radiustechsystems/sdk';
+ *
+ * try {
+ *   await client.sendTransaction({ to, value });
+ * } catch (error) {
+ *   if (error instanceof InsufficientBalanceError) {
+ *     console.log('Not enough funds:', error.balance, 'required:', error.required);
+ *   } else if (error instanceof TransactionFailedError) {
+ *     console.log('Transaction failed:', error.transactionHash);
+ *   } else if (error instanceof RadiusError) {
+ *     console.log('SDK error:', error.shortMessage);
+ *   }
+ * }
+ * ```
+ */
+export { InsufficientBalanceError, InvalidAddressError, InvalidPrivateKeyError, SignerNotFoundError, SigningError, } from './account.js';
+export { RadiusError, type RadiusErrorOptions } from './base.js';
+export { AbiError, ContractCallError, ContractDeploymentError, MissingAbiError, } from './contract.js';
+export { BatchTransactionError, type BatchTransactionResult, GasEstimationError, NonceError, TransactionFailedError, TransactionRevertedError, TransactionTimeoutError, } from './transaction.js';
+/**
+ * Error types that can be thrown by sendTransaction operations.
+ */
+export type SendTransactionErrorType = InsufficientBalanceError | TransactionFailedError | TransactionRevertedError | TransactionTimeoutError | SignerNotFoundError | GasEstimationError | NonceError;
+/**
+ * Error types that can be thrown by batch transaction operations.
+ */
+export type BatchTransactionErrorType = BatchTransactionError | GasEstimationError | NonceError;
+/**
+ * Error types that can be thrown by contract call operations.
+ */
+export type CallContractErrorType = ContractCallError | MissingAbiError | AbiError;
+/**
+ * Error types that can be thrown by contract execution operations.
+ */
+export type ExecuteContractErrorType = ContractCallError | TransactionFailedError | TransactionRevertedError | SignerNotFoundError | GasEstimationError | MissingAbiError | AbiError;
+/**
+ * Error types that can be thrown by contract deployment operations.
+ */
+export type DeployContractErrorType = ContractDeploymentError | TransactionFailedError | TransactionRevertedError | SignerNotFoundError | GasEstimationError | AbiError;
+/**
+ * Error types that can be thrown by signing operations.
+ */
+export type SigningErrorType = SigningError | SignerNotFoundError | InvalidPrivateKeyError;
+import type { InsufficientBalanceError, InvalidPrivateKeyError, SignerNotFoundError, SigningError } from './account.js';
+import type { AbiError, ContractCallError, ContractDeploymentError, MissingAbiError } from './contract.js';
+import type { BatchTransactionError, GasEstimationError, NonceError, TransactionFailedError, TransactionRevertedError, TransactionTimeoutError } from './transaction.js';
+//# sourceMappingURL=index.d.ts.map

package/src/_types/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EACN,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,YAAY,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAGjE,OAAO,EACN,QAAQ,EACR,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,GACf,MAAM,eAAe,CAAC;AAGvB,OAAO,EACN,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,kBAAkB,EAClB,UAAU,EACV,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,GACvB,MAAM,kBAAkB,CAAC;AAG1B;;GAEG;AACH,MAAM,MAAM,wBAAwB,GACjC,wBAAwB,GACxB,sBAAsB,GACtB,wBAAwB,GACxB,uBAAuB,GACvB,mBAAmB,GACnB,kBAAkB,GAClB,UAAU,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAEhG;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,eAAe,GAAG,QAAQ,CAAC;AAEnF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GACjC,iBAAiB,GACjB,sBAAsB,GACtB,wBAAwB,GACxB,mBAAmB,GACnB,kBAAkB,GAClB,eAAe,GACf,QAAQ,CAAC;AAEZ;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAChC,uBAAuB,GACvB,sBAAsB,GACtB,wBAAwB,GACxB,mBAAmB,GACnB,kBAAkB,GAClB,QAAQ,CAAC;AAEZ;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;AAG3F,OAAO,KAAK,EACX,wBAAwB,EACxB,sBAAsB,EACtB,mBAAmB,EACnB,YAAY,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACX,QAAQ,EACR,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EACX,qBAAqB,EACrB,kBAAkB,EAClB,UAAU,EACV,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,MAAM,kBAAkB,CAAC"}

package/src/_types/errors/transaction.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Transaction-related errors
+ */
+import type { Address, Hash, Hex } from 'viem';
+import { RadiusError, type RadiusErrorOptions } from './base';
+/**
+ * Error thrown when a transaction fails to execute.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await walletClient.sendTransaction({ to, value });
+ * } catch (error) {
+ *   if (error instanceof TransactionFailedError) {
+ *     console.log('Transaction failed:', error.transactionHash);
+ *     console.log('Reason:', error.shortMessage);
+ *   }
+ * }
+ * ```
+ */
+export declare class TransactionFailedError extends RadiusError {
+    readonly name = "TransactionFailedError";
+    /** The transaction hash (if available) */
+    readonly transactionHash?: Hash;
+    /** The reason for failure */
+    readonly reason?: string;
+    constructor(message: string, options?: RadiusErrorOptions & {
+        transactionHash?: Hash;
+        reason?: string;
+    });
+}
+/**
+ * Error thrown when a transaction reverts on-chain.
+ */
+export declare class TransactionRevertedError extends RadiusError {
+    readonly name = "TransactionRevertedError";
+    /** The transaction hash (if available) */
+    readonly transactionHash?: Hash;
+    /** The reason for failure */
+    readonly reason?: string;
+    /** The revert reason (decoded if available) */
+    readonly revertReason?: string;
+    /** The raw revert data */
+    readonly revertData?: Hex;
+    constructor(message: string, options?: RadiusErrorOptions & {
+        transactionHash?: Hash;
+        reason?: string;
+        revertReason?: string;
+        revertData?: Hex;
+    });
+}
+/**
+ * Error thrown when gas estimation fails.
+ */
+export declare class GasEstimationError extends RadiusError {
+    readonly name = "GasEstimationError";
+    /** The address being called */
+    readonly to?: Address;
+    /** The call data */
+    readonly data?: Hex;
+    constructor(message: string, options?: RadiusErrorOptions & {
+        to?: Address;
+        data?: Hex;
+    });
+}
+/**
+ * Error thrown when transaction nonce is invalid.
+ */
+export declare class NonceError extends RadiusError {
+    readonly name = "NonceError";
+    /** The nonce that was used */
+    readonly nonce?: number;
+    /** The expected nonce */
+    readonly expectedNonce?: number;
+    constructor(message: string, options?: RadiusErrorOptions & {
+        nonce?: number;
+        expectedNonce?: number;
+    });
+}
+/**
+ * Error thrown when a transaction times out waiting for confirmation.
+ */
+export declare class TransactionTimeoutError extends RadiusError {
+    readonly name = "TransactionTimeoutError";
+    /** The transaction hash */
+    readonly transactionHash?: Hash;
+    /** How long we waited (in ms) */
+    readonly timeout?: number;
+    constructor(message: string, options?: RadiusErrorOptions & {
+        transactionHash?: Hash;
+        timeout?: number;
+    });
+}
+/**
+ * Result of a single transaction in a batch.
+ */
+export interface BatchTransactionResult {
+    /** The index of this transaction in the batch */
+    index: number;
+    /** The transaction hash (if successful) */
+    hash?: Hash;
+    /** The error message (if failed) */
+    error?: string;
+}
+/**
+ * Error thrown when one or more transactions in a batch fail.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await walletClient.sendTransactionBatch({ transactions });
+ * } catch (error) {
+ *   if (error instanceof BatchTransactionError) {
+ *     console.log('Batch failed:', error.message);
+ *     error.results.forEach((r, i) => {
+ *       if (r.error) {
+ *         console.log(`  Transaction ${i} failed: ${r.error}`);
+ *       } else {
+ *         console.log(`  Transaction ${i} succeeded: ${r.hash}`);
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class BatchTransactionError extends RadiusError {
+    readonly name = "BatchTransactionError";
+    /** Results for each transaction in the batch */
+    readonly results: BatchTransactionResult[];
+    constructor(message: string, results: BatchTransactionResult[], options?: RadiusErrorOptions);
+}
+//# sourceMappingURL=transaction.d.ts.map

package/src/_types/errors/transaction.d.ts.map

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

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