Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions _compress_images_cache.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3178,3 +3178,17 @@ assets/images/social-media/social-media.jpg: social-media.jpg
assets/images/social-media/social-media@2x.jpg: social-media@2x.jpg
assets/images/submit-header-design-preview.jpg: submit-header-design-preview.jpg
assets/mstile-150x150.png: mstile-150x150.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-exchange.png: multi-key-diagram-1-key-exchange.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-exchange@2x.png: multi-key-diagram-1-key-exchange@2x.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-generation.png: multi-key-diagram-1-key-generation.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-generation@2x.png: multi-key-diagram-1-key-generation@2x.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-signing.png: multi-key-diagram-1-signing.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-signing@2x.png: multi-key-diagram-1-signing@2x.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-wallet-setup.png: multi-key-diagram-1-wallet-setup.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-wallet-setup@2x.png: multi-key-diagram-1-wallet-setup@2x.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-signing-mobile.png: multi-key-diagram-1-signing-mobile.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-signing-mobile@2x.png: multi-key-diagram-1-signing-mobile@2x.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-exchange-mobile.png: multi-key-diagram-1-key-exchange-mobile.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-exchange-mobile@2x.png: multi-key-diagram-1-key-exchange-mobile@2x.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-generation-mobile.png: multi-key-diagram-1-key-generation-mobile.png
assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-generation-mobile@2x.png: multi-key-diagram-1-key-generation-mobile@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
69 changes: 61 additions & 8 deletions guide/how-it-works/private-key-management/multi-key.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ main_classes: -no-top-padding

Editor's notes

Description of what multi-key scheme consists of.
Explains generally how multi-key schemes work.

Illustration sources

Expand All @@ -40,15 +40,15 @@ https://www.figma.com/community/file/995256542920917246/BDG---Private-key-manage

All of the previous schemes have relied on a single private key to control the wallet. This presents an all-or-nothing risk for loss of funds from both theft and negligence. To counter this, a wallet can have several private keys attached of which all or a subset need to sign any transactions.

This is often called multi-signature, or multisig for short, but is also sometimes referred to as a *vault*. A multi-key setup is described as *n-of-n* to indicate how many keys are needed to sign a transaction out of the issued number. For example, a *2-of-3* setup requires two of the three private keys to sign a transaction for it to be valid.
This is often called multi-signature, or multi-sig for short, but is also sometimes referred to as a *vault*. A multi-key setup is described as *m-of-n* to indicate how many keys are needed to sign a transaction out of the issued number. For example, a *2-of-3* setup requires two of the three private keys to sign a transaction for it to be valid.

In the case of a personal wallet, one individual will control all the keys but hold them on different devices for increased security. See the [savings wallet reference design]({{ '/guide/savings-wallet/' | relative_url }}) for a UX exploration of this use case.

In the case of a shared wallet, different people will control the keys. The number of keys and required co-signers will depend on the use case. With spouses sharing a *joint account*, a simple 1-of-2 multi-key setup might suffice, meaning there are two keys but only one is required to sign for a transaction to be valid. At the other end of the spectrum, a company might require a more complex 3-of-5 setup, requiring three of the five co-signers to approve any transaction.
In the case of a [shared wallet]({{ '/guide/shared-wallet/' | relative_url }}), different people will control the keys. The number of keys and required co-signers will depend on the use case. With spouses sharing a *joint account*, a simple 1-of-2 multi-key setup might suffice, meaning there are two keys but only one is required to sign for a transaction to be valid. At the other end of the spectrum, a company might require a more complex 3-of-5 setup, requiring three of the five co-signers to approve any transaction.

It is important to remember that the usage of multiple keys is necessary only for signing outgoing transactions, but not for receiving funds. This is a common misunderstanding.

Multi-key schemes can raise the security, since anyone needs access to more than one key to move any funds. But clearly, it also increases complexity and the requirements on the user to keep even more keys securely stored and/or backed up.
A multi-key scheme can raise the security, since anyone needs access to more than one key to move any funds. But clearly, it also increases complexity and requires the user(s) to keep even more keys securely stored and/or backed up.

{% include tip/tip.html %}

Expand All @@ -57,7 +57,9 @@ The keys used by a lightning node cannot be controlled by a multi-key setup, as
{% include tip/close.html %}

### How it works
A software wallet application or coordination software initiates a multi-sig wallet, choosing the number of total keys, and the number required to sign transactions. You then add private keys from other wallets generated elsewhere to the multisig after which the software wallet can complete the creation process. For any future transaction from the multi-sig wallet, the required amount of co-signers need to sign (using Partially Signed Bitcoin Transactions - PSBT from [BIP174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki)) before any transaction is valid.
A software wallet application or coordination software initiates a multi-key wallet, choosing the number of total keys, and the number required to sign transactions. You then add [extended public keys]({{ '/guide/glossary/#extended-public-key-xpub-ypub-zpub' | relative_url }}) from other wallets generated elsewhere to the multisig after which the software wallet can complete the creation process, and start generating addresses. For any future transaction from the multi-key wallet, the required amount of co-signers need to sign (using [Partially Signed Bitcoin Transactions]({{ '/guide/glossary/#partially-signed-bitcoin-transaction-psbt' | relative_url }})) before any transaction is valid.

It is possible to configure a wallet with multiple sets of keys, with each having its own spending rules. Find out more in the [custom spending conditions]({{ '/guide/how-it-works/custom-spending-conditions/' | relative_url }}) page.

{% include fact/pros.html %}

Expand All @@ -74,7 +76,57 @@ A software wallet application or coordination software initiates a multi-sig wal

{% include fact/close.html %}

### Best practice
### General user flow

Alice, Robert, and Charles want to set up a multi-key wallet that has a total of 3 keys, with 2 keys required to send a transaction.

In the first step, each of them independently generates a private key and a public key (technically an extended public key). All 3 public keys together are used to construct the multi-key wallet, for generating addresses to receive bitcoin to, and by extension also for constructing new transactions. The private key is never shared, and used to approve transactions, initiated by themselves or others.

{% include picture.html
image = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-generation.png"
retina = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-generation@2x.png"
mobile = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-generation-mobile.png"
mobileRetina = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-generation-mobile@2x.png"
alt-text = "Diagram of Alice, Robert, and Charles generating private and public keys"
width = 800
height = 456
%}

Then, they exchange the public keys, so each of them has a set of all 3.

{% include picture.html
image = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-exchange.png"
retina = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-exchange@2x.png"
mobile = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-exchange-mobile.png"
mobileRetina = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-key-exchange-mobile@2x.png"
alt-text = "Diagram of the three wallet owners exchanging public keys"
width = 800
height = 381
%}

They can now individually construct the same multi-key wallet with the 3 public keys and the spending conditions they decided on (2-of-3). Addresses generated by each wallet will be identical. The order of the public keys is important. A different order will result in a different wallet (for signing, the order does not matter).

{% include picture.html
image = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-wallet-setup.png"
retina = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-wallet-setup@2x.png"
alt-text = "Diagram of each wallet owner constructing the multi-key wallet"
width = 800
height = 408
%}

Now Alice wants to send bitcoin received to the shared wallet. She can initiate transactions, and sign them with her own key. But she needs another signature for the bitcoin network to accept the transaction. She sends the transaction to Robert, who signs it, and broadcasts it to the network. She could also have asked Charles to do this.

{% include picture.html
image = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-signing.png"
retina = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-signing@2x.png"
mobile = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-signing-mobile.png"
mobileRetina = "/assets/images/guide/how-it-works/private-key-management/multi-key/multi-key-diagram-1-signing-mobile@2x.png"
alt-text = "Diagram of Alice intiating a transaction and Robert signing it"
width = 800
height = 168
%}

### Best practices

**When to use**
- When storing large amounts
Expand All @@ -97,13 +149,14 @@ A software wallet application or coordination software initiates a multi-sig wal
- Make sure the multi-key setup itself is backed up properly, including [extended public keys]({{ '/guide/glossary/#extended-public-key-xpub-ypub-zpub' | relative_url }}) for all the participating keys, fingerprint and derivation.

**Products that use this scheme**
- [Sparrow Wallet](https://sparrowwallet.com/)
- [Casa](https://keys.casa) co-managed 2-of-3, or 3-of-5
- [Electrum](https://electrum.org)
- [Bluewallet](https://bluewallet.io)
- [BlueWallet](https://bluewallet.io)
- [Nunchuk](https://nunchuk.io)
- [Unchained Capital/Caravan](https://unchained-capital.com) co-managed
- [Specter](https://specter.solutions)
- [Armory](https://btcarmory.com)
- [Guarda](https://guarda.com)
- [Revault](https://revault.dev){:target="_blank"} - in development

Comment thread
GBKS marked this conversation as resolved.
Resolved
---
Expand Down