Identify what content around Lightning should be added to the guide

[GBKS]

Adding Lighting to the guide has been a goal from the beginning and now that the first version of the guide is live, we can start tackling this complex topic.

[Bosch-0]

There is two ways we can approach this:

1. Integrate Lightning content within existing content.
2. Segment lightning content into its own sections.

It would be easier to go with option 2 as option 1 would involve a lot of refactoring / pages will get too lengthy and complicated.

Better to stay focused on having 'This section covers an on-chain focused product design' and 'This section covers an lightning focused product design'

An example: in the onboarding chapter we could nest pages from 'Creating a new wallet' to 'Funding a wallet' in a page called 'On-chain' which gives some details about how this section is on-chain focused and why you would want a product focused on just that (say a vault / storage type product). Then have a 'Lightning' section that builds on / goes through a similar process but in the context of LN.

There will likely be some overlap, which I think is fine, as the target audience will be focused on the sections relevant to the products they are designing (whether on-chain focused or lightning focused).

More general sections of the guide option 1 is more suited. For example, including lightning context in technology primer / software overview and getting to know your users pages.

[johnsBeharry]

I think we need to actually do the work to try and form consistency between the two networks on the UI as well as the language we use to describe things. Then, designers can learn about both in a cohesive way instead of having to compartmentalise them and go through duplicate content. So we need to refactor.

Things like automatic cloud backup, isn't just used for backing up 12 seeds, it can back up any arbitrary data, even Muun's recovery codes, or Breez channel state, or Chaincase labels and anonymity set data. I can also go on about addresses being invoices, esp. as they are only used once. This style of writing was mostly removed from the payments section to have more standard on-chain language but perhaps we should revisit when adding lightning .

At some point, you're going to need to interact on-chain, and as lesser as it may be, if that experience is just absolutely separate and unfamiliar we can expect confusion.

• Onboarding
• Address/Address reuse -> Invoices
• Coin selection -> Channel selection
• Send -> Send
• Receive -> Receive

The content in the guide is focused on mobile experiences. Hardly anything on Creating a new wallet would change conceptually for lightning from what I can tell.

@Bosch-0 better a page being a bit more lengthy vs a bunch of duplicated content and structure.

[Bosch-0]

Having Lightning from the start of the guide would of made things a lot easier!

I think we need to actually do the work to try and form consistency between the two networks on the UI as well as the language we use to describe things.

Not having to worry about the two networks is what end users should ultimately experience though this guide is about educating designers about how to design Bitcoin products right? Educating designers should involve:

1. This is what Bitcoin is and how you design on-chain focused products.
2. This is what Lightning is and how you design Lighting products.

Designers armed with this knowledge can then decide how they want to craft their product. Do they want a lightning product more like Muun or more like Zeus? Do they want an on-chain focused product like Spectre or Bitcoin Core? If it is just all merged together things will get overly complex and it will be harder to illustrate all the UI flows as clearly as it would be having the content separate.

They are separate networks with different tradeoffs / use cases. Designers building Bitcoin products need to know this. End users don't need to know the difference but this guide isn't for them. We can unify the content with case studies / prototypes but when it comes to the main content, that is educating designers on how to design these products, they should be taught separately.

Regarding terminology I think it is much more confusing merging terms such as a Bitcoin send and a Lightning send. When things go wrong not knowing the difference will end badly. I don't think we are at a stage where we can do this technology wise, we should be wary not to abstract too much away.

[moneyball]

If we imagine a future of financial inclusion and wild success for bitcoin, it will mean there will be billions of users and hundreds of millions of non-custodial users. The vast majority of non-custodial users will necessarily have to be using LN-enabled bitcoin products (ie not on-chain-only products). As the design guide focuses on non-custodial bitcoin usage, it seems to make sense to me that the guide assumes LN.

Why will LN be used by the vast majority of non-custodial users? For a variety of reasons which I'll elaborate.

1) Scaling. On-chain bitcoin handles about 300K transactions per day. Let's walk through a couple of examples: a) Let's take the "bitcoin is currency of the internet" use case and assume 3 payments/week for an average user. 300K/day 365 days/year / 52 weeks/year / 3 payments/week = a maximum 700K users. El Salvador alone has 6.5 million people... b) Let's take the saver/HODLer use case and assume 4 on-chain transactions per year (some blend of people doing recurring buys every paycheck with others who only buy or sell or switch wallets say once a year). 300K/day 365 days/year / 4 txn/year = a maximum 27 million users. Also note that custodial services do a large portion of on-chain transactions so in reality there would likely be a max of 10 million or so savers. So even the HODLer use case fails to scale in the long-term if we assume 100mil+ non-custodial users.

2) Settlement speed. For the payment use case, be it in person or online, people expect to settle in seconds, not tens of minutes. LN is designed for payments whereas on-chain is not.

3) Fees. LN fees will undoubtedly be substantially cheaper than on-chain fees facilitating payments of less than $100 which is the vast majority of payments.

4) Significantly improved payment destination UX. Instead of requiring users to deal with addresses such as "3LDs8bmx2do1SunJEb7WpB4iobrjf6TAHf" they can instead pay "Bob" (from their phone contacts, which is mapped to Bob's LN node pubkey using keysend).

So IMO the design guide should be a guide that covers 99.9% of users. It should be woven into the design guide where it needs to be, such as: 1) Onboarding/backup/recovery (more than just a seed word) 2) Private key management (more than just a seed word) 3) Payments - this section should be 99% about LN and 1% on-chain for the exceptional cases where users need to worry about this. 4) Case studies - Daily spending (obviously must assume LN) (probably other areas too)

If there is a desire by the design community to also assist designers and developers to build products for power users and LN router managers, this is where I'd suggest a separate section is created in isolation to help with those important but niche use cases. This is where detailed channel management could be covered.

I listened to the community call recording and saw @sbddesign reference Apple's WiFi advanced settings on a Macbook for power users, which I acknowledge, but I also note that similar settings are not available on iPhone. I would liken a Macbook more to a future power LN router user who wants to optimize their LN router and fee revenue.

What do I think are some important LN-related topics the design guide should cover that will be most useful to product designers?

1. How to send a payment (keysend vs. invoice-style) 1b. If the payment is unable to be made on LN, and on-chain is used as a backup, what ramifications are there for the user, what needs to be communicated to the user?

2. How to receive a payment 2b. How to handle mobile case of being "offline"? 2c. How does user map their LN node pubkey to their identity for others to use (keysend) 2d. How to use invoices. When to use invoices vs. keysend? 2e. How/when to expose user to receiving a payment on-chain vs. LN?

3. How to communication to the user less common situations such as unspendability of channel reserve, channel closing fees, etc?

4. How to communicate to user the UX/security tradeoffs made in the design of the product such as where block data is sourced from (full-node on device vs. trusted server full node vs. BIP 157/158 compact block filter p2p network vs. Electrum API), where recovery data, particularly persistent LN data, is stored (in cloud vs. on a memory stick), use of watchtower or other mechanism to protect against hostile channel closings, etc.

[Bosch-0]

So IMO the design guide should be a guide that covers 99.9% of users.

I agree, my original post suggesting splitting the content did not take into account the 'scope' of the guide which I think we haven't clearly defined resulting in this debate. Steve did a great job in defining a LN first scope above, which I also think we should go with for reasons he pointed out, and I've added some comments of my own below as to why.

As the design guide focuses on non-custodial bitcoin usage, it seems to make sense to me that the guide assumes LN.

Based on the comments after this opening paragraph it would seem you lean towards more lightning first rather than just assuming LN in the stack - is that correct? I agree with this approach with the design guide being for the products 99.9% of users will be using.

Assuming LN first we should explicitly state this early in the guide so readers know the scope of products the guide is helping designers build (currently things are quite general and broad). Defining this scope would also be beneficial to contributors coming on board looking to contribute to the guide. We can have separate sections and scope for more advanced products like Lightning node managers, Bitcoin node and/or multisig vault products.

So, the primary scope of the guide should be - Mobile first, non-custodial, Bitcoin Lightning products.

Current great examples we can model a lot of our content around is Muun + Phoenix + Breez.

Payments - this section should be 99% about LN and 1% on-chain

I agree, LN and payments are synonymous to me whilst on-chain is for savings and transfers type value movements. A money transfer doesn't usually encompass standard payments you make to buy goods and services, hence we should refer to an on-chain sends as transfers and lightning sends as payments. A lot of grey areas here but that's how traditional finance defines these things so people wouldn't have too hard a time grasping the distinction imo. It's better to distinguish these networks by their use cases, calling them both payments when they serve different purposes is way too general and confusing imo.

A comment that stuck with me that John C mentioned in the recent community call is about how quick things move, especially with regards to LN, our content will get dated quickly.

Something we must consider when crafting content, especially LN content, is should we 'future proof' it and make assumptions about where Bitcoin UX is going or stay focused on what is best design practices right now? I think we should design ahead as to not make our content dated by the time we publish it.

Some examples include using LN keysends over invoices with a contact list mapped to their users pubkeys and mobile lightning nodes so it's non-custodial / don't need a 24/7 uptime node. Another example is moving our recommended backups content to something more akin to Muun which is a much better UX than a mnemonic which does not backup derivation paths, order of keys in multisig etc.

We may be wrong at times, and some new technology may come out that makes our content / assumptions irrelevant but it is better then building content that isn't useful. As the Bitcoin Design community we should be at the cutting edge of Bitcoin UX not recommending transitory practices that will be replaced in the near future.

If there is a desire by the design community to also assist designers and developers to build products for power users and LN router managers, this is where I'd suggest a separate section is created in isolation...

+1 this. These more technical aspects should be separate in later sections of the guide. Whether or not these were to be included was something that made me lean more towards separating content in my OP. Lets do it!

So to clarify:

1. Guide's primary scope for now should be: Mobile first, non-custodial, Bitcoin Lightning products.
2. On-chain content should be discussed only where relevant in the context of point 1.
3. General content should be focused on what is relevant in assisting designers craft user friendly products (product scope defined in point 1) and no more - more technical dives can be linked to in the guide and/or covered in the sections defined in point 4.
4. A secondary scope / sections could cover more novel products like Lightning node managers (Zeus), multisig 'vaults' or nodes (Bitcoin Core / RoninDojo).

[sbddesign]

I feel like we are orbiting around consensus on integrated LN content, if I am understanding everyone's points of view correctly. I also support the idea of LN content integrated into the existing Guide.

I think for someone who is trying to deeply learn LN from a technical perspective, it makes sense to first study Bitcoin  and then study LN. However, the target audience for the guide IMHO is first designers, and secondly developers who may need design help but who probably understand these technologies well already. As a result, I think it's more efficient to discuss designing for Layer 1 Bitcoin and LN more cohesively.

Here is a quick mock-up I did as an example of integrating LN into the existing Guide.

See Figma File

• On the left, we have the existing page "Onboarding > Backing up a recovery phrase".
• On the right, I have modified the page to be "Onboarding > Backing up a new wallet".
  • In the introductory text, I stress the importance of encouraging the user to backup the wallet, and I discuss how different types of bitcoin wallets will have different types of backups.
  • I then link to the sub-chapters discussing the different types of backups the user might encounter.
  • The wonderful text about recovery phrases could be consolidated into the manual backups chapter.
  • An emergency kit chapter could be added for situations where the manual backup requires a lot of extra information beyond the recovery phrase (I am borrowing that term from the Muun wallet).

This example was quickly put together and I do not mean to say it should say all of that exactly. I'm just trying to demonstrate a way that LN content could be interwoven seamlessly into the existing content.

[moneyball]

@sbddesign Thank you for putting that together! I see 2 ways we could go about it:

1. What you've demonstrated, which I'd characterize as "ok product designers, here are N different types of wallets, and here is the recommended solution for each."
2. Or, we could assume a LN-enabled wallet as default, and thus describe the recommended guidelines for that type of wallet (in this specific case, that would mean we assume LN channel states need to be backed up, somehow). Then, discussion of the "1% case" of an on-chain only wallet, which has simpler backup requirements, could be done as more of a footnote, or separate section at the end, or somewhere else.

I was leaning more toward 2. It'd be interesting to see how that looks if you "mock it up" so we can compare.

[Bosch-0]

I generally lean towards the second approach as well but I think there is a way we could have a mix of those those two approaches without things getting too convoluted and simultaneously not limiting things by being too specific. I've detailed this to some degree here but below is my thoughts in a nutshell.

1. We have a section in the guide early on that lays out all the design pieces that can be configured in various ways to construct a wallet.
   • Examples of chapters in this section:
     • Private key schemes, Backup schemes, Networking schemes (broken into Bitcoin + Lightning).
   • An example of a piece would be 'Emergency recovery kit' used in Muun detailed within the 'Private key schemes' chapter.
2. The section following this we combine the pieces we think results in the best UX for a mobile-first, non-custodial, Bitcoin Lightning wallet.
3. We can combine pieces in different ways to construct other products in a seperate section that suit different needs later on (we should just focus on point 2 for V2 of the guide though imo).

Defining these sections IMO would make the guide much easier to parse and find info relevant to the reader. Currently we have a setup where point 1 and 2 and kind of jelled together and it can get a little messy at times. Not separating things will compound this issue as we introduce more 'pieces' around LN.

[sbddesign]

@moneyball Yes I can mockup another version.

@Bosch-0 I do like your idea (detailed more here) about separating ideas into design pieces and then show how those pieces form together into a wallet. Worth exploring.

[sbddesign]

2. Or, we could assume a LN-enabled wallet as default, and thus describe the recommended guidelines for that type of wallet (in this specific case, that would mean we assume LN channel states need to be backed up, somehow). Then, discussion of the "1% case" of an on-chain only wallet, which has simpler backup requirements, could be done as more of a footnote, or separate section at the end, or somewhere else.

@moneyball I updated the Figma file to include a new row frames showing the wallet backup section as LN first. Forgive the placeholder text.

See Figma File

As I start to think about things from a LN first perspective, I realize that an automated cloud backup basically becomes the only recommended solution for a good UX. Asking the user to manually backup LN channel state info would be tedious, especially if they use the LN everyday as we hope they do.

It might be worth rewording the automatic cloud backup section to the effect of "automated cloud backup is the preferred way to backup because of LN channel states ... manual backups are for specific situations, such as where a user does not manage their own channels or when backing up a layer 1 wallet".

[GBKS]

@sbddesign thanks for the mockup. My concern is that the page get super long. And I wonder if we can't modularize this a bit more. So just like we have a section that describes private key management techniques, we could have a section (or page) about backup techniques. Then the onboarding section (and other sections) would no longer have to explain that logic but only reference it, and be more focused on the user experience of that specific product. Does that make sense?

Overall, I think there's a point where we need to just start creating the content and adjust the structure as needed along the way.

[Bosch-0]

So just like we have a section that describes private key management techniques, we could have a section (or page) about backup techniques.

I brung this up awhile ago and think it makes sense to have a private key schemes and Backup schemes chapter. This approach would align with what I mentioned about having 'pieces' we then assemble into products above.

Then the onboarding section (and other sections) would no longer have to explain that logic but only reference it, and be more focused on the user experience of that specific product. Does that make sense?

+1, makes a lot more sense to me then the current structure imo. This is what I was going for with my 'pieces' structure also.

It would be great if there was some kind of file standard that included everything: mnemonic, descriptors, channel backups etc. most cloud backup options currently aren't very interoperable.

[pavlenex]

This is a good starting point for the Google Doc cc @danielnordh

[pavlenex]

The notes from Jam Session Call 13 can be a good structure for how we may want to identify what content to add to the guide

[Bosch-0]

We should pin this issue for more visibility, it's probably the main focus of our discussions / direction currently.

[pavlenex]

Closing this one in favour of #478