@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/adapters/BaseAdapter.d.ts

@@ -0,0 +1,231 @@
+/**
+ * BaseAdapter - Abstract base class for all adapter implementations
+ *
+ * Provides shared utility methods for parsing user-friendly inputs into
+ * protocol-level types. All adapters extend this class to ensure consistent
+ * behavior across the Three-Level API.
+ *
+ * Key Responsibilities:
+ * - Amount parsing (string → bigint with 6 decimals for USDC)
+ * - Address validation (0x-prefixed hex)
+ * - Deadline parsing ("+24h" → Unix timestamp)
+ * - User-friendly error messages
+ *
+ * @module adapters/BaseAdapter
+ */
+/**
+ * Default dispute window in seconds (2 days).
+ * Used when no dispute window is specified in transaction parameters.
+ */
+export declare const DEFAULT_DISPUTE_WINDOW_SECONDS = 172800;
+/**
+ * Minimum dispute window in seconds (1 hour).
+ * Ensures requesters have reasonable time to dispute.
+ *
+ * SECURITY: Prevents providers from setting windows too short
+ * to avoid dispute detection.
+ */
+export declare const MIN_DISPUTE_WINDOW_SECONDS = 3600;
+/**
+ * Maximum dispute window in seconds (30 days).
+ * Prevents excessively long fund locks.
+ *
+ * SECURITY: Prevents DoS via indefinite fund locking.
+ */
+export declare const MAX_DISPUTE_WINDOW_SECONDS: number;
+/**
+ * Default deadline offset in seconds (24 hours).
+ * Used when no deadline is specified in transaction parameters.
+ */
+export declare const DEFAULT_DEADLINE_SECONDS = 86400;
+/**
+ * Minimum transaction amount in USDC wei (6 decimals).
+ * $0.05 minimum per AGIRAILS protocol specification.
+ */
+export declare const MIN_AMOUNT_WEI = 50000n;
+/**
+ * Maximum deadline in hours (10 years).
+ * Prevents integer overflow in deadline calculations.
+ */
+export declare const MAX_DEADLINE_HOURS = 87600;
+/**
+ * Maximum deadline in days (10 years).
+ * Prevents integer overflow in deadline calculations.
+ */
+export declare const MAX_DEADLINE_DAYS = 3650;
+/**
+ * Custom error for validation failures.
+ *
+ * Thrown when user input is invalid (e.g., malformed address, negative amount).
+ * Provides descriptive error messages for end-user debugging.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid amount format: "abc". Expected number like "100" or "100.50"');
+ * ```
+ */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Abstract base adapter with shared parsing utilities.
+ *
+ * Provides common functionality for all adapter implementations:
+ * - Amount parsing (USDC has 6 decimals)
+ * - Address validation
+ * - Deadline parsing (relative time or Unix timestamp)
+ * - Amount formatting
+ *
+ * @abstract
+ */
+export declare abstract class BaseAdapter {
+    protected requesterAddress: string;
+    /**
+     * Creates a new BaseAdapter instance.
+     *
+     * @param requesterAddress - The requester's Ethereum address
+     */
+    constructor(requesterAddress: string);
+    /**
+     * Parse user-friendly amount string to bigint (USDC has 6 decimals).
+     *
+     * Accepts multiple input formats:
+     * - "100" → 100_000_000n (100.00 USDC)
+     * - "100.50" → 100_500_000n (100.50 USDC)
+     * - "100 USDC" → 100_000_000n (strips currency suffix)
+     * - "$100" → 100_000_000n (strips $ prefix)
+     * - 100 (number) → 100_000_000n
+     *
+     * Rejects:
+     * - "abc" → throws ValidationError
+     * - "" → throws ValidationError
+     * - "-100" → throws ValidationError (negative amounts)
+     * - "100.1234567" → throws ValidationError (too many decimals)
+     *
+     * @param amount - Amount as string or number
+     * @returns Amount as bigint with 6 decimals
+     * @throws {ValidationError} If amount format is invalid
+     *
+     * @example
+     * ```typescript
+     * const amount = this.parseAmount("100.50"); // 100_500_000n
+     * const amount = this.parseAmount("100 USDC"); // 100_000_000n
+     * ```
+     */
+    protected parseAmount(amount: string | number): bigint;
+    /**
+     * Validate Ethereum address format.
+     *
+     * Checks that address:
+     * - Is a string
+     * - Starts with "0x"
+     * - Is exactly 42 characters (0x + 40 hex chars)
+     * - Contains only valid hex characters
+     *
+     * Note: Does not validate checksum (EIP-55) in mock mode.
+     *
+     * @param address - Address to validate
+     * @param paramName - Parameter name for error message
+     * @returns Validated address (unchanged)
+     * @throws {ValidationError} If address format is invalid
+     *
+     * @example
+     * ```typescript
+     * const provider = this.validateAddress(params.to, 'to');
+     * ```
+     */
+    protected validateAddress(address: string, paramName: string): string;
+    /**
+     * Parse deadline from relative time expression or Unix timestamp.
+     *
+     * Accepts multiple formats:
+     * - undefined → now + 24 hours (default)
+     * - 1734076400 (number) → passed through as Unix timestamp
+     * - "+1h" → now + 1 hour
+     * - "+24h" → now + 24 hours
+     * - "+7d" → now + 7 days
+     *
+     * Rejects:
+     * - "invalid" → throws ValidationError
+     * - "-24h" → throws ValidationError (negative time)
+     *
+     * @param deadline - Deadline as relative time string, Unix timestamp, or undefined
+     * @param currentTime - Current time in seconds (defaults to Date.now() / 1000)
+     * @returns Unix timestamp in seconds
+     * @throws {ValidationError} If deadline format is invalid
+     *
+     * @example
+     * ```typescript
+     * const deadline = this.parseDeadline("+24h"); // now + 86400
+     * const deadline = this.parseDeadline(1734076400); // 1734076400
+     * const deadline = this.parseDeadline(); // now + 86400 (default)
+     * ```
+     */
+    protected parseDeadline(deadline?: string | number, currentTime?: number): number;
+    /**
+     * Validate and normalize dispute window.
+     *
+     * SECURITY FIX (L-1): Enforces bounds on dispute window:
+     * - Minimum: 1 hour (prevents skipping disputes)
+     * - Maximum: 30 days (prevents indefinite fund locking)
+     *
+     * @param disputeWindow - Dispute window in seconds (undefined uses default)
+     * @returns Validated dispute window in seconds
+     * @throws {ValidationError} If window is outside allowed bounds
+     *
+     * @example
+     * ```typescript
+     * this.validateDisputeWindow(3600); // 1 hour - OK
+     * this.validateDisputeWindow(86400); // 1 day - OK
+     * this.validateDisputeWindow(100); // Too short - throws
+     * this.validateDisputeWindow(31 * 86400); // Too long - throws
+     * ```
+     */
+    protected validateDisputeWindow(disputeWindow?: number): number;
+    /**
+     * Validate bytes32 hex string format.
+     *
+     * SECURITY FIX (L-2): Validates that a string is a valid bytes32 hex.
+     * Used for transaction IDs, escrow IDs, attestation UIDs, etc.
+     *
+     * @param value - Value to validate
+     * @param paramName - Parameter name for error message
+     * @returns Validated bytes32 string (normalized to lowercase)
+     * @throws {ValidationError} If format is invalid
+     *
+     * @example
+     * ```typescript
+     * const txId = this.validateBytes32(id, 'transactionId');
+     * ```
+     */
+    protected validateBytes32(value: string, paramName: string): string;
+    /**
+     * Validate Unix timestamp is reasonable.
+     *
+     * SECURITY FIX (L-6): Validates timestamps to prevent overflow/underflow.
+     *
+     * @param timestamp - Unix timestamp in seconds
+     * @param paramName - Parameter name for error message
+     * @returns Validated timestamp
+     * @throws {ValidationError} If timestamp is invalid
+     */
+    protected validateTimestamp(timestamp: number, paramName: string): number;
+    /**
+     * Format bigint amount to human-readable string.
+     *
+     * Converts USDC wei (6 decimals) to formatted string with 2 decimal places.
+     * Uses proper rounding (round half up) for display purposes.
+     *
+     * @param amount - Amount as bigint (6 decimals) or string
+     * @returns Formatted string like "100.00 USDC"
+     *
+     * @example
+     * ```typescript
+     * this.formatAmount(100_000_000n); // "100.00 USDC"
+     * this.formatAmount(100_500_000n); // "100.50 USDC"
+     * this.formatAmount(100_126_000n); // "100.13 USDC" (rounded)
+     * ```
+     */
+    protected formatAmount(amount: bigint | string): string;
+}
+//# sourceMappingURL=BaseAdapter.d.ts.map

package/dist/adapters/BaseAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/BaseAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;;GAGG;AACH,eAAO,MAAM,8BAA8B,SAAS,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAiB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,cAAc,SAAU,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;GAUG;AACH,8BAAsB,WAAW;IAMnB,SAAS,CAAC,gBAAgB,EAAE,MAAM;IAL9C;;;;OAIG;gBACmB,gBAAgB,EAAE,MAAM;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAqDtD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAiCrE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM;IAwCjF;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,qBAAqB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM;IAsB/D;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAgCnE;;;;;;;;;OASG;IACH,SAAS,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAkCzE;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;CAoBxD"}

package/dist/adapters/BaseAdapter.js

@@ -0,0 +1,393 @@
+"use strict";
+/**
+ * BaseAdapter - Abstract base class for all adapter implementations
+ *
+ * Provides shared utility methods for parsing user-friendly inputs into
+ * protocol-level types. All adapters extend this class to ensure consistent
+ * behavior across the Three-Level API.
+ *
+ * Key Responsibilities:
+ * - Amount parsing (string → bigint with 6 decimals for USDC)
+ * - Address validation (0x-prefixed hex)
+ * - Deadline parsing ("+24h" → Unix timestamp)
+ * - User-friendly error messages
+ *
+ * @module adapters/BaseAdapter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAdapter = exports.ValidationError = exports.MAX_DEADLINE_DAYS = exports.MAX_DEADLINE_HOURS = exports.MIN_AMOUNT_WEI = exports.DEFAULT_DEADLINE_SECONDS = exports.MAX_DISPUTE_WINDOW_SECONDS = exports.MIN_DISPUTE_WINDOW_SECONDS = exports.DEFAULT_DISPUTE_WINDOW_SECONDS = void 0;
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Default dispute window in seconds (2 days).
+ * Used when no dispute window is specified in transaction parameters.
+ */
+exports.DEFAULT_DISPUTE_WINDOW_SECONDS = 172800;
+/**
+ * Minimum dispute window in seconds (1 hour).
+ * Ensures requesters have reasonable time to dispute.
+ *
+ * SECURITY: Prevents providers from setting windows too short
+ * to avoid dispute detection.
+ */
+exports.MIN_DISPUTE_WINDOW_SECONDS = 3600; // 1 hour
+/**
+ * Maximum dispute window in seconds (30 days).
+ * Prevents excessively long fund locks.
+ *
+ * SECURITY: Prevents DoS via indefinite fund locking.
+ */
+exports.MAX_DISPUTE_WINDOW_SECONDS = 30 * 24 * 3600; // 30 days
+/**
+ * Default deadline offset in seconds (24 hours).
+ * Used when no deadline is specified in transaction parameters.
+ */
+exports.DEFAULT_DEADLINE_SECONDS = 86400;
+/**
+ * Minimum transaction amount in USDC wei (6 decimals).
+ * $0.05 minimum per AGIRAILS protocol specification.
+ */
+exports.MIN_AMOUNT_WEI = 50000n; // $0.05 USDC
+/**
+ * Maximum deadline in hours (10 years).
+ * Prevents integer overflow in deadline calculations.
+ */
+exports.MAX_DEADLINE_HOURS = 87600; // 10 years
+/**
+ * Maximum deadline in days (10 years).
+ * Prevents integer overflow in deadline calculations.
+ */
+exports.MAX_DEADLINE_DAYS = 3650; // 10 years
+/**
+ * Custom error for validation failures.
+ *
+ * Thrown when user input is invalid (e.g., malformed address, negative amount).
+ * Provides descriptive error messages for end-user debugging.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid amount format: "abc". Expected number like "100" or "100.50"');
+ * ```
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Abstract base adapter with shared parsing utilities.
+ *
+ * Provides common functionality for all adapter implementations:
+ * - Amount parsing (USDC has 6 decimals)
+ * - Address validation
+ * - Deadline parsing (relative time or Unix timestamp)
+ * - Amount formatting
+ *
+ * @abstract
+ */
+class BaseAdapter {
+    /**
+     * Creates a new BaseAdapter instance.
+     *
+     * @param requesterAddress - The requester's Ethereum address
+     */
+    constructor(requesterAddress) {
+        this.requesterAddress = requesterAddress;
+    }
+    /**
+     * Parse user-friendly amount string to bigint (USDC has 6 decimals).
+     *
+     * Accepts multiple input formats:
+     * - "100" → 100_000_000n (100.00 USDC)
+     * - "100.50" → 100_500_000n (100.50 USDC)
+     * - "100 USDC" → 100_000_000n (strips currency suffix)
+     * - "$100" → 100_000_000n (strips $ prefix)
+     * - 100 (number) → 100_000_000n
+     *
+     * Rejects:
+     * - "abc" → throws ValidationError
+     * - "" → throws ValidationError
+     * - "-100" → throws ValidationError (negative amounts)
+     * - "100.1234567" → throws ValidationError (too many decimals)
+     *
+     * @param amount - Amount as string or number
+     * @returns Amount as bigint with 6 decimals
+     * @throws {ValidationError} If amount format is invalid
+     *
+     * @example
+     * ```typescript
+     * const amount = this.parseAmount("100.50"); // 100_500_000n
+     * const amount = this.parseAmount("100 USDC"); // 100_000_000n
+     * ```
+     */
+    parseAmount(amount) {
+        // Issue #3 Fix: Normalize input - handle all Unicode whitespace
+        // Converts all Unicode whitespace to regular spaces, then strip currency symbols
+        let normalized = String(amount)
+            .replace(/[\s\u00A0\u2000-\u200B\uFEFF]/g, ' ') // Replace all Unicode whitespace with regular space
+            .replace(/^[\$]/, '') // Strip leading $
+            .replace(/\s*(USDC|usdc)$/, '') // Strip trailing USDC
+            .replace(/,/g, '') // Strip thousands separators
+            .replace(/\s+/g, '') // Remove ALL whitespace (including normalized Unicode spaces)
+            .trim(); // Final trim for edge cases
+        // Check for negative
+        if (normalized.startsWith('-')) {
+            throw new ValidationError('Amount cannot be negative');
+        }
+        // Validate format (integer or decimal with up to 6 decimal places)
+        if (!/^\d+(\.\d{1,6})?$/.test(normalized)) {
+            throw new ValidationError(`Invalid amount format: "${amount}". Expected number like "100" or "100.50"`);
+        }
+        // Parse to bigint with 6 decimals
+        try {
+            const parts = normalized.split('.');
+            const wholePart = parts[0];
+            const decimalPart = (parts[1] || '').padEnd(6, '0'); // Pad to 6 decimals
+            const wholeAmount = BigInt(wholePart) * 1000000n;
+            const decimalAmount = BigInt(decimalPart);
+            const totalAmount = wholeAmount + decimalAmount;
+            // M1 Fix: Enforce minimum amount ($0.05 USDC = 50,000 wei)
+            if (totalAmount < exports.MIN_AMOUNT_WEI) {
+                throw new ValidationError(`Amount too small: "${amount}". Minimum transaction is $0.05 USDC`);
+            }
+            return totalAmount;
+        }
+        catch (error) {
+            // Re-throw ValidationError as-is
+            if (error instanceof ValidationError) {
+                throw error;
+            }
+            throw new ValidationError(`Failed to parse amount: "${amount}". Please use format like "100" or "100.50"`);
+        }
+    }
+    /**
+     * Validate Ethereum address format.
+     *
+     * Checks that address:
+     * - Is a string
+     * - Starts with "0x"
+     * - Is exactly 42 characters (0x + 40 hex chars)
+     * - Contains only valid hex characters
+     *
+     * Note: Does not validate checksum (EIP-55) in mock mode.
+     *
+     * @param address - Address to validate
+     * @param paramName - Parameter name for error message
+     * @returns Validated address (unchanged)
+     * @throws {ValidationError} If address format is invalid
+     *
+     * @example
+     * ```typescript
+     * const provider = this.validateAddress(params.to, 'to');
+     * ```
+     */
+    validateAddress(address, paramName) {
+        if (typeof address !== 'string') {
+            throw new ValidationError(`Invalid ${paramName} address: expected string, got ${typeof address}`);
+        }
+        // Check 0x prefix
+        if (!address.startsWith('0x')) {
+            throw new ValidationError(`Invalid ${paramName} address: "${address}". Expected 0x-prefixed hex string.`);
+        }
+        // Check length (0x + 40 hex chars = 42 total)
+        if (address.length !== 42) {
+            throw new ValidationError(`Invalid ${paramName} address: "${address}". Expected 42 characters (0x + 40 hex).`);
+        }
+        // Check hex format
+        if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+            throw new ValidationError(`Invalid ${paramName} address: "${address}". Contains invalid hex characters.`);
+        }
+        // Issue #2 Fix: Normalize to lowercase for consistency
+        // This prevents case-sensitivity issues when comparing addresses
+        return address.toLowerCase();
+    }
+    /**
+     * Parse deadline from relative time expression or Unix timestamp.
+     *
+     * Accepts multiple formats:
+     * - undefined → now + 24 hours (default)
+     * - 1734076400 (number) → passed through as Unix timestamp
+     * - "+1h" → now + 1 hour
+     * - "+24h" → now + 24 hours
+     * - "+7d" → now + 7 days
+     *
+     * Rejects:
+     * - "invalid" → throws ValidationError
+     * - "-24h" → throws ValidationError (negative time)
+     *
+     * @param deadline - Deadline as relative time string, Unix timestamp, or undefined
+     * @param currentTime - Current time in seconds (defaults to Date.now() / 1000)
+     * @returns Unix timestamp in seconds
+     * @throws {ValidationError} If deadline format is invalid
+     *
+     * @example
+     * ```typescript
+     * const deadline = this.parseDeadline("+24h"); // now + 86400
+     * const deadline = this.parseDeadline(1734076400); // 1734076400
+     * const deadline = this.parseDeadline(); // now + 86400 (default)
+     * ```
+     */
+    parseDeadline(deadline, currentTime) {
+        const now = currentTime ?? Math.floor(Date.now() / 1000);
+        if (deadline === undefined) {
+            // Default: 24 hours from now
+            return now + exports.DEFAULT_DEADLINE_SECONDS;
+        }
+        if (typeof deadline === 'number') {
+            return deadline;
+        }
+        // Parse relative time
+        const match = deadline.match(/^\+(\d+)(h|d)$/);
+        if (!match) {
+            throw new ValidationError(`Invalid deadline format: "${deadline}". Expected Unix timestamp or relative time (e.g., "+24h", "+7d")`);
+        }
+        const [, amountStr, unit] = match;
+        const amount = parseInt(amountStr, 10);
+        // H1 Fix: Add bounds check to prevent integer overflow
+        if (unit === 'h' && amount > exports.MAX_DEADLINE_HOURS) {
+            throw new ValidationError(`Deadline too far in future: "${deadline}". Maximum is 10 years (${exports.MAX_DEADLINE_HOURS}h)`);
+        }
+        if (unit === 'd' && amount > exports.MAX_DEADLINE_DAYS) {
+            throw new ValidationError(`Deadline too far in future: "${deadline}". Maximum is 10 years (${exports.MAX_DEADLINE_DAYS}d)`);
+        }
+        const multiplier = unit === 'h' ? 3600 : 86400;
+        return now + amount * multiplier;
+    }
+    /**
+     * Validate and normalize dispute window.
+     *
+     * SECURITY FIX (L-1): Enforces bounds on dispute window:
+     * - Minimum: 1 hour (prevents skipping disputes)
+     * - Maximum: 30 days (prevents indefinite fund locking)
+     *
+     * @param disputeWindow - Dispute window in seconds (undefined uses default)
+     * @returns Validated dispute window in seconds
+     * @throws {ValidationError} If window is outside allowed bounds
+     *
+     * @example
+     * ```typescript
+     * this.validateDisputeWindow(3600); // 1 hour - OK
+     * this.validateDisputeWindow(86400); // 1 day - OK
+     * this.validateDisputeWindow(100); // Too short - throws
+     * this.validateDisputeWindow(31 * 86400); // Too long - throws
+     * ```
+     */
+    validateDisputeWindow(disputeWindow) {
+        if (disputeWindow === undefined) {
+            return exports.DEFAULT_DISPUTE_WINDOW_SECONDS;
+        }
+        if (disputeWindow < exports.MIN_DISPUTE_WINDOW_SECONDS) {
+            throw new ValidationError(`Dispute window too short: ${disputeWindow} seconds. ` +
+                `Minimum is ${exports.MIN_DISPUTE_WINDOW_SECONDS} seconds (1 hour).`);
+        }
+        if (disputeWindow > exports.MAX_DISPUTE_WINDOW_SECONDS) {
+            throw new ValidationError(`Dispute window too long: ${disputeWindow} seconds. ` +
+                `Maximum is ${exports.MAX_DISPUTE_WINDOW_SECONDS} seconds (30 days).`);
+        }
+        return disputeWindow;
+    }
+    /**
+     * Validate bytes32 hex string format.
+     *
+     * SECURITY FIX (L-2): Validates that a string is a valid bytes32 hex.
+     * Used for transaction IDs, escrow IDs, attestation UIDs, etc.
+     *
+     * @param value - Value to validate
+     * @param paramName - Parameter name for error message
+     * @returns Validated bytes32 string (normalized to lowercase)
+     * @throws {ValidationError} If format is invalid
+     *
+     * @example
+     * ```typescript
+     * const txId = this.validateBytes32(id, 'transactionId');
+     * ```
+     */
+    validateBytes32(value, paramName) {
+        if (typeof value !== 'string') {
+            throw new ValidationError(`Invalid ${paramName}: expected string, got ${typeof value}`);
+        }
+        // Check 0x prefix
+        if (!value.startsWith('0x')) {
+            throw new ValidationError(`Invalid ${paramName}: "${value}". Expected 0x-prefixed bytes32 (66 characters total).`);
+        }
+        // Check length (0x + 64 hex chars = 66 total)
+        if (value.length !== 66) {
+            throw new ValidationError(`Invalid ${paramName}: "${value}". Expected 66 characters (0x + 64 hex), got ${value.length}.`);
+        }
+        // Check hex format
+        if (!/^0x[0-9a-fA-F]{64}$/.test(value)) {
+            throw new ValidationError(`Invalid ${paramName}: "${value}". Contains invalid hex characters.`);
+        }
+        // Normalize to lowercase
+        return value.toLowerCase();
+    }
+    /**
+     * Validate Unix timestamp is reasonable.
+     *
+     * SECURITY FIX (L-6): Validates timestamps to prevent overflow/underflow.
+     *
+     * @param timestamp - Unix timestamp in seconds
+     * @param paramName - Parameter name for error message
+     * @returns Validated timestamp
+     * @throws {ValidationError} If timestamp is invalid
+     */
+    validateTimestamp(timestamp, paramName) {
+        // Check it's a number
+        if (typeof timestamp !== 'number' || isNaN(timestamp)) {
+            throw new ValidationError(`Invalid ${paramName}: expected number, got ${typeof timestamp}`);
+        }
+        // Check it's positive
+        if (timestamp <= 0) {
+            throw new ValidationError(`Invalid ${paramName}: timestamp must be positive`);
+        }
+        // Check it's not in the past (with 1 minute buffer)
+        const now = Math.floor(Date.now() / 1000);
+        const oneMinuteAgo = now - 60;
+        // Only apply this check if it looks like a deadline/future timestamp
+        // (e.g., createdAt can be in the past)
+        // For now, just validate it's reasonable
+        // Check for overflow (year 3000 = ~32503680000)
+        const year3000 = 32503680000;
+        if (timestamp > year3000) {
+            throw new ValidationError(`Invalid ${paramName}: timestamp ${timestamp} is too far in the future (overflow prevention)`);
+        }
+        return timestamp;
+    }
+    /**
+     * Format bigint amount to human-readable string.
+     *
+     * Converts USDC wei (6 decimals) to formatted string with 2 decimal places.
+     * Uses proper rounding (round half up) for display purposes.
+     *
+     * @param amount - Amount as bigint (6 decimals) or string
+     * @returns Formatted string like "100.00 USDC"
+     *
+     * @example
+     * ```typescript
+     * this.formatAmount(100_000_000n); // "100.00 USDC"
+     * this.formatAmount(100_500_000n); // "100.50 USDC"
+     * this.formatAmount(100_126_000n); // "100.13 USDC" (rounded)
+     * ```
+     */
+    formatAmount(amount) {
+        const amountBigInt = typeof amount === 'string' ? BigInt(amount) : amount;
+        // Convert from 6 decimals to decimal string
+        const wholePart = amountBigInt / 1000000n;
+        const decimalPart = amountBigInt % 1000000n;
+        // M3 Fix: Proper rounding to 2 decimal places (round half up)
+        // decimalPart is 0-999999, we need to round to nearest 10000 (cents)
+        const decimalNum = Number(decimalPart);
+        const roundedCents = Math.round(decimalNum / 10000); // 6 decimals → 2 decimals
+        // Handle case where rounding causes overflow (e.g., 99.999999 → 100.00)
+        if (roundedCents >= 100) {
+            return `${wholePart + 1n}.00 USDC`;
+        }
+        const formattedDecimal = roundedCents.toString().padStart(2, '0');
+        return `${wholePart}.${formattedDecimal} USDC`;
+    }
+}
+exports.BaseAdapter = BaseAdapter;
+//# sourceMappingURL=BaseAdapter.js.map

package/dist/adapters/BaseAdapter.js.map

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