@totemsdk/core 1.0.9 → 1.0.11

package/src/javaStreamables.ts

@@ -1,403 +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: number): Uint8Array {
-  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: Uint8Array): Uint8Array {
-  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: Uint8Array[]): Uint8Array {
-  // 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: Uint8Array, index: number): Uint8Array {
-  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: Uint8Array, childIndex: number): Uint8Array {
-  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: Uint8Array): Uint8Array {
-  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: number): Uint8Array {
-  if (index === 0) {
-    return new Uint8Array([0x00]);
-  }
-  
-  // Convert to minimum byte representation (big-endian, no leading zeros)
-  const bytes: number[] = [];
-  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: Uint8Array, addressIndex: number): Uint8Array {
-  // 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 as any).TOTEM_SEED_DEBUG) {
-    const toHex = (b: Uint8Array) => 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(): Uint8Array {
-  return new Uint8Array([0x00, 0x01, 0x00]);
-}
-
-/**
- * Serialize MiniNumber.ONE
- * Returns: [0x00, 0x01, 0x01] = scale(0) + length(1) + value(1)
- */
-export function serializeMiniNumberONE(): Uint8Array {
-  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: Uint8Array): Uint8Array {
-  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: Uint8Array[]): Uint8Array {
-  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);
-}
-
-/**
- * MMREntryNumber interface matching Minima's MMREntryNumber.java
- * Represents a BigDecimal position in the MMR tree
- */
-export interface MMREntryNumber {
-  scale: number;       // BigDecimal scale (typically 0 for integer positions)
-  unscaled: bigint;    // BigDecimal unscaled value
-}
-
-/**
- * Create MMREntryNumber from bigint (common case for integer positions)
- */
-export function createMMREntryNumber(value: bigint): MMREntryNumber {
-  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: MMREntryNumber): Uint8Array {
-  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: bigint): Uint8Array {
-  return bigIntToByteArray(n);
-}
-
-/**
- * MMRData interface for serialization purposes
- * Matches Minima's MMRData.java
- */
-export interface MMRData {
-  data: Uint8Array;    // 32-byte hash
-  value: bigint;       // Sum value (typically 0n for TreeKey)
-}
-
-/**
- * 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: MMRData): Uint8Array {
-  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;
-}
-
-/**
- * MMREntry interface for serialization purposes
- * Matches Minima's MMREntry.java
- */
-export interface MMREntry {
-  row: number;
-  entryNumber: MMREntryNumber;
-  mmrData: MMRData;
-}
-
-/**
- * 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: MMREntry): Uint8Array {
-  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: { coinId: Uint8Array }[],
-  outputs: { coinId: Uint8Array }[]
-): void {
-  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);
-  }
-}

package/src/lease/LeaseMonitor.d.ts

@@ -1,44 +0,0 @@
-/**
- * @module LeaseMonitor
- * Monitors lease expiry and triggers renewal/cleanup actions
- *
- * Features:
- * - Automatic expiry detection with configurable thresholds
- * - Event-based notifications for expiring leases
- * - Adaptive monitoring interval based on shortest TTL
- */
-import type { TimerAdapter, LoggerAdapter } from '../adapters';
-import type { LeaseStore, StoredLease } from './LeaseStore';
-export interface LeaseExpiryEvent {
-    leaseId: string;
-    expiresAt: number;
-    remainingMs: number;
-    lease: StoredLease;
-}
-export type LeaseExpiryCallback = (event: LeaseExpiryEvent) => void;
-export interface LeaseMonitorConfig {
-    defaultIntervalMs?: number;
-    expiryThresholdMs?: number;
-    minIntervalMs?: number;
-    maxIntervalMs?: number;
-}
-export declare class LeaseMonitor {
-    private readonly leaseStore;
-    private readonly timer;
-    private readonly logger;
-    private readonly config;
-    private timerHandle;
-    private isRunning;
-    private expiryCallbacks;
-    constructor(leaseStore: LeaseStore, timer?: TimerAdapter, logger?: LoggerAdapter, config?: LeaseMonitorConfig);
-    start(): void;
-    stop(): void;
-    isActive(): boolean;
-    onExpirySoon(callback: LeaseExpiryCallback): () => void;
-    removeAllListeners(): void;
-    checkNow(): Promise<LeaseExpiryEvent[]>;
-    private scheduleNextCheck;
-    private runCheck;
-    private calculateInterval;
-    private notifyExpirySoon;
-}

package/src/lease/LeaseMonitor.js

@@ -1,111 +0,0 @@
-"use strict";
-/**
- * @module LeaseMonitor
- * Monitors lease expiry and triggers renewal/cleanup actions
- *
- * Features:
- * - Automatic expiry detection with configurable thresholds
- * - Event-based notifications for expiring leases
- * - Adaptive monitoring interval based on shortest TTL
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LeaseMonitor = void 0;
-const adapters_1 = require("../adapters");
-const DEFAULT_CONFIG = {
-    defaultIntervalMs: 5000,
-    expiryThresholdMs: 5000,
-    minIntervalMs: 1000,
-    maxIntervalMs: 30000,
-};
-class LeaseMonitor {
-    constructor(leaseStore, timer = new adapters_1.DefaultTimerAdapter(), logger = new adapters_1.NoopLogger(), config = {}) {
-        this.timerHandle = null;
-        this.isRunning = false;
-        this.expiryCallbacks = new Set();
-        this.leaseStore = leaseStore;
-        this.timer = timer;
-        this.logger = logger;
-        this.config = { ...DEFAULT_CONFIG, ...config };
-    }
-    start() {
-        if (this.isRunning) {
-            this.logger.debug('LeaseMonitor already running');
-            return;
-        }
-        this.isRunning = true;
-        this.scheduleNextCheck();
-        this.logger.debug('LeaseMonitor started');
-    }
-    stop() {
-        if (!this.isRunning)
-            return;
-        this.isRunning = false;
-        if (this.timerHandle !== null) {
-            this.timer.clearTimeout(this.timerHandle);
-            this.timerHandle = null;
-        }
-        this.logger.debug('LeaseMonitor stopped');
-    }
-    isActive() {
-        return this.isRunning;
-    }
-    onExpirySoon(callback) {
-        this.expiryCallbacks.add(callback);
-        return () => this.expiryCallbacks.delete(callback);
-    }
-    removeAllListeners() {
-        this.expiryCallbacks.clear();
-    }
-    async checkNow() {
-        const now = this.timer.now();
-        const expiringSoon = this.leaseStore.getExpiringSoon(this.config.expiryThresholdMs);
-        const events = expiringSoon.map(lease => ({
-            leaseId: lease.leaseId,
-            expiresAt: lease.expiresAt,
-            remainingMs: Math.max(0, lease.expiresAt - now),
-            lease,
-        }));
-        for (const event of events) {
-            this.notifyExpirySoon(event);
-        }
-        await this.leaseStore.cleanupExpired();
-        return events;
-    }
-    scheduleNextCheck() {
-        if (!this.isRunning)
-            return;
-        const interval = this.calculateInterval();
-        this.timerHandle = this.timer.setTimeout(() => {
-            this.runCheck();
-        }, interval);
-        this.logger.debug(`Next lease check scheduled in ${interval}ms`);
-    }
-    async runCheck() {
-        if (!this.isRunning)
-            return;
-        try {
-            await this.checkNow();
-        }
-        catch (error) {
-            this.logger.error('Error during lease check:', error);
-        }
-        this.scheduleNextCheck();
-    }
-    calculateInterval() {
-        const storeInterval = this.leaseStore.calculateMonitoringInterval();
-        const interval = Math.max(this.config.minIntervalMs, Math.min(storeInterval, this.config.maxIntervalMs));
-        return interval;
-    }
-    notifyExpirySoon(event) {
-        this.logger.debug(`Lease expiring soon: ${event.leaseId}, remaining: ${event.remainingMs}ms`);
-        this.expiryCallbacks.forEach(callback => {
-            try {
-                callback(event);
-            }
-            catch (error) {
-                this.logger.error('Error in expiry callback:', error);
-            }
-        });
-    }
-}
-exports.LeaseMonitor = LeaseMonitor;