@totemsdk/wots-lease 0.1.6 → 1.0.1

package/dist/quorum.js

@@ -31,17 +31,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.P2PQuorumLeaseProvider = void 0;
 const errors_js_1 = require("./errors.js");
+const certificate_js_1 = require("./certificate.js");
 function sameIndices(a, b) {
     return a.addressIndex === b.addressIndex && a.l1 === b.l1 && a.l2 === b.l2;
 }
 class P2PQuorumLeaseProvider {
     constructor(config) {
+        /**
+         * localReservationId -> (peerId -> the reservation id that peer issued).
+         * Commit/burn must reference each peer's own id, because a peer only knows
+         * the reservation it issued, not the local provider's id (AUD-044).
+         */
+        this.peerReservationIds = new Map();
         this._initialized = false;
         this.peers = config.peers;
         this.minAttestations = config.minAttestations ?? 1;
         this.local = config.local;
         this.requestTimeoutMs = config.requestTimeoutMs ?? 5000;
         this.requireQuorumOnCommit = config.requireQuorumOnCommit ?? false;
+        this.certificateSigner = config.certificateSigner;
     }
     async initialize() {
         if (this._initialized)
@@ -73,6 +81,7 @@ class P2PQuorumLeaseProvider {
             await this.local.burnReservation(reservation.reservationId, reason);
             throw err;
         }
+        this.recordPeerReservationIds(reservation.reservationId, attestations);
         const certificate = {
             reservationId: reservation.reservationId,
             treeId: params.treeId,
@@ -81,12 +90,13 @@ class P2PQuorumLeaseProvider {
             indices: reservation.indices,
             purpose: params.purpose,
             payloadHash: params.payloadHash,
-            issuedBy: 'p2p-quorum',
+            issuedBy: this.certificateSigner?.name ?? 'p2p-quorum',
             issuedAt: Date.now(),
             expiresAt: reservation.expiresAt,
             signature: '',
             attestations,
         };
+        certificate.signature = this.certificateSigner ? await (0, certificate_js_1.signCertificate)(this.certificateSigner, certificate) : '';
         return { ...reservation, certificate };
     }
     /**
@@ -123,10 +133,14 @@ class P2PQuorumLeaseProvider {
                     conflicts.push('peer returned mismatched indices');
                     return;
                 }
+                const peerReservationId = body.reservation?.reservationId;
                 attestations.push({
                     peerId: peer.peerId,
                     indices,
                     expiresAt: body.reservation?.expiresAt ?? Date.now() + (params.ttlMs ?? 120000),
+                    ...(typeof peerReservationId === 'string' && peerReservationId.length > 0
+                        ? { peerReservationId }
+                        : {}),
                 });
             }
             catch {
@@ -147,7 +161,10 @@ class P2PQuorumLeaseProvider {
     async commitKeyUse(reservationId, txId) {
         await this.ensureInit();
         await this.local.commitKeyUse(reservationId, txId);
-        const acks = await this.broadcastAck('LEASE_COMMIT', { reservationId, txId });
+        const acks = await this.broadcastAck('LEASE_COMMIT', (peerId) => ({
+            reservationId: this.peerReservationIdFor(reservationId, peerId),
+            txId,
+        }));
         if (this.requireQuorumOnCommit && acks < this.minAttestations) {
             throw new errors_js_1.QuorumUnavailableError(this.minAttestations, acks);
         }
@@ -155,13 +172,35 @@ class P2PQuorumLeaseProvider {
     async burnReservation(reservationId, reason) {
         await this.ensureInit();
         await this.local.burnReservation(reservationId, reason);
-        await this.broadcastAck('LEASE_BURN', { reservationId, reason });
+        await this.broadcastAck('LEASE_BURN', (peerId) => ({
+            reservationId: this.peerReservationIdFor(reservationId, peerId),
+            reason,
+        }));
+    }
+    /** Record which peer issued which reservation id for a local reservation. */
+    recordPeerReservationIds(localReservationId, attestations) {
+        const byPeer = new Map();
+        for (const attestation of attestations) {
+            if (attestation.peerReservationId) {
+                byPeer.set(attestation.peerId, attestation.peerReservationId);
+            }
+        }
+        if (byPeer.size > 0)
+            this.peerReservationIds.set(localReservationId, byPeer);
     }
-    async broadcastAck(type, payload) {
+    /**
+     * The id to send a peer for a local reservation. Peers only know the id they
+     * issued; fall back to the local id only when no peer id was recorded (e.g.
+     * attestations gathered outside `reserveKeyUse`).
+     */
+    peerReservationIdFor(localReservationId, peerId) {
+        return this.peerReservationIds.get(localReservationId)?.get(peerId) ?? localReservationId;
+    }
+    async broadcastAck(type, payloadFor) {
         let acks = 0;
         await Promise.all(this.peers.map(async (peer) => {
             try {
-                const resp = await peer.request({ type, payload }, this.requestTimeoutMs);
+                const resp = await peer.request({ type, payload: payloadFor(peer.peerId) }, this.requestTimeoutMs);
                 if (resp.type !== 'ERROR')
                     acks++;
             }
@@ -254,6 +293,10 @@ class P2PQuorumLeaseProvider {
             return false;
         if (cert.expiresAt <= Date.now())
             return false;
+        // An unsigned certificate carries no authenticity evidence.
+        if (!(await (0, certificate_js_1.certificateSignatureVerified)(cert, this.certificateSigner))) {
+            return false;
+        }
         const attestations = cert.attestations ?? [];
         if (attestations.length < this.minAttestations)
             return false;

package/dist/seed.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module @totemsdk/wots-lease/seed
+ *
+ * Watermark seeding for import/restore (RFC-013 §9). The safety property is
+ * "never reissue a used leaf". A local watermark alone is insufficient across
+ * devices/restores, so seeding draws from, in priority order:
+ *
+ *   1. the on-chain watermark cursor (advances the local watermark),
+ *   2. an exported watermark blob,
+ *   3. an operator-provided high-water mark.
+ *
+ * If none is available and the caller has not declared the keyspace fresh,
+ * seeding **fails closed** — starting at 0 would reissue spent leaves.
+ */
+import type { LocalLeaseProvider } from './local.js';
+import type { OnchainWatermarkProvider } from './onchain.js';
+import type { LocalWatermark, WatermarkSeed } from './types.js';
+export interface SeedLeaseWatermarkParams {
+    readonly local: LocalLeaseProvider;
+    readonly treeId: string;
+    /** Layer 5 — the on-chain cursor is authoritative when reachable. */
+    readonly onchain?: OnchainWatermarkProvider;
+    /** Exported watermark blob. */
+    readonly exported?: WatermarkSeed;
+    /** Operator-provided flat high-water mark. */
+    readonly operatorHighWaterMark?: number;
+    /** Declares the keyspace fresh/unspent, so cursor 0 is safe. */
+    readonly fresh?: boolean;
+}
+/**
+ * Seed a local watermark from the best available source, requiring at least one
+ * source unless `fresh` is set. Returns the resulting local watermark.
+ *
+ * @throws {WatermarkSeedRequiredError} when no source is available and the
+ *   keyspace is not declared fresh.
+ * @throws {WatermarkSeedRegressionError} when a supplied seed is behind the
+ *   current cursor.
+ */
+export declare function seedLeaseWatermark(params: SeedLeaseWatermarkParams): Promise<LocalWatermark>;
+/** Export a portable watermark blob for backup/restore. */
+export declare function exportLeaseWatermark(local: LocalLeaseProvider, treeId: string): Promise<WatermarkSeed>;

package/dist/seed.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * @module @totemsdk/wots-lease/seed
+ *
+ * Watermark seeding for import/restore (RFC-013 §9). The safety property is
+ * "never reissue a used leaf". A local watermark alone is insufficient across
+ * devices/restores, so seeding draws from, in priority order:
+ *
+ *   1. the on-chain watermark cursor (advances the local watermark),
+ *   2. an exported watermark blob,
+ *   3. an operator-provided high-water mark.
+ *
+ * If none is available and the caller has not declared the keyspace fresh,
+ * seeding **fails closed** — starting at 0 would reissue spent leaves.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seedLeaseWatermark = seedLeaseWatermark;
+exports.exportLeaseWatermark = exportLeaseWatermark;
+const watermark_js_1 = require("./watermark.js");
+const errors_js_1 = require("./errors.js");
+function flatOf(w) {
+    return (0, watermark_js_1.flatIndex)({ addressIndex: w.addressCursor, l1: w.l1Cursor, l2: w.l2Cursor });
+}
+/**
+ * Seed a local watermark from the best available source, requiring at least one
+ * source unless `fresh` is set. Returns the resulting local watermark.
+ *
+ * @throws {WatermarkSeedRequiredError} when no source is available and the
+ *   keyspace is not declared fresh.
+ * @throws {WatermarkSeedRegressionError} when a supplied seed is behind the
+ *   current cursor.
+ */
+async function seedLeaseWatermark(params) {
+    const { local, treeId } = params;
+    // 1. On-chain cursor — advances the same local watermark (monotonic).
+    if (params.onchain) {
+        try {
+            await params.onchain.syncLeaseJournal();
+        }
+        catch {
+            // Chain unreachable — fall through to exported/operator sources below.
+        }
+    }
+    const current = await local.getLocalWatermark(treeId);
+    let bestFlat = flatOf({ addressCursor: current.addressCursor, l1Cursor: current.l1Cursor, l2Cursor: current.l2Cursor });
+    let best;
+    // 2. Exported blob.
+    if (params.exported) {
+        if (flatOf(params.exported) > bestFlat) {
+            best = params.exported;
+            bestFlat = flatOf(params.exported);
+        }
+    }
+    // 3. Operator high-water mark.
+    if (params.operatorHighWaterMark !== undefined) {
+        const indices = (0, watermark_js_1.fromFlatIndex)(params.operatorHighWaterMark);
+        const candidate = {
+            version: 1,
+            treeId,
+            addressCursor: indices.addressIndex,
+            l1Cursor: indices.l1,
+            l2Cursor: indices.l2,
+            unavailable: [],
+        };
+        if (flatOf(candidate) > bestFlat) {
+            best = candidate;
+            bestFlat = flatOf(candidate);
+        }
+    }
+    if (best) {
+        await local.seedWatermark(best);
+    }
+    if (!params.onchain &&
+        !params.exported &&
+        params.operatorHighWaterMark === undefined &&
+        !params.fresh) {
+        throw new errors_js_1.WatermarkSeedRequiredError(treeId);
+    }
+    return local.getLocalWatermark(treeId);
+}
+/** Export a portable watermark blob for backup/restore. */
+function exportLeaseWatermark(local, treeId) {
+    return local.exportWatermark(treeId);
+}

package/dist/stubs.d.ts

@@ -34,6 +34,8 @@ export declare class PersonalLeaseNodeProvider implements WotsLeaseProvider {
     private readonly baseUrl;
     private readonly nodePubkey;
     private readonly authToken?;
+    private readonly certificateSigner?;
+    private readonly verify?;
     constructor(config: PersonalLeaseNodeConfig);
     private headers;
     private post;

package/dist/stubs.js

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PersonalLeaseNodeProvider = exports.OnchainWatermarkProvider = exports.P2PQuorumLeaseProvider = void 0;
+const certificate_js_1 = require("./certificate.js");
 var quorum_js_1 = require("./quorum.js");
 Object.defineProperty(exports, "P2PQuorumLeaseProvider", { enumerable: true, get: function () { return quorum_js_1.P2PQuorumLeaseProvider; } });
 var onchain_js_1 = require("./onchain.js");
@@ -39,6 +40,8 @@ class PersonalLeaseNodeProvider {
         this.baseUrl = config.nodeUrl.replace(/\/$/, '');
         this.nodePubkey = config.nodePubkey;
         this.authToken = config.authToken;
+        this.certificateSigner = config.certificateSigner;
+        this.verify = config.verify;
     }
     headers() {
         const h = { 'Content-Type': 'application/json' };
@@ -103,7 +106,20 @@ class PersonalLeaseNodeProvider {
             return false;
         if (cert.expiresAt <= Date.now())
             return false;
-        return true;
+        // AUD-016: fail closed. The provider can only verify a certificate when it
+        // holds a verifier; an `issuedBy` match is not authenticity evidence.
+        const signer = this.certificateSigner?.verify
+            ? this.certificateSigner
+            : this.verify
+                ? {
+                    publicKeyDigest: this.nodePubkey,
+                    sign: async () => {
+                        throw new Error('PersonalLeaseNodeProvider holds a verify-only signer and cannot sign');
+                    },
+                    verify: this.verify,
+                }
+                : undefined;
+        return (0, certificate_js_1.certificateSignatureVerified)(cert, signer);
     }
 }
 exports.PersonalLeaseNodeProvider = PersonalLeaseNodeProvider;

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/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

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WotsWatermarkStore = void 0;
 exports.flatIndex = flatIndex;
 exports.fromFlatIndex = fromFlatIndex;
+exports.assertValidSigningIndices = assertValidSigningIndices;
 const core_1 = require("@totemsdk/core");
 const errors_js_1 = require("./errors.js");
 const STORAGE_KEY = 'totem_wots_watermark';
@@ -18,15 +19,27 @@ const MAX_L = 64;
 const CAPACITY_PER_TREE = MAX_L * MAX_L * MAX_L;
 const DEFAULT_TREE = 'default';
 function flatIndex(idx) {
+    assertValidSigningIndices(idx);
     return idx.addressIndex * MAX_L * MAX_L + idx.l1 * MAX_L + idx.l2;
 }
 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 };
 }
+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 +58,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: {} };
@@ -113,6 +157,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]) {
@@ -160,7 +217,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();
@@ -192,6 +255,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 errors_js_1.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();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totemsdk/wots-lease",
-  "version": "0.1.6",
+  "version": "1.0.1",
   "description": "WOTS key-use coordination — canonical v3 watermark, provider-based lease safety layers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,9 +19,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@totemsdk/lookup-protocol": "^0.1.6",
-    "@totemsdk/core": "^1.2.8",
-    "@totemsdk/txpow": "^0.1.7"
+    "@totemsdk/core": "^1.2.11",
+    "@totemsdk/lookup-protocol": "^0.2.0",
+    "@totemsdk/txpow": "^1.0.2",
+    "@totemsdk/storage": "^0.1.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -38,13 +39,13 @@
   },
   "license": "MIT",
   "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": [