@cryptforge/blockchain-btc

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 @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

$3

The recommended way to use this adapter is through @cryptforge/auth:

`typescript
import { createAuthClient } from '@cryptforge/auth';
import { BitcoinAdapter } from '@cryptforge/blockchain-btc';

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);
`

$3

`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);
`

$3

`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
},
],
},
});

console.log('Signed Transaction:', signedTransaction);
`

$3

`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
// ...
`

$3

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

$3

#### Properties

- chainData: ChainData - Chain metadata
- name: "Bitcoin"
- symbol: "BTC"
- cmc_id: 1 (CoinMarketCap ID)
- decimals: 8

#### Methods

##### deriveKeys(mnemonic: string): Promise

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

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

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>

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

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 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

$3

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

$3

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

MIT