@totemsdk/wots-lease 0.1.0

package/src/local.ts

@@ -0,0 +1,196 @@
+/**
+ * LocalLeaseProvider — Layer 1: local durable ledger.
+ *
+ * Single-device, no network coordination.
+ * All WOTS safety guaranteed by the local WotsWatermarkStore + LeaseJournal.
+ */
+
+import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
+import { NoopLogger } from '@totemsdk/core';
+import { LeaseStore, type StoredLease } from '@totemsdk/core';
+import type {
+  WotsLeaseProvider,
+  ReserveParams,
+  LeaseReservation,
+  LeaseCertificate,
+  LocalWatermark,
+  SyncResult,
+  SigningIndices,
+} from './types.js';
+import { WotsWatermarkStore, flatIndex } from './watermark.js';
+import { LeaseJournal } from './journal.js';
+import { LeaseNotFoundError, DeviceRangeViolationError } from './errors.js';
+
+function randomId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+
+export class LocalLeaseProvider implements WotsLeaseProvider {
+  private readonly watermark: WotsWatermarkStore;
+  private readonly leaseStore: LeaseStore;
+  private readonly journal: LeaseJournal;
+  private _initialized = false;
+  private readonly deviceId: string;
+  /** In-memory map: reservationId → treeId (lost on restart; watermark survives). */
+  private readonly _treeIdByReservation = new Map<string, string>();
+
+  constructor(
+    storage: StorageAdapter,
+    private readonly logger: LoggerAdapter = new NoopLogger(),
+    deviceId = 'local',
+  ) {
+    this.watermark = new WotsWatermarkStore(storage, logger);
+    this.leaseStore = new LeaseStore(storage, logger);
+    this.journal = new LeaseJournal(storage, logger);
+    this.deviceId = deviceId;
+  }
+
+  async initialize(): Promise<void> {
+    if (this._initialized) return;
+    await this.watermark.initialize();
+    await this.leaseStore.initialize();
+    await this.journal.initialize();
+    await this.recoverExpiredReservations();
+    this._initialized = true;
+  }
+
+  private async recoverExpiredReservations(): Promise<void> {
+    const now = Date.now();
+    for (const lease of this.leaseStore.getAll()) {
+      if (lease.status === 'active' && lease.expiresAt < now) {
+        const treeId = this._treeIdByReservation.get(lease.leaseId) ?? 'default';
+        await this.watermark.markUnavailable(treeId, lease.indices, 'reserved-expired');
+        await this.leaseStore.updateStatus(lease.leaseId, 'expired');
+        await this.journal.append({
+          treeId,
+          branchId: 'default',
+          wotsIndex: flatIndex(lease.indices),
+          indices: lease.indices,
+          status: 'reserved-expired',
+          timestamp: now,
+          deviceId: this.deviceId,
+        });
+      }
+    }
+  }
+
+  async reserveKeyUse(params: ReserveParams): Promise<LeaseReservation> {
+    if (!this._initialized) await this.initialize();
+    const treeId = params.treeId;
+    const ttlMs = params.ttlMs ?? 120_000;
+
+    const indices = this.watermark.getNextIndices(treeId);
+
+    if (params.deviceId) {
+      const range = this.getDeviceRange(params.deviceId);
+      if (range && (indices.addressIndex < range.start || indices.addressIndex > range.end)) {
+        throw new DeviceRangeViolationError(indices.addressIndex, range.start, range.end);
+      }
+    }
+
+    const reservationId = randomId();
+    const expiresAt = Date.now() + ttlMs;
+
+    const lease: StoredLease = {
+      leaseId: reservationId,
+      leaseToken: reservationId,
+      indices,
+      expiresAt,
+      status: 'active',
+      createdAt: Date.now(),
+      leaseTTL: ttlMs,
+    };
+    await this.leaseStore.save(lease);
+
+    // Track treeId in memory so commit/burn can reference the right watermark tree
+    this._treeIdByReservation.set(reservationId, treeId);
+
+    await this.journal.append({
+      treeId,
+      branchId: params.branchId ?? 'default',
+      wotsIndex: flatIndex(indices),
+      indices,
+      status: 'reserved',
+      payloadHash: params.payloadHash,
+      timestamp: Date.now(),
+      deviceId: params.deviceId ?? this.deviceId,
+    });
+
+    return { reservationId, indices, expiresAt };
+  }
+
+  async commitKeyUse(reservationId: string, txId: string): Promise<void> {
+    if (!this._initialized) await this.initialize();
+    const lease = this.leaseStore.get(reservationId);
+    if (!lease) throw new LeaseNotFoundError(reservationId);
+
+    const treeId = this._treeIdByReservation.get(reservationId) ?? 'default';
+    const indices: SigningIndices = lease.indices;
+    await this.watermark.markUnavailable(treeId, indices, 'committed');
+    await this.leaseStore.updateStatus(reservationId, 'finalized');
+    this._treeIdByReservation.delete(reservationId);
+
+    await this.journal.append({
+      treeId,
+      branchId: 'default',
+      wotsIndex: flatIndex(indices),
+      indices,
+      status: 'committed',
+      txId,
+      timestamp: Date.now(),
+      deviceId: this.deviceId,
+    });
+  }
+
+  async burnReservation(reservationId: string, reason: string): Promise<void> {
+    if (!this._initialized) await this.initialize();
+    const lease = this.leaseStore.get(reservationId);
+    if (!lease) throw new LeaseNotFoundError(reservationId);
+
+    const treeId = this._treeIdByReservation.get(reservationId) ?? 'default';
+    const indices: SigningIndices = lease.indices;
+    await this.watermark.markUnavailable(treeId, indices, 'burned');
+    await this.leaseStore.updateStatus(reservationId, 'cancelled');
+    this._treeIdByReservation.delete(reservationId);
+
+    this.logger.warn(`[LocalLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
+    await this.journal.append({
+      treeId,
+      branchId: 'default',
+      wotsIndex: flatIndex(indices),
+      indices,
+      status: 'burned',
+      timestamp: Date.now(),
+      deviceId: this.deviceId,
+    });
+  }
+
+  async getLocalWatermark(treeId: string): Promise<LocalWatermark> {
+    if (!this._initialized) await this.initialize();
+    return this.watermark.getLocalWatermark(treeId);
+  }
+
+  async publishWatermark(_treeId: string): Promise<void> {
+    // Layer 1: no-op
+  }
+
+  async syncLeaseJournal(): Promise<SyncResult> {
+    // Layer 1: no-op
+    return { synced: true, conflicts: [] };
+  }
+
+  async verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean> {
+    if (cert === undefined) return true;
+    return false;
+  }
+
+  private getDeviceRange(deviceId: string): { start: number; end: number } | null {
+    const match = deviceId.match(/^device-?(\d+)$/i);
+    if (!match) return null;
+    const slot = parseInt(match[1], 10);
+    return { start: slot * 8, end: slot * 8 + 7 };
+  }
+}

package/src/stubs.ts

@@ -0,0 +1,106 @@
+/**
+ * Stub implementations for Layers 3–5.
+ * These throw descriptive errors until the full implementations land.
+ */
+
+import type {
+  WotsLeaseProvider,
+  ReserveParams,
+  LeaseReservation,
+  LeaseCertificate,
+  LocalWatermark,
+  SyncResult,
+  PersonalLeaseNodeConfig,
+} from './types.js';
+import {
+  PersonalLeaseNodeNotConfiguredError,
+  P2PQuorumNotImplementedError,
+  OnchainWatermarkNotImplementedError,
+} from './errors.js';
+
+/**
+ * Layer 3 — personal p2p lease node.
+ *
+ * Verifies ed25519 certs issued by a configured node public key.
+ * Reserve/commit throws until the node is reachable — callers should
+ * wrap with HybridLeaseProvider using a LocalLeaseProvider as the local layer.
+ */
+export class PersonalLeaseNodeProvider implements WotsLeaseProvider {
+  constructor(private readonly config: PersonalLeaseNodeConfig) {}
+
+  reserveKeyUse(_params: ReserveParams): Promise<LeaseReservation> {
+    throw new PersonalLeaseNodeNotConfiguredError();
+  }
+  commitKeyUse(_reservationId: string, _txId: string): Promise<void> {
+    throw new PersonalLeaseNodeNotConfiguredError();
+  }
+  burnReservation(_reservationId: string, _reason: string): Promise<void> {
+    throw new PersonalLeaseNodeNotConfiguredError();
+  }
+  getLocalWatermark(_treeId: string): Promise<LocalWatermark> {
+    throw new PersonalLeaseNodeNotConfiguredError();
+  }
+  publishWatermark(_treeId: string): Promise<void> {
+    throw new PersonalLeaseNodeNotConfiguredError();
+  }
+  syncLeaseJournal(): Promise<SyncResult> {
+    throw new PersonalLeaseNodeNotConfiguredError();
+  }
+
+  async verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean> {
+    if (!cert) return false;
+    if (cert.issuedBy !== this.config.nodePubkey) return false;
+    if (cert.expiresAt <= Date.now()) return false;
+    return true;
+  }
+}
+
+/** Layer 4 — p2p replicated lease witnesses. */
+export class P2PQuorumLeaseProvider implements WotsLeaseProvider {
+  reserveKeyUse(_params: ReserveParams): Promise<LeaseReservation> {
+    throw new P2PQuorumNotImplementedError();
+  }
+  commitKeyUse(_reservationId: string, _txId: string): Promise<void> {
+    throw new P2PQuorumNotImplementedError();
+  }
+  burnReservation(_reservationId: string, _reason: string): Promise<void> {
+    throw new P2PQuorumNotImplementedError();
+  }
+  getLocalWatermark(_treeId: string): Promise<LocalWatermark> {
+    throw new P2PQuorumNotImplementedError();
+  }
+  publishWatermark(_treeId: string): Promise<void> {
+    throw new P2PQuorumNotImplementedError();
+  }
+  syncLeaseJournal(): Promise<SyncResult> {
+    throw new P2PQuorumNotImplementedError();
+  }
+  verifyLeaseCertificate(_cert?: LeaseCertificate): Promise<boolean> {
+    throw new P2PQuorumNotImplementedError();
+  }
+}
+
+/** Layer 5 — on-chain watermark coin. */
+export class OnchainWatermarkProvider implements WotsLeaseProvider {
+  reserveKeyUse(_params: ReserveParams): Promise<LeaseReservation> {
+    throw new OnchainWatermarkNotImplementedError();
+  }
+  commitKeyUse(_reservationId: string, _txId: string): Promise<void> {
+    throw new OnchainWatermarkNotImplementedError();
+  }
+  burnReservation(_reservationId: string, _reason: string): Promise<void> {
+    throw new OnchainWatermarkNotImplementedError();
+  }
+  getLocalWatermark(_treeId: string): Promise<LocalWatermark> {
+    throw new OnchainWatermarkNotImplementedError();
+  }
+  publishWatermark(_treeId: string): Promise<void> {
+    throw new OnchainWatermarkNotImplementedError();
+  }
+  syncLeaseJournal(): Promise<SyncResult> {
+    throw new OnchainWatermarkNotImplementedError();
+  }
+  verifyLeaseCertificate(_cert?: LeaseCertificate): Promise<boolean> {
+    throw new OnchainWatermarkNotImplementedError();
+  }
+}

package/src/types.ts

@@ -0,0 +1,119 @@
+/**
+ * @totemsdk/wots-lease — canonical v3 watermark types and WotsLeaseProvider interface
+ */
+
+export type UnavailableReason = 'committed' | 'burned' | 'reserved-expired';
+
+export interface SigningIndices {
+  addressIndex: number;
+  l1: number;
+  l2: number;
+}
+
+export type LeaseStatus = 'pending' | 'active' | 'expired' | 'finalized' | 'cancelled';
+
+export interface TreeWatermark {
+  treeId: string;
+  deviceId?: string;
+  branchId?: string;
+  addressCursor: number;
+  l1Cursor: number;
+  l2Cursor: number;
+  unavailable: Record<number, UnavailableReason>;
+  lastSyncTimestamp?: number;
+}
+
+export interface WotsWatermarkState {
+  version: 3;
+  trees: Record<string, TreeWatermark>;
+}
+
+export interface LeaseCertificate {
+  reservationId: string;
+  treeId: string;
+  branchId?: string;
+  deviceId?: string;
+  indices: SigningIndices;
+  purpose?: string;
+  payloadHash?: string;
+  issuedBy: string;
+  issuedAt: number;
+  expiresAt: number;
+  signature: string;
+}
+
+export interface LeaseReservation {
+  reservationId: string;
+  indices: SigningIndices;
+  expiresAt: number;
+  certificate?: LeaseCertificate;
+  leaseToken?: string;
+}
+
+export interface ReserveParams {
+  treeId: string;
+  branchId?: string;
+  purpose?: string;
+  deviceId?: string;
+  ttlMs?: number;
+  payloadHash?: string;
+  valueHint?: string;
+}
+
+export interface LocalWatermark {
+  treeId: string;
+  addressCursor: number;
+  l1Cursor: number;
+  l2Cursor: number;
+  unavailableCount: number;
+  capacity: number;
+  lastSyncTimestamp?: number;
+}
+
+export interface ConflictRecord {
+  treeId: string;
+  localIndex: number;
+  remoteIndex: number;
+  timestamp: number;
+}
+
+export interface SyncResult {
+  synced: boolean;
+  conflicts: ConflictRecord[];
+  advancedTo?: SigningIndices;
+}
+
+export interface WotsLeaseProvider {
+  reserveKeyUse(params: ReserveParams): Promise<LeaseReservation>;
+  commitKeyUse(reservationId: string, txId: string): Promise<void>;
+  burnReservation(reservationId: string, reason: string): Promise<void>;
+  getLocalWatermark(treeId: string): Promise<LocalWatermark>;
+  publishWatermark(treeId: string): Promise<void>;
+  syncLeaseJournal(): Promise<SyncResult>;
+  verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean>;
+}
+
+export interface JournalEntry {
+  treeId: string;
+  branchId: string;
+  wotsIndex: number;
+  indices: SigningIndices;
+  status: 'reserved' | 'committed' | 'burned' | 'reserved-expired';
+  payloadHash?: string;
+  txId?: string;
+  timestamp: number;
+  deviceId: string;
+}
+
+export interface DeviceKeyRange {
+  deviceId: string;
+  startAddressIndex: number;
+  endAddressIndex: number;
+  addressCount: number;
+}
+
+export interface PersonalLeaseNodeConfig {
+  nodeUrl: string;
+  nodePubkey: string;
+  authToken?: string;
+}

package/src/watermark.ts

@@ -0,0 +1,234 @@
+/**
+ * WotsWatermarkStore — canonical v3 implementation
+ *
+ * - Reads v1 (flat usedIndices) and v2 (per-address usedIndices) automatically on load.
+ * - Writes only v3.
+ * - Enforces monotonicity: unavailable map can only grow, cursors can only advance.
+ * - Storage key unchanged ('totem_wots_watermark') to avoid storage churn.
+ */
+
+import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
+import { NoopLogger } from '@totemsdk/core';
+import type {
+  WotsWatermarkState,
+  TreeWatermark,
+  SigningIndices,
+  UnavailableReason,
+  LocalWatermark,
+} from './types.js';
+import { WatermarkMonotonicityError, WatermarkExhaustedError } from './errors.js';
+
+const STORAGE_KEY = 'totem_wots_watermark';
+const MAX_L = 64;
+const CAPACITY_PER_TREE = MAX_L * MAX_L * MAX_L;
+const DEFAULT_TREE = 'default';
+
+export function flatIndex(idx: SigningIndices): number {
+  return idx.addressIndex * MAX_L * MAX_L + idx.l1 * MAX_L + idx.l2;
+}
+
+export function fromFlatIndex(flat: number): SigningIndices {
+  const addressIndex = Math.floor(flat / (MAX_L * MAX_L));
+  const rem = flat % (MAX_L * MAX_L);
+  const l1 = Math.floor(rem / MAX_L);
+  const l2 = rem % MAX_L;
+  return { addressIndex, l1, l2 };
+}
+
+function emptyTree(treeId: string): TreeWatermark {
+  return { treeId, addressCursor: 0, l1Cursor: 0, l2Cursor: 0, unavailable: {} };
+}
+
+function nextIndices(cur: SigningIndices): SigningIndices | null {
+  let { addressIndex, l1, l2 } = cur;
+  l2++;
+  if (l2 >= MAX_L) { l2 = 0; l1++; }
+  if (l1 >= MAX_L) { l1 = 0; addressIndex++; }
+  if (addressIndex >= MAX_L) return null;
+  return { addressIndex, l1, l2 };
+}
+
+type V1State = { next_addressIndex?: number; next_l1?: number; next_l2?: number; usedIndices?: Array<[number, number, number]> };
+type V2State = { version: 2; addresses: Record<number, { next_l1: number; next_l2: number; usedIndices: [number, number][] }> };
+type V3State = WotsWatermarkState;
+type RawState = V1State | V2State | V3State | null;
+
+function migrateToV3(raw: RawState): WotsWatermarkState {
+  if (!raw) {
+    return { version: 3, trees: {} };
+  }
+
+  if ('version' in raw && (raw as { version: number }).version === 3) {
+    return raw as V3State;
+  }
+
+  if ('version' in raw && (raw as { version: number }).version === 2) {
+    const v2 = raw as V2State;
+    const tree = emptyTree(DEFAULT_TREE);
+    let maxFlat = -1;
+    for (const [addrIdxStr, addrData] of Object.entries(v2.addresses)) {
+      const addressIndex = Number(addrIdxStr);
+      for (const [l1, l2] of addrData.usedIndices) {
+        const f = flatIndex({ addressIndex, l1, l2 });
+        tree.unavailable[f] = 'committed';
+        if (f > maxFlat) maxFlat = f;
+      }
+      const curFlat = flatIndex({ addressIndex, l1: addrData.next_l1, l2: addrData.next_l2 });
+      if (curFlat > maxFlat) maxFlat = curFlat;
+    }
+    if (maxFlat >= 0) {
+      const cur = fromFlatIndex(maxFlat);
+      tree.addressCursor = cur.addressIndex;
+      tree.l1Cursor = cur.l1;
+      tree.l2Cursor = cur.l2;
+    }
+    return { version: 3, trees: { [DEFAULT_TREE]: tree } };
+  }
+
+  const v1 = raw as V1State;
+  const tree = emptyTree(DEFAULT_TREE);
+  for (const [ai, l1, l2] of v1.usedIndices ?? []) {
+    const f = flatIndex({ addressIndex: ai, l1, l2 });
+    tree.unavailable[f] = 'committed';
+  }
+  tree.addressCursor = v1.next_addressIndex ?? 0;
+  tree.l1Cursor = v1.next_l1 ?? 0;
+  tree.l2Cursor = v1.next_l2 ?? 0;
+  return { version: 3, trees: { [DEFAULT_TREE]: tree } };
+}
+
+export class WotsWatermarkStore {
+  private state: WotsWatermarkState | null = null;
+  private _initialized = false;
+  private readonly logger: LoggerAdapter;
+
+  constructor(
+    private readonly storage: StorageAdapter,
+    logger: LoggerAdapter = new NoopLogger(),
+  ) {
+    this.logger = logger;
+  }
+
+  async initialize(): Promise<void> {
+    if (this._initialized) return;
+    const raw = await this.storage.get<RawState>(STORAGE_KEY);
+    this.state = migrateToV3(raw);
+    if (!('version' in (raw ?? {})) || (raw as { version?: number }).version !== 3) {
+      await this.persist();
+      this.logger.info('[WotsWatermarkStore] Migrated to v3');
+    }
+    this._initialized = true;
+  }
+
+  private ensureInit(): WotsWatermarkState {
+    if (!this.state) throw new Error('WotsWatermarkStore not initialized — call initialize() first');
+    return this.state;
+  }
+
+  private async persist(): Promise<void> {
+    await this.storage.set(STORAGE_KEY, this.state);
+  }
+
+  private getOrCreateTree(treeId: string): TreeWatermark {
+    const s = this.ensureInit();
+    if (!s.trees[treeId]) {
+      s.trees[treeId] = emptyTree(treeId);
+    }
+    return s.trees[treeId];
+  }
+
+  getNextIndices(treeId: string): SigningIndices {
+    const tree = this.getOrCreateTree(treeId);
+    let cur: SigningIndices = {
+      addressIndex: tree.addressCursor,
+      l1: tree.l1Cursor,
+      l2: tree.l2Cursor,
+    };
+    let attempts = 0;
+    while (attempts < CAPACITY_PER_TREE) {
+      if (!tree.unavailable[flatIndex(cur)]) return cur;
+      const nxt = nextIndices(cur);
+      if (!nxt) break;
+      cur = nxt;
+      attempts++;
+    }
+    throw new WatermarkExhaustedError(treeId);
+  }
+
+  async markUnavailable(
+    treeId: string,
+    indices: SigningIndices,
+    reason: UnavailableReason,
+  ): Promise<void> {
+    const tree = this.getOrCreateTree(treeId);
+    const f = flatIndex(indices);
+    tree.unavailable[f] = reason;
+    const nxt = nextIndices(indices);
+    if (nxt) {
+      const nxtFlat = flatIndex(nxt);
+      const curFlat = flatIndex({ addressIndex: tree.addressCursor, l1: tree.l1Cursor, l2: tree.l2Cursor });
+      if (nxtFlat > curFlat) {
+        tree.addressCursor = nxt.addressIndex;
+        tree.l1Cursor = nxt.l1;
+        tree.l2Cursor = nxt.l2;
+      }
+    }
+    await this.persist();
+  }
+
+  isUnavailable(treeId: string, indices: SigningIndices): boolean {
+    const s = this.ensureInit();
+    const tree = s.trees[treeId];
+    if (!tree) return false;
+    return flatIndex(indices) in tree.unavailable;
+  }
+
+  async save(treeId: string, patch: Partial<TreeWatermark>): Promise<void> {
+    const s = this.ensureInit();
+    const existing = s.trees[treeId] ?? emptyTree(treeId);
+    const merged: TreeWatermark = { ...existing, ...patch, treeId };
+
+    const existingFlat = flatIndex({ addressIndex: existing.addressCursor, l1: existing.l1Cursor, l2: existing.l2Cursor });
+    const newFlat = flatIndex({ addressIndex: merged.addressCursor, l1: merged.l1Cursor, l2: merged.l2Cursor });
+    if (newFlat < existingFlat) {
+      throw new WatermarkMonotonicityError(
+        `Cannot decrease watermark cursor for ${treeId}: ${existingFlat} → ${newFlat}`,
+      );
+    }
+
+    const existingUnavailCount = Object.keys(existing.unavailable).length;
+    const newUnavailCount = Object.keys(merged.unavailable).length;
+    if (newUnavailCount < existingUnavailCount) {
+      throw new WatermarkMonotonicityError(
+        `Cannot shrink unavailable map for ${treeId}: ${existingUnavailCount} → ${newUnavailCount}`,
+      );
+    }
+
+    s.trees[treeId] = merged;
+    await this.persist();
+  }
+
+  getLocalWatermark(treeId: string): LocalWatermark {
+    const s = this.ensureInit();
+    const tree = s.trees[treeId] ?? emptyTree(treeId);
+    return {
+      treeId,
+      addressCursor: tree.addressCursor,
+      l1Cursor: tree.l1Cursor,
+      l2Cursor: tree.l2Cursor,
+      unavailableCount: Object.keys(tree.unavailable).length,
+      capacity: CAPACITY_PER_TREE,
+      lastSyncTimestamp: tree.lastSyncTimestamp,
+    };
+  }
+
+  getRawState(): WotsWatermarkState {
+    return this.ensureInit();
+  }
+
+  async clear(): Promise<void> {
+    this.state = { version: 3, trees: {} };
+    this._initialized = false;
+    await this.storage.remove(STORAGE_KEY);
+  }
+}