diff --git a/README.md b/README.md index a354d726f..2f3e6e5f4 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Here is an initial outline that will be updated as needed, content that is live * Technology primer * Software overview * Hardware overview -* Bitcoin design principles (to be discussed) +* [Bitcoin design principles](https://bitcoin.design/guide/principles/principles/) * Decentralization * Self-sovereignty * Security @@ -51,7 +51,6 @@ Here is an initial outline that will be updated as needed, content that is live * Private key schemes * Personal schemes * Shared schemes - * Principles * Case studies * Payments and transactions - [Discussion about WIP](https://github.com/BitcoinDesign/Guide/discussions/98) * Transactions overview diff --git a/assets/images/guide/private-key-management/principles/page-principles.jpg b/assets/images/guide/foundations/principles/page-principles.jpg similarity index 100% rename from assets/images/guide/private-key-management/principles/page-principles.jpg rename to assets/images/guide/foundations/principles/page-principles.jpg diff --git a/assets/images/guide/private-key-management/principles-mobile.jpg b/assets/images/guide/foundations/principles/principles-mobile.jpg similarity index 100% rename from assets/images/guide/private-key-management/principles-mobile.jpg rename to assets/images/guide/foundations/principles/principles-mobile.jpg diff --git a/assets/images/guide/private-key-management/principles-mobile@2x.jpg b/assets/images/guide/foundations/principles/principles-mobile@2x.jpg similarity index 100% rename from assets/images/guide/private-key-management/principles-mobile@2x.jpg rename to assets/images/guide/foundations/principles/principles-mobile@2x.jpg diff --git a/assets/images/guide/private-key-management/principles.jpg b/assets/images/guide/foundations/principles/principles.jpg similarity index 100% rename from assets/images/guide/private-key-management/principles.jpg rename to assets/images/guide/foundations/principles/principles.jpg diff --git a/assets/images/guide/private-key-management/principles@2x.jpg b/assets/images/guide/foundations/principles/principles@2x.jpg similarity index 100% rename from assets/images/guide/private-key-management/principles@2x.jpg rename to assets/images/guide/foundations/principles/principles@2x.jpg diff --git a/guide/contribute/contribute.md b/guide/contribute/contribute.md index 66ee30f79..4b6d92f63 100644 --- a/guide/contribute/contribute.md +++ b/guide/contribute/contribute.md @@ -2,7 +2,7 @@ layout: guide title: Contribute to guide description: Additional material for both readers and writers of the guide. -nav_order: 9 +nav_order: 8 has_children: true permalink: /guide/contribute/ image: /assets/images/guide/contribute/contribute-preview.jpg diff --git a/guide/foundations/foundations.md b/guide/foundations/foundations.md index 6d79641f8..11a8f7fba 100644 --- a/guide/foundations/foundations.md +++ b/guide/foundations/foundations.md @@ -10,7 +10,13 @@ image: /assets/images/guide/foundations/foundations-preview.jpg # Foundations -Learn about some of the basic principles to keep in mind when designing Bitcoin applications. +Learn about some of the basics to keep in mind when designing Bitcoin applications. + +--- + +**[Bitcoin design principles]({{ '/guide/foundations/principles/' | relative_url }})** + +Principles that the Bitcoin Design Community have identified and stand behind. Although every use case and product is different, applications should strive to follow these principles. --- diff --git a/guide/foundations/principles.md b/guide/foundations/principles.md new file mode 100644 index 000000000..eb9e82c94 --- /dev/null +++ b/guide/foundations/principles.md @@ -0,0 +1,182 @@ +--- +layout: guide +title: Principles +description: The key principles to follow when designing Bitcoin products. +nav_order: 9 +parent: Foundations +permalink: /guide/foundations/principles/ +main_classes: -no-top-padding +image: /assets/images/guide/foundations/principles/page-principles.jpg +--- + + + +{% include picture.html + image = "/assets/images/guide/foundations/principles/principles.jpg" + retina = "/assets/images/guide/foundations/principles/principles@2x.jpg" + mobile = "/assets/images/guide/foundations/principles/principles-mobile.jpg" + mobileRetina = "/assets/images/foundations/principles/principles-mobile@2x.jpg" + alt-text = "Principles header illustration, five white circles in a horizontal line on black background" + width = 1600 + height = 600 + layout = "full-width" +%} + +# Bitcoin design principles + +As a new technology, Bitcoin offers the opportunity of a decentralized open financial system, where participants share the role of securing the network. This is important to give everyone equal and direct access to economic opportunities without fearing seizure or needing intermediaries. To make this a reality, we encourage everyone working on products to deliberately support the core principles of designing for Bitcoin. + +These are principles we in the Bitcoin Design Community identified and stand behind. Some of these come from the technology itself and others from the community's behavior and ethos. Although every use case and product is different, applications should strive to follow these principles. Diverging from them should only be done with very good reason. + + +- [Self-custody](#self-custody) +- [Security](#security) +- [Inclusion](#inclusion) +- [Interoperability](#interoperability) +- [Transparency](#transparency) +- [Privacy](#privacy) +- [Decentralization](#decentralization) + +--- + +## Self-custody + +> Let users control their private keys, with no risk for seizure or freezing of funds + +Our existing mental models of access to digital services are usernames and passwords controlled by a company with custody of your funds and data. With everyone having direct access to the Bitcoin network, we no longer need to design products that require people to delegate control of their funds to middlemen. While it comes with greater responsibility, self-custody enables the open financial system of peer-to-peer transactions. + +**Do** +- Let users control their bitcoin and private keys directly +- Create an easy path to self-custody for Bitcoin beginners + +**Don't** +- Custody funds for your users +- Build products where the users' funds can be seized, or frozen + +--- + +## Security + +> Provide appropriate and progressive security for all types of users + +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 new to Bitcoin. For example, new users are likely to start by only storing small amounts. After a while, however, they may get more comfortable with the idea of self-custody. The concept of progressive security is a good idea here, starting with automatic cloud backups. 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 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. + +Security can also be a feeling. A polished, good-looking, easy-to-use product that transparently communicates how it works can help users feel more secure– especially when compared to another product with the same security measures - but lacks these qualities. + + +**Do** +- Take safeguarding of users' funds seriously +- Strive for no loss of funds, whether by negligence or theft +- Provide suitable private key management schemes for beginners +- Offer progressive security and upgrade paths +- Build with bad actors in mind +- Minimize risk of self-inflicted loss from user negligence +- Continuously educate users on best practice and risks +- Reduce attack surfaces by minimizing use of external code dependencies + +**Don't** +- Blame the user for losing funds +- Expect beginners to implement best practice backup strategies +- Underestimate the added *feeling* of security that can come from well polished products + +--- + +## Inclusion + +> Build borderless products without location, language or social barriers + +There are no background checks, credit checks, or gatekeepers to Bitcoin. A Kenyan farmer has the same access to Bitcoin as a Wall Street trader. + +While Bitcoin is already used by a large number of people, it pales in comparison with the many more that are likely to use it in the future. We need to design products that are prepared for people unfamiliar with Bitcoin. This means using plain and familiar language, explaining things in the context where they are needed, not overwhelming people with technical detail, and more. + +**Do** +- Provide equal and direct access to the Bitcoin network +- Design Bitcoin products that are usable by the widest range of people possible +- Use plain language that people new to Bitcoin can understand regardless of prior knowledge +- Localize your product and make it multilingual +- Educate in place, when people are presented with a new concept +- Treat users who rely on assistive technologies as first-class citizens + +**Don't** +- Exclude people by building features that only work in certain countries +- Add technical detail that is not required knowledge, or technical terms like seed phrase, XPUBs, mnemonics etc. +- Put all education up front and expect people to read and remember it + +--- + +## Interoperability + +> Enable import and export of wallets, maximise backwards compatibility and use of open standards + +Bitcoin is an open-source protocol, operating in a decentralized manner. This has led to a number of standards being developed to ensure compatibility between products. It should be easy to switch and move your Bitcoin wallet to a different application, should you wish. Ensuring that your product supports as many of these standards as possible is best practice and builds trust. More on [wallet interoperability]({{ '/guide/foundations/wallet-interoperability/' | relative_url }}). + +**Do** +- Support import and export of wallets +- Support as many relevant BIPs as possible +- Be transparent with which ones you do and don’t support +- Maximize backwards compatibility + +**Don't** +- Lock your users in +- Implement proprietary solutions when open standards exist + +--- + +## Transparency + +> Be open and transparent with how your product works, open-source your code when possible + +While an open and decentralized financial system that users can connect with directly is great, it puts a burden on them to choose a product that they trust and like to use. We can make this easier by freely sharing information about how our products work and what technologies they use/rely on. By open-sourcing your code, you can let people verify that your claims are true, ultimately building more trust with your users. It is important to be transparent with users about the risks that come with self-custodying funds. Be sure to educate about scenarios where they may risk losing access to their funds along with best practices for avoiding this. + +**Do** +- Be open and transparent with how your product works +- Let people verify your claims by open-sourcing your code when possible +- Explain what risks the user is taking on, and how best to mitigate them + +**Don't** +- Make claims that are not explained or verifiable + +--- + +## Privacy + +> Minimize collection of personal information, and maximize financial transaction privacy + +A common misconception of Bitcoin is that it provides complete anonymity and privacy of transactions. Since the blockchain is an unchangeable ledger of all transactions ever made, it is very hard not to have your complete transaction history visible once even a single one of your addresses is connected to you. If Bitcoin is to become viable for a wider audience and daily use, we should take privacy seriously. This is certainly not to enable or encourage illicit activity but to protect individual financial privacy. We would not accept our bank to publish our financial transactions to our Twitter or Facebook feeds, so we should avoid that scenario with Bitcoin. + +The Bitcoin network doesn’t need to know your name for you to use it. Strive to collect as little personal information as possible about your users. When absolutely required to provide the product services, collect only the bare minimum and consider if and when this can be discarded when no longer necessary. If you collect personal information, be transparent about why and how you will use and store it. + +**Do** +- Minimize the personal information you collect +- Avoid address reuse +- Embrace privacy-preserving options when relevant (running a full node, compact block filters, Tor, Lightning Network, coin selection, schnorr signatures, payjoin, coinswap, etc.) + +**Don't** +- Collect and store personal information not required for the functionality of your product + +--- + +## Decentralization + +> Design products that encourage people to run a full Bitcoin node + +Unlike traditional banking systems, the Bitcoin economy does not require new users to seek permission from anyone. Bitcoin has no central point of control. No one person or entity is in charge. Connecting to any [node]({{ '/guide/glossary/#node' | relative_url }}) on the network gives you the same rights and responsibilities, ensuring no single point of failure. + +**Do** +- Design products that encourage people to run a full Bitcoin node +- Alternatively, use a light client with the [p2p network]({{ 'https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki'}}) using [compact block filters]({{ 'https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki'}}) +- Offer the user choice of what node and other external services to connect to + +**Don't** +- Introduce a single point of failure between the user and the Bitcoin network +- Build products that stop working if the project shuts down diff --git a/guide/onboarding/introduction.md b/guide/onboarding/introduction.md index 4ee8a63a9..262d549c1 100644 --- a/guide/onboarding/introduction.md +++ b/guide/onboarding/introduction.md @@ -42,12 +42,6 @@ Remember: Onboarding should not be a crutch for bad design. Avoid trying to expl --- -**Principles (coming soon)** - -Onboarding experiences can look very different depending on your target audience, however, some things should be consistent across Bitcoin products. - ---- - **Getting to know your users (coming soon)** This section will give you some tips on how best to understand and develop knowledge about your users. diff --git a/guide/private-key-management/introduction.md b/guide/private-key-management/introduction.md index eb92682dc..8291ba7c1 100644 --- a/guide/private-key-management/introduction.md +++ b/guide/private-key-management/introduction.md @@ -43,11 +43,17 @@ This chapter is meant to give an overview of private key management schemes, inc An overview of the most common private key management schemes for bitcoin products, and thoughts on picking a suitable scheme for your target audience and their use case. ---- +**[Personal schemes]({{ '/guide/private-key-management/single-user-schemes/' | relative_url }})** + +The schemes that are most common for the personal use of one individual. + +**[Shared schemes]({{ '/guide/private-key-management/single-user-schemes/' | relative_url }})** + +When more than one person wants to share a Bitcoin wallet, multi-key schemes become essential. -**[Principles]({{ '/guide/private-key-management/principles/' | relative_url }})** +**[Case studies]({{ '/guide/private-key-management/case-studies/' | relative_url }})** -Every use case and product is different but there are things that all wallet applications should strive for, and only diverge from with very good reasons. +A look at some hypothetical use case categories and what might be suitable approaches for private key management schemes for each of them. --- diff --git a/guide/private-key-management/multi-user-schemes.md b/guide/private-key-management/multi-user-schemes.md index 6a6f5842f..3e44d0d4b 100644 --- a/guide/private-key-management/multi-user-schemes.md +++ b/guide/private-key-management/multi-user-schemes.md @@ -87,4 +87,4 @@ Few tailor-made products exist for shared wallets, but any wallet application th --- -Next up, common [principles]({{ '/guide/private-key-management/principles/' | relative_url }}) we should strive to follow. \ No newline at end of file +OK, let's have a look at some [case studies]({{ '/guide/private-key-management/case-studies/' | relative_url }}). \ No newline at end of file diff --git a/guide/private-key-management/principles.md b/guide/private-key-management/principles.md deleted file mode 100644 index b12f9750d..000000000 --- a/guide/private-key-management/principles.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -layout: guide -title: Principles -description: Principles to strive for while building bitcoin applications for end-users. -nav_order: 4 -parent: Private key management -permalink: /guide/private-key-management/principles/ -main_classes: -no-top-padding -image: /assets/images/guide/private-key-management/principles/page-principles.jpg ---- - - - -{% include picture.html - image = "/assets/images/guide/private-key-management/principles.jpg" - retina = "/assets/images/guide/private-key-management/principles@2x.jpg" - mobile = "/assets/images/guide/private-key-management/principles-mobile.jpg" - mobileRetina = "/assets/images/guide/private-key-management/principles-mobile@2x.jpg" - alt-text = "Principles header illustration" - width = 1600 - height = 600 - layout = "full-width" -%} - -# Principles - -Although every use case and product is different, there are a number of things that all wallet applications should strive for. Diverging from them should only be done with good reason. - -## No loss of funds - -Even though non-custodial wallet-makers don’t technically hold their users’ funds, and are less exposed to regulation, you are still providing a financial service product. It is essential to take the safekeeping of users’ funds seriously. Regardless of how loss could occur, whether it is self-inflicted or through theft, you should have thought this through and implemented adequate measures for the risk-profile of the use-case. This includes not simply blaming a first-time bitcoin user for not manually backing up their recovery phase when you told them to. - -Any loss is ultimately bad for both the user, the wallet application maker and the whole bitcoin community. Strive for *No loss of funds*. - -## Interoperability - -The bitcoin community is firmly built on open-source, decentralization, and the idea that the individual should be in full control of their funds. This has led to a number of standards that should make it fairly easy to switch and move your bitcoin wallet to a different wallet application. Making sure that your product supports these standards when relevant is best practice and builds trust. - -At a minimum, strive for supporting interoperability by enabling import and export, and using standard [address]({{ '/guide/glossary/#address' | relative_url }}){:target="_blank"} derivation schemes. - -## Privacy - -A common misconception of bitcoin is that it provides anonymity and privacy of transactions. Since the blockchain is literally an unchangeable ledger of all bitcoin transactions ever made, it is in fact very hard to not have your complete transaction history visible to knowledgable parties once even a single one of your addresses is connected to you. If bitcoin is to become viable for a wider audience and daily use we ought to take privacy seriously. This is certainly not to enable or encourage illicit activity, but to protect individual financial privacy. We would not accept our bank to publish our financial transactions publicly. So when building wallet-applications we should strive to implement best practice for maintaining and improving the financial privacy of bitcoin. - -At a minimum, make it easy for your customers to avoid address re-use. - -## Progressive security - -While it is possible to own and store immense wealth in a non-custodial bitcoin wallet, most new users of bitcoin are likely to start with much smaller sums before they get comfortable with depositing material parts of their savings in a wallet where they are responsible for security. There are many guides out there for how to best keep your recovery phrase backup safe, and conduct advanced op-sec to minimise every conceivable threat-vector. This might be appropriate for someone already intimately familiar with bitcoin technology, but is very likely both overkill and scary to the point of turning away new users. Think carefully about who your target customer is and choose a private key management scheme that is well suited to them. - -Strive for your product to grow with the user and provide progressively stronger security. For example, offering the ability to *sweep* a wallet into a new one, with a higher level security scheme once certain thresholds are reached. This way, a beginner could start out with an automatic cloud backup scheme but know that as they grow their funds could upgrade to a multikey setup down the line. - -*** - -OK, let's have a look at some [case studies]({{ '/guide/case-studies/' | relative_url }}).