@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/utils/Helpers.d.ts

@@ -0,0 +1,453 @@
+/**
+ * Helpers - Common utility functions for ACTP SDK
+ *
+ * SECURITY FIX (L-7): Convenience methods for common operations
+ * to reduce boilerplate and prevent mistakes.
+ *
+ * @module utils/Helpers
+ */
+/**
+ * USDC amount utilities (6 decimal places)
+ */
+export declare const USDC: {
+    /**
+     * USDC decimals
+     */
+    DECIMALS: number;
+    /**
+     * Minimum transaction amount in USDC wei ($0.05)
+     */
+    MIN_AMOUNT_WEI: bigint;
+    /**
+     * Convert human-readable USDC amount to wei
+     *
+     * @param amount - Amount as string or number (e.g., "100.50")
+     * @returns Amount in USDC wei (6 decimals)
+     *
+     * @example
+     * ```typescript
+     * USDC.toWei("100") // 100_000_000n
+     * USDC.toWei("100.50") // 100_500_000n
+     * USDC.toWei(100) // 100_000_000n
+     * ```
+     */
+    toWei(amount: string | number): bigint;
+    /**
+     * Convert USDC wei to human-readable string
+     *
+     * SECURITY FIX (MEDIUM-6): Uses pure BigInt arithmetic to prevent precision loss
+     *
+     * @param weiAmount - Amount in USDC wei
+     * @param decimals - Number of decimal places to show (default: 2)
+     * @returns Formatted string (e.g., "100.50")
+     *
+     * @example
+     * ```typescript
+     * USDC.fromWei(100_500_000n) // "100.50"
+     * USDC.fromWei(100_000_000n) // "100.00"
+     * USDC.fromWei(100_126_000n, 4) // "100.1260"
+     * ```
+     */
+    fromWei(weiAmount: bigint | string, decimals?: number): string;
+    /**
+     * Format USDC amount with currency symbol
+     *
+     * @param weiAmount - Amount in USDC wei
+     * @returns Formatted string with USDC suffix (e.g., "100.50 USDC")
+     */
+    format(weiAmount: bigint | string): string;
+    /**
+     * Check if amount meets minimum transaction requirement
+     *
+     * @param weiAmount - Amount in USDC wei
+     * @returns true if amount >= $0.05
+     */
+    meetsMinimum(weiAmount: bigint | string): boolean;
+};
+/**
+ * Deadline utilities
+ */
+export declare const Deadline: {
+    /**
+     * Create deadline N hours from now
+     *
+     * @param hours - Number of hours from now
+     * @returns Unix timestamp in seconds
+     *
+     * @example
+     * ```typescript
+     * Deadline.hoursFromNow(24) // timestamp 24 hours from now
+     * ```
+     */
+    hoursFromNow(hours: number): number;
+    /**
+     * Create deadline N days from now
+     *
+     * @param days - Number of days from now
+     * @returns Unix timestamp in seconds
+     *
+     * @example
+     * ```typescript
+     * Deadline.daysFromNow(7) // timestamp 7 days from now
+     * ```
+     */
+    daysFromNow(days: number): number;
+    /**
+     * Create deadline at specific date
+     *
+     * @param date - Date object or ISO string
+     * @returns Unix timestamp in seconds
+     *
+     * @example
+     * ```typescript
+     * Deadline.at(new Date('2025-01-01'))
+     * Deadline.at('2025-01-01T00:00:00Z')
+     * ```
+     */
+    at(date: Date | string): number;
+    /**
+     * Check if deadline has passed
+     *
+     * @param deadline - Unix timestamp in seconds
+     * @returns true if deadline is in the past
+     */
+    isPast(deadline: number): boolean;
+    /**
+     * Get time remaining until deadline
+     *
+     * @param deadline - Unix timestamp in seconds
+     * @returns Time remaining in seconds (negative if past)
+     */
+    timeRemaining(deadline: number): number;
+    /**
+     * Format deadline as human-readable string
+     *
+     * @param deadline - Unix timestamp in seconds
+     * @returns Human-readable string (e.g., "in 2 hours", "expired 1 day ago")
+     */
+    format(deadline: number): string;
+};
+/**
+ * Address utilities
+ */
+export declare const Address: {
+    /**
+     * Normalize address to lowercase with 0x prefix
+     *
+     * @param address - Ethereum address
+     * @returns Normalized address
+     */
+    normalize(address: string): string;
+    /**
+     * Check if two addresses are the same (case-insensitive)
+     *
+     * @param a - First address
+     * @param b - Second address
+     * @returns true if addresses match
+     */
+    equals(a: string, b: string): boolean;
+    /**
+     * Truncate address for display
+     *
+     * @param address - Ethereum address
+     * @param chars - Characters to show on each side (default: 4)
+     * @returns Truncated address (e.g., "0x1234...5678")
+     */
+    truncate(address: string, chars?: number): string;
+    /**
+     * Check if string is valid Ethereum address format
+     *
+     * @param address - String to check
+     * @returns true if valid address format
+     */
+    isValid(address: string): boolean;
+    /**
+     * Check if address is zero address
+     *
+     * @param address - Ethereum address
+     * @returns true if zero address
+     */
+    isZero(address: string): boolean;
+};
+/**
+ * Bytes32 utilities
+ */
+export declare const Bytes32: {
+    /**
+     * Check if string is valid bytes32 format
+     *
+     * @param value - String to check
+     * @returns true if valid bytes32 format
+     */
+    isValid(value: string): boolean;
+    /**
+     * Normalize bytes32 to lowercase
+     *
+     * @param value - Bytes32 string
+     * @returns Normalized lowercase string
+     */
+    normalize(value: string): string;
+    /**
+     * Check if two bytes32 values are equal
+     *
+     * @param a - First value
+     * @param b - Second value
+     * @returns true if equal
+     */
+    equals(a: string, b: string): boolean;
+    /**
+     * Check if bytes32 is zero
+     *
+     * @param value - Bytes32 string
+     * @returns true if zero
+     */
+    isZero(value: string): boolean;
+    /**
+     * Create zero bytes32
+     *
+     * @returns Zero bytes32 string
+     */
+    zero(): string;
+    /**
+     * Truncate bytes32 for display
+     *
+     * @param value - Bytes32 string
+     * @param chars - Characters to show on each side (default: 6)
+     * @returns Truncated string (e.g., "0x123456...abcdef")
+     */
+    truncate(value: string, chars?: number): string;
+};
+/**
+ * State machine utilities
+ */
+export declare const State: {
+    /**
+     * Valid ACTP states
+     */
+    STATES: readonly ["INITIATED", "QUOTED", "COMMITTED", "IN_PROGRESS", "DELIVERED", "SETTLED", "DISPUTED", "CANCELLED"];
+    /**
+     * Terminal states (no further transitions)
+     */
+    TERMINAL: readonly ["SETTLED", "CANCELLED"];
+    /**
+     * Check if state is terminal
+     *
+     * @param state - State to check
+     * @returns true if terminal state
+     */
+    isTerminal(state: string): boolean;
+    /**
+     * Check if state is valid
+     *
+     * @param state - State to check
+     * @returns true if valid state
+     */
+    isValid(state: string): boolean;
+    /**
+     * Get valid next states from current state
+     *
+     * SECURITY FIX (CRITICAL-1): Must match ACTPKernel contract state machine exactly
+     * Per CLAUDE.md §Architecture Overview - ACTP Protocol State Machine
+     *
+     * @param currentState - Current state
+     * @returns Array of valid next states
+     */
+    validTransitions(currentState: string): string[];
+    /**
+     * Check if transition is valid
+     *
+     * @param from - Current state
+     * @param to - Target state
+     * @returns true if transition is valid
+     */
+    canTransition(from: string, to: string): boolean;
+};
+/**
+ * Dispute window utilities
+ */
+export declare const DisputeWindow: {
+    /**
+     * Default dispute window in seconds (2 days)
+     */
+    DEFAULT: number;
+    /**
+     * Minimum dispute window in seconds (1 hour)
+     */
+    MIN: number;
+    /**
+     * Maximum dispute window in seconds (30 days)
+     */
+    MAX: number;
+    /**
+     * Convert hours to seconds
+     */
+    hours(h: number): number;
+    /**
+     * Convert days to seconds
+     */
+    days(d: number): number;
+    /**
+     * Check if dispute window is still active
+     *
+     * @param completedAt - Completion timestamp
+     * @param windowSeconds - Dispute window in seconds
+     * @returns true if window is still active
+     */
+    isActive(completedAt: number, windowSeconds: number): boolean;
+    /**
+     * Get time remaining in dispute window
+     *
+     * @param completedAt - Completion timestamp
+     * @param windowSeconds - Dispute window in seconds
+     * @returns Seconds remaining (0 if expired)
+     */
+    remaining(completedAt: number, windowSeconds: number): number;
+};
+/**
+ * ============================================================================
+ * Convenience Wrappers for Common Operations
+ * ============================================================================
+ */
+/**
+ * Parse USDC amount string to wei (6 decimals)
+ *
+ * Convenience wrapper for USDC.toWei()
+ *
+ * @param amount - Amount in USDC (e.g., "100" or "0.50")
+ * @returns BigInt in wei (e.g., 100000000n for $100)
+ *
+ * @example
+ * ```typescript
+ * parseUSDC("100") // 100_000_000n
+ * parseUSDC("0.50") // 500_000n
+ * parseUSDC(100) // 100_000_000n
+ * ```
+ */
+export declare function parseUSDC(amount: string | number): bigint;
+/**
+ * Format USDC wei to human-readable string
+ *
+ * Convenience wrapper for USDC.fromWei()
+ *
+ * @param wei - Amount in wei (BigInt or string)
+ * @returns Formatted string (e.g., "100.00")
+ *
+ * @example
+ * ```typescript
+ * formatUSDC(100_000_000n) // "100.00"
+ * formatUSDC("100000000") // "100.00"
+ * formatUSDC(500_000n) // "0.50"
+ * ```
+ */
+export declare function formatUSDC(wei: bigint | string): string;
+/**
+ * Shorten Ethereum address for display
+ *
+ * Convenience wrapper for Address.truncate()
+ *
+ * @param address - Full Ethereum address
+ * @param chars - Characters to show on each side (default: 4)
+ * @returns Shortened address (e.g., "0x1234...abcd")
+ *
+ * @example
+ * ```typescript
+ * shortenAddress("0x1234567890123456789012345678901234567890") // "0x1234...7890"
+ * shortenAddress("0x1234567890123456789012345678901234567890", 6) // "0x123456...567890"
+ * ```
+ */
+export declare function shortenAddress(address: string, chars?: number): string;
+/**
+ * ============================================================================
+ * Service Metadata Utilities
+ *
+ * SECURITY FIX (CRITICAL): ACTPKernel expects bytes32 serviceHash, not raw strings.
+ * These utilities handle proper hashing and encoding of service metadata.
+ * ============================================================================
+ */
+/**
+ * Service metadata structure
+ */
+export interface ServiceMetadata {
+    service: string;
+    input?: unknown;
+    version?: string;
+    timestamp?: number;
+}
+/**
+ * Service metadata utilities for ACTP transactions
+ *
+ * SECURITY FIX (CRITICAL): The ACTPKernel contract expects a bytes32 serviceHash,
+ * not a raw JSON string. This utility properly hashes metadata before on-chain calls.
+ */
+export declare const ServiceHash: {
+    /**
+     * Create canonical JSON from service metadata
+     *
+     * SECURITY: Uses deterministic key ordering to ensure consistent hashes
+     *
+     * @param metadata - Service metadata object
+     * @returns Canonical JSON string
+     */
+    toCanonical(metadata: ServiceMetadata): string;
+    /**
+     * Hash service metadata to bytes32 using keccak256
+     *
+     * SECURITY FIX (CRITICAL): This is what should be passed to ACTPKernel.createTransaction()
+     *
+     * @param metadata - Service metadata (string or object)
+     * @returns bytes32 hash string (0x-prefixed, 64 hex chars)
+     *
+     * @example
+     * ```typescript
+     * const hash = ServiceHash.hash({ service: 'echo', input: 'hello' });
+     * // Returns: 0x1234...abcd (bytes32)
+     * ```
+     */
+    hash(metadata: ServiceMetadata | string): string;
+    /**
+     * Create service metadata from legacy format
+     *
+     * Parses the old "service:X;input:Y" format into structured metadata
+     *
+     * @param legacyFormat - Legacy service description string
+     * @returns Parsed ServiceMetadata or null if invalid
+     */
+    fromLegacy(legacyFormat: string): ServiceMetadata | null;
+    /**
+     * Extract service name from metadata hash (requires off-chain lookup)
+     *
+     * NOTE: The hash cannot be reversed. This is a helper for when you have
+     * both the hash and the original metadata stored off-chain.
+     *
+     * @param metadata - Original metadata
+     * @returns Service name
+     */
+    getServiceName(metadata: ServiceMetadata | string): string;
+    /**
+     * Validate bytes32 format
+     *
+     * @param value - Value to check
+     * @returns true if valid bytes32 format
+     */
+    isValidHash(value: string): boolean;
+    /**
+     * Zero hash (empty service metadata)
+     */
+    ZERO: string;
+};
+/**
+ * Hash service description for on-chain storage
+ *
+ * Convenience function for ServiceHash.hash()
+ *
+ * @param service - Service name
+ * @param input - Input data (optional)
+ * @returns bytes32 hash
+ *
+ * @example
+ * ```typescript
+ * const hash = hashServiceMetadata('echo', { text: 'hello' });
+ * ```
+ */
+export declare function hashServiceMetadata(service: string, input?: unknown): string;
+//# sourceMappingURL=Helpers.d.ts.map

package/dist/utils/Helpers.d.ts.map

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