hd-wallet-wasm 2.1.0 → 2.1.2

package/dist/runtime/aligned.mjs

@@ -51,6 +51,7 @@ import {
   Curve as AlignedCurve,
   Error as AlignedErrorCode,
 } from './generated/aligned/hd_wallet_aligned.mjs';
+import { createInputValidation } from './input-validation.mjs';
 
 // Re-export for external use
 export { AlignedCurve, AlignedErrorCode };
@@ -90,12 +91,54 @@ const ERROR_MESSAGES = {
  */
 export class AlignedError extends Error {
   constructor(code, message) {
-    super(message || ERROR_MESSAGES[code] || `Error code: ${code}`);
+    const lookup = code < 0 ? -code : code;
+    super(message || ERROR_MESSAGES[lookup] || `Error code: ${code}`);
     this.name = 'AlignedError';
-    this.code = code;
+    this.code = lookup;
   }
 }
 
+// Input validation shared with the main API (input-validation.mjs): every
+// key, hash and signature is checked for type, length and (keys) validity
+// before it is written into a request.
+const V = createInputValidation((code, message) => new AlignedError(code, message));
+
+// Largest batch: the request structs carry 32-bit counts, and the result
+// buffers are allocated up front.
+const MAX_BATCH = 0x100000;
+
+// Allocate `size` bytes and zero them, so no field a request leaves unset is
+// read from stale heap.
+function allocZeroed(wasm, size) {
+  const pointer = wasm._hd_alloc(Math.max(1, size));
+  if (!pointer) {
+    throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+  }
+  wasm.HEAPU8.fill(0, pointer, pointer + Math.max(1, size));
+  return pointer;
+}
+
+// Curves the batch APIs sign and verify with; P-384 signatures do not fit the
+// 64-byte entries and X25519 does not sign, so entries for them report
+// NOT_SUPPORTED.
+const BATCH_CURVES = Object.freeze([
+  AlignedCurve.SECP256K1,
+  AlignedCurve.ED25519,
+  AlignedCurve.P256,
+  AlignedCurve.P384,
+  AlignedCurve.X25519,
+]);
+
+// The batch exports return the number of entries written, or a negative
+// -Error code. Only a count within [0, capacity] is success; anything else
+// throws before a result entry is read.
+function checkCount(result, capacity) {
+  if (!Number.isInteger(result) || result < 0 || result > capacity) {
+    throw new AlignedError(result < 0 ? result : AlignedErrorCode.INTERNAL);
+  }
+  return result;
+}
+
 // =============================================================================
 // AlignedKeyDeriver - Batch Key Derivation
 // =============================================================================
@@ -141,6 +184,8 @@ export class AlignedKeyDeriver {
    * @returns {Array<DerivedKey>} Array of derived keys
    */
   deriveBatch(baseKey, startIndex, count, hardened = false) {
+    V.uint32(startIndex, 'startIndex');
+    V.integer(count, 'count', 0, MAX_BATCH);
     // Short-circuit: requesting zero keys returns empty array
     if (count === 0) {
       return [];
@@ -149,10 +194,7 @@ export class AlignedKeyDeriver {
     const wasm = this.#wasm;
 
     // Allocate request buffer
-    const requestPtr = wasm._hd_alloc(BATCHDERIVEREQUEST_SIZE);
-    if (!requestPtr) {
-      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
-    }
+    const requestPtr = allocZeroed(wasm, BATCHDERIVEREQUEST_SIZE);
 
     try {
       // Fill request
@@ -171,15 +213,11 @@ export class AlignedKeyDeriver {
 
       try {
         // Call WASM function
-        const derivedCount = wasm._hd_aligned_derive_batch(
+        const derivedCount = checkCount(wasm._hd_aligned_derive_batch(
           requestPtr,
           resultsPtr,
           count
-        );
-
-        if (derivedCount < 0) {
-          throw new AlignedError(derivedCount);
-        }
+        ), count);
 
         // Read results
         const results = [];
@@ -203,9 +241,13 @@ export class AlignedKeyDeriver {
 
         return results;
       } finally {
+        // Entries carry derived private keys.
+        wasm._hd_secure_wipe(resultsPtr, resultsSize);
         wasm._hd_dealloc(resultsPtr);
       }
     } finally {
+      // The request carries the base private key.
+      wasm._hd_secure_wipe(requestPtr, BATCHDERIVEREQUEST_SIZE);
       wasm._hd_dealloc(requestPtr);
     }
   }
@@ -221,23 +263,28 @@ export class AlignedKeyDeriver {
    */
   *streamKeys(baseKey, startIndex = 0, batchSize = 100, hardened = false) {
     const wasm = this.#wasm;
+    V.uint32(startIndex, 'startIndex');
+    // The results buffer holds exactly batchSize entries.
+    V.integer(batchSize, 'batchSize', 1, MAX_BATCH);
 
     // Allocate config buffer
-    const configPtr = wasm._hd_alloc(STREAMDERIVECONFIG_SIZE);
-    if (!configPtr) {
-      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
-    }
+    const configPtr = allocZeroed(wasm, STREAMDERIVECONFIG_SIZE);
 
-    // 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;
+    // Fill config, create the stream, then wipe the config (it carries the
+    // base private key) whatever happens.
+    let streamHandle;
+    try {
+      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);
+      streamHandle = wasm._hd_aligned_stream_create(configPtr);
+    } finally {
+      wasm._hd_secure_wipe(configPtr, STREAMDERIVECONFIG_SIZE);
+      wasm._hd_dealloc(configPtr);
+    }
 
     if (!streamHandle) {
       throw new AlignedError(AlignedErrorCode.INTERNAL, 'Failed to create stream');
@@ -253,13 +300,15 @@ export class AlignedKeyDeriver {
 
     try {
       while (true) {
-        const derivedCount = wasm._hd_aligned_stream_next(
+        // 0 ends the stream; a negative -Error throws instead of ending it
+        // silently.
+        const derivedCount = checkCount(wasm._hd_aligned_stream_next(
           streamHandle,
           resultsPtr,
           batchSize
-        );
+        ), batchSize);
 
-        if (derivedCount <= 0) {
+        if (derivedCount === 0) {
           break;
         }
 
@@ -286,6 +335,7 @@ export class AlignedKeyDeriver {
         yield batch;
       }
     } finally {
+      wasm._hd_secure_wipe(resultsPtr, resultsSize);
       wasm._hd_dealloc(resultsPtr);
       wasm._hd_aligned_stream_destroy(streamHandle);
     }
@@ -296,11 +346,18 @@ export class AlignedKeyDeriver {
    * @private
    */
   #fillBaseKey(view, baseKey) {
-    if (baseKey._handle) {
+    if (baseKey && baseKey._handle) {
       // HDKey object - use conversion function
       const keyDataPtr = this.#wasm._hd_alloc(EXTENDEDKEYDATA_SIZE);
+      if (!keyDataPtr) {
+        throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
+      }
       try {
-        this.#wasm._hd_aligned_from_extended_key(baseKey._handle, keyDataPtr);
+        // On failure the buffer holds no key: never copy it.
+        const result = this.#wasm._hd_aligned_from_extended_key(baseKey._handle, keyDataPtr);
+        if (result !== 0) {
+          throw new AlignedError(result);
+        }
         const keyDataView = ExtendedKeyDataView.fromMemory(
           this.#wasm.wasmMemory, keyDataPtr
         );
@@ -314,14 +371,27 @@ export class AlignedKeyDeriver {
         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_secure_wipe(keyDataPtr, EXTENDEDKEYDATA_SIZE);
         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;
+    } else if (baseKey && baseKey.privateKey && baseKey.chainCode) {
+      // Plain object with key data: every field at its exact size, the keys
+      // valid for the curve (32-byte scalars, 33-byte compressed keys).
+      const curve = baseKey.curve ?? AlignedCurve.SECP256K1;
+      V.curve(curve, [AlignedCurve.SECP256K1, AlignedCurve.P256]);
+      const depth = baseKey.depth ?? 0;
+      const parentFingerprint = baseKey.parentFingerprint ?? 0;
+      const childIndex = baseKey.childIndex ?? 0;
+      V.integer(depth, 'depth', 0, 255);
+      V.uint32(parentFingerprint, 'parentFingerprint');
+      V.uint32(childIndex, 'childIndex');
+      V.bytesOfLength(baseKey.chainCode, 32, 'chainCode');
+      V.privateKey(this.#wasm, baseKey.privateKey, curve);
+      V.publicKey(this.#wasm, baseKey.publicKey, curve, 'publicKey', [33]);
+      view.base_key_curve = curve;
+      view.base_key_depth = depth;
+      view.base_key_parent_fingerprint = parentFingerprint;
+      view.base_key_child_index = childIndex;
       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);
@@ -371,13 +441,28 @@ export class AlignedSigner {
    */
   signBatch(privateKey, hashes, curve = AlignedCurve.SECP256K1) {
     const wasm = this.#wasm;
-    const count = hashes.length;
+    V.curve(curve, BATCH_CURVES);
+    // The array and each entry are read once (a Proxy or a getter could answer
+    // a second read differently); only the copies are used below.
+    const hashCount = Array.isArray(hashes) ? hashes.length : -1;
+    if (!Number.isInteger(hashCount) || hashCount < 0 || hashCount > MAX_BATCH) {
+      throw new AlignedError(AlignedErrorCode.INVALID_ARGUMENT, `hashes must be an array of at most ${MAX_BATCH}`);
+    }
+    const hashCopies = [];
+    for (let i = 0; i < hashCount; i++) hashCopies.push(V.snapshot(hashes[i], 'hash'));
+    // The request holds a 32-byte key: secp256k1 and P-256 keys must be
+    // 0 < d < n; Ed25519 seeds are any 32 bytes. P-384 and X25519 entries
+    // report NOT_SUPPORTED.
+    if (curve === AlignedCurve.SECP256K1 || curve === AlignedCurve.P256 || curve === AlignedCurve.ED25519) {
+      V.privateKey(wasm, privateKey, curve);
+    } else {
+      V.bytesOfLength(privateKey, 32, 'privateKey', AlignedErrorCode.INVALID_PRIVATE_KEY);
+    }
+    for (const hash of hashCopies) V.bytesOfLength(hash, 32, 'hash');
+    const count = hashCopies.length;
 
     // Allocate request
-    const requestPtr = wasm._hd_alloc(BATCHSIGNREQUEST_SIZE);
-    if (!requestPtr) {
-      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
-    }
+    const requestPtr = allocZeroed(wasm, BATCHSIGNREQUEST_SIZE);
 
     try {
       // Fill request
@@ -387,38 +472,28 @@ export class AlignedSigner {
       requestView.count = count;
 
       // Allocate and fill hashes
-      const hashesPtr = wasm._hd_alloc(count * HASHENTRY_SIZE);
-      if (!hashesPtr) {
-        throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
-      }
+      const hashesPtr = allocZeroed(wasm, count * HASHENTRY_SIZE);
 
       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]);
+          entry.hash_data.set(hashCopies[i]);
         }
 
         // Allocate results
-        const resultsPtr = wasm._hd_alloc(count * SIGNATUREENTRY_SIZE);
-        if (!resultsPtr) {
-          throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
-        }
+        const resultsPtr = allocZeroed(wasm, count * SIGNATUREENTRY_SIZE);
 
         try {
           // Call WASM function
-          const signedCount = wasm._hd_aligned_sign_batch(
+          const signedCount = checkCount(wasm._hd_aligned_sign_batch(
             requestPtr,
             hashesPtr,
             count,
             resultsPtr,
             count
-          );
-
-          if (signedCount < 0) {
-            throw new AlignedError(signedCount);
-          }
+          ), count);
 
           // Read results
           const results = [];
@@ -446,6 +521,8 @@ export class AlignedSigner {
         wasm._hd_dealloc(hashesPtr);
       }
     } finally {
+      // The request carries the private key.
+      wasm._hd_secure_wipe(requestPtr, BATCHSIGNREQUEST_SIZE);
       wasm._hd_dealloc(requestPtr);
     }
   }
@@ -460,55 +537,83 @@ export class AlignedSigner {
    */
   verifyBatch(publicKey, entries, curve = AlignedCurve.SECP256K1) {
     const wasm = this.#wasm;
-    const count = entries.length;
+    V.curve(curve, BATCH_CURVES);
+    // The array, each entry and each field are read once (a Proxy or a getter
+    // could answer a second read differently); only the copies are used below.
+    const entryCount = Array.isArray(entries) ? entries.length : -1;
+    if (!Number.isInteger(entryCount) || entryCount < 0 || entryCount > MAX_BATCH) {
+      throw new AlignedError(AlignedErrorCode.INVALID_ARGUMENT, `entries must be an array of at most ${MAX_BATCH}`);
+    }
+    // Types are programmer errors (throw); wrong lengths or an invalid key
+    // only make the affected entries invalid.
+    const publicKeyCopy = V.snapshot(publicKey, 'publicKey');
+    const entryCopies = [];
+    for (let i = 0; i < entryCount; i++) {
+      const entry = entries[i];
+      if (entry === null || typeof entry !== 'object') {
+        throw new AlignedError(AlignedErrorCode.INVALID_ARGUMENT, 'each entry must be { hash, signature }');
+      }
+      const { hash, signature } = entry;
+      entryCopies.push({ hash: V.snapshot(hash, 'hash'), signature: V.snapshot(signature, 'signature') });
+    }
+    const count = entryCopies.length;
+
+    // The request holds a 33-byte key: a compressed secp256k1 or P-256 key,
+    // or an Ed25519 key after one padding byte.
+    let keyBytes = null;
+    if (curve === AlignedCurve.ED25519) {
+      if (publicKeyCopy.length === 32) {
+        keyBytes = new Uint8Array(33);
+        keyBytes.set(publicKeyCopy, 1);
+      } else if (publicKeyCopy.length === 33) {
+        keyBytes = publicKeyCopy;
+      }
+    } else if (curve === AlignedCurve.SECP256K1 || curve === AlignedCurve.P256) {
+      if (V.isPublicKey(wasm, publicKeyCopy, curve, [33])) keyBytes = publicKeyCopy;
+    } else {
+      // P-384 / X25519: the export reports NOT_SUPPORTED for every entry.
+      keyBytes = new Uint8Array(33);
+    }
+    const entryValid = entryCopies.map((entry) => keyBytes !== null &&
+      entry.hash.length === 32 && entry.signature.length === 64);
 
     // Allocate request
-    const requestPtr = wasm._hd_alloc(BATCHVERIFYREQUEST_SIZE);
-    if (!requestPtr) {
-      throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
-    }
+    const requestPtr = allocZeroed(wasm, BATCHVERIFYREQUEST_SIZE);
 
     try {
       // Fill request
       const requestView = BatchVerifyRequestView.fromMemory(wasm.wasmMemory, requestPtr);
-      requestView.public_key_data.set(publicKey);
+      if (keyBytes !== null) requestView.public_key_data.set(keyBytes);
       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);
-      }
+      // Allocate and fill entries (an invalid entry stays all zero and its
+      // result is reported invalid below whatever the export says)
+      const entriesPtr = allocZeroed(wasm, count * VERIFYENTRY_SIZE);
 
       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);
+          if (entryValid[i]) {
+            view.hash_data.set(entryCopies[i].hash);
+            view.signature_data.set(entryCopies[i].signature);
+          }
         }
 
         // Allocate results
-        const resultsPtr = wasm._hd_alloc(count * VERIFYRESULTENTRY_SIZE);
-        if (!resultsPtr) {
-          throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
-        }
+        const resultsPtr = allocZeroed(wasm, count * VERIFYRESULTENTRY_SIZE);
 
         try {
           // Call WASM function
-          const verifiedCount = wasm._hd_aligned_verify_batch(
+          const verifiedCount = checkCount(wasm._hd_aligned_verify_batch(
             requestPtr,
             entriesPtr,
             count,
             resultsPtr,
             count
-          );
-
-          if (verifiedCount < 0) {
-            throw new AlignedError(verifiedCount);
-          }
+          ), count);
 
           // Read results
           const results = [];
@@ -518,6 +623,16 @@ export class AlignedSigner {
 
           for (let i = 0; i < verifiedCount; i++) {
             const entry = resultsArray.at(i);
+            if (!entryValid[i]) {
+              results.push({
+                index: i,
+                valid: false,
+                error: keyBytes === null
+                  ? AlignedErrorCode.INVALID_PUBLIC_KEY
+                  : AlignedErrorCode.INVALID_SIGNATURE,
+              });
+              continue;
+            }
             results.push({
               index: entry.index,
               valid: entry.error === AlignedErrorCode.OK,
@@ -588,6 +703,9 @@ export class AlignedAPI {
    */
   keyToBytes(hdKey) {
     const wasm = this.#wasm;
+    if (!hdKey || !hdKey._handle) {
+      throw new AlignedError(AlignedErrorCode.INVALID_ARGUMENT, 'hdKey must be a live HDKey');
+    }
     const ptr = wasm._hd_alloc(EXTENDEDKEYDATA_SIZE);
     if (!ptr) {
       throw new AlignedError(AlignedErrorCode.OUT_OF_MEMORY);
@@ -600,6 +718,7 @@ export class AlignedAPI {
       }
       return new Uint8Array(wasm.HEAPU8.buffer, ptr, EXTENDEDKEYDATA_SIZE).slice();
     } finally {
+      wasm._hd_secure_wipe(ptr, EXTENDEDKEYDATA_SIZE);
       wasm._hd_dealloc(ptr);
     }
   }

package/dist/runtime/epm-attestation.mjs

@@ -224,6 +224,15 @@ export function buildEPMSigningContent(epm) {
 const SECP256K1_ORDER = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
 const SECP256K1_HALF_ORDER = SECP256K1_ORDER >> 1n;
 
+// Hex from an attestation or proof is untrusted data: anything that is not an
+// even-length hex string decodes to null, and the verification fails.
+function hexOrNull(wallet, value) {
+  if (typeof value !== 'string' || value.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(value)) {
+    return null;
+  }
+  return wallet.utils.decodeHex(value);
+}
+
 function bytesToBigInt(bytes) {
   let value = 0n;
   for (const b of bytes) value = (value << 8n) | BigInt(b);
@@ -337,7 +346,8 @@ export function verifyEPMSignature(wallet, epm, publicKey, options = {}) {
   if (!sigHex) return false;
 
   const content = buildEPMSigningContent(epm);
-  const sig = wallet.utils.decodeHex(sigHex);
+  const sig = hexOrNull(wallet, sigHex);
+  if (sig === null) return false;
   const curve = String(
     options.curve || (publicKey && publicKey.length === 32 ? 'ed25519' : 'secp256k1'),
   ).toLowerCase();
@@ -547,9 +557,14 @@ export function buildSolanaChainProof(wallet, { address, publicKeyHex, privateKe
  * @returns {boolean} True if the signature is valid for the given public key and payload
  */
 export function verifyChainProof(wallet, proof) {
-  const pubKey = wallet.utils.decodeHex(proof.PUBLIC_KEY);
-  const sig = wallet.utils.decodeHex(proof.SIGNATURE);
-  const payload = wallet.utils.decodeHex(proof.SIGNED_PAYLOAD);
+  if (proof === null || typeof proof !== 'object') {
+    throw new TypeError('proof must be a ChainProof object');
+  }
+  // A proof whose fields are not hex does not verify.
+  const pubKey = hexOrNull(wallet, proof.PUBLIC_KEY);
+  const sig = hexOrNull(wallet, proof.SIGNATURE);
+  const payload = hexOrNull(wallet, proof.SIGNED_PAYLOAD);
+  if (pubKey === null || sig === null || payload === null) return false;
 
   const algorithm = proof.ALGORITHM;
 

package/dist/runtime/index.d.ts

@@ -12,8 +12,16 @@
 // Import aligned API types
 import { AlignedAPI } from './aligned.js';
 
-export type BinaryLike = Uint8Array | ArrayBuffer | ArrayBufferView;
-export type X509CertificateInput = string | BinaryLike;
+/**
+ * Binary input to every wallet API: a Uint8Array (Node Buffers included) of
+ * this realm. A DataView, an ArrayBuffer, another typed array, a detached or
+ * cross-realm array is refused.
+ */
+export type BinaryLike = Uint8Array;
+/** A PEM string or its bytes, or DER bytes. */
+export type X509CertificateInput = string | Uint8Array;
+/** What an SDN plugin capability callback may return (it is copied to a Uint8Array). */
+export type PluginBinaryLike = Uint8Array | ArrayBuffer | ArrayBufferView;
 
 export interface SdnPluginTypeRef {
   schemaName: string | null;
@@ -113,7 +121,7 @@ export interface SdnPluginInvocationResult {
 }
 
 export interface SdnPluginCapabilities {
-  randomBytes?: (length: number, context?: Record<string, unknown>) => BinaryLike;
+  randomBytes?: (length: number, context?: Record<string, unknown>) => PluginBinaryLike;
   /**
    * Wallet-held signer for sign_detached. For secp256k1 it receives the message
    * (digest is null) and must return ECDSA over SHA-256(messageBytes), hashed once.
@@ -124,8 +132,8 @@ export interface SdnPluginCapabilities {
     messageBytes: Uint8Array;
     digest: Uint8Array | null;
   }) => {
-    signature: BinaryLike;
-    publicKey: BinaryLike;
+    signature: PluginBinaryLike;
+    publicKey: PluginBinaryLike;
     algorithm?: string;
   };
 }
@@ -818,7 +826,12 @@ export interface BitcoinTxBuilder {
 
 export interface BitcoinTx {
   addInput(txid: string, vout: number, sequence?: number): this;
-  addOutput(address: string, amount: bigint): this;
+  /**
+   * Pay `address`: P2PKH, P2SH, P2WPKH (v0, 20 bytes), P2WSH (v0, 32 bytes)
+   * or P2TR (v1, 32 bytes) of `network` (mainnet by default). Any other
+   * address, or one of the other network, throws (BIP-350).
+   */
+  addOutput(address: string, amount: bigint, network?: Network): this;
   sign(inputIndex: number, privateKey: Uint8Array, redeemScript?: Uint8Array): this;
   serialize(): Uint8Array;
   getTxid(): string;
@@ -867,6 +880,11 @@ export interface EthereumAPI {
   tx: EthereumTxBuilder;
 }
 
+/**
+ * `nonce` and `chainId` are required: a missing nonce or chainId, or a chainId
+ * outside 1 to 2^63 - 37 (EIP-2294), throws (an explicit nonce 0 is valid).
+ * Each field is read once.
+ */
 export interface EthereumTxBuilder {
   create(params: {
     nonce: number;
@@ -1044,7 +1062,7 @@ export interface UtilsAPI {
 
 export interface X509WalletAttestationOptions {
   curve: Curve;
-  privateKey: BinaryLike;
+  privateKey: Uint8Array;
   keyLabel?: string;
   commentPrefix?: string;
 }
@@ -1090,22 +1108,22 @@ export interface X509Pkcs12Bundle {
 export interface X509API {
   isAvailable(): boolean;
   generatePrivateKey(curve: Curve): Uint8Array;
-  exportPrivateKeyPem(curve: Curve, privateKey: BinaryLike): string;
+  exportPrivateKeyPem(curve: Curve, privateKey: Uint8Array): string;
   importPrivateKeyPem(curve: Curve, pem: string): Uint8Array;
   createSelfSignedCertificate(
     options: X509CertificateOptions,
     certificateCurve: Curve,
-    certificatePrivateKey: BinaryLike,
+    certificatePrivateKey: Uint8Array,
     outputEncoding?: X509Encoding
   ): string | Uint8Array;
   issueCertificate(
     options: X509CertificateOptions,
     issuerCurve: Curve,
-    issuerPrivateKey: BinaryLike,
+    issuerPrivateKey: Uint8Array,
     issuerCertificate: X509CertificateInput,
     issuerCertificateEncoding: X509Encoding,
     subjectCurve: Curve,
-    subjectPrivateKey: BinaryLike,
+    subjectPrivateKey: Uint8Array,
     outputEncoding?: X509Encoding
   ): string | Uint8Array;
   convertCertificate(
@@ -1119,12 +1137,12 @@ export interface X509API {
     certificate: X509CertificateInput,
     certificateEncoding: X509Encoding,
     privateKeyCurve: Curve,
-    privateKey: BinaryLike,
+    privateKey: Uint8Array,
     password: string,
     friendlyName?: string,
     chainPem?: X509CertificateInput
   ): Uint8Array;
-  importPkcs12(pkcs12Bundle: BinaryLike, password: string): X509Pkcs12Bundle;
+  importPkcs12(pkcs12Bundle: Uint8Array, password: string): X509Pkcs12Bundle;
 }
 
 // =============================================================================