@agirails/sdk 2.0.3 → 2.2.0

package/dist/storage/ArweaveClient.d.ts

@@ -0,0 +1,271 @@
+/**
+ * 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
+ */
+import { ArweaveConfig, IrysCurrency, IrysNetwork, ArchiveBundle, ArweaveUploadResult, DownloadResult } from './types';
+/**
+ * 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);
+ * ```
+ */
+export declare class ArweaveClient {
+    private _irys;
+    private readonly config;
+    private readonly maxDownloadSize;
+    private readonly retryOptions;
+    private readonly circuitBreaker;
+    private readonly circuitBreakerEnabled;
+    private initialized;
+    /**
+     * Get initialized Irys instance (throws if not initialized)
+     */
+    private get irys();
+    /**
+     * Private constructor - use ArweaveClient.create() factory
+     */
+    private constructor();
+    /**
+     * 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 create(config: ArweaveConfig): Promise<ArweaveClient>;
+    /**
+     * Initialize Irys SDK connection
+     */
+    private initialize;
+    /**
+     * 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);
+     * ```
+     */
+    fund(amount: bigint): Promise<void>;
+    /**
+     * Get current Irys balance
+     *
+     * @returns Balance in payment currency (wei for ETH)
+     *
+     * @example
+     * ```typescript
+     * const balance = await client.getBalance();
+     * console.log('Balance:', balance, 'wei');
+     * ```
+     */
+    getBalance(): Promise<bigint>;
+    /**
+     * 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');
+     * ```
+     */
+    estimateCost(sizeBytes: number): Promise<bigint>;
+    /**
+     * 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);
+     * ```
+     */
+    uploadBundle(bundle: ArchiveBundle): Promise<ArweaveUploadResult>;
+    /**
+     * 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
+     */
+    uploadJSON(data: unknown, tags?: Array<{
+        name: string;
+        value: string;
+    }>): Promise<ArweaveUploadResult>;
+    /**
+     * 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);
+     * ```
+     */
+    downloadBundle(txId: string): Promise<DownloadResult<ArchiveBundle>>;
+    /**
+     * 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
+     */
+    downloadJSON<T = unknown>(txId: string): Promise<DownloadResult<T>>;
+    /**
+     * Check if content exists on Arweave
+     *
+     * @param txId - Arweave transaction ID
+     * @returns True if content exists
+     */
+    exists(txId: string): Promise<boolean>;
+    /**
+     * Get configured currency
+     */
+    getCurrency(): IrysCurrency;
+    /**
+     * Get configured network
+     */
+    getNetwork(): IrysNetwork;
+    /**
+     * Get wallet address
+     */
+    getAddress(): Promise<string>;
+    /**
+     * Validate archive bundle structure
+     */
+    private validateBundle;
+    /**
+     * Wrap promise with timeout
+     */
+    private withTimeout;
+    /**
+     * 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)
+     */
+    private isGatewayFailure;
+    /**
+     * 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(): {
+        state: string;
+        failures: number;
+    } | null;
+    /**
+     * 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(): void;
+}
+//# sourceMappingURL=ArweaveClient.d.ts.map

package/dist/storage/ArweaveClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArweaveClient.d.ts","sourceRoot":"","sources":["../../src/storage/ArweaveClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAYH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,cAAc,EAEf,MAAM,SAAS,CAAC;AA8BjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkD;IACzE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+B;IAC9D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAU;IAChD,OAAO,CAAC,WAAW,CAAS;IAE5B;;OAEG;IACH,OAAO,KAAK,IAAI,GAKf;IAED;;OAEG;IACH,OAAO;IA6CP;;;;;;;;;;;;;OAaG;WACU,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAMlE;;OAEG;YACW,UAAU;IA+BxB;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BzC;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAYnC;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBtD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAyDvE;;;;;;;;OAQG;IACG,UAAU,CACd,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAC5C,OAAO,CAAC,mBAAmB,CAAC;IAoD/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IA0H1E;;;;;;;;;;OAUG;IACG,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAkHzE;;;;;OAKG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B5C;;OAEG;IACH,WAAW,IAAI,YAAY;IAI3B;;OAEG;IACH,UAAU,IAAI,WAAW;IAIzB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAUnC;;OAEG;IACH,OAAO,CAAC,cAAc;IAwCtB;;OAEG;YACW,WAAW;IAoBzB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,gBAAgB;IAqCxB;;;;;;;;;;;;OAYG;IACH,uBAAuB,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IASrE;;;;;;;;;;OAUG;IACH,mBAAmB,IAAI,IAAI;CAG5B"}