@totemsdk/core 1.0.0

package/src/lease/LeaseMonitor.ts

@@ -0,0 +1,157 @@
+/**
+ * @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

@@ -0,0 +1,57 @@
+/**
+ * @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

@@ -0,0 +1,148 @@
+"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

@@ -0,0 +1,203 @@
+/**
+ * @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

@@ -0,0 +1,61 @@
+/**
+ * @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;
+}