This PR adds a mutisig tutorial, as requested in #21278
Although there is already a brief explanation and a functional test about the multisig implemented in #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.
I’m not sure if this format should be in this repository or on some wiki page. But as there is an open issue regarding this matter, that is my suggestion.
@harding might be interested too
Unsure if here or some wiki page is best, but I can step through the tutorial in a bit and give feedback
25+done
26+```
27+
28+### 1.2 Create the Descriptor Wallets
29+
30+Extract 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.
m/86'/1'/0' here?
0@@ -0,0 +1,225 @@
1+# 1. Multisig Tutorial
2+
3+Currently, it is possible to create a multig wallet using Bitcoin Core only.
utACK 2693a97e51ee527a5e43c1d9c493a43cbd289af8
This process is still quite tedious, but it’s good to have it documented.
148+
149+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).
150+
151+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](https://bitcoinops.org/en/topics/psbt/)]
152+
153+Te current PSBT version (v0) is defined in [BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki).
152+
153+Te current PSBT version (v0) is defined in [BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki).
154+
155+For simplicity, the destination address is taken from the `participant_1` wallet in the code above, but it can be any valid bitcoin address.
156+
157+The `walletcreatefundedpsbt` RPC is used to create and fund a transaction in the PSBT format. It is the first step in creating the PSBT.\
55+
56+```bash
57+for x in "${!xpubs[@]}"; do printf "[%s]=%s\n" "$x" "${xpubs[$x]}" ; done
58+```
59+
60+Note that this step extracts the `m/84'/1'/0'` account and does not conform to [BIP 45](https://github.com/bitcoin/bips/blob/master/bip-0045.mediawiki) or [BIP 87](https://github.com/bitcoin/bips/blob/master/bip-0087.mediawiki).
14+
15+## 1.1 Basic Multisig Workflow
16+
17+### 1.1 Create the Descriptor Wallets
18+
19+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.
In addition, these three wallets should not be used directly for privacy reasons (public key reuse). They should only be used to sign transactions for the (watch-only) multisig wallet.
(that said, I find this restriction annoying)
0@@ -0,0 +1,225 @@
1+# 1. Multisig Tutorial
2+
3+Currently, it is possible to create a multig wallet using Bitcoin Core only.
4+
5+Although there is already a brief explanation and a functional test about the multisig implemented in [PR 22067](https://github.com/bitcoin/bitcoin/pull/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.
I don’t quite understand the point of this, when we have #22067
22067 simply explains how to set up a multisig wallet using the GUI and RPC commands, why have another document with bash scripts? Other improvements can be added to the other PR
The purpose of this PR is to add a tutorial (step by step) on multisig that explains some current functions and limitations in more detail.
Thus, the reader who doesn’t understand the Test Framework or python will still be able to reproduce these steps on signet or even mainnet .
If this is a valid proposal, it can be a complement to PR #22067.
Thus, the reader who doesn’t understand the Test Framework or python will still be able to reproduce these steps on signet or even mainnet .
Conversely, the purpose of tests is to ensure we don’t accidentally break functionality.
I agree it’s useful if the toturial points to the test and vv, and we try to keep them somewhat consistent (although the test may continue to use earlier methods to ensure we don’t break those as we change the recommended workflow for new users)
Concept ACK I successfully followed the tutorial on Ubuntu 20.04 to create a multisig transaction over the signet network. Thank you very much for creating such a detailed guide. I have some suggestions that might help to improve this tutorial further. This suggestion includes the occasional situation where I had some confusion following the tutorial or needed additional help from the internet. Suggestions:
.src/bitcoind -signet -daemon instead of .src/bitcoind -signet; otherwise, the terminal starts a non-finishing process which might off-put a new user. -daemon does the same job, just starts the process in the background.receive_address. Something like: “To copy the receiving address onto the clipboard, use the following command.”0echo -n "$receiving_address" | xclip -sel clip
0for ((n=1;n<=3;n++)); do ./src/bitcoin-cli -signet loadwallet "participant_${n}"; done
0./src/bitcoin-cli -signet loadwallet "multisig_wallet_01"
I hope these suggestions will be of help to the OP to improve upon the tutorial.
I don’t quite understand the point of this, when we have #22067
22067 simply explains how to set up a multisig wallet using the GUI and RPC commands, why have another document with bash scripts? Other improvements can be added to the other PR
I agree with @Rspigler. I’d prefer this was a StackExchange post given that the process will likely repeatedly change in future and introduces maintenance burden. It looks good though, just quibbling on the best location for it given we want to avoid bloated, outdated docs in the repo in future.
edit: Feel free to put it here if you agree with above. Once the (optimal) process has crystallized I’d be more comfortable transferring it back as a stable doc to the repo.
I put up a StackExchange post by @ben-kaufman there on multisig backups which seems to me to be in a similar vein.
Thanks for suggestions @shaavan. I added them. @michaelfolkson I will add a short version of this tutorial to the StackExchange question you created.
I don’t have a strong opinion whether this type of documentation is better to be in the repo or on another site.
The advantage of listing the procedures here is that it is extensively reviewed, so it is much more reliable and is part of the reference implementation.
The downside, as already mentioned, is the maintenance burden.
The document looks a lot better now. Great Work, @lsilva01!
Just a tiny thing to add. Since xclip is now being used to copy the address, it should also be mentioned as a dependency along with jq as it is not usually preinstalled in a Debian-based system.
edit: Feel free to put it here if you agree with the above. Once the (optimal) process has crystallized, I’d be more comfortable transferring it back as a stable doc to the repo.
I am no expert when it comes to maintenance, but I understand that it would be a burden to keep updating the doc as the process keeps changing. But posting this as a StackExchange answer doesn’t feel right to me. I think so because most people searching for the same question do not end up on the same StackExchange article, resulting in not many people being aware of this thorough documentation.
It would be great if we could figure out some middle ground where the documentation is visible to the audience who needs a multisig tutorial. But at the same time, not being a maintenance burden to the bitcoin in general.
I have a slight preference towards more concise guide from #22067.
But in case this will be merged sooner, I’ll repeat my concern for both this PR and #22067
Why not have just one wallet? Having two wallets is less intuitive, complicates backups and could lead to user confusion and even loss of funds. Especially taking into account that you need to backup both wallets to restore your funds. This doesn’t come through the documentation.
See my comment for suggestions
I have a slight preference towards more concise guide from #22067.
whynotboth.gif
Although I like this tutorial. Other PR adds lot of things which can be useful for devs but docs from repository are also used by power users.
Concept ACK and thanks for your contribution @lsilva01
I want to use this tutorial and make some GUI or script to make it even easier for users before reviewing this PR in detail. Because multisig still feels like something only devs and few users can do.
https://unchained-capital.github.io/caravan/ is a nice web app although I don’t have the skills to create such things, I will try doing a console application/desktop application/scripts. Also it would be better if we can avoid reference to open PRs in docs.
132+At time of writing, the url is [`https://signetfaucet.com`](https://signetfaucet.com).
133+
134+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.
135+
136+```bash
137+receiving_address=$(./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getnewaddress)
This gives error:
0error code: -4
1error message:
2Error: This wallet has no available keys
The multisig wallet is created without keys (line 114), so you can import the descriptors (line 116). If you forget to do this, this error message is displayed.
You can check if the wallet has descriptors imported with the command command ./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" listdescriptors .
I have also started working on a desktop application based on this tutorial. Hopefully will be completed by end of this week.
@prayank23 Awesome!
Please see #21071 (comment) if you are working on a multisig GUI
31+do
32+ ./src/bitcoin-cli -signet -named createwallet wallet_name="participant_${n}" descriptors=true
33+done
34+```
35+
36+### 1.2 Create the Descriptor Wallets
Line 23 is ### 1.1 Create the Descriptor Wallets and this line ### 1.2 Create the Descriptor Wallets
Should combine them in one or change 1.2 to something else? I think we list descriptors in 1.2
It would be great if we could figure out some middle ground where the documentation is visible to the audience who needs a multisig tutorial. But at the same time, not being a maintenance burden to the bitcoin in general.
I think documenting a basic multisig flow is important, as it is something a lot of people want to do nowadays. IMO it’s best to regard it as basic functionality of the wallet not something exotic.
but I understand that it would be a burden to keep updating the doc as the process keeps changing
Now that PSBT’s and descriptor wallets have been hammered out. The process shouldn’t change too much anymore, right?
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
Reviewers, this pull request conflicts with the following ones:
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.
utACK d92210e01b5d38bba5ce5bd80fd4caa59f96eec1
Looking forward to making this easier over time. I think it’s fine to update this document whenever that happens; it could even make review easier.
0@@ -0,0 +1,242 @@
1+# 1. Multisig Tutorial
2+
3+Currently, it is possible to create a multisig wallet using Bitcoin Core only.
4+
5+Although there is already a brief explanation and a functional test about the multisig implemented in [PR 22067](https://github.com/bitcoin/bitcoin/pull/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.
124+
125+### 1.4 Fund the wallet
126+
127+The wallet can receive signet coins by generating a new address and passing it as parameters to `getcoins.py` script.
128+
129+If the script throws an error such as `Captcha required (reload page)`, the url in the script can be accessed directly.
