@totemsdk/core 1.0.0

package/dist/tx/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @module Transaction Types
+ * Type definitions for transaction service
+ */
+export interface WotsIndices {
+    addressIndex: number;
+    l1: number;
+    l2: number;
+}
+export interface PrepareRequest {
+    to: string;
+    amount: string;
+    tokenId?: string;
+    burn?: string;
+    txId?: string;
+    addressIndex?: number;
+}
+export interface PrepareResponse {
+    addressIndex: number;
+    l1: number;
+    l2: number;
+    leaseToken: string;
+    digestTx: string;
+    digestL2: string | null;
+    digestL3: string | null;
+    txId: string;
+    rootPublicKey: string;
+    paramSet: string;
+    leaseId: string;
+    leaseTTL: number;
+}
+export interface SignRequest {
+    addressIndex: number;
+    l1: number;
+    l2: number;
+    digestTx: string;
+}
+/**
+ * Per-proof entry in a hierarchical TreeKey signature chain.
+ * Each proof represents one parent→child signing step.
+ */
+export interface SignatureProofHex {
+    leafPubkey: string;
+    signature: string;
+    mmrProof: string;
+}
+/**
+ * Hierarchical witness bundle produced by per-address TreeKey signing.
+ *
+ * Index mapping:
+ *   addressIndex — which HD address (0-63)
+ *   l1           — L1 index within per-address TreeKey (0-63)
+ *   l2           — L2 index within per-address TreeKey (0-63)
+ *
+ * proofs contains 3 entries for depth-3 TreeKeys (Root→L1→L2→DATA),
+ * matching Minima's TreeKey.sign() exactly.
+ */
+export interface HierarchicalWitnessBundle {
+    addressIndex: number;
+    l1: number;
+    l2: number;
+    rootPublicKey: string;
+    proofs: SignatureProofHex[];
+}
+/**
+ * @deprecated Use HierarchicalWitnessBundle. Kept for backward compatibility.
+ */
+export interface WitnessBundle {
+    addressIndex: number;
+    l1: number;
+    l2: number;
+    signatures: {
+        l1Proof: string[];
+        l2Proof: string[];
+        l3Proof: string[];
+    };
+}
+export interface SignResult {
+    witnessBundle: HierarchicalWitnessBundle;
+    signedHex: string;
+}
+export interface FinalizeRequest {
+    leaseToken: string;
+    signedHex?: string;
+    signedBase64?: string;
+    transactionHex?: string;
+    importId?: string;
+}
+export interface FinalizeResponse {
+    ok: boolean;
+    leaseId: string;
+    txpowid: string;
+}
+export interface TransactionMetadata {
+    to: string;
+    amount: string;
+    tokenId: string;
+}
+export interface TransactionReceipt {
+    txpowid: string;
+    timestamp: number;
+    to: string;
+    amount: string;
+    tokenId: string;
+    indices: WotsIndices;
+    status: 'confirmed' | 'pending' | 'failed';
+    txId?: string;
+    leaseId?: string;
+}
+export interface TransactionError {
+    code: number;
+    message: string;
+    userMessage: string;
+}

package/dist/tx/types.js

@@ -0,0 +1,5 @@
+/**
+ * @module Transaction Types
+ * Type definitions for transaction service
+ */
+export {};

package/dist/util.d.ts

@@ -0,0 +1 @@
+export declare const bytesToHex: (b: Uint8Array) => string;

package/dist/util.js

@@ -0,0 +1 @@
+export const bytesToHex = (b) => "0x" + [...b].map(x => x.toString(16).padStart(2, "0")).join("").toUpperCase();

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility functions for byte array manipulation
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;
+export declare function utf8ToBytes(str: string): Uint8Array;
+export declare function bytesToUtf8(bytes: Uint8Array): string;

package/dist/utils.js

@@ -0,0 +1,35 @@
+/**
+ * Utility functions for byte array manipulation
+ */
+export function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+export function hexToBytes(hex) {
+    if (hex.startsWith('0x'))
+        hex = hex.slice(2);
+    if (hex.length % 2 !== 0)
+        throw new Error('Invalid hex string');
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+export function concatBytes(...arrays) {
+    const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+export function utf8ToBytes(str) {
+    return new TextEncoder().encode(str);
+}
+export function bytesToUtf8(bytes) {
+    return new TextDecoder().decode(bytes);
+}

package/dist/verify.d.ts

@@ -0,0 +1,18 @@
+import type { TreeSignature } from './treekey.js';
+import type { Bytes } from './mmr.js';
+export interface VerificationResult {
+    valid: boolean;
+    error?: string;
+}
+export declare function normalizeHex(hex: string): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function deriveAddressFromPublicKey(publicKeyHex: string): string;
+export declare function verifyTreeSignatureDetailed(expectedPubkey: Bytes, data: Bytes, signature: TreeSignature): VerificationResult;
+export declare function verifySignature(address: string, message: string, signatureHex: string, publicKeyHex: string): boolean;
+export declare function verifySignatureDetailed(address: string, message: string, signatureHex: string, publicKeyHex: string): VerificationResult;
+export declare function createChallenge(domain: string, nonce?: string): string;
+export declare function validateChallenge(challenge: string, options?: {
+    maxAgeMs?: number;
+    expectedDomain?: string;
+}): VerificationResult;

package/dist/verify.js

@@ -0,0 +1,162 @@
+import { sha3_256 } from '@noble/hashes/sha3';
+import { deserializeTreeSignature } from './treekey.js';
+import { scriptToAddress } from './derive.js';
+import { scriptFromWotsPk } from './script.js';
+import { getRootPublicKey } from './treekey.js';
+import { wotsVerifyDigest } from './wots.js';
+import { getParamSet } from './params.js';
+export function normalizeHex(hex) {
+    const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+    return stripped.toLowerCase();
+}
+export function hexToBytes(hex) {
+    const h = normalizeHex(hex);
+    if (h.length % 2 !== 0)
+        throw new Error('Invalid hex string: odd length');
+    const bytes = new Uint8Array(h.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+export function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+export function deriveAddressFromPublicKey(publicKeyHex) {
+    const pkBytes = hexToBytes(publicKeyHex);
+    if (pkBytes.length !== 32) {
+        throw new Error(`Public key must be 32 bytes (64 hex chars), got ${pkBytes.length} bytes`);
+    }
+    const script = scriptFromWotsPk(pkBytes);
+    return scriptToAddress(script);
+}
+export function verifyTreeSignatureDetailed(expectedPubkey, data, signature) {
+    const { proofs } = signature;
+    if (proofs.length === 0) {
+        return { valid: false, error: 'Signature contains no proofs' };
+    }
+    const paramSet = getParamSet();
+    for (let depth = 0; depth < proofs.length; depth++) {
+        const proof = proofs[depth];
+        const rootPubkey = getRootPublicKey(proof);
+        if (depth === 0) {
+            if (!timingSafeEqual(expectedPubkey, rootPubkey)) {
+                return {
+                    valid: false,
+                    error: 'Root public key does not match expected public key (wrong key or address)',
+                };
+            }
+        }
+        let signedData;
+        if (depth === proofs.length - 1) {
+            signedData = data;
+        }
+        else {
+            signedData = getRootPublicKey(proofs[depth + 1]);
+        }
+        if (!wotsVerifyDigest(proof.signature, signedData, proof.leafPubkey, paramSet)) {
+            return {
+                valid: false,
+                error: `WOTS signature verification failed at depth ${depth} (digest mismatch or corrupted signature)`,
+            };
+        }
+    }
+    return { valid: true };
+}
+export function verifySignature(address, message, signatureHex, publicKeyHex) {
+    const result = verifySignatureDetailed(address, message, signatureHex, publicKeyHex);
+    return result.valid;
+}
+export function verifySignatureDetailed(address, message, signatureHex, publicKeyHex) {
+    try {
+        const pkBytes = hexToBytes(publicKeyHex);
+        if (pkBytes.length !== 32) {
+            return {
+                valid: false,
+                error: `Public key must be 32 bytes (64 hex chars), got ${pkBytes.length} bytes`,
+            };
+        }
+        const derivedAddress = deriveAddressFromPublicKey(publicKeyHex);
+        if (derivedAddress.toLowerCase() !== address.toLowerCase()) {
+            return {
+                valid: false,
+                error: `Public key does not match claimed address. Expected ${address}, derived ${derivedAddress}`,
+            };
+        }
+        const sigBytes = hexToBytes(signatureHex);
+        let treeSignature;
+        try {
+            treeSignature = deserializeTreeSignature(sigBytes);
+        }
+        catch (e) {
+            return {
+                valid: false,
+                error: `Malformed signature: ${e.message}`,
+            };
+        }
+        const digest = sha3_256(new TextEncoder().encode(message));
+        return verifyTreeSignatureDetailed(pkBytes, digest, treeSignature);
+    }
+    catch (e) {
+        return {
+            valid: false,
+            error: `Verification error: ${e.message}`,
+        };
+    }
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a[i] ^ b[i];
+    }
+    return result === 0;
+}
+function cryptoRandomBytes(length) {
+    const buf = new Uint8Array(length);
+    if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues) {
+        globalThis.crypto.getRandomValues(buf);
+    }
+    else {
+        try {
+            const { randomFillSync } = require('crypto');
+            randomFillSync(buf);
+        }
+        catch {
+            throw new Error('No cryptographically secure RNG available');
+        }
+    }
+    return buf;
+}
+export function createChallenge(domain, nonce) {
+    const ts = Date.now();
+    const n = nonce || bytesToHex(sha3_256(new Uint8Array([...new TextEncoder().encode(`${domain}:${ts}:`), ...cryptoRandomBytes(16)]))).slice(0, 16);
+    return JSON.stringify({ domain, nonce: n, issuedAt: ts });
+}
+export function validateChallenge(challenge, options) {
+    try {
+        const parsed = JSON.parse(challenge);
+        const { domain, nonce, issuedAt } = parsed;
+        if (!domain || !nonce || !issuedAt) {
+            return { valid: false, error: 'Challenge missing required fields (domain, nonce, issuedAt)' };
+        }
+        if (options?.expectedDomain && domain !== options.expectedDomain) {
+            return { valid: false, error: `Domain mismatch: expected ${options.expectedDomain}, got ${domain}` };
+        }
+        const maxAge = options?.maxAgeMs ?? 5 * 60 * 1000;
+        const age = Date.now() - issuedAt;
+        if (age > maxAge) {
+            return { valid: false, error: `Challenge expired: ${Math.round(age / 1000)}s old (max ${Math.round(maxAge / 1000)}s)` };
+        }
+        if (age < 0) {
+            return { valid: false, error: 'Challenge issued in the future' };
+        }
+        return { valid: true };
+    }
+    catch {
+        return { valid: false, error: 'Invalid challenge format (not valid JSON)' };
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SDK Core Version Information
+ *
+ * CORE_BUILD_ID is used to detect bundle duplication issues where
+ * the extension might bundle two different copies of sdk-core,
+ * computing addresses with one copy and signing with another.
+ *
+ * If you see different CORE_BUILD_IDs logged from wallet creation
+ * vs signing modules, there's a bundling issue.
+ */
+export declare const CORE_BUILD_ID = "2026.02.05-v1";
+export declare const CORE_VERSION = "1.0.0";

package/dist/version.js

@@ -0,0 +1,12 @@
+/**
+ * SDK Core Version Information
+ *
+ * CORE_BUILD_ID is used to detect bundle duplication issues where
+ * the extension might bundle two different copies of sdk-core,
+ * computing addresses with one copy and signing with another.
+ *
+ * If you see different CORE_BUILD_IDs logged from wallet creation
+ * vs signing modules, there's a bundling issue.
+ */
+export const CORE_BUILD_ID = '2026.02.05-v1';
+export const CORE_VERSION = '1.0.0';

package/dist/wots.d.ts

@@ -0,0 +1,232 @@
+/**
+ * WOTS Implementation - BouncyCastle Compatible
+ *
+ * This implementation matches BouncyCastle's WinternitzOTSignature exactly,
+ * which is used by Minima's Winternitz.java class.
+ *
+ * Key differences from standard WOTS/WOTS+:
+ * - w=8 means 8 BITS per digit (not base-8), so each byte is one digit (0-255)
+ * - Stateful PRNG (GMSSRandom) for chain seed derivation, not stateless H(i||seed)
+ * - 34 total chains (32 message + 2 checksum), not 89
+ * - Each chain hashed up to 255 times (2^8 - 1)
+ *
+ * Source: org.bouncycastle.pqc.crypto.gmss.util.{WinternitzOTSignature, WinternitzOTSVerify, GMSSRandom}
+ */
+import { ParamSet } from "./params.js";
+import type { LoggerAdapter } from "./adapters/index.js";
+/**
+ * Enable WOTS debug logging with a custom logger
+ * Use this for parity testing to capture all intermediate values
+ *
+ * WARNING: Debug logging outputs sensitive cryptographic material including
+ * private key chains and seeds. NEVER enable in production builds.
+ * This is intended for development/testing parity verification only.
+ */
+export declare function setWotsLogger(logger: LoggerAdapter): void;
+/**
+ * Disable WOTS debug logging
+ */
+export declare function disableWotsLogger(): void;
+/**
+ * Check if WOTS debug logging is enabled
+ */
+export declare function isWotsDebugEnabled(): boolean;
+export declare const F: (x: Uint8Array) => Uint8Array<ArrayBufferLike>;
+export declare const hex: (u: Uint8Array) => string;
+export declare const fromHex: (h: string) => Uint8Array<ArrayBuffer>;
+export declare const concatBytes: (...arrs: Uint8Array[]) => Uint8Array<ArrayBuffer>;
+export declare const u16be: (n: number) => Uint8Array<ArrayBuffer>;
+export declare const u32be: (n: number) => Uint8Array<ArrayBuffer>;
+export declare function assert32(u: Uint8Array, label?: string): void;
+export declare const h: (x: Uint8Array) => Uint8Array<ArrayBufferLike>;
+/**
+ * GMSSRandom - BouncyCastle's stateful PRNG for WOTS chain seed derivation
+ *
+ * Algorithm from GMSSRandom.java:
+ *   rand = H(state)
+ *   state = state + rand + 1 (byte-wise addition with carry)
+ *   return rand
+ *
+ * The state is MUTATED in place after each call.
+ */
+export declare class GMSSRandom {
+    /**
+     * Generate next random value and update state
+     *
+     * @param state - 32-byte state array (MUTATED in place)
+     * @returns 32-byte random value
+     */
+    static nextSeed(state: Uint8Array): Uint8Array;
+    /**
+     * Add two byte arrays: a = a + b (little-endian, with carry)
+     * Matches GMSSRandom.addByteArrays()
+     */
+    private static addByteArrays;
+    /**
+     * Add one to byte array: a = a + 1 (little-endian, with carry)
+     * Matches GMSSRandom.addOne()
+     */
+    private static addOne;
+}
+/**
+ * getLog - Calculate ceil(log2(x))
+ *
+ * Matches WinternitzOTSignature.getLog():
+ *   int log = 1;
+ *   int i = 2;
+ *   while (i < intValue) { i <<= 1; log++; }
+ *   return log;
+ */
+export declare function getLog(intValue: number): number;
+/**
+ * Expand master seed into L private key chains using GMSSRandom
+ *
+ * Matches WinternitzOTSignature constructor:
+ *   byte[] dummy = new byte[mdsize];
+ *   System.arraycopy(seed0, 0, dummy, 0, dummy.length);
+ *   for (int i = 0; i < keysize; i++) {
+ *     privateKeyOTS[i] = gmssRandom.nextSeed(dummy);
+ *   }
+ */
+export declare function expandPrivateKey(seed: Uint8Array, ps?: ParamSet): Uint8Array[];
+/**
+ * Convert message hash to Winternitz digits with checksum
+ *
+ * For w=8 (8 bits per digit), since 8 % 8 == 0:
+ * - Each byte of the hash IS one digit (0-255)
+ * - messagesize = 32 digits
+ * - checksum = (messagesize << w) - sum = 8192 - sum
+ * - checksumsize = 14 bits, extracted as 2 digits
+ *
+ * Matches WinternitzOTSignature.getSignature() for w=8 case
+ */
+export declare function toWinternitzDigits(hash32: Uint8Array, ps?: ParamSet): {
+    digits: number[];
+    checksumDigits: number[];
+    total: number;
+};
+/**
+ * Decompose digest into base-w digits + checksum
+ * Returns flat array of all L digits
+ */
+export declare function baseWWithChecksum(msgHash: Uint8Array, paramSet?: ParamSet): number[];
+/**
+ * Hash a value k times
+ *
+ * Matches WinternitzOTSignature.hashPrivateKeyBlock():
+ * - If rounds < 1: return input unchanged
+ * - Otherwise: hash `rounds` times
+ */
+export declare function hashChain(x: Uint8Array, rounds: number): Uint8Array;
+export type WotsKeypair = {
+    seed: Uint8Array;
+    index: number;
+    pk: Uint8Array;
+};
+/**
+ * Derive unique seed for a specific key index
+ *
+ * DEPRECATED: Use deriveChainSeedJava for Java parity.
+ * This function is preserved for backward compatibility only.
+ *
+ * The correct derivation matching Minima's TreeKeyNode.java:
+ *   MiniData seed = Crypto.getInstance().hashAllObjects(new MiniNumber(i), zPrivateSeed);
+ *
+ * This old implementation used H(seed || u32be(i)) which is NOT Java compatible.
+ * @deprecated Use deriveChainSeedJava from javaStreamables.ts
+ */
+export declare function deriveIndexedSeed(seed: Uint8Array, keyIndex: number): Uint8Array;
+/**
+ * Derive WOTS public key digest from seed and key index
+ *
+ * The key index is mixed into the seed first (deriveIndexedSeed),
+ * then expanded using GMSSRandom to get unique chain seeds.
+ *
+ * Matches WinternitzOTSignature.getPublicKey():
+ *   int rounds = (1 << w) - 1;  // 255 for w=8
+ *   for (int i = 0; i < keysize; i++) {
+ *     hashPrivateKeyBlock(i, rounds, buf, pos);
+ *   }
+ *   return H(buf);
+ */
+export declare function derivePKdigest(seed: Uint8Array, i: number, ps?: ParamSet): Uint8Array;
+/**
+ * Derive full WOTS public key (L × 32 bytes) without final hash
+ *
+ * Returns the concatenation of all chain tops BEFORE hashing.
+ * Required by Minima's SignatureProof which expects the full public key.
+ */
+export declare function deriveFullPublicKey(seed: Uint8Array, i: number, ps?: ParamSet): Uint8Array;
+export declare function wotsKeypairFromSeed(seed: Uint8Array, index: number, paramSet?: ParamSet): WotsKeypair;
+export type WotsSignature = {
+    index: number;
+    w: number;
+    sig: Uint8Array[];
+};
+/**
+ * Sign a message using WOTS
+ *
+ * Matches Java's WinternitzOTSignature.getSignature():
+ * 1. Hash the message internally: hashedMsg = SHA3-256(message)
+ * 2. For each digit d[i]: sig[i] = hash(privateKey[i], d[i] times)
+ *
+ * IMPORTANT: This function hashes the message internally to match Java/BouncyCastle.
+ * Callers pass RAW 32-byte data (tx digest, child root), NOT pre-hashed!
+ *
+ * @param seed - 32-byte master seed
+ * @param i - Key index
+ * @param message - Raw 32-byte message (will be hashed internally)
+ * @param ps - WOTS parameter set (default: minima)
+ * @returns Flat signature (L × 32 = 1088 bytes)
+ */
+export declare function wotsSign(seed: Uint8Array, i: number, message: Uint8Array, ps?: ParamSet): Uint8Array;
+/**
+ * Legacy wrapper returning structured signature
+ */
+export declare function wotsSignLegacy(msgHash: Uint8Array, seed: Uint8Array, index: number, paramSet?: ParamSet): WotsSignature;
+/**
+ * Recover public key from signature
+ *
+ * Matches WinternitzOTSVerify.Verify():
+ *   1. Hash the message: hashedMsg = SHA3-256(message)
+ *   2. for each digit d[i]:
+ *        top[i] = hash(sig[i], (255 - d[i]) times)
+ *   3. return H(concat(tops))
+ *
+ * CRITICAL: This function hashes the message internally to match Java/BouncyCastle
+ * Winternitz behavior. Both wotsSign and wotsPkFromSig hash internally for parity.
+ */
+export declare function wotsPkFromSig(message: Uint8Array, signature: WotsSignature, paramSet?: ParamSet): Uint8Array;
+/**
+ * Verify WOTS signature against a FULL 1088-byte public key
+ *
+ * Matches Java's Winternitz.verify():
+ * 1. Hash the message internally: hashedMsg = SHA3-256(message)
+ * 2. Recover FULL public key from signature using hashedMsg (1088 bytes)
+ * 3. Compare FULL reconstructed key to expected FULL public key
+ *
+ * CRITICAL: Java's Winternitz.verify() compares the FULL 1088-byte reconstructed
+ * public key against the FULL 1088-byte stored public key, NOT a 32-byte digest!
+ *
+ * IMPORTANT: This function hashes the message internally to match Java/BouncyCastle.
+ * Callers pass RAW 32-byte data (tx digest, child root), NOT pre-hashed!
+ *
+ * @param sig - The 1088-byte WOTS signature
+ * @param message - Raw 32-byte message (will be hashed internally)
+ * @param pkFull - The FULL 1088-byte WOTS public key (L=34 × 32 bytes)
+ * @param ps - WOTS parameter set (default: minima)
+ */
+export declare function wotsVerify(sig: Uint8Array, message: Uint8Array, pkFull: Uint8Array, ps?: ParamSet): boolean;
+/**
+ * Legacy verify function that accepts a 32-byte digest
+ * @deprecated Use wotsVerify with full 1088-byte public key instead
+ */
+export declare function wotsVerifyDigest(sig: Uint8Array, message: Uint8Array, pkDigest: Uint8Array, ps?: ParamSet): boolean;
+/**
+ * Generate WOTS public key from seed (convenience wrapper)
+ */
+export declare function wotsPublicKeyFromSeed(seed: Uint8Array, index?: number, paramSet?: ParamSet): Uint8Array;
+/**
+ * @deprecated Use expandPrivateKey instead
+ */
+export declare function prfChainSeed(seed: Uint8Array, i: number, j: number, _paramSet: ParamSet): Uint8Array;