Currently, it is possible to create a multig wallet using Bitcoin Core only.
Although there is already a brief explanation and a functional test about the multisig implemented in PR 22067, this tutorial proposes to use the signet (instead of regtest), bringing the reader closer to a real environment and explaining some functions in more detail.
Before starting this tutorial, start the bitcoin node on the signet network.
./src/bitcoind -signetThis tutorial also uses jq JSON processor to process the results from RPC and stores the relevant values in bash variables. This makes the tutorial reproducible and easier to follow step by step.
For a 2-of-3 multisig, create 3 descriptor wallets. It is important that they are of the descriptor type in order to retrieve the wallet descriptors. These wallets contain HD seed and private keys, which will be used to sign the PSBTs and derive the xpub.
for ((n=1;n<=3;n++))
do
./src/bitcoin-cli -signet -named createwallet wallet_name="participant_${n}" descriptors=true
doneExtract the xpub of each wallet. To do this, the listdescriptors RPC is used. By default, Bitcoin Core single-sig wallets are created using path m/44'/1'/0' for PKH, m/84'/1'/0' for WPKH and m/49'/1'/0' for P2WPKH-nested-in-P2SH based accounts. Each of them uses the chain 0 for external addresses and chain 1 for internal ones, as shown in the example below.
wpkh([1004658e/84'/1'/0']tpubDCBEcmVKbfC9KfdydyLbJ2gfNL88grZu1XcWSW9ytTM6fitvaRmVyr8Ddf7SjZ2ZfMx9RicjYAXhuh3fmLiVLPodPEqnQQURUfrBKiiVZc8/0/*)#g8l47ngv
wpkh([1004658e/84'/1'/0']tpubDCBEcmVKbfC9KfdydyLbJ2gfNL88grZu1XcWSW9ytTM6fitvaRmVyr8Ddf7SjZ2ZfMx9RicjYAXhuh3fmLiVLPodPEqnQQURUfrBKiiVZc8/1/*)#en65rxc5
The suffix (after #) is the checksum. Descriptors can optionally be suffixed with a checksum to protect against typos or copy-paste errors. All RPCs in Bitcoin Core will include the checksum in their output.
declare -A xpubs
for ((n=1;n<=3;n++))
do
xpubs["internal_xpub_${n}"]=$(./src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/1/*"))][0] | .desc' | grep -Po '(?<=\().*(?=\))')
xpubs["external_xpub_${n}"]=$(./src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/0/*") )][0] | .desc' | grep -Po '(?<=\().*(?=\))')
donejq is used to extract the xpub from the wpkh descriptor.
The following command can be used to verify if the xpub was generated correctly.
for x in "${!xpubs[@]}"; do printf "[%s]=%s\n" "$x" "${xpubs[$x]}" ; doneNote that this step extracts the m/84'/1'/0' account and does not conform to BIP 45 or BIP 87.
At the time of writing, there is no way to extract a specific path from wallets in Bitcoin Core. For this, an external signer/xpub can be used.
PR #22341, which is still under development, introduces a new wallet RPC getxpub. It takes a BIP32 path as an argument and returns the xpub, along with the master key fingerprint.
Define the external and internal multisig descriptors, add the checksum and then, join both in a JSON array.
external_desc="wsh(sortedmulti(2,${xpubs["external_xpub_1"]},${xpubs["external_xpub_2"]},${xpubs["external_xpub_3"]}))"
internal_desc="wsh(sortedmulti(2,${xpubs["internal_xpub_1"]},${xpubs["internal_xpub_2"]},${xpubs["internal_xpub_3"]}))"
external_desc_sum=$(./src/bitcoin-cli -signet getdescriptorinfo $external_desc | jq '.descriptor')
internal_desc_sum=$(./src/bitcoin-cli -signet getdescriptorinfo $internal_desc | jq '.descriptor')
multisig_ext_desc="{\"desc\": $external_desc_sum, \"active\": true, \"internal\": false, \"timestamp\": \"now\"}"
multisig_int_desc="{\"desc\": $internal_desc_sum, \"active\": true, \"internal\": true, \"timestamp\": \"now\"}"
multisig_desc="[$multisig_ext_desc, $multisig_int_desc]"external_desc and internal_desc specify the output type (wsh, in this case) and the xpubs involved. They also use BIP 67 (sortedmulti), so the wallet can be recreated without worrying about the order of xpubs. Conceptually, descriptors describe a list of scriptPubKey (along with information for spending from it) [source].
Note that at least two descriptors are usually used, one for internal derivation paths and external ones. There are discussions about eliminating this redundancy, as can been seen in the issue #17190.
After creating the descriptors, it is necessary to add the checksum, which is required by the importdescriptors RPC.
The checksum for a descriptor without one can be computed using the getdescriptorinfo RPC. The response has the descriptor field, which is the descriptor with the checksum added.
There are other fields that can be added to the descriptors:
active: Sets the descriptor to be the active one for the corresponding output type (wsh, in this case).internal: Indicates whether matching outputs should be treated as something other than incoming payments (e.g. change).timestamp: Sets the time from which to start rescanning the blockchain for the descriptor, in UNIX epoch time.
Documentation for these and other parameters can be found by typing ./src/bitcoin-cli help importdescriptors.
multisig_desc concatenates external and internal descriptors in a JSON array and then it will be used to create the multisig wallet.
./src/bitcoin-cli -signet -named createwallet wallet_name="multisig_wallet_01" disable_private_keys=true blank=true descriptors=true
./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" importdescriptors "$multisig_desc"
./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getwalletinfoTo create the multisig wallet, first create an empty one (no keys, HD seed and private keys disabled).
Then import the descriptors created in the previous step using the importdescriptors RPC.
After that, getwalletinfo can be used to check if the wallet was created successfully.
receiving_address=$(./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getnewaddress)
./contrib/signet/getcoins.py -a $receiving_addressThe wallet can receive signet coins by generating a new address and passing it as parameters to getcoins.py script.
If the script throws an error such as Captcha required (reload page), the url in the script can be accessed directly.
At time of writing, the url is https://signetfaucet.com.
Coins received by the wallet must have at least 1 confirmation before they can be spent. It is necessary to wait for a new block to be mined before continuing.
The getbalances RPC may be used to check the balance. Coins with trusted status can be spent.
./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalancesbalance=$(./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalance)
amount=$(echo "$balance * 0.8" | bc -l | sed -e 's/^\./0./' -e 's/^-\./-0./')
destination_addr=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" getnewaddress)
funded_psbt=$(./src/bitcoin-cli -signet -named -rpcwallet="multisig_wallet_01" walletcreatefundedpsbt outputs="{\"$destination_addr\": $amount}" | jq -r '.psbt')Unlike singlesig wallets, multisig wallets cannot create and sign transactions directly because they require the signatures of the co-signers. Instead they create a Partially Signed Bitcoin Transaction (PSBT).
PSBT is a data format that allows wallets and other tools to exchange information about a Bitcoin transaction and the signatures necessary to complete it. [source]
Te current PSBT version (v0) is defined in BIP 174.
For simplicity, the destination address is taken from the participant_1 wallet in the code above, but it can be any valid bitcoin address.
The walletcreatefundedpsbt RPC is used to create and fund a transaction in the PSBT format. It is the first step in creating the PSBT.\
There is also the createpsbt RPC, which serves the same purpose, but it has no access to the wallet or to the UTXO set. It is functionally the same as createrawtransaction and just drops the raw transaction into an otherwise blank PSBT. [source] In most cases, walletcreatefundedpsbt solves the problem.
The send RPC can also return a PSBT if more signatures are needed to sign the transaction.
./src/bitcoin-cli -signet decodepsbt $funded_psbt
./src/bitcoin-cli -signet analyzepsbt $funded_psbtOptionally, the PSBT can be decoded to a JSON format using decodepsbt RPC.
The analyzepsbt RPC analyzes and provides information about the current status of a PSBT and its inputs, e.g. missing signatures.
psbt_1=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq '.psbt')
psbt_2=$(./src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $funded_psbt | jq '.psbt')In the code above, two PSBTs are created. One signed by participant_1 wallet and other, by the participant_2 wallet.
The walletprocesspsbt is used by the wallet to sign a PSBT.
combined_psbt=$(./src/bitcoin-cli -signet combinepsbt "[$psbt_1, $psbt_2]")The PSBT, if signed separately by the co-signers, must be combined into one transaction before being finalized. This is done by combinepsbt RPC.
There is an RPC called joinpsbts, but it has a different purpose than combinepsbt. joinpsbts joins the inputs from multiple distinct PSBTs into one PSBT.
In the example above, the PSBTs are the same, but signed by different participants. If the user tries to merge them using joinpsbts, the error Input txid:pos exists in multiple PSBTs is returned. To be able to merge different PSBTs into one, they must have different inputs and outputs.
finalized_psbt_hex=$(./src/bitcoin-cli -signet finalizepsbt $combined_psbt | jq -r '.hex')
./src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hexThe finalizepsbt RPC is used to produce a network serialized transaction which can be broadcast with sendrawtransaction.
It checks that all inputs have complete scriptSigs and scriptWitnesses and, if so, encodes them into network serialized transactions.
psbt_1=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq -r '.psbt')
psbt_2=$(./src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $psbt_1 | jq -r '.psbt')
finalized_psbt_hex=$(./src/bitcoin-cli -signet finalizepsbt $psbt_2 | jq -r '.hex')
./src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hexInstead of each wallet signing the original PSBT and combining them later, the wallets can also sign the PSBTs sequentially. This is less scalable than the previously presented parallel workflow, but it works.
After that, the rest of the process is the same: the PSBT is finalized and transmitted to the network.