@totemsdk/wots-lease 1.0.1 → 1.0.2

package/dist/cjs/onchain.js

@@ -0,0 +1,314 @@
+"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 certificate_js_1 = require("./certificate.js");
+const MAX_L = 64;
+const WATERMARK_COIN_STORAGE_KEY = 'wots-lease:onchain:watermark-coin';
+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.initialWatermarkCoinId = config.watermarkCoinId;
+        this.currentCoinId = 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;
+        this.storage = config.storage;
+    }
+    async initialize() {
+        if (this._initialized)
+            return;
+        // Recover the advanced watermark coin identity across restarts.
+        if (this.storage) {
+            try {
+                const saved = await this.storage.get(WATERMARK_COIN_STORAGE_KEY);
+                if (saved?.coinId)
+                    this.currentCoinId = saved.coinId;
+                if (typeof saved?.lastPublishBlock === 'number') {
+                    this._lastPublishBlock = saved.lastPublishBlock;
+                }
+            }
+            catch {
+                // Storage unavailable — fall back to the configured coin.
+            }
+        }
+        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: '',
+        };
+        certificate.signature = await (0, certificate_js_1.signCertificate)(this.signer, certificate);
+        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
+        // anchored by the CURRENT watermark coin (which advances on every spend).
+        const coin = await this.chain.getCoin(this.currentCoinId);
+        if (!coin) {
+            throw new errors_js_1.OnchainWatermarkError(`Watermark coin not found: ${this.currentCoinId}`);
+        }
+        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.currentCoinId,
+            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 rolledCoinId = (0, core_1.rollCoinId)((0, core_1.hexToBytes)(this.currentCoinId), 0);
+        const tx = {
+            linkhash: '0x00',
+            inputs: [inputCoin],
+            outputs: [{ ...outputCoin, coinid: '0x' + (0, core_1.bytesToHex)(rolledCoinId) }],
+            state: [],
+        };
+        const txBytes = (0, core_1.serializeTransaction)(JSON.stringify(tx));
+        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.currentCoinId}:${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'}`);
+        }
+        // Rollover: the spent watermark coin is destroyed and replaced by a fresh
+        // coin with a new coin ID (output 0 of this spend). Track and persist the
+        // ADVANCED identity so the next publish spends the live coin, not the
+        // consumed one.
+        const newCoinId = '0x' + (0, core_1.bytesToHex)(rolledCoinId);
+        this.currentCoinId = newCoinId;
+        if (this.storage) {
+            try {
+                await this.storage.set(WATERMARK_COIN_STORAGE_KEY, {
+                    coinId: newCoinId,
+                    lastPublishBlock: this._lastPublishBlock,
+                });
+            }
+            catch {
+                // Storage unavailable — in-memory rollover still applies this session.
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 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.currentCoinId);
+                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;
+        if (!(await (0, certificate_js_1.certificateSignatureVerified)(cert, this.signer)))
+            return false;
+        return cert.issuedBy === 'onchain-watermark';
+    }
+}
+exports.OnchainWatermarkProvider = OnchainWatermarkProvider;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/quorum.d.ts

@@ -0,0 +1,75 @@
+/**
+ * P2PQuorumLeaseProvider — Layer 4: multi-device quorum lease coordination.
+ *
+ * Safety model
+ * ────────────
+ * The local provider remains the authoritative watermark (it can only move
+ * forward). The quorum adds a second, independent check: before a reservation
+ * is handed to the caller, at least `minAttestations` peers must confirm that
+ * the same (treeId, indices) slot is free in *their* view of the world. This
+ * catches the failure mode where two devices share a seed and both believe
+ * they own the next slot — the peers see the double-reservation and refuse
+ * to attest.
+ *
+ * Wire protocol
+ * ─────────────
+ * Peers speak the same LEASE_RESERVE / LEASE_COMMIT / LEASE_BURN /
+ * LEASE_WATERMARK message shapes as the lookup protocol, so any peer that
+ * implements that protocol can participate: a personal lookup node, another
+ * device running this provider, or an in-memory test peer.
+ *
+ * Failure semantics
+ * ─────────────────
+ * - If quorum cannot be reached, the local reservation is burned and
+ *   QuorumUnavailableError is thrown. The slot is NOT reusable (burned),
+ *   which is the safe direction: a slot that might have been attested by
+ *   some peers must never be handed out again.
+ * - If a peer reports the slot as taken, the local reservation is burned
+ *   and QuorumConflictError is thrown.
+ */
+import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, QuorumAttestation, P2PQuorumLeaseProviderConfig } from './types.js';
+export declare class P2PQuorumLeaseProvider implements WotsLeaseProvider {
+    private readonly peers;
+    private readonly minAttestations;
+    private readonly local;
+    private readonly requestTimeoutMs;
+    private readonly requireQuorumOnCommit;
+    private readonly certificateSigner?;
+    /**
+     * 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).
+     */
+    private readonly peerReservationIds;
+    private _initialized;
+    constructor(config: P2PQuorumLeaseProviderConfig);
+    initialize(): Promise<void>;
+    private ensureInit;
+    reserveKeyUse(params: ReserveParams): Promise<LeaseReservation>;
+    /**
+     * Collect quorum attestations for a reservation that was already made
+     * locally (used by HybridLeaseProvider so the local slot and the attested
+     * slot are the same). Throws QuorumUnavailableError / QuorumConflictError
+     * on failure — the caller owns the local reservation and must burn it.
+     */
+    attestKeyUse(params: ReserveParams, indices: {
+        addressIndex: number;
+        l1: number;
+        l2: number;
+    }): Promise<QuorumAttestation[]>;
+    commitKeyUse(reservationId: string, txId: string): Promise<void>;
+    burnReservation(reservationId: string, reason: string): Promise<void>;
+    /** Record which peer issued which reservation id for a local reservation. */
+    private recordPeerReservationIds;
+    /**
+     * 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`).
+     */
+    private peerReservationIdFor;
+    private broadcastAck;
+    getLocalWatermark(treeId: string): Promise<LocalWatermark>;
+    publishWatermark(treeId: string): Promise<void>;
+    syncLeaseJournal(): Promise<SyncResult>;
+    verifyLeaseCertificate(cert?: LeaseCertificate): Promise<boolean>;
+}