@totemsdk/core 1.0.0

package/src/adapters/index.ts

@@ -0,0 +1,301 @@
+/**
+ * @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 const WebSocketReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const;
+
+export interface CancellationToken {
+  readonly cancelled: boolean;
+  onCancel(callback: () => void): () => void;
+}
+
+export interface CancellationTokenSource {
+  readonly token: CancellationToken;
+  cancel(): void;
+}
+
+export function createCancellationToken(): CancellationTokenSource {
+  let cancelled = false;
+  const callbacks = new Set<() => void>();
+  
+  const token: CancellationToken = {
+    get cancelled() { return cancelled; },
+    onCancel(callback: () => void): () => void {
+      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 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 function createAdapterRegistry(adapters: Partial<AdapterRegistry>): AdapterRegistry {
+  const required: (keyof AdapterRegistry)[] = [
+    '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 as AdapterRegistry;
+}
+
+export 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 class ConsoleLogger implements LoggerAdapter {
+  constructor(private prefix: string = '[SDK]') {}
+  
+  debug(message: string, ...args: unknown[]): void {
+    console.debug(`${this.prefix} ${message}`, ...args);
+  }
+  
+  info(message: string, ...args: unknown[]): void {
+    console.info(`${this.prefix} ${message}`, ...args);
+  }
+  
+  warn(message: string, ...args: unknown[]): void {
+    console.warn(`${this.prefix} ${message}`, ...args);
+  }
+  
+  error(message: string, ...args: unknown[]): void {
+    console.error(`${this.prefix} ${message}`, ...args);
+  }
+}
+
+export 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 class DefaultTimerAdapter implements TimerAdapter {
+  setTimeout(callback: () => void, ms: number): TimerHandle {
+    return setTimeout(callback, ms);
+  }
+  
+  setInterval(callback: () => void, ms: number): TimerHandle {
+    return setInterval(callback, ms);
+  }
+  
+  clearTimeout(handle: TimerHandle): void {
+    clearTimeout(handle);
+  }
+  
+  clearInterval(handle: TimerHandle): void {
+    clearInterval(handle);
+  }
+  
+  now(): number {
+    return Date.now();
+  }
+}
+
+export interface LifecycleAdapter {
+  onSuspend(callback: () => void): () => void;
+  onResume?(callback: () => void): () => void;
+}
+
+export class NoopLifecycleAdapter implements LifecycleAdapter {
+  onSuspend(_callback: () => void): () => void {
+    return () => {};
+  }
+  onResume(_callback: () => void): () => void {
+    return () => {};
+  }
+}

package/src/adapters/types.ts

@@ -0,0 +1,235 @@
+/**
+ * @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 class SdkError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'SdkError';
+  }
+}
+
+export class StorageError extends SdkError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'STORAGE_ERROR', cause);
+    this.name = 'StorageError';
+  }
+}
+
+export class NetworkError extends SdkError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'NETWORK_ERROR', cause);
+    this.name = 'NetworkError';
+  }
+}
+
+export class AuthenticationError extends SdkError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'AUTH_ERROR', cause);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class LeaseError extends SdkError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'LEASE_ERROR', cause);
+    this.name = 'LeaseError';
+  }
+}
+
+export class TransactionError extends SdkError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'TRANSACTION_ERROR', cause);
+    this.name = 'TransactionError';
+  }
+}
+
+export class QuotaExceededError extends SdkError {
+  constructor(
+    message: string,
+    public readonly quotaInfo: QuotaInfo,
+    cause?: Error
+  ) {
+    super(message, 'QUOTA_EXCEEDED', cause);
+    this.name = 'QuotaExceededError';
+  }
+}
+
+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 function createEventEmitter<Events extends Record<string, unknown>>(): EventEmitter<Events> {
+  const listeners = new Map<keyof Events, Set<(data: unknown) => void>>();
+  
+  return {
+    on<K extends keyof Events>(event: K, listener: (data: Events[K]) => void): EventUnsubscribe {
+      if (!listeners.has(event)) {
+        listeners.set(event, new Set());
+      }
+      listeners.get(event)!.add(listener as (data: unknown) => void);
+      return () => listeners.get(event)?.delete(listener as (data: unknown) => void);
+    },
+    
+    off<K extends keyof Events>(event: K, listener: (data: Events[K]) => void): void {
+      listeners.get(event)?.delete(listener as (data: unknown) => void);
+    },
+    
+    emit<K extends keyof Events>(event: K, data: Events[K]): void {
+      listeners.get(event)?.forEach(listener => listener(data));
+    }
+  };
+}

package/src/addr.oracle.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import { scriptToAddress } from "./derive";
+import { decodeMx } from "../../base32/src/minima32";
+import { bytesToHex } from "@noble/hashes/utils";
+
+describe("Script → Mx (Minima oracles)", () => {
+  it("RETURN TRUE", () => {
+    const mx = scriptToAddress("RETURN TRUE");
+    expect(mx).toBe("MxG082Z5AW0TACM86D3R2WT4Z1PKJKYGWRKDGM2DU30RB43EAVA8HBQURHCQE9V");
+    // payload should equal oracle root
+    expect(bytesToHex(decodeMx(mx)).toUpperCase()).toBe(
+      "582AA40EA996419A3D8A5D26039A4E9584B746C2C26F860DAC8372BEA4457AF6"
+    );
+  });
+
+  it("LET x 1 RETURN x == 1", () => {
+    const mx = scriptToAddress("LET x 1 RETURN x == 1");
+    expect(mx).toBe("MxG085JV8JAT8VVQGR7Z8UVVQQYZ5TUEMN4Y4HU98T9SU8CVRU5Y5NRWFVU5MEF");
+  });
+
+  it("RETURN SIGNEDBY(0xFFFF)", () => {
+    const mx = scriptToAddress("RETURN SIGNEDBY(0xFFFF)");
+    expect(mx).toBe("MxG0835THZEDNNJHWU8S5AM61FGCZRRV3BB1RQN371SR4S6J0EWA2SUWYS7MZVQ");
+  });
+});

package/src/address.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { makeMinimaAddress, convertMinimaAddress } from "./index";
+
+describe("Address Tests (matching Java AddressTests)", () => {
+  it("testMakeMinimaAddress - should roundtrip various lengths", () => {
+    // Test cases from Java AddressTests.testMakeMinimaAddress()
+    const testCases = [
+      "0xFFFF",
+      "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",  // 19 bytes (38 hex chars)
+      "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",  // 66 bytes (132 hex chars)
+      "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",  // 34 bytes
+      "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",  // 20 bytes
+      "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"  // 38 bytes
+    ];
+
+    for (const hexInput of testCases) {
+      console.log(`Testing hex length ${(hexInput.length - 2) / 2} bytes`);
+      
+      // Make Minima address
+      const mxAddress = makeMinimaAddress(hexInput);
+      console.log(`  Input:  ${hexInput.slice(0, 20)}...`);
+      console.log(`  Output: ${mxAddress}`);
+      
+      // Convert back
+      const converted = convertMinimaAddress(mxAddress);
+      
+      // Should be equal (case-insensitive comparison since we uppercase on output)
+      expect(converted.toUpperCase()).toBe(hexInput.toUpperCase());
+      console.log(`  ✓ Roundtrip successful\n`);
+    }
+  });
+
+  it("should handle MiniData constructor test cases", () => {
+    // Test cases from the Java constructor tests
+    const testCases = [
+      "0xF0F0",
+      "0xFFFF",
+      "0xFFF0F0"
+    ];
+
+    for (const hexInput of testCases) {
+      const mxAddress = makeMinimaAddress(hexInput);
+      const converted = convertMinimaAddress(mxAddress);
+      expect(converted.toUpperCase()).toBe(hexInput.toUpperCase());
+    }
+  });
+
+  it("should handle empty MiniData", () => {
+    // Java test includes new MiniData() which is empty
+    const empty = "0x";
+    const mxAddress = makeMinimaAddress(empty);
+    const converted = convertMinimaAddress(mxAddress);
+    expect(converted).toBe("0X");
+  });
+});

package/src/binio.ts

@@ -0,0 +1,21 @@
+export class BinWriter {
+  #buf: number[] = [];
+  get bytes(): Uint8Array { return new Uint8Array(this.#buf); }
+
+  writeU8(n: number)  { this.#buf.push(n & 0xff); }
+  writeU16(n: number) { this.#buf.push((n >>> 8) & 0xff, n & 0xff); }        // big-endian
+  writeU32(n: number) {
+    this.#buf.push((n>>>24)&0xff, (n>>>16)&0xff, (n>>>8)&0xff, n&0xff);
+  }
+  writeU64(bi: bigint) {
+    // 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: Uint8Array) { for (const x of b) this.#buf.push(x); }
+}