@totemsdk/core 1.0.0

package/dist/minima32.js

@@ -0,0 +1,112 @@
+// Minima "Mx" Base32 — matches org.minima.utils.BaseConverter.encode32/decode32
+// Source behavior: BigInteger radix-32, then i→w, l→y, o→z, uppercased, prefixed with "Mx".
+function bytesToBigInt(bytes) {
+    let x = 0n;
+    for (const b of bytes)
+        x = (x << 8n) | BigInt(b);
+    return x;
+}
+function bigIntToBytes(x) {
+    if (x === 0n)
+        return new Uint8Array([0]); // not normally hit for framed addresses
+    let hex = x.toString(16);
+    if (hex.length % 2)
+        hex = '0' + hex;
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+    }
+    return out;
+}
+export function encodeMxRadix32Frame(frame) {
+    let s = bytesToBigInt(frame).toString(32).toLowerCase();
+    // JAR swaps (avoid ambiguous letters) then uppercase and add prefix
+    s = s.replace(/i/g, 'w').replace(/l/g, 'y').replace(/o/g, 'z');
+    return 'Mx' + s.toUpperCase();
+}
+export function decodeMxRadix32Frame(mx) {
+    let s = mx.trim().toLowerCase();
+    if (s.startsWith('mx'))
+        s = s.slice(2);
+    s = s.replace(/w/g, 'i').replace(/y/g, 'l').replace(/z/g, 'o'); // reverse swaps
+    // parse base-32 by hand (radix 32)
+    let x = 0n;
+    for (const ch of s) {
+        const v = parseInt(ch, 32);
+        if (Number.isNaN(v))
+            throw new Error(`Invalid base32 character: ${ch}`);
+        x = x * 32n + BigInt(v);
+    }
+    return bigIntToBytes(x);
+}
+import { sha3_256 as nobleSha3 } from '@noble/hashes/sha3';
+/** Encode raw 32 bytes to Mx address with frame and checksum */
+export function makeMxAddress(root32) {
+    if (root32.length !== 32) {
+        throw new Error(`Expected 32 bytes, got ${root32.length}`);
+    }
+    // Build frame: [sentinel(1), length(2), data(32), checksum(4)]
+    const frame = new Uint8Array(1 + 2 + 32 + 4);
+    frame[0] = 0x01; // Sentinel byte
+    frame[1] = 0; // Length high byte
+    frame[2] = 32; // Length low byte
+    frame.set(root32, 3);
+    // Calculate checksum of the raw 32 bytes
+    const chk = nobleSha3(root32);
+    frame.set(chk.slice(0, 4), 35);
+    return encodeMxRadix32Frame(frame);
+}
+/** Decode Mx address to raw 32 bytes, validating frame and checksum */
+export function parseMxAddress(mx) {
+    const frame = decodeMxRadix32Frame(mx);
+    // Validate frame structure
+    if (frame[0] !== 0x01) {
+        throw new Error(`Invalid sentinel byte: ${frame[0]}`);
+    }
+    const len = (frame[1] << 8) | frame[2];
+    if (len !== 32) {
+        throw new Error(`Invalid length: ${len}, expected 32`);
+    }
+    const root32 = frame.slice(3, 35);
+    const checksum = frame.slice(35, 39);
+    // Validate checksum
+    const expectedChk = nobleSha3(root32);
+    const expected = expectedChk.slice(0, 4);
+    for (let i = 0; i < 4; i++) {
+        if (checksum[i] !== expected[i]) {
+            throw new Error('Invalid checksum');
+        }
+    }
+    return root32;
+}
+// Aliases for backward compatibility
+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;
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+/** Make an Mx address from a hex string (legacy API compatibility) */
+export function hexToMx(hex) {
+    const bytes = hexToBytes(hex);
+    return makeMxAddress(bytes);
+}
+/** Convert an Mx address back to uppercase hex (legacy API compatibility) */
+export function mxToHex(mx) {
+    const bytes = parseMxAddress(mx);
+    return bytesToHex(bytes);
+}
+/** @deprecated Use makeMxAddress */
+export const encodeMx = makeMxAddress;
+/** @deprecated Use parseMxAddress */
+export const decodeMx = parseMxAddress;
+/** @deprecated Use hexToMx */
+export const makeMinimaAddress = hexToMx;
+/** @deprecated Use mxToHex */
+export const convertMinimaAddress = mxToHex;

package/dist/minimaWireSerializer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Minima Wire Format Serializer
+ *
+ * High-level serialization for hex-string bundles (used in service.ts).
+ * Primitive serialization functions are imported from Streamable.ts.
+ *
+ * @deprecated (2026-01) - Most functions deprecated. Use Streamable.ts directly for
+ * byte-level serialization. This file remains for HierarchicalWitnessBundle hex APIs.
+ */
+import { hexToBytes, bytesToHex, writeMiniNumber, writeMiniData, type Bytes } from './Streamable.js';
+export { writeMiniNumber as serializeMiniNumber, writeMiniData as serializeMiniData };
+export { hexToBytes as fromHex, bytesToHex as toHex };
+export type { Bytes };
+/**
+ * SignatureProof with hex strings (for bundle transport)
+ */
+export interface SignatureProofHex {
+    leafPubkey: string;
+    signature: string;
+    mmrProof: string;
+}
+/**
+ * HierarchicalWitnessBundle - used by service.ts for transaction signing
+ * All fields are hex strings for JSON transport
+ */
+export interface HierarchicalWitnessBundle {
+    addressIndex: number;
+    l1: number;
+    l2: number;
+    rootPublicKey: string;
+    proofs: SignatureProofHex[];
+}
+/**
+ * Serialize hierarchical witness bundle to Minima wire format
+ *
+ * This converts the HierarchicalWitnessBundle (with hex strings) to
+ * the proper Witness signature format matching Witness.java → Signature.java hierarchy.
+ *
+ * CRITICAL FIX (2026-01): Must use double-nesting to match Java format:
+ *   - Witness.writeDataStream writes: [signatureCount][Signature[0].writeDataStream()]...
+ *   - Signature.writeDataStream writes: [proofCount][SignatureProof[0]]...
+ *
+ * So the final format is:
+ *   [1] = signatureCount (we have 1 Signature object in Witness)
+ *   [N] = proofCount inside that Signature (2 for address-based TreeKey)
+ *   [SignatureProof[0]]
+ *   [SignatureProof[1]]
+ *
+ * IMPORTANT: Uses pre-serialized MMR proof bytes directly to avoid
+ * double-serialization (deserialize then re-serialize).
+ */
+export declare function serializeHierarchicalWitness(bundle: HierarchicalWitnessBundle): Bytes;
+/**
+ * @deprecated (2026-01) This function's output is NOT used in the main Totem transaction flow.
+ * MinimaTransactionBuilder.serializeWitness in the extension handles actual witness serialization.
+ * Kept for API compatibility and potential future direct SDK usage.
+ *
+ * Serialize hierarchical witness bundle to hex string for transport
+ */
+export declare function serializeHierarchicalWitnessToHex(bundle: HierarchicalWitnessBundle): string;

package/dist/minimaWireSerializer.js

@@ -0,0 +1,71 @@
+/**
+ * Minima Wire Format Serializer
+ *
+ * High-level serialization for hex-string bundles (used in service.ts).
+ * Primitive serialization functions are imported from Streamable.ts.
+ *
+ * @deprecated (2026-01) - Most functions deprecated. Use Streamable.ts directly for
+ * byte-level serialization. This file remains for HierarchicalWitnessBundle hex APIs.
+ */
+import { concat, hexToBytes, bytesToHex, writeMiniNumber, writeMiniData, } from './Streamable.js';
+// Re-export primitives for backward compatibility
+export { writeMiniNumber as serializeMiniNumber, writeMiniData as serializeMiniData };
+export { hexToBytes as fromHex, bytesToHex as toHex };
+/**
+ * Serialize a SignatureProof from pre-serialized byte arrays
+ *
+ * This avoids double-serialization by passing MMR proof bytes through directly.
+ * Format matches SignatureProof.writeDataStream():
+ *   1. MiniData (publicKey) - 4-byte length + bytes
+ *   2. MiniData (signature) - 4-byte length + bytes
+ *   3. MMRProof bytes (pre-serialized)
+ */
+function serializeSignatureProofFromBytes(publicKey, signature, mmrProofBytes) {
+    return concat(writeMiniData(publicKey), writeMiniData(signature), mmrProofBytes // Already serialized - pass through directly
+    );
+}
+/**
+ * Serialize hierarchical witness bundle to Minima wire format
+ *
+ * This converts the HierarchicalWitnessBundle (with hex strings) to
+ * the proper Witness signature format matching Witness.java → Signature.java hierarchy.
+ *
+ * CRITICAL FIX (2026-01): Must use double-nesting to match Java format:
+ *   - Witness.writeDataStream writes: [signatureCount][Signature[0].writeDataStream()]...
+ *   - Signature.writeDataStream writes: [proofCount][SignatureProof[0]]...
+ *
+ * So the final format is:
+ *   [1] = signatureCount (we have 1 Signature object in Witness)
+ *   [N] = proofCount inside that Signature (2 for address-based TreeKey)
+ *   [SignatureProof[0]]
+ *   [SignatureProof[1]]
+ *
+ * IMPORTANT: Uses pre-serialized MMR proof bytes directly to avoid
+ * double-serialization (deserialize then re-serialize).
+ */
+export function serializeHierarchicalWitness(bundle) {
+    const parts = [];
+    // Witness.signatureCount (MiniNumber) - 1 Signature object containing N proofs
+    parts.push(writeMiniNumber(1n));
+    // Signature.proofCount (MiniNumber) - N SignatureProofs inside the Signature
+    parts.push(writeMiniNumber(BigInt(bundle.proofs.length)));
+    for (const proofHex of bundle.proofs) {
+        const publicKey = hexToBytes(proofHex.leafPubkey);
+        const signature = hexToBytes(proofHex.signature);
+        const mmrProofBytes = hexToBytes(proofHex.mmrProof); // Already serialized
+        // Serialize SignatureProof with pre-serialized MMR bytes
+        parts.push(serializeSignatureProofFromBytes(publicKey, signature, mmrProofBytes));
+    }
+    return concat(...parts);
+}
+/**
+ * @deprecated (2026-01) This function's output is NOT used in the main Totem transaction flow.
+ * MinimaTransactionBuilder.serializeWitness in the extension handles actual witness serialization.
+ * Kept for API compatibility and potential future direct SDK usage.
+ *
+ * Serialize hierarchical witness bundle to hex string for transport
+ */
+export function serializeHierarchicalWitnessToHex(bundle) {
+    const bytes = serializeHierarchicalWitness(bundle);
+    return bytesToHex(bytes);
+}

package/dist/mmr.d.ts

@@ -0,0 +1,156 @@
+export declare function serializeMMRProof(proof: {
+    chunks: Array<{
+        isLeft: boolean;
+        mmrData: {
+            data: Bytes;
+            value: bigint;
+        };
+    }>;
+}, blockTime?: bigint): Bytes;
+export declare const serializeRealMMRProof: typeof serializeMMRProof;
+export type Bytes = Uint8Array;
+/**
+ * Byte-exact one-leaf MMR leaf used by Minima Address.java path:
+ *   sha3( MiniNumber.ZERO || MiniString(script) || MiniNumber.ZERO )
+ */
+export declare function mmrLeafExact(script: string): Bytes;
+/** In a single-leaf MMR the root equals the leaf commitment. */
+export declare function mmrRootFromSingleLeaf(script: string): Bytes;
+/**
+ * MMRData structure matching Minima's MMRData.java
+ * Contains hash and value (for sum tree functionality)
+ */
+export interface MMRData {
+    data: Bytes;
+    value: bigint;
+}
+/**
+ * MMREntry structure matching Minima's MMREntry.java
+ * Represents a node in the MMR at a specific row and position
+ */
+export interface MMREntry {
+    row: number;
+    entryNumber: bigint;
+    mmrData: MMRData;
+}
+/**
+ * MMRProofChunk - one step in the proof path
+ * Matches Minima's MMRProof structure
+ */
+export interface MMRProofChunk {
+    isLeft: boolean;
+    mmrData: MMRData;
+}
+/**
+ * MMRProof structure matching Minima's MMRProof.java
+ * Contains proof chunks to verify leaf membership in the tree
+ */
+export interface MMRProof {
+    chunks: MMRProofChunk[];
+}
+/**
+ * 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]
+ */
+export declare function createMMRDataLeafNode(pubkey: Bytes, sumValue?: bigint): MMRData;
+/**
+ * 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
+ */
+export declare function createMMRDataParentNode(left: MMRData, right: MMRData): MMRData;
+/**
+ * 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)
+ */
+export declare class MMRTree {
+    private entries;
+    private leafCount;
+    private maxRow;
+    private getKey;
+    private setEntry;
+    private getEntry;
+    /**
+     * Add a leaf entry to the MMR
+     * Matches MMR.java addEntry() but simplified for power-of-2 trees
+     */
+    addLeaf(data: MMRData): MMREntry;
+    /**
+     * Build tree from array of Winternitz public keys
+     * Used by TreeKeyNode to compute wallet public key
+     */
+    static fromPublicKeys(pubkeys: Bytes[]): MMRTree;
+    /**
+     * Get the root of the tree
+     * For a perfect binary tree with N leaves, root is at row log2(N), entry 0
+     */
+    getRoot(): MMRData | null;
+    /**
+     * Get proof for a leaf at given index
+     * Matches MMR.java getProofToPeak()
+     */
+    getProof(leafIndex: number): MMRProof;
+    /**
+     * Get the leaf MMRData at a specific index
+     */
+    getLeaf(index: number): MMRData | null;
+}
+/**
+ * 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();
+ */
+export declare function calculateProofRoot(leafData: MMRData, proof: MMRProof): Bytes;
+/**
+ * Verify a proof: check that leaf + proof computes to expected root
+ */
+export declare function verifyMMRProof(leafPubkey: Bytes, proof: MMRProof, expectedRoot: Bytes): boolean;
+/**
+ * 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 }
+ */
+export declare function parseMMRProofFromHex(data: Bytes): {
+    proof: MMRProof;
+    blockTime: bigint;
+};
+/** @deprecated Use parseMMRProofFromHex */
+export declare const deserializeMMRProof: typeof parseMMRProofFromHex;