@totemsdk/core 1.0.9 → 1.0.11

package/src/javaStreamables.js

@@ -1,332 +0,0 @@
-/**
- * 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.
- */
-import { sha3_256 } from '@noble/hashes/sha3.js';
-import { writeMiniNumber as streamableWriteMiniNumber, writeMiniData as streamableWriteMiniData, writeHashToStream as streamableWriteHashToStream, bigIntToByteArray } from './Streamable.js';
-/**
- * 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
- */
-export function serializeMiniNumber(n) {
-    if (n < 0)
-        throw new Error('MiniNumber must be non-negative');
-    return streamableWriteMiniNumber(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
- */
-export function serializeMiniData(data) {
-    return streamableWriteMiniData(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
- */
-export 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 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
- */
-export 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
- */
-export 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
- */
-export function hashObject(data) {
-    const serialized = serializeMiniData(data);
-    return 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
- */
-export 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
- */
-export 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);
-    const result = sha3_256(combined);
-    // DIAGNOSTIC: Log first 8 bytes to detect bundle duplication or implementation differences
-    // Enable via: globalThis.TOTEM_SEED_DEBUG = true
-    if (typeof console !== 'undefined' && globalThis.TOTEM_SEED_DEBUG) {
-        const toHex = (b) => Array.from(b.slice(0, 8)).map(x => x.toString(16).padStart(2, '0')).join('');
-        console.log(`[derivePerAddressSeed] idx=${addressIndex} baseSeed[0:8]=${toHex(baseSeed)} -> result[0:8]=${toHex(result)}`);
-    }
-    return result;
-}
-/**
- * Serialize MiniNumber.ZERO - cached for performance
- * Returns: [0x00, 0x01, 0x00] = scale(0) + length(1) + value(0)
- */
-export function serializeMiniNumberZERO() {
-    return new Uint8Array([0x00, 0x01, 0x00]);
-}
-/**
- * Serialize MiniNumber.ONE
- * Returns: [0x00, 0x01, 0x01] = scale(0) + length(1) + value(1)
- */
-export 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
- */
-export function writeHashToStream(data) {
-    return streamableWriteHashToStream(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
- */
-export 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 sha3_256(combined);
-}
-/**
- * Create MMREntryNumber from bigint (common case for integer positions)
- */
-export 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)
- */
-export 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 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)
- */
-export 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
- */
-export 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;
-}
-/**
- * Precompute output coin IDs before computing the transaction digest.
- *
- * CRITICAL: Java's txnsign command calls TxPoWGenerator.precomputeTransactionCoinID(txn)
- * BEFORE calculateTransactionID(). This means the transaction digest that gets signed
- * includes the PRECOMPUTED output coin IDs, not the placeholder 0x00.
- *
- * Formula: outputCoinID = SHA3-256( writeMiniData(input[0].coinID) || writeMiniNumber(outputIndex) )
- * This matches Java's Crypto.hashObjects(baseCoinID, new MiniNumber(outputNum))
- *
- * Without this, the wallet signs a different digest than what the node verifies against,
- * causing allsignaturesvalid=false on every transaction.
- *
- * @param inputs - Transaction inputs array, each must have a coinId (Uint8Array)
- * @param outputs - Transaction outputs array, each will have its coinId mutated in-place
- */
-export 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 = streamableWriteMiniData(baseCoinId);
-        const outputIndexStream = streamableWriteMiniNumber(BigInt(i));
-        const combined = new Uint8Array(baseCoinIdStream.length + outputIndexStream.length);
-        combined.set(baseCoinIdStream, 0);
-        combined.set(outputIndexStream, baseCoinIdStream.length);
-        outputs[i].coinId = sha3_256(combined);
-    }
-}