@totemsdk/wots-lease 0.1.5 → 1.0.0

package/README.md

@@ -28,9 +28,9 @@ npm install @totemsdk/wots-lease
 | `LocalLeaseProvider` | Single-device, in-process coordination |
 | `AxiaLeaseProvider` | Cloud-coordinated leases via Axia API |
 | `HybridLeaseProvider` | Local-first with Axia sync fallback |
-| `PersonalLeaseNodeProvider` | Coordinates through your personal lookup node *(ready for implementation)* |
-| `P2PQuorumLeaseProvider` | Multi-device quorum consensus *(stub)* |
-| `OnchainWatermarkProvider` | On-chain watermark anchoring *(stub)* |
+| `PersonalLeaseNodeProvider` | Coordinates through your personal lookup node |
+| `P2PQuorumLeaseProvider` | Multi-device quorum consensus — peers attest to the same slot before it is handed out |
+| `OnchainWatermarkProvider` | On-chain watermark anchoring — spends a dedicated watermark coin whose STATE(0) holds the flat cursor |
 
 ### Device range splitting
 
@@ -90,6 +90,45 @@ const entries = await journal.getEntries({ addressIndex: 0 });
 entries.forEach(e => console.log(e.flatIndex, e.allocatedAt, e.committedAt));
 ```
 
+### P2P quorum (multi-device)
+
+```typescript
+import { P2PQuorumLeaseProvider, LocalLeaseProvider } from '@totemsdk/wots-lease';
+
+const provider = new P2PQuorumLeaseProvider({
+  local: new LocalLeaseProvider(storage),
+  peers: [peerA, peerB, peerC],   // QuorumPeer[] — any LEASE_* wire-protocol speaker
+  minAttestations: 2,             // require 2 peers to attest before handing out a slot
+});
+
+const reservation = await provider.reserveKeyUse({ treeId: 'wallet' });
+// reservation.certificate.attestations — peer attestations for the same indices
+```
+
+Peers speak the same `LEASE_RESERVE` / `LEASE_COMMIT` / `LEASE_BURN` /
+`LEASE_WATERMARK` messages as the lookup protocol, so a personal lookup node
+(`@totemsdk/lookup-node` with `lease.enabled`) or another device running this
+provider can participate. If quorum cannot be reached the local reservation is
+**burned** — a slot that might have been attested is never handed out again.
+
+### On-chain watermark anchoring
+
+```typescript
+import { OnchainWatermarkProvider, LocalLeaseProvider } from '@totemsdk/wots-lease';
+
+const provider = new OnchainWatermarkProvider({
+  local: new LocalLeaseProvider(storage),
+  chain: chainProvider,            // any ChainStateProvider (hosted / RPC / lookup node)
+  watermarkCoinId: '0x…',         // dedicated watermark coin
+  watermarkAddress: '0x…',        // its current spending address
+  signer: { publicKeyDigest, sign }, // SIGNEDBY key for the watermark coin
+});
+
+await provider.publishWatermark('wallet');
+// Spends the watermark coin back to itself with STATE(0) = flat cursor,
+// so any third party can verify slot consumption on-chain.
+```
+
 ## See also
 
 - [`@totemsdk/core`](https://www.npmjs.com/package/@totemsdk/core) — WOTS primitives this package protects

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import type { SigningIndices } from './types.js';
 export declare class WatermarkMonotonicityError extends Error {
     constructor(message: string);
 }
@@ -9,6 +10,11 @@ export declare class LeaseNotFoundError extends Error {
     readonly reservationId: string;
     constructor(reservationId: string);
 }
+export declare class IndicesUnavailableError extends Error {
+    readonly treeId: string;
+    readonly indices: SigningIndices;
+    constructor(treeId: string, indices: SigningIndices);
+}
 export declare class PersonalLeaseNodeNotConfiguredError extends Error {
     constructor();
 }
@@ -18,6 +24,19 @@ export declare class P2PQuorumNotImplementedError extends Error {
 export declare class OnchainWatermarkNotImplementedError extends Error {
     constructor();
 }
+export declare class QuorumUnavailableError extends Error {
+    readonly required: number;
+    readonly available: number;
+    constructor(required: number, available: number);
+}
+export declare class QuorumConflictError extends Error {
+    readonly treeId: string;
+    readonly indices: SigningIndices;
+    constructor(treeId: string, indices: SigningIndices);
+}
+export declare class OnchainWatermarkError extends Error {
+    constructor(message: string);
+}
 export declare class DeviceRangeViolationError extends Error {
     readonly addressIndex: number;
     readonly allowedStart: number;

package/dist/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeviceRangeViolationError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.LeaseNotFoundError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = void 0;
+exports.DeviceRangeViolationError = exports.OnchainWatermarkError = exports.QuorumConflictError = exports.QuorumUnavailableError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.IndicesUnavailableError = exports.LeaseNotFoundError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = void 0;
 class WatermarkMonotonicityError extends Error {
     constructor(message) {
         super(message);
@@ -24,6 +24,15 @@ class LeaseNotFoundError extends Error {
     }
 }
 exports.LeaseNotFoundError = LeaseNotFoundError;
+class IndicesUnavailableError extends Error {
+    constructor(treeId, indices) {
+        super(`Indices (${indices.addressIndex}, ${indices.l1}, ${indices.l2}) are already unavailable for tree: ${treeId}`);
+        this.treeId = treeId;
+        this.indices = indices;
+        this.name = 'IndicesUnavailableError';
+    }
+}
+exports.IndicesUnavailableError = IndicesUnavailableError;
 class PersonalLeaseNodeNotConfiguredError extends Error {
     constructor() {
         super('PersonalLeaseNodeProvider requires a running lookup node. ' +
@@ -46,6 +55,33 @@ class OnchainWatermarkNotImplementedError extends Error {
     }
 }
 exports.OnchainWatermarkNotImplementedError = OnchainWatermarkNotImplementedError;
+class QuorumUnavailableError extends Error {
+    constructor(required, available) {
+        super(`Quorum not reached: ${available}/${required} peers attested. ` +
+            'The reservation was burned locally — retry when more peers are reachable.');
+        this.required = required;
+        this.available = available;
+        this.name = 'QuorumUnavailableError';
+    }
+}
+exports.QuorumUnavailableError = QuorumUnavailableError;
+class QuorumConflictError extends Error {
+    constructor(treeId, indices) {
+        super(`Quorum conflict for tree ${treeId} at (${indices.addressIndex}, ${indices.l1}, ${indices.l2}): ` +
+            'a peer already holds a reservation for these indices.');
+        this.treeId = treeId;
+        this.indices = indices;
+        this.name = 'QuorumConflictError';
+    }
+}
+exports.QuorumConflictError = QuorumConflictError;
+class OnchainWatermarkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OnchainWatermarkError';
+    }
+}
+exports.OnchainWatermarkError = OnchainWatermarkError;
 class DeviceRangeViolationError extends Error {
     constructor(addressIndex, allowedStart, allowedEnd) {
         super(`Address index ${addressIndex} is outside device range [${allowedStart}, ${allowedEnd}]`);

package/dist/hybrid.js

@@ -24,6 +24,33 @@ class HybridLeaseProvider {
     async reserveKeyUse(params) {
         const reservation = await this.local.reserveKeyUse(params);
         if (this.isHighValue(params)) {
+            // Layer 4 — quorum attestation over the SAME local slot.
+            if (this.quorum) {
+                try {
+                    const attestations = await this.quorum.attestKeyUse(params, reservation.indices);
+                    return {
+                        ...reservation,
+                        certificate: {
+                            reservationId: reservation.reservationId,
+                            treeId: params.treeId,
+                            branchId: params.branchId,
+                            deviceId: params.deviceId,
+                            indices: reservation.indices,
+                            purpose: params.purpose,
+                            payloadHash: params.payloadHash,
+                            issuedBy: 'p2p-quorum',
+                            issuedAt: Date.now(),
+                            expiresAt: reservation.expiresAt,
+                            signature: '',
+                            attestations,
+                        },
+                    };
+                }
+                catch {
+                    // Quorum unavailable — fall through to node / local only.
+                }
+            }
+            // Layer 3 — personal lookup node certificate.
             if (this.node) {
                 try {
                     const nodeReservation = await this.node.reserveKeyUse(params);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { UnavailableReason, SigningIndices, LeaseStatus, TreeWatermark, WotsWatermarkState, LeaseCertificate, LeaseReservation, ReserveParams, LocalWatermark, ConflictRecord, SyncResult, WotsLeaseProvider, JournalEntry, DeviceKeyRange, PersonalLeaseNodeConfig, } from './types.js';
+export type { UnavailableReason, SigningIndices, LeaseStatus, TreeWatermark, WotsWatermarkState, LeaseCertificate, LeaseReservation, ReserveParams, LocalWatermark, ConflictRecord, SyncResult, WotsLeaseProvider, JournalEntry, DeviceKeyRange, PersonalLeaseNodeConfig, QuorumAttestation, QuorumPeer, P2PQuorumLeaseProviderConfig, OnchainWatermarkProviderConfig, } from './types.js';
 export { WotsWatermarkStore, flatIndex, fromFlatIndex, } from './watermark.js';
 export { LeaseJournal } from './journal.js';
 export { LocalLeaseProvider } from './local.js';
@@ -7,5 +7,7 @@ export type { AxiaLeaseProviderConfig } from './axia.js';
 export { HybridLeaseProvider } from './hybrid.js';
 export type { HybridLeaseProviderConfig } from './hybrid.js';
 export { PersonalLeaseNodeProvider, P2PQuorumLeaseProvider, OnchainWatermarkProvider, } from './stubs.js';
+export { P2PQuorumLeaseProvider as QuorumLeaseProvider } from './quorum.js';
+export { OnchainWatermarkProvider as ChainWatermarkProvider } from './onchain.js';
 export { allocateDeviceRange, deviceSlotForAddressIndex } from './device.js';
-export { WatermarkMonotonicityError, WatermarkExhaustedError, LeaseNotFoundError, PersonalLeaseNodeNotConfiguredError, P2PQuorumNotImplementedError, OnchainWatermarkNotImplementedError, DeviceRangeViolationError, } from './errors.js';
+export { WatermarkMonotonicityError, WatermarkExhaustedError, LeaseNotFoundError, IndicesUnavailableError, PersonalLeaseNodeNotConfiguredError, P2PQuorumNotImplementedError, OnchainWatermarkNotImplementedError, QuorumUnavailableError, QuorumConflictError, OnchainWatermarkError, DeviceRangeViolationError, } from './errors.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeviceRangeViolationError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.LeaseNotFoundError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = exports.deviceSlotForAddressIndex = exports.allocateDeviceRange = exports.OnchainWatermarkProvider = exports.P2PQuorumLeaseProvider = exports.PersonalLeaseNodeProvider = exports.HybridLeaseProvider = exports.AxiaLeaseProvider = exports.LocalLeaseProvider = exports.LeaseJournal = exports.fromFlatIndex = exports.flatIndex = exports.WotsWatermarkStore = void 0;
+exports.DeviceRangeViolationError = exports.OnchainWatermarkError = exports.QuorumConflictError = exports.QuorumUnavailableError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.IndicesUnavailableError = exports.LeaseNotFoundError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = exports.deviceSlotForAddressIndex = exports.allocateDeviceRange = exports.ChainWatermarkProvider = exports.QuorumLeaseProvider = exports.OnchainWatermarkProvider = exports.P2PQuorumLeaseProvider = exports.PersonalLeaseNodeProvider = exports.HybridLeaseProvider = exports.AxiaLeaseProvider = exports.LocalLeaseProvider = exports.LeaseJournal = exports.fromFlatIndex = exports.flatIndex = exports.WotsWatermarkStore = void 0;
 var watermark_js_1 = require("./watermark.js");
 Object.defineProperty(exports, "WotsWatermarkStore", { enumerable: true, get: function () { return watermark_js_1.WotsWatermarkStore; } });
 Object.defineProperty(exports, "flatIndex", { enumerable: true, get: function () { return watermark_js_1.flatIndex; } });
@@ -17,6 +17,10 @@ var stubs_js_1 = require("./stubs.js");
 Object.defineProperty(exports, "PersonalLeaseNodeProvider", { enumerable: true, get: function () { return stubs_js_1.PersonalLeaseNodeProvider; } });
 Object.defineProperty(exports, "P2PQuorumLeaseProvider", { enumerable: true, get: function () { return stubs_js_1.P2PQuorumLeaseProvider; } });
 Object.defineProperty(exports, "OnchainWatermarkProvider", { enumerable: true, get: function () { return stubs_js_1.OnchainWatermarkProvider; } });
+var quorum_js_1 = require("./quorum.js");
+Object.defineProperty(exports, "QuorumLeaseProvider", { enumerable: true, get: function () { return quorum_js_1.P2PQuorumLeaseProvider; } });
+var onchain_js_1 = require("./onchain.js");
+Object.defineProperty(exports, "ChainWatermarkProvider", { enumerable: true, get: function () { return onchain_js_1.OnchainWatermarkProvider; } });
 var device_js_1 = require("./device.js");
 Object.defineProperty(exports, "allocateDeviceRange", { enumerable: true, get: function () { return device_js_1.allocateDeviceRange; } });
 Object.defineProperty(exports, "deviceSlotForAddressIndex", { enumerable: true, get: function () { return device_js_1.deviceSlotForAddressIndex; } });
@@ -24,7 +28,11 @@ var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "WatermarkMonotonicityError", { enumerable: true, get: function () { return errors_js_1.WatermarkMonotonicityError; } });
 Object.defineProperty(exports, "WatermarkExhaustedError", { enumerable: true, get: function () { return errors_js_1.WatermarkExhaustedError; } });
 Object.defineProperty(exports, "LeaseNotFoundError", { enumerable: true, get: function () { return errors_js_1.LeaseNotFoundError; } });
+Object.defineProperty(exports, "IndicesUnavailableError", { enumerable: true, get: function () { return errors_js_1.IndicesUnavailableError; } });
 Object.defineProperty(exports, "PersonalLeaseNodeNotConfiguredError", { enumerable: true, get: function () { return errors_js_1.PersonalLeaseNodeNotConfiguredError; } });
 Object.defineProperty(exports, "P2PQuorumNotImplementedError", { enumerable: true, get: function () { return errors_js_1.P2PQuorumNotImplementedError; } });
 Object.defineProperty(exports, "OnchainWatermarkNotImplementedError", { enumerable: true, get: function () { return errors_js_1.OnchainWatermarkNotImplementedError; } });
+Object.defineProperty(exports, "QuorumUnavailableError", { enumerable: true, get: function () { return errors_js_1.QuorumUnavailableError; } });
+Object.defineProperty(exports, "QuorumConflictError", { enumerable: true, get: function () { return errors_js_1.QuorumConflictError; } });
+Object.defineProperty(exports, "OnchainWatermarkError", { enumerable: true, get: function () { return errors_js_1.OnchainWatermarkError; } });
 Object.defineProperty(exports, "DeviceRangeViolationError", { enumerable: true, get: function () { return errors_js_1.DeviceRangeViolationError; } });

package/dist/local.d.ts

@@ -5,7 +5,8 @@
  * All WOTS safety guaranteed by the local WotsWatermarkStore + LeaseJournal.
  */
 import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
-import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult } from './types.js';
+import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, SigningIndices } from './types.js';
+import { LeaseJournal } from './journal.js';
 export declare class LocalLeaseProvider implements WotsLeaseProvider {
     private readonly logger;
     private readonly watermark;
@@ -21,9 +22,30 @@ export declare class LocalLeaseProvider implements WotsLeaseProvider {
     private burnUnresolvedReservations;
     private recoverExpiredReservations;
     reserveKeyUse(params: ReserveParams): Promise<LeaseReservation>;
+    /**
+     * Reserve a specific set of indices (used by quorum coordination so every
+     * peer attests to the same slot). Throws IndicesUnavailableError when the
+     * slot is already taken.
+     */
+    reserveSpecificKeyUse(params: ReserveParams, indices: SigningIndices): Promise<LeaseReservation>;
     commitKeyUse(reservationId: string, txId: string): Promise<void>;
     burnReservation(reservationId: string, reason: string): Promise<void>;
     getLocalWatermark(treeId: string): Promise<LocalWatermark>;
+    /** List all tree IDs known to the local watermark store. */
+    listTrees(): string[];
+    /** Expose the journal for quorum/on-chain providers to merge remote entries. */
+    getJournal(): LeaseJournal;
+    /**
+     * Advance the local watermark to a remote cursor (monotonic merge).
+     * Used by quorum sync and the lookup-node LeaseCoordinator when a peer
+     * publishes a watermark ahead of ours. Returns false when the remote
+     * cursor is behind (no-op).
+     */
+    advanceToRemoteWatermark(treeId: string, remote: {
+        addressCursor: number;
+        l1Cursor: number;
+        l2Cursor: number;
+    }): Promise<boolean>;
     publishWatermark(_treeId: string): Promise<void>;
     syncLeaseJournal(): Promise<SyncResult>;
     verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean>;

package/dist/local.js

@@ -81,12 +81,24 @@ class LocalLeaseProvider {
         }
     }
     async reserveKeyUse(params) {
+        if (!this._initialized)
+            await this.initialize();
+        const indices = this.watermark.getNextIndices(params.treeId);
+        return this.reserveSpecificKeyUse(params, indices);
+    }
+    /**
+     * Reserve a specific set of indices (used by quorum coordination so every
+     * peer attests to the same slot). Throws IndicesUnavailableError when the
+     * slot is already taken.
+     */
+    async reserveSpecificKeyUse(params, indices) {
         if (!this._initialized)
             await this.initialize();
         const treeId = params.treeId;
         const ttlMs = params.ttlMs ?? 120000;
-        // Atomically get the next available index AND mark it reserved in the watermark
-        const indices = this.watermark.getNextIndices(treeId);
+        if (this.watermark.isUnavailable(treeId, indices)) {
+            throw new errors_js_1.IndicesUnavailableError(treeId, indices);
+        }
         // Validate device range BEFORE marking unavailable — prevents permanent index loss
         if (params.deviceId) {
             const range = this.getDeviceRange(params.deviceId);
@@ -172,6 +184,36 @@ class LocalLeaseProvider {
             await this.initialize();
         return this.watermark.getLocalWatermark(treeId);
     }
+    /** List all tree IDs known to the local watermark store. */
+    listTrees() {
+        return Object.keys(this.watermark.getRawState().trees);
+    }
+    /** Expose the journal for quorum/on-chain providers to merge remote entries. */
+    getJournal() {
+        return this.journal;
+    }
+    /**
+     * Advance the local watermark to a remote cursor (monotonic merge).
+     * Used by quorum sync and the lookup-node LeaseCoordinator when a peer
+     * publishes a watermark ahead of ours. Returns false when the remote
+     * cursor is behind (no-op).
+     */
+    async advanceToRemoteWatermark(treeId, remote) {
+        if (!this._initialized)
+            await this.initialize();
+        const local = this.watermark.getLocalWatermark(treeId);
+        const localFlat = (0, watermark_js_1.flatIndex)({ addressIndex: local.addressCursor, l1: local.l1Cursor, l2: local.l2Cursor });
+        const remoteFlat = (0, watermark_js_1.flatIndex)({ addressIndex: remote.addressCursor, l1: remote.l1Cursor, l2: remote.l2Cursor });
+        if (remoteFlat <= localFlat)
+            return false;
+        await this.watermark.save(treeId, {
+            addressCursor: remote.addressCursor,
+            l1Cursor: remote.l1Cursor,
+            l2Cursor: remote.l2Cursor,
+            lastSyncTimestamp: Date.now(),
+        });
+        return true;
+    }
     async publishWatermark(_treeId) {
         // Layer 1: no-op
     }

package/dist/onchain.d.ts

@@ -0,0 +1,52 @@
+/**
+ * OnchainWatermarkProvider — Layer 5: on-chain watermark anchoring.
+ *
+ * Safety model
+ * ────────────
+ * The local provider remains the authoritative watermark. This provider adds
+ * a verifiable public record: a dedicated watermark coin whose STATE(0) holds
+ * the flat watermark cursor. Every publish spends the coin back to itself
+ * with an advanced cursor, so any third party can read the on-chain state and
+ * prove that a given signing slot was consumed — without trusting this device.
+ *
+ * The watermark coin script is `RETURN SIGNEDBY(0x<digest>)` — the same
+ * single-sig pattern used by statechain reclaim addresses. The signer is the
+ * WOTS key owner; the digest is the 32-byte public key digest.
+ *
+ * Failure semantics
+ * ─────────────────
+ * - publishWatermark fails loudly (OnchainWatermarkError) when the chain
+ *   rejects the TX — the local watermark is never rolled back.
+ * - syncLeaseJournal merges the on-chain cursor into the local watermark
+ *   monotonically (remote ahead → advance; remote behind → conflict record).
+ */
+import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, OnchainWatermarkProviderConfig } from './types.js';
+export declare class OnchainWatermarkProvider implements WotsLeaseProvider {
+    private readonly chain;
+    private readonly watermarkCoinId;
+    private readonly watermarkAddress;
+    private readonly tokenId;
+    private readonly amount;
+    private readonly local;
+    private readonly signer;
+    private readonly statePort;
+    private readonly minBlocksBetweenPublishes;
+    private _initialized;
+    private _lastPublishBlock;
+    constructor(config: OnchainWatermarkProviderConfig);
+    initialize(): Promise<void>;
+    private ensureInit;
+    reserveKeyUse(params: ReserveParams): Promise<LeaseReservation>;
+    commitKeyUse(reservationId: string, txId: string): Promise<void>;
+    burnReservation(reservationId: string, reason: string): Promise<void>;
+    getLocalWatermark(treeId: string): Promise<LocalWatermark>;
+    /**
+     * Publish the local watermark cursor on-chain by spending the watermark
+     * coin back to itself with STATE(statePort) = flat cursor.
+     *
+     * Rate-limited by minBlocksBetweenPublishes using the chain tip.
+     */
+    publishWatermark(treeId: string): Promise<void>;
+    syncLeaseJournal(): Promise<SyncResult>;
+    verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean>;
+}

package/dist/onchain.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * OnchainWatermarkProvider — Layer 5: on-chain watermark anchoring.
+ *
+ * Safety model
+ * ────────────
+ * The local provider remains the authoritative watermark. This provider adds
+ * a verifiable public record: a dedicated watermark coin whose STATE(0) holds
+ * the flat watermark cursor. Every publish spends the coin back to itself
+ * with an advanced cursor, so any third party can read the on-chain state and
+ * prove that a given signing slot was consumed — without trusting this device.
+ *
+ * The watermark coin script is `RETURN SIGNEDBY(0x<digest>)` — the same
+ * single-sig pattern used by statechain reclaim addresses. The signer is the
+ * WOTS key owner; the digest is the 32-byte public key digest.
+ *
+ * Failure semantics
+ * ─────────────────
+ * - publishWatermark fails loudly (OnchainWatermarkError) when the chain
+ *   rejects the TX — the local watermark is never rolled back.
+ * - syncLeaseJournal merges the on-chain cursor into the local watermark
+ *   monotonically (remote ahead → advance; remote behind → conflict record).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnchainWatermarkProvider = void 0;
+const watermark_js_1 = require("./watermark.js");
+const errors_js_1 = require("./errors.js");
+const core_1 = require("@totemsdk/core");
+const txpow_1 = require("@totemsdk/txpow");
+const MAX_L = 64;
+function multiConcat(parts) {
+    if (parts.length === 0)
+        return new Uint8Array(0);
+    let result = parts[0];
+    for (let i = 1; i < parts.length; i++) {
+        result = concatBytes(result, parts[i]);
+    }
+    return result;
+}
+function concatBytes(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+function addressToHex(address) {
+    const upper = address.startsWith('0x') || address.startsWith('0X') ? address.slice(2) : address;
+    return upper.toUpperCase().startsWith('MX')
+        ? (0, core_1.bytesToHex)((0, core_1.parseMxAddress)(address))
+        : address.replace(/^0x/i, '');
+}
+function flatToHex(flat) {
+    let hex = BigInt(flat).toString(16);
+    if (hex.length % 2 !== 0)
+        hex = '0' + hex;
+    return hex || '00';
+}
+function hexToFlat(hex) {
+    const clean = (hex.startsWith('0x') ? hex.slice(2) : hex).replace(/^0+/, '') || '0';
+    return Number(BigInt('0x' + clean));
+}
+function readStateCursor(state, statePort) {
+    for (const raw of state) {
+        const entry = raw;
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        if (entry.port !== statePort)
+            continue;
+        if (typeof entry.data === 'string')
+            return hexToFlat(entry.data);
+        if (entry.value !== undefined)
+            return Number(entry.value);
+    }
+    return null;
+}
+function stateVarJson(port, hexValue) {
+    return { port, svtype: 'hex', data: hexValue };
+}
+function buildWitnessBytes(sigs) {
+    const parts = [(0, core_1.writeMiniNumber)(BigInt(sigs.length), 0)];
+    for (const sig of sigs)
+        parts.push(sig);
+    parts.push((0, core_1.writeMiniNumber)(0n, 0));
+    parts.push((0, core_1.writeMiniNumber)(0n, 0));
+    return multiConcat(parts);
+}
+class OnchainWatermarkProvider {
+    constructor(config) {
+        this._initialized = false;
+        this._lastPublishBlock = -1;
+        this.chain = config.chain;
+        this.watermarkCoinId = config.watermarkCoinId;
+        this.watermarkAddress = config.watermarkAddress;
+        this.tokenId = config.tokenId ?? '0x00';
+        this.amount = config.amount ?? '1';
+        this.local = config.local;
+        this.signer = config.signer;
+        this.statePort = config.statePort ?? 0;
+        this.minBlocksBetweenPublishes = config.minBlocksBetweenPublishes ?? 1;
+    }
+    async initialize() {
+        if (this._initialized)
+            return;
+        await this.local.initialize();
+        this._initialized = true;
+    }
+    async ensureInit() {
+        if (!this._initialized)
+            await this.initialize();
+    }
+    // -------------------------------------------------------------------------
+    // Reserve / commit / burn — local authoritative
+    // -------------------------------------------------------------------------
+    async reserveKeyUse(params) {
+        await this.ensureInit();
+        const reservation = await this.local.reserveKeyUse(params);
+        const certificate = {
+            reservationId: reservation.reservationId,
+            treeId: params.treeId,
+            branchId: params.branchId,
+            deviceId: params.deviceId,
+            indices: reservation.indices,
+            purpose: params.purpose,
+            payloadHash: params.payloadHash,
+            issuedBy: 'onchain-watermark',
+            issuedAt: Date.now(),
+            expiresAt: reservation.expiresAt,
+            signature: '',
+        };
+        return { ...reservation, certificate };
+    }
+    async commitKeyUse(reservationId, txId) {
+        await this.ensureInit();
+        await this.local.commitKeyUse(reservationId, txId);
+    }
+    async burnReservation(reservationId, reason) {
+        await this.ensureInit();
+        await this.local.burnReservation(reservationId, reason);
+    }
+    // -------------------------------------------------------------------------
+    // Watermark — local read, on-chain publish
+    // -------------------------------------------------------------------------
+    async getLocalWatermark(treeId) {
+        await this.ensureInit();
+        return this.local.getLocalWatermark(treeId);
+    }
+    /**
+     * Publish the local watermark cursor on-chain by spending the watermark
+     * coin back to itself with STATE(statePort) = flat cursor.
+     *
+     * Rate-limited by minBlocksBetweenPublishes using the chain tip.
+     */
+    async publishWatermark(treeId) {
+        await this.ensureInit();
+        const wm = await this.local.getLocalWatermark(treeId);
+        const newFlat = (0, watermark_js_1.flatIndex)({
+            addressIndex: wm.addressCursor,
+            l1: wm.l1Cursor,
+            l2: wm.l2Cursor,
+        });
+        // Rate limit: skip when the last publish was too recent.
+        try {
+            const tip = await this.chain.getTip?.();
+            if (tip && this._lastPublishBlock >= 0 && tip.block - this._lastPublishBlock < this.minBlocksBetweenPublishes) {
+                return;
+            }
+            if (tip)
+                this._lastPublishBlock = tip.block;
+        }
+        catch {
+            // Tip unavailable — proceed without rate limiting.
+        }
+        // Read the current on-chain cursor so the input state matches the coin.
+        const coin = await this.chain.getCoin(this.watermarkCoinId);
+        if (!coin) {
+            throw new errors_js_1.OnchainWatermarkError(`Watermark coin not found: ${this.watermarkCoinId}`);
+        }
+        const currentState = coin.state ?? [];
+        const currentFlat = readStateCursor(currentState, this.statePort);
+        if (currentFlat !== null && currentFlat >= newFlat) {
+            // On-chain cursor already at or ahead of local — nothing to publish.
+            return;
+        }
+        const inputCoin = {
+            coinid: this.watermarkCoinId,
+            address: addressToHex(this.watermarkAddress),
+            amount: this.amount,
+            tokenid: this.tokenId,
+            storestate: true,
+            state: currentState,
+        };
+        const outputCoin = {
+            address: addressToHex(this.watermarkAddress),
+            amount: this.amount,
+            tokenid: this.tokenId,
+            storestate: true,
+            state: [stateVarJson(this.statePort, flatToHex(newFlat))],
+        };
+        const tx = {
+            linkhash: '0x00',
+            inputs: [inputCoin],
+            outputs: [outputCoin],
+            state: [],
+        };
+        const txBytes = (0, core_1.serializeTransaction)(JSON.stringify(tx));
+        (0, core_1.precomputeTransactionCoinID)(txBytes, 0);
+        const digest = (0, core_1.computeTransactionDigest)(txBytes);
+        const sig = await this.signer.sign(digest);
+        const witnessBytes = buildWitnessBytes([sig]);
+        const prng = (0, core_1.sha3_256)(new TextEncoder().encode(`watermark:${treeId}:${this.watermarkCoinId}:${newFlat}`));
+        const txHex = Buffer.from((0, txpow_1.serializeTxPoW)(txBytes, witnessBytes, { prng })).toString('hex');
+        const result = await this.chain.broadcastTxPoW(txHex);
+        if (!result.success) {
+            throw new errors_js_1.OnchainWatermarkError(`Watermark publish rejected: ${result.message ?? 'unknown error'}`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Sync — merge on-chain cursor into local watermark
+    // -------------------------------------------------------------------------
+    async syncLeaseJournal() {
+        await this.ensureInit();
+        const conflicts = [];
+        let advancedTo;
+        for (const treeId of this.local.listTrees()) {
+            const localWm = await this.local.getLocalWatermark(treeId);
+            const localFlat = (0, watermark_js_1.flatIndex)({
+                addressIndex: localWm.addressCursor,
+                l1: localWm.l1Cursor,
+                l2: localWm.l2Cursor,
+            });
+            let onchainFlat = null;
+            try {
+                const coin = await this.chain.getCoin(this.watermarkCoinId);
+                if (coin)
+                    onchainFlat = readStateCursor(coin.state ?? [], this.statePort);
+            }
+            catch {
+                // Chain unreachable — skip.
+            }
+            if (onchainFlat === null)
+                continue;
+            if (onchainFlat > localFlat) {
+                const addressIndex = Math.floor(onchainFlat / (MAX_L * MAX_L));
+                const rem = onchainFlat % (MAX_L * MAX_L);
+                const l1 = Math.floor(rem / MAX_L);
+                const l2 = rem % MAX_L;
+                const advanced = await this.local.advanceToRemoteWatermark(treeId, {
+                    addressCursor: addressIndex,
+                    l1Cursor: l1,
+                    l2Cursor: l2,
+                });
+                if (advanced) {
+                    advancedTo = { addressIndex, l1, l2 };
+                }
+            }
+            else if (onchainFlat < localFlat) {
+                conflicts.push({
+                    treeId,
+                    localIndex: localFlat,
+                    remoteIndex: onchainFlat,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        return { synced: conflicts.length === 0, conflicts, advancedTo };
+    }
+    async verifyLeaseCertificate(cert) {
+        if (!cert)
+            return false;
+        if (cert.expiresAt <= Date.now())
+            return false;
+        return cert.issuedBy === 'onchain-watermark';
+    }
+}
+exports.OnchainWatermarkProvider = OnchainWatermarkProvider;