@vbyte/btc-dev 2.0.0 → 2.1.0

package/docs/CONVENTIONS.md

@@ -0,0 +1,316 @@
+# Code Conventions
+
+Coding conventions for the btc-dev Bitcoin development library. Reference this when writing or editing code.
+
+## Quick Reference
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Functions | `snake_case` | `encode_address`, `parse_witness`, `create_tx_input` |
+| Variables | `snake_case` | `txid`, `witness`, `sequence`, `prevout` |
+| Types/Interfaces | `PascalCase` | `TxData`, `AddressInfo`, `SigHashOptions` |
+| Constants | `SCREAMING_SNAKE_CASE` | `SIGHASH_DEFAULT`, `COINBASE`, `LOCK_SCRIPT_TYPE` |
+| Files | `snake_case.ts` | `encode.ts`, `parse.ts`, `create.ts` |
+| Directories | `snake_case` | `address/`, `script/`, `tx/`, `signer/` |
+
+## Naming Conventions
+
+### Functions and Variables
+
+Use `snake_case` for all functions, variables, and object properties:
+
+```typescript
+// Functions
+export function create_tx_input(config: TxInputTemplate) { }
+export function sign_segwit_tx(seckey: string, txdata: TxData) { }
+
+// Variables
+const sequence = normalize_sequence(config.sequence)
+const witness  = config.witness ?? []
+const prevout  = normalize_prevout(config.prevout)
+```
+
+### Types and Interfaces
+
+Use `PascalCase` with semantic suffixes:
+
+| Suffix | Purpose | Example |
+|--------|---------|---------|
+| `Config` | User-provided configuration | `TaprootConfig`, `AddressConfig` |
+| `Template` | Input structure for creation | `TxTemplate`, `TxInputTemplate` |
+| `Data` | Generic data structure | `TxData`, `TxDecodedData` |
+| `Info` | Enriched/parsed information | `AddressInfo`, `ScriptInfo` |
+| `Options` | Optional parameters | `SigHashOptions` |
+
+```typescript
+// Template (user input for creation)
+export interface TxInputTemplate extends TxOutpoint {
+  coinbase?   : string   | null
+  prevout?    : TxOutput | null
+  script_sig? : string   | null
+  sequence?   : number
+  witness?    : string[]
+}
+
+// Data (normalized output)
+export interface TxData {
+  locktime : number
+  vin      : TxInput[]
+  vout     : TxOutput[]
+  version  : number
+}
+
+// Options (configuration for operations)
+export interface SigHashOptions {
+  extension?     : string
+  sigflag?       : number
+  txindex?       : number
+  pubkey?        : string
+  script?        : string
+}
+```
+
+### Constants
+
+Use `SCREAMING_SNAKE_CASE`:
+
+```typescript
+export const SIGHASH_DEFAULT = 0x01
+export const TAPLEAF_DEFAULT_VERSION = 0xc0
+
+// Grouped constants use nested objects
+export const COINBASE = {
+  TXID : '00'.repeat(32),
+  VOUT : 0xFFFFFFFF,
+}
+
+export const LOCK_SCRIPT_TYPE = {
+  P2PKH    : 'p2pkh',
+  P2SH     : 'p2sh',
+  P2WPKH   : 'p2wpkh',
+  P2WSH    : 'p2wsh',
+  P2TR     : 'p2tr',
+  OPRETURN : 'opreturn',
+} as const
+```
+
+## API Namespace Pattern
+
+Each module exports a namespace using `export * as NAMESPACE`:
+
+```typescript
+// src/index.ts
+export * as ADDRESS from './lib/address/index.js'
+export * as SCRIPT  from './lib/script/index.js'
+export * as SIGNER  from './lib/signer/index.js'
+export * as TX      from './lib/tx/index.js'
+
+export * as CONST  from './const.js'
+export * as SCHEMA from './schema/index.js'
+
+export type * from './types/index.js'
+```
+
+**Usage pattern:**
+```typescript
+import { ADDRESS, TX, SCRIPT } from '@vbyte/btc-dev'
+
+// Access module functions via namespace
+const address_info = ADDRESS.P2PKH.decode(address)
+const tx_data      = TX.create_tx(template)
+const script_hex   = SCRIPT.encode_script(script)
+```
+
+## Import Organization
+
+Three groups in order, with aligned `from` keywords:
+
+```typescript
+// 1. External dependencies
+import { Buff }            from '@vbyte/buff'
+import { Assert }          from '@vbyte/util'
+import { ECC }             from '@vbyte/crypto'
+import { schnorr }         from '@noble/curves/secp256k1'
+
+// 2. Internal imports (path alias)
+import { COINBASE, DEFAULT }   from '@/const.js'
+import { parse_tx }            from '@/lib/tx/parse.js'
+import { hash_segwit_tx }      from '@/lib/sighash/segwit.js'
+
+// 3. Type imports (separate block)
+import type {
+  TxData,
+  TxInputTemplate,
+  SigHashOptions
+} from '@/types/index.js'
+```
+
+### Path Aliases
+
+| Alias | Resolves To | Used In |
+|-------|-------------|---------|
+| `@/`  | `src/`      | All code (`src/`, `test/`) |
+
+```typescript
+// In src/ files
+import { DEFAULT } from '@/const.js'
+
+// In test/ files
+import { TX } from '@/index.js'
+```
+
+## Export Patterns
+
+```typescript
+// Flat re-exports in index.ts
+export * from './encode.js'
+export * from './decode.js'
+export * from './parse.js'
+
+// Namespaced exports for modules
+export * as SCHEMA from './schema/index.js'
+
+// Type-only exports
+export type * from './types/index.js'
+```
+
+## Error Handling
+
+### Assertions
+
+Use `Assert` from `@vbyte/util`:
+
+```typescript
+import { Assert } from '@vbyte/util'
+
+Assert.exists(config.prevout, 'prevout is required')
+Assert.is_empty(config.coinbase, 'coinbase is not allowed')
+```
+
+### Zod Validation
+
+Use Zod schemas for runtime validation:
+
+```typescript
+import { z } from 'zod'
+
+export const tx_output = z.object({
+  value     : z.bigint().min(0n).max(2_100_000_000_000_000n),
+  script_pk : hex,
+}) satisfies z.ZodType<TxOutput>
+
+export const tx_input = z.object({
+  coinbase   : hex.nullable(),
+  txid       : hex32,
+  vout       : uint,
+  prevout    : tx_output.nullable(),
+  script_sig : hex.nullable(),
+  sequence   : uint,
+  witness    : z.array(hex)
+})
+```
+
+## Formatting
+
+### Vertical Alignment
+
+Align colons in interfaces, objects, and parameters:
+
+```typescript
+// Interface properties
+export interface TxSize {
+  base   : number
+  total  : number
+  vsize  : number
+  weight : number
+}
+
+// Function parameters
+export function sign_segwit_tx (
+  seckey  : string,
+  txdata  : TxData,
+  options : SigHashOptions,
+) : string { }
+
+// Object literals
+const input = {
+  txid       : config.txid,
+  vout       : config.vout,
+  prevout    : normalize_prevout(config.prevout),
+  sequence   : normalize_sequence(config.sequence),
+  witness    : config.witness ?? []
+}
+```
+
+### Indentation
+
+- 2 spaces (no tabs)
+- Multi-line parameters aligned
+
+### Numbers
+
+Use underscores for readability:
+
+```typescript
+const MAX_SATS = 2_100_000_000_000_000n
+const TIMEOUT_MS = 30_000
+```
+
+### File Extensions
+
+Always use `.js` in imports (ES module compatibility):
+
+```typescript
+import { DEFAULT } from '@/const.js'
+import type { TxData } from '../types/index.js'
+```
+
+## Domain Abbreviations
+
+| Abbrev | Meaning |
+|--------|---------|
+| `psbt` | Partially Signed Bitcoin Transaction |
+| `txid` | Transaction ID (hex string) |
+| `utxo` | Unspent Transaction Output |
+| `sats` | Satoshis (1 BTC = 100,000,000 sats) |
+| `vout` | Output index in transaction |
+| `vin` | Input index in transaction |
+| `tx` | Transaction |
+| `sig` | Signature |
+| `seckey` | Secret/private key |
+| `pubkey` | Public key |
+| `script_pk` | Script pubkey (locking script) |
+| `script_sig` | Script signature (unlocking script) |
+| `prevout` | Previous output (spent by input) |
+| `segwit` | Segregated Witness |
+| `taproot` | Taproot (BIP340/341/342) |
+
+## Comments
+
+- Explain "why" not "what"
+- Use `//` with space, sentence case
+- JSDoc for exported functions
+
+```typescript
+/**
+ * Sign a transaction input using segwit (BIP143) signature hashing.
+ * @param seckey  - 32-byte secret key as hex string (64 characters)
+ * @param txdata  - Transaction data
+ * @param options - Sighash options including txindex, sigflag, pubkey/script
+ * @returns ECDSA signature with sighash flag appended
+ * @throws Error if secret key format is invalid
+ */
+export function sign_segwit_tx (
+  seckey  : string,
+  txdata  : TxData,
+  options : SigHashOptions,
+) {
+  // Validate inputs before processing.
+  validate_seckey(seckey)
+  validate_sighash_options(options, SIGHASH_SEGWIT)
+  // Hash and sign the transaction.
+  const tx  = parse_tx(txdata)
+  const msg = hash_segwit_tx(tx, options)
+  return ECC.sign_ecdsa(seckey, msg).hex + format_sigflag(options.sigflag)
+}
+```

package/docs/FAQ.md

@@ -0,0 +1,396 @@
+# Frequently Asked Questions
+
+Common questions and troubleshooting for `@vbyte/btc-dev`.
+
+## Installation
+
+### Why can't I import the library?
+
+**ESM Only**: This library is ESM-only. Make sure your project is configured for ESM:
+
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+Or use the `.mjs` extension for your files.
+
+### Can I use this with CommonJS?
+
+The library provides a CommonJS build at `dist/main.cjs`, but ESM is recommended. For CommonJS:
+
+```javascript
+const { ADDRESS, TX } = require('@vbyte/btc-dev')
+```
+
+### Can I use this in a browser?
+
+Yes. Use the UMD bundle:
+
+```html
+<script src="https://unpkg.com/@vbyte/btc-dev/dist/script.js"></script>
+<script>
+  const { ADDRESS, TX } = btcDev
+</script>
+```
+
+Or use a bundler like Vite, Webpack, or Rollup with the ESM imports.
+
+## TypeScript
+
+### What TypeScript version is required?
+
+TypeScript 5.0 or later is recommended. The library uses strict mode.
+
+### How do I import types?
+
+```typescript
+import type { TxData, AddressInfo, SigHashOptions } from '@vbyte/btc-dev'
+```
+
+### Why am I getting type errors?
+
+Make sure your `tsconfig.json` has:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2020"
+  }
+}
+```
+
+## Addresses
+
+### Which address type should I use?
+
+- **P2WPKH** (`bc1q...`): Best for single-signature wallets. Good balance of efficiency and compatibility.
+- **P2TR** (`bc1p...`): Best for privacy and future-proofing. Some older wallets don't support it yet.
+- **P2WSH**: For multisig or complex scripts.
+- **P2PKH/P2SH**: Only for legacy compatibility.
+
+### Why does my address look different on testnet?
+
+Testnet uses different prefixes:
+
+| Type | Mainnet | Testnet |
+|------|---------|---------|
+| P2WPKH | `bc1q...` | `tb1q...` |
+| P2TR | `bc1p...` | `tb1p...` |
+
+Always specify the correct network: `'main'` or `'test'`.
+
+### How do I convert a compressed pubkey to x-only for taproot?
+
+Remove the first byte (02 or 03):
+
+```typescript
+const compressed = '02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c'
+const xOnly = compressed.slice(2)  // Remove 02/03 prefix
+```
+
+## Transactions
+
+### Why does my signature verification fail?
+
+Common causes:
+
+1. **Wrong prevout data**: The prevout value and script must match exactly
+2. **Wrong pubkey**: For P2WPKH, use the compressed public key
+3. **Wrong sighash flag**: Make sure signing and verification use the same flag
+4. **Missing witness**: Add the witness data after signing
+
+```typescript
+// Check prevout is correct
+console.log('Prevout value:', tx.vin[0].prevout.value)
+console.log('Prevout script:', tx.vin[0].prevout.script_pk)
+
+// Verify witness is added
+console.log('Witness:', tx.vin[0].witness)
+```
+
+### How do I calculate the transaction fee?
+
+```typescript
+const inputTotal = tx.vin.reduce((sum, vin) => sum + vin.prevout.value, 0n)
+const outputTotal = tx.vout.reduce((sum, vout) => sum + vout.value, 0n)
+const fee = inputTotal - outputTotal
+```
+
+### What's the difference between size, vsize, and weight?
+
+- **Size**: Raw byte count
+- **Weight**: Size calculation that discounts witness data (base * 4 + witness)
+- **vSize**: Virtual size = weight / 4, used for fee calculation
+
+Always use `vsize` for fee estimation.
+
+### Why is my transaction rejected as "dust"?
+
+Outputs below the dust limit (~546 sats for P2PKH, ~294 for P2WPKH) are rejected. Increase the output value.
+
+### How do I enable RBF (Replace-By-Fee)?
+
+Set sequence to less than 0xfffffffe on at least one input:
+
+```typescript
+{
+  txid: '...',
+  vout: 0,
+  sequence: 0xfffffffd  // RBF enabled
+}
+```
+
+## Signing
+
+### What format should the secret key be?
+
+A 64-character hex string (32 bytes):
+
+```typescript
+const secretKey = 'abcd1234...'.repeat(8)  // 64 hex chars
+```
+
+### Why do I get "Invalid secret key format"?
+
+The secret key must be:
+- A string (not Buffer or Uint8Array)
+- Exactly 64 hex characters
+- Valid hex (0-9, a-f, A-F)
+
+### What's the difference between segwit and taproot signing?
+
+- **Segwit** (`sign_segwit_tx`): Uses ECDSA signatures, requires compressed pubkey
+- **Taproot** (`sign_taproot_tx`): Uses Schnorr signatures, uses x-only pubkeys
+
+### How do I sign multiple inputs?
+
+Sign each input separately:
+
+```typescript
+for (let i = 0; i < tx.vin.length; i++) {
+  const sig = SIGNER.sign_segwit_tx(secretKey, tx, {
+    txindex: i,
+    pubkey: pubkeys[i],
+    sigflag: 0x01
+  })
+  tx.vin[i].witness = [sig, pubkeys[i]]
+}
+```
+
+## Taproot
+
+### When should I use key-path vs script-path?
+
+- **Key-path**: Single signer, no complex conditions (cheapest, most private)
+- **Script-path**: Multisig, timelocks, or alternative spending conditions
+
+### Do I need to tweak the secret key?
+
+For key-path spending, yes:
+
+```typescript
+import { tweak_seckey } from '@vbyte/crypto/ecc'
+const taptweak = TAPROOT.encode_taptweak(internalPubkey, merkleRoot)
+const tweakedSeckey = tweak_seckey(internalSeckey, taptweak, true)
+```
+
+For script-path, use the original key for the script, not the tweaked key.
+
+### What's a control block?
+
+A control block proves that a script is part of the taproot tree. It contains:
+- Leaf version and parity byte
+- Internal public key
+- Merkle path (sibling hashes)
+
+## Scripts
+
+### How do I detect the script type of an output?
+
+```typescript
+import { SCRIPT } from '@vbyte/btc-dev'
+
+const type = SCRIPT.get_lock_script_type(scriptPubKey)
+// Returns: 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr' | 'opreturn' | null
+```
+
+### How do I create a multisig script?
+
+```typescript
+// 2-of-3 multisig
+import { SCRIPT } from '@vbyte/btc-dev'
+
+const script = SCRIPT.encode([
+  'OP_2',
+  pubkey1,
+  pubkey2,
+  pubkey3,
+  'OP_3',
+  'OP_CHECKMULTISIG'
+])
+```
+
+## Error Handling
+
+### What error types does the library throw?
+
+The library provides three custom error classes for better error handling:
+
+```typescript
+import { ValidationError, DecodingError, ConfigError } from '@vbyte/btc-dev'
+
+try {
+  const tx = TX.decode(malformedData)
+} catch (err) {
+  if (err instanceof DecodingError) {
+    console.log('Malformed data at position:', err.position)
+  } else if (err instanceof ValidationError) {
+    console.log('Invalid input field:', err.field)
+  } else if (err instanceof ConfigError) {
+    console.log('Configuration error:', err.message)
+  }
+}
+```
+
+| Error Class | When Thrown | Properties |
+|-------------|-------------|------------|
+| `ValidationError` | Invalid input format, wrong length, type mismatch | `field?: string` |
+| `DecodingError` | Malformed data, truncated input, invalid structure | `position?: number` |
+| `ConfigError` | Invalid sigflag, unknown network, bad configuration | - |
+
+### How do I catch specific errors?
+
+Use `instanceof` to check the error type:
+
+```typescript
+try {
+  SIGNER.sign_segwit_tx('invalid', tx, options)
+} catch (err) {
+  if (err instanceof ValidationError) {
+    // Handle invalid secret key format
+    console.log(`Validation failed for: ${err.field}`)
+  }
+}
+```
+
+### Which functions throw which errors?
+
+**ValidationError:**
+- `sign_segwit_tx`, `sign_taproot_tx` - Invalid secret key format
+- Most functions with input validation
+
+**DecodingError:**
+- `decode_tx` - Malformed transaction data
+- `decode_script` - Invalid script (truncated pushdata, invalid opcodes)
+
+**ConfigError:**
+- `sign_segwit_tx`, `sign_taproot_tx` - Invalid sigflag
+- Address functions - Unknown network
+
+### How do I handle errors gracefully?
+
+```typescript
+function safeDecode(hexData: string) {
+  try {
+    return { success: true, data: TX.decode(hexData) }
+  } catch (err) {
+    if (err instanceof DecodingError) {
+      return { success: false, error: `Decode error at ${err.position}: ${err.message}` }
+    }
+    return { success: false, error: err instanceof Error ? err.message : 'Unknown error' }
+  }
+}
+```
+
+## Security
+
+### Is this library audited?
+
+The cryptographic operations use audited libraries (`@noble/curves`, `@noble/hashes`). The Bitcoin-specific code has comprehensive tests but hasn't undergone a formal audit.
+
+### How do I securely handle private keys?
+
+Key points:
+- Never log or expose secret keys
+- Clear from memory when possible
+- Use cryptographically secure random number generation
+
+See the [Security Best Practices section in the Guide](GUIDE.md#security-best-practices) for detailed examples.
+
+### What transaction size limits are enforced?
+
+The library enforces limits to prevent denial-of-service attacks:
+
+- **Maximum transaction size**: 4MB (Bitcoin consensus limit)
+- **Maximum varint size**: 10MB (prevents memory exhaustion)
+- **Maximum inputs/outputs**: 100,000 per transaction
+- **Maximum taproot tree depth**: 128 levels
+
+These limits are enforced automatically during decoding.
+
+### What are the known limitations?
+
+1. **OP_CODESEPARATOR**: Not fully supported in segwit scripts. The library will throw if encountered.
+
+2. **P2SH-wrapped scripts**: Legacy P2SH spending is not fully implemented. Use native segwit (P2WPKH/P2WSH) instead.
+
+3. **Multi-signature**: Complex multi-sig scripts require manual construction and may need custom handling.
+
+### What cryptographic dependencies does this library use?
+
+This library depends on well-maintained, audited cryptographic libraries:
+
+- `@noble/curves` - Audited cryptographic library for elliptic curves
+- `@noble/hashes` - Audited hash functions
+- `@scure/btc-signer` - Bitcoin signing utilities from the same author
+
+Keep dependencies updated:
+
+```bash
+npm audit
+npm update
+```
+
+## Debugging
+
+### How do I inspect a raw transaction?
+
+```typescript
+import { TX, SCRIPT } from '@vbyte/btc-dev'
+
+const tx = TX.parse(rawTxHex)
+
+console.log('Version:', tx.version)
+console.log('Locktime:', tx.locktime)
+
+tx.vin.forEach((vin, i) => {
+  console.log(`Input ${i}:`, vin.txid, vin.vout)
+})
+
+tx.vout.forEach((vout, i) => {
+  const type = SCRIPT.get_lock_script_type(vout.script_pk)
+  console.log(`Output ${i}:`, vout.value.toString(), 'sats', type)
+})
+```
+
+### How do I decode a witness?
+
+```typescript
+import { WITNESS } from '@vbyte/btc-dev'
+
+const data = WITNESS.parse(tx.vin[0].witness)
+console.log('Type:', data.type)
+console.log('Version:', data.version)
+console.log('Params:', data.params)
+```
+
+## Getting Help
+
+- Check [GitHub Issues](https://github.com/cmdruid/btc-dev/issues)
+- Read the [API Reference](API.md)
+- See the [Guide](GUIDE.md) for tutorials and examples