doc: Add multisig tutorial

[lsilva01]

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.

[fanquake]

Please add a link from the main README.

[lsilva01]

@fanquake Done.

[instagibbs]

@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

[Sjors]

utACK 2693a97

This process is still quite tedious, but it's good to have it documented.

[mjdietzx]

Concept ACK. Just commented on some minor type-os for now

[S3RK]

Is regtest vs signet the main difference? I'd expect the guide to have the same steps regardless of the chain used.

What's the long-term plan for this guide and the guide from #22067? Do we plan to maintain both of them or keep only one?

[Sjors]

The "Basic multisig example" in 22067 should probably link to this guide, but let's see what gets merged first.

[jaysonmald35]

Thank u

[Rspigler]

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

[lsilva01]

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.

[jonatack]

Concept ACK, provided people continue to maintain this and keep it up-to-date. Links between this and the docs + test in #22067 may be good to avoid information siloing.

[Sjors]

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)

[shaavan]

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:

• OP should mention .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.
• Dependencies like jq that are required to run the code should be mentioned at starting of the file.
• In the earlier parts of the tutorial, the instructions and reasoning precede the code. In contrast, in the later sections, after 1.4 Create the MultiSig Wallet, code precedes the instruction. This should be standardized, and the same style should be followed throughout the tutorial document.
• Following line 126, OP should provide instruction to copy the receive_address. Something like: “To copy the receiving address onto the clipboard, use the following command.”

echo -n "$receiving_address" | xclip -sel clip

• When a wallet is once created, and this process needs to be repeated, one has to load it instead of recreating wallets. This should be explicitly mentioned and explained in the tutorial file.

for ((n=1;n<=3;n++)); do  ./src/bitcoin-cli -signet loadwallet "participant_${n}"; done

./src/bitcoin-cli -signet loadwallet "multisig_wallet_01"

I hope these suggestions will be of help to the OP to improve upon the tutorial.

[michaelfolkson]

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.

[lsilva01]

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.

[shaavan]

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.

[S3RK]

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

[ghost]

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.

[Rspigler]

@S3RK I think it is better to have the setup with 2 wallets, because that is how offline multisig should be run (1 wallet for the offline privkey/signing, another wallet for the online coordinator/node).

[ghost]

I have also started working on a desktop application based on this tutorial. Hopefully will be completed by end of this week.

[Rspigler]

@prayank23 Awesome!

Please see #21071 (comment) if you are working on a multisig GUI

[ghost]

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

[lsilva01]

Done in 1b58755

[laanwj]

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?

[DrahtBot]

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #23711 (docs: RBF policy and mempool limit exemptions by glozow)

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.

[laanwj]

Anything left to be done here?

[Sjors]

utACK d92210e

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.

[Sjors]

re-utACK 1b58755

[ghost]

ACK 1ef2c03

[Sjors]

re-utACK 1ef2c03