Add ecash section to guide #1093
Conversation
Introducing an ecash folder into the guide. This branch will be the working draft.
✅ Deploy Preview for bitcoin-design-site ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Removed old illustration. Added notes for future illustrations.
Added overview, cashu, and introduction page.
Thanks for the catch. I've updated this on my local environment and will update in the next commit. |
…R review session on September 5th, and feedback left on draft PR. Ecash Introduction Page: * Added a privacy bullet point explainer section to key benefits. * Updated copy beneath the protocol image to clarify the distinction between Fedimint and Cashu. * Included a brief explainer in the Ecash protocols section to further detail the differences between Fedimint and Cashu. * Updated the “Creating and Redeeming” ecash image. * Changed terminology in the “Creating and Redeeming” section to reflect more neutral terms (no longer Cashu protocol-specific). Included a terminology translation table detailing terms used for Cashu and Fedimint. * Updated the “Sending and Receiving” ecash image to include users "Alice, Carol, and David." Using Alice and Carol more closely matches the users named in the Cashu documentation. * Updated the “Bitcoin Custody Spectrum” graphic to show a distinction between Solo mints and Federated Mints. * Revised the “Ecash vs Custodial Lightning” comparison table. Replaced Ecash's red x under "Secure Against Theft (Rug Pulls)" with a yellow triangle, reflecting that multi-guardian federations storing user funds in multi-sig offer improved protection against rug pulls compared to custodial lightning. This is explained in the text below the table. * Updated navigation buttons with correct links per Daniel's recommendation. Cashu: * Updated Cashu Solo mint illustration. * Added Pros and Cons section beneath the Cashu mint explainer. * Included a sentence explaining that Cashu has a much smaller codebase compared to Fedimint under the "When to use Cashu" section. * Separated Cashu wallets and services into two lists. Fedimint: * Added a "Role of Guardians" section to explain what guardians are and what they do. * Added a "Role of Gateways" section to better explain how Gateways work and what Vetted Gateways are. * Updated federation illustrations for clarity. * Changed the name of "Unfederated Mints" to "Solo Mints" to match the terminology used in Cashu. * Separated Fedimint wallets and services into lists. * Added additional Fedimint resources and a link to the Awesome Fedimint GitHub repository.
|
Feedback provided on these these sections as per your request Erik: Second half of introduction page:
Design Best Practices:This page is packed with useful design info however there is a feeling as if the overall heading structure can be made a bit similar. If this is done the mind understands the topics under them a bit more. There are some commonalities in the headings: Design Best Practices1. General ecash best practices (remains as is)
Then there's 4 common headings for both Cashu and Fedimint
Cashu1. User Interface and Experience
2. Security and Privacy
3. Metadata and Information Management
4. Advanced Features
Fedimint Design Best Practices1. User Interface and Experience
2. Security and Privacy
3. Metadata and Information Management
4. Advanced Features
|
Thanks @mouxdesign, this is really helpful. In my local environment I've pushed these changes. I will push a commit this weekend once I update the images. With that, I think we'll be in a good place for the call next week! |
Updated layout and structure of design best practices along with Fedimint images.
Updated images with custom midjourney images for all sections.
There was a problem hiding this comment.
Review for design best practices page:
Another big page with important guidance, so great you're doing this. The header image is pretty cool!
Leaving comments & suggestions in-line as well but here are some big areas of feedback (do let me know if I'm wrong coz I don't know a lot about ecash mechanics):
- I'd like to see onboarding/setup, sending, receiving, minting and redeeming sections/screens/flows? (sorry if this already exists and I missed it)
- change Title Case to sentence case in section headings
- Suggestion: evaluate whether best practices may be better placed on the respective Cashu/Fedimint page since common best practices seem to be few and users are likely to be looking for guidance on one specific solution
- After reading the entire page, my guess there's a lot of scope for trimming content; I have added suggestions where I see opportunities
There was a problem hiding this comment.
Just went through the intro, cashu and fedimint pages and have a few recommendations. I'll tackle the design best practices page separately, as this review is already getting pretty big.
Not sure if you gotten around to that, but there are a lot of issues with images. Make sure to follow all the best practices we have around those. There are also some issues with the front matter (attributes at the top of markdown pages).
There are a handful of structural things, where I recommend moving content around a bit. I'd address (or ignore) those first before finessing.
I like the style of the header images. Is that your interpretation of David Chaum in 1983, coming up with ecash and dreaming of a future with digital money?
Hope the feedback is helpful.
| - /guide/ecash/introductions/ | ||
| - /guide/ecash/introduction/ | ||
| main_classes: -no-top-padding | ||
| image: https://bitcoin.design/assets/images/guide/how-it-works/ecash/ecash.jpg |
There was a problem hiding this comment.
Should be a custom JPG image (different from the banner) with 1200x630px size.
There was a problem hiding this comment.
Thanks! I updated this with a unique image. On what part of the site is this image referenced? I would like to see a preview of it if i can.
guide/how-it-works/ecash/fedimint.md
Outdated
| %} | ||
|
|
||
| # Fedimint | ||
| Fedimint is the first bitcoin-backed ecash protocol. Fedimint decentralizes trust across a federation of guardians, ensuring that no single guardian has complete control over user funds. Fedimint allows for various Federation configurations, each catering to different needs. These configurations include **Federated Mints**, **Federated Single Guardian Mints**, and **Solo Mints (Unfederated Mints)**, each with its strengths and trade-offs. |
There was a problem hiding this comment.
Surprised to see a mention of solo mints, since the previous pages made strong points about Fedimint being federated, and that Cashu was presented as the solo option...
There was a problem hiding this comment.
Can the configurations in bold be links for more info?
There was a problem hiding this comment.
Yes, Solomints are something I recently learned that Fedimint supports. They were created as an alternative to Cashu mints. In the first review call with the Fedimint developers, they referred to it as 'using a hammer to kill a fly,' since Fedimint is primarily designed for federated mints. However, in theory, you could use it for a solo mint if you wanted to, as the protocol does support it.
guide/how-it-works/ecash/fedimint.md
Outdated
| ## Role of Guardians | ||
| Guardians are participants who collaboratively manage a federations operations. They secure the federation's funds using multi-sig wallets, validate transactions through consensus, and control ecash issuance and redemption. | ||
|
|
||
| ## Role of Gateways |
There was a problem hiding this comment.
On the intro page, I mentioned that the illustration about connectivity using lighting felt out of place. It seems to fit well with this part about gateways. Isn't the gateway stuff generally a thing and maybe should not be in the fedimint page?
There was a problem hiding this comment.
‘Gateway’ is a term used only for Fedimint. It’s unique because it’s a separate service that a federation needs to set up in order to be lightning compatible. Cashu doesn’t use ‘gateway.’ To connect a lightning node on Cashu the user simply edits a mint setup file and plugs in some mint info, like an admin macaroon and TLS cert (at least for LND—other implementations may require different details). Since gateways aren’t relevant for Cashu, I didn’t include them in the introduction.
I agree that this illustration is great for visualizing the role of the gateway. I’ll modify it to show only Fedimint federations so it’s clearer that it’s a Fedimint-specific service enabling lightning and connecting federations to the lightning network.
|
|
||
| ### Federated Mints (4+ Guardians) | ||
|
|
||
| {% include picture.html |
There was a problem hiding this comment.
I don't understand this diagram. There's a lot going on and I can't really tell what each actor does. I don't think the arrows are enough. One solution could be to have numbers in circles on there, along with a legend or text explanation that references them. Or, break it down into multiple diagrams.
There was a problem hiding this comment.
I agree. I’d like to revisit the illustrations. I think it would be clearer to depict where each mint or federation is its own circle, and these federations are part of a larger circle representing the Fedimint protocol. The protocol circle would then be connected to the entire bitcoin network with dotted lines representing lightning or on-chain. I’m drawing inspiration from these examples.
There was a problem hiding this comment.
Just reviewed the design best practices page. Tons of great content there. The intro to the page is a bit rough as it does not provide a good table of contents, or entry point into what makes designing for Ecash unique. And it throws you right in to screens far down the user experience where the user already has multiple mints. Making that initial reading experience more gentle and guided should help quite a bit, IMHO.
Also keep in mind that we have a lot of existing content, especially in the daily spending wallet, you can refer to and build on. Especially around activity, sending, and receiving.
I am slightly wondering if isn't best to put the Cashu design stuff on the cashu page and the Fedimint design stuff on the Fedimint page. A reason is that those pages explain unique aspects of the protocols, and the designs build on those things. One thing leads to the other, but they are on separate pages now. I am sure you have also thought about this...
|
|
||
| <div class="glossary-toc" markdown="1"> | ||
| * Table of contents | ||
| {:toc} |
There was a problem hiding this comment.
I think the table of contents should include individual user flows like "Joining a mint", "Sending ecash", etc.
There was a problem hiding this comment.
Do you have a guide or example on how to customize the table of contents and link it to specific sections? It seems to automatically display whatever is marked as ## or H2, but I’d like to create my own shortcuts.
|
|
||
| --- | ||
| ## General Ecash Best Practices | ||
| When designing bitcoin-backed ecash applications it's important to prioritize clear and intuitive interfaces that allow users to easily manage their tokens, whether they are minting, sending, or redeeming them. |
There was a problem hiding this comment.
I think it would be helpful to provide some context on what's on this page and what isn't. For example, I was expecting sending and receiving (essential activities), but there is almost no mention of that. That can be totally fine if it's pretty much the same as what we have in the lightning wallet reference design. But I think it might be good to prime people before they dig in.
There was a problem hiding this comment.
How about a note that Ecash is super new and UX is still evolving as the tech is maturing? And ask people to contribute, etc?
There was a problem hiding this comment.
I want to include something more explicit that mentions the sending practices are the same as those in the existing reference wallet design. Guidelines like entering an amount, displaying fees, and showing a success message still apply. However the key difference is that ecash wallets allow users to generate a payment in the form of an ecash token, which can be shared as a QR code or a string of text. It might be enough to mention this in the text, though I could include an image of a QR code with its text string underneath to show an example. But this image is already shown in the pending tokens section right below.
| ## General Ecash Best Practices | ||
| When designing bitcoin-backed ecash applications it's important to prioritize clear and intuitive interfaces that allow users to easily manage their tokens, whether they are minting, sending, or redeeming them. | ||
|
|
||
| ### Multiple Mint or Federation Display |
There was a problem hiding this comment.
I would start this page at the point where the user encounters a mint for the first time, maybe during onboarding. That first impression/interaction will be the layup for everything that happens afterwards. You could speak to how onboarding discusses mints, risks, etc. We need to teach both the end user and the reader step-by-step.
When I see a fully populated federation list screen right off the bat, I instantly have a lot of questions. How did I get here? What is a federation? Do most users have multiple mints? For what use cases?
For mint/federation display, you can also speak to the relationship the user has to them. Those are the custodians that hold your money. You have to trust them, and you want full transparency from them. They are also a bit like accounts that you may want to balance. With that in mind it's easier to derive design guidelines.
| - file: cashu-id1 | ||
| modalImage: cashu-id1@2x | ||
| alt: Mint identity and version display in a wallet interface | ||
| caption: Consider the most important information to display to the user about the mint. |
There was a problem hiding this comment.
What is the "Pubkey" field. Does not seem like something a casual user can make sense of.
There was a problem hiding this comment.
A version number is also only helpful to highly technical users. Contact info seems more relevant.
There was a problem hiding this comment.
Pubkey is not yet used, but it’s in the spec so it needs to be removed. Initially when I included the metadata fields for both Fedimint and Cashu I wanted to provide UI examples showing all the metadata fields the protocol supports. Buit as you pointed out, not all metadata fields are equally important. Some are crucial while some are only relevant to technical users. I will revisit this section and mention this distinction. I’ll focus on UI examples that display the most relevant metadata fields for design, and then include a paragraph about the other fields.
I'll note that while they may be useful for technical users, they are likely irrelevant for most users. It’s best to carefully consider whether or not to include these fields based on your product’s target audience.
| caption = "A message of the day can consists of anything the mint operator wants to tell the user. It can for example be used to announce a new feature or a upcoming maintenance." | ||
| %} | ||
|
|
||
| - `motd` (Message of the Day): Used for important announcements. Consider displaying this in a prominent, dismissible notification area when users interact with the mint, making sure they don't miss any critical information. |
There was a problem hiding this comment.
There could also be a small notification icon on the home screen.
| caption: A message of the day can consists of anything the mint operator wants to tell the user. It can for example be used to announce a new feature or a upcoming maintenance. | ||
| - file: cashu-id5 | ||
| modalImage: cashu-id5@2x | ||
| alt: Example of supported features display in a wallet interface |
There was a problem hiding this comment.
Seems only useful for highly technical people. Can some of those be actions I can perform? Can I do a "Token state check" if that mint supports that feature?
There was a problem hiding this comment.
Yes, token state check is an action users can perform if the mint supports it. It’s quite useful because it allows you to quickly update your token status list without having to re-check each individual token. In eNuts this feature is called ‘check proofs.’ P2PK and multimint payments are also unique actions but no wallet supports multimint payments yet. To your point, listing all of this is probably not useful for most regular users so I’ll remove it.
|
|
||
| ### User Interface and Experience | ||
|
|
||
| #### Federation Status Display |
There was a problem hiding this comment.
Does Cashu not have that feature? Might be good to explain that.
There was a problem hiding this comment.
Since cashu is a single mint there is no real status it is either up and working or not, where as a fedimint could have a minatory of guardians down ans still work in a degraded state.
Cashu does have a message of the day so it could publish a message thats its lightning node is temporarily down so minting and melting is not possible but you can still swap and funds are safe but there isnt a specific spec for this and it would just be a general message so don't think I would include that here
|
|
||
| #### Why Showing Gateway Information Might Not Be Necessary: | ||
|
|
||
| 1. **Cognitive Overload**: Most users are not interested in the technical details of how their transactions are processed. Presenting information about gateways, especially vetted versus non-vetted ones, could lead to confusion, as users may not understand what this information means or how to act on it. |
There was a problem hiding this comment.
How about showing something about vetted gateways at the point they become relevant to users? I do think people care, but it doesn't have to be front-loaded or too in-your-face.
There was a problem hiding this comment.
I'll have to find out at what point they become relevant to users. I can't think of one. @elsirion any thoughts?
Removed unused images, updated copy, changed layouts. Addressed a lot of feedback on the existing PR. Biggest changes were made to the introduction page.
|
|
||
| **2. Token Creation** - Upon successful payment, the wallet generates secrets and blinds them. The wallet then sends the blinded messages to the mint or federation, which returns a blind signature on the blinded messages. The blinding process ensures that the mint cannot link the tokens to the user, preserving privacy. | ||
|
|
||
| **3. Token Receipt** - The user receives a set of secrets (a cryptographic value that represents ownership of a specific amount of bitcoin) that correspond to specific amounts of sats. These secrets can be combined to create an ecash token of any amount denominated in bitcoin. |
There was a problem hiding this comment.
I don't think we should use secrets here. The user does not receive secrets from the mint as the user is the once that generates the secrets as stated in the paragraph before, point 2.
|
|
||
| **1. User Deposits Funds** - The user deposits bitcoin into a mint or federation. Typically this is done by generating a Lightning invoice through the mint and paying it. | ||
|
|
||
| **2. Token Creation** - Upon successful payment, the wallet generates secrets and blinds them. The wallet then sends the blinded messages to the mint or federation, which returns a blind signature on the blinded messages. The blinding process ensures that the mint cannot link the tokens to the user, preserving privacy. |
There was a problem hiding this comment.
| **2. Token Creation** - Upon successful payment, the wallet generates secrets and blinds them. The wallet then sends the blinded messages to the mint or federation, which returns a blind signature on the blinded messages. The blinding process ensures that the mint cannot link the tokens to the user, preserving privacy. | |
| **2. Token Creation** - Upon successful payment, the wallet generates secrets and blinds them. The wallet then sends the blinded messages to the mint or federation, which returns blind signatures on the blinded messages. The blinding process ensures that the mint cannot link the tokens to the user, preserving privacy. |
To me the other wording implied it was one signature across all the blinded messages where it is one for each.
There was a problem hiding this comment.
Thanks! Just updated.
There was a problem hiding this comment.
For point 3. What do you think about:
**3. Token receipt** - The user receives a set of proofs that correspond to specific amounts of bitcoin. These proofs can be combined to create an ecash token of any amount denominated in bitcoin.
I'm not sure about the labeling of this step. "Token receipt". I don't think the user receives a token in this process. Is it correct to say they receive a set of proofs?
Co-authored-by: Max <[email protected]>
Co-authored-by: Max <[email protected]>
Co-authored-by: Max <[email protected]>
Added commit suggestions from yashrajd and GBKS. Co-authored-by: Christoph Ono <[email protected]> Co-authored-by: Max <[email protected]>
Fixed formatting issue currently causing the checks to fail.
Small copy updates to fedimint gateway best practices section.
guide/how-it-works/ecash/fedimint.md
Outdated
| %} | ||
|
|
||
| # Fedimint | ||
| Fedimint is the first bitcoin-backed ecash protocol. Fedimint decentralizes trust across a federation of guardians, ensuring that no single guardian has complete control over user funds. Fedimint allows for various Federation configurations, each catering to different needs. These configurations include **Federated mints**, **Federated single guardian mints**, and **Solo mints (Unfederated mints)**, each with its strengths and trade-offs. |
There was a problem hiding this comment.
Notes from offline discussion: The distinction between federated, federated-single-guardian, and solo mints is an implementation detail. The user should make sure they have vetted the federation, should be able to view important metrics such as historical uptime, total lifespan, and recommendations/reviews from other users. Details such as the number of guardians are easily gamed.
guide/how-it-works/ecash/fedimint.md
Outdated
| Fedimint is the first bitcoin-backed ecash protocol. Fedimint decentralizes trust across a federation of guardians, ensuring that no single guardian has complete control over user funds. Fedimint allows for various Federation configurations, each catering to different needs. These configurations include **Federated mints**, **Federated single guardian mints**, and **Solo mints (Unfederated mints)**, each with its strengths and trade-offs. | ||
|
|
||
| ## Role of guardians | ||
| Guardians are participants who collaboratively manage a federations operations. They secure the federation's funds using multi-sig wallets, validate payments through consensus, and control ecash issuance and redemption. |
guide/how-it-works/ecash/fedimint.md
Outdated
|
|
||
| ## Role of gateways | ||
|
|
||
| {% include picture.html |
There was a problem hiding this comment.
Notes from offline discussion: The graphic here could convey so much more information. I'd include the following:
- A gateway that serves multiple federations
- A gateway that serves a single federation
- A gateway with a lightning channel directly connected to another gateway
- A federation that is served by multiple gateways
We should also differentiate between real lightning channels and gateway<->federation connections
guide/how-it-works/ecash/fedimint.md
Outdated
| layout = "full-width" | ||
| %} | ||
|
|
||
| A gateway is a service that facilitates interactions between the federation (which operates largely off-chain) and the lightning network. A gateway acts as a bridge, enabling users within the federation to make payments to and receive payments on the lightning network. |
There was a problem hiding this comment.
I would get rid of "which operates largely off-chain". Maybe instead you could add a paragraph about why gateways are necessary, describing that without them, users could only operate entirely off-chain when transacting with other users within the same federation (through direct ecash swaps).
guide/how-it-works/ecash/fedimint.md
Outdated
|
|
||
| A gateway is a service that facilitates interactions between the federation (which operates largely off-chain) and the lightning network. A gateway acts as a bridge, enabling users within the federation to make payments to and receive payments on the lightning network. | ||
|
|
||
| **How gateways work**: The gateway accepts bitcoin payments on the lightning Network and converts them into the bitcoin-backed ecash tokens used within the federation. It can also convert bitcoin-backed ecash tokens into bitcoin and send them over the lightning network. This is crucial because it allows the users within a federation to interact with the outside bitcoin and lightning network. |
There was a problem hiding this comment.
Nit: "lightning Network" -> "lightning network"
guide/how-it-works/ecash/fedimint.md
Outdated
|
|
||
| **How gateways work**: The gateway accepts bitcoin payments on the lightning Network and converts them into the bitcoin-backed ecash tokens used within the federation. It can also convert bitcoin-backed ecash tokens into bitcoin and send them over the lightning network. This is crucial because it allows the users within a federation to interact with the outside bitcoin and lightning network. | ||
|
|
||
| **Vetted gateways**: A vetted gateway is one that has been approved by the federation's guardians as reliable and trustworthy. This vetting process helps to ensure that users' payments are handled by gateways that have a track record of reliability, reducing the likelihood of payment failures. |
There was a problem hiding this comment.
The concept of unvetted gateways is being removed in the LNv2 module. All gateways will be vetted, since although they can be trusted to not steal user funds, they still must be trusted to provide a good user experience by routing quickly and not maliciously locking up funds in-flight. LNv2 won't be used until fedimint v0.6 (at least 3 months out) so it might be fine to just remove this - use your own discretion.
|
|
||
| <div class="center" markdown="1"> | ||
|
|
||
| {% include picture.html |
There was a problem hiding this comment.
The federation as a whole could be online, degraded, or offline. However, each guardian is either online or offline.
| #### Guardian Status Indicators | ||
| {% include image-gallery.html pages = page.images_guardian-status %} | ||
|
|
||
| Consider displaying real-time indicators of each guardian's status, such as the connection status and last activity. This information builds trust by keeping users informed about the reliability and performance of the guardians managing their funds. |
There was a problem hiding this comment.
"Last active" doesn't make sense for online guardians. For offline guardians, "last active" could indicate the last time that the client has seen the guardian online.
There was a problem hiding this comment.
Updated so "last active" is only visible for offline guardians.
|
|
||
| ### Security and privacy | ||
|
|
||
| #### Privacy considerations in guardian information display |
|
|
||
| #### Federation metadata fields: Explanation and usage | ||
|
|
||
| Federations can provide configuration and metadata to users. These metadata fields are consensus-relevant, meaning they must be consistent across all federation members. This ensures that users can rely on their accuracy. Let's explore the core metadata fields defined in the Fedimint protocol: |
There was a problem hiding this comment.
Can we link to the fedimint documentation here?
https://github.com/fedimint/fedimint/blob/master/docs/meta_fields/README.md
| - file: federation-guardian-expiry | ||
| modalImage: federation-guardian-expiry@2x | ||
| alt: A mobile wallet interface with a screen that shows a countdown timer and a message that the federation will shut down in 15 days. | ||
| caption: Federation expiration timestamp displayed as a countdown alter when less 30 days remaining. |
There was a problem hiding this comment.
Nit: "alter" -> "alert"
Also it would be useful for federations to be able to extend their expiration time (i.e. they're promising to not shut down before a certain date, but not promising that they will definitely shut down at that date. They might tack on more time later)
…ration illustrations, updated design best practices page to include user onboarding, mint connection, and mint discovery.
Hey @GBKS @mouxdesign @danielnordh.
I am working on the ecash section for the design guide. I have some foundations laid down and would like to submit a Draft PR so I can preview it in a test environment.
I would like to keep pushing changes to the draft PR regularly as I will be adding illustrations, updating copy, moving things around etc...
I'm still rather new to this process so please let me know what are the best practices here.
Preview