Libauth 3.0.0

Libauth provides a comprehensive suite of low-level and high-level utilities for blockchain development, specifically focused on Bitcoin and Bitcoin Cash ecosystems. High-level utilities are composed from lower-level primitives, allowing developers to remix behavior with minimal maintenance.

The API is organized into several functional domains:

• Address Formats: Encoding and decoding for Base58, Bech32, CashAddress, and related formats.
• Crypto: Hashing (SHA, RIPEMD), HMAC, PBKDF2, and secp256k1 operations.
• Formats: Conversions between Base-N, Base64, Binary Strings, Hex, and various numeric representations (including CompactUint/VarInt and Satoshi values).
• Keys: BIP32 (HD Keys), BIP39 (Mnemonics), WIF, and general key generation/validation.
• P2P Messages: Utilities for decoding P2P messages, handling transactions, and calculating dust thresholds.
• Virtual Machines: Built-in VMs for different instruction sets (BCH, XEC, etc.), debugging tools (assembler/disassembler), and operation combinators.
• Wallet Engine: Advanced features including Bitcoin Cash Metadata Registries (BCMRs), CashAssembly language/compiler, multi-party compilation, and wallet templates.

Libauth provides utilities for managing BIP32-compliant Hierarchical Deterministic (HD) keys. HD keys allow you to generate a structured tree of keys from a single master key.

Key capabilities include:

• Derivation: Create sub-accounts or specific child keys using paths (e.g., deriveHdPath, deriveHdPathRelative).
• Encoding/Decoding: Convert between raw nodes and string formats like extended private keys (xprv) and extended public keys (xpub) using encodeHdPrivateKey, decodeHdPrivateKey, encodeHdPublicKey, and decodeHdPublicKey.
• Identification: Generate identifiers for nodes using hdPrivateKeyToIdentifier or hdPublicKeyToIdentifier.
• Security: Use crackHdPrivateNodeFromHdPublicNodeAndChildPrivateNode to understand the risk where gaining a single non-hardened child private key allows an attacker to derive the parent private key if they also possess the parent extended public key.

Libauth provides support for Virtual Machines (VMs) used by public bitcoin-like networks and stable upgrade proposals.

Key Principles:

• VM Selection: When multiple VMs share similar functionality, Libauth's exported utilities prefer the configuration used by the latest version of the Bitcoin Cash (BCH) VM.
• Upgrade Handling: For pending BCH upgrades with wide consensus and established activation dates, Libauth may upgrade utilities before mainnet activation. In the event of a network split, Libauth attempts to support both sides and may delay selecting a default VM until the split is resolved.
• Deprecation Policy: Libauth generally only maintains support for active VM versions. When an upgrade replaces a previous version without a network split (e.g., BCH_2019_05 being replaced by BCH_2019_11), the older version's specific code paths and flags are removed to maintain code simplicity.

CashAddress-like formats support correcting up to 2 errors using attemptCashAddressFormatErrorCorrection.

CAUTION: Error correction is not fail-safe. If a payload has more than 2 errors, it might be 'corrected' to an incorrect but plausible payload. Never use naive error correction for irreversible actions like sending payments.

For high-stakes data (like secret keys), use a safe failure mode where you prompt the user to review the errors rather than automatically applying the correction.

import { attemptCashAddressFormatErrorCorrection } from '@bitauth/libauth';

const maybeAddress = 'bch-est:qq2azmyyv6dtgczexyalqar70q036yund53jvfde0z';
const result = attemptCashAddressFormatErrorCorrection(maybeAddress);

if (typeof result === 'string') {
  // result is an error message describing where the errors are
  console.error(result);
  return;
}

// result.address contains the corrected address
// result.corrections contains the indices of the corrected characters

To verify a transaction using Bitcoin Cash's latest standard VM, use createVirtualMachineBCH with the standard parameter set to true.

1. Create the VM instance using createVirtualMachineBCH(true).
2. Decode the transaction using decodeTransaction.
3. Decode the source outputs (UTXOs) using decodeTransactionOutputs.
4. Call vm.verify({ sourceOutputs, transaction }).

The verify method returns true if successful, or a string containing the error message if verification fails.

import {
  assertSuccess,
  decodeTransaction,
  decodeTransactionOutputs,
  createVirtualMachineBCH,
} from '@bitauth/libauth';

const vm = createVirtualMachineBCH(true);

/* Decode the transaction, throwing any errors */
const transaction = assertSuccess(decodeTransaction(vmbTest.tx));
/* Decode the serialized outputs, throwing any errors */
const sourceOutputs = assertSuccess(decodeTransactionOutputs(vmbTest.utxos));

// Result is either `true` or an error message (`string`)
const result = vm.verify({ sourceOutputs, transaction });

if (typeof result === 'string') {
  console.error(result);
} else {
  console.log('Transaction verified 🚀');
}