@totemsdk/core 1.2.6 → 1.2.7

package/dist/cjs/adapters/index.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * @module @totemsdk/core/adapters
+ * Platform-agnostic adapter interfaces for SDK portability
+ *
+ * These interfaces enable the SDK to work across multiple platforms:
+ * - Browser (Chrome Extensions, web apps)
+ * - Node.js (server-side, CLI tools)
+ * - React Native (mobile apps) - follow-up
+ *
+ * Each platform provides its own implementation of these adapters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopLifecycleAdapter = exports.DefaultTimerAdapter = exports.NoopMetrics = exports.ConsoleLogger = exports.NoopLogger = exports.WebSocketReadyState = void 0;
+exports.createCancellationToken = createCancellationToken;
+exports.createAdapterRegistry = createAdapterRegistry;
+exports.WebSocketReadyState = {
+    CONNECTING: 0,
+    OPEN: 1,
+    CLOSING: 2,
+    CLOSED: 3,
+};
+function createCancellationToken() {
+    let cancelled = false;
+    const callbacks = new Set();
+    const token = {
+        get cancelled() { return cancelled; },
+        onCancel(callback) {
+            if (cancelled) {
+                callback();
+                return () => { };
+            }
+            callbacks.add(callback);
+            return () => callbacks.delete(callback);
+        }
+    };
+    return {
+        token,
+        cancel() {
+            if (!cancelled) {
+                cancelled = true;
+                callbacks.forEach(cb => cb());
+                callbacks.clear();
+            }
+        }
+    };
+}
+function createAdapterRegistry(adapters) {
+    const required = [
+        'storage', 'auth', 'websocket', 'http', 'config', 'logger', 'timer', 'crypto'
+    ];
+    for (const key of required) {
+        if (!adapters[key]) {
+            throw new Error(`Missing required adapter: ${key}`);
+        }
+    }
+    return adapters;
+}
+class NoopLogger {
+    debug(_message, ..._args) { }
+    info(_message, ..._args) { }
+    warn(_message, ..._args) { }
+    error(_message, ..._args) { }
+}
+exports.NoopLogger = NoopLogger;
+class ConsoleLogger {
+    prefix;
+    constructor(prefix = '[SDK]') {
+        this.prefix = prefix;
+    }
+    debug(message, ...args) {
+        console.debug(`${this.prefix} ${message}`, ...args);
+    }
+    info(message, ...args) {
+        console.info(`${this.prefix} ${message}`, ...args);
+    }
+    warn(message, ...args) {
+        console.warn(`${this.prefix} ${message}`, ...args);
+    }
+    error(message, ...args) {
+        console.error(`${this.prefix} ${message}`, ...args);
+    }
+}
+exports.ConsoleLogger = ConsoleLogger;
+class NoopMetrics {
+    increment(_name, _value, _tags) { }
+    gauge(_name, _value, _tags) { }
+    timing(_name, _durationMs, _tags) { }
+    histogram(_name, _value, _tags) { }
+}
+exports.NoopMetrics = NoopMetrics;
+class DefaultTimerAdapter {
+    setTimeout(callback, ms) {
+        return setTimeout(callback, ms);
+    }
+    setInterval(callback, ms) {
+        return setInterval(callback, ms);
+    }
+    clearTimeout(handle) {
+        clearTimeout(handle);
+    }
+    clearInterval(handle) {
+        clearInterval(handle);
+    }
+    now() {
+        return Date.now();
+    }
+}
+exports.DefaultTimerAdapter = DefaultTimerAdapter;
+class NoopLifecycleAdapter {
+    onSuspend(_callback) {
+        return () => { };
+    }
+    onResume(_callback) {
+        return () => { };
+    }
+}
+exports.NoopLifecycleAdapter = NoopLifecycleAdapter;

package/dist/cjs/adapters/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @module @totemsdk/core/adapters/types
+ * Shared type definitions for SDK modules
+ */
+export interface WotsIndices {
+    addressIndex: number;
+    l1: number;
+    l2: number;
+}
+export type LeaseStatus = 'pending' | 'active' | 'expired' | 'finalized' | 'cancelled';
+export interface StoredLease {
+    leaseId: string;
+    leaseToken: string;
+    treeId?: string;
+    indices: WotsIndices;
+    expiresAt: number;
+    status: LeaseStatus;
+    createdAt: number;
+    txId?: string;
+    leaseTTL: number;
+}
+export interface WatermarkState {
+    next_addressIndex: number;
+    next_l1: number;
+    next_l2: number;
+    usedIndices: Array<[number, number, number]>;
+    lastSyncTimestamp?: number;
+    serverWatermark?: WotsIndices;
+}
+export interface SyncResult {
+    updated: boolean;
+    drift: number;
+    hasConflict: boolean;
+}
+export interface LeaseExpiryEvent {
+    leaseId: string;
+    expiresAt: number;
+    remainingMs: number;
+}
+export type LeaseExpiryCallback = (event: LeaseExpiryEvent) => void;
+export interface TransactionPrepareParams {
+    txId: string;
+    rootPublicKey: string;
+    to: string;
+    amount: string;
+    tokenId?: string;
+    burn?: string | null;
+    digestL2?: string | null;
+    digestL3?: string | null;
+    ttlMs?: number;
+}
+export interface PreparedTransaction {
+    leaseToken: string;
+    lease: WotsIndices;
+    txId: string;
+    digestTx?: string | null;
+}
+export interface SignedTransaction {
+    txId: string;
+    signedHex: string;
+    leaseToken: string;
+}
+export interface FinalizedTransaction {
+    txId: string;
+    status: 'success' | 'failed';
+    blockHeight?: number;
+    confirmations?: number;
+    error?: string;
+}
+export type TransactionStatus = 'preparing' | 'signing' | 'submitting' | 'pending' | 'confirmed' | 'failed';
+export interface TransactionState {
+    txId: string;
+    status: TransactionStatus;
+    lease?: StoredLease;
+    signedHex?: string;
+    blockHeight?: number;
+    confirmations?: number;
+    error?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface BalanceSnapshot {
+    address: string;
+    confirmed: string;
+    unconfirmed: string;
+    total: string;
+    tokenId: string;
+    timestamp: number;
+}
+export interface BalanceUpdate {
+    type: 'snapshot' | 'delta';
+    address: string;
+    tokenId: string;
+    confirmed?: string;
+    unconfirmed?: string;
+    total?: string;
+    delta?: string;
+    timestamp: number;
+}
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+export interface ConnectionState {
+    status: ConnectionStatus;
+    lastConnectedAt?: number;
+    lastDisconnectedAt?: number;
+    reconnectAttempts: number;
+    error?: string;
+}
+export interface QuotaInfo {
+    used: number;
+    limit: number;
+    remaining: number;
+    resetsAt: number;
+    windowMs: number;
+}
+export interface RpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export declare class SdkError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: string, cause?: Error | undefined);
+}
+export declare class StorageError extends SdkError {
+    constructor(message: string, cause?: Error);
+}
+export declare class NetworkError extends SdkError {
+    constructor(message: string, cause?: Error);
+}
+export declare class AuthenticationError extends SdkError {
+    constructor(message: string, cause?: Error);
+}
+export declare class LeaseError extends SdkError {
+    constructor(message: string, cause?: Error);
+}
+export declare class TransactionError extends SdkError {
+    constructor(message: string, cause?: Error);
+}
+export declare class QuotaExceededError extends SdkError {
+    readonly quotaInfo: QuotaInfo;
+    constructor(message: string, quotaInfo: QuotaInfo, cause?: Error);
+}
+export type EventUnsubscribe = () => void;
+export interface EventEmitter<Events extends Record<string, unknown>> {
+    on<K extends keyof Events>(event: K, listener: (data: Events[K]) => void): EventUnsubscribe;
+    off<K extends keyof Events>(event: K, listener: (data: Events[K]) => void): void;
+    emit<K extends keyof Events>(event: K, data: Events[K]): void;
+}
+export declare function createEventEmitter<Events extends Record<string, unknown>>(): EventEmitter<Events>;

package/dist/cjs/adapters/types.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * @module @totemsdk/core/adapters/types
+ * Shared type definitions for SDK modules
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExceededError = exports.TransactionError = exports.LeaseError = exports.AuthenticationError = exports.NetworkError = exports.StorageError = exports.SdkError = void 0;
+exports.createEventEmitter = createEventEmitter;
+class SdkError extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'SdkError';
+    }
+}
+exports.SdkError = SdkError;
+class StorageError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'STORAGE_ERROR', cause);
+        this.name = 'StorageError';
+    }
+}
+exports.StorageError = StorageError;
+class NetworkError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'NETWORK_ERROR', cause);
+        this.name = 'NetworkError';
+    }
+}
+exports.NetworkError = NetworkError;
+class AuthenticationError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'AUTH_ERROR', cause);
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class LeaseError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'LEASE_ERROR', cause);
+        this.name = 'LeaseError';
+    }
+}
+exports.LeaseError = LeaseError;
+class TransactionError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'TRANSACTION_ERROR', cause);
+        this.name = 'TransactionError';
+    }
+}
+exports.TransactionError = TransactionError;
+class QuotaExceededError extends SdkError {
+    quotaInfo;
+    constructor(message, quotaInfo, cause) {
+        super(message, 'QUOTA_EXCEEDED', cause);
+        this.quotaInfo = quotaInfo;
+        this.name = 'QuotaExceededError';
+    }
+}
+exports.QuotaExceededError = QuotaExceededError;
+function createEventEmitter() {
+    const listeners = new Map();
+    return {
+        on(event, listener) {
+            if (!listeners.has(event)) {
+                listeners.set(event, new Set());
+            }
+            listeners.get(event).add(listener);
+            return () => listeners.get(event)?.delete(listener);
+        },
+        off(event, listener) {
+            listeners.get(event)?.delete(listener);
+        },
+        emit(event, data) {
+            listeners.get(event)?.forEach(listener => listener(data));
+        }
+    };
+}

package/dist/cjs/binio.d.ts

@@ -0,0 +1,9 @@
+export declare class BinWriter {
+    #private;
+    get bytes(): Uint8Array;
+    writeU8(n: number): void;
+    writeU16(n: number): void;
+    writeU32(n: number): void;
+    writeU64(bi: bigint): void;
+    writeBytes(b: Uint8Array): void;
+}

package/dist/cjs/binio.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BinWriter = void 0;
+class BinWriter {
+    #buf = [];
+    get bytes() { return new Uint8Array(this.#buf); }
+    writeU8(n) { this.#buf.push(n & 0xff); }
+    writeU16(n) { this.#buf.push((n >>> 8) & 0xff, n & 0xff); } // big-endian
+    writeU32(n) {
+        this.#buf.push((n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff);
+    }
+    writeU64(bi) {
+        // big-endian 8 bytes
+        const out = new Uint8Array(8);
+        let x = bi;
+        for (let i = 7; i >= 0; i--) {
+            out[i] = Number(x & 0xffn);
+            x >>= 8n;
+        }
+        this.writeBytes(out);
+    }
+    writeBytes(b) { for (const x of b)
+        this.#buf.push(x); }
+}
+exports.BinWriter = BinWriter;

package/dist/cjs/bip39.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Minima-Compatible BIP39 Seed Phrase Handling
+ *
+ * IMPORTANT: This is NOT standard BIP39!
+ * Minima uses the BIP39 English word list for human-friendly phrases,
+ * but does NOT use PBKDF2, passphrase salt, or checksum validation.
+ *
+ * Seed derivation is simply: SHA3-256(phrase_bytes)
+ *
+ * Matches BIP39.java behavior exactly:
+ * - cleanSeedPhrase(): Normalizes input with prefix matching
+ * - convertStringToSeed(): Hashes phrase bytes with SHA3-256
+ */
+/**
+ * Official BIP39 English word list (2048 words)
+ * From https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt
+ */
+export declare const WORD_LIST: readonly string[];
+/**
+ * Clean and normalize a seed phrase matching Minima's BIP39.cleanSeedPhrase() exactly
+ *
+ * From BIP39.java:
+ * - Split by whitespace
+ * - For each token: lowercase; length >= 3 required
+ * - If token length < 4: must match full word in wordlist
+ * - Else: accept FIRST word in wordlist that startsWith(token)
+ * - Join with single spaces, trim, then convert to UPPERCASE
+ *
+ * @param seedPhrase - Raw user input (may be abbreviated, mixed case)
+ * @returns Canonical uppercase phrase with full words from BIP39 list
+ * @throws Error if any word cannot be matched
+ */
+export declare function cleanSeedPhrase(seedPhrase: string): string;
+/**
+ * Validate that a phrase contains valid BIP39 words
+ * Does NOT check checksum (Minima doesn't use checksums)
+ *
+ * @param phrase - Space-separated words (any case)
+ * @returns true if all words are valid BIP39 words
+ */
+export declare function validatePhrase(phrase: string): boolean;
+/**
+ * Convert a seed phrase to a 32-byte seed matching Minima's BIP39.convertStringToSeed()
+ *
+ * IMPORTANT: This is NOT standard BIP39!
+ * Minima simply hashes the phrase bytes with SHA3-256.
+ * No PBKDF2, no passphrase salt, no "mnemonic" prefix.
+ *
+ * From BIP39.java convertStringToSeed():
+ *   MiniString phrase = new MiniString(zPhrase);
+ *   return new MiniData(Crypto.getInstance().hashData(phrase.getData()));
+ *
+ * @param phrase - Canonical phrase (should be cleaned first with cleanSeedPhrase)
+ * @returns 32-byte SHA3-256 seed
+ */
+export declare function convertStringToSeed(phrase: string): Uint8Array;
+/**
+ * Convert word array to seed matching Minima's BIP39.convertWordListToSeed()
+ *
+ * From BIP39.java:
+ *   String allwords = convertWordListToString(zWords);
+ *   MiniString ministr = new MiniString(allwords);
+ *   MiniData hash = new MiniData(Crypto.getInstance().hashData(ministr.getData()));
+ *
+ * @param words - Array of BIP39 words
+ * @returns 32-byte SHA3-256 seed
+ */
+export declare function convertWordListToSeed(words: string[]): Uint8Array;
+/**
+ * Full pipeline: raw user input → 32-byte seed
+ *
+ * 1. cleanSeedPhrase() - normalize with prefix matching, output uppercase
+ * 2. convertStringToSeed() - SHA3-256 hash of phrase bytes
+ *
+ * @param rawPhrase - User's input (may be abbreviated, mixed case)
+ * @returns 32-byte seed for TreeKey
+ * @throws Error if phrase contains invalid words
+ */
+export declare function phraseToSeed(rawPhrase: string): Uint8Array;
+/**
+ * Generate a new random 24-word seed phrase
+ * Uses crypto.getRandomValues for secure randomness
+ *
+ * @returns Array of 24 random BIP39 words (lowercase)
+ */
+export declare function generateWordList(): string[];
+/**
+ * Generate a new random seed phrase as a string
+ * @returns 24-word phrase in UPPERCASE (canonical form)
+ */
+export declare function generateSeedPhrase(): string;