Merge remote-tracking branch 'upstream/master' into invoice-patch

Bosch-0 · Bosch-0 · commit f5009ca9ed27 · 2022-03-04T14:53:01.000+08:00
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ An equally important goal is that the process of creating this guide nurtures an
 
 ## Process and how to contribute
 
-The process of creating the guide is meant to be as open and decentralized as possible, resulting in a sustainable model to run projects with the community. Most of the discussion happens in the [Bitcoin Design Slack](http://bitcoindesigners.org), in the #bitcoin-design-guide, and here on GitHub in [Issues](https://github.com/BitcoinDesign/Guide/issues), [Pull requests](https://github.com/BitcoinDesign/Guide/pulls) and [Discussions](https://github.com/BitcoinDesign/Guide/discussions).
+The process of creating the guide is meant to be as open and decentralized as possible, resulting in a sustainable model to run projects with the community. Most of the discussion happens in the [Bitcoin Design Slack](http://bitcoindesigners.org), in the #bitcoin-design-guide channel, and here on GitHub in [Issues](https://github.com/BitcoinDesign/Guide/issues), [Pull requests](https://github.com/BitcoinDesign/Guide/pulls) and [Discussions](https://github.com/BitcoinDesign/Guide/discussions). Also see the [roadmap](https://github.com/orgs/BitcoinDesign/projects/2) for an overview of current and upcoming activities.
 
 You can read more about [how to contribute](https://bitcoin.design/guide/contribute/).
 
@@ -42,6 +42,8 @@ The process to create the guide started in the summer of 2020. The first draft o
 
 On June 2, 2021, the community [announced](https://bitcoindesign.medium.com/announcing-the-bitcoin-design-guide-c4955d859fda) the launch of the initial version of the Bitcoin Design Guide to the public.
 
+On February 9, 2022, the community [announced](https://bitcoindesign.medium.com/design-better-lightning-wallets-with-the-bitcoin-design-guide-v2-2669f610ebc7) the completion of a major revision of the guide to include content about the Lightning network.
+
 ---
 
 
diff --git a/guide.md b/guide.md
@@ -43,14 +43,6 @@ Illustration sources
 
 We designed this guide to help anyone navigate those complexities—regardless of where they live or work. We can’t imagine every possible use case, but we can help you build for them.
 
-{% include tip/tip.html %}
-
-This guide is a work in progress. We are currently adding information about the [Lightning Network]({{ '/guide/glossary/#lightning-network' | relative_url }}) on all relevant pages.
-
-You can track the progress on this [Github issue]({{ 'https://github.com/BitcoinDesign/Guide/issues/478' }}).
-
-{% include tip/close.html %}
-
 ---
 
 ### [Getting started]({{ '/guide/getting-started/introduction/' | relative_url }})
diff --git a/guide/designing-products/common-user-flows.md b/guide/designing-products/common-user-flows.md
@@ -282,7 +282,7 @@ Like fiat currencies, securely storing funds can be as simple as storing some co
 
 ## Backing up a wallet
 
-To enable recovery of a wallet that uses the manual backup scheme for private key management, we should ask users to securely back up their keys with their recovery phrase (and for full compatibility, [derivation path](/guide/glossary/#derivation-path) and [output descriptors](/guide/glossary/#output-script-descriptor)) when they create new wallets.  See also, [Wallet interoperability](/guide/designing-products/wallet-interoperability/) and [bitcoin backups](/guide/private-key-management/backups/).
+To enable recovery of a wallet that uses the manual backup scheme for private key management, we should ask users to securely back up their keys with their [recovery phrase]({{ '/guide/glossary/#recovery-phrase' | relative_url }}) (and for full compatibility, [derivation path](/guide/glossary/#derivation-path) and [output descriptors](/guide/glossary/#output-script-descriptor)) when they create new wallets.  See also, [Wallet interoperability](/guide/designing-products/wallet-interoperability/) and [bitcoin backups](/guide/private-key-management/backups/).
 
 ## Importing an existing wallet
 
diff --git a/guide/designing-products/getting-to-know-your-users.md b/guide/designing-products/getting-to-know-your-users.md
@@ -173,7 +173,7 @@ Motivators are specific user wants that are driving the user to seek out bitcoin
 ## Brainstorm solutions with your team
 With this information, you can craft solutions based on these barriers and motivators to create the best experience for a user like Josh.
 
-To weaken Josh's "Fear of losing a private key," a [wallet]({{ 'guide/getting-started/software/#wallets' | relative_url }}) might opt to initially backup an encrypted version of his recovery phrase to a cloud provider and educate him over time on how to take more control of his private key.
+To weaken Josh's "Fear of losing a private key," a [wallet]({{ 'guide/getting-started/software/#wallets' | relative_url }}) might opt to initially backup an encrypted version of his [recovery phrase]({{ '/guide/glossary/#recovery-phrase' | relative_url }}) to a cloud provider and educate him over time on how to take more control of his private key.
 
 Savings is a big motivator for Josh and so you should have a big focus on security and making sure a loss of funds over a long period of time is virtually impossible. Given that control is also a motivator, a wallet could aim to provide as much customizability as possible such as fee selection or coin selection.
 
diff --git a/guide/designing-products/principles.md b/guide/designing-products/principles.md
@@ -102,7 +102,7 @@ layout="float-left"
 
 Self-custody often leaves the end-user responsible for the security of their private keys. They can only do a good job of that if we provide them with appropriate tools and awareness of best practices.
 
-Security is especially important when onboarding people who are new to bitcoin. For example, new users are likely to start by only storing small amounts. After a while, they may become more comfortable with the idea of self-custody and begin to store larger amounts. The concept of progressive security is a good idea here, starting with [automatic cloud backups]({{'/guide/onboarding/backing-up-a-wallet/cloud-backup/' | relative_url}}). This would let a user upgrade their security and private key management scheme as their savings grow. Although common, recovery phrases that require [manual backup]({{'/guide/onboarding/backing-up-a-wallet/manual-backup/' | relative_url}}) might backfire for new users not yet familiar with safe backup practices.
+Security is especially important when onboarding people who are new to bitcoin. For example, new users are likely to start by only storing small amounts. After a while, they may become more comfortable with the idea of self-custody and begin to store larger amounts. The concept of progressive security is a good idea here, starting with [automatic cloud backups]({{'/guide/onboarding/backing-up-a-wallet/cloud-backup/' | relative_url}}). This would let a user upgrade their security and private key management scheme as their savings grow. Although common, [recovery phrases]({{ '/guide/glossary/#recovery-phrase' | relative_url }}) that require [manual backup]({{'/guide/onboarding/backing-up-a-wallet/manual-backup/' | relative_url}}) might backfire for new users not yet familiar with safe backup practices.
 
 Education and awareness are a big part of security, as they can protect users from bad actors and potentially their own security mistakes. It is unrealistic to expect beginners to take in all the knowledge acquired by advanced users in one go, for example, while [onboarding]({{ '/guide/onboarding/introduction/' | relative_url }}) to a bitcoin product. We should therefore consider how to continuously educate and level up user awareness of best practices and risks.
 
diff --git a/guide/getting-started/hardware.md b/guide/getting-started/hardware.md
@@ -42,7 +42,7 @@ General purpose hardware, like personal computers and smartphones, work great fo
 
 ## Physical backups
 
-Recovery phrases and other important recovery data such as descriptors are often backed up physically. Many simple, cheap, and robust physical backup solutions for bitcoin exist.
+[Recovery phrases]({{ '/guide/glossary/#recovery-phrase' | relative_url }}) and other important recovery data such as descriptors are often backed up physically. Many simple, cheap, and robust physical backup solutions for bitcoin exist.
 
 {% include picture.html
    image = "/assets/images/guide/getting-started/hardware/hardware-seed-storage.jpg"
diff --git a/guide/glossary/index.md b/guide/glossary/index.md
@@ -320,7 +320,7 @@ A node policy that allows an unconfirmed transaction to be replaced with a diffe
 
 _Also referred to as Seed, Mnemonic, and Backup phrase._
 
-The controlling keypair of a bitcoin wallet can be derived from a *recovery phrase* of 12 words (or 18 or 24, which is less common) from a standardized list, defined in [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki). The recovery phrase provides full access to a bitcoin wallet as it contains the private key and is therefore very valuable. It’s extremely important to keep it safe, both from other people getting access to it and for yourself not to lose it by creating one or several backups of the phrase. In many applications most of this work falls on the user and it’s important to acknowledge the responsibility here of the makers of the application to ensure that the user is able and aware of how to securely store a recovery phrase backup.
+The controlling keypair of a bitcoin wallet can be derived from a *recovery phrase* of 12 words (it can also be 18 or 24 words, which is less common and not recommended as it does not provide better security) from a standardized list, defined in [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki). The recovery phrase provides full access to a bitcoin wallet as it contains the private key and is therefore very valuable. It’s extremely important to keep it safe, both from other people getting access to it and for yourself not to lose it by creating one or several backups of the phrase. In many applications most of this work falls on the user and it’s important to acknowledge the responsibility here of the makers of the application to ensure that the user is able and aware of how to securely store a recovery phrase backup.
 
 Many wallet-applications work with HD Wallets and recovery phrases, and are interoperable, meaning you can change the application that can control your wallet should you wish (although there are some caveats depending on if they support just BIP32 or also BIP44).
 
diff --git a/guide/glossary/wallet.md b/guide/glossary/wallet.md
@@ -27,7 +27,7 @@ This term is often used interchangeably for very different things. A user can *d
 
 #### Bitcoin wallet
 
-All bitcoin-related data derived from and associated with a single recovery phrase. Most modern bitcoin wallets are HD wallets.
+All bitcoin-related data derived from and associated with a single [recovery phrase]({{ '/guide/glossary/#recovery-phrase' | relative_url }}). Most modern bitcoin wallets are HD wallets.
 
 #### HD wallet
 
diff --git a/guide/onboarding/cloud-backup.md b/guide/onboarding/cloud-backup.md
@@ -37,7 +37,7 @@ layout = "full-width"
 
 ### How it works
 
-The user's wallet recovery data and channel states are backed up on their respective cloud storage provider. The recovery phrase only needs to be backed up once. However, channel states may need to be backed up frequently because they change every time the user's wallet sends, receives, or routes a payment; therefore, the channel state should be backed up automatically.
+The user's wallet recovery data and channel states are backed up on their respective cloud storage provider. The [recovery phrase]({{ '/guide/glossary/#recovery-phrase' | relative_url }}) only needs to be backed up once. However, channel states may need to be backed up frequently because they change every time the user's wallet sends, receives, or routes a payment; therefore, the channel state should be backed up automatically.
 
 If the user's device is lost, stolen, or broken, they can use the backup from their cloud storage account (such as Apple iCloud or Google Drive) to regain access to their funds. To learn more about the technical details, hop over to the [private key management]({{ '/guide/private-key-management/introduction' | relative_url }}) section on this topic.
 
@@ -74,7 +74,7 @@ height = 541
 {% include picture.html
      image = "/assets/images/guide/onboarding/backing-up-a-wallet/automatic-cloud-backup/cloud-backup-PIN.png"
    retina = "/assets/images/guide/onboarding/backing-up-a-wallet/automatic-cloud-backup/cloud-backup-PIN@2x.png"
-   class = "shadow"
+   layout = "shadow"
    caption = "Allows the user to set a PIN used for authentication."
    alt-text = "The user can set a PIN which will be used to authenticate and access the wallet"
    width = 250
@@ -84,7 +84,7 @@ height = 541
 {% include picture.html
      image = "/assets/images/guide/onboarding/backing-up-a-wallet/automatic-cloud-backup/cloud-backup-service.png"
    retina = "/assets/images/guide/onboarding/backing-up-a-wallet/automatic-cloud-backup/cloud-backup-service@2x.png"
-   class = "shadow"
+   layout = "shadow"
    caption = "Give the user different cloud provider options, others such as Dropbox might also be included."
    alt-text = "Screen showing saving a password to encrypt the recovery phrase"
    width = 250
@@ -94,7 +94,7 @@ height = 541
 {% include picture.html
      image = "/assets/images/guide/onboarding/backing-up-a-wallet/automatic-cloud-backup/cloud-backup-provider.png"
    retina = "/assets/images/guide/onboarding/backing-up-a-wallet/automatic-cloud-backup/cloud-backup-provider@2x.png"
-   class = "shadow"
+   layout = "shadow"
    caption = "This UI will be very different depending on the cloud provider and what permissions are required."
    alt-text = "Screen of placeholder where cloud provider UI would be"
    width = 250
@@ -104,7 +104,7 @@ height = 541
 {% include picture.html
    image = "/assets/images/guide/onboarding/backing-up-a-wallet/automatic-cloud-backup/cloud-backup-confirmation.png"
    retina = "/assets/images/guide/onboarding/backing-up-a-wallet/automatic-cloud-backup/cloud-backup-confirmation@2x.png"
-   class = "shadow"
+   layout = "shadow"
    caption = "Once the upload is complete it's a good idea to show a success screen and give some reassurances."
    alt-text = "Screen showing completing a cloud backup"
    width = 250
diff --git a/guide/onboarding/first-use.md b/guide/onboarding/first-use.md
@@ -44,7 +44,7 @@ There are a number of common tasks a user might want to achieve the first time t
 
 While the first two, creating or restoring a wallet, normally need to be tackled straight away, the last two can be designed to fit the flow and capability of your application.
 
-It is common to see onboarding flows that implore the user to do a manual backup of their recovery phrase straight away, often before they have even gotten to see the main screen of the application. While this can make sure the user is aware of the need to backup, their motivation and ability to safely do this at that exact moment might be limited.
+It is common to see onboarding flows that implore the user to do a manual backup of their [recovery phrase]({{ '/guide/glossary/#recovery-phrase' | relative_url }}) straight away, often before they have even gotten to see the main screen of the application. While this can make sure the user is aware of the need to backup, their motivation and ability to safely do this at that exact moment might be limited.
 
 Alternative approaches can be to wait and prompt the user only once there are funds in the wallet, at regular intervals, or to use an automatic cloud backup for small amounts. It is up to you as the application designer to decide what works best in your users’ use case.
 
@@ -98,6 +98,7 @@ Below is an example of some carousel screens that might be useful in helping a u
    retina = "/assets/images/guide/onboarding/first-use/product-intro-1@2x.png"
    alt-text = "Introduction screen explaining ownership"
    caption = "Talk about ownership"
+   layout = "shadow"
    width = 250
    height = 541
 %}
@@ -107,6 +108,7 @@ Below is an example of some carousel screens that might be useful in helping a u
    retina = "/assets/images/guide/onboarding/first-use/product-intro-2@2x.png"
    alt-text = "Introduction screen explaining recovery"
    caption = "Talk about recovery"
+   layout = "shadow"
    width = 250
    height = 541
 %}
@@ -116,6 +118,7 @@ Below is an example of some carousel screens that might be useful in helping a u
    retina = "/assets/images/guide/onboarding/first-use/product-intro-3@2x.png"
    alt-text = "Introduction screen explaining security"
    caption = "Talk about security"
+   layout = "shadow"
    width = 250
    height = 541
 %}
diff --git a/guide/onboarding/manual-backup.md b/guide/onboarding/manual-backup.md
@@ -44,7 +44,7 @@ Manual backups of Lightning channel state should only be performed with careful
 ## Backing up wallet recovery data
 
 Manual backup should be used primarily for wallet recovery data. Wallet recovery data includes:
-- The recovery phrase
+- The [recovery phrase]({{ '/guide/glossary/#recovery-phrase' | relative_url }})
   - Type - BIP39, Electrum, Shamir Shares (SLIP39), AEZEED
   - Passphrase (optional)
 - Derivation path
diff --git a/guide/onboarding/protecting-a-wallet.md b/guide/onboarding/protecting-a-wallet.md
@@ -47,7 +47,7 @@ Illustration sources
 
 ---
 
-Bitcoin wallets contain sensitive information such as recovery phrases, balances, transaction histories, and more. Therefore, it is crucial to add extra layers of security to keep private data, and access to sensitive functionality, out of bad actors' hands. Additional protection may also be necessary for users who share devices, such as parents with children.
+Bitcoin wallets contain sensitive information such as [recovery phrases]({{ '/guide/glossary/#recovery-phrase' | relative_url }}), balances, transaction histories, and more. Therefore, it is crucial to add extra layers of security to keep private data, and access to sensitive functionality, out of bad actors' hands. Additional protection may also be necessary for users who share devices, such as parents with children.
 
 ## Proactive support
 
diff --git a/guide/onboarding/restoring-a-wallet.md b/guide/onboarding/restoring-a-wallet.md
@@ -34,7 +34,7 @@ Illustration sources:
 
 There are several reasons why a user might need to restore their bitcoin wallet. They may have lost their device, be migrating from a different application or have deleted their wallet application. Regardless of why, it’s important that your wallet application has an easy way for users to recover their funds.
 
-However, not all wallets from one application can be recovered in another, depending on what standards they support, as covered in the [wallet interoperability]({{ 'guide/designing-products/wallet-interoperability' | relative_url }}) section. Lack of interoperability and vendor dependance is an issue for wallets holding bitcoin on the Lightning network. Lightning network wallets can currently only be restored in the application originally used. It's also worth noting that restoring from a recovery phrase only restores the private keys, but no user data like transaction notes, contacts etc.
+However, not all wallets from one application can be recovered in another, depending on what standards they support, as covered in the [wallet interoperability]({{ 'guide/designing-products/wallet-interoperability' | relative_url }}) section. Lack of interoperability and vendor dependance is an issue for wallets holding bitcoin on the Lightning network. Lightning network wallets can currently only be restored in the application originally used. It's also worth noting that restoring from a [recovery phrase]({{ '/guide/glossary/#recovery-phrase' | relative_url }}) only restores the private keys, but no user data like transaction notes, contacts etc.
 
 {% include picture.html
    image = "/assets/images/guide/onboarding/restoring-a-wallet/import-options.png"
diff --git a/guide/private-key-management/external-signer.md b/guide/private-key-management/external-signer.md
@@ -38,7 +38,7 @@ https://www.figma.com/file/qr4P17z6WSPADm6oW0cKw2/?node-id=261%3A1837
 
 # External signers
 
-External signers use, store, and manage private keys and other sensitive info, such as the user's recovery phrase, externally from the user's wallet application. The most common external signers used today are hardware wallets. Software-only external signing applications also exist, but are less secure than their hardware counterparts.
+External signers use, store, and manage private keys and other sensitive info, such as the user's [recovery phrase]({{ '/guide/glossary/#recovery-phrase' | relative_url }}), externally from the user's wallet application. The most common external signers used today are hardware wallets. Software-only external signing applications also exist, but are less secure than their hardware counterparts.
 
 A wallet application supporting external signers removes the need for storing private keys locally by the wallet application. This decreases the theft risk as the keys can be isolated from the internet and/or a potentially malicious device.
 
