bip388

TypeScript library for building Bitcoin scripts and BIP-388 wallet policies, with first-class support for Ledger hardware wallets.

Install

npm install bip388

Features

• BIP-388 Wallet Policies - Descriptor templates with key placeholders for Ledger registration
• BIP-379 Miniscript - Typesafe miniscript fragment builders
• HTLCs - Hash Time-Locked Contracts for both Taproot and SegWit
• Multisig - k-of-n multisig for Taproot and SegWit

Quick Start

Taproot HTLC

import { taprootHtlc } from "bip388";

const htlc = taprootHtlc({
  payee: {
    xpub: "tpub...",
    fingerprint: "3442193e",
    originPath: "86'/1'/0'",
  },
  payer: {
    xpub: "tpub...",
    fingerprint: "3442193e",
    originPath: "86'/1'/1'",
  },
  secretHash: "deadbeef...",
  timelock: 800000,
  network: "testnet",
});

// Address to fund
console.log(htlc.address);

// BIP-388 policy for Ledger
console.log(htlc.policy?.template);
// => tr(@0/**,{and_v(v:sha256(...),pk(@1/**)),and_v(v:after(800000),pk(@2/**))})

// Witness for spending with preimage
const witness = htlc.witness.secret(signature, preimage);

// Witness for timeout refund
const witness = htlc.witness.timeout(signature);

SegWit HTLC

import { segwitHtlc } from "bip388";

const htlc = segwitHtlc({
  payee: { xpub: "tpub...", fingerprint: "...", originPath: "..." },
  payer: { xpub: "tpub...", fingerprint: "...", originPath: "..." },
  secretHash: "deadbeef...",
  timelock: 800000,
  network: "testnet",
});

console.log(htlc.address); // tb1q...

Taproot Multisig (2-of-3)

import { taprootMultisig } from "bip388";

const multisig = taprootMultisig({
  threshold: 2,
  keys: [
    { xpub: "tpub...", fingerprint: "...", originPath: "..." },
    { xpub: "tpub...", fingerprint: "...", originPath: "..." },
    { xpub: "tpub...", fingerprint: "...", originPath: "..." },
  ],
  network: "testnet",
});

console.log(multisig.address);
console.log(multisig.policy?.template);
// => tr(@0/**,sortedmulti_a(2,@1/**,@2/**,@3/**))

// Build witness with signatures (empty buffer for non-signers)
const witness = multisig.witness([sig1, sig2, Buffer.alloc(0)]);

SegWit Multisig

import { segwitMultisig } from "bip388";

const multisig = segwitMultisig({
  threshold: 2,
  keys: [key1, key2, key3],
  network: "testnet",
});

console.log(multisig.policy?.template);
// => wsh(sortedmulti(2,@0/**,@1/**,@2/**))

Key Types

Keys can be either XpubKey (for BIP-388 policy generation) or RawKey (just a pubkey):

// XpubKey - enables BIP-388 policy generation
const xpubKey: XpubKey = {
  xpub: "tpub...",
  fingerprint: "3442193e", // master fingerprint
  originPath: "86'/1'/0'", // derivation path
  index: 0, // optional, default 0
  change: 0, // optional, 0=receive, 1=change
};

// RawKey - no policy generated
const rawKey: RawKey = {
  pubkey: "02abc...", // 33-byte compressed or 32-byte x-only
};

When all keys are XpubKey, a WalletPolicy is generated for Ledger registration. When using RawKey, policy will be null.

Miniscript Fragments

Build miniscript expressions directly:

import { pk, sha256, and_v, or_i, older, after, multi_a } from "bip388";

// pk(@0/**)
pk(keyPlaceholder(0));

// and_v(v:sha256(H),pk(@0/**))
and_v(sha256("deadbeef..."), pk(keyPlaceholder(0)));

// or_i(and_v(v:sha256(H),pk(@0/**)),and_v(v:after(144),pk(@1/**)))
or_i(
  and_v(sha256("..."), pk(keyPlaceholder(0))),
  and_v(after(144), pk(keyPlaceholder(1))),
);

// multi_a(2,@0/**,@1/**,@2/**) - Taproot
multi_a(2, [keyPlaceholder(0), keyPlaceholder(1), keyPlaceholder(2)]);

Low-Level Scripts

For direct Bitcoin Script building:

import {
  pkScript,
  pkhScript,
  multiScript,
  cltvScript,
  csvScript,
} from "bip388";

// <pubkey> OP_CHECKSIG
pkScript(pubkey);

// OP_DUP OP_HASH160 <hash> OP_EQUALVERIFY OP_CHECKSIG
pkhScript(pubkey);

// OP_2 <key1> <key2> <key3> OP_3 OP_CHECKMULTISIG
multiScript(2, [key1, key2, key3]);

// <time> OP_CHECKLOCKTIMEVERIFY OP_DROP <pubkey> OP_CHECKSIG
cltvScript(pubkey, locktime);

// <blocks> OP_CHECKSEQUENCEVERIFY OP_DROP <pubkey> OP_CHECKSIG
csvScript(pubkey, blocks);

API Reference

Pattern Builders

| Function | Description | | ------------------------- | ------------------------------------------ | | taprootHtlc(params) | Taproot HTLC with secret and timeout paths | | segwitHtlc(params) | SegWit P2WSH HTLC | | taprootMultisig(params) | Taproot k-of-n multisig | | segwitMultisig(params) | SegWit P2WSH k-of-n multisig |

BIP-388 Builders

| Function | Description | | ---------------------- | -------------------------------------- | | buildTaprootPolicy() | Build a tr() wallet policy | | buildSegwitPolicy() | Build a wsh() wallet policy | | keyPlaceholder(n) | Create @n/** key placeholder | | formatKeyInfo() | Format key as [fingerprint/path]xpub |

Miniscript Fragments

| Function | Description | | ------------------------ | ------------------------- | | pk(key) | Public key check | | sha256(hash) | SHA256 preimage check | | and_v(left, right) | Verify AND | | or_i(left, right) | IF/ELSE OR | | older(blocks) | Relative timelock (CSV) | | after(time) | Absolute timelock (CLTV) | | multi(k, keys) | k-of-n multisig (SegWit) | | multi_a(k, keys) | k-of-n multisig (Taproot) | | sortedmulti(k, keys) | Sorted k-of-n (SegWit) | | sortedmulti_a(k, keys) | Sorted k-of-n (Taproot) |

License

MIT