hd-wallet-wasm 0.1.0 → 0.1.5

package/dist/index.d.ts

@@ -9,6 +9,9 @@
  * - Transaction building and signing
  */
 
+// Import aligned API types
+import { AlignedAPI } from './aligned';
+
 // =============================================================================
 // Module Types
 // =============================================================================
@@ -62,6 +65,9 @@ export interface HDWalletModule {
 
   // Utilities
   utils: UtilsAPI;
+
+  // Aligned binary API for efficient batch operations
+  aligned: AlignedAPI;
 }
 
 // =============================================================================
@@ -600,10 +606,12 @@ export interface UtilsAPI {
 
 /**
  * Initialize the HD Wallet WASM module
+ * @param wasmPath - Optional path to WASM file
  */
-export default function init(): Promise<HDWalletModule>;
+export default function init(wasmPath?: string): Promise<HDWalletModule>;
 
 /**
  * Create HD Wallet instance (alternative syntax)
+ * @param wasmPath - Optional path to WASM file
  */
-export function createHDWallet(): Promise<HDWalletModule>;
+export function createHDWallet(wasmPath?: string): Promise<HDWalletModule>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-wallet-wasm",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "Comprehensive HD Wallet implementation in WebAssembly - BIP-32/39/44, multi-curve, multi-chain support",
   "type": "module",
   "main": "src/index.mjs",
@@ -13,6 +13,10 @@
       "import": "./src/index.mjs",
       "require": "./dist/hd-wallet.cjs"
     },
+    "./aligned": {
+      "types": "./src/aligned.d.ts",
+      "import": "./src/aligned.mjs"
+    },
     "./wasm": {
       "types": "./dist/index.d.ts",
       "import": "./dist/hd-wallet.js"
@@ -21,6 +25,8 @@
   "files": [
     "src/index.mjs",
     "src/index.d.ts",
+    "src/aligned.mjs",
+    "src/aligned.d.ts",
     "dist/hd-wallet.js",
     "dist/hd-wallet.wasm",
     "dist/hd-wallet.cjs",
@@ -28,11 +34,13 @@
     "README.md"
   ],
   "scripts": {
-    "build": "cmake --build ../build-wasm --target hd_wallet_wasm_npm -j",
+    "generate": "node ../scripts/generate-aligned.mjs",
+    "build": "npm run generate && cmake --build ../build-wasm --target hd_wallet_wasm_npm -j",
     "test": "node test/test_all.mjs",
     "test:bip39": "node test/test_bip39.mjs",
     "test:bip32": "node test/test_bip32.mjs",
     "test:vectors": "node test/test_vectors.mjs",
+    "test:aligned": "node test/test_aligned.mjs",
     "prepublishOnly": "npm run build && npm test"
   },
   "repository": {

package/src/aligned.d.ts

@@ -0,0 +1,349 @@
+/**
+ * HD Wallet WASM - Aligned Binary API Type Definitions
+ *
+ * Provides efficient batch operations using aligned, fixed-size structs
+ * for zero-copy WASM interop.
+ *
+ * @module hd-wallet-wasm/aligned
+ */
+
+// =============================================================================
+// Enums
+// =============================================================================
+
+/**
+ * Elliptic curve types for aligned operations
+ */
+export enum AlignedCurve {
+  SECP256K1 = 0,
+  ED25519 = 1,
+  P256 = 2,
+  P384 = 3,
+  X25519 = 4
+}
+
+/**
+ * Error codes for aligned operations
+ */
+export enum AlignedError {
+  OK = 0,
+  UNKNOWN = 1,
+  INVALID_ARGUMENT = 2,
+  NOT_SUPPORTED = 3,
+  OUT_OF_MEMORY = 4,
+  INTERNAL = 5,
+  NO_ENTROPY = 100,
+  INSUFFICIENT_ENTROPY = 101,
+  INVALID_WORD = 200,
+  INVALID_CHECKSUM = 201,
+  INVALID_MNEMONIC_LENGTH = 202,
+  INVALID_ENTROPY_LENGTH = 203,
+  INVALID_SEED = 300,
+  INVALID_PATH = 301,
+  INVALID_CHILD_INDEX = 302,
+  HARDENED_FROM_PUBLIC = 303,
+  INVALID_EXTENDED_KEY = 304,
+  INVALID_PRIVATE_KEY = 400,
+  INVALID_PUBLIC_KEY = 401,
+  INVALID_SIGNATURE = 402,
+  VERIFICATION_FAILED = 403,
+  KEY_DERIVATION_FAILED = 404
+}
+
+// =============================================================================
+// Size Constants
+// =============================================================================
+
+export const EXTENDEDKEYDATA_SIZE: number;
+export const BATCHDERIVEREQUEST_SIZE: number;
+export const DERIVEDKEYENTRY_SIZE: number;
+
+// =============================================================================
+// Result Types
+// =============================================================================
+
+/**
+ * Result of a single key derivation
+ */
+export interface DerivedKey {
+  /** Child index that was derived */
+  index: number;
+  /** Error code (AlignedError.OK on success) */
+  error: AlignedError;
+  /** Compressed public key (33 bytes), null on error */
+  publicKey: Uint8Array | null;
+  /** Private key (32 bytes), null on error or if base was neutered */
+  privateKey: Uint8Array | null;
+}
+
+/**
+ * Result of a single signing operation
+ */
+export interface SignatureResult {
+  /** Index of the hash that was signed */
+  index: number;
+  /** Error code (AlignedError.OK on success) */
+  error: AlignedError;
+  /** Signature (64 bytes r||s format), null on error */
+  signature: Uint8Array | null;
+  /** Recovery ID for recoverable signatures (-1 if not applicable) */
+  recoveryId: number;
+}
+
+/**
+ * Result of a single signature verification
+ */
+export interface VerifyResult {
+  /** Index of the entry that was verified */
+  index: number;
+  /** Whether the signature is valid */
+  valid: boolean;
+  /** Error code */
+  error: AlignedError;
+}
+
+/**
+ * Input for signature verification
+ */
+export interface VerifyEntry {
+  /** 32-byte message hash */
+  hash: Uint8Array;
+  /** 64-byte signature */
+  signature: Uint8Array;
+}
+
+/**
+ * Base key data for batch operations
+ */
+export interface BaseKeyData {
+  /** Elliptic curve */
+  curve?: AlignedCurve;
+  /** Key depth in derivation tree */
+  depth?: number;
+  /** Parent fingerprint */
+  parentFingerprint?: number;
+  /** Child index */
+  childIndex?: number;
+  /** Chain code (32 bytes) */
+  chainCode: Uint8Array;
+  /** Compressed public key (33 bytes) */
+  publicKey: Uint8Array;
+  /** Private key (32 bytes) */
+  privateKey: Uint8Array;
+}
+
+// =============================================================================
+// View Classes (from generated code)
+// =============================================================================
+
+export class ExtendedKeyDataView {
+  constructor(buffer: ArrayBuffer, byteOffset?: number);
+  static fromMemory(memory: WebAssembly.Memory, ptr: number): ExtendedKeyDataView;
+  static fromBytes(bytes: Uint8Array, offset?: number): ExtendedKeyDataView;
+  static allocate(): ExtendedKeyDataView;
+
+  get curve(): AlignedCurve;
+  set curve(v: AlignedCurve);
+  get depth(): number;
+  set depth(v: number);
+  get parent_fingerprint(): number;
+  set parent_fingerprint(v: number);
+  get child_index(): number;
+  set child_index(v: number);
+  get chain_code_data(): Uint8Array;
+  get public_key_data(): Uint8Array;
+  get private_key_data(): Uint8Array;
+  get has_private_key(): number;
+  set has_private_key(v: number);
+
+  toObject(): Record<string, unknown>;
+  copyFrom(obj: Partial<Record<string, unknown>>): void;
+  copyTo(dest: Uint8Array, offset?: number): void;
+  getBytes(): Uint8Array;
+}
+
+export class BatchDeriveRequestView {
+  constructor(buffer: ArrayBuffer, byteOffset?: number);
+  static fromMemory(memory: WebAssembly.Memory, ptr: number): BatchDeriveRequestView;
+  static fromBytes(bytes: Uint8Array, offset?: number): BatchDeriveRequestView;
+  static allocate(): BatchDeriveRequestView;
+
+  get base_key_curve(): AlignedCurve;
+  set base_key_curve(v: AlignedCurve);
+  get base_key_depth(): number;
+  set base_key_depth(v: number);
+  get base_key_parent_fingerprint(): number;
+  set base_key_parent_fingerprint(v: number);
+  get base_key_child_index(): number;
+  set base_key_child_index(v: number);
+  get base_key_chain_code_data(): Uint8Array;
+  get base_key_public_key_data(): Uint8Array;
+  get base_key_private_key_data(): Uint8Array;
+  get base_key_has_private_key(): number;
+  set base_key_has_private_key(v: number);
+  get start_index(): number;
+  set start_index(v: number);
+  get count(): number;
+  set count(v: number);
+  get hardened(): number;
+  set hardened(v: number);
+
+  toObject(): Record<string, unknown>;
+  copyFrom(obj: Partial<Record<string, unknown>>): void;
+  copyTo(dest: Uint8Array, offset?: number): void;
+  getBytes(): Uint8Array;
+}
+
+export class DerivedKeyEntryView {
+  constructor(buffer: ArrayBuffer, byteOffset?: number);
+  static fromMemory(memory: WebAssembly.Memory, ptr: number): DerivedKeyEntryView;
+  static fromBytes(bytes: Uint8Array, offset?: number): DerivedKeyEntryView;
+  static allocate(): DerivedKeyEntryView;
+
+  get index(): number;
+  set index(v: number);
+  get error(): AlignedError;
+  set error(v: AlignedError);
+  get public_key_data(): Uint8Array;
+  get private_key_data(): Uint8Array;
+
+  toObject(): Record<string, unknown>;
+  copyFrom(obj: Partial<Record<string, unknown>>): void;
+  copyTo(dest: Uint8Array, offset?: number): void;
+  getBytes(): Uint8Array;
+}
+
+export class DerivedKeyEntryArrayView implements Iterable<DerivedKeyEntryView> {
+  constructor(buffer: ArrayBuffer, byteOffset: number, count: number);
+  static fromMemory(memory: WebAssembly.Memory, ptr: number, count: number): DerivedKeyEntryArrayView;
+
+  readonly length: number;
+  at(index: number): DerivedKeyEntryView;
+  [Symbol.iterator](): Iterator<DerivedKeyEntryView>;
+}
+
+// =============================================================================
+// AlignedKeyDeriver
+// =============================================================================
+
+/**
+ * Efficient batch key derivation using aligned binary format.
+ */
+export class AlignedKeyDeriver {
+  /**
+   * @param wasm - WASM module instance
+   */
+  constructor(wasm: unknown);
+
+  /**
+   * Derive multiple child keys from a base key in batch.
+   *
+   * @param baseKey - Base HDKey or BaseKeyData
+   * @param startIndex - Starting child index
+   * @param count - Number of keys to derive
+   * @param hardened - Use hardened derivation
+   * @returns Array of derived keys
+   */
+  deriveBatch(
+    baseKey: BaseKeyData | { _handle: unknown },
+    startIndex: number,
+    count: number,
+    hardened?: boolean
+  ): DerivedKey[];
+
+  /**
+   * Generator for streaming key derivation.
+   *
+   * @param baseKey - Base HDKey or BaseKeyData
+   * @param startIndex - Starting child index
+   * @param batchSize - Keys per batch
+   * @param hardened - Use hardened derivation
+   * @yields Batches of derived keys
+   */
+  streamKeys(
+    baseKey: BaseKeyData | { _handle: unknown },
+    startIndex?: number,
+    batchSize?: number,
+    hardened?: boolean
+  ): Generator<DerivedKey[], void, unknown>;
+}
+
+// =============================================================================
+// AlignedSigner
+// =============================================================================
+
+/**
+ * Efficient batch signing using aligned binary format.
+ */
+export class AlignedSigner {
+  /**
+   * @param wasm - WASM module instance
+   */
+  constructor(wasm: unknown);
+
+  /**
+   * Sign multiple message hashes with the same private key.
+   *
+   * @param privateKey - 32-byte private key
+   * @param hashes - Array of 32-byte message hashes
+   * @param curve - Elliptic curve
+   * @returns Array of signature results
+   */
+  signBatch(
+    privateKey: Uint8Array,
+    hashes: Uint8Array[],
+    curve?: AlignedCurve
+  ): SignatureResult[];
+
+  /**
+   * Verify multiple signatures against the same public key.
+   *
+   * @param publicKey - 33-byte compressed public key
+   * @param entries - Hash/signature pairs
+   * @param curve - Elliptic curve
+   * @returns Array of verification results
+   */
+  verifyBatch(
+    publicKey: Uint8Array,
+    entries: VerifyEntry[],
+    curve?: AlignedCurve
+  ): VerifyResult[];
+}
+
+// =============================================================================
+// AlignedAPI
+// =============================================================================
+
+/**
+ * Combined aligned API providing access to batch operations.
+ */
+export class AlignedAPI {
+  /**
+   * @param wasm - WASM module instance
+   */
+  constructor(wasm: unknown);
+
+  /** Key deriver for batch derivation */
+  readonly keyDeriver: AlignedKeyDeriver;
+
+  /** Signer for batch signing/verification */
+  readonly signer: AlignedSigner;
+
+  /**
+   * Convert HDKey to ExtendedKeyData bytes
+   * @param hdKey - HDKey instance
+   * @returns Extended key data bytes
+   */
+  keyToBytes(hdKey: { _handle: unknown }): Uint8Array;
+
+  /** Size of DerivedKeyEntry struct */
+  readonly derivedKeyEntrySize: number;
+
+  /** Size of ExtendedKeyData struct */
+  readonly extendedKeyDataSize: number;
+
+  /** Size of BatchDeriveRequest struct */
+  readonly batchDeriveRequestSize: number;
+}
+
+export default AlignedAPI;

package/src/aligned.mjs

@@ -0,0 +1,627 @@
+/**
+ * HD Wallet WASM - Aligned Binary API
+ *
+ * Provides efficient batch operations using aligned, fixed-size structs
+ * for zero-copy WASM interop. This module wraps the C++ aligned API
+ * with JavaScript-friendly interfaces.
+ *
+ * Features:
+ * - Batch key derivation (derive 100s of keys efficiently)
+ * - Batch signing (sign multiple hashes with same key)
+ * - Batch verification
+ * - Streaming key derivation (generators for unlimited sequences)
+ *
+ * @module hd-wallet-wasm/aligned
+ */
+
+// Import generated aligned struct definitions
+import {
+  // Size constants
+  EXTENDEDKEYDATA_SIZE,
+  BATCHDERIVEREQUEST_SIZE,
+  DERIVEDKEYENTRY_SIZE,
+  BATCHSIGNREQUEST_SIZE,
+  HASHENTRY_SIZE,
+  SIGNATUREENTRY_SIZE,
+  BATCHVERIFYREQUEST_SIZE,
+  VERIFYENTRY_SIZE,
+  VERIFYRESULTENTRY_SIZE,
+  STREAMDERIVECONFIG_SIZE,
+  STREAMSTATUS_SIZE,
+
+  // View classes
+  ExtendedKeyDataView,
+  BatchDeriveRequestView,
+  DerivedKeyEntryView,
+  DerivedKeyEntryArrayView,
+  BatchSignRequestView,
+  HashEntryView,
+  HashEntryArrayView,
+  SignatureEntryView,
+  SignatureEntryArrayView,
+  BatchVerifyRequestView,
+  VerifyEntryView,
+  VerifyEntryArrayView,
+  VerifyResultEntryView,
+  VerifyResultEntryArrayView,
+  StreamDeriveConfigView,
+  StreamStatusView,
+
+  // Enums
+  Curve as AlignedCurve,
+  Error as AlignedErrorCode,
+} from '../../generated/aligned/hd_wallet_aligned.mjs';
+
+// Re-export for external use
+export { AlignedCurve, AlignedErrorCode };
+export {
+  EXTENDEDKEYDATA_SIZE,
+  BATCHDERIVEREQUEST_SIZE,
+  DERIVEDKEYENTRY_SIZE,
+  ExtendedKeyDataView,
+  BatchDeriveRequestView,
+  DerivedKeyEntryView,
+  DerivedKeyEntryArrayView,
+};
+
+// =============================================================================
+// Error Handling
+// =============================================================================
+
+const ERROR_MESSAGES = {
+  [AlignedErrorCode.OK]: 'Success',
+  [AlignedErrorCode.UNKNOWN]: 'Unknown error',
+  [AlignedErrorCode.INVALID_ARGUMENT]: 'Invalid argument',
+  [AlignedErrorCode.NOT_SUPPORTED]: 'Operation not supported',
+  [AlignedErrorCode.OUT_OF_MEMORY]: 'Out of memory',
+  [AlignedErrorCode.INTERNAL]: 'Internal error',
+  [AlignedErrorCode.NO_ENTROPY]: 'No entropy available',
+  [AlignedErrorCode.INSUFFICIENT_ENTROPY]: 'Insufficient entropy',
+  [AlignedErrorCode.INVALID_PRIVATE_KEY]: 'Invalid private key',
+  [AlignedErrorCode.INVALID_PUBLIC_KEY]: 'Invalid public key',
+  [AlignedErrorCode.INVALID_SIGNATURE]: 'Invalid signature',
+  [AlignedErrorCode.VERIFICATION_FAILED]: 'Signature verification failed',
+  [AlignedErrorCode.KEY_DERIVATION_FAILED]: 'Key derivation failed',
+  [AlignedErrorCode.HARDENED_FROM_PUBLIC]: 'Cannot derive hardened from public key',
+};
+
+/**
+ * Aligned API Error
+ */
+export class AlignedError extends Error {
+  constructor(code, message) {
+    super(message || ERROR_MESSAGES[code] || `Error code: ${code}`);
+    this.name = 'AlignedError';
+    this.code = code;
+  }
+}
+
+// =============================================================================
+// AlignedKeyDeriver - Batch Key Derivation
+// =============================================================================
+
+/**
+ * Efficient batch key derivation using aligned binary format.
+ *
+ * @example
+ * ```js
+ * const deriver = new AlignedKeyDeriver(wasm);
+ *
+ * // Derive 100 keys at once
+ * const keys = deriver.deriveBatch(masterKey, 0, 100);
+ * for (const key of keys) {
+ *   console.log(key.index, key.publicKey);
+ * }
+ *
+ * // Stream unlimited keys
+ * for (const batch of deriver.streamKeys(masterKey, 0, 50)) {
+ *   for (const key of batch) {
+ *     processKey(key);
+ *   }
+ * }
+ * ```
+ */
+export class AlignedKeyDeriver {
+  #wasm;
+
+  /**
+   * @param {Object} wasm - WASM module instance
+   */
+  constructor(wasm) {
+    this.#wasm = wasm;
+  }
+
+  /**
+   * Derive multiple child keys from a base key in batch.
+   *
+   * @param {Object} baseKey - Base HDKey or ExtendedKeyData
+   * @param {number} startIndex - Starting child index
+   * @param {number} count - Number of keys to derive
+   * @param {boolean} [hardened=false] - Use hardened derivation
+   * @returns {Array<DerivedKey>} Array of derived keys
+   */
+  deriveBatch(baseKey, startIndex, count, hardened = false) {
+    const wasm = this.#wasm;
+
+    // Allocate request buffer
+    const requestPtr = wasm._hd_alloc(BATCHDERIVEREQUEST_SIZE);
+    if (!requestPtr) {
+      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+    }
+
+    try {
+      // Fill request
+      const requestView = BatchDeriveRequestView.fromMemory(wasm.wasmMemory, requestPtr);
+      this.#fillBaseKey(requestView, baseKey);
+      requestView.start_index = startIndex >>> 0;
+      requestView.count = count >>> 0;
+      requestView.hardened = hardened ? 1 : 0;
+
+      // Allocate results buffer
+      const resultsSize = count * DERIVEDKEYENTRY_SIZE;
+      const resultsPtr = wasm._hd_alloc(resultsSize);
+      if (!resultsPtr) {
+        throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+      }
+
+      try {
+        // Call WASM function
+        const derivedCount = wasm._hd_aligned_derive_batch(
+          requestPtr,
+          resultsPtr,
+          count
+        );
+
+        if (derivedCount < 0) {
+          throw new AlignedError(derivedCount);
+        }
+
+        // Read results
+        const results = [];
+        const resultsArray = DerivedKeyEntryArrayView.fromMemory(
+          wasm.wasmMemory, resultsPtr, derivedCount
+        );
+
+        for (let i = 0; i < derivedCount; i++) {
+          const entry = resultsArray.at(i);
+          results.push({
+            index: entry.index,
+            error: entry.error,
+            publicKey: entry.error === AlignedErrorCode.OK
+              ? new Uint8Array(entry.public_key_data)
+              : null,
+            privateKey: entry.error === AlignedErrorCode.OK
+              ? new Uint8Array(entry.private_key_data)
+              : null,
+          });
+        }
+
+        return results;
+      } finally {
+        wasm._hd_dealloc(resultsPtr);
+      }
+    } finally {
+      wasm._hd_dealloc(requestPtr);
+    }
+  }
+
+  /**
+   * Generator for streaming key derivation.
+   *
+   * @param {Object} baseKey - Base HDKey or ExtendedKeyData
+   * @param {number} [startIndex=0] - Starting child index
+   * @param {number} [batchSize=100] - Keys per batch
+   * @param {boolean} [hardened=false] - Use hardened derivation
+   * @yields {Array<DerivedKey>} Batches of derived keys
+   */
+  *streamKeys(baseKey, startIndex = 0, batchSize = 100, hardened = false) {
+    const wasm = this.#wasm;
+
+    // Allocate config buffer
+    const configPtr = wasm._hd_alloc(STREAMDERIVECONFIG_SIZE);
+    if (!configPtr) {
+      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+    }
+
+    // Fill config
+    const configView = StreamDeriveConfigView.fromMemory(wasm.wasmMemory, configPtr);
+    this.#fillBaseKey(configView, baseKey);
+    configView.start_index = startIndex >>> 0;
+    configView.batch_size = batchSize >>> 0;
+    configView.hardened = hardened ? 1 : 0;
+
+    // Create stream
+    const streamHandle = wasm._hd_aligned_stream_create(configPtr);
+    wasm._hd_dealloc(configPtr);
+
+    if (!streamHandle) {
+      throw new AlignedError(AlignedErrorCode.INTERNAL, 'Failed to create stream');
+    }
+
+    // Allocate results buffer
+    const resultsSize = batchSize * DERIVEDKEYENTRY_SIZE;
+    const resultsPtr = wasm._hd_alloc(resultsSize);
+    if (!resultsPtr) {
+      wasm._hd_aligned_stream_destroy(streamHandle);
+      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+    }
+
+    try {
+      while (true) {
+        const derivedCount = wasm._hd_aligned_stream_next(
+          streamHandle,
+          resultsPtr,
+          batchSize
+        );
+
+        if (derivedCount <= 0) {
+          break;
+        }
+
+        // Read batch results
+        const batch = [];
+        const resultsArray = DerivedKeyEntryArrayView.fromMemory(
+          wasm.wasmMemory, resultsPtr, derivedCount
+        );
+
+        for (let i = 0; i < derivedCount; i++) {
+          const entry = resultsArray.at(i);
+          batch.push({
+            index: entry.index,
+            error: entry.error,
+            publicKey: entry.error === AlignedErrorCode.OK
+              ? new Uint8Array(entry.public_key_data)
+              : null,
+            privateKey: entry.error === AlignedErrorCode.OK
+              ? new Uint8Array(entry.private_key_data)
+              : null,
+          });
+        }
+
+        yield batch;
+      }
+    } finally {
+      wasm._hd_dealloc(resultsPtr);
+      wasm._hd_aligned_stream_destroy(streamHandle);
+    }
+  }
+
+  /**
+   * Fill base key data in request/config view
+   * @private
+   */
+  #fillBaseKey(view, baseKey) {
+    if (baseKey._handle) {
+      // HDKey object - use conversion function
+      const keyDataPtr = this.#wasm._hd_alloc(EXTENDEDKEYDATA_SIZE);
+      try {
+        this.#wasm._hd_aligned_from_extended_key(baseKey._handle, keyDataPtr);
+        const keyDataView = ExtendedKeyDataView.fromMemory(
+          this.#wasm.wasmMemory, keyDataPtr
+        );
+        // Copy to request view's base_key fields
+        view.base_key_curve = keyDataView.curve;
+        view.base_key_depth = keyDataView.depth;
+        view.base_key_parent_fingerprint = keyDataView.parent_fingerprint;
+        view.base_key_child_index = keyDataView.child_index;
+        view.base_key_chain_code_data.set(keyDataView.chain_code_data);
+        view.base_key_public_key_data.set(keyDataView.public_key_data);
+        view.base_key_private_key_data.set(keyDataView.private_key_data);
+        view.base_key_has_private_key = keyDataView.has_private_key;
+      } finally {
+        this.#wasm._hd_dealloc(keyDataPtr);
+      }
+    } else if (baseKey.privateKey && baseKey.chainCode) {
+      // Plain object with key data
+      view.base_key_curve = baseKey.curve ?? AlignedCurve.SECP256K1;
+      view.base_key_depth = baseKey.depth ?? 0;
+      view.base_key_parent_fingerprint = baseKey.parentFingerprint ?? 0;
+      view.base_key_child_index = baseKey.childIndex ?? 0;
+      view.base_key_chain_code_data.set(baseKey.chainCode);
+      view.base_key_public_key_data.set(baseKey.publicKey);
+      view.base_key_private_key_data.set(baseKey.privateKey);
+      view.base_key_has_private_key = 1;
+    } else {
+      throw new AlignedError(
+        AlignedErrorCode.INVALID_ARGUMENT,
+        'baseKey must be an HDKey or have privateKey and chainCode'
+      );
+    }
+  }
+}
+
+// =============================================================================
+// AlignedSigner - Batch Signing
+// =============================================================================
+
+/**
+ * Efficient batch signing using aligned binary format.
+ *
+ * @example
+ * ```js
+ * const signer = new AlignedSigner(wasm);
+ *
+ * // Sign multiple hashes
+ * const hashes = [hash1, hash2, hash3];
+ * const signatures = signer.signBatch(privateKey, hashes);
+ * ```
+ */
+export class AlignedSigner {
+  #wasm;
+
+  /**
+   * @param {Object} wasm - WASM module instance
+   */
+  constructor(wasm) {
+    this.#wasm = wasm;
+  }
+
+  /**
+   * Sign multiple message hashes with the same private key.
+   *
+   * @param {Uint8Array} privateKey - 32-byte private key
+   * @param {Array<Uint8Array>} hashes - Array of 32-byte message hashes
+   * @param {number} [curve=AlignedCurve.SECP256K1] - Elliptic curve
+   * @returns {Array<SignatureResult>} Array of signature results
+   */
+  signBatch(privateKey, hashes, curve = AlignedCurve.SECP256K1) {
+    const wasm = this.#wasm;
+    const count = hashes.length;
+
+    // Allocate request
+    const requestPtr = wasm._hd_alloc(BATCHSIGNREQUEST_SIZE);
+    if (!requestPtr) {
+      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+    }
+
+    try {
+      // Fill request
+      const requestView = BatchSignRequestView.fromMemory(wasm.wasmMemory, requestPtr);
+      requestView.private_key_data.set(privateKey);
+      requestView.curve = curve;
+      requestView.count = count;
+
+      // Allocate and fill hashes
+      const hashesPtr = wasm._hd_alloc(count * HASHENTRY_SIZE);
+      if (!hashesPtr) {
+        throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+      }
+
+      try {
+        const hashesArray = HashEntryArrayView.fromMemory(wasm.wasmMemory, hashesPtr, count);
+        for (let i = 0; i < count; i++) {
+          const entry = hashesArray.at(i);
+          entry.index = i;
+          entry.hash_data.set(hashes[i]);
+        }
+
+        // Allocate results
+        const resultsPtr = wasm._hd_alloc(count * SIGNATUREENTRY_SIZE);
+        if (!resultsPtr) {
+          throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+        }
+
+        try {
+          // Call WASM function
+          const signedCount = wasm._hd_aligned_sign_batch(
+            requestPtr,
+            hashesPtr,
+            count,
+            resultsPtr,
+            count
+          );
+
+          if (signedCount < 0) {
+            throw new AlignedError(signedCount);
+          }
+
+          // Read results
+          const results = [];
+          const resultsArray = SignatureEntryArrayView.fromMemory(
+            wasm.wasmMemory, resultsPtr, signedCount
+          );
+
+          for (let i = 0; i < signedCount; i++) {
+            const entry = resultsArray.at(i);
+            results.push({
+              index: entry.index,
+              error: entry.error,
+              signature: entry.error === AlignedErrorCode.OK
+                ? new Uint8Array(entry.signature_data)
+                : null,
+              recoveryId: entry.recovery_id,
+            });
+          }
+
+          return results;
+        } finally {
+          wasm._hd_dealloc(resultsPtr);
+        }
+      } finally {
+        wasm._hd_dealloc(hashesPtr);
+      }
+    } finally {
+      wasm._hd_dealloc(requestPtr);
+    }
+  }
+
+  /**
+   * Verify multiple signatures against the same public key.
+   *
+   * @param {Uint8Array} publicKey - 33-byte compressed public key
+   * @param {Array<{hash: Uint8Array, signature: Uint8Array}>} entries - Hash/signature pairs
+   * @param {number} [curve=AlignedCurve.SECP256K1] - Elliptic curve
+   * @returns {Array<VerifyResult>} Array of verification results
+   */
+  verifyBatch(publicKey, entries, curve = AlignedCurve.SECP256K1) {
+    const wasm = this.#wasm;
+    const count = entries.length;
+
+    // Allocate request
+    const requestPtr = wasm._hd_alloc(BATCHVERIFYREQUEST_SIZE);
+    if (!requestPtr) {
+      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+    }
+
+    try {
+      // Fill request
+      const requestView = BatchVerifyRequestView.fromMemory(wasm.wasmMemory, requestPtr);
+      requestView.public_key_data.set(publicKey);
+      requestView.curve = curve;
+      requestView.count = count;
+
+      // Allocate and fill entries
+      const entriesPtr = wasm._hd_alloc(count * VERIFYENTRY_SIZE);
+      if (!entriesPtr) {
+        throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+      }
+
+      try {
+        const entriesArray = VerifyEntryArrayView.fromMemory(wasm.wasmMemory, entriesPtr, count);
+        for (let i = 0; i < count; i++) {
+          const view = entriesArray.at(i);
+          view.index = i;
+          view.hash_data.set(entries[i].hash);
+          view.signature_data.set(entries[i].signature);
+        }
+
+        // Allocate results
+        const resultsPtr = wasm._hd_alloc(count * VERIFYRESULTENTRY_SIZE);
+        if (!resultsPtr) {
+          throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+        }
+
+        try {
+          // Call WASM function
+          const verifiedCount = wasm._hd_aligned_verify_batch(
+            requestPtr,
+            entriesPtr,
+            count,
+            resultsPtr,
+            count
+          );
+
+          if (verifiedCount < 0) {
+            throw new AlignedError(verifiedCount);
+          }
+
+          // Read results
+          const results = [];
+          const resultsArray = VerifyResultEntryArrayView.fromMemory(
+            wasm.wasmMemory, resultsPtr, verifiedCount
+          );
+
+          for (let i = 0; i < verifiedCount; i++) {
+            const entry = resultsArray.at(i);
+            results.push({
+              index: entry.index,
+              valid: entry.error === AlignedErrorCode.OK,
+              error: entry.error,
+            });
+          }
+
+          return results;
+        } finally {
+          wasm._hd_dealloc(resultsPtr);
+        }
+      } finally {
+        wasm._hd_dealloc(entriesPtr);
+      }
+    } finally {
+      wasm._hd_dealloc(requestPtr);
+    }
+  }
+}
+
+// =============================================================================
+// AlignedAPI - Combined API
+// =============================================================================
+
+/**
+ * Combined aligned API providing access to batch operations.
+ */
+export class AlignedAPI {
+  #wasm;
+  #keyDeriver;
+  #signer;
+
+  /**
+   * @param {Object} wasm - WASM module instance
+   */
+  constructor(wasm) {
+    this.#wasm = wasm;
+    this.#keyDeriver = null;
+    this.#signer = null;
+  }
+
+  /**
+   * Get key deriver instance
+   * @returns {AlignedKeyDeriver}
+   */
+  get keyDeriver() {
+    if (!this.#keyDeriver) {
+      this.#keyDeriver = new AlignedKeyDeriver(this.#wasm);
+    }
+    return this.#keyDeriver;
+  }
+
+  /**
+   * Get signer instance
+   * @returns {AlignedSigner}
+   */
+  get signer() {
+    if (!this.#signer) {
+      this.#signer = new AlignedSigner(this.#wasm);
+    }
+    return this.#signer;
+  }
+
+  /**
+   * Convert HDKey to ExtendedKeyData bytes
+   * @param {Object} hdKey - HDKey instance
+   * @returns {Uint8Array} Extended key data bytes
+   */
+  keyToBytes(hdKey) {
+    const wasm = this.#wasm;
+    const ptr = wasm._hd_alloc(EXTENDEDKEYDATA_SIZE);
+    if (!ptr) {
+      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+    }
+
+    try {
+      const result = wasm._hd_aligned_from_extended_key(hdKey._handle, ptr);
+      if (result !== 0) {
+        throw new AlignedError(result);
+      }
+      return new Uint8Array(wasm.HEAPU8.buffer, ptr, EXTENDEDKEYDATA_SIZE).slice();
+    } finally {
+      wasm._hd_dealloc(ptr);
+    }
+  }
+
+  /**
+   * Get size of DerivedKeyEntry struct
+   * @returns {number}
+   */
+  get derivedKeyEntrySize() {
+    return DERIVEDKEYENTRY_SIZE;
+  }
+
+  /**
+   * Get size of ExtendedKeyData struct
+   * @returns {number}
+   */
+  get extendedKeyDataSize() {
+    return EXTENDEDKEYDATA_SIZE;
+  }
+
+  /**
+   * Get size of BatchDeriveRequest struct
+   * @returns {number}
+   */
+  get batchDeriveRequestSize() {
+    return BATCHDERIVEREQUEST_SIZE;
+  }
+}
+
+export default AlignedAPI;

package/src/index.d.ts

@@ -9,6 +9,9 @@
  * - Transaction building and signing
  */
 
+// Import aligned API types
+import { AlignedAPI } from './aligned';
+
 // =============================================================================
 // Module Types
 // =============================================================================
@@ -62,6 +65,9 @@ export interface HDWalletModule {
 
   // Utilities
   utils: UtilsAPI;
+
+  // Aligned binary API for efficient batch operations
+  aligned: AlignedAPI;
 }
 
 // =============================================================================
@@ -600,10 +606,12 @@ export interface UtilsAPI {
 
 /**
  * Initialize the HD Wallet WASM module
+ * @param wasmPath - Optional path to WASM file
  */
-export default function init(): Promise<HDWalletModule>;
+export default function init(wasmPath?: string): Promise<HDWalletModule>;
 
 /**
  * Create HD Wallet instance (alternative syntax)
+ * @param wasmPath - Optional path to WASM file
  */
-export function createHDWallet(): Promise<HDWalletModule>;
+export function createHDWallet(wasmPath?: string): Promise<HDWalletModule>;

package/src/index.mjs

@@ -12,6 +12,9 @@
  * @version 0.1.0
  */
 
+// Import aligned API for batch operations
+import { AlignedAPI } from './aligned.mjs';
+
 // =============================================================================
 // Enums (matching TypeScript definitions)
 // =============================================================================
@@ -604,7 +607,7 @@ async function loadWasmModule(wasmPath) {
 
   try {
     // Try dynamic import (works in Node.js and bundlers)
-    const module = await import('./hd-wallet.js');
+    const module = await import('../dist/hd-wallet.js');
     HDWalletWasm = module.default;
   } catch (e) {
     // Fallback for browsers without ES module support
@@ -768,8 +771,9 @@ function createModule(wasm) {
       const outputPtr = wasm._hd_alloc(1024);
       try {
         wasm._hd_mnemonic_suggest_word(prefixPtr, language, outputPtr, 1024, maxSuggestions);
-        const json = readString(wasm, outputPtr);
-        return JSON.parse(json);
+        const text = readString(wasm, outputPtr);
+        // C API returns newline-separated words
+        return text ? text.split('\n').filter(w => w.length > 0) : [];
       } finally {
         wasm._hd_dealloc(prefixPtr);
         wasm._hd_dealloc(outputPtr);
@@ -804,23 +808,24 @@ function createModule(wasm) {
   const hdkey = {
     /**
      * Create master key from seed
-     * @param {Uint8Array} seed - 64-byte seed
+     * @param {Uint8Array} seed - 16-64 byte seed (BIP-32 allows 128-512 bits)
      * @param {number} [curve=Curve.SECP256K1] - Elliptic curve
      * @returns {HDKey} Master HD key
      */
     fromSeed(seed, curve = Curve.SECP256K1) {
-      if (seed.length !== 64) {
-        throw new HDWalletError(ErrorCode.INVALID_SEED, 'Seed must be 64 bytes');
+      // BIP-32 allows 128-512 bits (16-64 bytes)
+      if (seed.length < 16 || seed.length > 64) {
+        throw new HDWalletError(ErrorCode.INVALID_SEED, 'Seed must be 16-64 bytes');
       }
       const seedPtr = allocAndCopy(wasm, seed);
       try {
-        const handle = wasm._hd_key_from_seed(seedPtr, 64, curve);
+        const handle = wasm._hd_key_from_seed(seedPtr, seed.length, curve);
         if (!handle) {
           throw new HDWalletError(ErrorCode.INVALID_SEED);
         }
         return new HDKey(wasm, handle, 'm');
       } finally {
-        wasm._hd_secure_wipe(seedPtr, 64);
+        wasm._hd_secure_wipe(seedPtr, seed.length);
         wasm._hd_dealloc(seedPtr);
       }
     },
@@ -2444,7 +2449,20 @@ function createModule(wasm) {
     polkadot,
     hardware,
     keyring,
-    utils
+    utils,
+
+    // Aligned binary API for efficient batch operations
+    get aligned() {
+      if (!this._aligned) {
+        // Create a wrapper that exposes wasmMemory for the aligned API
+        const wasmWithMemory = Object.create(wasm);
+        Object.defineProperty(wasmWithMemory, 'wasmMemory', {
+          get: () => ({ buffer: wasm.HEAPU8.buffer })
+        });
+        this._aligned = new AlignedAPI(wasmWithMemory);
+      }
+      return this._aligned;
+    }
   };
 }