Restructured Payments chapter.

guide/payments/coin-selection.md → guide/glossary/coin-selection.md

@@ -2,10 +2,11 @@
 layout: guide
 title: Coin Selection
 description: A primer on how UTXOs are chosen to fund new bitcoin transactions.
-nav_order: 2
-grand_parent: Payments
-parent: Sending bitcoin
-permalink: /guide/payments/send/coin-selection/
+nav_order: 4
+parent: Glossary
+permalink: /guide/glossary/coin-selection/
+redirect_from:
+ - /guide/payments/send/coin-selection/
 main_classes: -no-top-padding
 ---
 
@@ -82,6 +83,7 @@ Automatic selection strategies can provide a near frictionless user experience a
 %}
 
 ### How it works
+
 A user chooses to send a payment to one of their contacts. They enter the amount of bitcoin they wish to send, select their transaction fee rate, and approve the outgoing payment request. During this process, their wallet **automatically** selects which coins to use to fund the transaction’s inputs, making sure it can fulfill the payment request.
 
 <div class="image-slide-gallery">
@@ -133,35 +135,45 @@ A user chooses to send a payment to one of their contacts. They enter the amount
 Below are some popular algorithms currently implemented by Bitcoin wallets that optimize for speed and lower fees:
 
 #### First In First Out (FIFO) / Last In, First Out (LIFO)
+
 The default strategy spends the oldest/youngest coins first.
 
 #### Pruned FIFO
+
 Similiar to FIFO, but smallest coins filtered out in post-selection step.
 
 #### High Priority First
+
 Coins selected by priority (calculated by value x age). Up until February 2016, a portion of each block (50kB) was reserved for high-priority transactions by default. This algorithm therefore optimised for transaction speed.
 
 #### Minimize Fees (Optimize Size)
+
 Spending the lowest number of coins to reduce the byte size of the transaction, resulting in a lower fee.
 
 #### Minimize Future Fees (Merge Coins)
+
 Spending the maximum number of inputs to merge coins as a single change output for future use. This strategy can optimise for speed as the transaction size (and therefore cost) is increased. However, merging coins can also lead to a loss of privacy as coins, their addresses, balances, and historical transaction data are intertwined.
 
 Below are algoorithms that optimize for privacy
 
 #### Target Sized Change
+
 Wallet aims to minimize the value difference of target input and change output.
 
 #### Branch & Bound (BnB)/Exact Change
+
 Wallet finds an input set that is equal in value to the target, avoiding change outputs. If the wallet cannot find an exact match, it refers back to a “knapsack” solver which selects inputs that minimise the change output to within 0.01 BTC.
 
 #### Blackjack
+
 Accumulates inputs until the target value (+fees) is matched, does not accumulate inputs that go over the target value (within a threshold).
 
 #### Accumulative
+
 Accumulates inputs until the target value (+fees) is reached, skipping detrimental inputs.
 
 #### Freezing Coins
+
 Freezes certain coins or clusters from their wallet’s UTXO pool to either prioritize or avoid using when funding outgoing payment requests. This technique aids automatic selection strategies to become more private but also relies on the practice of successfully labeling coins.
 
 {% include picture.html
@@ -191,14 +203,17 @@ Freezes certain coins or clusters from their wallet’s UTXO pool to either prio
 ### Best practice
 
 #### When to use
+
 - New users or introductory level wallets
 - Wallets specifically optimizing for either cost, speed, or privacy
 
 #### When not to use
+
 - When privacy is a top priority to users
 - When wanting to provide a more custom experience for Bitcoin transactions
 
 #### Products that use this scheme
+
 {% include fact/products.html %}
 [BitcoinJ and Bitcoin Wallet for Android](https://bitcoinj.org/), [Bitcoin Core](https://bitcoin.org/en/bitcoin-core/), [Bread Wallet](https://brd.com/), [Electrum](https://electrum.org/#home), [Hexa Wallet](https://hexawallet.io/), and [Mycelium](https://wallet.mycelium.com/)
 {% include fact/close.html %}

guide/payments/introduction.md

@@ -9,6 +9,14 @@ main_classes: -no-top-padding
 image: https://bitcoin.design/assets/images/guide/payments/payments-preview.jpg
 ---
 
+<!--
+
+Illustration source
+
+-
+
+-->
+
 {% include picture.html
  image = "/assets/images/guide/payments/introduction.svg"
  mobile = "/assets/images/guide/payments/introduction-mobile.svg"
@@ -28,9 +36,9 @@ We have already established that [Bitcoin is money]({{ '/guide/getting-started/w
 
 ---
 
-### [Transactions overview]({{ '/guide/payments/transactions/' | relative_url }})
+### [Requesting bitcoin]({{ '/guide/payments/request/' | relative_url }})
 
-An overview of Bitcoin payments, common concepts and the transaction lifecycle.
+An introduction to how requesting and receiving bitcoin works.
 
 ---
 
@@ -40,13 +48,7 @@ An introduction to how sending bitcoin works.
 
 ---
 
-### [Requesting bitcoin]({{ '/guide/payments/request/' | relative_url }})
-
-An introduction to how requesting and receiving bitcoin works.
-
----
-
-### [Transaction privacy]({{ '/guide/payments/privacy/' | relative_url }})
+### [Privacy]({{ '/guide/payments/privacy/' | relative_url }})
 
 An overview of how to help users maintain transaction privacy with Bitcoin.
 
@@ -58,15 +60,15 @@ The basics on units and currency symbols, how to format them and what options to
 
 ---
 
-### Managing funds (coming soon)
+### [Transactions overview]({{ '/guide/payments/transactions/' | relative_url }})
 
-How to help users organize and manage their transaction data and holdings.
+An overview of Bitcoin payments, common concepts, and the transaction lifecycle.
 
 ---
 
 {% include next-previous.html
  previousUrl = "/guide/private-key-management/backups/"
  previousName = "Bitcoin backups"
- nextUrl = "/guide/payments/transactions/"
- nextName = "Transactions overview"
+ nextUrl = "/guide/payments/request/"
+ nextName = "Requesting bitcoin"
 %}

guide/payments/payment-request-formats.md

@@ -1,15 +1,15 @@
 ---
 layout: guide
 title: Payment request formats
-description: An introduction to how sending bitcoin works.
+description: An introduction to the different Bitcoin payment request formats.
 nav_order: 1
 grand_parent: Payments
-parent: Sending bitcoin
-has_children: false
-permalink: /guide/payments/send/payment-request-formats/
+parent: Requesting bitcoin
+permalink: /guide/payments/request/payment-request-formats/
+redirect_from:
+ - /guide/payments/send/payment-request-formats/
 main_classes: -no-top-padding
 image: /assets/images/guide/payments/send/bitcoin-payments-social.jpg
-
 image_base: /assets/images/guide/payments/send/
 images:
  - file: home
@@ -129,11 +129,11 @@ Each request format has its own unique approach to bundle payment information fo
 
 ---
 
-Sending is one side of the process. Let's look at things from the [receiver's perspective](/guide/payments/request).
+Next, we will look at how a [sender](/guide/payments/send) pays these payment requests.
 
 {% include next-previous.html
- previousUrl = "/guide/payments/transactions/"
- previousName = "Transactions overview"
- nextUrl = "/guide/payments/request"
- nextName = "Receiving bitcoin"
+ previousUrl = "/guide/payments/request/"
+ previousName = "Requesting bitcoin"
+ nextUrl = "/guide/payments/send"
+ nextName = "Sending bitcoin"
 %}

guide/payments/privacy.md

@@ -1,8 +1,8 @@
 ---
 layout: guide
-title: Transaction privacy
+title: Privacy
 description: An overview of how to help users maintain their financial privacy while using Bitcoin.
-nav_order: 4
+nav_order: 3
 parent: Payments
 permalink: /guide/payments/privacy/
 main_classes: -no-top-padding
@@ -148,11 +148,11 @@ There is no perfect solution to guarantee 100% privacy that lasts forever becaus
 
 ---
 
-Next, let's look at [units & symbols]({{ '/guide/payments/units-and-symbols/' | relative_url }}).
+Next, let's dive into how to display various [units & symbols]({{ '/guide/payments//units-and-symbols/' | relative_url }}) in bitcoin applications.
 
 {% include next-previous.html
- previousUrl = "/guide/payments/request"
- previousName = "Requesting bitcoin"
- nextUrl = "/guide/payments/units-and-symbols/"
+ previousUrl = "/guide/payments/send/"
+ previousName = "Sending bitcoin"
+ nextUrl = "/guide/payments//units-and-symbols/"
  nextName = "Units & Symbols"
 %}

guide/payments/request.md

@@ -2,11 +2,12 @@
 layout: guide
 title: Requesting bitcoin
 description: An introduction to how requesting bitcoin works.
-nav_order: 3
+nav_order: 1
 parent: Payments
+has_children: true
 permalink: /guide/payments/request/
 redirect_from:
- - /guide/onboarding/receive/
+ - /guide/payments/receive/
 main_classes: -no-top-padding
 # image: /assets/images/guide/payments/request/header.svg
 ---
@@ -173,7 +174,7 @@ Reusable payment requests are common when making Lightning payments as they are
 
 Reusable payment requests are not common when conducting transactions. This is due to them being conducted less frequently so the burden of generating a new payment request for each on-chain payment is not as large. On-chain addresses are reusable, though as previously mentioned this has privacy implications so this practice is not recommended.
 
-Several, not widely supported, reusable payments request formats also exist. For Lightning, there are BOLT 12 offers, AMP invoices and Keysends, which require just a node ID. For on-chain, there are reusable payment codes [BIP 47](https://bips.xyz/47) and [xpubs]({{ "/guide/glossary/#extended-public-key-xpub-ypub-zpub" | relative_url }}), which can be used to generate addresses for receiving bitcoin on-chain. Learn more about these on our [payment request formats]({{ "/guide/payments/send/payment-request-formats/" | relative_url }}) page.
+Several, not widely supported, reusable payments request formats also exist. For Lightning, there are BOLT 12 offers, AMP invoices and Keysends, which require just a node ID. For on-chain, there are reusable payment codes [BIP 47](https://bips.xyz/47) and [xpubs]({{ "/guide/glossary/#extended-public-key-xpub-ypub-zpub" | relative_url }}), which can be used to generate addresses for receiving bitcoin on-chain. Learn more about these on our [payment request formats]({{ "/guide/payments/request/payment-request-formats/" | relative_url }}) page.
 
 ### Contact cards
 
@@ -247,7 +248,7 @@ Contact cards are a great way to store, manage and share reusable payment reque
 
 Another way a user can request bitcoin is from a withdrawal request. A withdrawal request is a payment request that lets the receiver withdraw bitcoin from another wallet. Unlike previously mentioned payment requests, withdrawal requests are generated by the sender. These can be useful for merchants providing refunds to customers.
 
-We explore generating a withdrawal request in our [sending bitcoin]({{ "/guide/payments/send/" | relative_url }}) section. Wallets that do not support withdrawal requests should provide users with a human readable error if an attempt is made to use one. Our [payments format page]({{ "/guide/payments/send/payment-request-formats/" | relative_url }}) goes into more detail on withdrawal requests.
+We explore generating a withdrawal request in our [sending bitcoin]({{ "/guide/payments/send/" | relative_url }}) section. Wallets that do not support withdrawal requests should provide users with a human readable error if an attempt is made to use one. Our [payments format page]({{ "/guide/payments/request/payment-request-formats/" | relative_url }}) goes into more detail on withdrawal requests.
 
 <div class="image-slide-gallery">
 
@@ -457,11 +458,11 @@ For in-person payments, showing the confirmation screen to the sender will likel
 
 ---
 
-Let's go, time go dive in a bit deeper with [transaction privacy]({{ "/guide/payments/privacy/" | relative_url }}).
+Next, we go over the different [payment request formats](/guide/payments/request/payment-request-formats/) available in bitcoin.
 
 {% include next-previous.html
- previousUrl = "/guide/payments/send/"
- previousName = "Sending bitcoin"
- nextUrl = "/guide/payments/privacy/"
- nextName = "Transaction privacy"
+ previousUrl = "/guide/payments"
+ previousName = "Payments"
+ nextUrl = "/guide/payments/request/payment-request-formats"
+ nextName = "Payment request formats"
 %}

guide/payments/send.md

@@ -4,7 +4,6 @@ title: Sending bitcoin
 description: Best practices and design guidelines for designing user experiences for sending bitcoin in wallet applications
 nav_order: 2
 parent: Payments
-has_children: true
 permalink: /guide/payments/send/
 main_classes: -no-top-padding
 image: /assets/images/guide/payments/send/bitcoin-payments-social.jpg
@@ -128,7 +127,7 @@ Below are visualizations of some of these entry points.
 
 Since users cannot control how a payment request is presented to them, wallets should be highly flexible in terms of input options and [interoperability]({{ '/guide/designing-products/wallet-interoperability/' | relative_url }}). If your wallet does not support a particular payment request, users should be presented with a human readable [error]({{ '/guide/payments/send/#errors' | relative_url }}).
 
-Payment information can be shared in many formats and over diverse communication channels. Each has its own advantages and limitations. More details on the [payment request formats]({{ '/guide/payments/send/payment-request-formats/' | relative_url }}) page.
+Payment information can be shared in many formats and over diverse communication channels. Each has its own advantages and limitations. More details on the [payment request formats]({{ '/guide/payments/request/payment-request-formats/' | relative_url }}) page.
 
 ## Presenting payment requests
 
@@ -146,7 +145,7 @@ When responding to an invoice that contains all relevent information, the user c
 
 The most convenient option for choosing a recipient is from previously saved contacts. Alternatively, users can enter on-chain addresses, Lightning addresses, Lightning node IDs, or other static identifies that are supported by the wallet.
 
-There are also static [invoice types]({{ '/guide/payments/send/payment-request-formats/' | relative_url }}) that can receive payments repeatedly. These are less intuitive overall due to their appearance, but could also be considered payment endpoints.
+There are also static [invoice types]({{ '/guide/payments/request/payment-request-formats/' | relative_url }}) that can receive payments repeatedly. These are less intuitive overall due to their appearance, but could also be considered payment endpoints.
 
 **Amount**
 
@@ -282,19 +281,19 @@ There are situations in which users may want to make more complex adjustments to
 
 **Coin selection**
 
-Some users may prefer to choose which of their bitcoin (UTXOs to be precise) to send, in order to protect their privacy. More on this topic on the [Coin selection page]({{ '/guide/payments/send/coin-selection/' | relative_url }}) page.
+Some users may prefer to choose which of their bitcoin (UTXOs to be precise) to send, in order to protect their privacy. More on this topic on the [Coin selection page]({{ '/guide/glossary/coin-selection/' | relative_url }}) page.
 
 **Lightning routing options**
 
 Routing is a probabilistic endeavor. For example, a routing algorithm may identify two routes. The first one has a low fee but is also less likely to succeed. The second route has a higher fee, but is more likely to succeed. Due to the technical complexity and unknowns, there is [ongoing conversation](https://github.com/BitcoinDesign/Guide/issues/585) whether routing options are relevant for users to be aware of and make decisions on.
 
 ---
 
-Sending is one side of the process. Let's look at things from the [requester's perspective](/guide/payments/request).
+Next, we cover [privacy considerations]({{ '/guide/payments/privacy' | relative_url }}) when to consider when making bitcoin payments.
 
 {% include next-previous.html
- previousUrl = "/guide/payments/transactions/"
- previousName = "Transactions overview"
- nextUrl = "/guide/payments/request"
- nextName = "Requesting bitcoin"
+ previousUrl = "/guide/payments/request/payment-request-formats"
+ previousName = "Requesting bitcoin"
+ nextUrl = "/guide/payments/privacy/"
+ nextName = "Payments privacy"
 %}

guide/payments/transactions.md

@@ -1,8 +1,8 @@
 ---
 layout: guide
-title: Transactions
-description: An overview of Bitcoin payments, common concepts and the transaction lifecycle.
-nav_order: 1
+title: Transactions overview
+description: An overview of Bitcoin transactions, common concepts, and the transaction lifecycle.
+nav_order: 5
 parent: Payments
 permalink: /guide/payments/transactions/
 main_classes: -no-top-padding
@@ -183,11 +183,11 @@ Blocks are also limited in size and new ones are created every 10 minutes on ave
 
 ---
 
-Next we will cover [sending bitcoin]({{ '/guide/payments/send/' | relative_url }}).
+The next section explores common product designs via [case studies]({{ '/guide/case-studies/' | relative_url }}).
 
 {% include next-previous.html
- previousUrl = "/guide/payments/"
- previousName = "Payments"
- nextUrl = "/guide/payments/send/"
- nextName = "Sending bitcoin"
+ previousUrl = "/guide/payments/units-and-symbols"
+ previousName = "Units & Symbols"
+ nextUrl = "/guide/case-studies"
+ nextName = "Case studies"
 %}

guide/payments/units-and-symbols.md

@@ -2,7 +2,7 @@
 layout: guide
 title: Units & Symbols
 description: How to display and format bitcoin and currency units in Bitcoin applications.
-nav_order: 5
+nav_order: 4
 parent: Payments
 permalink: /guide/payments/units-and-symbols/
 main_classes: -no-top-padding
@@ -203,17 +203,17 @@ Trailing zeros can help more easily compare amounts in right-aligned tables.
  height = 198
 %}
 
-Complex use cases often require users to interact with addresses, public keys, and other encrypted data, where it is important that each character is easily identifyable. Slashed zeros can help distinguish 0 (the number zero) and O (the uppercase letter "O"), which can look very similar in some typefaces.
+Complex use cases often require users to interact with addresses, public keys, and other encrypted data, where it is important that each character is easily identifiable. Slashed zeros can help distinguish 0 (the number zero) and O (the uppercase letter "O"), which can look very similar in some typefaces.
 
 Note that uppercase letter "O", uppercase letter "I", lowercase letter "l", and the number "0" are not valid characters in addresses, in order to prevent mistakes. As users may not be aware of this, using slashed zeros may still be a helpful design choice.
 
 ---
 
-The next section explores common product designs via [case studies]({{ '/guide/case-studies/' | relative_url }}).
+Next, we do a technical deep dive into how [transactions]({{ '/guide/payments/transaction' | relative_url }}) on bitcoin work.
 
 {% include next-previous.html
  previousUrl = "/guide/payments/privacy"
  previousName = "Transaction privacy"
- nextUrl = "/guide/case-studies/"
- nextName = "Case studies"
+ nextUrl = "/guide/Payments/transactions"
+ nextName = "Transactions overview"
 %}