@agirails/sdk 2.0.4 → 2.2.0

package/dist/storage/ArweaveClient.js

@@ -0,0 +1,761 @@
+"use strict";
+/**
+ * ArweaveClient - Permanent Storage via Irys (AIP-7 §4.3)
+ *
+ * Provides permanent storage on Arweave via Irys (formerly Bundlr).
+ * Used for archiving settled transaction bundles for compliance.
+ *
+ * Security Features (Post-Audit):
+ * - Gateway URL whitelist (SSRF protection)
+ * - Download size limits (DoS protection)
+ * - Credential sanitization in errors
+ * - Retry with exponential backoff
+ * - Circuit breaker for gateway health tracking
+ *
+ * @module storage/ArweaveClient
+ *
+ * Key Principle: Arweave-First Write Order
+ * 1. Write to Arweave FIRST -> Get Arweave TX ID
+ * 2. THEN anchor TX ID on-chain
+ *
+ * @see AIP-7 §4.1 for invariant explanation
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArweaveClient = void 0;
+const sdk_1 = __importDefault(require("@irys/sdk"));
+const errors_1 = require("../errors");
+const types_1 = require("./types");
+const validation_1 = require("../utils/validation");
+const retry_1 = require("../utils/retry");
+const circuitBreaker_1 = require("../utils/circuitBreaker");
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_CURRENCY = 'base-eth';
+const DEFAULT_NETWORK = 'mainnet';
+const DEFAULT_TIMEOUT = 60000; // 60 seconds
+const DEFAULT_MAX_DOWNLOAD_SIZE = 10 * 1024 * 1024; // 10MB for archive bundles
+const ARWEAVE_GATEWAY = 'https://arweave.net/';
+// Minimum funding amount (to avoid dust)
+const MIN_FUNDING_AMOUNT = 1000n; // 1000 wei minimum
+// ============================================================================
+// ArweaveClient Class
+// ============================================================================
+/**
+ * ArweaveClient - Permanent storage on Arweave via Irys
+ *
+ * Used for:
+ * - Archiving settled transaction bundles (compliance)
+ * - 7-year retention requirement (Arweave guarantees 200+ years)
+ *
+ * IMPORTANT: Uses Base ETH for payments (no bridging required)
+ *
+ * @example
+ * ```typescript
+ * const client = await ArweaveClient.create({
+ *   privateKey: process.env.ARCHIVE_UPLOADER_KEY!,
+ *   rpcUrl: process.env.BASE_RPC_URL!
+ * });
+ *
+ * // Check balance
+ * const balance = await client.getBalance();
+ * console.log('Irys balance:', balance);
+ *
+ * // Fund if needed
+ * if (balance < 10000n) {
+ *   await client.fund(100000n);
+ * }
+ *
+ * // Upload archive bundle
+ * const result = await client.uploadBundle(archiveBundle);
+ * console.log('Arweave TX ID:', result.txId);
+ *
+ * // Download archive bundle
+ * const downloaded = await client.downloadBundle(result.txId);
+ * ```
+ */
+class ArweaveClient {
+    /**
+     * Get initialized Irys instance (throws if not initialized)
+     */
+    get irys() {
+        if (!this.initialized || !this._irys) {
+            throw new errors_1.StorageError('operation', 'ArweaveClient not initialized. Call create() first.');
+        }
+        return this._irys;
+    }
+    /**
+     * Private constructor - use ArweaveClient.create() factory
+     */
+    constructor(config) {
+        this._irys = null;
+        this.initialized = false;
+        // Validate required config
+        if (!config.privateKey) {
+            throw new errors_1.ValidationError('privateKey', 'Private key is required for Arweave uploads');
+        }
+        if (!config.rpcUrl) {
+            throw new errors_1.ValidationError('rpcUrl', 'RPC URL is required for payment chain');
+        }
+        // P0-1: Validate default gateway URL against whitelist
+        (0, validation_1.validateGatewayURL)(ARWEAVE_GATEWAY, validation_1.ALLOWED_ARWEAVE_GATEWAYS, 'gatewayUrl');
+        this.config = {
+            privateKey: config.privateKey,
+            rpcUrl: config.rpcUrl,
+            currency: config.currency || DEFAULT_CURRENCY,
+            network: config.network || DEFAULT_NETWORK,
+            timeout: config.timeout || DEFAULT_TIMEOUT
+        };
+        // P1-1: DoS protection
+        this.maxDownloadSize = DEFAULT_MAX_DOWNLOAD_SIZE;
+        // P1-2: Default retry options
+        this.retryOptions = {
+            maxAttempts: 3,
+            initialDelayMs: 2000,
+            maxDelayMs: 30000,
+            backoffMultiplier: 2
+        };
+        // Circuit breaker for gateway health tracking
+        this.circuitBreakerEnabled = config.circuitBreaker?.enabled !== false;
+        if (this.circuitBreakerEnabled) {
+            this.circuitBreaker = new circuitBreaker_1.GatewayCircuitBreaker({
+                failureThreshold: config.circuitBreaker?.failureThreshold,
+                resetTimeoutMs: config.circuitBreaker?.resetTimeoutMs,
+                failureWindowMs: config.circuitBreaker?.failureWindowMs,
+                successThreshold: config.circuitBreaker?.successThreshold
+            });
+        }
+        else {
+            this.circuitBreaker = null;
+        }
+    }
+    /**
+     * Create and initialize ArweaveClient
+     *
+     * @param config - Arweave configuration
+     * @returns Initialized ArweaveClient
+     *
+     * @example
+     * ```typescript
+     * const client = await ArweaveClient.create({
+     *   privateKey: process.env.ARCHIVE_UPLOADER_KEY!,
+     *   rpcUrl: 'https://mainnet.base.org'
+     * });
+     * ```
+     */
+    static async create(config) {
+        const client = new ArweaveClient(config);
+        await client.initialize();
+        return client;
+    }
+    /**
+     * Initialize Irys SDK connection
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            this._irys = new sdk_1.default({
+                network: this.config.network,
+                token: this.config.currency,
+                key: this.config.privateKey,
+                config: {
+                    providerUrl: this.config.rpcUrl
+                }
+            });
+            // Connect to Irys node
+            await this._irys.ready();
+            this.initialized = true;
+        }
+        catch (error) {
+            // P0-2: Sanitize error message (may contain credentials)
+            throw new errors_1.StorageError('initialization', `Failed to initialize Irys client: ${(0, validation_1.sanitizeErrorMessage)(error)}`, { currency: this.config.currency, network: this.config.network });
+        }
+    }
+    // ==========================================================================
+    // Funding Methods
+    // ==========================================================================
+    /**
+     * Fund the Irys node (required before uploading)
+     *
+     * @param amount - Amount to fund in payment currency (wei for ETH)
+     * @throws {ValidationError} If amount is invalid
+     * @throws {StorageError} If funding fails
+     *
+     * @example
+     * ```typescript
+     * // Fund with 0.001 ETH (1e15 wei)
+     * await client.fund(1000000000000000n);
+     * ```
+     */
+    async fund(amount) {
+        if (amount < MIN_FUNDING_AMOUNT) {
+            throw new errors_1.ValidationError('amount', `Funding amount too small. Minimum: ${MIN_FUNDING_AMOUNT} wei`);
+        }
+        try {
+            await this.withTimeout(this.irys.fund(amount), this.config.timeout, 'fund');
+        }
+        catch (error) {
+            if (error instanceof errors_1.ArweaveTimeoutError)
+                throw error;
+            // P0-2: Sanitize error message (may contain credentials)
+            throw new errors_1.StorageError('funding', `Failed to fund Irys: ${(0, validation_1.sanitizeErrorMessage)(error)}`, {
+                amount: amount.toString(),
+                currency: this.config.currency
+            });
+        }
+    }
+    /**
+     * Get current Irys balance
+     *
+     * @returns Balance in payment currency (wei for ETH)
+     *
+     * @example
+     * ```typescript
+     * const balance = await client.getBalance();
+     * console.log('Balance:', balance, 'wei');
+     * ```
+     */
+    async getBalance() {
+        try {
+            const balance = await this.irys.getLoadedBalance();
+            return BigInt(balance.toString());
+        }
+        catch (error) {
+            // P0-2: Sanitize error message
+            throw new errors_1.StorageError('balance', `Failed to get Irys balance: ${(0, validation_1.sanitizeErrorMessage)(error)}`);
+        }
+    }
+    /**
+     * Estimate cost of uploading data
+     *
+     * @param sizeBytes - Size of data to upload in bytes
+     * @returns Cost in payment currency (wei for ETH)
+     *
+     * @example
+     * ```typescript
+     * const cost = await client.estimateCost(50 * 1024); // 50KB
+     * console.log('Upload cost:', cost, 'wei');
+     * ```
+     */
+    async estimateCost(sizeBytes) {
+        if (sizeBytes <= 0) {
+            throw new errors_1.ValidationError('sizeBytes', 'Size must be positive');
+        }
+        try {
+            const price = await this.irys.getPrice(sizeBytes);
+            return BigInt(price.toString());
+        }
+        catch (error) {
+            // P0-2: Sanitize error message
+            throw new errors_1.StorageError('estimate', `Failed to estimate cost: ${(0, validation_1.sanitizeErrorMessage)(error)}`, {
+                sizeBytes
+            });
+        }
+    }
+    // ==========================================================================
+    // Upload Methods
+    // ==========================================================================
+    /**
+     * Upload archive bundle to Arweave (permanent storage)
+     *
+     * IMPORTANT: This is the first step in the archive flow.
+     * After getting the TX ID, anchor it on-chain via ArchiveTreasury.anchorArchive()
+     *
+     * @param bundle - Archive bundle to upload
+     * @returns Upload result with Arweave TX ID
+     * @throws {InsufficientBalanceError} If Irys balance is too low
+     * @throws {ArweaveUploadError} If upload fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.uploadBundle(bundle);
+     * console.log('Arweave TX ID:', result.txId);
+     *
+     * // Then anchor on-chain
+     * await archiveTreasury.anchorArchive(bundle.txId, result.txId);
+     * ```
+     */
+    async uploadBundle(bundle) {
+        // Validate bundle
+        this.validateBundle(bundle);
+        // Serialize bundle
+        const jsonString = JSON.stringify(bundle);
+        const buffer = Buffer.from(jsonString, 'utf-8');
+        // Check balance
+        const cost = await this.estimateCost(buffer.length);
+        const balance = await this.getBalance();
+        if (balance < cost) {
+            throw new errors_1.InsufficientBalanceError(cost.toString(), balance.toString(), this.config.currency.toUpperCase());
+        }
+        try {
+            // Upload with tags for discoverability
+            const tx = await this.withTimeout(this.irys.upload(buffer, {
+                tags: [
+                    { name: 'Content-Type', value: 'application/json' },
+                    { name: 'Protocol', value: 'AGIRAILS' },
+                    { name: 'Version', value: bundle.protocolVersion },
+                    { name: 'Schema', value: bundle.archiveSchemaVersion },
+                    { name: 'Type', value: bundle.type },
+                    { name: 'ChainId', value: bundle.chainId.toString() },
+                    { name: 'TxId', value: bundle.txId }
+                ]
+            }), this.config.timeout, 'upload');
+            return {
+                txId: tx.id,
+                size: buffer.length,
+                uploadedAt: new Date(),
+                cost: cost.toString()
+            };
+        }
+        catch (error) {
+            if (error instanceof errors_1.ArweaveTimeoutError)
+                throw error;
+            if (error instanceof errors_1.InsufficientBalanceError)
+                throw error;
+            throw new errors_1.ArweaveUploadError(error.message || 'Upload failed', {
+                bundleTxId: bundle.txId,
+                size: buffer.length
+            });
+        }
+    }
+    /**
+     * Upload arbitrary JSON to Arweave
+     *
+     * For general-purpose permanent storage (not archive bundles).
+     *
+     * @param data - JSON data to upload
+     * @param tags - Optional tags for discoverability
+     * @returns Upload result with Arweave TX ID
+     */
+    async uploadJSON(data, tags) {
+        const jsonString = JSON.stringify(data);
+        const buffer = Buffer.from(jsonString, 'utf-8');
+        // Check balance
+        const cost = await this.estimateCost(buffer.length);
+        const balance = await this.getBalance();
+        if (balance < cost) {
+            throw new errors_1.InsufficientBalanceError(cost.toString(), balance.toString(), this.config.currency.toUpperCase());
+        }
+        try {
+            const defaultTags = [
+                { name: 'Content-Type', value: 'application/json' },
+                { name: 'Protocol', value: 'AGIRAILS' }
+            ];
+            const tx = await this.withTimeout(this.irys.upload(buffer, {
+                tags: tags ? [...defaultTags, ...tags] : defaultTags
+            }), this.config.timeout, 'upload');
+            return {
+                txId: tx.id,
+                size: buffer.length,
+                uploadedAt: new Date(),
+                cost: cost.toString()
+            };
+        }
+        catch (error) {
+            if (error instanceof errors_1.ArweaveTimeoutError)
+                throw error;
+            if (error instanceof errors_1.InsufficientBalanceError)
+                throw error;
+            throw new errors_1.ArweaveUploadError(error.message || 'JSON upload failed', {
+                size: buffer.length
+            });
+        }
+    }
+    // ==========================================================================
+    // Download Methods
+    // ==========================================================================
+    /**
+     * Download archive bundle from Arweave
+     *
+     * Security Features:
+     * - Size limit enforcement (P1-1: DoS protection)
+     * - Retry with exponential backoff (P1-2)
+     * - Centralized TX ID validation (P1-3)
+     * - Credential sanitization in errors (P0-2)
+     *
+     * @param txId - Arweave transaction ID
+     * @returns Downloaded archive bundle
+     * @throws {InvalidArweaveTxIdError} If TX ID format is invalid
+     * @throws {FileSizeLimitExceededError} If content exceeds size limit
+     * @throws {ArweaveDownloadError} If download fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.downloadBundle('h7Xk2...');
+     * console.log('Bundle:', result.data);
+     * ```
+     */
+    async downloadBundle(txId) {
+        // P1-3: Use centralized TX ID validation
+        (0, validation_1.validateArweaveTxId)(txId);
+        const url = `${ARWEAVE_GATEWAY}${txId}`;
+        // Circuit breaker: check gateway health before attempting download
+        if (this.circuitBreaker && !this.circuitBreaker.isHealthy(ARWEAVE_GATEWAY)) {
+            const state = this.circuitBreaker.getState(ARWEAVE_GATEWAY);
+            const failures = this.circuitBreaker.getFailureCount(ARWEAVE_GATEWAY);
+            throw new errors_1.ArweaveDownloadError(txId, `Gateway circuit breaker OPEN for ${ARWEAVE_GATEWAY}. ` +
+                `State: ${state}, Failures: ${failures}. ` +
+                `Please wait for cooldown period before retrying.`);
+        }
+        // P1-2: Wrap in retry logic
+        return (0, retry_1.withRetry)(async () => {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+            try {
+                const response = await fetch(url, {
+                    signal: controller.signal,
+                    headers: { 'Accept': 'application/json' }
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    throw new errors_1.ArweaveDownloadError(txId, `HTTP ${response.status}: ${response.statusText}`);
+                }
+                // P1-1: Check Content-Length header before downloading
+                const contentLength = response.headers.get('content-length');
+                if (contentLength && parseInt(contentLength, 10) > this.maxDownloadSize) {
+                    throw new errors_1.FileSizeLimitExceededError(parseInt(contentLength, 10), this.maxDownloadSize);
+                }
+                // P1-1: Stream response with size limit enforcement
+                const reader = response.body?.getReader();
+                if (!reader) {
+                    throw new errors_1.ArweaveDownloadError(txId, 'No response body');
+                }
+                const chunks = [];
+                let totalSize = 0;
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    totalSize += value.length;
+                    // P1-1: Enforce size limit during streaming
+                    if (totalSize > this.maxDownloadSize) {
+                        reader.cancel();
+                        throw new errors_1.FileSizeLimitExceededError(totalSize, this.maxDownloadSize);
+                    }
+                    chunks.push(value);
+                }
+                // Combine chunks into text
+                const decoder = new TextDecoder();
+                const text = chunks.map(chunk => decoder.decode(chunk, { stream: true })).join('') +
+                    decoder.decode();
+                const data = JSON.parse(text);
+                // Validate it's actually an archive bundle
+                if (data.type !== types_1.ARCHIVE_BUNDLE_TYPE) {
+                    throw new errors_1.ArweaveDownloadError(txId, `Invalid bundle type: ${data.type}. Expected: ${types_1.ARCHIVE_BUNDLE_TYPE}`);
+                }
+                // Circuit breaker: record success
+                this.circuitBreaker?.recordSuccess(ARWEAVE_GATEWAY);
+                return {
+                    data,
+                    size: totalSize,
+                    downloadedAt: new Date()
+                };
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                // Circuit breaker: record failure only for gateway issues (not content errors)
+                if (this.isGatewayFailure(error)) {
+                    this.circuitBreaker?.recordFailure(ARWEAVE_GATEWAY);
+                }
+                if (error instanceof errors_1.ArweaveDownloadError)
+                    throw error;
+                if (error instanceof errors_1.FileSizeLimitExceededError)
+                    throw error;
+                if (error.name === 'AbortError') {
+                    throw new errors_1.ArweaveTimeoutError('download', this.config.timeout);
+                }
+                if (error instanceof SyntaxError) {
+                    throw new errors_1.ArweaveDownloadError(txId, 'Invalid JSON content');
+                }
+                // P0-2: Sanitize error message
+                throw new errors_1.ArweaveDownloadError(txId, (0, validation_1.sanitizeErrorMessage)(error));
+            }
+        }, this.retryOptions);
+    }
+    /**
+     * Download arbitrary JSON from Arweave
+     *
+     * Security Features:
+     * - Size limit enforcement (P1-1: DoS protection)
+     * - Retry with exponential backoff (P1-2)
+     * - Centralized TX ID validation (P1-3)
+     *
+     * @param txId - Arweave transaction ID
+     * @returns Downloaded JSON data
+     */
+    async downloadJSON(txId) {
+        // P1-3: Use centralized TX ID validation
+        (0, validation_1.validateArweaveTxId)(txId);
+        const url = `${ARWEAVE_GATEWAY}${txId}`;
+        // Circuit breaker: check gateway health before attempting download
+        if (this.circuitBreaker && !this.circuitBreaker.isHealthy(ARWEAVE_GATEWAY)) {
+            const state = this.circuitBreaker.getState(ARWEAVE_GATEWAY);
+            const failures = this.circuitBreaker.getFailureCount(ARWEAVE_GATEWAY);
+            throw new errors_1.ArweaveDownloadError(txId, `Gateway circuit breaker OPEN for ${ARWEAVE_GATEWAY}. ` +
+                `State: ${state}, Failures: ${failures}. ` +
+                `Please wait for cooldown period before retrying.`);
+        }
+        // P1-2: Wrap in retry logic
+        return (0, retry_1.withRetry)(async () => {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+            try {
+                const response = await fetch(url, {
+                    signal: controller.signal,
+                    headers: { 'Accept': 'application/json' }
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    throw new errors_1.ArweaveDownloadError(txId, `HTTP ${response.status}: ${response.statusText}`);
+                }
+                // P1-1: Check Content-Length header before downloading
+                const contentLength = response.headers.get('content-length');
+                if (contentLength && parseInt(contentLength, 10) > this.maxDownloadSize) {
+                    throw new errors_1.FileSizeLimitExceededError(parseInt(contentLength, 10), this.maxDownloadSize);
+                }
+                // P1-1: Stream response with size limit enforcement
+                const reader = response.body?.getReader();
+                if (!reader) {
+                    throw new errors_1.ArweaveDownloadError(txId, 'No response body');
+                }
+                const chunks = [];
+                let totalSize = 0;
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    totalSize += value.length;
+                    // P1-1: Enforce size limit during streaming
+                    if (totalSize > this.maxDownloadSize) {
+                        reader.cancel();
+                        throw new errors_1.FileSizeLimitExceededError(totalSize, this.maxDownloadSize);
+                    }
+                    chunks.push(value);
+                }
+                // Combine chunks into text
+                const decoder = new TextDecoder();
+                const text = chunks.map(chunk => decoder.decode(chunk, { stream: true })).join('') +
+                    decoder.decode();
+                const data = JSON.parse(text);
+                // Circuit breaker: record success
+                this.circuitBreaker?.recordSuccess(ARWEAVE_GATEWAY);
+                return {
+                    data,
+                    size: totalSize,
+                    downloadedAt: new Date()
+                };
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                // Circuit breaker: record failure only for gateway issues (not content errors)
+                if (this.isGatewayFailure(error)) {
+                    this.circuitBreaker?.recordFailure(ARWEAVE_GATEWAY);
+                }
+                if (error instanceof errors_1.ArweaveDownloadError)
+                    throw error;
+                if (error instanceof errors_1.FileSizeLimitExceededError)
+                    throw error;
+                if (error.name === 'AbortError') {
+                    throw new errors_1.ArweaveTimeoutError('download', this.config.timeout);
+                }
+                if (error instanceof SyntaxError) {
+                    throw new errors_1.ArweaveDownloadError(txId, 'Invalid JSON content');
+                }
+                // P0-2: Sanitize error message
+                throw new errors_1.ArweaveDownloadError(txId, (0, validation_1.sanitizeErrorMessage)(error));
+            }
+        }, this.retryOptions);
+    }
+    /**
+     * Check if content exists on Arweave
+     *
+     * @param txId - Arweave transaction ID
+     * @returns True if content exists
+     */
+    async exists(txId) {
+        // P1-3: Use centralized TX ID validation
+        (0, validation_1.validateArweaveTxId)(txId);
+        const url = `${ARWEAVE_GATEWAY}${txId}`;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+            const response = await fetch(url, {
+                method: 'HEAD',
+                signal: controller.signal
+            });
+            clearTimeout(timeoutId);
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ==========================================================================
+    // Getters
+    // ==========================================================================
+    /**
+     * Get configured currency
+     */
+    getCurrency() {
+        return this.config.currency;
+    }
+    /**
+     * Get configured network
+     */
+    getNetwork() {
+        return this.config.network;
+    }
+    /**
+     * Get wallet address
+     */
+    async getAddress() {
+        return this.irys.address;
+    }
+    // ==========================================================================
+    // Private Methods
+    // ==========================================================================
+    /**
+     * Validate archive bundle structure
+     */
+    validateBundle(bundle) {
+        if (!bundle) {
+            throw new errors_1.ValidationError('bundle', 'Archive bundle is required');
+        }
+        if (bundle.type !== types_1.ARCHIVE_BUNDLE_TYPE) {
+            throw new errors_1.ValidationError('bundle.type', `Invalid bundle type: ${bundle.type}. Expected: ${types_1.ARCHIVE_BUNDLE_TYPE}`);
+        }
+        if (!bundle.txId || !/^0x[a-fA-F0-9]{64}$/.test(bundle.txId)) {
+            throw new errors_1.ValidationError('bundle.txId', 'Invalid transaction ID format');
+        }
+        if (![8453, 84532].includes(bundle.chainId)) {
+            throw new errors_1.ValidationError('bundle.chainId', `Invalid chain ID: ${bundle.chainId}. Expected 8453 or 84532`);
+        }
+        if (!bundle.participants?.requester || !bundle.participants?.provider) {
+            throw new errors_1.ValidationError('bundle.participants', 'Both requester and provider required');
+        }
+        if (!bundle.references?.requestCID || !bundle.references?.deliveryCID) {
+            throw new errors_1.ValidationError('bundle.references', 'Both requestCID and deliveryCID required');
+        }
+        if (!bundle.hashes?.requestHash || !bundle.hashes?.deliveryHash || !bundle.hashes?.serviceHash) {
+            throw new errors_1.ValidationError('bundle.hashes', 'All hashes required');
+        }
+        if (!bundle.settlement) {
+            throw new errors_1.ValidationError('bundle.settlement', 'Settlement info required');
+        }
+    }
+    /**
+     * Wrap promise with timeout
+     */
+    async withTimeout(promise, timeoutMs, operation) {
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+                reject(new errors_1.ArweaveTimeoutError(operation, timeoutMs));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([promise, timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Determine if an error represents a gateway failure vs content-specific error
+     *
+     * Gateway failures (should trigger circuit breaker):
+     * - 5xx HTTP errors (server errors)
+     * - Network timeouts
+     * - Connection refused
+     * - DNS resolution failures
+     *
+     * Content-specific errors (should NOT trigger circuit breaker):
+     * - 404 (content not found - not gateway's fault)
+     * - 400 (bad request - client's fault)
+     * - SyntaxError (invalid JSON - content issue)
+     * - Invalid bundle type (content validation failed)
+     */
+    isGatewayFailure(error) {
+        // Network-level errors are always gateway failures
+        if (error.name === 'AbortError')
+            return true; // Timeout
+        if (error.code === 'ECONNREFUSED')
+            return true;
+        if (error.code === 'ENOTFOUND')
+            return true;
+        if (error.code === 'ETIMEDOUT')
+            return true;
+        // ArweaveTimeoutError is a gateway failure
+        if (error instanceof errors_1.ArweaveTimeoutError)
+            return true;
+        // Content-specific errors are NOT gateway failures
+        if (error instanceof SyntaxError)
+            return false; // Invalid JSON
+        if (error instanceof errors_1.FileSizeLimitExceededError)
+            return false;
+        // Check for HTTP status codes in ArweaveDownloadError
+        if (error instanceof errors_1.ArweaveDownloadError) {
+            const message = error.message || '';
+            // 5xx errors are gateway failures
+            if (/HTTP 5\d{2}/.test(message))
+                return true;
+            // 4xx errors are NOT gateway failures (content/client issues)
+            if (/HTTP 4\d{2}/.test(message))
+                return false;
+            // "Invalid bundle type" is content validation failure
+            if (message.includes('Invalid bundle type'))
+                return false;
+            // "Invalid JSON content" is content error
+            if (message.includes('Invalid JSON'))
+                return false;
+            // Default: treat unknown ArweaveDownloadError as potential gateway issue
+            return true;
+        }
+        // Generic errors (TypeError, etc.) could be network issues
+        return true;
+    }
+    // ==========================================================================
+    // Circuit Breaker Methods
+    // ==========================================================================
+    /**
+     * Get circuit breaker status for Arweave gateway
+     *
+     * @returns Circuit breaker status or null if disabled
+     *
+     * @example
+     * ```typescript
+     * const status = client.getCircuitBreakerStatus();
+     * if (status && status.state === 'OPEN') {
+     *   console.log('Gateway unhealthy, failures:', status.failures);
+     * }
+     * ```
+     */
+    getCircuitBreakerStatus() {
+        if (!this.circuitBreaker)
+            return null;
+        return {
+            state: this.circuitBreaker.getState(ARWEAVE_GATEWAY),
+            failures: this.circuitBreaker.getFailureCount(ARWEAVE_GATEWAY)
+        };
+    }
+    /**
+     * Reset circuit breaker for Arweave gateway
+     *
+     * Use with caution - only reset when you're confident the gateway is healthy.
+     * Useful for testing or after manual verification.
+     *
+     * @example
+     * ```typescript
+     * client.resetCircuitBreaker();
+     * ```
+     */
+    resetCircuitBreaker() {
+        this.circuitBreaker?.reset(ARWEAVE_GATEWAY);
+    }
+}
+exports.ArweaveClient = ArweaveClient;
+//# sourceMappingURL=ArweaveClient.js.map