@cryptforge/blockchain-btc 0.1.0 → 0.2.0

package/README.md

@@ -1,42 +1,361 @@
 # @cryptforge/blockchain-btc
 
-Bitcoin blockchain adapter for the CryptForge SDK.
+Bitcoin blockchain adapter for the CryptForge SDK. Provides BIP44-compliant key derivation, address generation, and transaction signing for Bitcoin.
 
 ## Installation
 
 ```bash
-npm install @cryptforge/blockchain-btc
+npm install @cryptforge/blockchain-btc @cryptforge/auth @cryptforge/core
+# or
+pnpm add @cryptforge/blockchain-btc @cryptforge/auth @cryptforge/core
+# or
+yarn add @cryptforge/blockchain-btc @cryptforge/auth @cryptforge/core
 ```
 
+## Quick Start
+
+```typescript
+import { createAuthClient } from '@cryptforge/auth';
+import { BitcoinAdapter } from '@cryptforge/blockchain-btc';
+
+// Create auth client and register Bitcoin adapter
+const auth = createAuthClient();
+auth.registerAdapter('bitcoin', new BitcoinAdapter());
+
+// Generate mnemonic
+const mnemonic = auth.generateMnemonic({ wordCount: 12 });
+
+// Create identity with Bitcoin
+const { identity, keys } = await auth.createIdentity({
+  mnemonic,
+  password: 'secure-password',
+  label: 'My Bitcoin Wallet',
+  chainId: 'bitcoin',
+});
+
+console.log('Bitcoin Address:', keys.address);
+// Example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
+```
+
+## Features
+
+- ✅ **BIP44 Derivation** - Standard Bitcoin derivation path: `m/44'/0'/0'/0/0`
+- ✅ **P2PKH Addresses** - Pay-to-Public-Key-Hash address generation
+- ✅ **Message Signing** - Sign messages with Bitcoin keys
+- ✅ **Transaction Signing** - Sign Bitcoin transactions (UTXO-based)
+- ✅ **HD Wallet Support** - Hierarchical Deterministic wallet key derivation
+- ✅ **Multiple Addresses** - Generate multiple addresses from a single seed
+- ✅ **Type-Safe** - Full TypeScript support
+
 ## Usage
 
+### With @cryptforge/auth (Recommended)
+
+The recommended way to use this adapter is through `@cryptforge/auth`:
+
 ```typescript
+import { createAuthClient } from '@cryptforge/auth';
 import { BitcoinAdapter } from '@cryptforge/blockchain-btc';
-import { setupCryptForgeHandlers } from '@cryptforge/transport-electron/main';
 
-// In your Electron main process or Node.js server
-setupCryptForgeHandlers({
-  blockchainAdapters: {
-    'Bitcoin': new BitcoinAdapter(),
+const auth = createAuthClient();
+auth.registerAdapter('bitcoin', new BitcoinAdapter());
+
+// Unlock wallet
+await auth.unlock({
+  password: 'your-password',
+  chainId: 'bitcoin',
+});
+
+// Get current Bitcoin address
+const address = auth.currentAddress;
+console.log('Address:', address);
+
+// Get multiple addresses
+const addresses = await auth.getAddresses('bitcoin', 0, 5);
+console.log('First 5 addresses:', addresses);
+```
+
+### Sign Message
+
+```typescript
+// Unlock wallet first
+await auth.unlock({
+  password: 'your-password',
+  chainId: 'bitcoin',
+});
+
+// Sign a message
+const { signature, address, publicKey } = await auth.signMessage({
+  message: 'Hello Bitcoin!',
+});
+
+console.log('Signature:', signature);
+console.log('Signed by:', address);
+
+// Verify signature
+const isValid = await auth.verifySignature(
+  'Hello Bitcoin!',
+  signature,
+  publicKey
+);
+console.log('Signature valid:', isValid);
+```
+
+### Sign Transaction
+
+```typescript
+// Unlock wallet first
+await auth.unlock({
+  password: 'your-password',
+  chainId: 'bitcoin',
+});
+
+// Sign a Bitcoin transaction
+const { signedTransaction, signature } = await auth.signTransaction({
+  transaction: {
+    inputs: [
+      {
+        txid: 'previous_transaction_id',
+        index: 0,
+        // ... other input fields
+      },
+    ],
+    outputs: [
+      {
+        address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
+        amount: '100000', // satoshis
+      },
+    ],
   },
-  // ... other options
 });
+
+console.log('Signed Transaction:', signedTransaction);
 ```
 
-## Features
+### Generate Multiple Addresses
+
+```typescript
+// Get addresses at specific indices
+const addresses = await auth.getAddresses('bitcoin', 0, 10);
+
+addresses.forEach((addr) => {
+  console.log(`Index ${addr.index}: ${addr.address}`);
+  console.log(`Path: ${addr.path}`);
+});
+
+// Output:
+// Index 0: 1A1zP1eP5... Path: m/44'/0'/0'/0/0
+// Index 1: 1BvBMSEYs... Path: m/44'/0'/0'/0/1
+// ...
+```
+
+### Direct Adapter Usage (Advanced)
+
+For advanced use cases, you can use the adapter directly:
+
+```typescript
+import { BitcoinAdapter } from '@cryptforge/blockchain-btc';
+
+const adapter = new BitcoinAdapter();
+
+// Derive keys from mnemonic
+const keys = await adapter.deriveKeys(
+  'your twelve word mnemonic phrase here that you backed up safely'
+);
+
+console.log('Address:', keys.address);
+console.log('Public Key:', keys.publicKeyHex);
+console.log('Derivation Path:', keys.path);
+
+// Get address at specific index
+const { address, publicKey, path } = await adapter.getAddressAtIndex(
+  'your twelve word mnemonic phrase here that you backed up safely',
+  5
+);
+
+// Sign message
+const { signature } = await adapter.signMessage(
+  keys.privateKey,
+  'Hello Bitcoin!'
+);
+```
+
+## API Reference
+
+### BitcoinAdapter
+
+#### Properties
+
+- `chainData: ChainData` - Chain metadata
+  - `name: "Bitcoin"`
+  - `symbol: "BTC"`
+  - `cmc_id: 1` (CoinMarketCap ID)
+  - `decimals: 8`
+
+#### Methods
+
+##### `deriveKeys(mnemonic: string): Promise<KeyData>`
+
+Derives Bitcoin keys from a BIP39 mnemonic using path `m/44'/0'/0'/0/0`.
+
+```typescript
+const keys = await adapter.deriveKeys(mnemonic);
+```
+
+##### `deriveKeysAtIndex(mnemonic: string, index: number): Promise<KeyData>`
+
+Derives keys at a specific address index.
+
+```typescript
+const keys = await adapter.deriveKeysAtIndex(mnemonic, 5);
+// Path: m/44'/0'/0'/0/5
+```
+
+##### `deriveKeysAtPath(mnemonic: string, path: string): Promise<KeyData>`
 
-- Derives Bitcoin keys from BIP39 mnemonics
-- Uses BIP44 derivation path: `m/44'/0'/0'/0/0`
-- Generates P2PKH (Pay-to-Public-Key-Hash) addresses
-- Provides chain metadata (name, symbol, CMC ID)
+Derives keys at a custom BIP44 path.
+
+```typescript
+const keys = await adapter.deriveKeysAtPath(mnemonic, "m/44'/0'/1'/0/0");
+```
+
+##### `getAddressAtIndex(mnemonic: string, index: number): Promise<{ address, publicKey, path }>`
+
+Gets address information at a specific index without returning private keys.
+
+```typescript
+const { address, publicKey, path } = await adapter.getAddressAtIndex(
+  mnemonic,
+  0
+);
+```
+
+##### `getAddresses(mnemonic: string, startIndex: number, count: number): Promise<Array<{ address, path, index }>>`
+
+Gets multiple addresses starting from an index.
+
+```typescript
+const addresses = await adapter.getAddresses(mnemonic, 0, 10);
+```
+
+##### `signMessage(privateKey: Uint8Array, message: string | Uint8Array): Promise<{ signature }>`
+
+Signs a message using Bitcoin's double SHA-256 hash.
+
+```typescript
+const { signature } = await adapter.signMessage(
+  keys.privateKey,
+  'Hello Bitcoin!'
+);
+```
+
+##### `signTransaction(privateKey: Uint8Array, transaction: any): Promise<{ signedTransaction, signature }>`
+
+Signs a Bitcoin transaction. Requires UTXO-based transaction structure.
+
+```typescript
+const { signedTransaction, signature } = await adapter.signTransaction(
+  keys.privateKey,
+  {
+    inputs: [{ txid: '...', index: 0 }],
+    outputs: [{ address: '...', amount: '100000' }],
+  }
+);
+```
+
+##### `verifySignature(message: string | Uint8Array, signature: string, publicKey: string): Promise<boolean>`
+
+Verifies a message signature.
+
+```typescript
+const isValid = await adapter.verifySignature(message, signature, publicKey);
+```
+
+## KeyData Type
+
+```typescript
+interface KeyData {
+  mnemonic: string; // BIP39 mnemonic phrase
+  seed: Uint8Array; // BIP39 seed (512 bits)
+  privateKey: Uint8Array; // Private key bytes
+  privateKeyHex: string; // Private key as hex string
+  publicKey: Uint8Array; // Compressed public key (33 bytes)
+  publicKeyHex: string; // Public key as hex string
+  address: string; // Bitcoin P2PKH address
+  path: string; // BIP44 derivation path
+}
+```
+
+## Address Types
+
+This adapter currently supports **P2PKH (Pay-to-Public-Key-Hash)** addresses only. P2PKH addresses:
+- Start with `1` (mainnet) or `m`/`n` (testnet)
+- Are the most common legacy Bitcoin address type
+- Use base58check encoding
+- Example: `1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa`
+
+Future versions may support:
+- P2SH (Pay-to-Script-Hash) - addresses starting with `3`
+- P2WPKH (SegWit) - addresses starting with `bc1q`
+- P2TR (Taproot) - addresses starting with `bc1p`
 
 ## Dependencies
 
-This package includes all necessary Bitcoin-specific dependencies:
-- `bitcoinjs-lib` - Bitcoin protocol implementation
-- `bip32` - HD wallet key derivation
-- `bip39` - Mnemonic generation and validation
-- `tiny-secp256k1` - Elliptic curve cryptography
+This package uses modern, audited Bitcoin libraries:
+
+- **`@scure/bip32`** - BIP32 HD wallet key derivation
+- **`@scure/bip39`** - BIP39 mnemonic generation and validation
+- **`@scure/btc-signer`** - Bitcoin transaction signing
+- **`@noble/hashes`** - Cryptographic hash functions (SHA-256)
+- **`@noble/secp256k1`** - secp256k1 elliptic curve cryptography
+
+All dependencies are minimal, audited, and widely trusted in the Bitcoin ecosystem.
+
+## Limitations
+
+### Not Yet Implemented
+
+The following features are not yet implemented but are planned for future releases:
+
+- **Balance Queries** - `getNativeBalance()`, `getTokenBalances()`
+- **Transaction History** - `getTransactions()`, `getTokenTransfers()`
+- **Transaction Broadcasting** - `sendNativeToken()`, `sendToken()`
+- **Transaction Status** - `getTransactionStatus()`
+
+For these features, please use:
+- Block explorer APIs (Blockstream, Blockchain.com, etc.)
+- Bitcoin RPC providers
+- Bitcoin wallet SDKs
+
+### UTXO Management
+
+Bitcoin uses a UTXO (Unspent Transaction Output) model, which is more complex than account-based models (like Ethereum). When building a transaction, you need to:
+
+1. Select appropriate UTXOs (inputs)
+2. Calculate transaction fees
+3. Handle change outputs
+4. Manage different address types
+
+Consider using specialized Bitcoin libraries or services for production applications.
+
+## Browser Compatibility
+
+This package is **100% browser-compatible**:
+
+- ✅ Chrome, Firefox, Safari, Edge
+- ✅ Node.js (v16+)
+- ✅ Electron (main and renderer)
+- ✅ React Native
+- ✅ Web Workers
+
+Uses only browser-safe cryptography with no Node.js dependencies.
+
+## Examples
+
+See working examples in:
+- `examples/vue-electron-example/src/AuthTest.vue` - Complete integration with @cryptforge/auth
+
+## License
 
-These dependencies are only added to your project if you install this package.
+MIT
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cryptforge/blockchain-btc",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Bitcoin blockchain adapter for CryptForge SDK",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -49,10 +49,10 @@
     "@noble/secp256k1": "^2.0.0"
   },
   "peerDependencies": {
-    "@cryptforge/core": "^0.1.0"
+    "@cryptforge/core": "workspace:*"
   },
   "devDependencies": {
-    "@cryptforge/core": "^0.1.0",
+    "@cryptforge/core": "workspace:*",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3"
   }