@totemsdk/core 1.2.6 → 1.2.7

package/dist/cjs/tx/TransactionLifecycle.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 type { LeaseStore, WatermarkStore } from '../lease/index.js';
+import type { TransactionService } from './TransactionService.js';
+import type { TransactionReceiptStore } from './TransactionReceiptStore.js';
+import type { PrepareRequest, PrepareResponse, FinalizeResponse, TransactionMetadata, SignResult } from './types.js';
+import type { WotsSigningDependencies } from './TransactionService.js';
+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/dist/cjs/tx/TransactionLifecycle.js

@@ -0,0 +1,205 @@
+"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 index_js_1 = require("../adapters/index.js");
+class TransactionLifecycleError extends Error {
+    code;
+    userMessage;
+    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 {
+    txService;
+    leaseStore;
+    watermarkStore;
+    receiptStore;
+    logger;
+    metrics;
+    config;
+    syncWatermark;
+    constructor(txService, leaseStore, watermarkStore, receiptStore, logger = new index_js_1.NoopLogger(), metrics = new index_js_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,
+                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 (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.',
+        };
+    }
+}
+exports.TransactionLifecycle = TransactionLifecycle;

package/dist/cjs/tx/TransactionReceiptStore.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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/index.js';
+import type { TransactionReceipt } from './types.js';
+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/dist/cjs/tx/TransactionReceiptStore.js

@@ -0,0 +1,93 @@
+"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 index_js_1 = require("../adapters/index.js");
+const DEFAULT_STORAGE_KEY = 'totem_transaction_receipts';
+const DEFAULT_MAX_RECEIPTS = 1000;
+class TransactionReceiptStore {
+    receipts = [];
+    _initialized = false;
+    storageKey;
+    maxReceipts;
+    storage;
+    logger;
+    constructor(storage, logger = new index_js_1.NoopLogger(), config = {}) {
+        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;

package/dist/cjs/tx/TransactionService.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module TransactionService
+ * Handles WOTS signing flow: prepare → sign → finalize
+ *
+ * Platform-agnostic implementation using HttpClient adapter.
+ *
+ * Sign architecture (2026-02): uses per-address TreeKey (depth=3, keysPerLevel=64)
+ * matching Minima Wallet.java exactly. Each address has its own TreeKey derived
+ * from the wallet seed. Signing produces 3 proofs (Root→L1→L2→DATA).
+ */
+import type { HttpClient, LoggerAdapter, MetricsAdapter } from '../adapters/index.js';
+import type { PrepareRequest, PrepareResponse, SignRequest, SignResult, FinalizeRequest, FinalizeResponse } from './types.js';
+export interface TransactionServiceConfig {
+    baseUrl: string;
+    apiKey: string;
+    paramSet?: string;
+}
+/**
+ * @deprecated WotsSigningDependencies is no longer used by TransactionService.sign().
+ * The service now derives everything from the seed and indices directly using
+ * the built-in TreeKey implementation. This interface is kept for backward compatibility
+ * only and will be removed in a future version.
+ */
+export interface WotsSigningDependencies {
+    wotsSign?: (seed: Uint8Array, index: number, message: Uint8Array, paramSet: any) => Uint8Array;
+    fromHex?: (hex: string) => Uint8Array;
+    getParamSet?: (name: string) => any;
+    defaultParamSet?: any;
+}
+export declare class TransactionService {
+    private readonly http;
+    private readonly logger;
+    private readonly metrics;
+    private readonly config;
+    constructor(http: HttpClient, config: TransactionServiceConfig, logger?: LoggerAdapter, metrics?: MetricsAdapter);
+    prepare(params: PrepareRequest, rootPublicKey: string): Promise<PrepareResponse>;
+    /**
+     * Sign a transaction using per-address TreeKey architecture.
+     *
+     * Produces 3 proofs (Root→L1→L2→DATA) matching Minima's TreeKey.sign() exactly.
+     *
+     * @param request    - Indices and digestTx from the /prepare response
+     * @param seed       - 32-byte wallet base seed (from mnemonic)
+     * @param _deps      - Deprecated, unused. Pass null or omit.
+     * @param _paramSet  - Deprecated, unused. TreeKey uses its own param set.
+     */
+    sign(request: SignRequest, seed: Uint8Array, _deps?: WotsSigningDependencies | null, _paramSet?: string): Promise<SignResult>;
+    finalize(params: FinalizeRequest): Promise<FinalizeResponse>;
+    private bytesToHex;
+}

package/dist/cjs/tx/TransactionService.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * @module TransactionService
+ * Handles WOTS signing flow: prepare → sign → finalize
+ *
+ * Platform-agnostic implementation using HttpClient adapter.
+ *
+ * Sign architecture (2026-02): uses per-address TreeKey (depth=3, keysPerLevel=64)
+ * matching Minima Wallet.java exactly. Each address has its own TreeKey derived
+ * from the wallet seed. Signing produces 3 proofs (Root→L1→L2→DATA).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionService = void 0;
+const index_js_1 = require("../adapters/index.js");
+const treekey_js_1 = require("../treekey.js");
+const mmr_js_1 = require("../mmr.js");
+const wots_js_1 = require("../wots.js");
+class TransactionService {
+    http;
+    logger;
+    metrics;
+    config;
+    constructor(http, config, logger = new index_js_1.NoopLogger(), metrics = new index_js_1.NoopMetrics()) {
+        this.http = http;
+        this.config = config;
+        this.logger = logger;
+        this.metrics = metrics;
+    }
+    async prepare(params, rootPublicKey) {
+        const startTime = Date.now();
+        const url = `${this.config.baseUrl.replace(/\/$/, '')}/v1/wots-hardened/prepare`;
+        const txId = params.txId || `tx-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        this.logger.debug('Requesting lease for transaction...');
+        this.logger.debug(`  txId: ${txId}, to: ${params.to}, amount: ${params.amount}`);
+        if (typeof params.addressIndex !== 'number' || params.addressIndex < 0 || params.addressIndex >= 64) {
+            throw new Error('params.addressIndex is required and must be 0-63');
+        }
+        try {
+            const response = await this.http.post(url, {
+                txId,
+                rootPublicKey,
+                to: params.to,
+                amount: params.amount,
+                tokenId: params.tokenId || '0x00',
+                burn: params.burn || null,
+                paramSet: this.config.paramSet || 'v2-spec',
+                addressIndex: params.addressIndex,
+            }, {
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.config.apiKey,
+                },
+            });
+            if (response.status === 429) {
+                const body = response.data;
+                const err = new Error(body?.error || 'Daily signing limit reached');
+                err.code = 429;
+                err.limit = body?.limit;
+                err.used = body?.used;
+                err.retryAfter = body?.retryAfter;
+                throw err;
+            }
+            if (!response.ok) {
+                const body = response.data;
+                const msg = body?.error || body?.message || `HTTP ${response.status}`;
+                const err = new Error(msg);
+                err.code = response.status;
+                throw err;
+            }
+            const result = response.data;
+            const elapsed = Date.now() - startTime;
+            this.metrics.timing('tx_prepare_duration_ms', elapsed);
+            this.metrics.increment('tx_prepare_success');
+            this.logger.debug(`Lease acquired (${elapsed}ms)`);
+            this.logger.debug(`  leaseId: ${result.leaseId}`);
+            this.logger.debug(`  indices: (addressIndex=${result.addressIndex}, l1=${result.l1}, l2=${result.l2})`);
+            this.logger.debug(`  TTL: ${result.leaseTTL}ms`);
+            return result;
+        }
+        catch (error) {
+            if (error.code === 429 || error.code === 400 || error.code === 403 || error.code === 409) {
+                throw error;
+            }
+            this.metrics.increment('tx_prepare_error');
+            this.logger.error('Lease acquisition failed:', error);
+            throw error;
+        }
+    }
+    /**
+     * Sign a transaction using per-address TreeKey architecture.
+     *
+     * Produces 3 proofs (Root→L1→L2→DATA) matching Minima's TreeKey.sign() exactly.
+     *
+     * @param request    - Indices and digestTx from the /prepare response
+     * @param seed       - 32-byte wallet base seed (from mnemonic)
+     * @param _deps      - Deprecated, unused. Pass null or omit.
+     * @param _paramSet  - Deprecated, unused. TreeKey uses its own param set.
+     */
+    async sign(request, seed, _deps, _paramSet) {
+        const startTime = Date.now();
+        const { addressIndex, l1, l2, digestTx } = request;
+        this.logger.debug('Starting per-address TreeKey signing...');
+        this.logger.debug(`  indices: (addressIndex=${addressIndex}, l1=${l1}, l2=${l2})`);
+        if (addressIndex < 0 || addressIndex >= 64) {
+            throw new Error(`Invalid addressIndex: ${addressIndex}. Must be 0-63.`);
+        }
+        const digestBytes = (0, wots_js_1.fromHex)(digestTx);
+        if (digestBytes.length !== 32) {
+            throw new Error(`Invalid digest length: ${digestBytes.length}, expected 32 bytes`);
+        }
+        // Derive unified child TreeKey for this address index
+        this.logger.debug(`  Deriving unified child TreeKey for index ${addressIndex}...`);
+        const treeKey = (0, treekey_js_1.createUnifiedChildTreeKey)(seed, addressIndex);
+        // Convert (l1, l2) to Java-compatible 'uses' counter
+        // Java's TreeKey.sign() uses baseConversion(uses) to compute path
+        const KEYS_PER_LEVEL = 64;
+        const uses = l1 * KEYS_PER_LEVEL + l2;
+        this.logger.debug(`  Converting indices to uses: (l1=${l1}, l2=${l2}) → uses=${uses}`);
+        // setUses() + sign() matches Java pattern: tk.setUses(uses) → tk.sign(zData)
+        treeKey.setUses(uses);
+        const treeSignature = treeKey.sign(digestBytes);
+        const newUses = treeKey.getUses();
+        this.logger.debug(`  TreeKey signing complete, proofs: ${treeSignature.proofs.length}, newUses: ${newUses}`);
+        // Build HierarchicalWitnessBundle with unified naming
+        const treeKeyPubkey = treeKey.getPublicKey();
+        const witnessBundle = {
+            addressIndex,
+            l1,
+            l2,
+            rootPublicKey: `0x${this.bytesToHex(treeKeyPubkey)}`,
+            proofs: treeSignature.proofs.map((proof) => ({
+                leafPubkey: `0x${this.bytesToHex(proof.leafPubkey)}`,
+                signature: `0x${this.bytesToHex(proof.signature)}`,
+                mmrProof: `0x${this.bytesToHex((0, mmr_js_1.serializeMMRProof)(proof.mmrProof))}`,
+            })),
+        };
+        // Serialize to byte-exact Java-compatible wire format
+        const serializedBytes = (0, treekey_js_1.serializeTreeSignature)(treeSignature);
+        const signedHex = `0x${this.bytesToHex(serializedBytes)}`;
+        const elapsed = Date.now() - startTime;
+        this.metrics.timing('tx_sign_duration_ms', elapsed);
+        this.logger.debug(`Signature created (${elapsed}ms), serialized: ${serializedBytes.length} bytes`);
+        return { witnessBundle, signedHex };
+    }
+    async finalize(params) {
+        const startTime = Date.now();
+        const url = `${this.config.baseUrl.replace(/\/$/, '')}/v1/wots-hardened/finalize`;
+        this.logger.debug('Submitting signed transaction to network...');
+        this.logger.debug(`  leaseToken: ${params.leaseToken.slice(0, 16)}...`);
+        try {
+            const response = await this.http.post(url, params, {
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.config.apiKey,
+                },
+            });
+            if (!response.ok) {
+                const body = response.data;
+                const msg = body?.error || body?.message || `HTTP ${response.status}`;
+                const err = new Error(msg);
+                err.code = response.status;
+                throw err;
+            }
+            const result = response.data;
+            const elapsed = Date.now() - startTime;
+            this.metrics.timing('tx_finalize_duration_ms', elapsed);
+            this.metrics.increment('tx_finalize_success');
+            this.logger.debug(`Transaction finalized (${elapsed}ms)`);
+            this.logger.debug(`  txpowid: ${result.txpowid}, leaseId: ${result.leaseId}`);
+            return result;
+        }
+        catch (error) {
+            if (error.code !== undefined)
+                throw error;
+            this.metrics.increment('tx_finalize_error');
+            this.logger.error('Finalization failed:', error);
+            throw error;
+        }
+    }
+    bytesToHex(bytes) {
+        return Array.from(bytes)
+            .map(b => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+}
+exports.TransactionService = TransactionService;

package/dist/cjs/tx/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module @totemsdk/core/tx
+ * Transaction service and lifecycle management
+ *
+ * This module provides:
+ * - TransactionService: WOTS signing flow (prepare → sign → finalize)
+ * - TransactionLifecycle: Orchestrates flow with lease/watermark stores
+ * - TransactionReceiptStore: Persistent transaction history
+ */
+export { TransactionService, type TransactionServiceConfig, type WotsSigningDependencies, } from './TransactionService.js';
+export { TransactionLifecycle, TransactionLifecycleError, WatermarkExhaustedError, type TransactionLifecycleConfig, type WatermarkSyncFunction, type PrepareResult, } from './TransactionLifecycle.js';
+export { TransactionReceiptStore, type TransactionReceiptStoreConfig, } from './TransactionReceiptStore.js';
+export type { WotsIndices, PrepareRequest, PrepareResponse, SignRequest, SignResult, HierarchicalWitnessBundle, WitnessBundle, FinalizeRequest, FinalizeResponse, TransactionMetadata, TransactionReceipt, TransactionError, } from './types.js';

package/dist/cjs/tx/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @module @totemsdk/core/tx
+ * Transaction service and lifecycle management
+ *
+ * This module provides:
+ * - TransactionService: WOTS signing flow (prepare → sign → finalize)
+ * - TransactionLifecycle: Orchestrates flow with lease/watermark stores
+ * - TransactionReceiptStore: Persistent transaction history
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionReceiptStore = exports.WatermarkExhaustedError = exports.TransactionLifecycleError = exports.TransactionLifecycle = exports.TransactionService = void 0;
+var TransactionService_js_1 = require("./TransactionService.js");
+Object.defineProperty(exports, "TransactionService", { enumerable: true, get: function () { return TransactionService_js_1.TransactionService; } });
+var TransactionLifecycle_js_1 = require("./TransactionLifecycle.js");
+Object.defineProperty(exports, "TransactionLifecycle", { enumerable: true, get: function () { return TransactionLifecycle_js_1.TransactionLifecycle; } });
+Object.defineProperty(exports, "TransactionLifecycleError", { enumerable: true, get: function () { return TransactionLifecycle_js_1.TransactionLifecycleError; } });
+Object.defineProperty(exports, "WatermarkExhaustedError", { enumerable: true, get: function () { return TransactionLifecycle_js_1.WatermarkExhaustedError; } });
+var TransactionReceiptStore_js_1 = require("./TransactionReceiptStore.js");
+Object.defineProperty(exports, "TransactionReceiptStore", { enumerable: true, get: function () { return TransactionReceiptStore_js_1.TransactionReceiptStore; } });