@cmdoss/memwal-sdk 0.6.1 → 0.6.2

package/src/client/SimplePDWClient.ts

@@ -190,6 +190,23 @@ export interface SimplePDWConfig {
     /** Progress callback for index operations */
     onProgress?: IndexProgressCallback;
   };
+
+  /**
+   * Optional: Index backup to Walrus cloud storage
+   * Enables syncing local HNSW index to Walrus for cross-device restoration
+   */
+  indexBackup?: {
+    /** Enable Walrus backup for local index */
+    enabled: boolean;
+    /** Walrus aggregator URL for downloading */
+    aggregatorUrl?: string;
+    /** Walrus publisher URL for uploading */
+    publisherUrl?: string;
+    /** Auto-sync index to Walrus on every save (default: false) */
+    autoSync?: boolean;
+    /** Storage duration in epochs (default: 3) */
+    epochs?: number;
+  };
 }
 
 /**
@@ -239,6 +256,13 @@ interface ResolvedConfig {
     enableAutoSave?: boolean;
     onProgress?: IndexProgressCallback;
   };
+  indexBackup?: {
+    enabled: boolean;
+    aggregatorUrl?: string;
+    publisherUrl?: string;
+    autoSync?: boolean;
+    epochs?: number;
+  };
 }
 
 /**
@@ -360,7 +384,8 @@ export class SimplePDWClient {
         enableLocalIndexing: config.features?.enableLocalIndexing ?? true,
         enableKnowledgeGraph: config.features?.enableKnowledgeGraph ?? true
       },
-      indexManager: config.indexManager
+      indexManager: config.indexManager,
+      indexBackup: config.indexBackup
     };
   }
 
@@ -473,6 +498,15 @@ export class SimplePDWClient {
     // Note: This starts async initialization - services will wait for it when needed
     let sharedHnswService: IHnswService | undefined;
     if (config.features.enableLocalIndexing) {
+      // Prepare Walrus backup config if enabled
+      const walrusBackupConfig = config.indexBackup?.enabled ? {
+        enabled: true,
+        aggregatorUrl: config.indexBackup.aggregatorUrl || config.walrus.aggregator,
+        publisherUrl: config.indexBackup.publisherUrl || config.walrus.publisher,
+        autoSync: config.indexBackup.autoSync ?? false,
+        epochs: config.indexBackup.epochs ?? 3
+      } : undefined;
+
       // Dynamic import to avoid bundling Node.js dependencies (hnswlib-node) in browser builds
       // When enableLocalIndexing is false, this code never runs and webpack won't bundle it
       this.sharedHnswServicePromise = import('../vector/createHnswService').then(
@@ -486,10 +520,14 @@ export class SimplePDWClient {
           batchConfig: {
             maxBatchSize: 100,
             batchDelayMs: 5000
-          }
+          },
+          walrusBackup: walrusBackupConfig
         })
       );
       console.log('✅ Shared HNSW service initialization started (singleton for all vector services)');
+      if (walrusBackupConfig?.enabled) {
+        console.log('   ☁️ Walrus backup enabled for local index');
+      }
     }
 
     // 9a. Vector Service (if local indexing enabled)

package/src/client/namespaces/IndexNamespace.ts

@@ -189,13 +189,11 @@ export class IndexNamespace {
   }
 
   /**
-   * Save index to Walrus storage
+   * Save index to local storage
    *
-   * Persists the HNSW index binary to Walrus for durability.
-   * Uses HnswWasmService.saveIndex() which properly serializes the index.
+   * Persists the HNSW index binary to local filesystem.
    *
    * @param spaceId - Index space identifier (userAddress)
-   * @returns Blob ID of saved index on Walrus, or null if no index exists
    */
   async save(spaceId: string): Promise<void> {
     const { type, service } = this.getService();
@@ -211,26 +209,106 @@ export class IndexNamespace {
   }
 
   /**
-   * Load index from Walrus storage
+   * Load index from storage (local or Walrus)
    *
-   * Loads a previously saved HNSW index from Walrus.
-   * Uses HnswWasmService.loadIndex() which properly deserializes the binary.
+   * If blobId is provided, attempts to load from Walrus first.
+   * Falls back to local storage if Walrus load fails.
    *
    * @param spaceId - Index space identifier (userAddress)
-   * @param blobId - Blob ID of the saved index on Walrus
+   * @param blobId - Optional Walrus blob ID to load from cloud
    */
-  async load(spaceId: string, blobId: string): Promise<void> {
+  async load(spaceId: string, blobId?: string): Promise<void> {
     const { type, service } = this.getService();
 
     if (type === 'memoryIndex') {
-      // MemoryIndexService.loadIndex(userAddress, indexBlobId?)
       await service.loadIndex(spaceId, blobId);
-      console.log(`Index loaded from Walrus: ${blobId}`);
+      if (blobId) {
+        console.log(`Index loaded from Walrus: ${blobId}`);
+      } else {
+        console.log(`Index loaded from local storage: ${spaceId}`);
+      }
     } else {
       await service.loadIndex(spaceId, blobId);
     }
   }
 
+  /**
+   * Sync index to Walrus cloud storage
+   *
+   * Uploads the HNSW index binary + metadata to Walrus for durability.
+   * This enables cross-device index restoration.
+   *
+   * @param spaceId - Index space identifier (userAddress)
+   * @returns Walrus blob ID if successful, null if Walrus is disabled
+   */
+  async syncToWalrus(spaceId: string): Promise<string | null> {
+    const { type, service } = this.getService();
+
+    if (type === 'memoryIndex' && 'syncToWalrus' in service) {
+      const blobId = await service.syncToWalrus(spaceId);
+      if (blobId) {
+        console.log(`Index synced to Walrus: ${blobId}`);
+      }
+      return blobId;
+    }
+
+    console.warn('Walrus sync not available for this service type');
+    return null;
+  }
+
+  /**
+   * Load index from Walrus cloud storage
+   *
+   * Downloads and restores a previously synced index from Walrus.
+   *
+   * @param spaceId - Index space identifier (userAddress)
+   * @param blobId - Walrus blob ID of the saved index
+   * @returns true if successfully loaded
+   */
+  async loadFromWalrus(spaceId: string, blobId: string): Promise<boolean> {
+    const { type, service } = this.getService();
+
+    if (type === 'memoryIndex' && 'loadFromWalrus' in service) {
+      const loaded = await service.loadFromWalrus(spaceId, blobId);
+      if (loaded) {
+        console.log(`Index loaded from Walrus: ${blobId}`);
+      }
+      return loaded;
+    }
+
+    console.warn('Walrus load not available for this service type');
+    return false;
+  }
+
+  /**
+   * Get the Walrus blob ID for a user's index (if backed up)
+   *
+   * @param spaceId - Index space identifier (userAddress)
+   * @returns Blob ID or null if not backed up
+   */
+  getWalrusBlobId(spaceId: string): string | null {
+    const { type, service } = this.getService();
+
+    if (type === 'memoryIndex' && 'getWalrusBlobId' in service) {
+      return service.getWalrusBlobId(spaceId);
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if Walrus backup is enabled
+   */
+  isWalrusEnabled(): boolean {
+    const { type, service } = this.getService();
+
+    if (type === 'memoryIndex' && 'isWalrusEnabled' in service) {
+      return service.isWalrusEnabled();
+    }
+
+    return false;
+  }
+
   /**
    * Clear index and remove all vectors
    *

package/src/client/namespaces/SearchNamespace.ts

@@ -154,18 +154,26 @@ export class SearchNamespace {
 
       // Convert to SearchResult format
       // Option A+: Content may be available from local index when encryption is OFF
-      const searchResults: SearchResult[] = results.map((r: any) => ({
-        id: r.memoryId || r.vectorId.toString(),
-        content: r.metadata?.content || r.content || '', // ✅ Get content from index metadata if available
-        score: r.similarity,
-        similarity: r.similarity,
-        category: r.metadata?.category,
-        importance: r.metadata?.importance || 5,
-        topic: r.metadata?.topic,
-        blobId: r.metadata?.blobId || r.memoryId || r.vectorId.toString(),
-        metadata: r.metadata || {},
-        timestamp: r.metadata?.timestamp || Date.now()
-      }));
+      const searchResults: SearchResult[] = results.map((r: any) => {
+        // blobId must be a valid Walrus blob ID, not a vectorId
+        // Only use metadata.blobId if it's a non-empty string that looks like a Walrus blobId
+        const rawBlobId = r.metadata?.blobId;
+        const isValidBlobId = rawBlobId && typeof rawBlobId === 'string' && rawBlobId.length > 10 && !/^\d+$/.test(rawBlobId);
+        const blobId = isValidBlobId ? rawBlobId : (r.metadata?.memoryObjectId || '');
+
+        return {
+          id: r.memoryId || r.vectorId.toString(),
+          content: r.metadata?.content || r.content || '', // ✅ Get content from index metadata if available
+          score: r.similarity,
+          similarity: r.similarity,
+          category: r.metadata?.category,
+          importance: r.metadata?.importance || 5,
+          topic: r.metadata?.topic,
+          blobId,
+          metadata: r.metadata || {},
+          timestamp: r.metadata?.timestamp || Date.now()
+        };
+      });
 
       // Optionally fetch content from Walrus
       if (fetchContent) {
@@ -329,7 +337,12 @@ export class SearchNamespace {
           const localResults = this.services.vector.getVectorsByCategory(spaceId, category);
 
           for (const { vectorId, metadata } of localResults) {
-            const id = metadata?.blobId || metadata?.memoryId || vectorId?.toString();
+            // blobId must be a valid Walrus blob ID, not a vectorId
+            const rawBlobId = metadata?.blobId;
+            const isValidBlobId = rawBlobId && typeof rawBlobId === 'string' && rawBlobId.length > 10 && !/^\d+$/.test(rawBlobId);
+            const blobId = isValidBlobId ? rawBlobId : (metadata?.memoryObjectId || '');
+            const id = blobId || metadata?.memoryId || vectorId?.toString();
+
             if (id && !seenIds.has(id)) {
               seenIds.add(id);
               results.push({
@@ -340,7 +353,7 @@ export class SearchNamespace {
                 category: metadata?.category,
                 importance: metadata?.importance || 5,
                 topic: metadata?.topic,
-                blobId: id,
+                blobId,
                 metadata: metadata || {},
                 timestamp: metadata?.timestamp || Date.now()
               });

package/src/client/namespaces/consolidated/BlockchainNamespace.ts

@@ -135,12 +135,66 @@ class TxSubNamespace {
    * ```
    */
   async execute(tx: Transaction): Promise<TransactionResult> {
+    const signer = this.services.config.signer;
+
+    // Check if signer supports signAndExecuteTransaction (browser wallets like DappKitSigner)
+    // Browser wallets cannot expose raw Signer for security reasons
+    if ('signAndExecuteTransaction' in signer && typeof signer.signAndExecuteTransaction === 'function') {
+      try {
+        // Use the signer's signAndExecuteTransaction directly
+        const result = await signer.signAndExecuteTransaction(tx);
+
+        // Get full transaction details to extract created objects
+        let createdObjects: Array<{ objectId: string; objectType: string }> | undefined;
+        let mutatedObjects: Array<{ objectId: string; objectType: string }> | undefined;
+
+        if (result.objectChanges && Array.isArray(result.objectChanges)) {
+          createdObjects = result.objectChanges
+            .filter((change: any) => change.type === 'created')
+            .map((change: any) => ({
+              objectId: change.objectId,
+              objectType: change.objectType || 'unknown',
+            }));
+
+          mutatedObjects = result.objectChanges
+            .filter((change: any) => change.type === 'mutated')
+            .map((change: any) => ({
+              objectId: change.objectId,
+              objectType: change.objectType || 'unknown',
+            }));
+        }
+
+        // Determine status from effects
+        const status = result.effects?.status?.status === 'success' ? 'success' : 'failure';
+
+        return {
+          digest: result.digest,
+          status,
+          effects: result.effects,
+          createdObjects,
+          mutatedObjects,
+          gasUsed: result.effects?.gasUsed?.computationCost
+            ? Number(result.effects.gasUsed.computationCost)
+            : undefined,
+          error: status === 'failure' ? result.effects?.status?.error : undefined,
+        };
+      } catch (error) {
+        console.error('Transaction execution failed:', error);
+        return {
+          digest: '',
+          status: 'failure',
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    // Fallback: Use TransactionService with raw Signer (Node.js/backend)
     if (!this.services.tx) {
       throw new Error('Transaction service not configured.');
     }
     return await this.services.tx.executeTransaction(
       tx,
-      this.services.config.signer.getSigner()
+      signer.getSigner()
     );
   }
 

package/src/client/namespaces/consolidated/StorageNamespace.ts

@@ -437,4 +437,61 @@ export class StorageNamespace {
       };
     }
   }
+
+  // ==========================================================================
+  // Batch Operations (Quilt)
+  // ==========================================================================
+
+  /**
+   * Upload multiple memories as a Quilt (batch upload)
+   *
+   * Uses Walrus Quilt for ~90% gas savings compared to individual uploads.
+   * Requires 2 user signatures:
+   * - Transaction 1: Register blob on-chain
+   * - Transaction 2: Certify upload on-chain
+   *
+   * @param memories - Array of memories to upload
+   * @param options - Upload options including signer
+   * @returns Quilt result with file mappings
+   *
+   * @example
+   * ```typescript
+   * const result = await pdw.storage.uploadMemoryBatch(
+   *   memories,
+   *   {
+   *     signer: pdw.getConfig().signer,
+   *     epochs: 3,
+   *     userAddress: pdw.getConfig().userAddress
+   *   }
+   * );
+   * console.log(`Uploaded ${result.files.length} files`);
+   * ```
+   */
+  async uploadMemoryBatch(
+    memories: Array<{
+      content: string;
+      category: string;
+      importance: number;
+      topic: string;
+      embedding: number[];
+      encryptedContent: Uint8Array;
+      summary?: string;
+      id?: string;
+    }>,
+    options: {
+      signer: any; // UnifiedSigner
+      epochs?: number;
+      userAddress: string;
+    }
+  ): Promise<{
+    quiltId: string;
+    files: Array<{ identifier: string; blobId: string }>;
+    uploadTimeMs: number;
+  }> {
+    if (!this.services.storage) {
+      throw new Error('Storage service not configured.');
+    }
+
+    return this.services.storage.uploadMemoryBatch(memories, options);
+  }
 }