Bitcoin blockchain adapter for CryptForge SDK
npm install @cryptforge/blockchain-btcBitcoin blockchain adapter for the CryptForge SDK. Provides BIP44-compliant key derivation, address generation, and transaction signing for Bitcoin.
``bash`
npm install @cryptforge/blockchain-btc @cryptforge/auth @cryptforge/coreor
pnpm add @cryptforge/blockchain-btc @cryptforge/auth @cryptforge/coreor
yarn add @cryptforge/blockchain-btc @cryptforge/auth @cryptforge/core
`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
`
- ✅ 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
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);
`
`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);
`
`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);
`
`typescript
// Get addresses at specific indices
const addresses = await auth.getAddresses('bitcoin', 0, 10);
addresses.forEach((addr) => {
console.log(Index ${addr.index}: ${addr.address});Path: ${addr.path}
console.log();
});
// Output:
// Index 0: 1A1zP1eP5... Path: m/44'/0'/0'/0/0
// Index 1: 1BvBMSEYs... Path: m/44'/0'/0'/0/1
// ...
`
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!'
);
`
#### Properties
- chainData: ChainData - Chain metadataname: "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);
`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
}
This adapter currently supports P2PKH (Pay-to-Public-Key-Hash) addresses only. P2PKH addresses:
- Start with 1 (mainnet) or m/n (testnet)1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
- Are the most common legacy Bitcoin address type
- Use base58check encoding
- Example:
Future versions may support:
- P2SH (Pay-to-Script-Hash) - addresses starting with 3bc1q
- P2WPKH (SegWit) - addresses starting with bc1p
- P2TR (Taproot) - addresses starting with
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.
The following features are not yet implemented but are planned for future releases:
- Balance Queries - getNativeBalance(), getTokenBalances()getTransactions()
- Transaction History - , getTokenTransfers()sendNativeToken()
- Transaction Broadcasting - , sendToken()getTransactionStatus()
- Transaction Status -
For these features, please use:
- Block explorer APIs (Blockstream, Blockchain.com, etc.)
- Bitcoin RPC providers
- Bitcoin wallet SDKs
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.
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.
See working examples in:
- examples/vue-electron-example/src/AuthTest.vue` - Complete integration with @cryptforge/auth
MIT