Silent payments in the Guide

[yashrajd]

This is a draft pull request for silent payments content in the guide. It is ready for review but not ready to merge just yet even if feedback is fine. I was able to able to create server and preview all of the content on local.

Preview the silent payments page

Listing a few minor of to-do's below, apart from the any changes necessitated by feedback:

• add mobile images for most screens
• add alt-text, captions to some screens
• [optional] improve header image
• refine copy

Look forward to review and feedback by way of suggestions, corrections for screens and content keeping in mind the above to-dos, which I will complete in a few days. I would discourage inputs on approach unless they were really necessary. I wanted to put this out there so the wider community in general could preview & review it.

[netlify]

✅ Deploy Preview for bitcoin-design-site ready!

Name	Link
🔨 Latest commit	5fa5071
🔍 Latest deploy log	https://app.netlify.com/sites/bitcoin-design-site/deploys/672976276632eb00081abd96
😎 Deploy Preview	https://deploy-preview-1109--bitcoin-design-site.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[GBKS]

Great start with this page. I know you're still working on things, so I didn't go into a ton of detail.

Generally, a lot of content here expands on stuff we already have dedicated pages for (contacts, backup...). As a reader, it can be tricky to piece it all together. Eventually, I think it would be good to have silent payments be covered in those pages, instead of having this addendum. For example, the contacts page should just include them by default. For now, I think it might be good to start paragraph by referencing those other pages, and then only describing what is different.

It's one of those tricky editorial things about the guide, having standalone content, but still having it all work together nicely with little duplication.

Anyhow, let my know if there's any other feedback you'd like (or not like).

[yashrajd]

Great start with this page. I know you're still working on things, so I didn't go into a ton of detail.

It's one of those tricky editorial things about the guide, having standalone content, but still having it all work together nicely with little duplication.

Thanks for reading through @GBKS, I see some great feedback, which I intend to add on top a lot of changes I'm about to push (edit: shown above since they were committed yesterday). Agree re: editorial things, see below.

Generally, a lot of content here expands on stuff we already have dedicated pages for (contacts, backup...). As a reader, it can be tricky to piece it all together. Eventually, I think it would be good to have silent payments be covered in those pages, instead of having this addendum. For example, the contacts page should just include them by default. For now, I think it might be good to start paragraph by referencing those other pages, and then only describing what is different.

Overall, I agree with you but view this effort as silent payments-focused for people who want to read about silent payments and their UX impact. My view (related to #1101 ) is that reference designs should outline established UX patterns and best practices, which IMO doesn't apply to silent payments currently since it is nascent at this point. That said, I've tried to link to existing pages where I could (do let me know if I missed someplace).

[mouxdesign]

Just had a read through Yashraj, thanks for putting this together. You approach the topic from a high level and then it gets more granular. Some suggestions and ideas:

Overall structure

It would be an idea to revisit the overall headings. In general it seems that there is a double introduction and that might be able to be revised by breaking the introduction into two parts. Also would suggest moving the contacts and labels to lower down in the copy.

1. Introduction
2. Advantages to users and user experience
3. Setup
4. Sending
5. Receiving and scanning
6. Contacts and labels
7. Backup
8. Recovery

Images

I would suggest to remove the static address and onchain address in all diagrams. It could be:

• Static address
• Bitcoin address
  For each of these a symbol or a color indicating that its moving from a static to an onchain address. People seeing the diagram would easily understand this if you also include a key at the top.

Suggested introduction with the help of AI

Introduction
On-chain addresses are only meant to be used once. Therefore, users have to interact with others to specify unique address(es) to be used every time they want to pay or get paid. This takes time and effort, along with the possibility of mistakes while handling on-chain addresses. Silent payments is a protocol involving static addresses that are used to derive unique on-chain address during every transaction. This not only prevents address reuse, but also removes the need for repeated interaction.
For example: Alice, who runs an NGO, can simply post a static address on her website, and receive bitcoin donations at unique on-chain addresses that only she can identify. The static address itself never shows up on-chain.

A silent payment transaction happens in 4 broad steps:

• The receiver shares/publishes a static payment address
• The sender obtains & uses it to derive a unique on-chain address
• The sender broadcasts a transaction that pays this derived address
• The receiver identifies the payment as theirs by verifying that they control this address

Advantages to users and user experience

• Removes the need for repeated interaction to specify unique addresses for each transaction
• Prevents address reuse, enhancing privacy and security
• Allows users to customize their static address with labels, which are detected when payments are received
• Improves features such as coin selection and contacts, making them more powerful and easier to use
• Enables a simpler and safer payment experience centered around people
• Reduces the possibility of mistakes while handling on-chain addresses
• Provides a more convenient way for individuals and organizations to receive payments (e.g., donations for an NGO)
• Offers a powerful yet user-friendly approach to bitcoin transactions

Overall, silent payments enable a more intuitive, secure, and user-centric payment experience in the bitcoin ecosystem.

[yashrajd]

Just had a read through Yashraj, thanks for putting this together. You approach the topic from a high level and then it gets more granular. Some suggestions and ideas:

Thanks a lot for this!!

Overall structure

It would be an idea to revisit the overall headings. In general it seems that there is a double introduction and that might be able to be revised by breaking the introduction into two parts. Also would suggest moving the contacts and labels to lower down in the copy.

• re intro: I see your overall point about this content being still too long. I'll try to move some content around and also shorten the text.
• re: contacts and labels - I mentioned them first since they are the most direct benefits of silent payments, and also set the foundation for the changes/benefits to general user flows. They also line up nicely with the content above them.

1. Introduction
2. Advantages to users and user experience
   I have briefly addressed in the intro already but will use them to distill it further. Will also add some of these to the pros and cons.

3. Setup
4. Sending
5. Receiving and scanning
6. Contacts and labels
7. Backup
8. Recovery

Images

I would suggest to remove the static address and onchain address in all diagrams. It could be:

• Static address
• Bitcoin address

I used on-chain address because it seemed specific enough and helpful in explaining the mechanism of silent payments as converting static address to the on-chain version that's in the blockchain.

For each of these a symbol or a color indicating that its moving from a static to an onchain address. People seeing the diagram would easily understand this if you also include a key at the top.

I'll add key to both diagrams, was kinda hoping it wouldn't be necessary if I did a good enough visual...

Suggested introduction with the help of AI

Introduction On-chain addresses are only meant to be used once. Therefore, users have to interact with others to specify unique address(es) to be used every time they want to pay or get paid. This takes time and effort, along with the possibility of mistakes while handling on-chain addresses. Silent payments is a protocol involving static addresses that are used to derive unique on-chain address during every transaction. This not only prevents address reuse, but also removes the need for repeated interaction. For example: Alice, who runs an NGO, can simply post a static address on her website, and receive bitcoin donations at unique on-chain addresses that only she can identify. The static address itself never shows up on-chain.

Thanks! Will use this in crafting a better intro section.

Advantages to users and user experience

• Removes the need for repeated interaction to specify unique addresses for each transaction
• Prevents address reuse, enhancing privacy and security
• Allows users to customize their static address with labels, which are detected when payments are received
• Improves features such as coin selection and contacts, making them more powerful and easier to use
• Enables a simpler and safer payment experience centered around people
• Reduces the possibility of mistakes while handling on-chain addresses
• Provides a more convenient way for individuals and organizations to receive payments (e.g., donations for an NGO)
• Offers a powerful yet user-friendly approach to bitcoin transactions

Overall, silent payments enable a more intuitive, secure, and user-centric payment experience in the bitcoin ecosystem

Incorporating these into pros and cons, adding a couple to intro section.

[yashrajd]

Just updated header images...if those are fine I think this one is ready for final reviews.

[rabbitholiness]

Great progress! The page reads much better already. I made some more suggestions.

It could also be a good idea to add a little bit more structure to the content by framing the bottom half of the content as UX implications. Like so:

• Rationale
• How it works
• New conceptual model
• Labels
• User experience implications
  -- Contacts
  -- Sending
  -- Receiving
  -- Setup
  -- Backup
  -- Recovery
• Pro's and cons

[GBKS]

I was just about to start reviewing the content, but I see 44 unresolved conversations from previous feedback. @yashrajd, could you please address those before we review again?

Did a very quick image check, and please review those as well. Pulling up the site on mobile and quickly scrolling down I saw two broken/missing images. Did not dig any further. I started an image checklist PR earlier with things to look out for (it's a draft and incomplete, but it's a starting point.

[yashrajd]

I was just about to start reviewing the content, but I see 44 unresolved conversations from previous feedback. @yashrajd, could you please address those before we review again?

Vast majority of these were addressed (even commit mentioned long time ago) but I had not marked them resolved. Have done so now.
AFAICT only unresolved conversations right now should be *comments Michael dropped late last week, so please go ahead and review.

Did a very quick image check, and please review those as well. Pulling up the site on mobile and quickly scrolling down I saw two broken/missing images.

I have investigated this and did not find the reason they're working on mobile, these 2images follow spec AFAICT, perhaps you can help me figure it out... I'm happy to investigate further myself but don't want that to prevent you from reviewing...

Did not dig any further. I started an image checklist PR earlier with things to look out for (it's a draft and incomplete, but it's a starting point.

Great to see the PR...

[yashrajd]

I was just about to start reviewing the content, but I see 44 unresolved conversations from previous feedback. @yashrajd, could you please address those before we review again?

Did a very quick image check, and please review those as well. Pulling up the site on mobile and quickly scrolling down I saw two broken/missing images. Did not dig any further. I started an image checklist PR earlier with things to look out for (it's a draft and incomplete, but it's a starting point.

missing mobile images are now fixed, *thx Christoph for the help: 8c2b78c

[yashrajd]

The checklist from #1117 :

Front matter
These are the page properties at the top of markdown files, between the dividers (“—”).

• Ensure the page preview image is 1200x630px in size, and different from the banner image
• redirect_from means that this page previously existed at a different URL. It is not needed for new pages

Content

• Write in sentence case, not title case
• Lowercase “bitcoin”, “lightning network” and “ecash”
• Make sure to explain less-widely known technical terms before expecting users to understand their meaning and properties
• If a new page is a sub-section, make sure to include a reference in the section landing page (example)
• A simpler writing style allows your content to be more accessible to more readers (especially ones for whom english is not their native language)
• For new pages, make sure to update the “Next” and “Previous” buttons on the respective next and previous pages
• Look for opportunities to cross-reference other content in the guide. If somethig is already well-covered elsewhere, you can build on that

Images

• Ensure image content (especially text in images) is legible on mobile devices
• Ensure image paths are correct
• Ensure “width” and “height” attributes in picture and image includes match the actual image dimensions
• For smallest file size, use the JPG file format for textured and photographic images, and PNG for images with mostly flat color
• Compress your images via tool like ImageOptim (can save ~70% of bandwidth)
• Delete unused images from your PR
• Every non-decorative image needs to have helpful alt text (tips)

[GBKS]

Thank for pushing this PR. This review has 30 more comments, but it really is mostly small stuff. Many of them are for adding commas to run-on sentences that are hard to read.

I still find the diagrams hard to read on mobile. You basically have to zoom in and pan around. Up to you if you want to address that further.

The tables are also not great, you basically get one word per line on mobile. Personally I'd just reformat those to regular text and full sentences. The table format requires me as a reader to piece things together. If you give me a sentence, you give me fully formed explanations without gaps. Also up to you what path to go there.

[GBKS]

I wonder if some of those tips can be hidden behind an info button and appear in a modal? The text just gets super tiny and that small address is basically impossible to compare.

[rabbitholiness]

+1

[GBKS]

ACK. Let's get this one out the door.

[rabbitholiness]

Looks great! Just had a few minor comments. Let's go 🤙

[rabbitholiness]

Suggested change

[Silent payments](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki) is a protocol that uses static addresses to simplify payment experience, while preserving privacy. Once the receiver shares a static address, senders derive a new unique on-chain addresses while making payments. This prevents [address reuse](/guide/glossary/address/#address-reuse) without repeated user interaction.

[Silent payments](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki) is a protocol that uses static addresses to simplify the payment experience, while preserving privacy. Once the receiver shares a static address, senders us it to derive a new unique on-chain addresses automatically for each payment they make. This prevents [address reuse](/guide/glossary/address/#address-reuse) without repeated user interaction.

[rabbitholiness]

Might be worth mentioning that they also help with accounting and book-keeping. I think that's also a nice real-world benefit to many users.

[rabbitholiness]

Not sure whether this helps, but the nodes and light clients probably represent the receiver in the vast majority of cases, right? Might be worth pointing this out.

[rabbitholiness]

Suggested change

	Labels (such as `business` or `no-kyc`) are brief identifiers often associated with information such as payments, transactions and addresses. They're used to organise, categorise or quickly spot information from a large set.
	Labels (such as `business` or `no-kyc`) are brief identifiers often associated with information such as payments, transactions and addresses. They are used to organise, categorise or quickly spot information from a large set.

[rabbitholiness]

Suggested change

	Silent payments allow users to add labels to their static addresses on a case-by-case basis before sharing or posting them. When a payment is received, these labels can be detected by the receiver (but no one else) and used to identify the static address that was used to make the payment.
	Silent payments allow users to add labels to their static addresses on a case-by-case basis before sharing or posting them. When a payment is received, these labels are detected by the receiver (but no one else) and used to identify the static address that was used to make the payment.

[rabbitholiness]

Suggested change

	Silent payments (along with [BOLT-12](http://bolt12.org)) allow applications to center their payments experience around people instead of addresses. This was not advisable before, due to issues with on-chain address reuse.
	Silent payments (along with [BOLT-12](http://bolt12.org)) allow applications to center their payments experience around people instead of addresses. This was not advisable before, due to privacy issues associated with on-chain address reuse.

[rabbitholiness]

Suggested change

	Contacts are not just for sending. The receiver can create contacts for parties they only receive bitcoin from. When they share a labelled static addresses with others, such as employers or customers, creating a contact can help with invoicing, tracking payments and coin selection.
	Contacts are not just for sending, however. The receiver can create contacts for counterparties they only receive bitcoin from, such as employers or customers. When they share a labelled static addresses with others, creating a contact can help with invoicing, tracking payments and coin selection.

[rabbitholiness]

+1

[rabbitholiness]

Would it make sense for applications to also provide an application setting where users can opt in to regular scanning, e.g. "every night at 1:00AM UTC", or "every 4 hours"? this way it would always be more or less up to date and I don't have to wait too long, if I open the app infrequently.

[rabbitholiness]

Bitbox recently supported sending to silent payment addresses as well, being the first hardware device to support the feature.

[yashrajd]

Thanks again for the review Michael...I looked at them and they seem good but minor, so I'd like to address them at a later date. I've created #1127 to track precisely such changes.

I'd like to request the maintainers to merge the PR in current state if they feel it is prudent but I'm also happy to make more changes if they feel that is what's needed...

[GBKS]

OK, going to merge this one, per Yashraj's request to address minor feedback in his follow-up issue. Thanks for being so thorough.