@cmdoss/memwal-sdk 0.6.0

package/dist/services/TransactionService.d.ts

@@ -0,0 +1,179 @@
+import { Transaction } from '@mysten/sui/transactions';
+import { SuiClient } from '@mysten/sui/client';
+import { PDWConfig, TransactionOptions, TransactionResult, CreateMemoryRecordTxOptions, CreateMemoryRecordLightweightTxOptions, UpdateMemoryMetadataTxOptions, UpdateMemoryRecordTxOptions, DeleteMemoryRecordTxOptions, CreateMemoryIndexTxOptions, UpdateMemoryIndexTxOptions, GrantAccessTxOptions, RevokeAccessTxOptions, RegisterContentTxOptions } from '../types';
+/**
+ * TransactionService provides high-level transaction building and execution
+ * for Personal Data Wallet Move contracts with proper error handling and gas management.
+ *
+ * Uses SerialTransactionExecutor to prevent gas coin version conflicts and equivocation
+ * when multiple transactions are executed in sequence. The executor caches object versions
+ * and manages gas coins automatically.
+ *
+ * @see https://sdk.mystenlabs.com/typescript/executors
+ */
+export declare class TransactionService {
+    private client;
+    private config;
+    private executor;
+    private currentSigner;
+    constructor(client: SuiClient, config: PDWConfig);
+    /**
+     * Get or create SerialTransactionExecutor for the given signer.
+     * The executor caches object versions and prevents equivocation.
+     */
+    private getExecutor;
+    /**
+     * Reset the executor (useful when gas coin is exhausted or for cleanup)
+     */
+    resetExecutor(): void;
+    /**
+     * Build transaction to create a new memory record
+     */
+    buildCreateMemoryRecord(options: CreateMemoryRecordTxOptions): Transaction;
+    /**
+     * Build transaction to create a lightweight memory record
+     *
+     * This creates a minimal on-chain Memory struct with only essential queryable fields.
+     * Rich metadata should be stored as Walrus blob metadata for gas efficiency.
+     *
+     * Use this when:
+     * - Gas costs are a concern (saves ~50% gas vs full metadata)
+     * - Rich metadata is stored on Walrus blob
+     * - Only need basic filtering (category, vector_id, importance)
+     *
+     * @param options - Lightweight memory creation options
+     * @returns Transaction to create lightweight memory record
+     */
+    buildCreateMemoryRecordLightweight(options: CreateMemoryRecordLightweightTxOptions): Transaction;
+    /**
+     * Build transaction to update memory metadata
+     */
+    buildUpdateMemoryMetadata(options: UpdateMemoryMetadataTxOptions): Transaction;
+    /**
+     * Build transaction for comprehensive memory record update
+     *
+     * Updates multiple fields of a Memory object in a single transaction.
+     * Only non-empty/non-zero values will be updated on-chain.
+     *
+     * @param options - Update options with memoryId and fields to update
+     * @returns Transaction to update memory record
+     */
+    buildUpdateMemoryRecord(options: UpdateMemoryRecordTxOptions): Transaction;
+    /**
+     * Build transaction to delete a memory record
+     */
+    buildDeleteMemoryRecord(options: DeleteMemoryRecordTxOptions): Transaction;
+    /**
+     * Build transaction to create a memory index
+     *
+     * Smart contract signature:
+     * ```move
+     * public entry fun create_memory_index(
+     *     index_blob_id: vector<u8>,
+     *     graph_blob_id: vector<u8>,
+     *     ctx: &mut tx_context::TxContext
+     * )
+     * ```
+     */
+    buildCreateMemoryIndex(options: CreateMemoryIndexTxOptions): Transaction;
+    /**
+     * Build transaction to update a memory index
+     *
+     * Smart contract signature:
+     * ```move
+     * public entry fun update_memory_index(
+     *     memory_index: &mut MemoryIndex,
+     *     expected_version: u64,
+     *     new_index_blob_id: vector<u8>,
+     *     new_graph_blob_id: vector<u8>,
+     *     ctx: &tx_context::TxContext
+     * )
+     * ```
+     *
+     * @param options - Update options including indexId (object ID), expectedVersion, and new blob IDs
+     */
+    buildUpdateMemoryIndex(options: UpdateMemoryIndexTxOptions): Transaction;
+    /**
+     * Build transaction to grant access to content
+     */
+    buildGrantAccess(options: GrantAccessTxOptions): Transaction;
+    /**
+     * Build transaction to revoke access from content
+     */
+    buildRevokeAccess(options: RevokeAccessTxOptions): Transaction;
+    /**
+     * Build transaction to register content for access control
+     */
+    buildRegisterContent(options: RegisterContentTxOptions): Transaction;
+    /**
+     * Execute a transaction using SerialTransactionExecutor with automatic retry.
+     *
+     * The executor automatically:
+     * - Caches object versions to prevent version conflicts within same session
+     * - Manages gas coins to prevent equivocation (24h lock)
+     * - Queues transactions sequentially for safe execution
+     *
+     * When version conflict occurs (external modification), the executor cache
+     * is reset and transaction is retried with fresh object references.
+     *
+     * @see https://sdk.mystenlabs.com/typescript/executors
+     * @see https://docs.sui.io/concepts/sui-architecture/epochs#equivocation
+     */
+    executeTransaction(tx: Transaction, signer: any, options?: TransactionOptions): Promise<TransactionResult>;
+    /**
+     * Execute a transaction directly without the executor (legacy method).
+     * Use this only when you need direct control over execution or for one-off transactions.
+     *
+     * WARNING: This method does not protect against equivocation.
+     * For sequential transactions, use executeTransaction() instead.
+     */
+    executeTransactionDirect(tx: Transaction, signer: any, options?: TransactionOptions): Promise<TransactionResult>;
+    /**
+     * Create and execute a memory record transaction
+     */
+    createMemoryRecord(options: CreateMemoryRecordTxOptions, signer: any): Promise<TransactionResult>;
+    /**
+     * Create and execute an update memory metadata transaction
+     */
+    updateMemoryMetadata(options: UpdateMemoryMetadataTxOptions, signer: any): Promise<TransactionResult>;
+    /**
+     * Create and execute a delete memory record transaction
+     */
+    deleteMemoryRecord(options: DeleteMemoryRecordTxOptions, signer: any): Promise<TransactionResult>;
+    /**
+     * Create and execute a grant access transaction
+     */
+    grantAccess(options: GrantAccessTxOptions, signer: any): Promise<TransactionResult>;
+    /**
+     * Create and execute a revoke access transaction
+     */
+    revokeAccess(options: RevokeAccessTxOptions, signer: any): Promise<TransactionResult>;
+    /**
+     * Build a batch transaction combining multiple operations
+     *
+     * Access control uses capability-based pattern:
+     * - createCap: Create a new MemoryCap for an app context
+     * - transferCap: Transfer capability to recipient (grants access)
+     * - burnCap: Burn capability (revokes access permanently)
+     */
+    buildBatchTransaction(operations: Array<{
+        type: 'createMemory' | 'updateMemory' | 'deleteMemory' | 'createCap' | 'transferCap' | 'burnCap';
+        options: any;
+    }>): Transaction;
+    /**
+     * Execute a batch transaction
+     */
+    executeBatch(operations: Array<{
+        type: 'createMemory' | 'updateMemory' | 'deleteMemory' | 'createCap' | 'transferCap' | 'burnCap';
+        options: any;
+    }>, signer: any, txOptions?: TransactionOptions): Promise<TransactionResult>;
+    /**
+     * Estimate gas cost for a transaction
+     */
+    estimateGas(tx: Transaction, signer: any): Promise<number>;
+    /**
+     * Get recommended gas budget based on transaction complexity
+     */
+    getRecommendedGasBudget(operationCount?: number): number;
+}
+//# sourceMappingURL=TransactionService.d.ts.map

package/dist/services/TransactionService.d.ts.map

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