@totemsdk/core 1.2.6 → 1.2.8

package/dist/cjs/mmr.js

@@ -0,0 +1,352 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deserializeMMRProof = exports.MMRTree = exports.serializeRealMMRProof = void 0;
+exports.serializeMMRProof = serializeMMRProof;
+exports.mmrLeafExact = mmrLeafExact;
+exports.mmrRootFromSingleLeaf = mmrRootFromSingleLeaf;
+exports.createMMRDataLeafNode = createMMRDataLeafNode;
+exports.createMMRDataParentNode = createMMRDataParentNode;
+exports.calculateProofRoot = calculateProofRoot;
+exports.verifyMMRProof = verifyMMRProof;
+exports.parseMMRProofFromHex = parseMMRProofFromHex;
+// packages/core/src/mmr.ts
+// Full MMR implementation matching Minima's MMR.java, MMRData.java, and TreeKeyNode.java
+const wasm_sync_js_1 = require("./wasm-sync.js");
+const javaStreamables_js_1 = require("./javaStreamables.js");
+// Import canonical wire serialization from Streamable.ts (single source of truth)
+const Streamable_js_1 = require("./Streamable.js");
+// Re-export for API compatibility (existing code imports from mmr.ts)
+// Using a wrapper function for better compatibility with dynamic imports
+function serializeMMRProof(proof, blockTime = 0n) {
+    // Convert to Streamable format and serialize
+    const streamableProof = {
+        blockTime: blockTime,
+        chunks: proof.chunks.map(c => ({
+            isLeft: c.isLeft,
+            mmrData: { data: c.mmrData.data, value: c.mmrData.value }
+        }))
+    };
+    return (0, Streamable_js_1.writeMMRProof)(streamableProof);
+}
+exports.serializeRealMMRProof = serializeMMRProof;
+/** SHA3-256 helper returning 32 bytes */
+function sha3(data) {
+    return (0, wasm_sync_js_1.sha3_256)(data);
+}
+/** concat utility */
+function concat(...parts) {
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+/** big-endian u32 */
+const u32be = (n) => new Uint8Array([(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]);
+/**
+ * EXACT MiniNumber.ZERO wire format from Java:
+ *   scale (1 byte) = 0x00
+ *   length (1 byte) = 0x01
+ *   unscaled bytes (length=1) = 0x00
+ * => 00 01 00
+ */
+function encodeMiniNumberZERO() {
+    return new Uint8Array([0x00, 0x01, 0x00]);
+}
+/**
+ * EXACT MiniString wire format (MiniData of UTF-8):
+ *   4-byte big-endian length
+ *   raw UTF-8 bytes
+ */
+function encodeMiniStringUTF8(text) {
+    const utf8 = new TextEncoder().encode(text);
+    const len = u32be(utf8.length);
+    return concat(len, utf8);
+}
+/**
+ * Byte-exact one-leaf MMR leaf used by Minima Address.java path:
+ *   sha3( MiniNumber.ZERO || MiniString(script) || MiniNumber.ZERO )
+ */
+function mmrLeafExact(script) {
+    const zero = encodeMiniNumberZERO();
+    const mstr = encodeMiniStringUTF8(script);
+    const all = concat(zero, mstr, zero);
+    return sha3(all); // 32-byte leaf hash
+}
+/** In a single-leaf MMR the root equals the leaf commitment. */
+function mmrRootFromSingleLeaf(script) {
+    return mmrLeafExact(script);
+}
+/**
+ * Create MMRData leaf node matching Minima's MMRData.CreateMMRDataLeafNode
+ *
+ * From MMRData.java:
+ *   MiniData hash = Crypto.getInstance().hashAllObjects(MiniNumber.ZERO, zData, zSumValue);
+ *
+ * CRITICAL: Crypto.hashAllObjects uses writeDataStream for Streamables:
+ * - MiniNumber: scale + len + data (see serializeMiniNumber)
+ * - MiniData: 4-byte length + data (see serializeMiniData)
+ *
+ * For TreeKeyNode, zData is the Winternitz public key (MiniData) and zSumValue is ZERO
+ *
+ * Serialization order:
+ * 1. MiniNumber.ZERO: [0x00, 0x01, 0x00]
+ * 2. MiniData (pubkey): [4-byte length] + [bytes] (writeDataStream, NOT writeHashToStream)
+ * 3. MiniNumber.ZERO: [0x00, 0x01, 0x00]
+ */
+function createMMRDataLeafNode(pubkey, sumValue = 0n) {
+    // Use cached ZERO serialization for efficiency
+    const zero = new Uint8Array([0x00, 0x01, 0x00]); // MiniNumber.ZERO
+    // IMPORTANT: hashAllObjects uses writeDataStream which is 4-byte length prefixed
+    const pubkeySerialized = (0, javaStreamables_js_1.serializeMiniData)(pubkey);
+    // For sumValue, serialize as MiniNumber
+    let sumSerialized;
+    if (sumValue === 0n) {
+        sumSerialized = new Uint8Array([0x00, 0x01, 0x00]); // MiniNumber.ZERO
+    }
+    else {
+        sumSerialized = (0, javaStreamables_js_1.serializeMiniNumber)(Number(sumValue));
+    }
+    const hash = (0, javaStreamables_js_1.javaHashAllObjects)(zero, pubkeySerialized, sumSerialized);
+    return { data: hash, value: sumValue };
+}
+/**
+ * Create MMRData parent node matching Minima's MMRData.CreateMMRDataParentNode
+ *
+ * From MMRData.java:
+ *   MiniNumber sumvalue = zLeft.getValue().add(zRight.getValue());
+ *   MiniData combinedhash = Crypto.getInstance().hashAllObjects(
+ *     MiniNumber.ONE, zLeft.getData(), zRight.getData(), sumvalue);
+ *
+ * CRITICAL: The getData() returns MiniData (the hash), which is serialized
+ * with writeDataStream (4-byte length) in hashAllObjects.
+ *
+ * Serialization order:
+ * 1. MiniNumber.ONE: [0x00, 0x01, 0x01]
+ * 2. MiniData (left.data): [4-byte length] + [bytes]
+ * 3. MiniData (right.data): [4-byte length] + [bytes]
+ * 4. MiniNumber (sumvalue): serialized MiniNumber
+ */
+function createMMRDataParentNode(left, right) {
+    const sumValue = left.value + right.value;
+    // MiniNumber.ONE: [0x00, 0x01, 0x01]
+    const one = new Uint8Array([0x00, 0x01, 0x01]);
+    // Serialize left and right data as MiniData (4-byte length-prefixed)
+    const leftDataSerialized = (0, javaStreamables_js_1.serializeMiniData)(left.data);
+    const rightDataSerialized = (0, javaStreamables_js_1.serializeMiniData)(right.data);
+    // Serialize sum value
+    let sumSerialized;
+    if (sumValue === 0n) {
+        sumSerialized = new Uint8Array([0x00, 0x01, 0x00]); // MiniNumber.ZERO
+    }
+    else {
+        sumSerialized = (0, javaStreamables_js_1.serializeMiniNumber)(Number(sumValue));
+    }
+    const hash = (0, javaStreamables_js_1.javaHashAllObjects)(one, leftDataSerialized, rightDataSerialized, sumSerialized);
+    return { data: hash, value: sumValue };
+}
+/**
+ * Simple MMR Tree for TreeKeyNode
+ * Builds a perfect binary tree from N entries (N must be power of 2 for simplicity)
+ *
+ * This matches TreeKeyNode.java which always uses 64 leaves (2^6)
+ */
+class MMRTree {
+    entries = new Map();
+    leafCount = 0;
+    maxRow = 0;
+    getKey(row, entryNumber) {
+        return `${row}:${entryNumber}`;
+    }
+    setEntry(row, entryNumber, data) {
+        const entry = { row, entryNumber, mmrData: data };
+        this.entries.set(this.getKey(row, entryNumber), entry);
+        if (row > this.maxRow)
+            this.maxRow = row;
+        return entry;
+    }
+    getEntry(row, entryNumber) {
+        return this.entries.get(this.getKey(row, entryNumber));
+    }
+    /**
+     * Add a leaf entry to the MMR
+     * Matches MMR.java addEntry() but simplified for power-of-2 trees
+     */
+    addLeaf(data) {
+        const entryNumber = BigInt(this.leafCount);
+        const entry = this.setEntry(0, entryNumber, data);
+        this.leafCount++;
+        // Propagate up the tree
+        let current = entry;
+        while (current.entryNumber % 2n === 1n) { // Is right child
+            const siblingNumber = current.entryNumber - 1n;
+            const sibling = this.getEntry(current.row, siblingNumber);
+            if (!sibling)
+                break;
+            // Create parent node
+            const parentData = createMMRDataParentNode(sibling.mmrData, current.mmrData);
+            const parentRow = current.row + 1;
+            const parentEntry = current.entryNumber / 2n;
+            current = this.setEntry(parentRow, parentEntry, parentData);
+        }
+        return entry;
+    }
+    /**
+     * Build tree from array of Winternitz public keys
+     * Used by TreeKeyNode to compute wallet public key
+     */
+    static fromPublicKeys(pubkeys) {
+        const tree = new MMRTree();
+        for (const pk of pubkeys) {
+            const leafData = createMMRDataLeafNode(pk, 0n);
+            tree.addLeaf(leafData);
+        }
+        return tree;
+    }
+    /**
+     * Get the root of the tree
+     * For a perfect binary tree with N leaves, root is at row log2(N), entry 0
+     */
+    getRoot() {
+        if (this.leafCount === 0)
+            return null;
+        // For power of 2 leaves, there's exactly one peak at the top
+        const topRow = Math.floor(Math.log2(this.leafCount));
+        const root = this.getEntry(topRow, 0n);
+        return root?.mmrData || null;
+    }
+    /**
+     * Get proof for a leaf at given index
+     * Matches MMR.java getProofToPeak()
+     */
+    getProof(leafIndex) {
+        const chunks = [];
+        let row = 0;
+        let entryNumber = BigInt(leafIndex);
+        // Walk up the tree collecting siblings
+        while (row < this.maxRow) {
+            const siblingNumber = entryNumber % 2n === 0n
+                ? entryNumber + 1n // Current is left, sibling is right
+                : entryNumber - 1n; // Current is right, sibling is left
+            const sibling = this.getEntry(row, siblingNumber);
+            if (!sibling)
+                break;
+            const isLeft = siblingNumber < entryNumber;
+            chunks.push({ isLeft, mmrData: sibling.mmrData });
+            // Move to parent
+            row++;
+            entryNumber = entryNumber / 2n;
+        }
+        return { chunks };
+    }
+    /**
+     * Get the leaf MMRData at a specific index
+     */
+    getLeaf(index) {
+        const entry = this.getEntry(0, BigInt(index));
+        return entry?.mmrData || null;
+    }
+}
+exports.MMRTree = MMRTree;
+/**
+ * Calculate root from leaf data and proof
+ * Matches SignatureProof.getRootPublicKey() in Java
+ *
+ * From SignatureProof.java:
+ *   MMRData pubentry = MMRData.CreateMMRDataLeafNode(mPublicKey, MiniNumber.ZERO);
+ *   return mProof.calculateProof(pubentry).getData();
+ */
+function calculateProofRoot(leafData, proof) {
+    let current = leafData;
+    for (const chunk of proof.chunks) {
+        if (chunk.isLeft) {
+            // Sibling is on the left, current is on the right
+            current = createMMRDataParentNode(chunk.mmrData, current);
+        }
+        else {
+            // Sibling is on the right, current is on the left
+            current = createMMRDataParentNode(current, chunk.mmrData);
+        }
+    }
+    return current.data;
+}
+/**
+ * Verify a proof: check that leaf + proof computes to expected root
+ */
+function verifyMMRProof(leafPubkey, proof, expectedRoot) {
+    const leafData = createMMRDataLeafNode(leafPubkey, 0n);
+    const computedRoot = calculateProofRoot(leafData, proof);
+    if (computedRoot.length !== expectedRoot.length)
+        return false;
+    for (let i = 0; i < computedRoot.length; i++) {
+        if (computedRoot[i] !== expectedRoot[i])
+            return false;
+    }
+    return true;
+}
+// NOTE: serializeMMRProof is now imported from minimaWireSerializer.ts and re-exported above
+// This consolidates wire format serialization into a single source of truth.
+/**
+ * Deserialize MMRProof from bytes matching Minima's MMRProof.readDataStream()
+ *
+ * Format:
+ *   1. blockTime (MiniNumber)
+ *   2. chain length (MiniNumber)
+ *   3. Each chunk: isLeft (1 byte) + MMRData (hash with 4-byte length prefix + value MiniNumber)
+ *
+ * CRITICAL: Java MMRData.readDataStream uses mData.readHashFromStream() which reads
+ * a 4-byte big-endian length prefix followed by the hash bytes.
+ *
+ * @returns { proof: MMRProof, blockTime: bigint }
+ */
+function parseMMRProofFromHex(data) {
+    let offset = 0;
+    // Read blockTime as MiniNumber
+    const { value: blockTime, bytesRead: btRead } = readMiniNumber(data, offset);
+    offset += btRead;
+    // Read chain length as MiniNumber
+    const { value: numChunks, bytesRead: ncRead } = readMiniNumber(data, offset);
+    offset += ncRead;
+    const chunks = [];
+    for (let i = 0; i < Number(numChunks); i++) {
+        // isLeft flag (1 byte)
+        const isLeft = data[offset] === 1;
+        offset += 1;
+        // MMRData: hash (4-byte length prefix + hash bytes) + value (MiniNumber)
+        // Read 4-byte big-endian length
+        const hashLength = (data[offset] << 24) | (data[offset + 1] << 16) | (data[offset + 2] << 8) | data[offset + 3];
+        offset += 4;
+        const hashData = data.slice(offset, offset + hashLength);
+        offset += hashLength;
+        const { value: chunkValue, bytesRead: cvRead } = readMiniNumber(data, offset);
+        offset += cvRead;
+        chunks.push({ isLeft, mmrData: { data: hashData, value: chunkValue } });
+    }
+    return { proof: { chunks }, blockTime, bytesRead: offset };
+}
+/**
+ * Read a MiniNumber from bytes at the given offset
+ * Format: [scale: 1 byte] [length: 1 byte] [data: N bytes]
+ */
+function readMiniNumber(data, offset) {
+    const scale = data[offset];
+    const length = data[offset + 1];
+    if (length === 0) {
+        // Zero value (shouldn't happen with proper serialization)
+        return { value: 0n, bytesRead: 2 };
+    }
+    const dataBytes = data.slice(offset + 2, offset + 2 + length);
+    // Convert bytes to bigint
+    let value = 0n;
+    for (let i = 0; i < dataBytes.length; i++) {
+        value = (value << 8n) | BigInt(dataBytes[i]);
+    }
+    // Apply scale if non-zero (for decimal numbers)
+    // For TreeKey MMR, scale is always 0
+    return { value, bytesRead: 2 + length };
+}
+/** @deprecated Use parseMMRProofFromHex */
+exports.deserializeMMRProof = parseMMRProofFromHex;

package/dist/cjs/mx.d.ts

@@ -0,0 +1 @@
+export { hexToMx, mxToHex, makeMinimaAddress, convertMinimaAddress, encodeMx, decodeMx } from './minima32.js';

package/dist/cjs/mx.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeMx = exports.encodeMx = exports.convertMinimaAddress = exports.makeMinimaAddress = exports.mxToHex = exports.hexToMx = void 0;
+var minima32_js_1 = require("./minima32.js");
+Object.defineProperty(exports, "hexToMx", { enumerable: true, get: function () { return minima32_js_1.hexToMx; } });
+Object.defineProperty(exports, "mxToHex", { enumerable: true, get: function () { return minima32_js_1.mxToHex; } });
+Object.defineProperty(exports, "makeMinimaAddress", { enumerable: true, get: function () { return minima32_js_1.makeMinimaAddress; } });
+Object.defineProperty(exports, "convertMinimaAddress", { enumerable: true, get: function () { return minima32_js_1.convertMinimaAddress; } });
+Object.defineProperty(exports, "encodeMx", { enumerable: true, get: function () { return minima32_js_1.encodeMx; } });
+Object.defineProperty(exports, "decodeMx", { enumerable: true, get: function () { return minima32_js_1.decodeMx; } });

package/dist/cjs/package.json

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

package/dist/cjs/params.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WOTS Parameter Set - BouncyCastle Compatible (w=8)
+ *
+ * Matches Minima Java implementation which uses BouncyCastle:
+ * - Winternitz.java: WINTERNITZ_VALUE = 8
+ * - WinternitzOTSignature.java: w=8 means 8 BITS per digit (not base-8)
+ * - SHA3-256 hash function (mdsize = 32 bytes)
+ *
+ * Chain count calculation (from WinternitzOTSignature constructor):
+ *   messagesize = ((mdsize << 3) + w - 1) / w = (256 + 7) / 8 = 32
+ *   checksumsize = getLog((messagesize << w) + 1) = getLog(8193) = 14 bits
+ *   keysize = messagesize + (checksumsize + w - 1) / w = 32 + (14 + 7) / 8 = 34
+ *
+ * So L = 34 chains total, each chain value is 0-255 (8-bit digit)
+ */
+export type ParamSet = {
+    name: 'minima';
+    n: 256;
+    w: 8;
+    L: 34;
+    messageSize: 32;
+    checksumSize: 14;
+    checksumDigits: 2;
+    maxDigit: 255;
+};
+export declare const WOTS_MINIMA: ParamSet;
+export declare const WOTS_V1_DEV: ParamSet;
+export declare const WOTS_V2_SPEC: ParamSet;
+export declare function getParamSet(_env?: string): ParamSet;

package/dist/cjs/params.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WOTS_V2_SPEC = exports.WOTS_V1_DEV = exports.WOTS_MINIMA = void 0;
+exports.getParamSet = getParamSet;
+exports.WOTS_MINIMA = {
+    name: 'minima',
+    n: 256,
+    w: 8,
+    L: 34,
+    messageSize: 32,
+    checksumSize: 14,
+    checksumDigits: 2,
+    maxDigit: 255,
+};
+// Legacy aliases for backwards compatibility during migration
+exports.WOTS_V1_DEV = exports.WOTS_MINIMA;
+exports.WOTS_V2_SPEC = exports.WOTS_MINIMA;
+function getParamSet(_env) {
+    return exports.WOTS_MINIMA;
+}

package/dist/cjs/script.d.ts

@@ -0,0 +1,7 @@
+import type { WotsKeypair } from "./wots.js";
+/** Produce KISSVM script that authorizes with a WOTS PK digest (32 bytes). */
+export declare function scriptFromWotsPk(pkDigest32: Uint8Array): string;
+/** Address from WOTS keypair (client-only): script -> MMR leaf -> Mx */
+export declare function wotsAddressFromKeypair(kp: WotsKeypair): string;
+/** tiny utils */
+export declare function hexToBytes(hex: string): Uint8Array;

package/dist/cjs/script.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scriptFromWotsPk = scriptFromWotsPk;
+exports.wotsAddressFromKeypair = wotsAddressFromKeypair;
+exports.hexToBytes = hexToBytes;
+const util_js_1 = require("./util.js");
+const derive_js_1 = require("./derive.js");
+/** Produce KISSVM script that authorizes with a WOTS PK digest (32 bytes). */
+function scriptFromWotsPk(pkDigest32) {
+    // Minima uses SHA3-256 in SIGNEDBY paths; here we embed the digest as hex.
+    return `RETURN SIGNEDBY(${(0, util_js_1.bytesToHex)(pkDigest32)})`;
+}
+/** Address from WOTS keypair (client-only): script -> MMR leaf -> Mx */
+function wotsAddressFromKeypair(kp) {
+    const script = scriptFromWotsPk(kp.pk);
+    return (0, derive_js_1.scriptToAddress)(script);
+}
+/** tiny utils */
+function hexToBytes(hex) {
+    let h = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (h.length % 2)
+        h = "0" + h;
+    const out = new Uint8Array(h.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}