@totemsdk/wots-lease 0.1.0

package/dist/stubs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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';
+/**
+ * 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 declare class PersonalLeaseNodeProvider implements WotsLeaseProvider {
+    private readonly config;
+    constructor(config: PersonalLeaseNodeConfig);
+    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>;
+}
+/** Layer 4 — p2p replicated lease witnesses. */
+export declare class P2PQuorumLeaseProvider implements 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>;
+}
+/** Layer 5 — on-chain watermark coin. */
+export declare class OnchainWatermarkProvider implements 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>;
+}

package/dist/stubs.js

@@ -0,0 +1,92 @@
+/**
+ * Stub implementations for Layers 3–5.
+ * These throw descriptive errors until the full implementations land.
+ */
+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 {
+    constructor(config) {
+        this.config = config;
+    }
+    reserveKeyUse(_params) {
+        throw new PersonalLeaseNodeNotConfiguredError();
+    }
+    commitKeyUse(_reservationId, _txId) {
+        throw new PersonalLeaseNodeNotConfiguredError();
+    }
+    burnReservation(_reservationId, _reason) {
+        throw new PersonalLeaseNodeNotConfiguredError();
+    }
+    getLocalWatermark(_treeId) {
+        throw new PersonalLeaseNodeNotConfiguredError();
+    }
+    publishWatermark(_treeId) {
+        throw new PersonalLeaseNodeNotConfiguredError();
+    }
+    syncLeaseJournal() {
+        throw new PersonalLeaseNodeNotConfiguredError();
+    }
+    async verifyLeaseCertificate(cert) {
+        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 {
+    reserveKeyUse(_params) {
+        throw new P2PQuorumNotImplementedError();
+    }
+    commitKeyUse(_reservationId, _txId) {
+        throw new P2PQuorumNotImplementedError();
+    }
+    burnReservation(_reservationId, _reason) {
+        throw new P2PQuorumNotImplementedError();
+    }
+    getLocalWatermark(_treeId) {
+        throw new P2PQuorumNotImplementedError();
+    }
+    publishWatermark(_treeId) {
+        throw new P2PQuorumNotImplementedError();
+    }
+    syncLeaseJournal() {
+        throw new P2PQuorumNotImplementedError();
+    }
+    verifyLeaseCertificate(_cert) {
+        throw new P2PQuorumNotImplementedError();
+    }
+}
+/** Layer 5 — on-chain watermark coin. */
+export class OnchainWatermarkProvider {
+    reserveKeyUse(_params) {
+        throw new OnchainWatermarkNotImplementedError();
+    }
+    commitKeyUse(_reservationId, _txId) {
+        throw new OnchainWatermarkNotImplementedError();
+    }
+    burnReservation(_reservationId, _reason) {
+        throw new OnchainWatermarkNotImplementedError();
+    }
+    getLocalWatermark(_treeId) {
+        throw new OnchainWatermarkNotImplementedError();
+    }
+    publishWatermark(_treeId) {
+        throw new OnchainWatermarkNotImplementedError();
+    }
+    syncLeaseJournal() {
+        throw new OnchainWatermarkNotImplementedError();
+    }
+    verifyLeaseCertificate(_cert) {
+        throw new OnchainWatermarkNotImplementedError();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @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/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * @totemsdk/wots-lease — canonical v3 watermark types and WotsLeaseProvider interface
+ */
+export {};

package/dist/watermark.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 type { WotsWatermarkState, TreeWatermark, SigningIndices, UnavailableReason, LocalWatermark } from './types.js';
+export declare function flatIndex(idx: SigningIndices): number;
+export declare function fromFlatIndex(flat: number): SigningIndices;
+export declare class WotsWatermarkStore {
+    private readonly storage;
+    private state;
+    private _initialized;
+    private readonly logger;
+    constructor(storage: StorageAdapter, logger?: LoggerAdapter);
+    initialize(): Promise<void>;
+    private ensureInit;
+    private persist;
+    private getOrCreateTree;
+    getNextIndices(treeId: string): SigningIndices;
+    markUnavailable(treeId: string, indices: SigningIndices, reason: UnavailableReason): Promise<void>;
+    isUnavailable(treeId: string, indices: SigningIndices): boolean;
+    save(treeId: string, patch: Partial<TreeWatermark>): Promise<void>;
+    getLocalWatermark(treeId: string): LocalWatermark;
+    getRawState(): WotsWatermarkState;
+    clear(): Promise<void>;
+}

package/dist/watermark.js

@@ -0,0 +1,198 @@
+/**
+ * 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 { NoopLogger } from '@totemsdk/core';
+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) {
+    return idx.addressIndex * MAX_L * MAX_L + idx.l1 * MAX_L + idx.l2;
+}
+export function fromFlatIndex(flat) {
+    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) {
+    return { treeId, addressCursor: 0, l1Cursor: 0, l2Cursor: 0, unavailable: {} };
+}
+function nextIndices(cur) {
+    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 };
+}
+function migrateToV3(raw) {
+    if (!raw) {
+        return { version: 3, trees: {} };
+    }
+    if ('version' in raw && raw.version === 3) {
+        return raw;
+    }
+    if ('version' in raw && raw.version === 2) {
+        const v2 = raw;
+        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;
+    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 {
+    constructor(storage, logger = new NoopLogger()) {
+        this.storage = storage;
+        this.state = null;
+        this._initialized = false;
+        this.logger = logger;
+    }
+    async initialize() {
+        if (this._initialized)
+            return;
+        const raw = await this.storage.get(STORAGE_KEY);
+        this.state = migrateToV3(raw);
+        if (!('version' in (raw ?? {})) || raw.version !== 3) {
+            await this.persist();
+            this.logger.info('[WotsWatermarkStore] Migrated to v3');
+        }
+        this._initialized = true;
+    }
+    ensureInit() {
+        if (!this.state)
+            throw new Error('WotsWatermarkStore not initialized — call initialize() first');
+        return this.state;
+    }
+    async persist() {
+        await this.storage.set(STORAGE_KEY, this.state);
+    }
+    getOrCreateTree(treeId) {
+        const s = this.ensureInit();
+        if (!s.trees[treeId]) {
+            s.trees[treeId] = emptyTree(treeId);
+        }
+        return s.trees[treeId];
+    }
+    getNextIndices(treeId) {
+        const tree = this.getOrCreateTree(treeId);
+        let cur = {
+            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, indices, reason) {
+        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, indices) {
+        const s = this.ensureInit();
+        const tree = s.trees[treeId];
+        if (!tree)
+            return false;
+        return flatIndex(indices) in tree.unavailable;
+    }
+    async save(treeId, patch) {
+        const s = this.ensureInit();
+        const existing = s.trees[treeId] ?? emptyTree(treeId);
+        const merged = { ...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) {
+        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() {
+        return this.ensureInit();
+    }
+    async clear() {
+        this.state = { version: 3, trees: {} };
+        this._initialized = false;
+        await this.storage.remove(STORAGE_KEY);
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@totemsdk/wots-lease",
+  "version": "0.1.0",
+  "description": "WOTS key-use coordination — canonical v3 watermark, provider-based lease safety layers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@totemsdk/core": "workspace:*",
+    "@totemsdk/lookup-protocol": "workspace:*"
+  },
+  "devDependencies": {
+    "@noble/hashes": "^1.3.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}