feat(wasm-utxo): add ECPair implementation

OttoAllmendinger · llm-git · OttoAllmendinger · commit b725ee25275c · 2025-11-26T11:55:39.000+01:00
Add elliptic curve key pair functionality with ECPair class that wraps the WasmECPair Rust implementation. This provides key generation, import/export functions including WIF format, and supports both private and public keys. Issue: BTC-2786 Co-authored-by: llm-git <llm-git@ttll.de>
diff --git a/packages/wasm-utxo/js/ecpair.ts b/packages/wasm-utxo/js/ecpair.ts
@@ -0,0 +1,178 @@
+import { WasmECPair } from "./wasm/wasm_utxo.js";
+
+/**
+ * ECPairArg represents the various forms that ECPair keys can take
+ * before being converted to a WasmECPair instance
+ */
+export type ECPairArg =
+  /** Private key (32 bytes) or compressed public key (33 bytes) as Buffer/Uint8Array */
+  | Uint8Array
+  /** ECPair instance */
+  | ECPair
+  /** WasmECPair instance */
+  | WasmECPair;
+
+/**
+ * Signer interface for signing operations
+ */
+export interface Signer {
+  publicKey: Uint8Array;
+  sign(hash: Uint8Array): Uint8Array;
+}
+
+/**
+ * Async signer interface
+ */
+export interface SignerAsync {
+  publicKey: Uint8Array;
+  sign(hash: Uint8Array): Promise<Uint8Array>;
+}
+
+/**
+ * ECPair interface for elliptic curve key pair operations
+ */
+export interface ECPairInterface {
+  publicKey: Uint8Array;
+  privateKey?: Uint8Array;
+  toWIF(): string;
+}
+
+/**
+ * ECPair wrapper class for elliptic curve key pair operations
+ */
+export class ECPair implements ECPairInterface {
+  private constructor(private _wasm: WasmECPair) {}
+
+  /**
+   * Create an ECPair instance from a WasmECPair instance (internal use)
+   * @internal
+   */
+  static fromWasm(wasm: WasmECPair): ECPair {
+    return new ECPair(wasm);
+  }
+
+  /**
+   * Convert ECPairArg to ECPair instance
+   * @param key - The ECPair key in various formats
+   * @returns ECPair instance
+   */
+  static from(key: ECPairArg): ECPair {
+    // Short-circuit if already an ECPair instance
+    if (key instanceof ECPair) {
+      return key;
+    }
+    // If it's a WasmECPair instance, wrap it
+    if (key instanceof WasmECPair) {
+      return new ECPair(key);
+    }
+    // Parse from Buffer/Uint8Array
+    // Check length to determine if it's a private key (32 bytes) or public key (33 bytes)
+    if (key.length === 32) {
+      const wasm = WasmECPair.from_private_key(key);
+      return new ECPair(wasm);
+    } else if (key.length === 33) {
+      const wasm = WasmECPair.from_public_key(key);
+      return new ECPair(wasm);
+    } else {
+      throw new Error(
+        `Invalid key length: ${key.length}. Expected 32 bytes (private key) or 33 bytes (compressed public key)`,
+      );
+    }
+  }
+
+  /**
+   * Create an ECPair from a private key (always uses compressed keys)
+   * @param buffer - The 32-byte private key
+   * @returns An ECPair instance
+   */
+  static fromPrivateKey(buffer: Uint8Array): ECPair {
+    const wasm = WasmECPair.from_private_key(buffer);
+    return new ECPair(wasm);
+  }
+
+  /**
+   * Create an ECPair from a compressed public key
+   * @param buffer - The compressed public key bytes (33 bytes)
+   * @returns An ECPair instance
+   */
+  static fromPublicKey(buffer: Uint8Array): ECPair {
+    const wasm = WasmECPair.from_public_key(buffer);
+    return new ECPair(wasm);
+  }
+
+  /**
+   * Create an ECPair from a WIF string (auto-detects network from WIF)
+   * @param wifString - The WIF-encoded private key string
+   * @returns An ECPair instance
+   */
+  static fromWIF(wifString: string): ECPair {
+    const wasm = WasmECPair.from_wif(wifString);
+    return new ECPair(wasm);
+  }
+
+  /**
+   * Create an ECPair from a mainnet WIF string
+   * @param wifString - The WIF-encoded private key string
+   * @returns An ECPair instance
+   */
+  static fromWIFMainnet(wifString: string): ECPair {
+    const wasm = WasmECPair.from_wif_mainnet(wifString);
+    return new ECPair(wasm);
+  }
+
+  /**
+   * Create an ECPair from a testnet WIF string
+   * @param wifString - The WIF-encoded private key string
+   * @returns An ECPair instance
+   */
+  static fromWIFTestnet(wifString: string): ECPair {
+    const wasm = WasmECPair.from_wif_testnet(wifString);
+    return new ECPair(wasm);
+  }
+
+  /**
+   * Get the private key as a Uint8Array (if available)
+   */
+  get privateKey(): Uint8Array | undefined {
+    return this._wasm.private_key;
+  }
+
+  /**
+   * Get the public key as a Uint8Array
+   */
+  get publicKey(): Uint8Array {
+    return this._wasm.public_key;
+  }
+
+  /**
+   * Convert to WIF string (mainnet)
+   * @returns The WIF-encoded private key
+   */
+  toWIF(): string {
+    return this._wasm.to_wif();
+  }
+
+  /**
+   * Convert to mainnet WIF string
+   * @returns The WIF-encoded private key
+   */
+  toWIFMainnet(): string {
+    return this._wasm.to_wif_mainnet();
+  }
+
+  /**
+   * Convert to testnet WIF string
+   * @returns The WIF-encoded private key
+   */
+  toWIFTestnet(): string {
+    return this._wasm.to_wif_testnet();
+  }
+
+  /**
+   * Get the underlying WASM instance (internal use only)
+   * @internal
+   */
+  get wasm(): WasmECPair {
+    return this._wasm;
+  }
+}
diff --git a/packages/wasm-utxo/js/index.ts b/packages/wasm-utxo/js/index.ts
@@ -9,6 +9,8 @@ export * as ast from "./ast/index.js";
 export * as utxolibCompat from "./utxolibCompat.js";
 export * as fixedScriptWallet from "./fixedScriptWallet.js";
 
+export { ECPair } from "./ecpair.js";
+
 export type { CoinName } from "./coinName.js";
 export type { Triple } from "./triple.js";
 export type { AddressFormat } from "./address.js";
diff --git a/packages/wasm-utxo/src/wasm/ecpair.rs b/packages/wasm-utxo/src/wasm/ecpair.rs
@@ -0,0 +1,180 @@
+use crate::bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
+use crate::bitcoin::PrivateKey;
+use crate::error::WasmUtxoError;
+use wasm_bindgen::prelude::*;
+
+// Internal enum to hold either public-only or private+public keys
+#[derive(Debug, Clone)]
+enum ECPairKey {
+    PublicOnly(PublicKey),
+    Private {
+        secret_key: SecretKey,
+        public_key: PublicKey,
+    },
+}
+
+impl ECPairKey {
+    fn public_key(&self) -> PublicKey {
+        match self {
+            ECPairKey::PublicOnly(pk) => *pk,
+            ECPairKey::Private { public_key, .. } => *public_key,
+        }
+    }
+
+    fn secret_key(&self) -> Option<SecretKey> {
+        match self {
+            ECPairKey::PublicOnly(_) => None,
+            ECPairKey::Private { secret_key, .. } => Some(*secret_key),
+        }
+    }
+}
+
+/// WASM wrapper for elliptic curve key pairs (always uses compressed keys)
+#[wasm_bindgen]
+#[derive(Debug, Clone)]
+pub struct WasmECPair {
+    key: ECPairKey,
+}
+
+impl WasmECPair {
+    /// Get the public key as a secp256k1::PublicKey (for internal Rust use)
+    pub(crate) fn get_public_key(&self) -> PublicKey {
+        self.key.public_key()
+    }
+}
+
+#[wasm_bindgen]
+impl WasmECPair {
+    /// Create an ECPair from a private key (always uses compressed keys)
+    #[wasm_bindgen]
+    pub fn from_private_key(private_key: &[u8]) -> Result<WasmECPair, WasmUtxoError> {
+        if private_key.len() != 32 {
+            return Err(WasmUtxoError::new("Private key must be 32 bytes"));
+        }
+
+        let secret_key = SecretKey::from_slice(private_key)
+            .map_err(|e| WasmUtxoError::new(&format!("Invalid private key: {}", e)))?;
+
+        let secp = Secp256k1::new();
+        let public_key = PublicKey::from_secret_key(&secp, &secret_key);
+
+        Ok(WasmECPair {
+            key: ECPairKey::Private {
+                secret_key,
+                public_key,
+            },
+        })
+    }
+
+    /// Create an ECPair from a public key (always uses compressed keys)
+    #[wasm_bindgen]
+    pub fn from_public_key(public_key: &[u8]) -> Result<WasmECPair, WasmUtxoError> {
+        let public_key = PublicKey::from_slice(public_key)
+            .map_err(|e| WasmUtxoError::new(&format!("Invalid public key: {}", e)))?;
+
+        Ok(WasmECPair {
+            key: ECPairKey::PublicOnly(public_key),
+        })
+    }
+
+    fn from_wif_with_network_check(
+        wif_string: &str,
+        expected_network: Option<crate::bitcoin::NetworkKind>,
+    ) -> Result<WasmECPair, WasmUtxoError> {
+        let private_key = PrivateKey::from_wif(wif_string)
+            .map_err(|e| WasmUtxoError::new(&format!("Invalid WIF: {}", e)))?;
+
+        if let Some(expected) = expected_network {
+            if private_key.network != expected {
+                let network_name = match expected {
+                    crate::bitcoin::NetworkKind::Main => "mainnet",
+                    crate::bitcoin::NetworkKind::Test => "testnet",
+                };
+                return Err(WasmUtxoError::new(&format!(
+                    "Expected {} WIF",
+                    network_name
+                )));
+            }
+        }
+
+        let secp = Secp256k1::new();
+        let secret_key = private_key.inner;
+        let public_key = PublicKey::from_secret_key(&secp, &secret_key);
+
+        Ok(WasmECPair {
+            key: ECPairKey::Private {
+                secret_key,
+                public_key,
+            },
+        })
+    }
+
+    /// Create an ECPair from a WIF string (auto-detects network)
+    #[wasm_bindgen]
+    pub fn from_wif(wif_string: &str) -> Result<WasmECPair, WasmUtxoError> {
+        Self::from_wif_with_network_check(wif_string, None)
+    }
+
+    /// Create an ECPair from a mainnet WIF string
+    #[wasm_bindgen]
+    pub fn from_wif_mainnet(wif_string: &str) -> Result<WasmECPair, WasmUtxoError> {
+        use crate::bitcoin::NetworkKind;
+        Self::from_wif_with_network_check(wif_string, Some(NetworkKind::Main))
+    }
+
+    /// Create an ECPair from a testnet WIF string
+    #[wasm_bindgen]
+    pub fn from_wif_testnet(wif_string: &str) -> Result<WasmECPair, WasmUtxoError> {
+        use crate::bitcoin::NetworkKind;
+        Self::from_wif_with_network_check(wif_string, Some(NetworkKind::Test))
+    }
+
+    /// Get the private key as a Uint8Array (if available)
+    #[wasm_bindgen(getter)]
+    pub fn private_key(&self) -> Option<js_sys::Uint8Array> {
+        self.key
+            .secret_key()
+            .map(|sk| js_sys::Uint8Array::from(&sk.secret_bytes()[..]))
+    }
+
+    /// Get the compressed public key as a Uint8Array (always 33 bytes)
+    #[wasm_bindgen(getter)]
+    pub fn public_key(&self) -> js_sys::Uint8Array {
+        let pk = self.key.public_key();
+        let bytes = pk.serialize();
+        js_sys::Uint8Array::from(&bytes[..])
+    }
+
+    /// Convert to WIF string (mainnet)
+    #[wasm_bindgen]
+    pub fn to_wif(&self) -> Result<String, WasmUtxoError> {
+        self.to_wif_mainnet()
+    }
+
+    /// Convert to mainnet WIF string
+    #[wasm_bindgen]
+    pub fn to_wif_mainnet(&self) -> Result<String, WasmUtxoError> {
+        use crate::bitcoin::NetworkKind;
+        self.to_wif_with_network(NetworkKind::Main)
+    }
+
+    /// Convert to testnet WIF string
+    #[wasm_bindgen]
+    pub fn to_wif_testnet(&self) -> Result<String, WasmUtxoError> {
+        use crate::bitcoin::NetworkKind;
+        self.to_wif_with_network(NetworkKind::Test)
+    }
+
+    fn to_wif_with_network(
+        &self,
+        network: crate::bitcoin::NetworkKind,
+    ) -> Result<String, WasmUtxoError> {
+        let secret_key = self
+            .key
+            .secret_key()
+            .ok_or_else(|| WasmUtxoError::new("Cannot get WIF from public key"))?;
+
+        let private_key = PrivateKey::new(secret_key, network);
+        Ok(private_key.to_wif())
+    }
+}
diff --git a/packages/wasm-utxo/src/wasm/mod.rs b/packages/wasm-utxo/src/wasm/mod.rs
@@ -1,6 +1,7 @@
 mod address;
 mod bip32interface;
 mod descriptor;
+mod ecpair;
 mod fixed_script_wallet;
 mod miniscript;
 mod psbt;
@@ -11,6 +12,7 @@ pub(crate) mod wallet_keys_helpers;
 
 pub use address::AddressNamespace;
 pub use descriptor::WrapDescriptor;
+pub use ecpair::WasmECPair;
 pub use fixed_script_wallet::FixedScriptWalletNamespace;
 pub use miniscript::WrapMiniscript;
 pub use psbt::WrapPsbt;
diff --git a/packages/wasm-utxo/test/ecpair.ts b/packages/wasm-utxo/test/ecpair.ts
