@totemsdk/core 1.0.0

package/src/javaStreamables.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * Java-Compatible Serialization Helpers
+ *
+ * Matches Minima Java serialization exactly:
+ * - MiniNumber.java: writeDataStream / readDataStream
+ * - MiniData.java: writeDataStream / readDataStream
+ * - Crypto.java: hashAllObjects - serializes Streamables then SHA3-256
+ *
+ * These helpers are used for seed derivation to match TreeKeyNode.java:
+ *   MiniData seed = Crypto.getInstance().hashAllObjects(new MiniNumber(i), zPrivateSeed);
+ *
+ * NOTE: This module provides number-based wrappers for backward compatibility.
+ * The canonical implementations are in Streamable.ts which uses bigint for precision.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeMiniNumber = serializeMiniNumber;
+exports.serializeMiniData = serializeMiniData;
+exports.hashAllObjects = hashAllObjects;
+exports.deriveChainSeedJava = deriveChainSeedJava;
+exports.deriveChildTreeSeedJava = deriveChildTreeSeedJava;
+exports.hashObject = hashObject;
+exports.indexToMiniDataBytes = indexToMiniDataBytes;
+exports.derivePerAddressSeed = derivePerAddressSeed;
+exports.serializeMiniNumberZERO = serializeMiniNumberZERO;
+exports.serializeMiniNumberONE = serializeMiniNumberONE;
+exports.writeHashToStream = writeHashToStream;
+exports.javaHashAllObjects = javaHashAllObjects;
+exports.createMMREntryNumber = createMMREntryNumber;
+exports.serializeMMREntryNumber = serializeMMREntryNumber;
+exports.serializeMMRData = serializeMMRData;
+exports.serializeMMREntry = serializeMMREntry;
+exports.precomputeTransactionCoinID = precomputeTransactionCoinID;
+const sha3_1 = require("@noble/hashes/sha3");
+const Streamable_1 = require("./Streamable");
+/**
+ * Serialize a number in MiniNumber format (Java compatible)
+ *
+ * Thin wrapper over Streamable.writeMiniNumber that accepts number for backward compatibility.
+ *
+ * @param n - Non-negative integer to serialize
+ * @returns Serialized bytes matching Java MiniNumber format
+ */
+function serializeMiniNumber(n) {
+    if (n < 0)
+        throw new Error('MiniNumber must be non-negative');
+    return (0, Streamable_1.writeMiniNumber)(BigInt(n));
+}
+/**
+ * Serialize bytes in MiniData format (Java compatible)
+ *
+ * Re-export of Streamable.writeMiniData for backward compatibility.
+ *
+ * @param data - Bytes to serialize
+ * @returns Serialized bytes matching Java MiniData format
+ */
+function serializeMiniData(data) {
+    return (0, Streamable_1.writeMiniData)(data);
+}
+/**
+ * Hash multiple Streamable objects (Java compatible)
+ *
+ * From Crypto.java hashAllObjects:
+ *   1. Write each object to DataOutputStream
+ *   2. SHA3-256 hash the combined bytes
+ *
+ * This matches TreeKeyNode.java seed derivation:
+ *   Crypto.getInstance().hashAllObjects(new MiniNumber(i), zPrivateSeed)
+ *
+ * @param items - Array of serialized objects (use serializeMiniNumber/serializeMiniData)
+ * @returns 32-byte SHA3-256 hash
+ */
+function hashAllObjects(...items) {
+    // Concatenate all serialized items
+    const totalLength = items.reduce((sum, item) => sum + item.length, 0);
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const item of items) {
+        combined.set(item, offset);
+        offset += item.length;
+    }
+    // SHA3-256 hash
+    return (0, sha3_1.sha3_256)(combined);
+}
+/**
+ * Derive per-chain seed matching Java TreeKeyNode.java exactly
+ *
+ * From TreeKeyNode.java constructor (line 43-44):
+ *   MiniData seed = Crypto.getInstance().hashAllObjects(new MiniNumber(i), zPrivateSeed);
+ *
+ * @param privateSeed - 32-byte private seed
+ * @param index - Chain index (0-63)
+ * @returns 32-byte derived seed for this chain
+ */
+function deriveChainSeedJava(privateSeed, index) {
+    const indexSerialized = serializeMiniNumber(index);
+    const seedSerialized = serializeMiniData(privateSeed);
+    return hashAllObjects(indexSerialized, seedSerialized);
+}
+/**
+ * Derive child tree seed matching Java TreeKeyNode.java exactly
+ *
+ * From TreeKeyNode.java getChild (line 68):
+ *   MiniData seed = Crypto.getInstance().hashAllObjects(new MiniNumber(zChild), mChildSeed);
+ *
+ * The child seed is derived from parent's private seed:
+ *   mChildSeed = Crypto.getInstance().hashObject(zPrivateSeed); // line 30
+ *
+ * @param childSeed - 32-byte child seed (hash of parent's private seed)
+ * @param childIndex - Child index (0-63)
+ * @returns 32-byte derived seed for child tree
+ */
+function deriveChildTreeSeedJava(childSeed, childIndex) {
+    const indexSerialized = serializeMiniNumber(childIndex);
+    const seedSerialized = serializeMiniData(childSeed);
+    return hashAllObjects(indexSerialized, seedSerialized);
+}
+/**
+ * Hash a single object matching Java's Crypto.hashObject()
+ *
+ * From TreeKeyNode.java line 30:
+ *   mChildSeed = Crypto.getInstance().hashObject(zPrivateSeed);
+ *
+ * This serializes the object as MiniData (length-prefixed) and hashes it.
+ *
+ * @param data - Raw bytes (will be serialized as MiniData)
+ * @returns 32-byte SHA3-256 hash
+ */
+function hashObject(data) {
+    const serialized = serializeMiniData(data);
+    return (0, sha3_1.sha3_256)(serialized);
+}
+/**
+ * Convert index to MiniData bytes matching Java's:
+ *   new MiniData(new BigInteger(Integer.toString(index)))
+ *
+ * BigInteger uses minimum byte representation (no leading zeros).
+ * This is used for per-address key derivation in Wallet.java.
+ *
+ * @param index - Non-negative integer (0, 1, 2, ...)
+ * @returns Minimal byte representation of the index
+ */
+function indexToMiniDataBytes(index) {
+    if (index === 0) {
+        return new Uint8Array([0x00]);
+    }
+    // Convert to minimum byte representation (big-endian, no leading zeros)
+    const bytes = [];
+    let n = index;
+    while (n > 0) {
+        bytes.unshift(n & 0xff);
+        n = n >> 8;
+    }
+    return new Uint8Array(bytes);
+}
+/**
+ * Derive per-address private seed matching Minima Wallet.java exactly
+ *
+ * From Wallet.java createNewKey() (lines 498-503):
+ *   MiniData modifier = new MiniData(new BigInteger(Integer.toString(numkeys)));
+ *   MiniData privseed = Crypto.getInstance().hashObjects(new MiniData(mBaseSeed.getSeed()), modifier);
+ *
+ * CRITICAL: This is DIFFERENT from deriveChainSeedJava!
+ * - deriveChainSeedJava: hashAllObjects(MiniNumber(index), MiniData(seed)) - index first as MiniNumber
+ * - This function: hashObjects(MiniData(baseSeed), MiniData(modifier)) - baseSeed first, both as MiniData
+ *
+ * @param baseSeed - 32-byte base wallet seed (from mnemonic)
+ * @param addressIndex - Address index (0, 1, 2, ... 63)
+ * @returns 32-byte private seed for this address's TreeKey
+ */
+function derivePerAddressSeed(baseSeed, addressIndex) {
+    // Step 1: Create modifier bytes from BigInteger representation of index
+    const modifierBytes = indexToMiniDataBytes(addressIndex);
+    // Step 2: Serialize both as MiniData (4-byte length prefix each)
+    const baseSeedSerialized = serializeMiniData(baseSeed);
+    const modifierSerialized = serializeMiniData(modifierBytes);
+    // Step 3: Concatenate and hash (baseSeed FIRST, then modifier)
+    const combined = new Uint8Array(baseSeedSerialized.length + modifierSerialized.length);
+    combined.set(baseSeedSerialized, 0);
+    combined.set(modifierSerialized, baseSeedSerialized.length);
+    return (0, sha3_1.sha3_256)(combined);
+}
+/**
+ * Serialize MiniNumber.ZERO - cached for performance
+ * Returns: [0x00, 0x01, 0x00] = scale(0) + length(1) + value(0)
+ */
+function serializeMiniNumberZERO() {
+    return new Uint8Array([0x00, 0x01, 0x00]);
+}
+/**
+ * Serialize MiniNumber.ONE
+ * Returns: [0x00, 0x01, 0x01] = scale(0) + length(1) + value(1)
+ */
+function serializeMiniNumberONE() {
+    return new Uint8Array([0x00, 0x01, 0x01]);
+}
+/**
+ * Serialize hash in MiniData.writeHashToStream format (4-byte length prefix)
+ *
+ * Re-export of Streamable.writeHashToStream for backward compatibility.
+ *
+ * @param data - Hash bytes (max 64 bytes per MINIMA_MAX_HASH_LENGTH)
+ * @returns Serialized bytes with 4-byte length prefix
+ */
+function writeHashToStream(data) {
+    return (0, Streamable_1.writeHashToStream)(data);
+}
+/**
+ * Java hashAllObjects for MMRData hashing
+ * Used for MMRData.CreateMMRDataLeafNode and CreateMMRDataParentNode
+ *
+ * From Crypto.java hashAllObjects:
+ * Serializes each Streamable object and hashes the concatenation.
+ *
+ * For MMRData, the serialization is:
+ * - MiniNumber: [scale][len][data] (see serializeMiniNumber)
+ * - MiniData: [4-byte len][data] for writeDataStream
+ * - Hash: [4-byte len][data] for writeHashToStream (same as MiniData)
+ *
+ * CRITICAL: Java writeHashToStream uses writeInt (4-byte prefix),
+ * identical to writeDataStream. See MiniData.java lines 282-289.
+ *
+ * @param items - Pre-serialized items to concatenate and hash
+ * @returns 32-byte SHA3-256 hash
+ */
+function javaHashAllObjects(...items) {
+    const totalLength = items.reduce((sum, item) => sum + item.length, 0);
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const item of items) {
+        combined.set(item, offset);
+        offset += item.length;
+    }
+    return (0, sha3_1.sha3_256)(combined);
+}
+/**
+ * Create MMREntryNumber from bigint (common case for integer positions)
+ */
+function createMMREntryNumber(value) {
+    return { scale: 0, unscaled: value };
+}
+/**
+ * Serialize MMREntryNumber matching Java MMREntryNumber.writeDataStream()
+ *
+ * From MMREntryNumber.java:
+ *   MiniNumber.WriteToStream(zOut, mNumber.scale());
+ *   MiniData.WriteToStream(zOut, mNumber.unscaledValue().toByteArray());
+ *
+ * @param entry - MMREntryNumber to serialize
+ * @returns Serialized bytes: MiniNumber(scale) + MiniData(unscaled bytes)
+ */
+function serializeMMREntryNumber(entry) {
+    const scaleSerialized = serializeMiniNumber(entry.scale);
+    const unscaledBytes = bigintToSignedBytes(entry.unscaled);
+    const unscaledSerialized = serializeMiniData(unscaledBytes);
+    const result = new Uint8Array(scaleSerialized.length + unscaledSerialized.length);
+    result.set(scaleSerialized, 0);
+    result.set(unscaledSerialized, scaleSerialized.length);
+    return result;
+}
+/**
+ * Convert bigint to Java BigInteger.toByteArray() format (big-endian, signed two's complement)
+ * Uses the canonical implementation from Streamable.ts
+ */
+function bigintToSignedBytes(n) {
+    return (0, Streamable_1.bigIntToByteArray)(n);
+}
+/**
+ * Serialize MMRData matching Java MMRData.writeDataStream()
+ *
+ * From MMRData.java:
+ *   mData.writeHashToStream(zOut);  // 4-byte length prefix + hash bytes
+ *   mValue.writeDataStream(zOut);   // MiniNumber format
+ *
+ * @param mmrData - MMRData to serialize
+ * @returns Serialized bytes: writeHashToStream(hash) + MiniNumber(value)
+ */
+function serializeMMRData(mmrData) {
+    const hashSerialized = writeHashToStream(mmrData.data);
+    const valueSerialized = serializeMiniNumber(Number(mmrData.value));
+    const result = new Uint8Array(hashSerialized.length + valueSerialized.length);
+    result.set(hashSerialized, 0);
+    result.set(valueSerialized, hashSerialized.length);
+    return result;
+}
+/**
+ * Serialize MMREntry matching Java MMREntry.writeDataStream()
+ *
+ * From MMREntry.java:
+ *   MiniNumber row = new MiniNumber(mRow);
+ *   row.writeDataStream(zOut);
+ *   mEntryNumber.writeDataStream(zOut);
+ *   mMMRData.writeDataStream(zOut);
+ *
+ * @param entry - MMREntry to serialize
+ * @returns Serialized bytes: MiniNumber(row) + MMREntryNumber + MMRData
+ */
+function serializeMMREntry(entry) {
+    const rowSerialized = serializeMiniNumber(entry.row);
+    const entryNumberSerialized = serializeMMREntryNumber(entry.entryNumber);
+    const mmrDataSerialized = serializeMMRData(entry.mmrData);
+    const totalLength = rowSerialized.length + entryNumberSerialized.length + mmrDataSerialized.length;
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    result.set(rowSerialized, offset);
+    offset += rowSerialized.length;
+    result.set(entryNumberSerialized, offset);
+    offset += entryNumberSerialized.length;
+    result.set(mmrDataSerialized, offset);
+    return result;
+}
+function precomputeTransactionCoinID(inputs, outputs) {
+    if (inputs.length === 0)
+        return;
+    const baseCoinId = inputs[0].coinId;
+    if (baseCoinId.length < 2) {
+        throw new Error(`Cannot precompute output coinIDs: input[0].coinId is ${baseCoinId.length} byte(s) ` +
+            `(placeholder?). Real coinId from CoinProof required for signing.`);
+    }
+    for (let i = 0; i < outputs.length; i++) {
+        const baseCoinIdStream = (0, Streamable_1.writeMiniData)(baseCoinId);
+        const outputIndexStream = (0, Streamable_1.writeMiniNumber)(BigInt(i));
+        const combined = new Uint8Array(baseCoinIdStream.length + outputIndexStream.length);
+        combined.set(baseCoinIdStream, 0);
+        combined.set(outputIndexStream, baseCoinIdStream.length);
+        outputs[i].coinId = (0, sha3_1.sha3_256)(combined);
+    }
+}