@cmdoss/memwal-sdk 0.9.0 → 1.0.0

package/src/infrastructure/walrus/WalrusStorageService.ts

@@ -1,638 +1,638 @@
-/**
- * WalrusStorageService - Production Decentralized Storage
- *
- * Walrus client integration with SEAL encryption,
- * content verification, and standardized tagging per https://docs.wal.app/
- *
- * Uses @mysten/walrus SDK for writeBlob/readBlob operations when signer is available.
- * Falls back to REST API for read-only operations without signer.
- */
-
-import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
-import { walrus } from '@mysten/walrus';
-import type { Signer } from '@mysten/sui/cryptography';
-import type { SealService } from '../seal/SealService';
-
-export interface WalrusConfig {
-  network?: 'testnet' | 'mainnet';
-  adminAddress?: string;
-  storageEpochs?: number;
-  /** Publisher URL for direct blob uploads (server-side) */
-  publisherHost?: string;
-  /** Upload Relay URL for browser/mobile uploads (fewer connections, faster) */
-  uploadRelayHost?: string;
-  /** Aggregator URL for blob retrieval */
-  aggregatorHost?: string;
-  /** Use upload relay instead of publisher (default: true for browser, false for server) */
-  useUploadRelay?: boolean;
-  retryAttempts?: number;
-  timeoutMs?: number;
-  sealService?: SealService;
-  signer?: Signer; // Required for writeBlob operations
-}
-
-export interface MemoryMetadata {
-  contentType: string;
-  contentSize: number;
-  contentHash: string;
-  category: string;
-  topic: string;
-  importance: number; // 1-10 scale
-  embeddingBlobId?: string;
-  embeddingDimension: number;
-  createdTimestamp: number;
-  updatedTimestamp?: number;
-  customMetadata?: Record<string, string>;
-  isEncrypted?: boolean;
-  encryptionType?: string;
-}
-
-export interface WalrusUploadResult {
-  blobId: string;
-  metadata: MemoryMetadata;
-  embeddingBlobId?: string;
-  isEncrypted: boolean;
-  backupKey?: string;
-  storageEpochs: number;
-  uploadTimeMs: number;
-}
-
-export interface WalrusRetrievalResult {
-  content: string;
-  metadata: MemoryMetadata;
-  isDecrypted: boolean;
-  retrievalTimeMs: number;
-}
-
-export interface BlobInfo {
-  blobId: string;
-  contentType: string;
-  contentLength: number;
-  contentHash: string;
-  metadata: Record<string, string>;
-  tags: string[];
-}
-
-class WalrusError extends Error {
-  public readonly cause?: unknown;
-  
-  constructor(message: string, cause?: unknown) {
-    super(message);
-    this.name = 'WalrusError';
-    this.cause = cause;
-  }
-}
-
-export interface WalrusStats {
-  totalUploads: number;
-  totalRetrievals: number;
-  successfulUploads: number;
-  failedUploads: number;
-  cacheHitRate: number;
-  averageUploadTime: number;
-  averageRetrievalTime: number;
-  localFallbackCount: number;
-  totalStorageUsed: number;
-}
-
-interface CachedBlob {
-  content: Uint8Array;
-  contentType: string;
-  timestamp: Date;
-  metadata: Record<string, string>;
-}
-
-/**
- * Production-ready Walrus storage service using @mysten/walrus SDK
- */
-export class WalrusStorageService {
-  private readonly config: Omit<Required<WalrusConfig>, 'sealService' | 'signer'> & {
-    sealService?: SealService;
-    signer?: Signer;
-  };
-  private readonly cache = new Map<string, CachedBlob>();
-  private stats: WalrusStats = {
-    totalUploads: 0,
-    totalRetrievals: 0,
-    successfulUploads: 0,
-    failedUploads: 0,
-    cacheHitRate: 0,
-    averageUploadTime: 0,
-    averageRetrievalTime: 0,
-    localFallbackCount: 0,
-    totalStorageUsed: 0
-  };
-
-  private readonly CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
-  private sealService?: SealService;
-  private walrusClient: ReturnType<typeof this.createWalrusClient> | null = null;
-
-  constructor(config: Partial<WalrusConfig> = {}) {
-    const network = config.network || 'testnet';
-    // Detect browser environment for default useUploadRelay
-    const isBrowser = typeof window !== 'undefined';
-
-    this.config = {
-      network,
-      adminAddress: config.adminAddress || '',
-      storageEpochs: config.storageEpochs || 12,
-      // Publisher: direct uploads (server-side)
-      publisherHost: config.publisherHost || 'https://publisher.walrus-testnet.walrus.space',
-      // Upload Relay: optimized for browser/mobile (fewer connections)
-      uploadRelayHost: config.uploadRelayHost || 'https://upload-relay.testnet.walrus.space',
-      // Aggregator: blob retrieval
-      aggregatorHost: config.aggregatorHost || 'https://aggregator.walrus-testnet.walrus.space',
-      // Use upload relay by default in browser, publisher on server
-      useUploadRelay: config.useUploadRelay ?? isBrowser,
-      retryAttempts: config.retryAttempts || 3,
-      timeoutMs: config.timeoutMs || 60000,
-      sealService: config.sealService,
-      signer: config.signer
-    };
-
-    this.sealService = config.sealService;
-
-    // Initialize Walrus SDK client
-    this.walrusClient = this.createWalrusClient(network);
-  }
-
-  /**
-   * Create Walrus client using @mysten/walrus SDK
-   * Uses $extend to add walrus capabilities to SuiClient
-   */
-  private createWalrusClient(network: 'testnet' | 'mainnet') {
-    const suiClient = new SuiClient({
-      url: getFullnodeUrl(network)
-    });
-
-    // Extend SuiClient with Walrus capabilities using $extend
-    return suiClient.$extend(walrus({
-      network,
-    }));
-  }
-
-  // ==================== PUBLIC API ====================
-
-  /**
-   * Store memory with encryption and metadata
-   */
-  async storeMemory(
-    content: string,
-    category: string,
-    options: {
-      topic?: string;
-      importance?: number;
-      customMetadata?: Record<string, string>;
-      contextId?: string;
-      appId?: string;
-      encrypt?: boolean;
-      userAddress?: string;
-    } = {}
-  ): Promise<WalrusUploadResult> {
-    const startTime = Date.now();
-    this.stats.totalUploads++;
-
-    try {
-      const {
-        topic = `Memory about ${category}`,
-        importance = 5,
-        customMetadata = {},
-        contextId,
-        appId,
-        encrypt = false,
-        userAddress
-      } = options;
-
-      let processedContent = content;
-      let backupKey: string | undefined;
-      let isEncrypted = false;
-
-      // Use SEAL encryption if requested and available
-      if (encrypt && this.sealService && userAddress) {
-        const sessionConfig = {
-          address: userAddress,
-          packageId: this.config.adminAddress, // Use configured package ID
-          ttlMin: 60 // 1 hour session
-        };
-        const sessionKey = await this.sealService.createSession(sessionConfig);
-        const encryptResult = await this.sealService.encryptData({
-          data: new TextEncoder().encode(content),
-          id: userAddress,
-          threshold: 2 // Default threshold
-        });
-        processedContent = JSON.stringify(encryptResult);
-        backupKey = 'session-key-reference'; // Store session reference
-        isEncrypted = true;
-      }
-
-      const metadata = this.createMetadataWithEmbedding(
-        processedContent,
-        category,
-        topic,
-        importance,
-        {
-          ...customMetadata,
-          ...(contextId && { 'context-id': contextId }),
-          ...(appId && { 'app-id': appId }),
-          ...(userAddress && { owner: userAddress }),
-          encrypted: isEncrypted.toString(),
-          ...(isEncrypted && { 'encryption-type': 'seal' })
-        }
-      );
-
-      // Upload to Walrus with official client
-      const blobId = await this.uploadToWalrus(processedContent, metadata);
-
-      // Use Walrus blob_id as content hash (already content-addressed via blake2b256)
-      metadata.contentHash = blobId;
-
-      const uploadTimeMs = Date.now() - startTime;
-      this.stats.successfulUploads++;
-      this.updateAverageUploadTime(uploadTimeMs);
-
-      return {
-        blobId,
-        metadata,
-        isEncrypted,
-        backupKey,
-        storageEpochs: this.config.storageEpochs,
-        uploadTimeMs
-      };
-
-    } catch (error) {
-      this.stats.failedUploads++;
-      throw new WalrusError(
-        `Failed to store memory: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        error
-      );
-    }
-  }
-
-  /**
-   * Retrieve memory with decryption
-   */
-  async retrieveMemory(
-    blobId: string,
-    options: {
-      userAddress?: string;
-      sessionKey?: any; // SEAL session key
-      txBytes?: Uint8Array;
-    } = {}
-  ): Promise<WalrusRetrievalResult> {
-    const startTime = Date.now();
-    this.stats.totalRetrievals++;
-
-    try {
-      // Check cache first
-      const cached = this.cache.get(blobId);
-      if (cached && this.isCacheValid(cached.timestamp)) {
-        this.stats.cacheHitRate = (this.stats.cacheHitRate * (this.stats.totalRetrievals - 1) + 1) / this.stats.totalRetrievals;
-        
-        const content = new TextDecoder().decode(cached.content);
-        return {
-          content,
-          metadata: cached.metadata as unknown as MemoryMetadata,
-          isDecrypted: false,
-          retrievalTimeMs: Date.now() - startTime
-        };
-      }
-
-      // Retrieve from Walrus
-      const { content, metadata } = await this.retrieveFromWalrus(blobId);
-      
-      let processedContent = content;
-      let isDecrypted = false;
-
-      // Decrypt if needed
-      if (metadata.isEncrypted && metadata.encryptionType === 'seal' && this.sealService) {
-        const { userAddress, sessionKey, txBytes } = options;
-        if (userAddress && sessionKey && txBytes) {
-          try {
-            const encryptedData = JSON.parse(content);
-            const decryptedBytes = await this.sealService.decryptData({
-              encryptedObject: new Uint8Array(encryptedData),
-              sessionKey,
-              txBytes
-            });
-            processedContent = new TextDecoder().decode(decryptedBytes);
-            isDecrypted = true;
-          } catch (decryptError) {
-            console.warn('SEAL decryption failed, returning encrypted content:', decryptError);
-          }
-        }
-      }
-
-      const retrievalTimeMs = Date.now() - startTime;
-      this.updateAverageRetrievalTime(retrievalTimeMs);
-
-      return {
-        content: processedContent,
-        metadata,
-        isDecrypted,
-        retrievalTimeMs
-      };
-
-    } catch (error) {
-      throw new WalrusError(
-        `Failed to retrieve memory ${blobId}: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        error
-      );
-    }
-  }
-
-  /**
-   * Get service statistics
-   */
-  getStats(): WalrusStats {
-    return { ...this.stats };
-  }
-
-  /**
-   * Clear cache
-   */
-  clearCache(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Retrieve content by blobId with optional decryption
-   */
-  async retrieveContent(blobId: string, decryptionKey?: string | Uint8Array): Promise<{
-    content: string;
-    metadata: MemoryMetadata;
-    retrievalTimeMs: number;
-    isFromCache: boolean;
-  }> {
-    const startTime = Date.now();
-    
-    try {
-      const result = await this.retrieveFromWalrus(blobId);
-      
-      return {
-        content: result.content,
-        metadata: result.metadata,
-        retrievalTimeMs: Date.now() - startTime,
-        isFromCache: false // TODO: implement cache checking
-      };
-    } catch (error) {
-      throw new Error(`Failed to retrieve content: ${error}`);
-    }
-  }
-
-  /**
-   * List blobs for a specific user
-   */
-  async listUserBlobs(userId: string, options: {
-    category?: string;
-    limit?: number;
-    offset?: number;
-    sortBy?: 'date' | 'size' | 'importance';
-    filters?: Record<string, any>;
-  } = {}): Promise<{ blobs: BlobInfo[]; totalCount: number }> {
-    // TODO: Implement actual Walrus listing when API is available
-    // For now, return empty result as this would require backend indexing
-    console.warn('listUserBlobs not yet implemented - requires Walrus indexing service');
-    return {
-      blobs: [],
-      totalCount: 0
-    };
-  }
-
-  /**
-   * Delete a blob by ID
-   */
-  async deleteBlob(blobId: string): Promise<boolean> {
-    // TODO: Implement actual Walrus deletion when API is available
-    // Walrus typically doesn't support deletion, but this could mark as deleted
-    console.warn('deleteBlob not yet implemented - Walrus typically immutable');
-    return false;
-  }
-
-  /**
-   * Check Walrus service availability
-   */
-  async checkWalrusAvailability(): Promise<boolean> {
-    // TODO: Implement proper availability check with official client
-    console.warn('checkWalrusAvailability not yet implemented - assuming available for testing');
-    return true; // Return true to allow tests to run, even though implementation is placeholder
-  }
-
-  /**
-   * Get cache information
-   */
-  getCacheInfo(): {
-    size: number;
-    maxSize: number;
-    hitRate: number;
-    entries: number;
-  } {
-    return {
-      size: this.cache.size, // Approximate
-      maxSize: 100, // Default cache size
-      hitRate: this.stats.cacheHitRate,
-      entries: this.cache.size
-    };
-  }
-
-  /**
-   * Upload content with metadata
-   */
-  async uploadContentWithMetadata(
-    content: string,
-    userId: string,
-    options: {
-      category?: string;
-      topic?: string;
-      importance?: number;
-      additionalTags?: Record<string, string>;
-      enableEncryption?: boolean;
-    }
-  ): Promise<{
-    blobId: string;
-    metadata: MemoryMetadata;
-    uploadTimeMs: number;
-    isEncrypted: boolean;
-  }> {
-    const startTime = Date.now();
-
-    try {
-      // Upload to Walrus first to get blob_id (which serves as content hash)
-      const tempMetadata: MemoryMetadata = {
-        contentType: 'application/json',
-        contentSize: content.length,
-        contentHash: '', // Will be set to blobId below
-        category: options.category || 'general',
-        topic: options.topic || 'misc',
-        importance: options.importance || 5,
-        embeddingDimension: 0,
-        createdTimestamp: Date.now(),
-        updatedTimestamp: Date.now(),
-        customMetadata: options.additionalTags || {},
-        isEncrypted: options.enableEncryption || false,
-        encryptionType: options.enableEncryption ? 'seal' : undefined
-      };
-
-      const blobId = await this.uploadToWalrus(content, tempMetadata);
-
-      // Use Walrus blob_id as content hash (already content-addressed via blake2b256)
-      const memoryMetadata: MemoryMetadata = {
-        ...tempMetadata,
-        contentHash: blobId, // Walrus blob_id serves as content hash
-      };
-
-      return {
-        blobId,
-        metadata: memoryMetadata,
-        uploadTimeMs: Date.now() - startTime,
-        isEncrypted: memoryMetadata.isEncrypted || false
-      };
-    } catch (error) {
-      throw new Error(`Failed to upload content: ${error}`);
-    }
-  }
-
-  // ==================== PRIVATE METHODS ====================
-
-  private createMetadataWithEmbedding(
-    content: string,
-    category: string,
-    topic: string,
-    importance: number,
-    customMetadata: Record<string, string>
-  ): MemoryMetadata {
-    const contentBuffer = Buffer.from(content, 'utf-8');
-    const timestamp = Date.now();
-
-    return {
-      contentType: 'text/plain',
-      contentSize: contentBuffer.length,
-      contentHash: '', // Will be set to blobId after upload
-      category,
-      topic: topic || `Memory about ${category}`,
-      importance: Math.max(1, Math.min(10, importance)),
-      embeddingDimension: 3072,
-      createdTimestamp: timestamp,
-      customMetadata
-    };
-  }
-
-  private async uploadToWalrus(content: string, _metadata: MemoryMetadata): Promise<string> {
-    // Use Walrus SDK writeBlob when signer is available
-    if (this.walrusClient && this.config.signer) {
-      try {
-        const blob = new TextEncoder().encode(content);
-        const { blobId } = await this.walrusClient.walrus.writeBlob({
-          blob,
-          deletable: false,
-          epochs: this.config.storageEpochs,
-          signer: this.config.signer
-        });
-        return blobId;
-      } catch (error) {
-        throw new WalrusError(`Walrus SDK upload failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error);
-      }
-    }
-
-    // Fallback to REST API based on useUploadRelay config
-    try {
-      let url: string;
-      if (this.config.useUploadRelay) {
-        // Upload Relay: optimized for browser/mobile (fewer network connections)
-        // POST to /v1/blobs endpoint
-        url = `${this.config.uploadRelayHost}/v1/blobs?epochs=${this.config.storageEpochs}`;
-      } else {
-        // Publisher: direct upload (server-side)
-        // PUT to /v1/blobs endpoint
-        url = `${this.config.publisherHost}/v1/blobs?epochs=${this.config.storageEpochs}`;
-      }
-
-      const response = await fetch(url, {
-        method: 'PUT',
-        headers: {
-          'Content-Type': 'application/octet-stream'
-        },
-        body: new TextEncoder().encode(content)
-      });
-
-      if (!response.ok) {
-        throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
-      }
-
-      const result = await response.json();
-      // Handle both newlyCreated and alreadyCertified responses
-      const newBlob = result.newlyCreated?.blobObject;
-      const certifiedBlob = result.alreadyCertified?.blobId;
-      return newBlob?.blobId || certifiedBlob || result.blobId;
-    } catch (error) {
-      throw new WalrusError(`Walrus REST upload failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error);
-    }
-  }
-
-  private async retrieveFromWalrus(blobId: string): Promise<{ content: string; metadata: MemoryMetadata }> {
-    // Use Walrus SDK readBlob when client is available
-    if (this.walrusClient) {
-      try {
-        const blob = await this.walrusClient.walrus.readBlob({ blobId });
-        const content = new TextDecoder().decode(blob);
-
-        const metadata: MemoryMetadata = {
-          contentType: 'text/plain',
-          contentSize: content.length,
-          contentHash: blobId,
-          category: 'unknown',
-          topic: 'Retrieved memory',
-          importance: 5,
-          embeddingDimension: 3072,
-          createdTimestamp: Date.now()
-        };
-
-        return { content, metadata };
-      } catch (error) {
-        // Fall through to REST API on SDK error
-        console.warn('Walrus SDK readBlob failed, falling back to REST API:', error);
-      }
-    }
-
-    // Fallback to REST API - Aggregator endpoint: GET /v1/blobs/<blob-id>
-    try {
-      const response = await fetch(`${this.config.aggregatorHost}/v1/blobs/${blobId}`);
-
-      if (!response.ok) {
-        throw new Error(`Retrieval failed: ${response.status} ${response.statusText}`);
-      }
-
-      const content = await response.text();
-
-      const metadata: MemoryMetadata = {
-        contentType: 'text/plain',
-        contentSize: content.length,
-        contentHash: blobId,
-        category: 'unknown',
-        topic: 'Retrieved memory',
-        importance: 5,
-        embeddingDimension: 3072,
-        createdTimestamp: Date.now()
-      };
-
-      return { content, metadata };
-    } catch (error) {
-      throw new WalrusError(`Walrus retrieval failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error);
-    }
-  }
-
-  private isCacheValid(timestamp: Date): boolean {
-    return Date.now() - timestamp.getTime() < this.CACHE_TTL_MS;
-  }
-
-  private updateAverageUploadTime(newTime: number): void {
-    const totalUploads = this.stats.successfulUploads;
-    this.stats.averageUploadTime = 
-      (this.stats.averageUploadTime * (totalUploads - 1) + newTime) / totalUploads;
-  }
-
-  private updateAverageRetrievalTime(newTime: number): void {
-    const totalRetrievals = this.stats.totalRetrievals;
-    this.stats.averageRetrievalTime = 
-      (this.stats.averageRetrievalTime * (totalRetrievals - 1) + newTime) / totalRetrievals;
-  }
+/**
+ * WalrusStorageService - Production Decentralized Storage
+ *
+ * Walrus client integration with SEAL encryption,
+ * content verification, and standardized tagging per https://docs.wal.app/
+ *
+ * Uses @mysten/walrus SDK for writeBlob/readBlob operations when signer is available.
+ * Falls back to REST API for read-only operations without signer.
+ */
+
+import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
+import { walrus } from '@mysten/walrus';
+import type { Signer } from '@mysten/sui/cryptography';
+import type { SealService } from '../seal/SealService';
+
+export interface WalrusConfig {
+  network?: 'testnet' | 'mainnet';
+  adminAddress?: string;
+  storageEpochs?: number;
+  /** Publisher URL for direct blob uploads (server-side) */
+  publisherHost?: string;
+  /** Upload Relay URL for browser/mobile uploads (fewer connections, faster) */
+  uploadRelayHost?: string;
+  /** Aggregator URL for blob retrieval */
+  aggregatorHost?: string;
+  /** Use upload relay instead of publisher (default: true for browser, false for server) */
+  useUploadRelay?: boolean;
+  retryAttempts?: number;
+  timeoutMs?: number;
+  sealService?: SealService;
+  signer?: Signer; // Required for writeBlob operations
+}
+
+export interface MemoryMetadata {
+  contentType: string;
+  contentSize: number;
+  contentHash: string;
+  category: string;
+  topic: string;
+  importance: number; // 1-10 scale
+  embeddingBlobId?: string;
+  embeddingDimension: number;
+  createdTimestamp: number;
+  updatedTimestamp?: number;
+  customMetadata?: Record<string, string>;
+  isEncrypted?: boolean;
+  encryptionType?: string;
+}
+
+export interface WalrusUploadResult {
+  blobId: string;
+  metadata: MemoryMetadata;
+  embeddingBlobId?: string;
+  isEncrypted: boolean;
+  backupKey?: string;
+  storageEpochs: number;
+  uploadTimeMs: number;
+}
+
+export interface WalrusRetrievalResult {
+  content: string;
+  metadata: MemoryMetadata;
+  isDecrypted: boolean;
+  retrievalTimeMs: number;
+}
+
+export interface BlobInfo {
+  blobId: string;
+  contentType: string;
+  contentLength: number;
+  contentHash: string;
+  metadata: Record<string, string>;
+  tags: string[];
+}
+
+class WalrusError extends Error {
+  public readonly cause?: unknown;
+  
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = 'WalrusError';
+    this.cause = cause;
+  }
+}
+
+export interface WalrusStats {
+  totalUploads: number;
+  totalRetrievals: number;
+  successfulUploads: number;
+  failedUploads: number;
+  cacheHitRate: number;
+  averageUploadTime: number;
+  averageRetrievalTime: number;
+  localFallbackCount: number;
+  totalStorageUsed: number;
+}
+
+interface CachedBlob {
+  content: Uint8Array;
+  contentType: string;
+  timestamp: Date;
+  metadata: Record<string, string>;
+}
+
+/**
+ * Production-ready Walrus storage service using @mysten/walrus SDK
+ */
+export class WalrusStorageService {
+  private readonly config: Omit<Required<WalrusConfig>, 'sealService' | 'signer'> & {
+    sealService?: SealService;
+    signer?: Signer;
+  };
+  private readonly cache = new Map<string, CachedBlob>();
+  private stats: WalrusStats = {
+    totalUploads: 0,
+    totalRetrievals: 0,
+    successfulUploads: 0,
+    failedUploads: 0,
+    cacheHitRate: 0,
+    averageUploadTime: 0,
+    averageRetrievalTime: 0,
+    localFallbackCount: 0,
+    totalStorageUsed: 0
+  };
+
+  private readonly CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+  private sealService?: SealService;
+  private walrusClient: ReturnType<typeof this.createWalrusClient> | null = null;
+
+  constructor(config: Partial<WalrusConfig> = {}) {
+    const network = config.network || 'testnet';
+    // Detect browser environment for default useUploadRelay
+    const isBrowser = typeof window !== 'undefined';
+
+    this.config = {
+      network,
+      adminAddress: config.adminAddress || '',
+      storageEpochs: config.storageEpochs || 12,
+      // Publisher: direct uploads (server-side)
+      publisherHost: config.publisherHost || 'https://publisher.walrus-testnet.walrus.space',
+      // Upload Relay: optimized for browser/mobile (fewer connections)
+      uploadRelayHost: config.uploadRelayHost || 'https://upload-relay.testnet.walrus.space',
+      // Aggregator: blob retrieval
+      aggregatorHost: config.aggregatorHost || 'https://aggregator.walrus-testnet.walrus.space',
+      // Use upload relay by default in browser, publisher on server
+      useUploadRelay: config.useUploadRelay ?? isBrowser,
+      retryAttempts: config.retryAttempts || 3,
+      timeoutMs: config.timeoutMs || 60000,
+      sealService: config.sealService,
+      signer: config.signer
+    };
+
+    this.sealService = config.sealService;
+
+    // Initialize Walrus SDK client
+    this.walrusClient = this.createWalrusClient(network);
+  }
+
+  /**
+   * Create Walrus client using @mysten/walrus SDK
+   * Uses $extend to add walrus capabilities to SuiClient
+   */
+  private createWalrusClient(network: 'testnet' | 'mainnet') {
+    const suiClient = new SuiClient({
+      url: getFullnodeUrl(network)
+    });
+
+    // Extend SuiClient with Walrus capabilities using $extend
+    return suiClient.$extend(walrus({
+      network,
+    }));
+  }
+
+  // ==================== PUBLIC API ====================
+
+  /**
+   * Store memory with encryption and metadata
+   */
+  async storeMemory(
+    content: string,
+    category: string,
+    options: {
+      topic?: string;
+      importance?: number;
+      customMetadata?: Record<string, string>;
+      contextId?: string;
+      appId?: string;
+      encrypt?: boolean;
+      userAddress?: string;
+    } = {}
+  ): Promise<WalrusUploadResult> {
+    const startTime = Date.now();
+    this.stats.totalUploads++;
+
+    try {
+      const {
+        topic = `Memory about ${category}`,
+        importance = 5,
+        customMetadata = {},
+        contextId,
+        appId,
+        encrypt = false,
+        userAddress
+      } = options;
+
+      let processedContent = content;
+      let backupKey: string | undefined;
+      let isEncrypted = false;
+
+      // Use SEAL encryption if requested and available
+      if (encrypt && this.sealService && userAddress) {
+        const sessionConfig = {
+          address: userAddress,
+          packageId: this.config.adminAddress, // Use configured package ID
+          ttlMin: 60 // 1 hour session
+        };
+        const sessionKey = await this.sealService.createSession(sessionConfig);
+        const encryptResult = await this.sealService.encryptData({
+          data: new TextEncoder().encode(content),
+          id: userAddress,
+          threshold: 2 // Default threshold
+        });
+        processedContent = JSON.stringify(encryptResult);
+        backupKey = 'session-key-reference'; // Store session reference
+        isEncrypted = true;
+      }
+
+      const metadata = this.createMetadataWithEmbedding(
+        processedContent,
+        category,
+        topic,
+        importance,
+        {
+          ...customMetadata,
+          ...(contextId && { 'context-id': contextId }),
+          ...(appId && { 'app-id': appId }),
+          ...(userAddress && { owner: userAddress }),
+          encrypted: isEncrypted.toString(),
+          ...(isEncrypted && { 'encryption-type': 'seal' })
+        }
+      );
+
+      // Upload to Walrus with official client
+      const blobId = await this.uploadToWalrus(processedContent, metadata);
+
+      // Use Walrus blob_id as content hash (already content-addressed via blake2b256)
+      metadata.contentHash = blobId;
+
+      const uploadTimeMs = Date.now() - startTime;
+      this.stats.successfulUploads++;
+      this.updateAverageUploadTime(uploadTimeMs);
+
+      return {
+        blobId,
+        metadata,
+        isEncrypted,
+        backupKey,
+        storageEpochs: this.config.storageEpochs,
+        uploadTimeMs
+      };
+
+    } catch (error) {
+      this.stats.failedUploads++;
+      throw new WalrusError(
+        `Failed to store memory: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Retrieve memory with decryption
+   */
+  async retrieveMemory(
+    blobId: string,
+    options: {
+      userAddress?: string;
+      sessionKey?: any; // SEAL session key
+      txBytes?: Uint8Array;
+    } = {}
+  ): Promise<WalrusRetrievalResult> {
+    const startTime = Date.now();
+    this.stats.totalRetrievals++;
+
+    try {
+      // Check cache first
+      const cached = this.cache.get(blobId);
+      if (cached && this.isCacheValid(cached.timestamp)) {
+        this.stats.cacheHitRate = (this.stats.cacheHitRate * (this.stats.totalRetrievals - 1) + 1) / this.stats.totalRetrievals;
+        
+        const content = new TextDecoder().decode(cached.content);
+        return {
+          content,
+          metadata: cached.metadata as unknown as MemoryMetadata,
+          isDecrypted: false,
+          retrievalTimeMs: Date.now() - startTime
+        };
+      }
+
+      // Retrieve from Walrus
+      const { content, metadata } = await this.retrieveFromWalrus(blobId);
+      
+      let processedContent = content;
+      let isDecrypted = false;
+
+      // Decrypt if needed
+      if (metadata.isEncrypted && metadata.encryptionType === 'seal' && this.sealService) {
+        const { userAddress, sessionKey, txBytes } = options;
+        if (userAddress && sessionKey && txBytes) {
+          try {
+            const encryptedData = JSON.parse(content);
+            const decryptedBytes = await this.sealService.decryptData({
+              encryptedObject: new Uint8Array(encryptedData),
+              sessionKey,
+              txBytes
+            });
+            processedContent = new TextDecoder().decode(decryptedBytes);
+            isDecrypted = true;
+          } catch (decryptError) {
+            console.warn('SEAL decryption failed, returning encrypted content:', decryptError);
+          }
+        }
+      }
+
+      const retrievalTimeMs = Date.now() - startTime;
+      this.updateAverageRetrievalTime(retrievalTimeMs);
+
+      return {
+        content: processedContent,
+        metadata,
+        isDecrypted,
+        retrievalTimeMs
+      };
+
+    } catch (error) {
+      throw new WalrusError(
+        `Failed to retrieve memory ${blobId}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Get service statistics
+   */
+  getStats(): WalrusStats {
+    return { ...this.stats };
+  }
+
+  /**
+   * Clear cache
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Retrieve content by blobId with optional decryption
+   */
+  async retrieveContent(blobId: string, decryptionKey?: string | Uint8Array): Promise<{
+    content: string;
+    metadata: MemoryMetadata;
+    retrievalTimeMs: number;
+    isFromCache: boolean;
+  }> {
+    const startTime = Date.now();
+    
+    try {
+      const result = await this.retrieveFromWalrus(blobId);
+      
+      return {
+        content: result.content,
+        metadata: result.metadata,
+        retrievalTimeMs: Date.now() - startTime,
+        isFromCache: false // TODO: implement cache checking
+      };
+    } catch (error) {
+      throw new Error(`Failed to retrieve content: ${error}`);
+    }
+  }
+
+  /**
+   * List blobs for a specific user
+   */
+  async listUserBlobs(userId: string, options: {
+    category?: string;
+    limit?: number;
+    offset?: number;
+    sortBy?: 'date' | 'size' | 'importance';
+    filters?: Record<string, any>;
+  } = {}): Promise<{ blobs: BlobInfo[]; totalCount: number }> {
+    // TODO: Implement actual Walrus listing when API is available
+    // For now, return empty result as this would require backend indexing
+    console.warn('listUserBlobs not yet implemented - requires Walrus indexing service');
+    return {
+      blobs: [],
+      totalCount: 0
+    };
+  }
+
+  /**
+   * Delete a blob by ID
+   */
+  async deleteBlob(blobId: string): Promise<boolean> {
+    // TODO: Implement actual Walrus deletion when API is available
+    // Walrus typically doesn't support deletion, but this could mark as deleted
+    console.warn('deleteBlob not yet implemented - Walrus typically immutable');
+    return false;
+  }
+
+  /**
+   * Check Walrus service availability
+   */
+  async checkWalrusAvailability(): Promise<boolean> {
+    // TODO: Implement proper availability check with official client
+    console.warn('checkWalrusAvailability not yet implemented - assuming available for testing');
+    return true; // Return true to allow tests to run, even though implementation is placeholder
+  }
+
+  /**
+   * Get cache information
+   */
+  getCacheInfo(): {
+    size: number;
+    maxSize: number;
+    hitRate: number;
+    entries: number;
+  } {
+    return {
+      size: this.cache.size, // Approximate
+      maxSize: 100, // Default cache size
+      hitRate: this.stats.cacheHitRate,
+      entries: this.cache.size
+    };
+  }
+
+  /**
+   * Upload content with metadata
+   */
+  async uploadContentWithMetadata(
+    content: string,
+    userId: string,
+    options: {
+      category?: string;
+      topic?: string;
+      importance?: number;
+      additionalTags?: Record<string, string>;
+      enableEncryption?: boolean;
+    }
+  ): Promise<{
+    blobId: string;
+    metadata: MemoryMetadata;
+    uploadTimeMs: number;
+    isEncrypted: boolean;
+  }> {
+    const startTime = Date.now();
+
+    try {
+      // Upload to Walrus first to get blob_id (which serves as content hash)
+      const tempMetadata: MemoryMetadata = {
+        contentType: 'application/json',
+        contentSize: content.length,
+        contentHash: '', // Will be set to blobId below
+        category: options.category || 'general',
+        topic: options.topic || 'misc',
+        importance: options.importance || 5,
+        embeddingDimension: 0,
+        createdTimestamp: Date.now(),
+        updatedTimestamp: Date.now(),
+        customMetadata: options.additionalTags || {},
+        isEncrypted: options.enableEncryption || false,
+        encryptionType: options.enableEncryption ? 'seal' : undefined
+      };
+
+      const blobId = await this.uploadToWalrus(content, tempMetadata);
+
+      // Use Walrus blob_id as content hash (already content-addressed via blake2b256)
+      const memoryMetadata: MemoryMetadata = {
+        ...tempMetadata,
+        contentHash: blobId, // Walrus blob_id serves as content hash
+      };
+
+      return {
+        blobId,
+        metadata: memoryMetadata,
+        uploadTimeMs: Date.now() - startTime,
+        isEncrypted: memoryMetadata.isEncrypted || false
+      };
+    } catch (error) {
+      throw new Error(`Failed to upload content: ${error}`);
+    }
+  }
+
+  // ==================== PRIVATE METHODS ====================
+
+  private createMetadataWithEmbedding(
+    content: string,
+    category: string,
+    topic: string,
+    importance: number,
+    customMetadata: Record<string, string>
+  ): MemoryMetadata {
+    const contentBuffer = Buffer.from(content, 'utf-8');
+    const timestamp = Date.now();
+
+    return {
+      contentType: 'text/plain',
+      contentSize: contentBuffer.length,
+      contentHash: '', // Will be set to blobId after upload
+      category,
+      topic: topic || `Memory about ${category}`,
+      importance: Math.max(1, Math.min(10, importance)),
+      embeddingDimension: 3072,
+      createdTimestamp: timestamp,
+      customMetadata
+    };
+  }
+
+  private async uploadToWalrus(content: string, _metadata: MemoryMetadata): Promise<string> {
+    // Use Walrus SDK writeBlob when signer is available
+    if (this.walrusClient && this.config.signer) {
+      try {
+        const blob = new TextEncoder().encode(content);
+        const { blobId } = await this.walrusClient.walrus.writeBlob({
+          blob,
+          deletable: false,
+          epochs: this.config.storageEpochs,
+          signer: this.config.signer
+        });
+        return blobId;
+      } catch (error) {
+        throw new WalrusError(`Walrus SDK upload failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error);
+      }
+    }
+
+    // Fallback to REST API based on useUploadRelay config
+    try {
+      let url: string;
+      if (this.config.useUploadRelay) {
+        // Upload Relay: optimized for browser/mobile (fewer network connections)
+        // POST to /v1/blobs endpoint
+        url = `${this.config.uploadRelayHost}/v1/blobs?epochs=${this.config.storageEpochs}`;
+      } else {
+        // Publisher: direct upload (server-side)
+        // PUT to /v1/blobs endpoint
+        url = `${this.config.publisherHost}/v1/blobs?epochs=${this.config.storageEpochs}`;
+      }
+
+      const response = await fetch(url, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/octet-stream'
+        },
+        body: new TextEncoder().encode(content)
+      });
+
+      if (!response.ok) {
+        throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
+      }
+
+      const result = await response.json();
+      // Handle both newlyCreated and alreadyCertified responses
+      const newBlob = result.newlyCreated?.blobObject;
+      const certifiedBlob = result.alreadyCertified?.blobId;
+      return newBlob?.blobId || certifiedBlob || result.blobId;
+    } catch (error) {
+      throw new WalrusError(`Walrus REST upload failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error);
+    }
+  }
+
+  private async retrieveFromWalrus(blobId: string): Promise<{ content: string; metadata: MemoryMetadata }> {
+    // Use Walrus SDK readBlob when client is available
+    if (this.walrusClient) {
+      try {
+        const blob = await this.walrusClient.walrus.readBlob({ blobId });
+        const content = new TextDecoder().decode(blob);
+
+        const metadata: MemoryMetadata = {
+          contentType: 'text/plain',
+          contentSize: content.length,
+          contentHash: blobId,
+          category: 'unknown',
+          topic: 'Retrieved memory',
+          importance: 5,
+          embeddingDimension: 3072,
+          createdTimestamp: Date.now()
+        };
+
+        return { content, metadata };
+      } catch (error) {
+        // Fall through to REST API on SDK error
+        console.warn('Walrus SDK readBlob failed, falling back to REST API:', error);
+      }
+    }
+
+    // Fallback to REST API - Aggregator endpoint: GET /v1/blobs/<blob-id>
+    try {
+      const response = await fetch(`${this.config.aggregatorHost}/v1/blobs/${blobId}`);
+
+      if (!response.ok) {
+        throw new Error(`Retrieval failed: ${response.status} ${response.statusText}`);
+      }
+
+      const content = await response.text();
+
+      const metadata: MemoryMetadata = {
+        contentType: 'text/plain',
+        contentSize: content.length,
+        contentHash: blobId,
+        category: 'unknown',
+        topic: 'Retrieved memory',
+        importance: 5,
+        embeddingDimension: 3072,
+        createdTimestamp: Date.now()
+      };
+
+      return { content, metadata };
+    } catch (error) {
+      throw new WalrusError(`Walrus retrieval failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error);
+    }
+  }
+
+  private isCacheValid(timestamp: Date): boolean {
+    return Date.now() - timestamp.getTime() < this.CACHE_TTL_MS;
+  }
+
+  private updateAverageUploadTime(newTime: number): void {
+    const totalUploads = this.stats.successfulUploads;
+    this.stats.averageUploadTime = 
+      (this.stats.averageUploadTime * (totalUploads - 1) + newTime) / totalUploads;
+  }
+
+  private updateAverageRetrievalTime(newTime: number): void {
+    const totalRetrievals = this.stats.totalRetrievals;
+    this.stats.averageRetrievalTime = 
+      (this.stats.averageRetrievalTime * (totalRetrievals - 1) + newTime) / totalRetrievals;
+  }
 }