When designing bitcoin-backed ecash applications, it’s important to prioritize clear and intuitive interfaces that allow users to easily manage their tokens, whether minting, sending, or redeeming them.
Since ecash is still a relatively new technology this guide focuses on best practices for managing tokens and communicating mint and federation details. As the ecash ecosystem develops we encourage designers and developers to contribute their insights and help improveme this guide.
When displaying multiple mints or federations in a bitcoin-backed ecash application, there are several best practices to consider:
Clear hierarchy and organization: Ensure that mints or federations are organized in a way that is easy for users to navigate. Group mints by relevance, trust level, or frequency of use, and consider using sorting or filtering options to help users find the right mint or federation quickly.
Prominent metadata display: Use metadata fields like mint name, icon, URL, and description, to give users insight into each mint or federations identity. Display this information prominently, so users can easily verify the authenticity and relevance of each mint or federation.
Quick mint access: Provide easy access to mint or federation details directly from the mint or federation list. This allows users to interact with mints or federations more fluidly without needing to navigate through multiple screens.
It’s useful to display generated tokens in the payment history along with their status—whether pending or redeemed. While token is pending, anyone with the token string can claim it. This helps users quickly assess their payment status. Providing the ability to expand on a token to view details and take actions like resending or redeeming is also important. This feature becomes particularly valuable if a token was lost or never claimed.
When designing for Cashu, consider allowing users to set a default mint. Since Cashu mints are independently operated, users may prefer to use a trusted mint for their payments. By allowing them to select a default mint, you simplify their experience and reduce the risk of exposure to a potentially malicious mint. Additionally, consider offering auto-swap preferences.
It’s useful to provide users with the ability to manually update or refresh mint settings in their wallets. While best practices suggest that wallets should auto-refresh and update mint settings periodically, there may be cases where this isn’t supported, or a mint undergoes significant updates, such as a URL change. By allowing users to edit the mint URL or refresh settings manually, you ensure that users always have the latest mint configurations.
The Cashu backup and restoration process is designed to ensure users can securely recover their wallets and maintain access to their bitcoin-backed ecash tokens in the event they switch devices or experience data loss. Users should only use their recovery seed phrase once. Repeated use of the seed phrase for restoration can lead to synchronization issues and potential errors. This is due to the fact that each time you restore, you might be dealing with an outdated state of the wallet, which can cause discrepancies in token balances and payments.
Single Use Recovery
After successfully restoring your wallet using a recovery seed phrase, it is highly recommended that you generate a new recovery seed phrase immediately. This step is crucial because the original recovery phrase has now been used and could be more susceptible to synchronization risks.
Deterministic Wallet with Seed Phrase: Cashu uses a deterministic wallet model, where all cryptographic keys and bitcoin-backed ecash tokens can be derived from a single seed phrase. This seed phrase can be generated when the wallet is first created, or a at any point in time when the user wants to backup their wallet.
Secure Storage: Users are advised to store their seed phrase securely. It is crucial to keep this seed phrase in a safe, physical format (such as written on paper) and stored in a secure location to prevent unauthorized access or loss. The best practices in the Backup & recovery section also apply to Cashu wallets.
Mint Information Needed
Keep a record of the mints you are connected to. During the restoration process, you will need to reconnect to these specific mints to re-verify your tokens. Without this information, you will not be able to fully restore your wallet.
Seed Phrase Entry: When restoring a wallet, users enter their seed phrase into their wallet. This seed phrase regenerates secrets that may have been used to mint ecash.
Mint(s) Entry: Users must input the mint URL for each mint they used before. This ensures their wallet can properly reconnect and recreate their tokens.
Verification: The mint(s) checks these blinded secrets against its records to confirm if it has been seen before and can reissue the signature.
Privacy Considerations During Verification
Verifying tokens after restoration might temporarily compromise their privacy. The mint needs to revalidate the tokens, which can potentially expose the payment history associated with those tokens. Be mindful of this aspect if privacy is a significant concern for your use case.
NUT06 provides a standardized way to display metadata for Cashu mints. Incorporating these metadata fields makes your application more transparent and informative. Here’s a breakdown of each field and how it can be used in wallet design:
name: The name of the mint. Display this prominently in mint listings and details pages to help users quickly identify different mints.
version: Shows the implementation name and software version of the mint. Consider displaying this in the mint details to inform users about the mint’s current software status.
description: A short description of the mint. Consider displaying this in mint listings or as a subtitle under the mint name to give users a quick overview.
description_long: A more detailed description. This can be displayed on a dedicated mint information page or in an expandable section for users who want more details.
contact: An list of contact methods for the mint operator. Consider displaying this in the mint details, using appropriate icons for each contact method (e.g., nostr, email icon, website icon) to make it easy for users to reach out if needed.
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.
nuts: Indicates which NUT specifications the mint supports and their settings. Create a “Features” or “Capabilities” section in the mint details, translating technical NUT numbers into user-friendly feature descriptions.
Avoid Jargon & NUTs 01-06
When displaying NUTs (Notation, Usage, and Terminology) that a mint supports, avoid simply listing NUT01, NUT02, etc. Instead, provide users with clear descriptions of each NUTs functionality. This helps users understand the features and capabilities of the mint at a glance. Since NUTs 01-06 are mandatory for Cashu protocol interoperability, focus on optional NUTs that add unique functionality. Consider using the descriptions provided in the official documentation to keep the information accurate.
When designing your Cashu wallet, consider organizing these metadata fields in a logical, user-friendly manner to help users understand and interact with different mints. Here are some suggestions:
Use the name and short description in mint listings for quick identification of mints.
Display a detailed mint information page using description_long, version, and contact details.
Display the motd as a prominent notification when relevant to the specific mint.
Use the nuts information to create a features list that helps users understand each mint’s capabilities.
By effectively incorporating these Cashu metadata fields, you can create a more transparent and informative experience for users, helping them make informed decisions about which Cashu mints to trust and use. This is particularly important for Cashu, as users interact directly with individual mints rather than a federation structure like in Fedimint.
NUT11 is a powerful feature that allows bitcoin-backed ecash tokens to be securely locked to another user’s public key, which is generated by the recipient’s wallet. This ensures that only the intended recipient can redeem the ecash. NUT11 enables secure offline payments, preventing double-spending. Beyond these basics, NUT11 supports advanced use cases like timelocks and multisignature (multisig) setups, where ecash can be conditionally spent or jointly owned by multiple parties. When designing make sure these functionalities are clearly communicated to users, highlighting their practical benefits and flexibility.
P2PK ecash backup limitations
P2PK ecash tokens are not derived from a seed phrase. This means they cannot be backed up using a seed phrase, and in the event of a recovery from seed phrase the P2PK ecash tokens will be lost.
Wallets can provide the option to automatically swap ecash from an unknown mint to their default mint. This optional feature can simplify payments by routing all ecash through the assigned default mint. An auto-swap requires a lightning payment.
Auto-Swapping Involves Fees
It’s important to inform users that auto-swapping involves fees and that the amount depends on the amount of ecash they want to swap and the current network conditions.
Consider using a prominent, color-coded indicator to show the overall status of the federation. This should reflect whether the federation is fully operational, partially degraded, or offline. This helps users quickly assess the health of a federation.
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.
Privacy considerations in guardian information display #
Fedimint automatically generates random names for guardians during setup. While users can change these names, it’s not recommended. When displaying guardian information, consider using code names like “Guardian 1” and randomly generated identicons for each guardian. This helps protect user and federation privacy, particularly for invite-only mints. Guardian information should only be visible to users who have joined the federation.
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:
federation_name: This field provides the name of the federation. It should be displayed prominently in the federation overview to help users quickly identify which federation they are interacting with.
federation_expiry_timestamp: This field contains a timestamp indicating when the federation will shut down. It’s crucial to display this information clearly to users, possibly with a countdown or warning as the expiration date approaches.
welcome_message: This field contains a welcome message for new users joining the federation. It could be displayed during the onboarding process to provide users with important information or instructions.
Flexible Use of Welcome Message
Different federations may choose to display the welcome message in different contexts. Some may use it as a welcome message, others may use it to display the terms of service or other important information.
vetted_gateways: This field contains a list of gateway identifiers that have been vetted by the federation. This information could be used to display trusted gateways to users, helping them make informed decisions about which gateways to use for payments.
Displaying gateway information is not necessary. Users trust their applications to handle payments securely. Adding gateway information risks introducing unnecessary complexity.
When designing your Fedimint wallet interface, consider organizing these metadata fields in a logical, user-friendly manner to help users understand and interact with the federation. Here are some suggestions:
Display the federation_name prominently in the federation overview for quick identification.
Create a detailed federation information page incorporating the welcome_message and federation_expiry_timestamp, ensuring users are aware of important information and any time limitations.
Implement notifications or warnings based on the federation_expiry_timestamp to keep users informed about the federation’s lifespan.
By effectively incorporating these Fedimint metadata fields you can create a more transparent and informative experience for users, helping them understand the federation’s structure, rules, and trusted entities.