@totemsdk/wots-lease 1.0.0 → 1.0.2

package/dist/types.d.ts

@@ -2,6 +2,7 @@
  * @totemsdk/wots-lease — canonical v3 watermark types and WotsLeaseProvider interface
  */
 import type { LocalLeaseProvider } from './local.js';
+import type { StorageAdapter } from '@totemsdk/core';
 export type UnavailableReason = 'reserved' | 'committed' | 'burned' | 'reserved-expired';
 export interface SigningIndices {
     addressIndex: number;
@@ -28,6 +29,28 @@ export interface QuorumAttestation {
     indices: SigningIndices;
     expiresAt: number;
     signature?: string;
+    /**
+     * The reservation id the peer issued for these indices in its own journal.
+     * Commit/burn broadcasts must reference the peer's id, not the local one
+     * (AUD-044) — each peer only knows the reservation it issued.
+     */
+    peerReservationId?: string;
+}
+/**
+ * Identity used to authenticate lease certificates (Layer 4/5).
+ *
+ * A certificate's `signature` is a signature over the canonical certificate
+ * payload (see certificate.ts). Verifiers reject unsigned certificates.
+ */
+export interface CertificateSigner {
+    /** Hex (0x-prefixed or bare) public key digest of the issuing identity. */
+    publicKeyDigest: string;
+    /** Identity label stored on issued certificates via `issuedBy`. */
+    name?: string;
+    /** Sign the canonical certificate message. */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    /** Verify a signature over the canonical certificate message. */
+    verify?(message: Uint8Array, signature: Uint8Array): Promise<boolean>;
 }
 export interface LeaseCertificate {
     reservationId: string;
@@ -71,6 +94,28 @@ export interface LocalWatermark {
     capacity: number;
     lastSyncTimestamp?: number;
 }
+/**
+ * A portable, self-describing watermark snapshot (RFC-013 §9). Used to seed a
+ * freshly-provisioned local watermark from an exported blob, an operator-supplied
+ * high-water mark, or the on-chain cursor, so a restored wallet never starts
+ * below the true high-water mark and reissues a spent leaf.
+ */
+export interface WatermarkSeed {
+    readonly version: 1;
+    readonly treeId: string;
+    readonly addressCursor: number;
+    readonly l1Cursor: number;
+    readonly l2Cursor: number;
+    /** Flat indices already consumed (reserved/committed/burned). */
+    readonly unavailable?: readonly number[];
+}
+export interface SeedWatermarkOptions {
+    /**
+     * Permit a seed whose cursor is behind the current local cursor. Defaults to
+     * `false` — regression re-exposes used leaves, so seeding fails closed.
+     */
+    readonly allowRegression?: boolean;
+}
 export interface ConflictRecord {
     treeId: string;
     localIndex: number;
@@ -115,6 +160,21 @@ export interface PersonalLeaseNodeConfig {
     nodeUrl: string;
     nodePubkey: string;
     authToken?: string;
+    /**
+     * Identity that authenticates certificates issued by this node. When it
+     * carries a `verify()` function, `verifyLeaseCertificate` uses it. Without
+     * any verifier the provider FAILS CLOSED (AUD-016) — an identity match on
+     * `issuedBy` alone is never enough.
+     */
+    certificateSigner?: CertificateSigner;
+    /**
+     * Verify-only cryptographic verifier for certificates issued by the node.
+     * The provider holds no signing key, so this is the recommended way to make
+     * `verifyLeaseCertificate` functional. When neither this nor a
+     * `certificateSigner.verify` is supplied, the provider rejects every
+     * certificate (fail closed).
+     */
+    verify?: (message: Uint8Array, signature: Uint8Array) => Promise<boolean>;
 }
 /**
  * Layer 4 — P2P quorum lease coordination.
@@ -146,6 +206,12 @@ export interface P2PQuorumLeaseProviderConfig {
     requestTimeoutMs?: number;
     /** Require quorum approval on commit as well as reserve. Default: false. */
     requireQuorumOnCommit?: boolean;
+    /**
+     * Identity that authenticates issued certificates. When set, reserved
+     * certificates carry a real signature; without it, certificates are
+     * issued unsigned and will FAIL verification.
+     */
+    certificateSigner?: CertificateSigner;
 }
 /**
  * Layer 5 — on-chain watermark anchoring.
@@ -187,13 +253,20 @@ export interface OnchainWatermarkProviderConfig {
     amount?: string;
     /** Local provider used for the authoritative local watermark + journal. */
     local: LocalLeaseProvider;
-    /** Signer for the watermark coin's script (SIGNEDBY digest). */
+    /** Signer for the watermark coin's script (SIGNEDBY digest). Also authenticates issued certificates. */
     signer: {
         publicKeyDigest: string;
         sign(message: Uint8Array): Promise<Uint8Array>;
+        verify?(message: Uint8Array, signature: Uint8Array): Promise<boolean>;
     };
     /** Port holding the flat watermark cursor in the coin state. Default: 0. */
     statePort?: number;
     /** Minimum blocks between on-chain publishes (rate limit). Default: 1. */
     minBlocksBetweenPublishes?: number;
+    /**
+     * Optional durable storage for the watermark coin's identity. When set, the
+     * provider persists the advanced watermark coin ID after each publish so the
+     * rollover survives restarts. Default: in-memory only.
+     */
+    storage?: StorageAdapter;
 }

package/dist/types.js

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

package/dist/watermark.d.ts

@@ -7,9 +7,10 @@
  * - 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';
+import type { WotsWatermarkState, TreeWatermark, SigningIndices, UnavailableReason, LocalWatermark, WatermarkSeed, SeedWatermarkOptions } from './types.js';
 export declare function flatIndex(idx: SigningIndices): number;
 export declare function fromFlatIndex(flat: number): SigningIndices;
+export declare function assertValidSigningIndices(indices: SigningIndices): void;
 export declare class WotsWatermarkStore {
     private readonly storage;
     private state;
@@ -19,12 +20,32 @@ export declare class WotsWatermarkStore {
     initialize(): Promise<void>;
     private ensureInit;
     private persist;
+    /**
+     * Reload the persisted watermark and merge it monotonically into the local
+     * state. A provider that shares its storage with another provider (AUD-004)
+     * must call this inside its mutation critical section before allocating or
+     * marking, so it observes writes it did not make and never re-issues a slot
+     * another instance already took.
+     */
+    refresh(): Promise<void>;
     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;
+    /**
+     * Export a portable seed for a tree (RFC-013 §9). Includes the cursor and the
+     * flat indices already consumed, so it can rebuild the no-reuse state exactly.
+     */
+    exportSeed(treeId: string): WatermarkSeed;
+    /**
+     * Seed the watermark from an exported/operator/on-chain snapshot. Forward-only
+     * by default: a seed behind the current cursor raises
+     * {@link WatermarkSeedRegressionError} so a restore can never re-expose used
+     * leaves. The unavailable set is unioned, never shrunk.
+     */
+    seed(seed: WatermarkSeed, options?: SeedWatermarkOptions): Promise<void>;
     getRawState(): WotsWatermarkState;
     clear(): Promise<void>;
 }

package/dist/watermark.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * WotsWatermarkStore — canonical v3 implementation
  *
@@ -7,26 +6,34 @@
  * - Enforces monotonicity: unavailable map can only grow, cursors can only advance.
  * - Storage key unchanged ('totem_wots_watermark') to avoid storage churn.
  */
-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");
+import { NoopLogger } from '@totemsdk/core';
+import { WatermarkMonotonicityError, WatermarkExhaustedError, WatermarkSeedRegressionError, } 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';
-function flatIndex(idx) {
+export function flatIndex(idx) {
+    assertValidSigningIndices(idx);
     return idx.addressIndex * MAX_L * MAX_L + idx.l1 * MAX_L + idx.l2;
 }
-function fromFlatIndex(flat) {
+export function fromFlatIndex(flat) {
+    if (!Number.isSafeInteger(flat) || flat < 0 || flat >= CAPACITY_PER_TREE) {
+        throw new RangeError(`WOTS flat index must be an integer in [0, ${CAPACITY_PER_TREE - 1}]`);
+    }
     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 };
 }
+export function assertValidSigningIndices(indices) {
+    for (const name of ['addressIndex', 'l1', 'l2']) {
+        const value = indices[name];
+        if (!Number.isSafeInteger(value) || value < 0 || value >= MAX_L) {
+            throw new RangeError(`WOTS ${name} must be an integer in [0, ${MAX_L - 1}]`);
+        }
+    }
+}
 function emptyTree(treeId) {
     return { treeId, addressCursor: 0, l1Cursor: 0, l2Cursor: 0, unavailable: {} };
 }
@@ -45,6 +52,37 @@ function nextIndices(cur) {
         return null;
     return { addressIndex, l1, l2 };
 }
+/**
+ * Monotonic merge of two watermark states: the cursor is the further of the
+ * two and the unavailable maps are unioned, so merging never re-exposes a used
+ * index. Used to pick up writes made by another provider over the same storage
+ * (AUD-004).
+ */
+function mergeWatermarkState(a, b) {
+    if (!a)
+        return b;
+    const trees = { ...a.trees };
+    for (const [treeId, bt] of Object.entries(b.trees)) {
+        const at = trees[treeId];
+        if (!at) {
+            trees[treeId] = bt;
+            continue;
+        }
+        const aFlat = flatIndex({ addressIndex: at.addressCursor, l1: at.l1Cursor, l2: at.l2Cursor });
+        const bFlat = flatIndex({ addressIndex: bt.addressCursor, l1: bt.l1Cursor, l2: bt.l2Cursor });
+        const cursor = bFlat > aFlat ? bt : at;
+        const lastSync = Math.max(at.lastSyncTimestamp ?? 0, bt.lastSyncTimestamp ?? 0);
+        trees[treeId] = {
+            treeId,
+            addressCursor: cursor.addressCursor,
+            l1Cursor: cursor.l1Cursor,
+            l2Cursor: cursor.l2Cursor,
+            unavailable: { ...bt.unavailable, ...at.unavailable },
+            ...(lastSync > 0 ? { lastSyncTimestamp: lastSync } : {}),
+        };
+    }
+    return { version: 3, trees };
+}
 function migrateToV3(raw) {
     if (!raw) {
         return { version: 3, trees: {} };
@@ -87,8 +125,8 @@ function migrateToV3(raw) {
     tree.l2Cursor = v1.next_l2 ?? 0;
     return { version: 3, trees: { [DEFAULT_TREE]: tree } };
 }
-class WotsWatermarkStore {
-    constructor(storage, logger = new core_1.NoopLogger()) {
+export class WotsWatermarkStore {
+    constructor(storage, logger = new NoopLogger()) {
         this.storage = storage;
         this.state = null;
         this._initialized = false;
@@ -113,6 +151,19 @@ class WotsWatermarkStore {
     async persist() {
         await this.storage.set(STORAGE_KEY, this.state);
     }
+    /**
+     * Reload the persisted watermark and merge it monotonically into the local
+     * state. A provider that shares its storage with another provider (AUD-004)
+     * must call this inside its mutation critical section before allocating or
+     * marking, so it observes writes it did not make and never re-issues a slot
+     * another instance already took.
+     */
+    async refresh() {
+        if (!this._initialized || !this.state)
+            return;
+        const raw = await this.storage.get(STORAGE_KEY);
+        this.state = mergeWatermarkState(this.state, migrateToV3(raw));
+    }
     getOrCreateTree(treeId) {
         const s = this.ensureInit();
         if (!s.trees[treeId]) {
@@ -137,7 +188,7 @@ class WotsWatermarkStore {
             cur = nxt;
             attempts++;
         }
-        throw new errors_js_1.WatermarkExhaustedError(treeId);
+        throw new WatermarkExhaustedError(treeId);
     }
     async markUnavailable(treeId, indices, reason) {
         const tree = this.getOrCreateTree(treeId);
@@ -160,7 +211,13 @@ class WotsWatermarkStore {
         const tree = s.trees[treeId];
         if (!tree)
             return false;
-        return flatIndex(indices) in tree.unavailable;
+        const index = flatIndex(indices);
+        const cursor = flatIndex({
+            addressIndex: tree.addressCursor,
+            l1: tree.l1Cursor,
+            l2: tree.l2Cursor,
+        });
+        return index < cursor || index in tree.unavailable;
     }
     async save(treeId, patch) {
         const s = this.ensureInit();
@@ -169,12 +226,12 @@ 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 errors_js_1.WatermarkMonotonicityError(`Cannot decrease watermark cursor for ${treeId}: ${existingFlat} → ${newFlat}`);
+            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 errors_js_1.WatermarkMonotonicityError(`Cannot shrink unavailable map for ${treeId}: ${existingUnavailCount} → ${newUnavailCount}`);
+            throw new WatermarkMonotonicityError(`Cannot shrink unavailable map for ${treeId}: ${existingUnavailCount} → ${newUnavailCount}`);
         }
         s.trees[treeId] = merged;
         await this.persist();
@@ -192,6 +249,67 @@ class WotsWatermarkStore {
             lastSyncTimestamp: tree.lastSyncTimestamp,
         };
     }
+    /**
+     * Export a portable seed for a tree (RFC-013 §9). Includes the cursor and the
+     * flat indices already consumed, so it can rebuild the no-reuse state exactly.
+     */
+    exportSeed(treeId) {
+        const s = this.ensureInit();
+        const tree = s.trees[treeId] ?? emptyTree(treeId);
+        const unavailable = Object.keys(tree.unavailable)
+            .map((k) => Number(k))
+            .filter((f) => Number.isSafeInteger(f))
+            .sort((a, b) => a - b);
+        return {
+            version: 1,
+            treeId,
+            addressCursor: tree.addressCursor,
+            l1Cursor: tree.l1Cursor,
+            l2Cursor: tree.l2Cursor,
+            unavailable,
+        };
+    }
+    /**
+     * Seed the watermark from an exported/operator/on-chain snapshot. Forward-only
+     * by default: a seed behind the current cursor raises
+     * {@link WatermarkSeedRegressionError} so a restore can never re-expose used
+     * leaves. The unavailable set is unioned, never shrunk.
+     */
+    async seed(seed, options = {}) {
+        const s = this.ensureInit();
+        const existing = s.trees[seed.treeId] ?? emptyTree(seed.treeId);
+        const seedCursor = flatIndex({
+            addressIndex: seed.addressCursor,
+            l1: seed.l1Cursor,
+            l2: seed.l2Cursor,
+        });
+        const existingCursor = flatIndex({
+            addressIndex: existing.addressCursor,
+            l1: existing.l1Cursor,
+            l2: existing.l2Cursor,
+        });
+        if (!options.allowRegression && seedCursor < existingCursor) {
+            throw new WatermarkSeedRegressionError(seed.treeId, existingCursor, seedCursor);
+        }
+        const unavailable = { ...existing.unavailable };
+        for (const flat of seed.unavailable ?? []) {
+            if (!Number.isSafeInteger(flat) || flat < 0 || flat >= CAPACITY_PER_TREE) {
+                throw new RangeError(`Seed unavailable index must be an integer in [0, ${CAPACITY_PER_TREE - 1}]`);
+            }
+            if (!(flat in unavailable))
+                unavailable[flat] = 'committed';
+        }
+        s.trees[seed.treeId] = {
+            ...existing,
+            treeId: seed.treeId,
+            addressCursor: seed.addressCursor,
+            l1Cursor: seed.l1Cursor,
+            l2Cursor: seed.l2Cursor,
+            unavailable,
+            lastSyncTimestamp: Date.now(),
+        };
+        await this.persist();
+    }
     getRawState() {
         return this.ensureInit();
     }
@@ -201,4 +319,3 @@ class WotsWatermarkStore {
         await this.storage.remove(STORAGE_KEY);
     }
 }
-exports.WotsWatermarkStore = WotsWatermarkStore;

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@totemsdk/wots-lease",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "WOTS key-use coordination — canonical v3 watermark, provider-based lease safety layers",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/cjs/index.js",
+  "types": "dist/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.js",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "files": [
@@ -16,12 +21,16 @@
     "rust/pkg/",
     "rust/pkg-node/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "dependencies": {
-    "@totemsdk/lookup-protocol": "^0.1.6",
-    "@totemsdk/core": "^1.2.9",
-    "@totemsdk/txpow": "^0.1.7"
+    "@noble/hashes": "^1.8.0",
+    "@totemsdk/core": "^1.4.2",
+    "@totemsdk/txpow": "^1.1.1",
+    "@totemsdk/replication": "^0.2.0",
+    "@totemsdk/lookup-protocol": "^0.3.0",
+    "@totemsdk/storage": "^0.2.2"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -36,15 +45,15 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "Totem SDK",
-  "homepage": "https://totem.ing",
+  "homepage": "https://docs.totem.ing",
   "bugs": {
-    "url": "https://github.com/totem-sdk/totem-sdk/issues"
+    "url": "https://github.com/Totem-Edge/totem-sdk/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/totem-sdk/totem-sdk.git",
+    "url": "git+https://github.com/Totem-Edge/totem-sdk.git",
     "directory": "packages/wots-lease"
   },
   "keywords": [
@@ -56,8 +65,9 @@
     "wots",
     "utxo"
   ],
+  "type": "module",
   "scripts": {
-    "build": "npm run build:wasm && tsc && node ../../scripts/clean-wasm-output-ignores.mjs",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'})+'\\n')\"",
     "build:wasm": "cd rust && wasm-pack build --target bundler --out-dir pkg && wasm-pack build --target nodejs --out-dir pkg-node",
     "clean": "rm -rf dist rust/pkg rust/pkg-node rust/target",
     "test": "jest"

package/rust/pkg/package.json

@@ -6,10 +6,10 @@
   ],
   "description": "WOTS key-use coordination — canonical v3 watermark, flat index computation, monotonicity enforcement, device keyspace partitioning (Rust/WASM)",
   "version": "0.1.0",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/totem-sdk/totem-sdk"
+    "url": "https://github.com/Totem-Edge/totem-sdk"
   },
   "files": [
     "wots_lease_wasm_bg.wasm",
@@ -24,4 +24,4 @@
     "./wots_lease_wasm.js",
     "./snippets/*"
   ]
-}
+}

package/rust/pkg-node/package.json

@@ -5,10 +5,10 @@
   ],
   "description": "WOTS key-use coordination — canonical v3 watermark, flat index computation, monotonicity enforcement, device keyspace partitioning (Rust/WASM)",
   "version": "0.1.0",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/totem-sdk/totem-sdk"
+    "url": "https://github.com/Totem-Edge/totem-sdk"
   },
   "files": [
     "wots_lease_wasm_bg.wasm",
@@ -18,4 +18,4 @@
   "main": "wots_lease_wasm.js",
   "homepage": "https://totem.ing",
   "types": "wots_lease_wasm.d.ts"
-}
+}