Payments Chapter Structure: Unified way to communicate both on-chain and lightning

[johnsBeharry]

Payments

RATIONALE

Below is the proposed structure for the payments section — there are first some foundations which will give readers a base to understand further chapters.

The goal with this structure is to provide the reader with a unified way of learning about bitcoin on-chain and lightning. Instead of having to navigate between separate subchapters and comparing the two - the reader is taken through a payments unified user flow. At each step, when relevant the individual considerations, implementation details and constraints are addressed for each technology.

Additionally the idea for "User Flow" section represents the components that map to what developers would use in implementation.

INTRODUCTION

FOUNDATIONS

Privacy

Units & Symbols

Push & Pull Payments

Addresses

• Types
• Validation
• Display

Transaction Structure & Lifecycle

• Creating a Transaction
• Funding a transaction
• Multiple Signers
• Adding Payments
• Fee
• Change
• Signing
• Filetype
• Broadcasting
• Speeding Up / Canceling
• Confirmations

Lightning Invoices

• Description
• Description Hash (use case: receipt)
• Amount
• Node ID
• Validation
• Fallback Address

USER FLOW

Account Discovery & Scanning

• Choosing Address Type
• Selecting Account
• Gap Limit

Requesting Payments

• QR Codes
• Sharing Payment Requests
• Merchants

Sending

• Coin Selection
• Fees & Estimations
• Case Study / Personal Spending
• Case Study / Joint Spending
• Paying Merchants(?)
• Troubleshooting(?)

Receiving

• Pending / Confirmations
• Notifications
• Dust Attacks

Managing Funds

• Transaction History
• Multi Party Payments
• Spending Policies

Security

• Hide Amounts / Privacy Mode
• Decoy Accounts

[danielnordh]

Awesome, thanks Johns.

I too had a whole bunch of 'basics / foundations' in the beginning of the private key chapter when I started writing.
Once I started to integrate it into the website I ended up moving most of it to the glossary as it really weighed the chapter down and loaded a ton of technical terms on the reader up front.

I would suggest shaping the structure so that it starts with the basic user need (sending or receiving transactions) and then digging deeper and referring to terms as it is needed.

I would also suggest to focus primarily on on-chain transactions (although I would not call it that, just payments or transactions) and leave Lightning/off-chain to after the reader has grasped the basics there.

[pavlenex]

I think starting with simpler stuff and expanding them gradually makes sense. Glossary will always be there to move important terms that overlap within different parts of the guide as Daniel mentioned.

It all comes down to, who is our target audience and how much technical and in-depth information they really need to be able to understand certain concept so that they can design a Bitcoin application.

I commented earlier on the structure, and to me it makes sense, but we need to see which of these sections are more suitable for other parts of the guide.

@johnsBeharry My recommendation is that now that you have a big picture on structure begin with smaller chunks and most basic concepts. Once those are in the guide, we'll get a better feeling on how to expand them.

In my view:

• Transaction Structure & Lifecycle
• Sending
• Receiving
• Managing

Are sections that definitely can be good basis on which we can build on. And all of these PR's are great, even if we fit them in glossary or even separate sections, it's still good. Privacy for example can probably be a whole new section just like Private Key Management.

[johnsBeharry]

Thanks for this input @danielnordh@pavlenex. Agreed I think it makes sense to have for example Privacy & Security under its own section, and even Account Scanning & Discovery could be under Recovery / Migration.

I think we should look at the entire user flow of a bitcoin application then fit the content we come up with in the guide into that. That would also be a structure that would allow us to communicate both lightning and on-chain unified way with two Send and Receive chapters.

As for a page like Units & Symbols and Wallet Interoperability that is being written in PR #30 they can be in a Foundations page (Wallet Interoperability is currently looking for a section).

Thoughts?

[GBKS]

I just created a new "Foundations" section in #108 . That structure makes sense to me. Only thing we need to be clear about is the difference between "Getting started" and "Foundations". "Getting started" is more top-level and even interesting to understand Bitcoin design and user experiences as a non-designer. "Foundations" is about practical design basics and more helpful when you're actually working on something. That's how I look at it at least. What do you think?

[johnsBeharry]

"Foundations" is about practical design basics and more helpful when you're actually working on something. That's how I look at it at least. What do you think?

Agreed with this. Perhaps we state clearly the criteria for what gets into both. Hopefully it doesn't become like the "lib" folder in development which turns into a dump for uncategorised source code.

[danielnordh]

I had a hard time visualizing the flow of this chapter so made an attempt at reorganizing the structure you outlined above @johnsBeharry as if I had tackled it in my own way. I do not want to step on any toes here, please see this as an attempt to help.

Basically all the same information you have outlined should fit in here, I have just attempted to streamline it from a readers point of view. It might be easier to comment in a doc so here's a link: https://docs.google.com/document/d/1Dhu2StMmHEDVTSNdlkQ7Asl695Z97c5qt7j1adjxV3s/edit?usp=sharing

[Page] - Payments introduction

(give an overview of the chapter with links to individual pages, similar to https://bitcoin.design/guide/getting-started/introduction/)

• Transactions overview
• Sending bitcoin
• Receiving bitcoin
• Transaction privacy
• Bitcoin transactions in depth
• Lightning transactions in depth
• Managing funds

[Page] - Transactions overview

Introduce basic transaction concepts and the lifecycle.

• Bitcoin vs Lightning transactions
• Push vs pull transactions
• Transaction life cycle

Link to glossary, foundations etc for things terms that need longer explanation (Units & symbols, address types etc.)

[Page] - Sending bitcoin

Explain what goes into sending bitcoin.

• Sending regular bitcoin
  • How it works
  • Best practices
  • Variations (if relevant)
• Sending bitcoin with the Lightning network
  • How it works
  • Best practices
  • Variations (if relevant)
• Sending from a multi-sig wallet
  • How it works
  • Best practices
  • Variations (if relevant)

Link to advanced information on separate page (like coin selection, coin join, labels etc.).

[Page] - Receiving bitcoin

Explain how receiving/requesting bitcoin works.

• Receiving/requesting regular bitcoin
  • How it works
  • Best practices
  • Variations (if relevant)
• Receiving/requesting bitcoin on the Lightning network
  • How it works
  • Best practices
  • Variations (if relevant)
• Merchant payments
  • How it works
  • Best practices
  • Variations (if relevant)

Link to advanced information on separate page.

[Page] - Transaction privacy

Explain concepts around the privacy of transactions.

[Page] - Bitcoin transactions in depth

Explain advanced concepts and actions you might have mentioned/linked to above in more depth.

• Addresses
  • Types
  • Validation
  • Display
• QR codes (unless this is done in Glossary)
• Creating a transaction
• Funding a transaction
• Signing
  • Multiple signers
• Filetypes
• Broadcasting
• Fee
• Speeding up / Canceling
• Confirmations
• Change
• Account discovery and scanning
• Notifications
• Dust attacks

[Page] - Lightning transactions in depth

Explain advanced concepts and actions for Lightning you might have mentioned/linked to above in more depth.

• Lightning overview
• Lightning nodes
• Invoices

[Page] - Managing funds

Explain concepts around managing funds.

• Transaction history
• Labeling
• Security

[Page] - Case studies (if wanted)

Show prototypical designs of common user flows.

• Sending bitcoin
• Sending with lightning
• ....