Unchained Capital Bitcoin Utilities


This library builds on the excellent
bitcoinjs-lib, adding
valuable but missing functionality for validation, HD wallets, block
explorers, and especially multisig.

Full API documentation can be found at
@caravan/bitcoin.

This library was built and is maintained by Unchained
Capital.

Installation

@caravan/bitcoin is distributed as an NPM package. Add it to your
application's dependencies:

``
$ npm install --save @caravan/bitcoin
`

Usage

The library provides a functional API which builds upon data
structures used by bitcoinjs-lib.

In particular, many functions accept a Multisig object which is the
type name given by this library to the kind of object returned by
functions such as bitcoin.payments.p2ms, bitcoin.payments.p2sh,
&c. from bitcoinjs-lib.

The examples below provide an initial idea of how to use this library.

$3

#### Generating multisigs

Multisig objects can be generated with two functions:

- generateMultisigFromPublicKeys -- useful when directly passing public keys
- generateMultisigFromHex -- useful when parsing an existing redeem/witness script

Each of these functions accepts additional arguments which determines
the multisig address type (e.g. P2SH or P2WSH).

> Important: Public Key Ordering
>
> generateMultisigFromPublicKeys uses public keys in the order they are passed.
> If you need sortedmulti compatibility (required by most hardware wallets including
> Ledger and Trezor, and standard in wallet descriptors), you must sort the public
> keys lexicographically before passing them to this function:
>
> `javascript
> const sortedPublicKeys = [...publicKeys].sort();
> const multisig = generateMultisigFromPublicKeys(network, addressType, m, ...sortedPublicKeys);
> `
>
> Failing to sort will generate a valid multisig address, but it will be different
> from the address generated by hardware wallets and other software expecting sortedmulti.

`javascript
import {
generateMultisigFromPublicKeys,
generateMultisigFromHex,
P2SH, // or: P2SH_P2WSH, P2WSH,
TESTNET, // or: MAINNET,
multisigAddress,
} from "@caravan/bitcoin";

// Public keys are represented as compressed hex.
const publicKeys = [
"02a8513d9931896d5d3afc8063148db75d8851fd1fc41b1098ba2a6a766db563d4",
"03938dd09bf3dd29ddf41f264858accfa40b330c98e0ed27caf77734fac00139ba",
];

// Sort public keys for sortedmulti compatibility (recommended)
const sortedPublicKeys = [...publicKeys].sort();

// A testnet P2SH 2-of-2 multisig.
const m1 = generateMultisigFromPublicKeys(TESTNET, P2SH, 2, ...sortedPublicKeys);
console.log(multisigAddress(m1))
// 2N5KgAnFFpmk5TRMiCicRZDQS8FFNCKqKf1

const redeemScript = "522102a8513d9931896d5d3afc8063148db75d8851fd1fc41b1098ba2a6a766db563d42103938dd09bf3dd29ddf41f264858accfa40b330c98e0ed27caf77734fac00139ba52ae";
// Same as m1 but using redeem script
const m2 = generateMultisigFromHex(TESTNET, P2SH, redeemScript);
console.log(multisigAddress(m2))
// 2N5KgAnFFpmk5TRMiCicRZDQS8FFNCKqKf1
`

#### Querying multisigs

Multisig objects can be passed around and queried with other
functions in the API.

`javascript
multisigAddress(multisig); // Returns public address
multisigAddressType(multisig); // P2SH
multisigRequiredSigners(multisig); // 2
multisigTotalSigners(multisig); // 3
multisigScript(multisig); // Returns redeem OR witness script, as appropriate
multisigRedeemScript(multisig); // Returns redeem script in hex (null for P2WSH)
multisigWitnessScript(multisig); // Returns witness script in hex (null for P2SH)
multisigPublicKeys(multisig); // Returns publicKeys
`

#### Multisig Transactions

Multisig objects can be used to draft signed or unsigned
transactions and to validate transaction signatures.

`javascript
import {
generateMultisigFromPublicKeys,
TESTNET,
P2SH,
unsignedMultisigTransaction,
validateMultisigSignature,
} from "@caravan/bitcoin";
// Spending 3 UTXOs from the same multisig address.

// First build the multisig for the address.
const publicKeys = [
"02a8513d9931896d5d3afc8063148db75d8851fd1fc41b1098ba2a6a766db563d4",
"03938dd09bf3dd29ddf41f264858accfa40b330c98e0ed27caf77734fac00139ba",
];
const multisig = generateMultisigFromPublicKeys(
TESTNET,
P2SH,
2,
...publicKeys
);

// All 3 UTXOs are at the same address so get decorated with the same multisig object.
const inputs = [
{
txid: "65e7ef764030dabfb46e3ae1c357b0666d0dda722c9809fb73245d6d68665284",
index: 1,
multisig,
},
{
txid: "ae9e1aa8312e102e806fa11d8e65965a624f88459e6bb5bcf48156a0c53e022a",
index: 1,
multisig,
},
{
txid: "f243c1fbb85dd49da91477b89c76636202721be9c7df5ee6eee0c6a10861ae44",
index: 0,
multisig,
},
];

const outputs = [
{
address: "2NE1LH35XT4YrdnEebk5oKMmRpGiYcUvpNR",
amountSats: 291590,
},
];

const unsignedTransaction = unsignedMultisigTransaction(
TESTNET,
inputs,
outputs
);

// Pass the above unsigned transaction to some keystore device/software to obtain a signature.
//
// One signature value per input.
const transactionSignature1 = [
"304402205397795a8b6e0b8d1c5a0b2b5b8fb8e49afb6dd150d1a186604fa9e71e23aaa20220514b7b7ed9ec43d983d7be5ea4ece5a55b29efa2193d90bf1fd087356fcbd54b",
"304402200ffcb2331655f1f24bf2f7e16984d81310e55d47c405b45e327abde524c8d31e022036460b70a665d1756ea91e131a1ed1022544dfdd2232f64117230d22f9deeb08",
"30440220167a35bccf4bb13073e8c66a1b094906d5c7879d6cdac730e435aef196d2f3eb02205a39e05763e511dc15deff56fa29eead850623076fda8a5e173dd0942197aaf4",
];

// Signatures can be validated.
transactionSignature1.forEach((inputSignature, inputIndex) => {
const result = validateMultisigSignature(
unsignedTransaction,
inputIndex,
inputs[inputIndex],
inputSignature
);
if (!result) {
console.error(Invalid signature for input ${inputIndex + 1});
}
});

// Get the second required signature.
const transactionSignature2 = ["304a...", "304b...", "304c..."];

// Combine signatures into a fully signed transaction.
const signedTransaction = signedMultisigTransaction(
TESTNET,
inputs,
outputs,
transactionSignature1,
transactionSignature2
);

// Broadcast this transaction somehow...
console.log(signedTransaction.tHex());
`

$3

This library contains several useful functions for validation not
provided by bitcoinjs-lib or other libraries. The validation
functions are designed to return an empty string '' on valid input
and provide a helpful error message otherwise.

- validateAddress -- understands Bech32 addresses and is aware of
differences in addresses across networks

- valdiateBIP32Path -- understands absolute and relative BIP32
paths, validates maximum BIP32 index values, and can optionally
check for fully hardened or unhardened paths

- validateExtendedPublicKey -- understands network-dependent
differences in encoding extended public keys

- validatePublicKey -- allows any hexadecimal value

- validateFeeRate -- implements a reasonable maximum fee rate in
Satoshis/byte

- validateFee -- implements a reasonable maximum fee in BTC

- validateOutputAmount -- checks for dust and that amount is less
than total input amount

- validateMultisigSignature -- checks signatures for correctness and
works across all multisig address types

Developers

$3

#### bitcoinjs-lib-v5`
This is to make sure that the legacy caravan/bitcoin functions
use the legacy bitcoinjs-lib when being built in caravan/coordinator.

Learn more here,
here, and
here.

$3

Unchained Capital welcomes bug reports, new features, and better documentation for this library.

If you are fixing a bug or adding a feature, please first check the GitHub issues page to see if there is any existing discussion about it.

To contribute, create a pull request (PR) on GitHub against the main fork of @caravan/bitcoin.

Before you submit your PR, make sure to update and run the test suite!