@totemsdk/core 1.0.9 → 1.0.10

package/src/lease/WatermarkStore.js

@@ -1,206 +0,0 @@
-"use strict";
-/**
- * @module WatermarkStore
- * WOTS index tracking with server synchronization
- *
- * Uses in-memory cache backed by persistent storage.
- * Pattern:
- * - initialize() loads from storage into memory cache (or creates default)
- * - Sync getters read from memory cache (fast, no I/O)
- * - Mutators update memory cache AND persist to storage
- * - Caller MUST call initialize() before using sync getters
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.WatermarkStore = void 0;
-const adapters_1 = require("../adapters");
-const DEFAULT_STORAGE_KEY = 'totem_wots_watermark';
-const MAX_INDEX_PER_LEVEL = 64;
-const TOTAL_INDICES = 64 * 64 * 64;
-class WatermarkStore {
-    constructor(storage, logger = new adapters_1.NoopLogger(), config = {}) {
-        this.state = null;
-        this._initialized = false;
-        this.storage = storage;
-        this.logger = logger;
-        this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;
-    }
-    async initialize() {
-        if (this._initialized && this.state) {
-            return this.state;
-        }
-        const existing = await this.load();
-        if (existing) {
-            this._initialized = true;
-            return existing;
-        }
-        const initialState = {
-            next_addressIndex: 0,
-            next_l1: 0,
-            next_l2: 0,
-            usedIndices: []
-        };
-        await this.save(initialState);
-        this._initialized = true;
-        return initialState;
-    }
-    isInitialized() {
-        return this._initialized;
-    }
-    async load() {
-        try {
-            const watermark = await this.storage.get(this.storageKey);
-            if (watermark) {
-                this.state = watermark;
-                this.logger.debug('Loaded watermark from storage');
-                return this.state;
-            }
-            return null;
-        }
-        catch (error) {
-            this.logger.error('Failed to load watermark:', error);
-            return null;
-        }
-    }
-    async save(watermark) {
-        try {
-            this.state = watermark;
-            await this.storage.set(this.storageKey, watermark);
-        }
-        catch (error) {
-            this.logger.error('Failed to save watermark:', error);
-            throw error;
-        }
-    }
-    async clear() {
-        try {
-            this.state = null;
-            this._initialized = false;
-            await this.storage.remove(this.storageKey);
-            this.logger.debug('Cleared watermark');
-        }
-        catch (error) {
-            this.logger.error('Failed to clear watermark:', error);
-            throw error;
-        }
-    }
-    getCurrent() {
-        return this.state;
-    }
-    getNextIndices() {
-        if (!this.state || this.isExhausted()) {
-            return null;
-        }
-        return {
-            addressIndex: this.state.next_addressIndex,
-            l1: this.state.next_l1,
-            l2: this.state.next_l2
-        };
-    }
-    isExhausted() {
-        if (!this.state)
-            return false;
-        return this.state.next_addressIndex >= MAX_INDEX_PER_LEVEL;
-    }
-    hasAvailableIndices() {
-        return !this.isExhausted();
-    }
-    async markUsed(indices) {
-        if (!this.state) {
-            await this.load();
-        }
-        if (!this.state) {
-            throw new Error('Watermark not initialized');
-        }
-        const indexTuple = [indices.addressIndex, indices.l1, indices.l2];
-        const flatIndex = this.flattenIndex(indices.addressIndex, indices.l1, indices.l2);
-        const alreadyUsed = this.state.usedIndices.some(([addressIndex, l1, l2]) => addressIndex === indices.addressIndex && l1 === indices.l1 && l2 === indices.l2);
-        if (!alreadyUsed) {
-            this.logger.debug(`Marking indices as USED: (addressIndex=${indices.addressIndex}, l1=${indices.l1}, l2=${indices.l2}) [${flatIndex}/${TOTAL_INDICES}]`);
-            this.logger.debug(`  total used: ${this.state.usedIndices.length + 1} / ${TOTAL_INDICES}`);
-            this.state.usedIndices.push(indexTuple);
-        }
-        else {
-            this.logger.warn(`Indices already marked as used: (addressIndex=${indices.addressIndex}, l1=${indices.l1}, l2=${indices.l2})`);
-        }
-        await this.save(this.state);
-    }
-    async advanceWatermark(indices) {
-        if (!this.state) {
-            await this.load();
-        }
-        if (!this.state) {
-            throw new Error('Watermark not initialized');
-        }
-        const currentFlat = this.flattenIndex(indices.addressIndex, indices.l1, indices.l2);
-        const nextIndices = this.calculateNextIndices(indices);
-        const nextFlat = this.flattenIndex(nextIndices.addressIndex, nextIndices.l1, nextIndices.l2);
-        this.logger.debug(`Advancing watermark...`);
-        this.logger.debug(`  current: (addressIndex=${indices.addressIndex}, l1=${indices.l1}, l2=${indices.l2}) [${currentFlat}/${TOTAL_INDICES}]`);
-        this.logger.debug(`  next:    (addressIndex=${nextIndices.addressIndex}, l1=${nextIndices.l1}, l2=${nextIndices.l2}) [${nextFlat}/${TOTAL_INDICES}]`);
-        this.state.next_addressIndex = nextIndices.addressIndex;
-        this.state.next_l1 = nextIndices.l1;
-        this.state.next_l2 = nextIndices.l2;
-        await this.save(this.state);
-        this.logger.debug('Watermark advanced and persisted');
-    }
-    async updateFromServer(serverWatermark) {
-        if (!this.state) {
-            await this.load();
-        }
-        if (!this.state) {
-            await this.initialize();
-        }
-        const localIndexFlat = this.flattenIndex(this.state.next_addressIndex, this.state.next_l1, this.state.next_l2);
-        const serverIndexFlat = this.flattenIndex(serverWatermark.addressIndex, serverWatermark.l1, serverWatermark.l2);
-        const drift = serverIndexFlat - localIndexFlat;
-        const hasConflict = drift > 1;
-        const needsUpdate = this.shouldUseServerWatermark(this.state, serverWatermark);
-        if (needsUpdate) {
-            this.logger.debug(`Updating watermark from server (drift: ${drift})`);
-            this.state.next_addressIndex = serverWatermark.addressIndex;
-            this.state.next_l1 = serverWatermark.l1;
-            this.state.next_l2 = serverWatermark.l2;
-            this.state.serverWatermark = serverWatermark;
-            this.state.lastSyncTimestamp = Date.now();
-            await this.save(this.state);
-            return { updated: true, drift, hasConflict };
-        }
-        this.state.lastSyncTimestamp = Date.now();
-        await this.save(this.state);
-        return { updated: false, drift, hasConflict };
-    }
-    getUsageStats() {
-        const used = this.state?.usedIndices.length ?? 0;
-        return {
-            used,
-            total: TOTAL_INDICES,
-            percentage: (used / TOTAL_INDICES) * 100
-        };
-    }
-    calculateNextIndices(current) {
-        let { addressIndex, l1, l2 } = current;
-        l2++;
-        if (l2 >= MAX_INDEX_PER_LEVEL) {
-            l2 = 0;
-            l1++;
-            if (l1 >= MAX_INDEX_PER_LEVEL) {
-                l1 = 0;
-                addressIndex++;
-            }
-        }
-        return { addressIndex, l1, l2 };
-    }
-    shouldUseServerWatermark(local, server) {
-        if (server.addressIndex > local.next_addressIndex)
-            return true;
-        if (server.addressIndex === local.next_addressIndex && server.l1 > local.next_l1)
-            return true;
-        if (server.addressIndex === local.next_addressIndex && server.l1 === local.next_l1 && server.l2 > local.next_l2)
-            return true;
-        return false;
-    }
-    flattenIndex(addressIndex, l1, l2) {
-        return (addressIndex * MAX_INDEX_PER_LEVEL * MAX_INDEX_PER_LEVEL) + (l1 * MAX_INDEX_PER_LEVEL) + l2;
-    }
-}
-exports.WatermarkStore = WatermarkStore;

package/src/lease/WatermarkStore.ts

@@ -1,270 +0,0 @@
-/**
- * @module WatermarkStore
- * WOTS index tracking with server synchronization
- * 
- * Uses in-memory cache backed by persistent storage.
- * Pattern:
- * - initialize() loads from storage into memory cache (or creates default)
- * - Sync getters read from memory cache (fast, no I/O)
- * - Mutators update memory cache AND persist to storage
- * - Caller MUST call initialize() before using sync getters
- */
-
-import type { StorageAdapter, LoggerAdapter } from '../adapters/index.js';
-import { NoopLogger } from '../adapters/index.js';
-
-export interface WotsIndices {
-  addressIndex: number;
-  l1: number;
-  l2: number;
-}
-
-export interface WatermarkState {
-  next_addressIndex: number;
-  next_l1: number;
-  next_l2: number;
-  usedIndices: Array<[number, number, number]>;
-  lastSyncTimestamp?: number;
-  serverWatermark?: WotsIndices;
-}
-
-export interface SyncResult {
-  updated: boolean;
-  drift: number;
-  hasConflict: boolean;
-}
-
-export interface WatermarkStoreConfig {
-  storageKey?: string;
-}
-
-const DEFAULT_STORAGE_KEY = 'totem_wots_watermark';
-const MAX_INDEX_PER_LEVEL = 64;
-const TOTAL_INDICES = 64 * 64 * 64;
-
-export class WatermarkStore {
-  private state: WatermarkState | null = null;
-  private _initialized = false;
-  private readonly storageKey: string;
-  private readonly storage: StorageAdapter;
-  private readonly logger: LoggerAdapter;
-
-  constructor(
-    storage: StorageAdapter,
-    logger: LoggerAdapter = new NoopLogger(),
-    config: WatermarkStoreConfig = {}
-  ) {
-    this.storage = storage;
-    this.logger = logger;
-    this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;
-  }
-
-  async initialize(): Promise<WatermarkState> {
-    if (this._initialized && this.state) {
-      return this.state;
-    }
-
-    const existing = await this.load();
-    if (existing) {
-      this._initialized = true;
-      return existing;
-    }
-
-    const initialState: WatermarkState = {
-      next_addressIndex: 0,
-      next_l1: 0,
-      next_l2: 0,
-      usedIndices: []
-    };
-
-    await this.save(initialState);
-    this._initialized = true;
-    return initialState;
-  }
-
-  isInitialized(): boolean {
-    return this._initialized;
-  }
-
-  async load(): Promise<WatermarkState | null> {
-    try {
-      const watermark = await this.storage.get<WatermarkState>(this.storageKey);
-      if (watermark) {
-        this.state = watermark;
-        this.logger.debug('Loaded watermark from storage');
-        return this.state;
-      }
-      return null;
-    } catch (error) {
-      this.logger.error('Failed to load watermark:', error);
-      return null;
-    }
-  }
-
-  async save(watermark: WatermarkState): Promise<void> {
-    try {
-      this.state = watermark;
-      await this.storage.set(this.storageKey, watermark);
-    } catch (error) {
-      this.logger.error('Failed to save watermark:', error);
-      throw error;
-    }
-  }
-
-  async clear(): Promise<void> {
-    try {
-      this.state = null;
-      this._initialized = false;
-      await this.storage.remove(this.storageKey);
-      this.logger.debug('Cleared watermark');
-    } catch (error) {
-      this.logger.error('Failed to clear watermark:', error);
-      throw error;
-    }
-  }
-
-  getCurrent(): WatermarkState | null {
-    return this.state;
-  }
-
-  getNextIndices(): WotsIndices | null {
-    if (!this.state || this.isExhausted()) {
-      return null;
-    }
-
-    return {
-      addressIndex: this.state.next_addressIndex,
-      l1: this.state.next_l1,
-      l2: this.state.next_l2
-    };
-  }
-
-  isExhausted(): boolean {
-    if (!this.state) return false;
-    return this.state.next_addressIndex >= MAX_INDEX_PER_LEVEL;
-  }
-
-  hasAvailableIndices(): boolean {
-    return !this.isExhausted();
-  }
-
-  async markUsed(indices: WotsIndices): Promise<void> {
-    if (!this.state) {
-      await this.load();
-    }
-
-    if (!this.state) {
-      throw new Error('Watermark not initialized');
-    }
-
-    const indexTuple: [number, number, number] = [indices.addressIndex, indices.l1, indices.l2];
-    const flatIndex = this.flattenIndex(indices.addressIndex, indices.l1, indices.l2);
-    
-    const alreadyUsed = this.state.usedIndices.some(([addressIndex, l1, l2]) => 
-      addressIndex === indices.addressIndex && l1 === indices.l1 && l2 === indices.l2
-    );
-    
-    if (!alreadyUsed) {
-      this.logger.debug(`Marking indices as USED: (addressIndex=${indices.addressIndex}, l1=${indices.l1}, l2=${indices.l2}) [${flatIndex}/${TOTAL_INDICES}]`);
-      this.logger.debug(`  total used: ${this.state.usedIndices.length + 1} / ${TOTAL_INDICES}`);
-      this.state.usedIndices.push(indexTuple);
-    } else {
-      this.logger.warn(`Indices already marked as used: (addressIndex=${indices.addressIndex}, l1=${indices.l1}, l2=${indices.l2})`);
-    }
-
-    await this.save(this.state);
-  }
-
-  async advanceWatermark(indices: WotsIndices): Promise<void> {
-    if (!this.state) {
-      await this.load();
-    }
-
-    if (!this.state) {
-      throw new Error('Watermark not initialized');
-    }
-
-    const currentFlat = this.flattenIndex(indices.addressIndex, indices.l1, indices.l2);
-    const nextIndices = this.calculateNextIndices(indices);
-    const nextFlat = this.flattenIndex(nextIndices.addressIndex, nextIndices.l1, nextIndices.l2);
-    
-    this.logger.debug(`Advancing watermark...`);
-    this.logger.debug(`  current: (addressIndex=${indices.addressIndex}, l1=${indices.l1}, l2=${indices.l2}) [${currentFlat}/${TOTAL_INDICES}]`);
-    this.logger.debug(`  next:    (addressIndex=${nextIndices.addressIndex}, l1=${nextIndices.l1}, l2=${nextIndices.l2}) [${nextFlat}/${TOTAL_INDICES}]`);
-    
-    this.state.next_addressIndex = nextIndices.addressIndex;
-    this.state.next_l1 = nextIndices.l1;
-    this.state.next_l2 = nextIndices.l2;
-
-    await this.save(this.state);
-    this.logger.debug('Watermark advanced and persisted');
-  }
-
-  async updateFromServer(serverWatermark: WotsIndices): Promise<SyncResult> {
-    if (!this.state) {
-      await this.load();
-    }
-
-    if (!this.state) {
-      await this.initialize();
-    }
-
-    const localIndexFlat = this.flattenIndex(this.state!.next_addressIndex, this.state!.next_l1, this.state!.next_l2);
-    const serverIndexFlat = this.flattenIndex(serverWatermark.addressIndex, serverWatermark.l1, serverWatermark.l2);
-    const drift = serverIndexFlat - localIndexFlat;
-    const hasConflict = drift > 1;
-
-    const needsUpdate = this.shouldUseServerWatermark(this.state!, serverWatermark);
-
-    if (needsUpdate) {
-      this.logger.debug(`Updating watermark from server (drift: ${drift})`);
-      this.state!.next_addressIndex = serverWatermark.addressIndex;
-      this.state!.next_l1 = serverWatermark.l1;
-      this.state!.next_l2 = serverWatermark.l2;
-      this.state!.serverWatermark = serverWatermark;
-      this.state!.lastSyncTimestamp = Date.now();
-      await this.save(this.state!);
-      return { updated: true, drift, hasConflict };
-    }
-
-    this.state!.lastSyncTimestamp = Date.now();
-    await this.save(this.state!);
-    return { updated: false, drift, hasConflict };
-  }
-
-  getUsageStats(): { used: number; total: number; percentage: number } {
-    const used = this.state?.usedIndices.length ?? 0;
-    return {
-      used,
-      total: TOTAL_INDICES,
-      percentage: (used / TOTAL_INDICES) * 100
-    };
-  }
-
-  private calculateNextIndices(current: WotsIndices): WotsIndices {
-    let { addressIndex, l1, l2 } = current;
-
-    l2++;
-    if (l2 >= MAX_INDEX_PER_LEVEL) {
-      l2 = 0;
-      l1++;
-      if (l1 >= MAX_INDEX_PER_LEVEL) {
-        l1 = 0;
-        addressIndex++;
-      }
-    }
-
-    return { addressIndex, l1, l2 };
-  }
-
-  private shouldUseServerWatermark(local: WatermarkState, server: WotsIndices): boolean {
-    if (server.addressIndex > local.next_addressIndex) return true;
-    if (server.addressIndex === local.next_addressIndex && server.l1 > local.next_l1) return true;
-    if (server.addressIndex === local.next_addressIndex && server.l1 === local.next_l1 && server.l2 > local.next_l2) return true;
-    return false;
-  }
-
-  private flattenIndex(addressIndex: number, l1: number, l2: number): number {
-    return (addressIndex * MAX_INDEX_PER_LEVEL * MAX_INDEX_PER_LEVEL) + (l1 * MAX_INDEX_PER_LEVEL) + l2;
-  }
-}

package/src/lease/index.d.ts

@@ -1,14 +0,0 @@
-/**
- * @module @totemsdk/core/lease
- * WOTS lease lifecycle management
- *
- * This module provides:
- * - LeaseStore: Persistent storage for lease records with in-memory cache
- * - WatermarkStore: WOTS index tracking with server sync
- * - LeaseMonitor: Expiry monitoring and renewal
- */
-export { LeaseStore, type StoredLease, type LeaseStatus, type LeaseStoreConfig, type WotsIndices as LeaseWotsIndices, } from './LeaseStore';
-export { WatermarkStore, type WatermarkState, type SyncResult, type WatermarkStoreConfig, } from './WatermarkStore';
-export type { WotsIndices } from './WatermarkStore';
-export { LeaseMonitor, type LeaseExpiryEvent, type LeaseExpiryCallback, type LeaseMonitorConfig, } from './LeaseMonitor';
-export { prepareLease, finalizeLease, flatIndexFromLanes, type PrepareArgs, type PrepareResp } from '../lease-client';

package/src/lease/index.js

@@ -1,22 +0,0 @@
-"use strict";
-/**
- * @module @totemsdk/core/lease
- * WOTS lease lifecycle management
- *
- * This module provides:
- * - LeaseStore: Persistent storage for lease records with in-memory cache
- * - WatermarkStore: WOTS index tracking with server sync
- * - LeaseMonitor: Expiry monitoring and renewal
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.flatIndexFromLanes = exports.finalizeLease = exports.prepareLease = exports.LeaseMonitor = exports.WatermarkStore = exports.LeaseStore = void 0;
-var LeaseStore_1 = require("./LeaseStore");
-Object.defineProperty(exports, "LeaseStore", { enumerable: true, get: function () { return LeaseStore_1.LeaseStore; } });
-var WatermarkStore_1 = require("./WatermarkStore");
-Object.defineProperty(exports, "WatermarkStore", { enumerable: true, get: function () { return WatermarkStore_1.WatermarkStore; } });
-var LeaseMonitor_1 = require("./LeaseMonitor");
-Object.defineProperty(exports, "LeaseMonitor", { enumerable: true, get: function () { return LeaseMonitor_1.LeaseMonitor; } });
-var lease_client_1 = require("../lease-client");
-Object.defineProperty(exports, "prepareLease", { enumerable: true, get: function () { return lease_client_1.prepareLease; } });
-Object.defineProperty(exports, "finalizeLease", { enumerable: true, get: function () { return lease_client_1.finalizeLease; } });
-Object.defineProperty(exports, "flatIndexFromLanes", { enumerable: true, get: function () { return lease_client_1.flatIndexFromLanes; } });

package/src/lease/index.ts

@@ -1,41 +0,0 @@
-/**
- * @module @totemsdk/core/lease
- * WOTS lease lifecycle management
- * 
- * This module provides:
- * - LeaseStore: Persistent storage for lease records with in-memory cache
- * - WatermarkStore: WOTS index tracking with server sync
- * - LeaseMonitor: Expiry monitoring and renewal
- */
-
-export { 
-  LeaseStore,
-  type StoredLease,
-  type LeaseStatus,
-  type LeaseStoreConfig,
-  type WotsIndices as LeaseWotsIndices,
-} from './LeaseStore.js';
-
-export { 
-  WatermarkStore,
-  type WatermarkState,
-  type SyncResult,
-  type WatermarkStoreConfig,
-} from './WatermarkStore.js';
-
-export type { WotsIndices } from './WatermarkStore.js';
-
-export {
-  LeaseMonitor,
-  type LeaseExpiryEvent,
-  type LeaseExpiryCallback,
-  type LeaseMonitorConfig,
-} from './LeaseMonitor.js';
-
-export { 
-  prepareLease, 
-  finalizeLease, 
-  flatIndexFromLanes,
-  type PrepareArgs,
-  type PrepareResp 
-} from '../lease-client.js';

package/src/lease-client.d.ts

@@ -1,31 +0,0 @@
-/**
- * Totem <-> Axia hardened WOTS helpers (no deps on server internals).
- */
-export type PrepareArgs = {
-    txId: string;
-    rootPublicKey: string;
-    to: string;
-    amount: string;
-    tokenId?: string;
-    burn?: string | null;
-    digestL2?: string | null;
-    digestL3?: string | null;
-    ttlMs?: number;
-};
-export type PrepareResp = {
-    leaseToken: string;
-    lease: {
-        addressIndex: number;
-        l1: number;
-        l2: number;
-    };
-    txId: string;
-    digestTx?: string | null;
-};
-export declare function prepareLease(apiUrl: string, apiKey: string, args: PrepareArgs): Promise<PrepareResp>;
-export declare function finalizeLease(apiUrl: string, apiKey: string, leaseToken: string, signedHex: string): Promise<{
-    status: number;
-    body: string;
-}>;
-/** lane tuple -> flat WOTS index (64^3 space) */
-export declare function flatIndexFromLanes(addressIndex: number, l1: number, l2: number): number;

package/src/lease-client.js

@@ -1,44 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.prepareLease = prepareLease;
-exports.finalizeLease = finalizeLease;
-exports.flatIndexFromLanes = flatIndexFromLanes;
-async function prepareLease(apiUrl, apiKey, args) {
-    const res = await fetch(`${apiUrl}/v1/wots-hardened/prepare`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', 'x-api-key': apiKey },
-        body: JSON.stringify({
-            tokenId: "0x00",
-            burn: null,
-            digestL2: null,
-            digestL3: null,
-            ttlMs: 20000,
-            ...args
-        })
-    });
-    if (!res.ok)
-        throw new Error(`prepareLease ${res.status}`);
-    const raw = await res.json();
-    const lease = raw.lease ?? { addressIndex: raw.addressIndex, l1: raw.l1, l2: raw.l2 };
-    return {
-        leaseToken: raw.leaseToken,
-        lease,
-        txId: raw.txId,
-        digestTx: raw.digestTx ?? null
-    };
-}
-async function finalizeLease(apiUrl, apiKey, leaseToken, signedHex) {
-    const res = await fetch(`${apiUrl}/v1/wots-hardened/finalize`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', 'x-api-key': apiKey },
-        body: JSON.stringify({ leaseToken, signedHex })
-    });
-    const text = await res.text();
-    return { status: res.status, body: text };
-}
-/** lane tuple -> flat WOTS index (64^3 space) */
-function flatIndexFromLanes(addressIndex, l1, l2) {
-    if (addressIndex | l1 | l2 & ~63)
-        throw new Error('lane out of range');
-    return (addressIndex * 64 * 64) + (l1 * 64) + l2;
-}