@totemsdk/core 1.0.0

package/dist/adapters/index.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @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.
+ */
+export interface StorageAdapter {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+    has(key: string): Promise<boolean>;
+}
+export interface AuthTokenProvider {
+    getToken(): Promise<string | null>;
+    setToken(token: string): Promise<void>;
+    clearToken(): Promise<void>;
+    onTokenChange(callback: (token: string | null) => void): () => void;
+    isAuthenticated(): Promise<boolean>;
+}
+export type BinaryData = Uint8Array | ArrayBuffer;
+export interface WebSocketFactoryOptions {
+    pingIntervalMs?: number;
+    pongTimeoutMs?: number;
+    maxPayloadBytes?: number;
+}
+export interface WebSocketOpenEvent {
+    type: 'open';
+}
+export interface WebSocketCloseEvent {
+    type: 'close';
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+export interface WebSocketMessageEvent {
+    type: 'message';
+    data: string | BinaryData;
+}
+export interface WebSocketErrorEvent {
+    type: 'error';
+    message?: string;
+    error?: Error;
+}
+export type WebSocketEventMap = {
+    open: WebSocketOpenEvent;
+    close: WebSocketCloseEvent;
+    message: WebSocketMessageEvent;
+    error: WebSocketErrorEvent;
+};
+export interface WebSocketFactory {
+    create(url: string, protocols?: string[], options?: WebSocketFactoryOptions): WebSocketClient;
+    dispose(): void;
+}
+export interface WebSocketClient {
+    readonly readyState: number;
+    readonly url: string;
+    send(data: string | BinaryData): void;
+    close(code?: number, reason?: string): void;
+    terminate(): void;
+    addEventListener<K extends keyof WebSocketEventMap>(event: K, listener: (ev: WebSocketEventMap[K]) => void): void;
+    removeEventListener<K extends keyof WebSocketEventMap>(event: K, listener: (ev: WebSocketEventMap[K]) => void): void;
+    removeAllListeners(): void;
+    onopen: ((ev: WebSocketOpenEvent) => void) | null;
+    onclose: ((ev: WebSocketCloseEvent) => void) | null;
+    onmessage: ((ev: WebSocketMessageEvent) => void) | null;
+    onerror: ((ev: WebSocketErrorEvent) => void) | null;
+}
+export declare const WebSocketReadyState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+export interface CancellationToken {
+    readonly cancelled: boolean;
+    onCancel(callback: () => void): () => void;
+}
+export interface CancellationTokenSource {
+    readonly token: CancellationToken;
+    cancel(): void;
+}
+export declare function createCancellationToken(): CancellationTokenSource;
+export interface HttpClient {
+    get<T>(url: string, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
+    post<T>(url: string, body?: unknown, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
+    put<T>(url: string, body?: unknown, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
+    delete<T>(url: string, options?: HttpRequestOptions): Promise<HttpResponse<T>>;
+}
+export interface HttpRequestOptions {
+    headers?: Record<string, string>;
+    timeout?: number;
+    cancellationToken?: CancellationToken;
+}
+export interface HttpResponse<T> {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    data: T;
+}
+export interface ConfigProvider {
+    get<T>(key: string): T | undefined;
+    get<T>(key: string, defaultValue: T): T;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    getAll(): Record<string, unknown>;
+    readonly apiUrl: string;
+    readonly wsUrl: string;
+    readonly network: 'mainnet' | 'testnet' | 'devnet';
+    readonly apiKey?: string;
+}
+export interface LoggerAdapter {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+export interface MetricsAdapter {
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    timing(name: string, durationMs: number, tags?: Record<string, string>): void;
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+}
+export interface TimerAdapter {
+    setTimeout(callback: () => void, ms: number): TimerHandle;
+    setInterval(callback: () => void, ms: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+    clearInterval(handle: TimerHandle): void;
+    now(): number;
+}
+export type TimerHandle = ReturnType<typeof setTimeout>;
+export interface CryptoAdapter {
+    randomBytes(length: number): Uint8Array;
+    sha256(data: Uint8Array): Uint8Array;
+    sha256Async(data: Uint8Array): Promise<Uint8Array>;
+}
+export interface AdapterRegistry {
+    storage: StorageAdapter;
+    auth: AuthTokenProvider;
+    websocket: WebSocketFactory;
+    http: HttpClient;
+    config: ConfigProvider;
+    logger: LoggerAdapter;
+    metrics?: MetricsAdapter;
+    timer: TimerAdapter;
+    crypto: CryptoAdapter;
+}
+export declare function createAdapterRegistry(adapters: Partial<AdapterRegistry>): AdapterRegistry;
+export declare class NoopLogger implements LoggerAdapter {
+    debug(_message: string, ..._args: unknown[]): void;
+    info(_message: string, ..._args: unknown[]): void;
+    warn(_message: string, ..._args: unknown[]): void;
+    error(_message: string, ..._args: unknown[]): void;
+}
+export declare class ConsoleLogger implements LoggerAdapter {
+    private prefix;
+    constructor(prefix?: string);
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+export declare class NoopMetrics implements MetricsAdapter {
+    increment(_name: string, _value?: number, _tags?: Record<string, string>): void;
+    gauge(_name: string, _value: number, _tags?: Record<string, string>): void;
+    timing(_name: string, _durationMs: number, _tags?: Record<string, string>): void;
+    histogram(_name: string, _value: number, _tags?: Record<string, string>): void;
+}
+export declare class DefaultTimerAdapter implements TimerAdapter {
+    setTimeout(callback: () => void, ms: number): TimerHandle;
+    setInterval(callback: () => void, ms: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+    clearInterval(handle: TimerHandle): void;
+    now(): number;
+}
+export interface LifecycleAdapter {
+    onSuspend(callback: () => void): () => void;
+    onResume?(callback: () => void): () => void;
+}
+export declare class NoopLifecycleAdapter implements LifecycleAdapter {
+    onSuspend(_callback: () => void): () => void;
+    onResume(_callback: () => void): () => void;
+}

package/dist/adapters/index.js

@@ -0,0 +1,107 @@
+/**
+ * @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.
+ */
+export const WebSocketReadyState = {
+    CONNECTING: 0,
+    OPEN: 1,
+    CLOSING: 2,
+    CLOSED: 3,
+};
+export 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();
+            }
+        }
+    };
+}
+export 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;
+}
+export class NoopLogger {
+    debug(_message, ..._args) { }
+    info(_message, ..._args) { }
+    warn(_message, ..._args) { }
+    error(_message, ..._args) { }
+}
+export class ConsoleLogger {
+    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);
+    }
+}
+export class NoopMetrics {
+    increment(_name, _value, _tags) { }
+    gauge(_name, _value, _tags) { }
+    timing(_name, _durationMs, _tags) { }
+    histogram(_name, _value, _tags) { }
+}
+export 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();
+    }
+}
+export class NoopLifecycleAdapter {
+    onSuspend(_callback) {
+        return () => { };
+    }
+    onResume(_callback) {
+        return () => { };
+    }
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @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;
+    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/adapters/types.js

@@ -0,0 +1,67 @@
+/**
+ * @module @totemsdk/core/adapters/types
+ * Shared type definitions for SDK modules
+ */
+export class SdkError extends Error {
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'SdkError';
+    }
+}
+export class StorageError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'STORAGE_ERROR', cause);
+        this.name = 'StorageError';
+    }
+}
+export class NetworkError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'NETWORK_ERROR', cause);
+        this.name = 'NetworkError';
+    }
+}
+export class AuthenticationError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'AUTH_ERROR', cause);
+        this.name = 'AuthenticationError';
+    }
+}
+export class LeaseError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'LEASE_ERROR', cause);
+        this.name = 'LeaseError';
+    }
+}
+export class TransactionError extends SdkError {
+    constructor(message, cause) {
+        super(message, 'TRANSACTION_ERROR', cause);
+        this.name = 'TransactionError';
+    }
+}
+export class QuotaExceededError extends SdkError {
+    constructor(message, quotaInfo, cause) {
+        super(message, 'QUOTA_EXCEEDED', cause);
+        this.quotaInfo = quotaInfo;
+        this.name = 'QuotaExceededError';
+    }
+}
+export 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/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/binio.js

@@ -0,0 +1,30 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _BinWriter_buf;
+export class BinWriter {
+    constructor() {
+        _BinWriter_buf.set(this, []);
+    }
+    get bytes() { return new Uint8Array(__classPrivateFieldGet(this, _BinWriter_buf, "f")); }
+    writeU8(n) { __classPrivateFieldGet(this, _BinWriter_buf, "f").push(n & 0xff); }
+    writeU16(n) { __classPrivateFieldGet(this, _BinWriter_buf, "f").push((n >>> 8) & 0xff, n & 0xff); } // big-endian
+    writeU32(n) {
+        __classPrivateFieldGet(this, _BinWriter_buf, "f").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)
+        __classPrivateFieldGet(this, _BinWriter_buf, "f").push(x); }
+}
+_BinWriter_buf = new WeakMap();

package/dist/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;