@totemsdk/core 1.0.9 → 1.0.11

package/src/tx/TransactionLifecycle.d.ts

@@ -1,55 +0,0 @@
-/**
- * @module TransactionLifecycle
- * Orchestrates the complete transaction flow with lease and watermark management
- *
- * Integrates:
- * - TransactionService for RPC calls
- * - LeaseStore for lease persistence
- * - WatermarkStore for index tracking
- * - TransactionReceiptStore for history
- */
-import type { LoggerAdapter, MetricsAdapter } from '../adapters';
-import type { LeaseStore, WatermarkStore } from '../lease';
-import type { TransactionService } from './TransactionService';
-import type { TransactionReceiptStore } from './TransactionReceiptStore';
-import type { PrepareRequest, PrepareResponse, FinalizeResponse, TransactionMetadata, SignResult } from './types';
-import type { WotsSigningDependencies } from './TransactionService';
-export declare class TransactionLifecycleError extends Error {
-    code: number;
-    userMessage: string;
-    constructor(message: string, code: number, userMessage: string);
-}
-export declare class WatermarkExhaustedError extends Error {
-    constructor();
-}
-export interface TransactionLifecycleConfig {
-    validateWatermarkBeforePrepare?: boolean;
-    syncWatermarkBeforePrepare?: boolean;
-}
-export interface WatermarkSyncFunction {
-    (rootPublicKey: string): Promise<{
-        updated: boolean;
-        multiDeviceConflict: boolean;
-    }>;
-}
-export interface PrepareResult extends PrepareResponse {
-    metadata: TransactionMetadata;
-}
-export declare class TransactionLifecycle {
-    private readonly txService;
-    private readonly leaseStore;
-    private readonly watermarkStore;
-    private readonly receiptStore;
-    private readonly logger;
-    private readonly metrics;
-    private readonly config;
-    private syncWatermark?;
-    constructor(txService: TransactionService, leaseStore: LeaseStore, watermarkStore: WatermarkStore, receiptStore: TransactionReceiptStore, logger?: LoggerAdapter, metrics?: MetricsAdapter, config?: TransactionLifecycleConfig);
-    setSyncWatermarkFunction(fn: WatermarkSyncFunction): void;
-    prepare(params: PrepareRequest, rootPublicKey: string): Promise<PrepareResult>;
-    sign(prepareResult: PrepareResult, seed: Uint8Array, deps: WotsSigningDependencies, paramSetName?: string): Promise<SignResult>;
-    finalize(leaseToken: string, signedHex: string, metadata: TransactionMetadata): Promise<FinalizeResponse>;
-    cancelLease(leaseToken: string): Promise<void>;
-    private validateWatermark;
-    private parseAxiaError;
-}

package/src/tx/TransactionLifecycle.js

@@ -1,188 +0,0 @@
-"use strict";
-/**
- * @module TransactionLifecycle
- * Orchestrates the complete transaction flow with lease and watermark management
- *
- * Integrates:
- * - TransactionService for RPC calls
- * - LeaseStore for lease persistence
- * - WatermarkStore for index tracking
- * - TransactionReceiptStore for history
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TransactionLifecycle = exports.WatermarkExhaustedError = exports.TransactionLifecycleError = void 0;
-const adapters_1 = require("../adapters");
-class TransactionLifecycleError extends Error {
-    constructor(message, code, userMessage) {
-        super(message);
-        this.code = code;
-        this.userMessage = userMessage;
-        this.name = 'TransactionLifecycleError';
-    }
-}
-exports.TransactionLifecycleError = TransactionLifecycleError;
-class WatermarkExhaustedError extends Error {
-    constructor() {
-        super('All WOTS signatures have been used. Please create a new wallet.');
-        this.name = 'WatermarkExhaustedError';
-    }
-}
-exports.WatermarkExhaustedError = WatermarkExhaustedError;
-class TransactionLifecycle {
-    constructor(txService, leaseStore, watermarkStore, receiptStore, logger = new adapters_1.NoopLogger(), metrics = new adapters_1.NoopMetrics(), config = {}) {
-        this.txService = txService;
-        this.leaseStore = leaseStore;
-        this.watermarkStore = watermarkStore;
-        this.receiptStore = receiptStore;
-        this.logger = logger;
-        this.metrics = metrics;
-        this.config = {
-            validateWatermarkBeforePrepare: config.validateWatermarkBeforePrepare ?? true,
-            syncWatermarkBeforePrepare: config.syncWatermarkBeforePrepare ?? true,
-        };
-    }
-    setSyncWatermarkFunction(fn) {
-        this.syncWatermark = fn;
-    }
-    async prepare(params, rootPublicKey) {
-        if (this.config.validateWatermarkBeforePrepare) {
-            await this.validateWatermark(rootPublicKey);
-        }
-        try {
-            const result = await this.txService.prepare(params, rootPublicKey);
-            await this.leaseStore.save({
-                leaseId: result.leaseId,
-                leaseToken: result.leaseToken,
-                indices: { addressIndex: result.addressIndex, l1: result.l1, l2: result.l2 },
-                expiresAt: Date.now() + (result.leaseTTL * 1000),
-                status: 'active',
-                createdAt: Date.now(),
-                txId: result.txId,
-                leaseTTL: result.leaseTTL,
-            });
-            this.logger.debug(`Lease persisted: ${result.leaseId}`);
-            return {
-                ...result,
-                metadata: {
-                    to: params.to,
-                    amount: params.amount,
-                    tokenId: params.tokenId || '0x00',
-                },
-            };
-        }
-        catch (error) {
-            const parsed = this.parseAxiaError(error);
-            throw new TransactionLifecycleError(error.message, parsed.code, parsed.userMessage);
-        }
-    }
-    async sign(prepareResult, seed, deps, paramSetName) {
-        const request = {
-            addressIndex: prepareResult.addressIndex,
-            l1: prepareResult.l1,
-            l2: prepareResult.l2,
-            digestTx: prepareResult.digestTx,
-        };
-        return this.txService.sign(request, seed, deps, paramSetName);
-    }
-    async finalize(leaseToken, signedHex, metadata) {
-        const lease = this.leaseStore.getByToken(leaseToken);
-        if (!lease) {
-            throw new TransactionLifecycleError('Lease not found', 404, 'Transaction lease not found. Please try again.');
-        }
-        try {
-            const result = await this.txService.finalize({ leaseToken, signedHex });
-            await this.watermarkStore.markUsed(lease.indices);
-            await this.watermarkStore.advanceWatermark(lease.indices);
-            await this.receiptStore.initialize();
-            await this.receiptStore.add({
-                txpowid: result.txpowid,
-                timestamp: Date.now(),
-                to: metadata.to,
-                amount: metadata.amount,
-                tokenId: metadata.tokenId,
-                indices: lease.indices,
-                status: 'confirmed',
-                txId: lease.txId,
-                leaseId: lease.leaseId,
-            });
-            await this.leaseStore.updateStatus(lease.leaseId, 'finalized');
-            await this.leaseStore.delete(lease.leaseId);
-            this.logger.debug(`Transaction finalized: ${result.txpowid}`);
-            this.logger.debug('Watermark advanced and receipt stored');
-            return result;
-        }
-        catch (error) {
-            const parsed = this.parseAxiaError(error);
-            throw new TransactionLifecycleError(error.message, parsed.code, parsed.userMessage);
-        }
-    }
-    async cancelLease(leaseToken) {
-        const lease = this.leaseStore.getByToken(leaseToken);
-        if (lease) {
-            await this.leaseStore.updateStatus(lease.leaseId, 'cancelled');
-            await this.leaseStore.delete(lease.leaseId);
-            this.logger.debug(`Lease cancelled: ${lease.leaseId}`);
-        }
-    }
-    async validateWatermark(rootPublicKey) {
-        if (!this.watermarkStore.isInitialized()) {
-            await this.watermarkStore.initialize();
-        }
-        if (this.watermarkStore.isExhausted()) {
-            throw new WatermarkExhaustedError();
-        }
-        if (this.config.syncWatermarkBeforePrepare && this.syncWatermark) {
-            try {
-                this.logger.debug('Syncing watermark before transaction prepare...');
-                const syncResult = await this.syncWatermark(rootPublicKey);
-                if (syncResult.updated) {
-                    this.logger.debug('Watermark synced before prepare');
-                }
-                if (syncResult.multiDeviceConflict) {
-                    this.logger.warn('Multi-device conflict detected before prepare');
-                }
-                if (this.watermarkStore.isExhausted()) {
-                    throw new WatermarkExhaustedError();
-                }
-            }
-            catch (error) {
-                if (error instanceof WatermarkExhaustedError) {
-                    throw error;
-                }
-                this.logger.warn('Watermark sync failed before prepare:', error);
-            }
-        }
-    }
-    parseAxiaError(error) {
-        const message = error.message || error.toString();
-        if (message.includes('403') || error.code === 403) {
-            return {
-                code: 403,
-                userMessage: 'Access denied. Your project may not have permission for this operation.',
-            };
-        }
-        if (message.includes('409') || error.code === 409) {
-            return {
-                code: 409,
-                userMessage: 'WOTS indices exhausted. Please create a new wallet.',
-            };
-        }
-        if (message.includes('410') || error.code === 410) {
-            return {
-                code: 410,
-                userMessage: 'Transaction lease expired. Please try again.',
-            };
-        }
-        if (message.includes('502') || error.code === 502) {
-            return {
-                code: 502,
-                userMessage: 'Failed to post transaction to network. Please try again.',
-            };
-        }
-        return {
-            code: 500,
-            userMessage: 'An error occurred. Please try again.',
-        };
-    }
-}
-exports.TransactionLifecycle = TransactionLifecycle;

package/src/tx/TransactionLifecycle.ts

@@ -1,280 +0,0 @@
-/**
- * @module TransactionLifecycle
- * Orchestrates the complete transaction flow with lease and watermark management
- * 
- * Integrates:
- * - TransactionService for RPC calls
- * - LeaseStore for lease persistence
- * - WatermarkStore for index tracking
- * - TransactionReceiptStore for history
- */
-
-import type { LoggerAdapter, MetricsAdapter } from '../adapters/index.js';
-import { NoopLogger, NoopMetrics } from '../adapters/index.js';
-import type { LeaseStore, WatermarkStore, WotsIndices } from '../lease/index.js';
-import type { TransactionService } from './TransactionService.js';
-import type { TransactionReceiptStore } from './TransactionReceiptStore.js';
-import type {
-  PrepareRequest,
-  PrepareResponse,
-  FinalizeResponse,
-  TransactionMetadata,
-  SignRequest,
-  SignResult,
-} from './types.js';
-import type { WotsSigningDependencies } from './TransactionService.js';
-
-export class TransactionLifecycleError extends Error {
-  constructor(
-    message: string,
-    public code: number,
-    public userMessage: string
-  ) {
-    super(message);
-    this.name = 'TransactionLifecycleError';
-  }
-}
-
-export class WatermarkExhaustedError extends Error {
-  constructor() {
-    super('All WOTS signatures have been used. Please create a new wallet.');
-    this.name = 'WatermarkExhaustedError';
-  }
-}
-
-export interface TransactionLifecycleConfig {
-  validateWatermarkBeforePrepare?: boolean;
-  syncWatermarkBeforePrepare?: boolean;
-}
-
-export interface WatermarkSyncFunction {
-  (rootPublicKey: string): Promise<{ updated: boolean; multiDeviceConflict: boolean }>;
-}
-
-export interface PrepareResult extends PrepareResponse {
-  metadata: TransactionMetadata;
-}
-
-export class TransactionLifecycle {
-  private readonly txService: TransactionService;
-  private readonly leaseStore: LeaseStore;
-  private readonly watermarkStore: WatermarkStore;
-  private readonly receiptStore: TransactionReceiptStore;
-  private readonly logger: LoggerAdapter;
-  private readonly metrics: MetricsAdapter;
-  private readonly config: Required<TransactionLifecycleConfig>;
-  private syncWatermark?: WatermarkSyncFunction;
-
-  constructor(
-    txService: TransactionService,
-    leaseStore: LeaseStore,
-    watermarkStore: WatermarkStore,
-    receiptStore: TransactionReceiptStore,
-    logger: LoggerAdapter = new NoopLogger(),
-    metrics: MetricsAdapter = new NoopMetrics(),
-    config: TransactionLifecycleConfig = {}
-  ) {
-    this.txService = txService;
-    this.leaseStore = leaseStore;
-    this.watermarkStore = watermarkStore;
-    this.receiptStore = receiptStore;
-    this.logger = logger;
-    this.metrics = metrics;
-    this.config = {
-      validateWatermarkBeforePrepare: config.validateWatermarkBeforePrepare ?? true,
-      syncWatermarkBeforePrepare: config.syncWatermarkBeforePrepare ?? true,
-    };
-  }
-
-  setSyncWatermarkFunction(fn: WatermarkSyncFunction): void {
-    this.syncWatermark = fn;
-  }
-
-  async prepare(
-    params: PrepareRequest,
-    rootPublicKey: string
-  ): Promise<PrepareResult> {
-    if (this.config.validateWatermarkBeforePrepare) {
-      await this.validateWatermark(rootPublicKey);
-    }
-
-    try {
-      const result = await this.txService.prepare(params, rootPublicKey);
-
-      await this.leaseStore.save({
-        leaseId: result.leaseId,
-        leaseToken: result.leaseToken,
-        indices: { addressIndex: result.addressIndex, l1: result.l1, l2: result.l2 },
-        expiresAt: Date.now() + result.leaseTTL,
-        status: 'active',
-        createdAt: Date.now(),
-        txId: result.txId,
-        leaseTTL: result.leaseTTL,
-      });
-
-      this.logger.debug(`Lease persisted: ${result.leaseId}`);
-
-      return {
-        ...result,
-        metadata: {
-          to: params.to,
-          amount: params.amount,
-          tokenId: params.tokenId || '0x00',
-        },
-      };
-    } catch (error: any) {
-      const parsed = this.parseAxiaError(error);
-      throw new TransactionLifecycleError(error.message, parsed.code, parsed.userMessage);
-    }
-  }
-
-  async sign(
-    prepareResult: PrepareResult,
-    seed: Uint8Array,
-    deps: WotsSigningDependencies,
-    paramSetName?: string
-  ): Promise<SignResult> {
-    const request: SignRequest = {
-      addressIndex: prepareResult.addressIndex,
-      l1: prepareResult.l1,
-      l2: prepareResult.l2,
-      digestTx: prepareResult.digestTx,
-    };
-
-    return this.txService.sign(request, seed, deps, paramSetName);
-  }
-
-  async finalize(
-    leaseToken: string,
-    signedHex: string,
-    metadata: TransactionMetadata
-  ): Promise<FinalizeResponse> {
-    const lease = this.leaseStore.getByToken(leaseToken);
-    if (!lease) {
-      throw new TransactionLifecycleError(
-        'Lease not found',
-        404,
-        'Transaction lease not found. Please try again.'
-      );
-    }
-
-    try {
-      const result = await this.txService.finalize({ leaseToken, signedHex });
-
-      await this.watermarkStore.markUsed(lease.indices);
-      await this.watermarkStore.advanceWatermark(lease.indices);
-
-      await this.receiptStore.initialize();
-      await this.receiptStore.add({
-        txpowid: result.txpowid,
-        timestamp: Date.now(),
-        to: metadata.to,
-        amount: metadata.amount,
-        tokenId: metadata.tokenId,
-        indices: lease.indices,
-        status: 'confirmed',
-        txId: lease.txId,
-        leaseId: lease.leaseId,
-      });
-
-      await this.leaseStore.updateStatus(lease.leaseId, 'finalized');
-      await this.leaseStore.delete(lease.leaseId);
-
-      this.logger.debug(`Transaction finalized: ${result.txpowid}`);
-      this.logger.debug('Watermark advanced and receipt stored');
-
-      return result;
-    } catch (error: any) {
-      const parsed = this.parseAxiaError(error);
-      throw new TransactionLifecycleError(error.message, parsed.code, parsed.userMessage);
-    }
-  }
-
-  async cancelLease(leaseToken: string): Promise<void> {
-    const lease = this.leaseStore.getByToken(leaseToken);
-    if (lease) {
-      await this.leaseStore.updateStatus(lease.leaseId, 'cancelled');
-      await this.leaseStore.delete(lease.leaseId);
-      this.logger.debug(`Lease cancelled: ${lease.leaseId}`);
-    }
-  }
-
-  private async validateWatermark(rootPublicKey: string): Promise<void> {
-    if (!this.watermarkStore.isInitialized()) {
-      await this.watermarkStore.initialize();
-    }
-
-    if (this.watermarkStore.isExhausted()) {
-      throw new WatermarkExhaustedError();
-    }
-
-    if (this.config.syncWatermarkBeforePrepare && this.syncWatermark) {
-      try {
-        this.logger.debug('Syncing watermark before transaction prepare...');
-        const syncResult = await this.syncWatermark(rootPublicKey);
-
-        if (syncResult.updated) {
-          this.logger.debug('Watermark synced before prepare');
-        }
-
-        if (syncResult.multiDeviceConflict) {
-          this.logger.warn('Multi-device conflict detected before prepare');
-        }
-
-        if (this.watermarkStore.isExhausted()) {
-          throw new WatermarkExhaustedError();
-        }
-      } catch (error) {
-        if (error instanceof WatermarkExhaustedError) {
-          throw error;
-        }
-        this.logger.warn('Watermark sync failed before prepare:', error);
-      }
-    }
-  }
-
-  private parseAxiaError(error: any): { code: number; userMessage: string } {
-    const message = error.message || error.toString();
-
-    if (error?.code === 429) {
-      const limit = error.limit ?? 10;
-      return {
-        code: 429,
-        userMessage: `Daily signing limit reached (${limit}/day). Resets at midnight UTC.`,
-      };
-    }
-
-    if (message.includes('403') || error.code === 403) {
-      return {
-        code: 403,
-        userMessage: 'Access denied. Your project may not have permission for this operation.',
-      };
-    }
-
-    if (message.includes('409') || error.code === 409) {
-      return {
-        code: 409,
-        userMessage: 'WOTS indices exhausted. Please create a new wallet.',
-      };
-    }
-
-    if (message.includes('410') || error.code === 410) {
-      return {
-        code: 410,
-        userMessage: 'Transaction lease expired. Please try again.',
-      };
-    }
-
-    if (message.includes('502') || error.code === 502) {
-      return {
-        code: 502,
-        userMessage: 'Failed to post transaction to network. Please try again.',
-      };
-    }
-
-    return {
-      code: 500,
-      userMessage: 'An error occurred. Please try again.',
-    };
-  }
-}

package/src/tx/TransactionReceiptStore.d.ts

@@ -1,36 +0,0 @@
-/**
- * @module TransactionReceiptStore
- * Persistent storage for transaction receipts
- *
- * Uses in-memory cache backed by persistent storage.
- * Pattern:
- * - initialize() loads from storage into memory cache
- * - Sync getters read from memory cache (fast, no I/O)
- * - Mutators update memory cache AND persist to storage
- */
-import type { StorageAdapter, LoggerAdapter } from '../adapters';
-import type { TransactionReceipt } from './types';
-export interface TransactionReceiptStoreConfig {
-    storageKey?: string;
-    maxReceipts?: number;
-}
-export declare class TransactionReceiptStore {
-    private receipts;
-    private _initialized;
-    private readonly storageKey;
-    private readonly maxReceipts;
-    private readonly storage;
-    private readonly logger;
-    constructor(storage: StorageAdapter, logger?: LoggerAdapter, config?: TransactionReceiptStoreConfig);
-    initialize(): Promise<void>;
-    isInitialized(): boolean;
-    private load;
-    private persist;
-    add(receipt: TransactionReceipt): Promise<void>;
-    getAll(): TransactionReceipt[];
-    getByTxpowid(txpowid: string): TransactionReceipt | undefined;
-    getRecent(count?: number): TransactionReceipt[];
-    updateStatus(txpowid: string, status: TransactionReceipt['status']): Promise<void>;
-    clear(): Promise<void>;
-    count(): number;
-}

package/src/tx/TransactionReceiptStore.js

@@ -1,89 +0,0 @@
-"use strict";
-/**
- * @module TransactionReceiptStore
- * Persistent storage for transaction receipts
- *
- * Uses in-memory cache backed by persistent storage.
- * Pattern:
- * - initialize() loads from storage into memory cache
- * - Sync getters read from memory cache (fast, no I/O)
- * - Mutators update memory cache AND persist to storage
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TransactionReceiptStore = void 0;
-const adapters_1 = require("../adapters");
-const DEFAULT_STORAGE_KEY = 'totem_transaction_receipts';
-const DEFAULT_MAX_RECEIPTS = 1000;
-class TransactionReceiptStore {
-    constructor(storage, logger = new adapters_1.NoopLogger(), config = {}) {
-        this.receipts = [];
-        this._initialized = false;
-        this.storage = storage;
-        this.logger = logger;
-        this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;
-        this.maxReceipts = config.maxReceipts ?? DEFAULT_MAX_RECEIPTS;
-    }
-    async initialize() {
-        if (this._initialized)
-            return;
-        await this.load();
-        this._initialized = true;
-    }
-    isInitialized() {
-        return this._initialized;
-    }
-    async load() {
-        try {
-            const receipts = await this.storage.get(this.storageKey);
-            if (receipts) {
-                this.receipts = receipts;
-                this.logger.debug(`Loaded ${this.receipts.length} transaction receipts`);
-            }
-        }
-        catch (error) {
-            this.logger.error('Failed to load receipts:', error);
-        }
-    }
-    async persist() {
-        try {
-            const trimmedReceipts = this.receipts.slice(-this.maxReceipts);
-            await this.storage.set(this.storageKey, trimmedReceipts);
-            this.receipts = trimmedReceipts;
-        }
-        catch (error) {
-            this.logger.error('Failed to persist receipts:', error);
-            throw error;
-        }
-    }
-    async add(receipt) {
-        this.receipts.push(receipt);
-        this.logger.debug(`Added receipt: ${receipt.txpowid}`);
-        await this.persist();
-    }
-    getAll() {
-        return [...this.receipts].reverse();
-    }
-    getByTxpowid(txpowid) {
-        return this.receipts.find(r => r.txpowid === txpowid);
-    }
-    getRecent(count = 50) {
-        return this.getAll().slice(0, count);
-    }
-    async updateStatus(txpowid, status) {
-        const receipt = this.receipts.find(r => r.txpowid === txpowid);
-        if (receipt) {
-            receipt.status = status;
-            this.logger.debug(`Updated receipt status: ${txpowid} → ${status}`);
-            await this.persist();
-        }
-    }
-    async clear() {
-        this.receipts = [];
-        await this.storage.remove(this.storageKey);
-        this.logger.debug('Cleared all receipts');
-    }
-    count() {
-        return this.receipts.length;
-    }
-}
-exports.TransactionReceiptStore = TransactionReceiptStore;