@totemsdk/core 1.0.9 → 1.0.11

package/src/lease/LeaseMonitor.ts

@@ -1,157 +0,0 @@
-/**
- * @module LeaseMonitor
- * Monitors lease expiry and triggers renewal/cleanup actions
- * 
- * Features:
- * - Automatic expiry detection with configurable thresholds
- * - Event-based notifications for expiring leases
- * - Adaptive monitoring interval based on shortest TTL
- */
-
-import type { TimerAdapter, LoggerAdapter } from '../adapters/index.js';
-import { DefaultTimerAdapter, NoopLogger, type TimerHandle } from '../adapters/index.js';
-import type { LeaseStore, StoredLease } from './LeaseStore.js';
-
-export interface LeaseExpiryEvent {
-  leaseId: string;
-  expiresAt: number;
-  remainingMs: number;
-  lease: StoredLease;
-}
-
-export type LeaseExpiryCallback = (event: LeaseExpiryEvent) => void;
-
-export interface LeaseMonitorConfig {
-  defaultIntervalMs?: number;
-  expiryThresholdMs?: number;
-  minIntervalMs?: number;
-  maxIntervalMs?: number;
-}
-
-const DEFAULT_CONFIG: Required<LeaseMonitorConfig> = {
-  defaultIntervalMs: 5000,
-  expiryThresholdMs: 5000,
-  minIntervalMs: 1000,
-  maxIntervalMs: 30000,
-};
-
-export class LeaseMonitor {
-  private readonly leaseStore: LeaseStore;
-  private readonly timer: TimerAdapter;
-  private readonly logger: LoggerAdapter;
-  private readonly config: Required<LeaseMonitorConfig>;
-  
-  private timerHandle: TimerHandle | null = null;
-  private isRunning = false;
-  private expiryCallbacks = new Set<LeaseExpiryCallback>();
-
-  constructor(
-    leaseStore: LeaseStore,
-    timer: TimerAdapter = new DefaultTimerAdapter(),
-    logger: LoggerAdapter = new NoopLogger(),
-    config: LeaseMonitorConfig = {}
-  ) {
-    this.leaseStore = leaseStore;
-    this.timer = timer;
-    this.logger = logger;
-    this.config = { ...DEFAULT_CONFIG, ...config };
-  }
-
-  start(): void {
-    if (this.isRunning) {
-      this.logger.debug('LeaseMonitor already running');
-      return;
-    }
-
-    this.isRunning = true;
-    this.scheduleNextCheck();
-    this.logger.debug('LeaseMonitor started');
-  }
-
-  stop(): void {
-    if (!this.isRunning) return;
-
-    this.isRunning = false;
-    if (this.timerHandle !== null) {
-      this.timer.clearTimeout(this.timerHandle);
-      this.timerHandle = null;
-    }
-    this.logger.debug('LeaseMonitor stopped');
-  }
-
-  isActive(): boolean {
-    return this.isRunning;
-  }
-
-  onExpirySoon(callback: LeaseExpiryCallback): () => void {
-    this.expiryCallbacks.add(callback);
-    return () => this.expiryCallbacks.delete(callback);
-  }
-
-  removeAllListeners(): void {
-    this.expiryCallbacks.clear();
-  }
-
-  async checkNow(): Promise<LeaseExpiryEvent[]> {
-    const now = this.timer.now();
-    const expiringSoon = this.leaseStore.getExpiringSoon(this.config.expiryThresholdMs);
-    
-    const events: LeaseExpiryEvent[] = expiringSoon.map(lease => ({
-      leaseId: lease.leaseId,
-      expiresAt: lease.expiresAt,
-      remainingMs: Math.max(0, lease.expiresAt - now),
-      lease,
-    }));
-
-    for (const event of events) {
-      this.notifyExpirySoon(event);
-    }
-
-    await this.leaseStore.cleanupExpired();
-
-    return events;
-  }
-
-  private scheduleNextCheck(): void {
-    if (!this.isRunning) return;
-
-    const interval = this.calculateInterval();
-    this.timerHandle = this.timer.setTimeout(() => {
-      this.runCheck();
-    }, interval);
-
-    this.logger.debug(`Next lease check scheduled in ${interval}ms`);
-  }
-
-  private async runCheck(): Promise<void> {
-    if (!this.isRunning) return;
-
-    try {
-      await this.checkNow();
-    } catch (error) {
-      this.logger.error('Error during lease check:', error);
-    }
-
-    this.scheduleNextCheck();
-  }
-
-  private calculateInterval(): number {
-    const storeInterval = this.leaseStore.calculateMonitoringInterval();
-    const interval = Math.max(
-      this.config.minIntervalMs,
-      Math.min(storeInterval, this.config.maxIntervalMs)
-    );
-    return interval;
-  }
-
-  private notifyExpirySoon(event: LeaseExpiryEvent): void {
-    this.logger.debug(`Lease expiring soon: ${event.leaseId}, remaining: ${event.remainingMs}ms`);
-    this.expiryCallbacks.forEach(callback => {
-      try {
-        callback(event);
-      } catch (error) {
-        this.logger.error('Error in expiry callback:', error);
-      }
-    });
-  }
-}

package/src/lease/LeaseStore.d.ts

@@ -1,57 +0,0 @@
-/**
- * @module LeaseStore
- * WOTS lease lifecycle management with platform-agnostic storage
- *
- * 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
- * - Caller MUST call initialize() before using sync getters
- */
-import type { StorageAdapter, LoggerAdapter } from '../adapters';
-export interface WotsIndices {
-    addressIndex: number;
-    l1: number;
-    l2: number;
-}
-export type LeaseStatus = 'pending' | 'active' | 'expired' | 'finalized' | 'cancelled';
-export interface StoredLease {
-    leaseId: string;
-    leaseToken: string;
-    indices: WotsIndices;
-    expiresAt: number;
-    status: LeaseStatus;
-    createdAt: number;
-    txId?: string;
-    leaseTTL: number;
-}
-export interface LeaseStoreConfig {
-    storageKey?: string;
-}
-export declare class LeaseStore {
-    private leases;
-    private _initialized;
-    private readonly storageKey;
-    private readonly storage;
-    private readonly logger;
-    constructor(storage: StorageAdapter, logger?: LoggerAdapter, config?: LeaseStoreConfig);
-    initialize(): Promise<void>;
-    isInitialized(): boolean;
-    private load;
-    private persist;
-    save(lease: StoredLease): Promise<void>;
-    get(leaseId: string): StoredLease | undefined;
-    getByToken(leaseToken: string): StoredLease | undefined;
-    getAll(): StoredLease[];
-    getActive(): StoredLease[];
-    getExpiringSoon(thresholdMs?: number): StoredLease[];
-    delete(leaseId: string): Promise<boolean>;
-    deleteByToken(leaseToken: string): Promise<boolean>;
-    updateStatus(leaseId: string, status: LeaseStatus): Promise<void>;
-    cleanupExpired(): Promise<number>;
-    clear(): Promise<void>;
-    getMinimumTTL(): number | null;
-    calculateMonitoringInterval(): number;
-    private flattenIndex;
-}

package/src/lease/LeaseStore.js

@@ -1,148 +0,0 @@
-"use strict";
-/**
- * @module LeaseStore
- * WOTS lease lifecycle management with platform-agnostic storage
- *
- * 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
- * - Caller MUST call initialize() before using sync getters
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LeaseStore = void 0;
-const adapters_1 = require("../adapters");
-const DEFAULT_STORAGE_KEY = 'totem_wots_leases';
-class LeaseStore {
-    constructor(storage, logger = new adapters_1.NoopLogger(), config = {}) {
-        this.leases = new Map();
-        this._initialized = false;
-        this.storage = storage;
-        this.logger = logger;
-        this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;
-    }
-    async initialize() {
-        if (this._initialized)
-            return;
-        await this.load();
-        await this.cleanupExpired();
-        this._initialized = true;
-    }
-    isInitialized() {
-        return this._initialized;
-    }
-    async load() {
-        try {
-            const leasesArray = await this.storage.get(this.storageKey);
-            if (leasesArray) {
-                this.leases = new Map(leasesArray.map(lease => [lease.leaseId, lease]));
-                this.logger.debug(`Loaded ${this.leases.size} leases from storage`);
-            }
-        }
-        catch (error) {
-            this.logger.error('Failed to load leases:', error);
-        }
-    }
-    async persist() {
-        try {
-            const leasesArray = Array.from(this.leases.values());
-            await this.storage.set(this.storageKey, leasesArray);
-        }
-        catch (error) {
-            this.logger.error('Failed to persist leases:', error);
-            throw error;
-        }
-    }
-    async save(lease) {
-        const flatIndex = this.flattenIndex(lease.indices);
-        this.logger.debug(`Storing lease: ${lease.leaseId}`);
-        this.logger.debug(`  indices: (addressIndex=${lease.indices.addressIndex}, l1=${lease.indices.l1}, l2=${lease.indices.l2}) [${flatIndex}/262,144]`);
-        this.logger.debug(`  status: ${lease.status}, TTL: ${lease.leaseTTL}ms`);
-        this.leases.set(lease.leaseId, lease);
-        await this.persist();
-    }
-    get(leaseId) {
-        return this.leases.get(leaseId);
-    }
-    getByToken(leaseToken) {
-        return Array.from(this.leases.values()).find(lease => lease.leaseToken === leaseToken);
-    }
-    getAll() {
-        return Array.from(this.leases.values());
-    }
-    getActive() {
-        const now = Date.now();
-        return this.getAll().filter(lease => lease.status === 'active' && lease.expiresAt > now);
-    }
-    getExpiringSoon(thresholdMs = 5000) {
-        const now = Date.now();
-        return this.getAll().filter(lease => lease.status === 'active' &&
-            lease.expiresAt > now &&
-            lease.expiresAt <= now + thresholdMs);
-    }
-    async delete(leaseId) {
-        const lease = this.leases.get(leaseId);
-        if (lease) {
-            this.logger.debug(`Deleting lease: ${leaseId}, final status: ${lease.status}`);
-        }
-        const existed = this.leases.delete(leaseId);
-        if (existed) {
-            await this.persist();
-        }
-        return existed;
-    }
-    async deleteByToken(leaseToken) {
-        const lease = this.getByToken(leaseToken);
-        if (lease) {
-            return this.delete(lease.leaseId);
-        }
-        return false;
-    }
-    async updateStatus(leaseId, status) {
-        const lease = this.leases.get(leaseId);
-        if (lease) {
-            const oldStatus = lease.status;
-            this.logger.debug(`Lease status change: ${leaseId} ${oldStatus} → ${status}`);
-            lease.status = status;
-            await this.persist();
-        }
-    }
-    async cleanupExpired() {
-        const now = Date.now();
-        const expiredLeaseIds = [];
-        for (const [leaseId, lease] of this.leases.entries()) {
-            if (lease.expiresAt <= now && lease.status !== 'finalized') {
-                lease.status = 'expired';
-                expiredLeaseIds.push(leaseId);
-            }
-        }
-        if (expiredLeaseIds.length > 0) {
-            this.logger.debug(`Marked ${expiredLeaseIds.length} leases as expired`);
-            await this.persist();
-        }
-        return expiredLeaseIds.length;
-    }
-    async clear() {
-        this.leases.clear();
-        await this.storage.remove(this.storageKey);
-        this.logger.debug('Cleared all leases');
-    }
-    getMinimumTTL() {
-        const activeLeases = this.getActive();
-        if (activeLeases.length === 0)
-            return null;
-        return Math.min(...activeLeases.map(lease => lease.leaseTTL));
-    }
-    calculateMonitoringInterval() {
-        const minTTL = this.getMinimumTTL();
-        if (minTTL === null)
-            return 5000;
-        const calculatedInterval = Math.min(minTTL / 4, 5000);
-        return Math.max(calculatedInterval, 1000);
-    }
-    flattenIndex(indices) {
-        return (indices.addressIndex * 64 * 64) + (indices.l1 * 64) + indices.l2;
-    }
-}
-exports.LeaseStore = LeaseStore;

package/src/lease/LeaseStore.ts

@@ -1,203 +0,0 @@
-/**
- * @module LeaseStore
- * WOTS lease lifecycle management with platform-agnostic storage
- * 
- * 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
- * - 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 type LeaseStatus = 'pending' | 'active' | 'expired' | 'finalized' | 'cancelled';
-
-export interface StoredLease {
-  leaseId: string;
-  leaseToken: string;
-  indices: WotsIndices;
-  expiresAt: number;
-  status: LeaseStatus;
-  createdAt: number;
-  txId?: string;
-  leaseTTL: number;
-}
-
-export interface LeaseStoreConfig {
-  storageKey?: string;
-}
-
-const DEFAULT_STORAGE_KEY = 'totem_wots_leases';
-
-export class LeaseStore {
-  private leases: Map<string, StoredLease> = new Map();
-  private _initialized = false;
-  private readonly storageKey: string;
-  private readonly storage: StorageAdapter;
-  private readonly logger: LoggerAdapter;
-
-  constructor(
-    storage: StorageAdapter,
-    logger: LoggerAdapter = new NoopLogger(),
-    config: LeaseStoreConfig = {}
-  ) {
-    this.storage = storage;
-    this.logger = logger;
-    this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;
-  }
-
-  async initialize(): Promise<void> {
-    if (this._initialized) return;
-
-    await this.load();
-    await this.cleanupExpired();
-    this._initialized = true;
-  }
-
-  isInitialized(): boolean {
-    return this._initialized;
-  }
-
-  private async load(): Promise<void> {
-    try {
-      const leasesArray = await this.storage.get<StoredLease[]>(this.storageKey);
-      if (leasesArray) {
-        this.leases = new Map(leasesArray.map(lease => [lease.leaseId, lease]));
-        this.logger.debug(`Loaded ${this.leases.size} leases from storage`);
-      }
-    } catch (error) {
-      this.logger.error('Failed to load leases:', error);
-    }
-  }
-
-  private async persist(): Promise<void> {
-    try {
-      const leasesArray = Array.from(this.leases.values());
-      await this.storage.set(this.storageKey, leasesArray);
-    } catch (error) {
-      this.logger.error('Failed to persist leases:', error);
-      throw error;
-    }
-  }
-
-  async save(lease: StoredLease): Promise<void> {
-    const flatIndex = this.flattenIndex(lease.indices);
-    this.logger.debug(`Storing lease: ${lease.leaseId}`);
-    this.logger.debug(`  indices: (addressIndex=${lease.indices.addressIndex}, l1=${lease.indices.l1}, l2=${lease.indices.l2}) [${flatIndex}/262,144]`);
-    this.logger.debug(`  status: ${lease.status}, TTL: ${lease.leaseTTL}ms`);
-    
-    this.leases.set(lease.leaseId, lease);
-    await this.persist();
-  }
-
-  get(leaseId: string): StoredLease | undefined {
-    return this.leases.get(leaseId);
-  }
-
-  getByToken(leaseToken: string): StoredLease | undefined {
-    return Array.from(this.leases.values()).find(
-      lease => lease.leaseToken === leaseToken
-    );
-  }
-
-  getAll(): StoredLease[] {
-    return Array.from(this.leases.values());
-  }
-
-  getActive(): StoredLease[] {
-    const now = Date.now();
-    return this.getAll().filter(lease => 
-      lease.status === 'active' && lease.expiresAt > now
-    );
-  }
-
-  getExpiringSoon(thresholdMs: number = 5000): StoredLease[] {
-    const now = Date.now();
-    return this.getAll().filter(lease => 
-      lease.status === 'active' && 
-      lease.expiresAt > now &&
-      lease.expiresAt <= now + thresholdMs
-    );
-  }
-
-  async delete(leaseId: string): Promise<boolean> {
-    const lease = this.leases.get(leaseId);
-    if (lease) {
-      this.logger.debug(`Deleting lease: ${leaseId}, final status: ${lease.status}`);
-    }
-    const existed = this.leases.delete(leaseId);
-    if (existed) {
-      await this.persist();
-    }
-    return existed;
-  }
-
-  async deleteByToken(leaseToken: string): Promise<boolean> {
-    const lease = this.getByToken(leaseToken);
-    if (lease) {
-      return this.delete(lease.leaseId);
-    }
-    return false;
-  }
-
-  async updateStatus(leaseId: string, status: LeaseStatus): Promise<void> {
-    const lease = this.leases.get(leaseId);
-    if (lease) {
-      const oldStatus = lease.status;
-      this.logger.debug(`Lease status change: ${leaseId} ${oldStatus} → ${status}`);
-      lease.status = status;
-      await this.persist();
-    }
-  }
-
-  async cleanupExpired(): Promise<number> {
-    const now = Date.now();
-    const expiredLeaseIds: string[] = [];
-
-    for (const [leaseId, lease] of this.leases.entries()) {
-      if (lease.expiresAt <= now && lease.status !== 'finalized') {
-        lease.status = 'expired';
-        expiredLeaseIds.push(leaseId);
-      }
-    }
-
-    if (expiredLeaseIds.length > 0) {
-      this.logger.debug(`Marked ${expiredLeaseIds.length} leases as expired`);
-      await this.persist();
-    }
-
-    return expiredLeaseIds.length;
-  }
-
-  async clear(): Promise<void> {
-    this.leases.clear();
-    await this.storage.remove(this.storageKey);
-    this.logger.debug('Cleared all leases');
-  }
-
-  getMinimumTTL(): number | null {
-    const activeLeases = this.getActive();
-    if (activeLeases.length === 0) return null;
-    return Math.min(...activeLeases.map(lease => lease.leaseTTL));
-  }
-
-  calculateMonitoringInterval(): number {
-    const minTTL = this.getMinimumTTL();
-    if (minTTL === null) return 5000;
-    const calculatedInterval = Math.min(minTTL / 4, 5000);
-    return Math.max(calculatedInterval, 1000);
-  }
-
-  private flattenIndex(indices: WotsIndices): number {
-    return (indices.addressIndex * 64 * 64) + (indices.l1 * 64) + indices.l2;
-  }
-}

package/src/lease/WatermarkStore.d.ts

@@ -1,61 +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';
-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;
-}
-export declare class WatermarkStore {
-    private state;
-    private _initialized;
-    private readonly storageKey;
-    private readonly storage;
-    private readonly logger;
-    constructor(storage: StorageAdapter, logger?: LoggerAdapter, config?: WatermarkStoreConfig);
-    initialize(): Promise<WatermarkState>;
-    isInitialized(): boolean;
-    load(): Promise<WatermarkState | null>;
-    save(watermark: WatermarkState): Promise<void>;
-    clear(): Promise<void>;
-    getCurrent(): WatermarkState | null;
-    getNextIndices(): WotsIndices | null;
-    isExhausted(): boolean;
-    hasAvailableIndices(): boolean;
-    markUsed(indices: WotsIndices): Promise<void>;
-    advanceWatermark(indices: WotsIndices): Promise<void>;
-    updateFromServer(serverWatermark: WotsIndices): Promise<SyncResult>;
-    getUsageStats(): {
-        used: number;
-        total: number;
-        percentage: number;
-    };
-    private calculateNextIndices;
-    private shouldUseServerWatermark;
-    private flattenIndex;
-}