diff --git a/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address.png b/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address.png new file mode 100644 index 000000000..7c1f14171 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address@2x.png b/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address@2x.png new file mode 100644 index 000000000..e469b7018 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday.png b/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday.png new file mode 100644 index 000000000..1f0c8a58f Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday@2x.png b/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday@2x.png new file mode 100644 index 000000000..fd1504201 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/clipboard-options-add-contacts-or-pay.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/clipboard-options-add-contacts-or-pay.png new file mode 100644 index 000000000..ce0a8730e Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/clipboard-options-add-contacts-or-pay.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/clipboard-options-add-contacts-or-pay@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/clipboard-options-add-contacts-or-pay@2x.png new file mode 100644 index 000000000..30446ea6d Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/clipboard-options-add-contacts-or-pay@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/contact-page.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/contact-page.png new file mode 100644 index 000000000..28c24dff2 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/contact-page.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/contact-page@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/contact-page@2x.png new file mode 100644 index 000000000..054e11057 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/contact-page@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/contacts-list.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/contacts-list.png new file mode 100644 index 000000000..e23af9a45 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/contacts-list.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/contacts-list@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/contacts-list@2x.png new file mode 100644 index 000000000..35ecbe430 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/contacts-list@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/home-screen-with-contacts.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/home-screen-with-contacts.png new file mode 100644 index 000000000..44e18d9a0 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/home-screen-with-contacts.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/home-screen-with-contacts@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/home-screen-with-contacts@2x.png new file mode 100644 index 000000000..a68d58d3c Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/home-screen-with-contacts@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-enter.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-enter.png new file mode 100644 index 000000000..b0299bd7d Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-enter.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-enter@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-enter@2x.png new file mode 100644 index 000000000..08251e1aa Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-enter@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-prompt.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-prompt.png new file mode 100644 index 000000000..445de5ca5 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-prompt.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-prompt@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-prompt@2x.png new file mode 100644 index 000000000..c7e70d048 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/recovery-wallet-birthday-prompt@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/send-address-error.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-address-error.png new file mode 100644 index 000000000..c115a8441 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-address-error.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/send-address-error@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-address-error@2x.png new file mode 100644 index 000000000..75a161ad9 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-address-error@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp-another.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp-another.png new file mode 100644 index 000000000..f8705c04a Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp-another.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp-another@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp-another@2x.png new file mode 100644 index 000000000..36baa8b8d Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp-another@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp.png new file mode 100644 index 000000000..1de71fb38 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp@2x.png new file mode 100644 index 000000000..f688a7127 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-sp@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-with-contact.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-with-contact.png new file mode 100644 index 000000000..5a2aca936 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-with-contact.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-with-contact@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-with-contact@2x.png new file mode 100644 index 000000000..68ccd60a1 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/send-review-with-contact@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-i.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-i.png new file mode 100644 index 000000000..dc7a28a49 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-i.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-i@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-i@2x.png new file mode 100644 index 000000000..7dea870c7 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-i@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-ii.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-ii.png new file mode 100644 index 000000000..2e45e75bb Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-ii.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-ii@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-ii@2x.png new file mode 100644 index 000000000..0423c1091 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-ii@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-iii.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-iii.png new file mode 100644 index 000000000..90f846706 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-iii.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-iii@2x.png b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-iii@2x.png new file mode 100644 index 000000000..5301cac2e Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/carousel-images/setup-silent-payments-onboarding-iii@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work-mobile.png b/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work-mobile.png new file mode 100644 index 000000000..7b1357158 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work-mobile.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work-mobile@2x.png b/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work-mobile@2x.png new file mode 100644 index 000000000..bfe8ba1c9 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work.png b/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work.png new file mode 100644 index 000000000..d0f537f92 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work@2x.png b/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work@2x.png new file mode 100644 index 000000000..b27b5f144 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work-mobile.png b/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work-mobile.png new file mode 100644 index 000000000..3f85f4147 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work-mobile.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work-mobile@2x.png b/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work-mobile@2x.png new file mode 100644 index 000000000..0ad1d52cf Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work.png b/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work.png new file mode 100644 index 000000000..b94ae8f06 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work@2x.png b/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work@2x.png new file mode 100644 index 000000000..16f72e5d1 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/silent-payments-header-mobile.png b/assets/images/guide/how-it-works/silent-payments/silent-payments-header-mobile.png new file mode 100644 index 000000000..c72cee054 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/silent-payments-header-mobile.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/silent-payments-header-mobile@2x.png b/assets/images/guide/how-it-works/silent-payments/silent-payments-header-mobile@2x.png new file mode 100644 index 000000000..ad8245ef7 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/silent-payments-header-mobile@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/silent-payments-header-preview.png b/assets/images/guide/how-it-works/silent-payments/silent-payments-header-preview.png new file mode 100644 index 000000000..f772b9aa1 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/silent-payments-header-preview.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/silent-payments-header.png b/assets/images/guide/how-it-works/silent-payments/silent-payments-header.png new file mode 100644 index 000000000..b7df848c4 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/silent-payments-header.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/silent-payments-header@2x.png b/assets/images/guide/how-it-works/silent-payments/silent-payments-header@2x.png new file mode 100644 index 000000000..39423435f Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/silent-payments-header@2x.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/silent-payments-preview-1200x630.png b/assets/images/guide/how-it-works/silent-payments/silent-payments-preview-1200x630.png new file mode 100644 index 000000000..e0f0ad268 Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/silent-payments-preview-1200x630.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options.png b/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options.png new file mode 100644 index 000000000..80849135b Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options.png differ diff --git a/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options@2x.png b/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options@2x.png new file mode 100644 index 000000000..cc9984a7d Binary files /dev/null and b/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options@2x.png differ diff --git a/guide.md b/guide.md index 198412429..1e8aae94b 100644 --- a/guide.md +++ b/guide.md @@ -170,7 +170,7 @@ How to design for use cases where it is important to manage multiple wallets in

[Inheritance wallet]({{ '/guide/inheritance-wallet/' | relative_url }})

-An in-depth exploration of a multi-key wallet designed for long-term savings and inheritance. It covers everything from wallet creation, backup, change management and succession. +An in-depth exploration of a multi-key wallet designed for long-term savings and inheritance. It covers everything from wallet creation, backup, change management and succession. --- @@ -202,6 +202,7 @@ Explanations of various technical aspects of bitcoin and lightning. [Lightning liquidity]({{ '/guide/how-it-works/liquidity/' | relative_url }})
[Lightning services]({{ '/guide/how-it-works/lightning-services/' | relative_url }})
[Sign in with bitcoin]({{ '/guide/how-it-works/sign-in-with-bitcoin/' | relative_url }})
+[Silent payments]({{ '/guide/how-it-works/silent-payments/' | relative_url }})
@@ -236,4 +237,4 @@ Join our open community and help us improve the Bitcoin Design Guide. Here’s w {% include next-previous.html nextUrl = "/guide/getting-started/introduction/" nextName = "Get started" -%} \ No newline at end of file +%} diff --git a/guide/how-it-works/custom-spending-conditions.md b/guide/how-it-works/custom-spending-conditions.md index ced9908c4..134be791d 100644 --- a/guide/how-it-works/custom-spending-conditions.md +++ b/guide/how-it-works/custom-spending-conditions.md @@ -2,7 +2,7 @@ layout: guide title: Custom spending conditions description: An overview about advanced capabilities that enable users to create more flexible bitcoin wallets. -nav_order: 12 +nav_order: 13 parent: How it works permalink: /guide/how-it-works/custom-spending-conditions/ main_classes: -no-top-padding @@ -46,13 +46,13 @@ In addition to these standard configurations it is also possible to create more #### Self-custody -Custom spending conditions can be helpful to decrease the risk of losing funds in personal self-custody context. Let's say that you have a wallet that you use regularly on a weekly basis. You could unlock a recovery spending condition automatically if that wallet has not been used for more than six months, because it's likely that you have lost access to your primary key. The recovery condition could contain an additional key held in a different location. Such a setup does not decrease the wallet security, because the second key is locked under normal circumstances of using the wallet. +Custom spending conditions can be helpful to decrease the risk of losing funds in personal self-custody context. Let's say that you have a wallet that you use regularly on a weekly basis. You could unlock a recovery spending condition automatically if that wallet has not been used for more than six months, because it's likely that you have lost access to your primary key. The recovery condition could contain an additional key held in a different location. Such a setup does not decrease the wallet security, because the second key is locked under normal circumstances of using the wallet. In a multi-key context, the recovery condition could require only one instead of two keys to spend funds after 6 months of inactivity. This will help mitigate the risk of loss of funds in case one key holder loses a key. #### Company treasuries -Custom spending conditions can also be useful in an organizational context. Companies need to make sure that they retain access to funds even if one or more employees lose their keys. Not only that, employees could also be compromised by a third party or try to obstruct the deployment of funds for their own benefit. Another use case is that a company needs to implement company-specific processes for corporate spending. For example, they would want to create a rule that the CFO must sign transactions for treasury management. +Custom spending conditions can also be useful in an organizational context. Companies need to make sure that they retain access to funds even if one or more employees lose their keys. Not only that, employees could also be compromised by a third party or try to obstruct the deployment of funds for their own benefit. Another use case is that a company needs to implement company-specific processes for corporate spending. For example, they would want to create a rule that the CFO must sign transactions for treasury management. ## Building blocks @@ -114,11 +114,11 @@ After the wallet has been created, it needs to be registered on all of the invol ### Timelocks -Timelocks can be relative (e.g. “1 year after the wallet has been last used”) or absolute (e.g. “on January 3rd, 2024”). +Timelocks can be relative (e.g. “1 year after the wallet has been last used”) or absolute (e.g. “on January 3rd, 2024”). ##### Relative timelocks -Relative timelocks can reach up to a maximum of 65535 blocks into the future, which is about 455 days. +Relative timelocks can reach up to a maximum of 65535 blocks into the future, which is about 455 days. An important aspect of timelocks is that they are applied to each [unspent transaction output (UTXO)](/guide/glossary/#unspent-transaction-output-utxo) in the wallet individually, not to the wallet as a whole. If a wallet uses relative timelocks, this means that the timelocks expire at different times for each UTXO, based on the time and date on which they were deposited into the wallet. @@ -135,7 +135,7 @@ An important aspect of timelocks is that they are applied to each [unspent trans layout = "float-right-desktop" %} -Let’s have a look at a concrete example. This image shows a wallet that contains three UTXOs with a total value of 0,40 BTC. The first UTXO of 0,10 BTC was received well ahead of the other two. And since it was not spent for six months, the recovery condition was unlocked. The emergency condition will unlock very soon, if the UTXO is not spent. +Let’s have a look at a concrete example. This image shows a wallet that contains three UTXOs with a total value of 0,40 BTC. The first UTXO of 0,10 BTC was received well ahead of the other two. And since it was not spent for six months, the recovery condition was unlocked. The emergency condition will unlock very soon, if the UTXO is not spent. As you can see, we are actually dealing with three timelocks, rather than one. @@ -153,16 +153,16 @@ Note that an on-chain transaction is required to reset a timelock, along with th #### Absolute timelocks -Absolute timelocks use a specific calendar date or block height as their reference point. In contrast to relative timelocks, absolute timelocks can go out as far as you want (the technical limit is 500 million blocks). +Absolute timelocks use a specific calendar date or block height as their reference point. In contrast to relative timelocks, absolute timelocks can go out as far as you want (the technical limit is 500 million blocks). Absolute timelocks apply the same timelock for each UTXO in the wallet. This has the advantage that they expire for all UTXOs in the wallet at the same time. This means that users only have to keep track of one deadline, which can make the management of the wallet easier and less demanding. -**Resetting an absolute timelock requires sending the funds to a brand new wallet,** because a self-transfer to the same wallet would re-apply the same absolute timelock to the newly created UTXO. If your product uses absolute timelocks, it is therefore recommended to provide features that help streamline this process for your users. +**Resetting an absolute timelock requires sending the funds to a brand new wallet,** because a self-transfer to the same wallet would re-apply the same absolute timelock to the newly created UTXO. If your product uses absolute timelocks, it is therefore recommended to provide features that help streamline this process for your users. ### Flexibility vs. complexity -Spending conditions based on Miniscript are composable. This means that you can create as many spending conditions as you like. You can even have one of the keys in one wallet be a multi-key wallet itself. Or you can combine time locked spending conditions with veto keys. It is also possible to combine relative and absolute timelocks. +Spending conditions based on Miniscript are composable. This means that you can create as many spending conditions as you like. You can even have one of the keys in one wallet be a multi-key wallet itself. Or you can combine time locked spending conditions with veto keys. It is also possible to combine relative and absolute timelocks. However, these kinds of setups can become complex very quickly and should not be used in most personal setups or by users who are new to bitcoin. diff --git a/guide/how-it-works/introduction.md b/guide/how-it-works/introduction.md index c10828c0c..70443f20c 100644 --- a/guide/how-it-works/introduction.md +++ b/guide/how-it-works/introduction.md @@ -86,6 +86,12 @@ How lightning wallets can support authentication and payments with external appl --- +### [Silent payments]({{ '/guide/how-it-works/silent-payments/' | relative_url }}) + +A simplified explanation of how silent payments work, along with its impact on bitcoin's interaction model and wallet flows. + +--- + ### [Wallet selector]({{ '/guide/how-it-works/wallet-selector/' | relative_url }}) Documentation of an interface pattern for letting users choose which external wallet to use when withdrawing, sending, or receiving in a bitcoin application. diff --git a/guide/how-it-works/sign-in-with-bitcoin.md b/guide/how-it-works/sign-in-with-bitcoin.md index 16b09a702..a01585e0c 100644 --- a/guide/how-it-works/sign-in-with-bitcoin.md +++ b/guide/how-it-works/sign-in-with-bitcoin.md @@ -166,11 +166,9 @@ If a user loses their wallet, they also lose their access to your service. Ensur --- -Next, view our [case studies]({{ '/guide/case-studies/' | relative_url }}) to see examples of design applied to real bitcoin software. - {% include next-previous.html previousUrl = "/guide/how-it-works/wallet-privacy/" previousName = "Wallet privacy" - nextUrl = "/guide/how-it-works/wallet-selector" - nextName = "Wallet selector" + nextUrl = "/guide/how-it-works/silent-payments" + nextName = "Silent payments" %} diff --git a/guide/how-it-works/silent-payments.md b/guide/how-it-works/silent-payments.md new file mode 100644 index 000000000..cccee027b --- /dev/null +++ b/guide/how-it-works/silent-payments.md @@ -0,0 +1,389 @@ +--- +layout: guide +title: Silent payments +description: How silent payments impact and improve bitcoin UX +nav_order: 11 +parent: How it works +permalink: /guide/how-it-works/silent-payments/ +main_classes: -no-top-padding +image: https://bitcoin.design/assets/images/guide/how-it-works/silent-payments/silent-payments-preview.png +image_base: /assets/images/guide/how-it-works/silent-payments/carousel-images/ +images_contacts: + - file: clipboard-options-add-contacts-or-pay + modalImage: clipboard-options-add-contacts-or-pay@2x + alt: A modal that prompts the user to create or save to a Contact when it detects a static address in the clipboard. + caption: A modal encourages the user to save a static address when it is detected on the clipboard. + - file: contact-page + modalImage: contact-page@2x + alt: The wallet owner's contact page, containing their bitcoin receiving methods with a QR at the top for a selected method. + caption: The wallet owner's contact page allows them to view and quickly share their payment information. + - file: contacts-list + modalImage: contacts-list@2x + alt: A Contacts page shows the user a searchable contact list, in order quickly access saved payment information, including their own. + caption: A Contacts page lets the user search and quickly access saved payment information, including their own. + - file: home-screen-with-contacts + modalImage: home-screen-with-contacts@2x + alt: App home screen containing a pinned contacts section, which includes a self contact for the wallet owner. + caption: A home screen with a pinned contacts section allows quick access to frequently used payment information. + +images_sp-onboarding: + - file: setup-silent-payments-onboarding-i + modalImage: setup-silent-payments-onboarding-i@2x + alt: A carousel page introducing the static address and a brief explainer. + caption: An onboarding page introducing the static address its ability to be safely reused. + - file: setup-silent-payments-onboarding-ii + modalImage: setup-silent-payments-onboarding-ii@2x + alt: A carousel page introducing labels along with an explainer. + caption: An onboarding page introducing labels, explaining they are automatically applied to payments received. + - file: setup-silent-payments-onboarding-iii + modalImage: setup-silent-payments-onboarding-iii@2x + alt: A carousel page introducing the Contacts feature. + caption: An onboarding page introducing the Contacts feature. + +images_send: + - file: send-review-sp + modalImage: send-review-sp@2x + alt: The send review page displaying the on-chain address explaining that it is derived from the static address. + caption: A note below the on-chain address explains that it is derived from the static address. + - file: send-review-sp-another + modalImage: send-review-sp-another@2x + alt: The send review page displaying the static address explaining that the on-chain address is different from it. + caption: A note below the static address mentions that the on-chain address is different from it. + - file: send-review-with-contact + modalImage: send-review-with-contact@2x + alt: The send review page with a contact item so that addresses do not have to be mentioned. + caption: Using contacts allows send pages to avoid mentioning addresses altogether. + - file: send-address-error + modalImage: send-address-error@2x + alt: A send review page with a error message under the address field informing the user about a static address not being supported. + caption: An error message under the address field informs the user about a static address not being supported. + +images_recovery: + - file: recovery-wallet-birthday-prompt + modalImage: recovery-wallet-birthday-prompt@2x + alt: Application screen with a toggle to opt into and enter a wallet birthday + caption: Applications should allow users to enter wallet birthday and while explaining its benefits. + - file: recovery-wallet-birthday-enter + modalImage: recovery-wallet-birthday-enter@2x + alt: A screen with a date picker for specifying the wallet birthday. + caption: A date picker allows the user to enter the wallet birthday before beginning recovery process. +--- + + + +{% include picture.html + image = "/assets/images/guide/how-it-works/silent-payments/silent-payments-header.png" + retina = "/assets/images/guide/how-it-works/silent-payments/silent-payments-header@2x.png" + mobile = "/assets/images/guide/how-it-works/silent-payments/silent-payments-header-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/silent-payments/silent-payments-header-mobile@2x.png" + alt-text = "A header image with a purple gradient, the text Silent Payments and a network visual." + width = 1600 + height = 600 + layout = "full-width" +%} + +# Silent payments +{: .no_toc } + +--- + +
+ * Table of contents +{:toc} +
+ +--- + +[Silent payments](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki) is a protocol that uses static addresses to simplify payment experience, while preserving privacy. Once the receiver shares a static address, senders derive a new unique on-chain addresses while making payments. This prevents [address reuse](/guide/glossary/address/#address-reuse) without repeated user interaction. + +For example: Alice can simply post a static address on her website, and receive bitcoin donations at unique on-chain addresses. The static address itself never shows up on-chain. + +Silent payments also allow users to customize their static address with labels that are detected when payments are received. This is a powerful tool that provides actionable information for [coin selection](/guide/how-it-works/silent-payments/#coin-selection), with minimal manual effort. + +Static addresses & labels enable robust [contacts](/guide/how-it-works/silent-payments/#contacts) features. The result is a better interaction model centred around users. + + +### Rationale + +Since the bitcoin blockchain is public, reusing an on-chain address informs the network that these payments are made to the same user. However, specifying a new address for each transaction usually requires user interaction. This is error-prone, takes time and requires manual effort. + +Silent payments circumvent both these issues by using static addresses (starting with `sp1`). + +## How silent payments work + +Silent payments are made in 4 broad steps: +1. The receiver shares/publishes a static payment address (manual, one-time) +2. The sender obtains & uses it to derive a unique on-chain address (partly automated) +3. The sender broadcasts a transaction that pays this derived address (manual) +4. The receiver scans the blockchain & identifies their payments (automated) + +{% include picture.html + image = "/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work.png" + retina = "/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work@2x.png" + mobile = "/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work-mobile@2x.png" + modalImage = "/assets/images/guide/how-it-works/silent-payments/how-silent-payments-work@2x.png" + alt-text = "An image that illustrates how silent payments work in 4 steps." + caption = "Alice posts a static address on the website of her non-profit, Chasing Rabbits. Bob uses it to send bitcoin from his wallet. This transaction pays a derived on-chain address that Alice can recognise while scanning the blockchain." + width = 1024 + height = 640 + layout = "full-width" +%} + +## A new conceptual model + +Silent payments introduce a new technical model that separates payment information based on its purpose. + +Here are the main components of this new model with their purpose: + +| Component |Used by | Purpose | +|:-------------|:------------------|:------| +| Static address | Senders | Making payments +| Scan key | [Nodes & light clients](/guide/how-it-works/nodes) | Detecting payments +| Spend key | Wallet owner | Spending bitcoin + +As shown above, the model introduces a scan key that is used for payment scanning and a static address which is used for deriving on-chain addresses. This is in contrast with the [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) model where [extended public key](/guide/glossary/#extended-public-key-xpub-ypub-zpub) are used for both purposes. Below is a summary of the differences between the two models: + +| BIP-32 | Silent payments | Benefit | +|:-------------|:------------------|:------| +| On-chain address | Static address | Reusable; untraceable on-chain | +| Extended private key (xprv) | Spend key | | +| Extended public key (xpub) | Scan key | Nodes & light clients can scan for payments but cannot derive addresses | +| *Address-based model* | *Contact-based model* | *More intuitive and familiar* | + + +## Labels & contacts + +### Labels + +
+ +{% include picture.html + image = "/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address.png" + retina = "/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address@2x.png" + modalImage = "/assets/images/guide/how-it-works/silent-payments/adding-labels-to-static-address@2x.png" + alt-text = "An application screen showing labels being added to a static address." + caption = "Adding labels to a static address before posting or sharing with others." + width = 250 + height = 542 + layout = "float-right-desktop -background -shadow" +%} + +Labels (such as `business` or `no-kyc`) are brief identifiers often associated with information such as payments, transactions and addresses. They're used to organise, categorise or quickly spot information from a large set. + +Silent payments allow users to add labels to their static addresses on a case-by-case basis before sharing or posting them. When a payment is received, these labels can be detected by the receiver (but no one else) and used to identify the static address that was used to make the payment. + +
+ +For example, Alice can customise her static address with different labels before sharing them: +- with a certain client +- on Nostr and +- on her website + +When she receives payments from any of these sources, the respective label(s) will be detected in the on-chain address and used to infer the source of the payment. + +{% include picture.html + image = "/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work.png" + retina = "/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work@2x.png" + mobile = "/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work-mobile.png" + mobileRetina = "/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work-mobile@2x.png" + modalImage = "/assets/images/guide/how-it-works/silent-payments/how-silent-payment-labels-work@2x.png" + alt-text = "An image that illustrates how labels feature in silent payments works." + caption = "Alice customizes her static address with labels before she shares them. Whenever she receives a payment from one of them, the label is auto-applied and detected by the wallet." + width = 1024 + height = 801 + layout = "full-width" +%} + +This scheme improves labelling in general, since labels get auto-applied to all derived on-chain addresses. This eliminates the friction of manually adding labels to addresses or transactions. Labels can contain crucial information that is useful for automatic or manual coin selection for future outgoing payments. + +#### Tracking payments + +Without labels, receivers have no way of knowing who may have paid them. This is because the sender independently generates the on-chain addresses without any involvement of the receiver. + +{% include tip/recommendation.html %} + +Labels in silent payments are critical when receivers, such as businesses, need to match payments with customers. + +{% include tip/close.html %} + +Here's how businesses, such as exchanges, merchants and vendors can use labels: +- **Invoices:** merchant software like [BTCPay](https://btcpayserver.org/) must use labels to match incoming payments with invoices and/or provide unique static addresses to repeat customers. +- **Bitcoin exchange deposits:** Customers looking to sell/deposit bitcoin at exchanges encounter friction when their deposit addresses change constantly. Labelled static addresses for users fix this without address reuse while retaining the ability to match deposits to customers. +- **Bitcoin exchange withdrawals:** Customers can withdraw bitcoin from exchanges by providing a (labelled) static address just once, without having to provide an on-chain address every time. This facilitates best practices like [DCA](https://river.com/learn/terms/d/dollar-cost-averaging-dca/) and self-custody, while labels identify bitcoin from exchanges. + + +### Contacts + + Since senders can safely use the same static address for multiple payments, it is natural for them to want to store these for future use. Contacts are a great way to do this in a way that users can intuit: names and faces. The [contacts](/guide/daily-spending-wallet/contacts/) page provides guidance about the topic. + + Silent payments (along with [BOLT-12](http://bolt12.org)) allow applications to center their payments experience around people instead of addresses. This was not advisable before, due to issues with on-chain address reuse. + + +{% include image-gallery.html pages = page.images_contacts %} + +{% include tip/tip.html %} + +Contacts are not just for sending. The receiver can create contacts for parties they only receive bitcoin from. When they share a labelled static addresses with others, such as employers or customers, creating a contact can help with invoicing, tracking payments and coin selection. + +{% include tip/close.html %} + + +## Setup + +Applications can take a variety of approaches to set up and communicate silent payment wallets. Benefits of silent payments, such as contacts and auto-labelling, should be explained during setup. Some wallets may use unique or significant locations (mobile widget, custom app logos, watch faces) to place this static address for easy retrieval, and may highlight the same during setup. + +{% include image-gallery.html pages = page.images_sp-onboarding %} + + +## Sending + +With the improvements to contacts, on-chain send flows may start from a number of [entry points](/guide/daily-spending-wallet/sending/#payment-entry-points). When users start with obtaining a static address, every on-chain address derived from it will be visibly different from the static address the sender started with. This is likely to be confusing for users. Applications should take measures such as short explainers to avoid confusion on the user's part. Test transactions are another good way to help users deal with this. + +{% include image-gallery.html pages = page.images_send %} + + +{% include tip/recommendation.html %} + +Applications that do not support static addresses should provide helpful, actionable, human readable errors. + +{% include tip/close.html %} + +### Coin selection +As mentioned in the introduction, coin selection can be significantly improved due to auto-applied label information. Applications should encourage and assist users during coin selection by surfacing relevant or related labels. Automatic coin selection should be improved with all the label information available. + +{% include tip/tip.html %} + +The coin(s) selected for a transaction determine the derived on-chain address, due to the nature of the silent payments protocol. The interface should avoid showing the on-chain address before the coin selection is done. + +{% include tip/close.html %} + +## Receiving & scanning + +
+ +{% include picture.html + image = "/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options.png" + retina = "/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options@2x.png" + modalImage = "/assets/images/guide/how-it-works/silent-payments/static-address-with-customization-options.png" + width = 250 + height = 522 + alt-text = "The user contact page listing their receive static address along with the ability to add labels before sharing it." + caption = "The user contact page allows the user to add labels to their receive static address before sharing it." + layout = "float-right-desktop -background -shadow" +%} + +Receiving flows are likely to be used less often, since static addresses can be safely reused. If the receiver has publicly posted their static address, they will receive payments without any interaction with the sender. Therefore, applications should encourage users to add labels or a contact whenever they actively share a static address with a sender. + +Applications should also allow receivers to generate and share conventional on-chain addresses in case the sender's wallet cannot send to static addresses. + +Some practical examples for where users might want to share (labelled) static addresses include: +- Social media pages +- Fundraising websites +- Exchanges +- Email signatures + +
+ + +The tradeoff with silent payments, for all their benefits, is a higher blockchain scanning requirement. This scanning process is more computation-intensive and time-consuming than for popular BIP-32 wallets and addresses. Mobile wallet users are likely to face a noticeable delay in detecting payments once they come online. While scanning takes place, applications should show progress and the estimated completion time. + + +## Backup & Recovery + +### Backup + +
+ +{% include picture.html + image = "/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday.png" + retina = "/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday@2x.png" + modalImage = "/assets/images/guide/how-it-works/silent-payments/backup-wallet-birthday.png" + width = 250 + height = 522 + alt-text = "A backup flow screen with a calendar visual highlighting the wallet creation date and mentioning it prominently." + caption = "Display wallet birthday as a part of the backup flow and explain the benefit of storing it." + layout = "float-right-desktop -background -shadow" +%} + +Like [lightning wallets](/guide/daily-spending-wallet/backup-and-recovery/cloud-backup/), on-chain wallets with robust silent payments functionality require file backups (cloud or offline). This is because such wallets have valuable [user metadata](/guide/daily-spending-wallet/backup-and-recovery/landing-page/#user-metadata) such as: +- scan and/or spend keys +- [tweak data](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki#user-content-Tweak_Data) +- [labels](/guide/how-it-works/silent-payments/#labels) +- contacts + +Applications should allow users to manually note backup information in case they misplace the backup file or the recovery application does not support backup files at all. Like regular wallets, silent payment wallets can also be backed up and restored using a recovery phrase. However, this method may result in longer recovery times as well as loss of valuable metadata. + +
+ +{% include tip/recommendation.html %} + +Applications should display backup information such as recovery phrase or wallet birthday in the UI even if file backups are being performed. This could reuse existing functionality and serve as a partial manual backup. + +{% include tip/close.html %} + + +### Recovery + +In addition to recovery methods mentioned [here](/guide/daily-spending-wallet/backup-and-recovery/recovery/), applications may enable manual recovery with data unique to silent payments wallets, such as scan/spend key material. + +Allowing users to enter the wallet creation date (wallet birthday) during recovery can help reduce recovery time substantially. + +Applications should allow both backup & recovery through multiple methods. This is especially important when backup & recovery features are not standardised – during early stages of adoption and if wallets do not support silent payments. + + +{% include image-gallery.html pages = page.images_recovery %} + +## Pros and cons + +{% include fact/pros.html %} + +- Prevents address reuse without repeated user interactions +- Enables a better user interaction model centred around users instead of unwieldy addresses +- Reduces the possibility of mistakes while handling on-chain addresses +- Allows users to optionally infer payment sources through labels +- Auto-applied labels improve coin-labelling and coin selection +- Scanning process is more private since sharing on-chain addresses (or xpubs) is not required + +{% include fact/close.html %} + +{% include fact/cons.html %} + +- Static addresses do not match on-chain addresses in transactions, breaking the conceptual model for seasoned users +- Scanning for payments doesn’t work well with electrum servers (widely used by wallets) + +{% include fact/close.html %} + +## Resources + +- [BIP-352](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki) +- [https://silentpayments.xyz/](https://silentpayments.xyz/) + +### Wallets implementing silent payments + +- [Cake wallet](https://cakewallet.com/) +- [Blue wallet](https://bluewallet.io/) (sending only) + + +--- + +{% include next-previous.html + previousUrl = "/guide/how-it-works/sign-in-with-bitcoin/" + previousName = "Sign in with bitcoin" + nextUrl = "/guide/how-it-works/wallet-selector" + nextName = "Wallet selector" +%} diff --git a/guide/how-it-works/stabilizing-bitcoin-value.md b/guide/how-it-works/stabilizing-bitcoin-value.md index 4ef04804b..9af86b081 100644 --- a/guide/how-it-works/stabilizing-bitcoin-value.md +++ b/guide/how-it-works/stabilizing-bitcoin-value.md @@ -2,7 +2,7 @@ layout: guide title: Stabilizing bitcoin value description: -nav_order: 13 +nav_order: 14 parent: How it works permalink: /guide/how-it-works/stabilizing-bitcoin-value/ main_classes: -no-top-padding diff --git a/guide/how-it-works/wallet-selector.md b/guide/how-it-works/wallet-selector.md index 200ed5d19..123cababa 100644 --- a/guide/how-it-works/wallet-selector.md +++ b/guide/how-it-works/wallet-selector.md @@ -2,7 +2,7 @@ layout: guide title: Wallet selector description: An interface pattern for letting users choose which external wallet to use when withdrawing, sending, or receiving in a bitcoin application. -nav_order: 11 +nav_order: 12 parent: How it works permalink: /guide/how-it-works/wallet-selector/ main_classes: -no-top-padding