makeprisms / boardwalkcash

Boardwalk Cash

A Lightning / Cashu Ecash wallet designed for fast easy onboarding and use

Table of Contents

• Features
• Getting Started
• Prerequisites
• Installation
• Architecture
• Contributing
• License
• Contact
• Acknowledgements

Features

• Lightning Integration: Send and Receive Lightning payments.
• Cashu Ecash Wallet: Store balance locally as e-cash while at rest.
• Lightning Address: Receive payments using an auto-generated Lightning Address.
• Nostr Wallet Connect: Initiate payments from apps using NWC (NIP-47)
• Nostr Wallet Authentication: Seamlessly create app connections with NWA (NIP-67)
• Prism Payments: Use NWC to pay multiple invoices at once

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

Before you begin, ensure you have the following tools installed and running:

• Docker
• Docker Compose
• Node.js

Installation

1. Clone the repository:

   git clone https://github.com/your-username/boardwalkcash.git
   

2. Navigate to the project directory:

   cd boardwalkcash
   

3. Use Docker Compose to build and run the containers:

   docker-compose up --build

Architecture

Frontend

• Framework: Built with Next.js and TypeScript.
• Pages:
  • index.tsx: The main page for the app. Starts up top level hooks and reads in proofs from localstorage
  • connect.tsx: Reads in query params to connect with the apps using NWA
• Components:
  • Balance: Displays sat/usd balance
  • ActivityIndicator: Controls the user messaging which appears between balance and buttons
  • buttons/lightning: Contains send and receive buttons for making Lightning payments
  • SendModal: UI / state for Lightning send flow
  • ClipboardButton: for copying to clipboard
  • EcashButtons: Currently in development
• Hooks: Custom React hooks for managing state and side effects.
  • useCashu: Handles all of the calls to cashu mint and cashu-ts library. Reads/Writes to localstorage for handling proofs
  • useNwc: Subscribes to and handles NWC requests and prism payments.
• State Management: Global state management using Redux Toolkit.
  • store.ts: Redux Toolkit store for global state management
  • slices/ActivitySlice.ts: managing activity state
  • slices/CashuSlice.ts: managing cashu state
  • slices/UserSlice.ts: managing user state
• LocalStorage: for persisting user data and allowing user to self custody ecash proofs.
  • localStorage is being called for reads/writes across the app. This is used to store the user's proofs.
  • We are currently working on a more consistent and centralized way to handle this.

Backend

• API Endpoints: RESTful API endpoints facilitating lud16, crud operations on the db, and mint operations such as paying invoices, creating invoices, and checking/exchanging proofs with the mint.
  • /api/callback: lud16 callback
  • /api/invoice/polling: Polls mint for invoices waiting to be paid.
  • /api/cron/invoice: Once above polling times out, this cron job check every minute for not-expired invoices
  • /api/lnurlp: lud16 lnurlp flow for paying invoices
  • /api/proofs: CRUD operations for the user's proofs
  • /api/users: CRUD operations for the user's data
  • /api/quotes: CRUD operations for managing quotes we need to keep track of
• Database: PostgreSQL database, managed using Prisma ORM.

Docker Integration

• Docker Containers: Next.js app and database are containerized.
• Docker Compose: orchestrates the deployment.

NOTE: You may run only the database with docker and use your local Node.js environment for running the Next.js app, if you so choose.

Contributing

Any contributions you make are greatly appreciated.

• Fork the Project
• Create your Feature Branch (git checkout -b feature/AmazingFeature)
• Commit your Changes (git commit -m 'Add some AmazingFeature')
• Push to the Branch (git push origin feature/AmazingFeature)
• Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

• https://github.com/gudnuf
• https://github.com/austinkelsay

Project Link: https://github.com/makeprisms/boardwalkcash

Acknowledgements

• The Cashu Ecosystem
• Cashu-TS
• Calle
• Egge

boardwalkcash's Issues

Error minting tokens that exceed stablenut.umint.cash's reserves

Minting tokens that exceed the reserves in the stablenut.umint.cash mint results in a loss of funds.

A wallet is able to request a mint quote (/v1/mint/quote/bolt11 ) for an amount greater than the remaining reserves, thereby receiving an invoice from the mint. When the wallet user pays the invoice, the request to mint tokens (/v1/mint/bolt11) fails with the following error:

The user successfully paid the mint, but no tokens were issued in exchange.

The stablenut.umint.cash mint should instead throw an error at the time the wallet requests the mint quote so that the user never receives an invoice they can pay.

Bug: requires refresh to use nwc connection after creating it

Failed to create mint quote when trying to mint tokens after paying an invoice

I clicked "receive" and then paid the invoice, and then it failed to mint the tokens.

Token checkstate on receive

Currently, if a user tries to claim an already claimed token it will wait to fail until they click "Claim". There should be a call to mint (/v1/checkstate) to show the user the token has been claimed as soon as it loads.

"Add Top Mint" button on add mint page

Separate NWC and Cashu logic into their respective hooks.

Right now there is a lot of Cashu related logic occurring in useNwc.ts, to whatever extent is possible, only nwc logic should exist in the nwc hook

Update Claim flow to remove modal

Remove modal and just claim when you click "Claim". No need for a warning in this flow.

Refreshing browser makes tokens not available

What happened

I created a token to send it, but I refreshed while the wallet was creating the token.
Not having the token makes the money disappear.

Expected behaviour

Having also the entries about unspent tokens in the transactions list.

Only allow 2 decimals on amount inputs

Differentiate between offline payments, and prism payments

If the wallet is offline, and multiple payment requests are made, then the wallet comes online, and all these events will be processed as a prism.

Instead, there should be a time when the wallet first comes online, that any offline payments are processed individually.