JSDoc: Module: multisig

This module provides an API around the multisig capabilities of the bitcoinjs-lib library. The API is functional but requires you creating and passing around a Multisig object.

This Multisig object represents the combination of:

a sequence of N public keys
the number of required signers (M)
the address type (P2SH, P2SH-P2WSH, P2WSH)
the bitcoin network

This corresponds to a unique bitcoin multisig address. Note that since (3) & (4) can change without changing (1) & (2), different Multisig objects (and their corresponding bitcoin addresses) can have different representations but the same security rules as to who can sign.

You can create Multisig objects yourself using the following functions:

generateMultisigFromPublicKeys which takes public keys as input
generateMultisigFromHex which takes a redeem/witness script as input

Once you have a Multisig object you can pass it around in your code and then ask questions about it using the other functions defined in this module.

You can manipulate Multisig objects directly but it's better to use the functions from API provided by this module.

Source:

multisig.js, line 1

Example

import {
  generateMultisigFromPublicKeys, MAINNET, P2SH,
  multisigRequiredSigners, multisigTotalSigners,
  multisigAddressType,
  multisigPublicKeys,
} from "unchained-bitcoin";
const pubkey1 = "03a...";
const pubkey2 = "03b...";
// A mainnet 1-of-2 P2SH multisig
const multisig = generateMultisigFromPublicKeys(MAINNET, P2SH, 1, pubkey1, pubkey2);

console.log(multisigRequiredSigners(multisig)); // 1
console.log(multisigTotalSigners(multisig)); // 2
console.log(multisigAddressType(multisig)); // "P2SH"
console.log(multisigPublicKeys(multisig)); // ["03a...", "03b..."]

Members

(static, constant) MULTISIG_ADDRESS_TYPES :string

Enumeration of possible multisig address types (P2SH|P2SH_P2WSH|P2WSH).

Type:

string

Source:

multisig.js, line 88

Methods

(static) generateMultisigFromHex(network, addressType, multisigScriptHex) → {Multisig}

Return an M-of-N Multisig object by passing a script in hex.

If the addressType is P2SH then the script hex being passed is the redeem script. If the addressType is P2SH-wrapped SegWit (P2SH_P2WSH) or native SegWit (P2WSH) then the script hex being passed is the witness script.

In practice, the same script hex can be thought of as any of several address types, depending on context.

Parameters:

Name	Type	Description
`network`	module:networks.NETWORKS	bitcoin network
`addressType`	module:multisig.MULTISIG_ADDRESS_TYPES	address type
`multisigScriptHex`	string	hex representation of the redeem/witness script

Source:

multisig.js, line 150

Returns:

object for further parsing

Type: Multisig

Example

import {
  generateMultisigFromHex, MAINNET, P2SH, P2WSH,
} from "unchained-bitcoin";
const multisigScript = "512103a90d10bf3794352bb1fa533dbd4ea75a0ffc98e0d05124938fcc3e10cdbe1a4321030d60e8d497fa8ce59a2b3203f0e597cd0182e1fe0cc3688f73497f2e99fbf64b52ae";
const multisigP2SH = generateMultisigFromHex(MAINNET, P2SH, multisigScript);
const multisigP2WSH = generateMultisigFromHex(MAINNET, P2WSH, multisigScript);

(static) generateMultisigFromPublicKeys(network, addressType, requiredSigners, …publicKeys) → {Multisig}

Return an M-of-N Multisig object by specifying the total number of signers (M) and the public keys (N total).

Parameters:

Name	Type	Attributes	Description
`network`	module:networks.NETWORKS		bitcoin network
`addressType`	module:multisig.MULTISIG_ADDRESS_TYPES		address type
`requiredSigners`	number		number of signers required needed to spend funds (M)
`publicKeys`	string	<repeatable>	list of public keys, 1 per possible signer (N)

Source:

multisig.js, line 112

Returns:

the corresponding Multisig object

Type: Multisig

Example

// A 2-of-3 P2SH mainnet multisig built from 3 public keys.
import {
  generateMultisigFromPublicKeys, MAINNET, P2SH, P2WSH,
} from "unchained-bitcoin";
const multisigP2SH = generateMultisigFromPublicKeys(MAINNET, P2SH, 2, "03a...", "03b...", "03c...");
const multisigP2WSH = generateMultisigFromPublicKeys(MAINNET, P2WSH, 2, "03a...", "03b...", "03c...");

(static) multisigAddress(multisig) → {string}

Return the address for a given Multisig object.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 398

Returns:

the address

Type: string

Example

import {
  generateMultisigFromPublicKeys, MAINNET, P2SH,
  multisigAddress,
} from "unchained-bitcoin";
const multisig = generateMultisigFromPublicKeys(MAINNET, P2SH, 2, "03a...", "03b...", "03c...");
console.log(multisigAddress(multisig)); // "3j..."

(static) multisigAddressType(multisig) → {module:multisig.MULTISIG_ADDRESS_TYPES|String}

Return the address type of the given Multisig object.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 210

Returns:

the address type

Type: module:multisig.MULTISIG_ADDRESS_TYPES | String

Example

import {
  multisigAddressType, P2SH, P2SH_P2WSH, P2WSH,
} from "unchained-bitcoin";
function doSomething(multisig) {
  switch (multisigAddressType(multisig)) {
  case P2SH:
    // handle P2SH here
  case P2SH_P2WSH:
    // handle P2SH-P2WSH here
  case P2WSH:
    // handle P2WSH here
  default:
    // shouldn't reach here
}

(static) multisigBraidDetails(multisig) → {string}

Return the braid details (if known) for a given Multisig object.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 420

Returns:

the braid details

Type: string

Example

import {
  generateBraidFromExtendedPublicKeys,
  generateMultisigFromPublicKeys, MAINNET, P2SH,
  braidConfig,
} from "unchained-bitcoin";
const multisig = generateMultisigFromPublicKeys(MAINNET, P2SH, 2, "03a...", "03b...", "03c...");
console.log(multisigBraidDetails(multisig)); // null, unknown

const braid = generateBraidFromExtenedPublicKeys(MAINNET, P2SH, {{'xpub...', bip32path: "m/45'/0'/0'"}, {'xpub...', bip32path: "m/45'/0/0"}, {'xpub...', bip32path: "m/45'/0/0"}}, 2);
const multisig = braid.deriveMultisigByPath("0/0");
console.log(multisigBraidDetails(multisig)); // {network: mainnet, addressType: p2sh, extendedPublicKeys: {...}, requiredSigners: 2}}

(static) multisigPublicKeys(multisig) → {Array.<string>}

Return the (compressed) public keys in hex for the given Multisig object.

The public keys are in the order used in the corresponding redeem/witness script.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 376

Returns:

(compressed) public keys in hex

Type: Array.<string>

Example

import {
  generateMultisigFromPublicKeys, MAINNET, P2WSH,
  multisigPublicKeys,
} from "unchained-bitcoin";
const multisig = generateMultisigFromPublicKeys(MAINNET, P2WSH, 2, "03a...", "03b...", "03c...");
console.log(multisigPublicKeys(multisig)); // ["03a...", "03b...", "03c..."]

(static) multisigRedeemScript(multisig) → {Multisig|null}

Return the redeem script for the given Multisig object.

If the address type of the given multisig object is P2WSH, this will return null.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 312

Returns:

the redeem script

Type: Multisig | null

Example

import {
  generateMultisigFromPublicKeys, MAINNET, P2SH,
  multisigRedeemScript,
} from "unchained-bitcoin";
const multisig = generateMultisigFromPublicKeys(MAINNET, P2SH, 2, "03a...", "03b...", "03c...");
console.log(multisigRedeemScript(multisig));

(static) multisigRequiredSigners(multisig) → {number}

Return the number of required signers of the given Multisig object.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 238

Returns:

number of required signers

Type: number

Example

import {
  generateMultisigFromPublicKeys, MAINNET, P2SH,
  multisigRequiredSigners,
} from "unchained-bitcoin";
const multisig = generateMultisigFromPublicKeys(MAINNET, P2SH, 2, "03a...", "03b...", "03c...");
console.log(multisigRequiredSigners(multisig)); // 2

(static) multisigScript(multisig) → {Multisig|null}

Return the multisig script for the given Multisig object.

If the address type of the given multisig object is P2SH, the redeem script will be returned. Otherwise, the witness script will be returned.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 281

Returns:

the corresponding script

Type: Multisig | null

Example

import {
  generateMultisigFromPublicKeys, MAINNET, P2SH,
  multisigScript,
} from "unchained-bitcoin";
const multisig = generateMultisigFromPublicKeys(MAINNET, P2SH, 2, "03a...", "03b...", "03c...");
console.log(multisigScript(multisig));

(static) multisigTotalSigners(multisig) → {number}

Return the number of total signers (public keys) of the given Multisig object.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 258

Returns:

number of total signers

Type: number

Example

import {
  generateMultisigFromPublicKeys, MAINNET, P2SH,
  multisigTotalSigners,
} from "unchained-bitcoin";
const multisig = generateMultisigFromPublicKeys(MAINNET, P2SH, 2, "03a...", "03b...", "03c...");
console.log(multisigTotalSigners(multisig)); // 3

(static) multisigWitnessScript(multisig) → {Multisig|null}

Return the witness script for the given Multisig object.

If the address type of the given multisig object is P2SH, this will return null.

Parameters:

Name	Type	Description
`multisig`	module:multisig.Multisig	the `Multisig` object

Source:

multisig.js, line 343

Returns:

the witness script

Type: Multisig | null

Example

import {
  generateMultisigFromPublicKeys, MAINNET, P2WSH,
  multisigWitnessScript,
} from "unchained-bitcoin";
const multisig = generateMultisigFromPublicKeys(MAINNET, P2WSH, 2, "03a...", "03b...", "03c...");
console.log(multisigWitnessScript(multisig));

Type Definitions

Multisig

Describes the return type of several functions in the payments module of bitcoinjs-lib.

The following functions in this module will return objects of this type:

generateMultisigFromPublicKeys which takes public keys as input
generateMultisigFromHex which takes a redeem/witness script as input

The remaining functions accept these objects as arguments.

Type:

Object

Properties:

Name	Type	Description
`address`	string	The multisig address
`redeem`	Object	the redeem object from p2ms
`multisigBraidDetails`	Object	details about the braid (addressType, network, requiredSigners, xpubs, index)
`getBip32Derivation`	Array.<Object>	Array of objects for every key in this multisig address

Source:

multisig.js, line 60