Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
27e003a
docs(payments/receive): import content
johnsBeharry Apr 19, 2021
0c443ba
docs(payments/receive): fix permalink
johnsBeharry Apr 19, 2021
1b0ad42
style(payments/receive): add image gallery to entering payment details
johnsBeharry Apr 19, 2021
030ff06
style(payments/receive): change background colour of images
johnsBeharry Apr 19, 2021
143c7cc
merge: branch 'feature/fix-image-slide-gallery-long-text' into featur…
johnsBeharry Apr 19, 2021
dc1a1fb
style(payments/receive): update images from @gbks
johnsBeharry Apr 20, 2021
87f41f9
docs(payments/receive): refine content and embed galleries
johnsBeharry Apr 21, 2021
4d3309c
merge: branch 'feature/css-image-drop-shadow-fix' into feature/receive
johnsBeharry Apr 21, 2021
a3e4f4a
docs(payments/receive): reword sharing/text
johnsBeharry Apr 22, 2021
45240fb
docs(payments/receive): improve intro
johnsBeharry Apr 28, 2021
e847c16
docs(payments): make links relative + add references
johnsBeharry Apr 29, 2021
5d56807
docs(payments/receive): restructure creating invoice -> requesitng bi…
johnsBeharry Apr 30, 2021
3101055
docs(payments/receive): add tip for address compatibltiy to requesting
johnsBeharry Apr 30, 2021
02fe1da
docs(payments/receive): change waiting title
johnsBeharry Apr 30, 2021
3304e32
docs(payments/receive): combine request and payment details
johnsBeharry Apr 30, 2021
d08914d
docs(payments/receive): update with feedback
johnsBeharry May 10, 2021
c112798
fix(payments/receive): resolve spelling and spacing issues
johnsBeharry May 10, 2021
84b007d
merge: branch 'master' into feature/receive
johnsBeharry May 10, 2021
8907c4e
fix(payments/receive): make links relative and fix grammer
johnsBeharry May 10, 2021
7a931d9
docs(payments/receive): move address content back to glossary
johnsBeharry May 10, 2021
27e4f87
merge: branch 'master' into feature/receive
johnsBeharry May 10, 2021
10f18f8
docs(payment/receive): update with feedback from @barefoot-88
johnsBeharry May 12, 2021
ef03cdc
docs(payments/receive): update with feedback
johnsBeharry May 13, 2021
aae4ed6
docs(glossary): reset address content
johnsBeharry May 13, 2021
d802be1
chore: update image compress cache
johnsBeharry May 13, 2021
93c579d
merge: branch 'master' into feature/receive
johnsBeharry May 13, 2021
8df761e
Update guide/payments/send.md
pavlenex May 14, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions _compress_images_cache.yml
Original file line number Diff line number Diff line change
Expand Up @@ -714,3 +714,31 @@ assets/images/guide/private-key-management/backups/paperbackup.jpg: paperbackup.
assets/images/guide/private-key-management/backups/multiple-discoveryprotection.jpg: multiple-discoveryprotection.jpg
assets/images/guide/private-key-management/backups/cloud-backup.jpg: cloud-backup.jpg
assets/images/guide/private-key-management/backups/multiple-discoveryprotection@2x.jpg: multiple-discoveryprotection@2x.jpg
assets/images/guide/payments/receive/address-info.png: address-info.png
assets/images/guide/payments/receive/address-info@2x.png: address-info@2x.png
assets/images/guide/payments/receive/address-switch.png: address-switch.png
assets/images/guide/payments/receive/address-switch@2x.png: address-switch@2x.png
assets/images/guide/payments/receive/enter-details-amount.png: enter-details-amount.png
assets/images/guide/payments/receive/enter-details-amount@2x.png: enter-details-amount@2x.png
assets/images/guide/payments/receive/enter-details-compact.png: enter-details-compact.png
assets/images/guide/payments/receive/enter-details-compact@2x.png: enter-details-compact@2x.png
assets/images/guide/payments/receive/enter-details-from.png: enter-details-from.png
assets/images/guide/payments/receive/enter-details-from@2x.png: enter-details-from@2x.png
assets/images/guide/payments/receive/enter-details-purpose.png: enter-details-purpose.png
assets/images/guide/payments/receive/enter-details-purpose@2x.png: enter-details-purpose@2x.png
assets/images/guide/payments/receive/receive-pending-details.png: receive-pending-details.png
assets/images/guide/payments/receive/receive-pending-details@2x.png: receive-pending-details@2x.png
assets/images/guide/payments/receive/receive-with-pending.png: receive-with-pending.png
assets/images/guide/payments/receive/receive-with-pending@2x.png: receive-with-pending@2x.png
assets/images/guide/payments/receive/share-sharesheet.png: share-sharesheet.png
assets/images/guide/payments/receive/share-sharesheet@2x.png: share-sharesheet@2x.png
assets/images/guide/payments/receive/share.png: share.png
assets/images/guide/payments/receive/share@2x.png: share@2x.png
assets/images/guide/payments/receive/simple-share-address-settings.png: simple-share-address-settings.png
assets/images/guide/payments/receive/simple-share-address-settings@2x.png: simple-share-address-settings@2x.png
assets/images/guide/payments/receive/simple-share.png: simple-share.png
assets/images/guide/payments/receive/simple-share@2x.png: simple-share@2x.png
assets/images/guide/payments/receive/transactions-no-label-context.png: transactions-no-label-context.png
assets/images/guide/payments/receive/transactions-no-label-context@2x.png: transactions-no-label-context@2x.png
assets/images/guide/payments/receive/transactions-with-label-context.png: transactions-with-label-context.png
assets/images/guide/payments/receive/transactions-with-label-context@2x.png: transactions-with-label-context@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/images/guide/payments/receive/share.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/images/guide/payments/receive/share@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
37 changes: 33 additions & 4 deletions guide/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,12 @@ https://www.figma.com/file/qzvCvqhSRx3Jq8aywaSjlr/Bitcoin-Design-Guide-Illustrat
---

### Address

An identifier of 26-35 alphanumeric characters that is used to receive bitcoin. There are [several address formats](https://en.bitcoin.it/wiki/List_of_address_prefixes) based on different specifications. Users need to know this information during backup for future recovery so applications should inform users which format it uses as support varies across applications.
A Bitcoin address is an identifier of 26-35 alphanumeric characters that is used to receive bitcoin. There are [several address formats](https://en.bitcoin.it/wiki/List_of_address_prefixes) based on different specifications. Users need to know this information during backup for future recovery so applications should inform users which format it uses as support varies across applications.

When users enter an address, these formats have specific prefixes so it is possible to instantly determine which format is being used.

These are the three most common ones:


**Legacy address - [P2PKH](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash)**<br/>
Stands for pay-to-pubkey-hash, i.e pay to a hash of the recipient’s public key. This was the original address format for bitcoin and is often called *legacy address*.

Expand All @@ -71,6 +69,35 @@ For example: `bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq`
**Change address**<br/>
When the output of a transaction is used as the input of another transaction, it must be spent in its entirety. Sometimes the value of the output is higher than what the user wishes to pay. In this case, the bitcoin client generates a new Bitcoin address, and sends the difference back to this address. This is known as *change address*.

##### Address compatibility
Since "legacy" addresses are still in use[^1], and some older applications have yet to upgrade. Script addresses can be used to resolve incompatibility issues that can arise when the sender's application does not recognize the SegWit address provided by the receiver.

To illustrate the problem, suppose the sender is using a legacy wallet and paying to the receiver's SegWit address. In this case, the sender's wallet may incorrectly warn them that the address is invalid or not supported. This can confuse the sender’s end, leading them to think that the receiver provided an incorrect address.

The receiver should then have the ability to switch to a Script address that does not have all the benefits of SegWit, like cheaper transactions but will be compatible with the sender's wallet.

<div class="image-slide-gallery">

{% include picture.html
image = "/assets/images/guide/payments/receive/address-switch.png"
retina = "/assets/images/guide/payments/receive/address-switch@2x.png"
alt-text = "Screen with modal of invoice details, and address switcher"
caption = "Allow the receiver to switch to a legacy compatible address"
width = 250
height = 541
%}

{% include picture.html
image = "/assets/images/guide/payments/receive/address-info.png"
retina = "/assets/images/guide/payments/receive/address-info@2x.png"
alt-text = "Screen explaining SegWit and Legacy addresses"
caption = "Provide information about the different address types"
width = 250
height = 541
%}

</div>

### Account

Just like wallet, the term account can also be used for very different things. In bitcoin wallets that follow the hierarchy described in [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki), a bitcoin wallet can have multiple accounts, with each one having its own addresses. However, account is also oftentimes used for accounts with third-party service providers.
Expand Down Expand Up @@ -376,4 +403,6 @@ With a custodial wallet-application, the users are not exposed to and in charge
- [Bitcoin Q + A glossary](https://www.bitcoinqna.com/glossary)
- [Bitcoin Wiki](https://en.bitcoin.it/wiki/Main_Page)
- [Bitcoin Optech style guide](https://github.com/bitcoinops/bitcoinops.github.io/blob/master/STYLE.md)
- [Bitcoin Optech topics](https://bitcoinops.org/en/topics/)
- [Bitcoin Optech topics](https://bitcoinops.org/en/topics/)

[^1]: [SegWit Usage Trends](https://dashboard.bitcoinops.org/d/xVQwtADiz/segwit-usage-trends?refresh=1h&orgId=1)
8 changes: 4 additions & 4 deletions guide/payments/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,23 +23,23 @@ At its core, the Bitcoin protocol enables transactions between people without in

This chapter is meant to give an overview of bitcoin transactions, including sending, receiving, and transaction privacy, with advice and best practices. After this chapter, you should be able to design payment solutions that are well suited to your product's use case and understand best-practices for its implementation.

We have already established that [Bitcoin is money](https://bitcoin.design/guide/getting-started/why-bitcoin-is-unique/#its-money-but-digital), so let's dive into how it can be used to facilitate payments.
We have already established that [Bitcoin is money]({{ '/guide/getting-started/why-bitcoin-is-unique/#its-money-but-digital' | relative_url }}), so let's dive into how it can be used to facilitate payments.

---

### [Transactions overview](/guide/payments/transactions/)
### [Transactions overview]({{ '/guide/payments/transactions/' | relative_url }})

An overview of Bitcoin payments, common concepts and the transaction lifecycle.

---

### [Sending bitcoin](/guide/payments/send/)
### [Sending bitcoin]({{ '/guide/payments/send/' | relative_url }})

An introduction to how sending bitcoin works.

---

### Receiving bitcoin (coming soon)
### [Receiving bitcoin]({{ '/guide/payments/receive/' | relative_url }})

An introduction to how receiving and requesting bitcoin works.

Expand Down
230 changes: 230 additions & 0 deletions guide/payments/receive.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,230 @@
---
layout: guide
title: Receiving bitcoin
description: An introduction to how receiving bitcoin works.
nav_order: 3
parent: Payments
permalink: /guide/payments/receive/
main_classes: -no-top-padding
# image: /assets/images/guide/payments/receive/header.svg
---

# Receiving bitcoin

<!--

Editor's notes

This page should cover what to do when receiving bitcoin, how to share and copy addresses etc.

- What addresses to support (native segwit by default)
- How to present QR codes (allow for specifying an amount)
- Generating a new address

-->

For someone to receive bitcoin, they must provide the sender with a payment destination. They can do this by generating an address in their Bitcoin wallet application. A new address should be generated for every payment, as addresses should only be used once. This helps safeguards the receiver’s privacy.

<!--
Update glossary

Each address that a Bitcoin application generates has an accompaniying private key. This private key allows the receiver to unlock the bitcoin that is sent to the address when the receiver chooses to spend it.

Although addresses are not a problem to share publically, their accompanying private keys which typically generated from a single recovery phrase must be kept secure and private.
-->

## Requesting bitcoin
The simplest way to receive bitcoin is by generating and sharing a Bitcoin address with the sender. Receivers can share the address by either as a scannable QR code, or as plain text via any regular communication tool like email, instant messaging, SMS, etc.

<div markdown="1">

{% include picture.html
image = "/assets/images/guide/payments/receive/simple-share.png"
retina = "/assets/images/guide/payments/receive/simple-share@2x.png"
alt-text = "Screen showing how receiver is able to share a bitcoin address as soon as they enter the request flow"
width = 250
height = 541
layout = "background -shadow"
%}

</div>

{% include tip/tip.html %}
There are several types of addresses. Sharing one that is incompatible with the sender's wallet application can prevent a successful payment. Read more about [address compatibility]({{ '/guide/glossary/#address-compatibility' | relative_url }}) issues in the glossary.
{% include tip/close.html %}

## Inputting additional payment details

Many Bitcoin wallet applications provide only this most basic interface with an address for requesting payments. This is convenient in the short-term as it is fast and simple, but may not be in the user’s best interest longer-term. Lists of transactions without information about who they are from and their purpose make it hard to manage personal finances and future transaction privacy.

<div class="image-slide-gallery">

{% include picture.html
image = "/assets/images/guide/payments/receive/transactions-no-label-context.png"
retina = "/assets/images/guide/payments/receive/transactions-no-label-context@2x.png"
alt-text = "Screen showing a list of transactions with no context just amounts and transaction IDs"
caption = "When no additional information is gathered from the receiver, only what is stored on the blockchain can be shown."
width = 250
height = 541
layout = "shadow"
%}

{% include picture.html
image = "/assets/images/guide/payments/receive/transactions-with-label-context.png"
retina = "/assets/images/guide/payments/receive/transactions-with-label-context@2x.png"
alt-text = "Screen showing a list of transactions with details about the payment"
caption = "While more information can be helpful it requires manual input. Ask which are priorities, and how can you make their entry easier?"
width = 250
height = 541
layout = "shadow"
%}

</div>

Since the Bitcoin blockchain only stores a limited amount of information, such as the amount and addresses involved, any additional information must be stored in your application. This additional information can be vital in providing context to wallet owners on their spending habits and payment histories. These details have to be manually added. It is possible for receivers to share some of these extra details with senders by encoding them in [payment links]({{ '/guide/foundations/wallet-interoperability/' | relative_url }}).

The following are the standard properties of a payment link:

- **Address** – The destination of the payment
- **Amount** – How much is being requested (optional)
- **Label** – For example, the name of who is sending the payment (optional)
- **Message** – For example, the purpose of payment (optional)

Not all applications support storing additional information, or sharing payment links with these details. When providing this functionality, find the right balance between convenience and usefulness for your target audience. Consider ways that can make the input of these details easy, not burdensome.

<div class="image-slide-gallery">
Comment thread
johnsBeharry marked this conversation as resolved.
Resolved

{% include picture.html
image = "/assets/images/guide/payments/receive/enter-details-amount.png"
retina = "/assets/images/guide/payments/receive/enter-details-amount@2x.png"
alt-text = "Screen asking the receiver to enter the amount being requested"
caption = "The receiver can specify the amount that they are requesting. This could be shared in payment links which would auto-fill the amount for the sender."
width = 250
height = 541
layout = "shadow"
%}

{% include picture.html
image = "/assets/images/guide/payments/receive/enter-details-from.png"
retina = "/assets/images/guide/payments/receive/enter-details-from@2x.png"
alt-text = "Screen asking the receiver to enter the name of the sender"
caption = "The receiver can use a label to specify who the payment is from. This can be stored and used in suggestions when making future payment requests."
width = 250
height = 541
layout = "shadow"
%}

{% include picture.html
image = "/assets/images/guide/payments/receive/enter-details-purpose.png"
retina = "/assets/images/guide/payments/receive/enter-details-purpose@2x.png"
alt-text = "Screen asking the receiver to enter the purpose of the payment"
caption = "Sometimes the purpose can be determined by identifying who the payment is from. Be mindful of that, and consider easy ways to help the receiver add more context."
width = 250
height = 541
layout = "shadow"
%}

</div>

<!--
Technical nitpick;
Addresses are not exactly "generated"
since they are deterministic technically
what happens is an unused address just gets chosen
-->

<!--
Update interopability page
Since there are many Bitcoin applications for people to choose from, its likely that the sender and receiver are not using the same one and they don't have the abilitiy to exchange payment details within the application itself.

The exchange of payment details then most commonly happens outside of the wallet application. This

Since bitcoin is a open system and has many payment applications built ontop of it, there is a [standard format]({{ '/guide/foundations/wallet-interoperability/#payment-links' | relative_url }}) of "payment links" that most bitcoin applications use to share payment details.
-->

## Sharing the payment request

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Sharing the payment request
## Sharing the request

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also with this one, i think its just clear to have the payment part in here. the payment request concept is something that will be in other places in this chapter I expect so might as well readers familiar with it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You decide. I think it's pretty clear from the page context that it's about payments but up to you.

Whether it’s just an address, or a payment link containing additional information, the two primary methods of sharing requests are via QR codes or as plain text.

<div class="image-slide-gallery">

{% include picture.html
image = "/assets/images/guide/payments/receive/share.png"
retina = "/assets/images/guide/payments/receive/share@2x.png"
alt-text = "Screen showing the invoice with a share button"
caption = ""
width = 250
height = 541
layout = "shadow"
%}

{% include picture.html
image = "/assets/images/guide/payments/receive/share-sharesheet.png"
retina = "/assets/images/guide/payments/receive/share-sharesheet@2x.png"
alt-text = "Screen showing the invoice overlayed with a share sheet"
caption = ""
width = 250
height = 541
layout = "shadow"
%}

</div>


**Text**

Sharing a request as text is as straightforward as copying and pasting. It is also typical for Bitcoin applications to provide the receiver with a “share” button - allowing them to conveniently share addresses or payment links via other applications, with “share sheets” being offered by most mobile operating systems.

**QR codes**

QR codes are commonly used when the sender and receiver are near one another. It is not without its faults though, as some people may not be familiar with QR Codes, and lower-end phones may have difficulty reading them.

Here are some constraints to consider when displaying QR codes:

- Complex QR codes can be difficult for devices with low-resolution cameras to read.
- Use high contrast between the QR code blocks and their background.
- Display the QR code at the largest size so that the scanner can detect it easily.

_For more technical details about optimizing QR codes, [see this article](https://bitcoinops.org/en/bech32-sending-support/#creating-more-efficient-qr-codes-with-bech32-addresses)._

## Awaiting the payment
Once the request has been shared, the sender still has to create and broadcast their transaction, leaving room for uncertainty as to when the payment will be completed and received. Think about how to keep the receiver informed whilst they await their payment.

<div class="image-slide-gallery">

{% include picture.html
image = "/assets/images/guide/payments/receive/receive-with-pending.png"
retina = "/assets/images/guide/payments/receive/receive-with-pending@2x.png"
alt-text = "Screen showing a list of incoming payments"
caption = "By labeling addresses and storing them, you will be able to indicate the state of incoming payments."
width = 250
height = 541
layout = "shadow"
%}

{% include picture.html
image = "/assets/images/guide/payments/receive/receive-pending-details.png"
retina = "/assets/images/guide/payments/receive/receive-pending-details@2x.png"
alt-text = "Screen showing details of an incoming payment that is pending"
caption = "Consider some users who are new to Bitcoin may not know how its transactions get processed."
width = 250
height = 541
layout = "shadow"
%}

</div>

If your application has a list of their payment requests or transaction history, show the status and what stage of completion the transaction is at.

Once the payment has been finalized, consider what the receiver may want to do with those funds. You may want to help facilitate those follow-up activities, for example moving the funds to a shared multi-key wallet or doing a [coinjoin]({{ '/guide/glossary/#coinjoin' | relative_url }}).

<!--
On /guide/payments/send/#inputting-an-address
Add below as Do's & Don'ts

> Besides pushing wallets to adopt Bech32, wallets should provide better and clearer error messages to the end-user. Merchants could use P2SH to mitigate. In my opinion P2SH is just a patch not a solution. A solution where Bech32 invoice can fallback to P2SH would be a good balance.
> @pavelenex
-->

<!--
Follow up page would touch on privacy of transactions including topics of wallet fingerprints (multisig vs signle sig), input/output ordering, coinjoins, and labeling to help users keep separate coin histories.
-->
Loading