diff --git a/_compress_images_cache.yml b/_compress_images_cache.yml index 4033da5a8..e44af77c7 100644 --- a/_compress_images_cache.yml +++ b/_compress_images_cache.yml @@ -373,3 +373,25 @@ assets/images/guide/getting-started/hardware/atm@2x.jpg: atm@2x.jpg assets/images/guide/getting-started/hardware/atm.jpg: atm.jpg assets/images/guide/getting-started/hardware/atm-mobile.jpg: atm-mobile.jpg assets/images/guide/getting-started/hardware/atm-mobile@2x.jpg: atm-mobile@2x.jpg +assets/images/guide/foundations/wallet-interoperability/qr-code.jpg: qr-code.jpg +assets/images/guide/foundations/wallet-interoperability/qr-code@2x.jpg: qr-code@2x.jpg +assets/images/guide/foundations/wallet-interoperability/multi-signature@2x.jpg: multi-signature@2x.jpg +assets/images/guide/foundations/wallet-interoperability/transaction-file.jpg: transaction-file.jpg +assets/images/guide/foundations/wallet-interoperability/payment-links@2x.jpg: payment-links@2x.jpg +assets/images/guide/foundations/wallet-interoperability/payment-links.jpg: payment-links.jpg +assets/images/guide/foundations/wallet-interoperability/user-data-import-export.jpg: user-data-import-export.jpg +assets/images/guide/foundations/wallet-interoperability/transaction-file@2x.jpg: transaction-file@2x.jpg +assets/images/guide/foundations/wallet-interoperability/key-import-export.jpg: key-import-export.jpg +assets/images/guide/foundations/wallet-interoperability/user-data-import-export@2x.jpg: user-data-import-export@2x.jpg +assets/images/guide/foundations/wallet-interoperability/key-import-export@2x.jpg: key-import-export@2x.jpg +assets/images/guide/foundations/wallet-interoperability/node-options@2x.jpg: node-options@2x.jpg +assets/images/guide/foundations/wallet-interoperability/multi-signature.jpg: multi-signature.jpg +assets/images/guide/foundations/wallet-interoperability/node-options.jpg: node-options.jpg +assets/images/guide/foundations/wallet-interoperability/integrations@2x.jpg: integrations@2x.jpg +assets/images/guide/foundations/wallet-interoperability/integrations.jpg: integrations.jpg +assets/images/guide/foundations/wallet-interoperability/wallet-interoperability@2x.jpg: wallet-interoperability@2x.jpg +assets/images/guide/foundations/wallet-interoperability/wallet-interoperability.jpg: wallet-interoperability.jpg +assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile.jpg: wallet-interoperability-mobile.jpg +assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile@2x.jpg: wallet-interoperability-mobile@2x.jpg +assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-preview.jpg: wallet-interoperability-preview.jpg +assets/images/guide/foundations/foundations-preview.jpg: foundations-preview.jpg diff --git a/assets/images/guide/foundations/foundations-preview.jpg b/assets/images/guide/foundations/foundations-preview.jpg new file mode 100644 index 000000000..d3ff53a3a Binary files /dev/null and b/assets/images/guide/foundations/foundations-preview.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/integrations.jpg b/assets/images/guide/foundations/wallet-interoperability/integrations.jpg new file mode 100644 index 000000000..bc3eb7e43 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/integrations.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/integrations@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/integrations@2x.jpg new file mode 100644 index 000000000..997989b1c Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/integrations@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/key-import-export.jpg b/assets/images/guide/foundations/wallet-interoperability/key-import-export.jpg new file mode 100644 index 000000000..fce797752 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/key-import-export.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/key-import-export@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/key-import-export@2x.jpg new file mode 100644 index 000000000..b33f943dd Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/key-import-export@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/multi-signature.jpg b/assets/images/guide/foundations/wallet-interoperability/multi-signature.jpg new file mode 100644 index 000000000..5c2217e56 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/multi-signature.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/multi-signature@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/multi-signature@2x.jpg new file mode 100644 index 000000000..ece59022d Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/multi-signature@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/node-options.jpg b/assets/images/guide/foundations/wallet-interoperability/node-options.jpg new file mode 100644 index 000000000..3fcf17179 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/node-options.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/node-options@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/node-options@2x.jpg new file mode 100644 index 000000000..ea76d86d4 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/node-options@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/payment-links.jpg b/assets/images/guide/foundations/wallet-interoperability/payment-links.jpg new file mode 100644 index 000000000..29683d75a Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/payment-links.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/payment-links@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/payment-links@2x.jpg new file mode 100644 index 000000000..5d0533bfb Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/payment-links@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/qr-code.jpg b/assets/images/guide/foundations/wallet-interoperability/qr-code.jpg new file mode 100644 index 000000000..8ae61098c Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/qr-code.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/qr-code@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/qr-code@2x.jpg new file mode 100644 index 000000000..c1c837769 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/qr-code@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/transaction-file.jpg b/assets/images/guide/foundations/wallet-interoperability/transaction-file.jpg new file mode 100644 index 000000000..44ec2c413 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/transaction-file.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/transaction-file@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/transaction-file@2x.jpg new file mode 100644 index 000000000..f231e0904 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/transaction-file@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/user-data-import-export.jpg b/assets/images/guide/foundations/wallet-interoperability/user-data-import-export.jpg new file mode 100644 index 000000000..70f5a3a65 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/user-data-import-export.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/user-data-import-export@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/user-data-import-export@2x.jpg new file mode 100644 index 000000000..53d563c87 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/user-data-import-export@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile.jpg b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile.jpg new file mode 100644 index 000000000..ce777d9e6 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile@2x.jpg new file mode 100644 index 000000000..71eb569f5 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile@2x.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-preview.jpg b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-preview.jpg new file mode 100644 index 000000000..4a854fa07 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-preview.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability.jpg b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability.jpg new file mode 100644 index 000000000..908777f0d Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability.jpg differ diff --git a/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability@2x.jpg b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability@2x.jpg new file mode 100644 index 000000000..ebb770a01 Binary files /dev/null and b/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability@2x.jpg differ diff --git a/guide/foundations/foundations.md b/guide/foundations/foundations.md new file mode 100644 index 000000000..50da29612 --- /dev/null +++ b/guide/foundations/foundations.md @@ -0,0 +1,19 @@ +--- +layout: guide +title: Foundations +description: Basics for designing great Bitcoin products. +nav_order: 5 +has_children: true +permalink: /guide/foundations/ +image: /assets/images/guide/foundations/foundations-preview.jpg +--- + +# Foundations + +Learn about some of the basic principles to keep in mind when designing Bitcoin applications. + +--- + +**[Wallet interoperability]({{ '/guide/foundations/wallet-interoperability/' | relative_url }})** + +An overview of important interaction points between Bitcoin applications and user experiences, from payment links and wallet recovery to node configuration. \ No newline at end of file diff --git a/guide/foundations/wallet-interoperability.md b/guide/foundations/wallet-interoperability.md new file mode 100644 index 000000000..0fc51d451 --- /dev/null +++ b/guide/foundations/wallet-interoperability.md @@ -0,0 +1,198 @@ +--- +layout: guide +title: Wallet interoperability +description: Designing for seamless experiences across Bitcoin applications. +nav_order: 10 +parent: Foundations +permalink: /guide/foundations/wallet-interoperability/ +main_classes: -no-top-padding +image: /assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-preview.jpg +--- + + + +{% include picture.html + image = "/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability@2x.jpg" + mobile = "/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile.jpg" + mobileRetina = "/assets/images/guide/foundations/wallet-interoperability/wallet-interoperability-mobile@2x.jpg" + alt-text = "Several devices exchanging data" + width = 1600 + height = 700 + layout = "full-width" +%} + +# Wallet interoperability + +Diverse applications with different philosophies, feature sets and approaches are fantastic for Bitcoin. It allows many different users around the world to choose the applications that best fit their needs. For this to be practical, a minimum of interoperability should be worked towards, for smoother interactions with fewer mistakes. + +Here are some common scenarios: +- Using different wallets for desktop and mobile +- Paying someone who uses different software +- Migrating to a different device, operating system or application +- Multi-signature wallets that require multiple devices and applications to exchange data +- Using your own [node]({{ 'guide/getting-started/software/#nodes' | relative_url }}) + +Each of these requires that applications are designed and developed to be open, ideally relying on standardized formats. + +So here are some ways to allow users to more seamlessly navigate different software configurations. + +## Wallet import and export + +
+ +{% include image.html + image = "/assets/images/guide/foundations/wallet-interoperability/key-import-export.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/key-import-export@2x.jpg" + alt-text = "Transfer of wallet data between applications" + width = 400 + height = 300 + layout = "float-right-desktop" +%} + +Allow for wallets generated in one application to be easily restored in another application. Over the years, Bitcoin applications have implemented various technical details in different ways, partly because standards take time to evolve. See [Wallets Recovery](https://walletsrecovery.org) as an illustration of the problem. + +To prevent issues, wallets should make it convenient for users to back up all relevant information they may need for recovery with other applications. One solution is, for example, to provide a downloadable PDF with the wallet name, software name and version, address type, derivation paths, and other non-standard information. + +
+ +## Payment links + +
+ +{% include image.html + image = "/assets/images/guide/foundations/wallet-interoperability/payment-links.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/payment-links@2x.jpg" + alt-text = "Click a link to launch Bitcoin software" + width = 400 + height = 300 + layout = "float-right-desktop" +%} + +Avoid copying & pasting payment data by providing clickable links with the right information embedded. Bitcoin applications can respond to such link clicks by automatically navigating to the payment screen and prefilling the provided form fields. Payment links as defined in [BIP 21](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) can contain contain address, amount, label and other details. + +Example link: +``` +bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz +``` + +
+ +## QR codes + +
+ +{% include image.html + image = "/assets/images/guide/foundations/wallet-interoperability/qr-code.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/qr-code@2x.jpg" + alt-text = "A smartphone camera scanning a QR code" + width = 400 + height = 400 + layout = "float-right-desktop" +%} + +QR codes are visual representations of data. Since most devices today feature cameras with built-in support for reading QR codes, this technique has become a convenient method to transfer data from one device to another, even if those devices are offline. Common use cases include reading payment invoices (such as the payment links described above), or importing wallet keys from a backup. + +Static QR codes can only contain small amounts of information. Animated QR codes address this problem by splitting up the data over multiple static QR codes. Reading animated QR codes is not a standard feature yet. + +Although QR codes are a well-established and standardized format, there are details to consider. It is, for example, [more efficient](https://bitcoinops.org/en/bech32-sending-support/#creating-more-efficient-qr-codes-with-bech32-addresses) to encode uppercase characters, resulting in simpler QR codes that are easier to scan. So it is recommended to uppercase data that is not case sensitive. However, [not all wallets](https://github.com/btcpayserver/btcpayserver/issues/2110) can properly interpret this capitalized data, which can cause issues for users. + +
+ +## User data import and export + +
+ +{% include image.html + image = "/assets/images/guide/foundations/wallet-interoperability/user-data-import-export.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/user-data-import-export@2x.jpg" + alt-text = "Transfer of user data between applications" + width = 400 + height = 300 + layout = "float-right-desktop" +%} + +Transaction data is stored on the Bitcoin block chain and available in any wallet a user has set up. As is, this transaction data does not contain any useful information about the reasons why transactions were made, who owns each address, etc. To better understand and organize their finances, users typically enrich transaction data by assigning contacts, notes, labels, and other useful information. This data should be stored in standardized, open formats and easily synced between applications. This is especially useful for users who rely on multiple devices. + +
+ +## Transaction files + +
+ +{% include image.html + image = "/assets/images/guide/foundations/wallet-interoperability/transaction-file.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/transaction-file@2x.jpg" + alt-text = "Transfer of transaction files between applications" + width = 400 + height = 300 + layout = "float-right-desktop" +%} + +Also known as the [Partially Signed Bitcoin Transaction Format](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki), this type of file allows for storage and transfer of transactions that are not finalized. Common use cases are in multi signature wallets where one application prepares a transaction and sends it to another wallet for an additional signature. It also allows signing wallets to be offline, as the transaction data can be transferred via USB drives or animated QR codes. + +
+ +## Multi signature wallets + +
+ +{% include image.html + image = "/assets/images/guide/foundations/wallet-interoperability/multi-signature.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/multi-signature@2x.jpg" + alt-text = "Cosigner wallets interacting with a multi signature wallet" + width = 400 + height = 300 + layout = "float-right-desktop" +%} + +Per definition, multi signature wallets require interaction between all cosigners and therefore interoperability between their software (or hardware) of choice. Especially when there are multiple cosigners (rather than one owner using multiple signing devices), there should be strong design considerations to how the cosigners exchange keystores and transaction data. + +
+ +## Self-hosted nodes + +
+ +{% include image.html + image = "/assets/images/guide/foundations/wallet-interoperability/node-options.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/node-options@2x.jpg" + alt-text = "Node options" + width = 400 + height = 300 + layout = "float-right-desktop" +%} + +While it is extremely convenient when applications provide their own node connections, it is recommended to allow users to have a choice, and potentially even encourage them to set up their own node. This results in better decentralization, and also has privacy and security benefits. + +
+ +## Integrations + +
+ +{% include image.html + image = "/assets/images/guide/foundations/wallet-interoperability/integrations.jpg" + retina = "/assets/images/guide/foundations/wallet-interoperability/integrations@2x.jpg" + alt-text = "Application reliance on external data and services" + width = 400 + height = 300 + layout = "float-right-desktop" +%} + +Most Bitcoin applications rely on external data sources (like currency conversion data) and may also have integrations with third parties (like linking to an external [block explorer]({{ 'guide/getting-started/software/#block-explorers' | relative_url }})). Whenever possible, it should be easy for users to learn about these dependencies and choose alternatives. + +
diff --git a/guide/glossary.md b/guide/glossary.md index e3e49c515..a80cbd2ae 100644 --- a/guide/glossary.md +++ b/guide/glossary.md @@ -2,7 +2,7 @@ layout: guide title: Glossary permalink: /guide/glossary/ -nav_order: 4 +nav_order: 6 --- # Glossary