@0xbridge/bitcoin-vault-trial v1.0.3

@0xbridge/bitcoin-vault

@0xbridge/bitcoin-vault is a powerful TypeScript library for creating and signing Bitcoin PSBT transactions, working with Taproot scripts (such as multisig and timelock), and fetching UTXOs via public APIs. It is optimized for Testnet but can be configured for Mainnet or custom networks.

Features

• PSBT Construction: Effortlessly build and sign Bitcoin transactions.
• Taproot Utilities: Support for creating advanced Taproot scripts for multisig and timelock paths.
• UTXO Fetching: Retrieve unspent outputs with automatic fallback using Blockstream or Mempool APIs.
• Fee Estimation: Fetch recommended sat/vB fee rates from public endpoints.
• TypeScript Support: Comprehensive type definitions for safer and easier development.

Project Structure

.
├── src/                # Source code
│   ├── constants.ts    # API endpoints, OP_RETURN messages, and common constants
│   ├── transaction.ts  # Core class for creating and signing PSBTs
│   ├── taproot.ts      # Utilities for building Taproot scripts (multisig, timelock, etc.)
│   ├── utils.ts        # Helper functions like fetchFeeRate, fetchUtxos, and selectUtxos
│   ├── types.ts        # Type definitions for UTXOs, configurations, and more
│   └── index.ts        # Main entry point exporting core modules
│
├── package.json        # Project metadata and dependencies
├── tsconfig.*.json     # TypeScript configurations for different builds
├── README.md           # Documentation (this file)

Note: The dist/ folder is auto-generated after running the build script (npm run build).

Installation

Install the library using your preferred package manager:

npm install @0xbridge/bitcoin-vault

or

yarn add @0xbridge/bitcoin-vault

Usage

Below are examples demonstrating common use cases. For detailed usage, refer to TypeScript definitions or documentation generated by tools like Typedoc.

1. Create and Sign a PSBT

import { TransactionService } from '@0xbridge/bitcoin-vault';

const userAddress = 'tb1qsomeTestnetAddr...';
const userWif = 'cYourPrivateKey...';
const lockingAddress = 'tb1qLockingAddress...';
const lockingAmount = 10_000; // Satoshis
const oxbridgeAmount = 5_000; // Satoshis

(async () => {
  try {
    const txService = new TransactionService();
    const { txid, rawTxHex } = await txService.createAndSignTransaction(
      userAddress,
      userWif,
      lockingAddress,
      lockingAmount,
      oxbridgeAmount,
      metadataParams,
      5 // Optional fee rate (sat/vB)

    );

    console.log('Transaction broadcast successfully!');
    console.log('TXID:', txid);
    console.log('Raw Transaction Hex:', rawTxHex);
  } catch (err) {
    console.error('Error creating or signing transaction:', err);
  }
})();

2. Create a Taproot Script (Multisig + Timelock)

import { createTaprootScriptWithMultisigAndTimelock, createTaprootOutput } from '@0xbridge/bitcoin-vault';
import { generateRandomKeyPair } from '@0xbridge/bitcoin-vault';
import * as bitcoin from 'bitcoinjs-lib';

const userKeyPair = generateRandomKeyPair();
const avsKeyPair = generateRandomKeyPair();
const locktime = 500_000; // Block height or timestamp

const { multisigScript, timelockScript } = createTaprootScriptWithMultisigAndTimelock(
  userKeyPair.publicKey,
  avsKeyPair.publicKey,
  locktime
);

const { address: taprootAddress } = createTaprootOutput(
  userKeyPair.publicKey, // Internal key
  multisigScript,
  timelockScript,
  bitcoin.networks.testnet
);

console.log('Generated Taproot Address:', taprootAddress);

3. Fetch UTXOs and Fee Rates

import { fetchUtxos, fetchFeeRate, selectUtxos } from '@0xbridge/bitcoin-vault';

const apiConfig = {
  primary: 'https://blockstream.info/testnet/api',
  fallback: 'https://mempool.space/testnet/api',
};

(async () => {
  try {
    const utxos = await fetchUtxos(apiConfig, 'tb1qsomeTestnetAddr...');
    console.log('Fetched UTXOs:', utxos);

    const feeRate = await fetchFeeRate(apiConfig);
    console.log('Recommended fee rate (sat/vB):', feeRate);

    const needed = 20_000; // Satoshis
    const { chosenUtxos, totalAmount } = selectUtxos(utxos, needed);
    console.log('Selected UTXOs:', chosenUtxos);
    console.log('Total Amount Found:', totalAmount);
  } catch (err) {
    console.error('Error fetching UTXOs or fee rates:', err);
  }
})();

Additional Information

• TypeScript Support: Fully typed definitions for all library functions.
• Networking: Configurable API endpoints for UTXO fetching and fee estimation.
• Fallbacks: Automatically switches to a fallback API if the primary endpoint fails.