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:

• [x] add mobile images for most screens
• [x] add alt-text, captions to some screens
• [x] [optional] improve header image
• [x] 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[bot]]

✅ Deploy Preview for bitcoin-design-site ready!

Name	Link
🔨 Latest commit	5fa5071875be562596ab3a8d30cf0d46f1ae18c6
🔍 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.

[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]

I've now updated intro, illustrations with keys and the pros and cons, as well as incorporated some of the other feedback provided over the last few days.

[rabbitholiness]

Great start, digging into a tricky topic.

In general, I have the impression that the page is quite long. Maybe that's because the content in the second half of the page resembles a reference design. But since it is not centered around a specific use case, it remains relatively vague (e.g. the section about the setup).

Maybe you could dedicate the first part to laying out, how silent payments work, as you currently do. The second half of the page could be framed to highlight the different areas of the bitcoin payments user experience that are impacted through the advent of silent payments, as @GBKS mentioned as well. You do this already, mentioning contacts, sending/receiving, coin selection, backups, etc. But grouping this content under a larger section like "Design considerations" or "User experience impact" could help structure the content and keep it more concise.

Maybe a structure like the following could work:

1. How silent payments work
2. Use cases
3. Conceptual model
4. Labels
5. Design considerations --- Contacts --- Sending & Receiving --- Backup & Recovery

[yashrajd]

Great start, digging into a tricky topic.

Thanks for going through it @rabbitholiness and that illustration! this one's a bit of a rabbit hole and sneaky troublemaker...

In general, I have the impression that the page is quite long. Maybe that's because the content in the second half of the page resembles a reference design. But since it is not centered around a specific use case, it remains relatively vague (e.g. the section about the setup).

I agree, since we discovered silent payments kinda affect or improve practically everything in many ways! But I don't want to call it a reference design since this is just my idea or vision of silent payment AND has great anticipation but little adoption so far.

I'd point to the vague-ness in some areas as an indicator it might not be ready for being a reference design yet.

Maybe you could dedicate the first part to laying out, how silent payments work, as you currently do. The second half of the page could be framed to highlight the different areas of the bitcoin payments user experience that are impacted through the advent of silent payments, as @GBKS mentioned as well. You do this already, mentioning contacts, sending/receiving, coin selection, backups, etc. But grouping this content under a larger section like "Design considerations" or "User experience impact" could help structure the content and keep it more concise.

Maybe a structure like the following could work:

1. How silent payments work
2. Use cases
3. Conceptual model
4. Labels
5. Design considerations --- Contacts --- Sending & Receiving --- Backup & Recovery

• Love the idea of adding a conceptual model section now that I have 2 tables for it
• Don't think sending & recovery can be combined since they have a lot of content
• Might be possible to combine backup & recovery, I'll look into it.
• Also constantly trying to trim content, so help it will help with length

[yashrajd]

Hey @rabbitholiness here's an update to the updates based on your feedback (see recent commits for details):

• Illustrations have been updated with inspiration & the mobile versions are now pretty close to your suggestions
• I've added a conceptual model section
• Backup and Recovery sections are now combined
• Have simplified and trimmed content where I could spot it

Hope it makes the page better...

[yashrajd]

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

[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: https://github.com/BitcoinDesign/Guide/pull/1109/commits/8c2b78c9fd754902c7e95eba504c992e7936321b

[yashrajd]

The checklist from #1117 :

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

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

Content

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

Images

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

[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.