@totemsdk/wots-lease 0.1.2 → 0.1.4

package/dist/stubs.js

@@ -1,92 +1,156 @@
+"use strict";
 /**
- * Stub implementations for Layers 3–5.
- * These throw descriptive errors until the full implementations land.
+ * Implementations for Layers 3–5 of the WotsLeaseProvider hierarchy.
+ *
+ * Layer 3 (PersonalLeaseNodeProvider) — HTTP client for a personal @totemsdk/lookup-node
+ *   that has lease coordination enabled ({ lease: { enabled: true } }).
+ *   The node exposes REST endpoints under /v1/lease/*.
+ *
+ * Layers 4–5 (P2PQuorumLeaseProvider, OnchainWatermarkProvider) — require
+ *   distributed infrastructure not yet available; they throw descriptive errors.
  */
-import { PersonalLeaseNodeNotConfiguredError, P2PQuorumNotImplementedError, OnchainWatermarkNotImplementedError, } from './errors.js';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnchainWatermarkProvider = exports.P2PQuorumLeaseProvider = exports.PersonalLeaseNodeProvider = void 0;
+const errors_js_1 = require("./errors.js");
 /**
- * Layer 3 — personal p2p lease node.
+ * Layer 3 — personal lookup-node lease coordinator.
+ *
+ * Calls the HTTP REST API exposed by a running @totemsdk/lookup-node that has
+ * lease coordination enabled. All write operations are forwarded to the node's
+ * LeaseCoordinator so the node acts as the source-of-truth watermark journal
+ * for high-value transactions.
+ *
+ * Wrap with HybridLeaseProvider so local reservations always succeed even when
+ * the personal node is temporarily unreachable:
  *
- * 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.
+ * ```ts
+ * const provider = new HybridLeaseProvider({
+ *   local: new LocalLeaseProvider(storage),
+ *   node:  new PersonalLeaseNodeProvider({ nodeUrl, nodePubkey }),
+ *   threshold: 10, // escalate to node for txns >= 10 MIN
+ * });
+ * ```
  */
-export class PersonalLeaseNodeProvider {
+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();
+        this.baseUrl = config.nodeUrl.replace(/\/$/, '');
+        this.nodePubkey = config.nodePubkey;
+        this.authToken = config.authToken;
+    }
+    headers() {
+        const h = { 'Content-Type': 'application/json' };
+        if (this.authToken)
+            h['Authorization'] = `Bearer ${this.authToken}`;
+        return h;
+    }
+    async post(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`PersonalLeaseNodeProvider: ${path} HTTP ${res.status} — ${text.slice(0, 200)}`);
+        }
+        return res.json();
+    }
+    async get(path) {
+        const res = await fetch(`${this.baseUrl}${path}`, { headers: this.headers() });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`PersonalLeaseNodeProvider: GET ${path} HTTP ${res.status} — ${text.slice(0, 200)}`);
+        }
+        return res.json();
+    }
+    async reserveKeyUse(params) {
+        const data = await this.post('/v1/lease/reserve', {
+            treeId: params.treeId,
+            branchId: params.branchId,
+            deviceId: params.deviceId,
+            ttlMs: params.ttlMs,
+            payloadHash: params.payloadHash,
+            purpose: params.purpose,
+        });
+        return { ...data.reservation, certificate: data.certificate };
+    }
+    async commitKeyUse(reservationId, txId) {
+        const data = await this.post('/v1/lease/commit', { reservationId, txId });
+        if (!data.ok)
+            throw new Error(`PersonalLeaseNodeProvider: commit failed — ${data.error ?? 'unknown'}`);
+    }
+    async burnReservation(reservationId, reason) {
+        const data = await this.post('/v1/lease/burn', { reservationId, reason });
+        if (!data.ok)
+            throw new Error(`PersonalLeaseNodeProvider: burn failed — ${data.error ?? 'unknown'}`);
+    }
+    async getLocalWatermark(treeId) {
+        return this.get(`/v1/lease/watermark/${encodeURIComponent(treeId)}`);
+    }
+    async publishWatermark(treeId) {
+        await this.post(`/v1/lease/watermark/${encodeURIComponent(treeId)}/publish`, {});
+    }
+    async syncLeaseJournal() {
+        return this.get('/v1/lease/journal/sync');
     }
     async verifyLeaseCertificate(cert) {
         if (!cert)
             return false;
-        if (cert.issuedBy !== this.config.nodePubkey)
+        if (cert.issuedBy !== this.nodePubkey)
             return false;
         if (cert.expiresAt <= Date.now())
             return false;
         return true;
     }
 }
+exports.PersonalLeaseNodeProvider = PersonalLeaseNodeProvider;
 /** Layer 4 — p2p replicated lease witnesses. */
-export class P2PQuorumLeaseProvider {
+class P2PQuorumLeaseProvider {
     reserveKeyUse(_params) {
-        throw new P2PQuorumNotImplementedError();
+        throw new errors_js_1.P2PQuorumNotImplementedError();
     }
     commitKeyUse(_reservationId, _txId) {
-        throw new P2PQuorumNotImplementedError();
+        throw new errors_js_1.P2PQuorumNotImplementedError();
     }
     burnReservation(_reservationId, _reason) {
-        throw new P2PQuorumNotImplementedError();
+        throw new errors_js_1.P2PQuorumNotImplementedError();
     }
     getLocalWatermark(_treeId) {
-        throw new P2PQuorumNotImplementedError();
+        throw new errors_js_1.P2PQuorumNotImplementedError();
     }
     publishWatermark(_treeId) {
-        throw new P2PQuorumNotImplementedError();
+        throw new errors_js_1.P2PQuorumNotImplementedError();
     }
     syncLeaseJournal() {
-        throw new P2PQuorumNotImplementedError();
+        throw new errors_js_1.P2PQuorumNotImplementedError();
     }
     verifyLeaseCertificate(_cert) {
-        throw new P2PQuorumNotImplementedError();
+        throw new errors_js_1.P2PQuorumNotImplementedError();
     }
 }
+exports.P2PQuorumLeaseProvider = P2PQuorumLeaseProvider;
 /** Layer 5 — on-chain watermark coin. */
-export class OnchainWatermarkProvider {
+class OnchainWatermarkProvider {
     reserveKeyUse(_params) {
-        throw new OnchainWatermarkNotImplementedError();
+        throw new errors_js_1.OnchainWatermarkNotImplementedError();
     }
     commitKeyUse(_reservationId, _txId) {
-        throw new OnchainWatermarkNotImplementedError();
+        throw new errors_js_1.OnchainWatermarkNotImplementedError();
     }
     burnReservation(_reservationId, _reason) {
-        throw new OnchainWatermarkNotImplementedError();
+        throw new errors_js_1.OnchainWatermarkNotImplementedError();
     }
     getLocalWatermark(_treeId) {
-        throw new OnchainWatermarkNotImplementedError();
+        throw new errors_js_1.OnchainWatermarkNotImplementedError();
     }
     publishWatermark(_treeId) {
-        throw new OnchainWatermarkNotImplementedError();
+        throw new errors_js_1.OnchainWatermarkNotImplementedError();
     }
     syncLeaseJournal() {
-        throw new OnchainWatermarkNotImplementedError();
+        throw new errors_js_1.OnchainWatermarkNotImplementedError();
     }
     verifyLeaseCertificate(_cert) {
-        throw new OnchainWatermarkNotImplementedError();
+        throw new errors_js_1.OnchainWatermarkNotImplementedError();
     }
 }
+exports.OnchainWatermarkProvider = OnchainWatermarkProvider;

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * @totemsdk/wots-lease — canonical v3 watermark types and WotsLeaseProvider interface
  */
-export type UnavailableReason = 'committed' | 'burned' | 'reserved-expired';
+export type UnavailableReason = 'reserved' | 'committed' | 'burned' | 'reserved-expired';
 export interface SigningIndices {
     addressIndex: number;
     l1: number;
@@ -86,10 +86,13 @@ export interface JournalEntry {
     wotsIndex: number;
     indices: SigningIndices;
     status: 'reserved' | 'committed' | 'burned' | 'reserved-expired';
+    reservationId?: string;
     payloadHash?: string;
     txId?: string;
     timestamp: number;
     deviceId: string;
+    previousHash?: string;
+    hash?: string;
 }
 export interface DeviceKeyRange {
     deviceId: string;

package/dist/types.js

@@ -1,4 +1,5 @@
+"use strict";
 /**
  * @totemsdk/wots-lease — canonical v3 watermark types and WotsLeaseProvider interface
  */
-export {};
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/watermark.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * WotsWatermarkStore — canonical v3 implementation
  *
@@ -6,16 +7,20 @@
  * - 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';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WotsWatermarkStore = void 0;
+exports.flatIndex = flatIndex;
+exports.fromFlatIndex = fromFlatIndex;
+const core_1 = require("@totemsdk/core");
+const errors_js_1 = require("./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) {
+function flatIndex(idx) {
     return idx.addressIndex * MAX_L * MAX_L + idx.l1 * MAX_L + idx.l2;
 }
-export function fromFlatIndex(flat) {
+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);
@@ -82,8 +87,8 @@ function migrateToV3(raw) {
     tree.l2Cursor = v1.next_l2 ?? 0;
     return { version: 3, trees: { [DEFAULT_TREE]: tree } };
 }
-export class WotsWatermarkStore {
-    constructor(storage, logger = new NoopLogger()) {
+class WotsWatermarkStore {
+    constructor(storage, logger = new core_1.NoopLogger()) {
         this.storage = storage;
         this.state = null;
         this._initialized = false;
@@ -132,7 +137,7 @@ export class WotsWatermarkStore {
             cur = nxt;
             attempts++;
         }
-        throw new WatermarkExhaustedError(treeId);
+        throw new errors_js_1.WatermarkExhaustedError(treeId);
     }
     async markUnavailable(treeId, indices, reason) {
         const tree = this.getOrCreateTree(treeId);
@@ -164,12 +169,12 @@ export class WotsWatermarkStore {
         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}`);
+            throw new errors_js_1.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}`);
+            throw new errors_js_1.WatermarkMonotonicityError(`Cannot shrink unavailable map for ${treeId}: ${existingUnavailCount} → ${newUnavailCount}`);
         }
         s.trees[treeId] = merged;
         await this.persist();
@@ -196,3 +201,4 @@ export class WotsWatermarkStore {
         await this.storage.remove(STORAGE_KEY);
     }
 }
+exports.WotsWatermarkStore = WotsWatermarkStore;

package/package.json

@@ -1,31 +1,37 @@
 {
   "name": "@totemsdk/wots-lease",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",
+      "require": "./dist/index.js",
       "import": "./dist/index.js"
     }
   },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests"
+  },
   "files": [
     "dist",
-    "src"
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
-    "@totemsdk/core": "1.0.9",
-    "@totemsdk/lookup-protocol": "0.1.2"
+    "@totemsdk/core": "^1.1.0",
+    "@totemsdk/lookup-protocol": "^0.1.3"
   },
   "devDependencies": {
-    "@noble/hashes": "^1.3.0",
-    "@types/jest": "^29.0.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
-    "jest": "^29.0.0",
+    "jest": "^30.4.2",
     "ts-jest": "^29.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -34,9 +40,24 @@
     "access": "public"
   },
   "license": "MIT",
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "test": "jest --passWithNoTests"
-  }
-}
+  "author": "Totem SDK",
+  "homepage": "https://totem.ing",
+  "bugs": {
+    "url": "https://github.com/totem-sdk/totem-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/totem-sdk/totem-sdk.git",
+    "directory": "packages/totem-sdk/packages/wots-lease"
+  },
+  "keywords": [
+    "totem",
+    "totemsdk",
+    "minima",
+    "blockchain",
+    "quantum-resistant",
+    "wots",
+    "kissvm",
+    "utxo"
+  ]
+}

package/src/__tests__/watermark.test.ts

@@ -1,200 +0,0 @@
-import { WotsWatermarkStore, flatIndex, fromFlatIndex } from '../watermark';
-import { WatermarkMonotonicityError, WatermarkExhaustedError } from '../errors';
-import { LocalLeaseProvider } from '../local';
-import { allocateDeviceRange } from '../device';
-import type { StorageAdapter } from '@totemsdk/core';
-
-function makeMemStorage(): StorageAdapter {
-  const store = new Map<string, unknown>();
-  return {
-    get: async <T>(key: string) => (store.has(key) ? (store.get(key) as T) : null),
-    set: async <T>(key: string, value: T) => { store.set(key, value); },
-    remove: async (key: string) => { const had = store.has(key); store.delete(key); return had; },
-    clear: async () => { store.clear(); },
-    keys: async () => Array.from(store.keys()),
-    has: async (key: string) => store.has(key),
-  };
-}
-
-describe('flatIndex / fromFlatIndex', () => {
-  it('round-trips', () => {
-    const cases = [
-      { addressIndex: 0, l1: 0, l2: 0 },
-      { addressIndex: 0, l1: 0, l2: 63 },
-      { addressIndex: 0, l1: 63, l2: 63 },
-      { addressIndex: 63, l1: 63, l2: 63 },
-      { addressIndex: 5, l1: 12, l2: 37 },
-    ];
-    for (const idx of cases) {
-      expect(fromFlatIndex(flatIndex(idx))).toEqual(idx);
-    }
-  });
-
-  it('total capacity is 64^3 = 262144', () => {
-    expect(flatIndex({ addressIndex: 63, l1: 63, l2: 63 })).toBe(262143);
-  });
-});
-
-describe('WotsWatermarkStore', () => {
-  it('initializes empty on first use', async () => {
-    const store = new WotsWatermarkStore(makeMemStorage());
-    await store.initialize();
-    const wm = store.getLocalWatermark('tree1');
-    expect(wm.addressCursor).toBe(0);
-    expect(wm.l1Cursor).toBe(0);
-    expect(wm.l2Cursor).toBe(0);
-    expect(wm.unavailableCount).toBe(0);
-    expect(wm.capacity).toBe(262144);
-  });
-
-  it('getNextIndices returns cursor position', async () => {
-    const store = new WotsWatermarkStore(makeMemStorage());
-    await store.initialize();
-    const idx = store.getNextIndices('tree1');
-    expect(idx).toEqual({ addressIndex: 0, l1: 0, l2: 0 });
-  });
-
-  it('markUnavailable advances cursor and records reason', async () => {
-    const store = new WotsWatermarkStore(makeMemStorage());
-    await store.initialize();
-    await store.markUnavailable('tree1', { addressIndex: 0, l1: 0, l2: 0 }, 'committed');
-    const next = store.getNextIndices('tree1');
-    expect(next).toEqual({ addressIndex: 0, l1: 0, l2: 1 });
-    expect(store.isUnavailable('tree1', { addressIndex: 0, l1: 0, l2: 0 })).toBe(true);
-    expect(store.isUnavailable('tree1', { addressIndex: 0, l1: 0, l2: 1 })).toBe(false);
-  });
-
-  it('migrates v1 flat state automatically', async () => {
-    const storage = makeMemStorage();
-    await storage.set('totem_wots_watermark', {
-      next_addressIndex: 0,
-      next_l1: 0,
-      next_l2: 3,
-      usedIndices: [[0, 0, 0], [0, 0, 1], [0, 0, 2]],
-    });
-    const store = new WotsWatermarkStore(storage);
-    await store.initialize();
-    const wm = store.getLocalWatermark('default');
-    expect(wm.unavailableCount).toBe(3);
-  });
-
-  it('migrates v2 per-address state automatically', async () => {
-    const storage = makeMemStorage();
-    await storage.set('totem_wots_watermark', {
-      version: 2,
-      addresses: {
-        0: { next_l1: 0, next_l2: 2, usedIndices: [[0, 0], [0, 1]] },
-      },
-    });
-    const store = new WotsWatermarkStore(storage);
-    await store.initialize();
-    const wm = store.getLocalWatermark('default');
-    expect(wm.unavailableCount).toBe(2);
-  });
-
-  it('throws WatermarkMonotonicityError if cursor decreases', async () => {
-    const store = new WotsWatermarkStore(makeMemStorage());
-    await store.initialize();
-    await store.markUnavailable('t', { addressIndex: 0, l1: 0, l2: 5 }, 'committed');
-    await expect(
-      store.save('t', { addressCursor: 0, l1Cursor: 0, l2Cursor: 0, unavailable: {} }),
-    ).rejects.toThrow(WatermarkMonotonicityError);
-  });
-
-  it('throws WatermarkMonotonicityError if unavailable map shrinks', async () => {
-    const store = new WotsWatermarkStore(makeMemStorage());
-    await store.initialize();
-    await store.markUnavailable('t', { addressIndex: 0, l1: 0, l2: 0 }, 'committed');
-    await expect(
-      store.save('t', { addressCursor: 0, l1Cursor: 0, l2Cursor: 1, unavailable: {} }),
-    ).rejects.toThrow(WatermarkMonotonicityError);
-  });
-});
-
-describe('LocalLeaseProvider', () => {
-  it('reserves and commits successfully', async () => {
-    const provider = new LocalLeaseProvider(makeMemStorage());
-    await provider.initialize();
-
-    const reservation = await provider.reserveKeyUse({ treeId: 'wallet' });
-    expect(reservation.reservationId).toBeTruthy();
-    expect(reservation.indices).toEqual({ addressIndex: 0, l1: 0, l2: 0 });
-
-    await provider.commitKeyUse(reservation.reservationId, '0xTXID');
-
-    const wm = await provider.getLocalWatermark('wallet');
-    expect(wm.unavailableCount).toBe(1);
-  });
-
-  it('burns reservation — marks index permanently unavailable', async () => {
-    const storage = makeMemStorage();
-    const provider = new LocalLeaseProvider(storage);
-    await provider.initialize();
-
-    const reservation = await provider.reserveKeyUse({ treeId: 'wallet' });
-    await provider.burnReservation(reservation.reservationId, 'test burn');
-
-    const store = new WotsWatermarkStore(storage);
-    await store.initialize();
-    expect(store.isUnavailable('wallet', reservation.indices)).toBe(true);
-  });
-
-  it('two consecutive reserves yield different indices', async () => {
-    const provider = new LocalLeaseProvider(makeMemStorage());
-    await provider.initialize();
-
-    const r1 = await provider.reserveKeyUse({ treeId: 'wallet' });
-    await provider.commitKeyUse(r1.reservationId, '0xA');
-    const r2 = await provider.reserveKeyUse({ treeId: 'wallet' });
-
-    expect(flatIndex(r2.indices)).toBeGreaterThan(flatIndex(r1.indices));
-  });
-
-  it('syncLeaseJournal returns synced:true (local no-op)', async () => {
-    const provider = new LocalLeaseProvider(makeMemStorage());
-    await provider.initialize();
-    const result = await provider.syncLeaseJournal();
-    expect(result.synced).toBe(true);
-  });
-
-  it('verifyLeaseCertificate returns true when cert is undefined', async () => {
-    const provider = new LocalLeaseProvider(makeMemStorage());
-    await provider.initialize();
-    expect(await provider.verifyLeaseCertificate(undefined)).toBe(true);
-  });
-
-  it('verifyLeaseCertificate returns false for external cert', async () => {
-    const provider = new LocalLeaseProvider(makeMemStorage());
-    await provider.initialize();
-    const cert = {
-      reservationId: 'r1',
-      treeId: 'wallet',
-      indices: { addressIndex: 0, l1: 0, l2: 0 },
-      issuedBy: 'external-key',
-      issuedAt: Date.now(),
-      expiresAt: Date.now() + 120000,
-      signature: 'sig',
-    };
-    expect(await provider.verifyLeaseCertificate(cert)).toBe(false);
-  });
-});
-
-describe('allocateDeviceRange', () => {
-  it('slot 0 gets addressIndex 0–7', () => {
-    const range = allocateDeviceRange({ deviceSlot: 0, deviceId: 'phone' });
-    expect(range.startAddressIndex).toBe(0);
-    expect(range.endAddressIndex).toBe(7);
-    expect(range.addressCount).toBe(8);
-  });
-
-  it('slot 3 gets addressIndex 24–31', () => {
-    const range = allocateDeviceRange({ deviceSlot: 3, deviceId: 'pear' });
-    expect(range.startAddressIndex).toBe(24);
-    expect(range.endAddressIndex).toBe(31);
-  });
-
-  it('throws on out-of-range slot', () => {
-    expect(() => allocateDeviceRange({ deviceSlot: 8, deviceId: 'x' })).toThrow(RangeError);
-    expect(() => allocateDeviceRange({ deviceSlot: -1, deviceId: 'x' })).toThrow(RangeError);
-  });
-});