@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.
• OP_RETURN Metadata :Insert optional metadata into the transaction’s outputs using OP_RETURN scripts.
• 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.

1. Create and Sign a PSBT

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

// Variables (example values)
const userAddress = 'tb1qsomeTestnetAddr...';
const userWif = 'cYourPrivateKey...';
const lockingAddress = 'tb1qLockingAddress...';
const lockingAmount = 10_000; // Satoshis
const oxbridgeAmount = 5_000; // Satoshis

const txService = new TransactionService();

(async () => {
  try {
    // define metadata to embed in OP_RETURN
    const metadataParams = {
      receiverAddress: '0xSomeReceiverOnAnotherChain',
      lockedAmount: 1000,
      chainId: 5,            
      baseTokenAmount: 99999,
    };

    // Fee rate can be omitted to automatically fetch a recommended rate
    const feeRate = 5; // sat/vB

    const { txid, rawTxHex } = await txService.createAndSignTransaction(
      userAddress,
      userWif,
      lockingAddress,
      lockingAmount,
      oxbridgeAmount,
      metadataParams,
      feeRate
    );

    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 an Unsigned PSBT

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

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

(async () => {
  try {
    const txService = new TransactionService();
    const { psbtBase64 } = await txService.createUnsignedTransaction(
      userAddress,
      Buffer.from('...someUserPubKey...'), // The user's public key
      lockingAddress,
      lockingAmount,
      oxbridgeAmount,
      {
        receiverAddress: '0xSomeReceiverOnAnotherChain',
        lockedAmount: 1000,
        chainId: 5,
        baseTokenAmount: 99999,
      }
      // feeRate: 5 (Optional)
    );

    console.log('Unsigned PSBT (Base64):', psbtBase64);

    // Later, you or another party can sign the PSBT:
  } catch (err) {
    console.error('Error creating an unsigned transaction:', err);
  }
})();

3. Create a Taproot Script (Multisig + Timelock)

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

// Create dummy key pairs for the user and AVS (vault) signers
const userKeyPair = generateRandomKeyPair();
const avsKeyPair = generateRandomKeyPair();

// Choose a locktime (block height or timestamp)
const locktime = 500_000;

const tapVault = createTaprootScriptWithMultisigAndTimelock(
  userKeyPair.publicKey,
  avsKeyPair.publicKey,
  locktime
);

// Build a Taproot output (address) using the userKeyPair as the internal key
const taprootOutput = createTaprootOutput(
  userKeyPair.publicKey,
  tapVault,
  bitcoin.networks.testnet
);

console.log('Generated Taproot Address:', taprootOutput.taprootAddress);
console.log('Taproot Output Script (hex):', taprootOutput.output?.toString('hex'));

4. 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 {
    // Fetch unspent outputs for a given address
    const utxos = await fetchUtxos(apiConfig, 'tb1qsomeTestnetAddr...');
    console.log('Fetched UTXOs:', utxos);

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

    // Select UTXOs that sum up to at least `needed` satoshis
    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 rate:', err);
  }
})();

5. Broadcasting Transactions

Once a PSBT is finalized (signed and finalizeAllInputs() called), you can broadcast with the built-in method:

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

const txid = await txService.broadcastTransaction(txHex);

console.log('Broadcasted TxID:', txid);

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.