Savr - Lightning Savings Goals

Transparent Bitcoin savings goals on the Lightning Network. Create personal or collaborative goals with daily, weekly, or monthly targets. When a goal is reached, spend the collected sats directly from the app by paying any Lightning invoice.

Features

• Personal & Collaborative Goals — Save alone or pool funds with others
• Invite Codes — Collaborative goals are protected by a 6-character code shared by the creator
• Daily / Weekly / Monthly Targets — Flexible saving schedules
• Full Transparency — All contributions and contributor rankings are publicly visible
• Lightning Payments — Instant Bitcoin deposits via Lightning invoices + QR codes
• Real-time Progress — Payment detection with automatic progress bar updates
• Celebrate & Spend — When a goal is reached, pay out to any Lightning invoice directly from the app

Project Structure

project/
├── backend/
│   ├── app.py              # Flask API server (port 5001)
│   ├── models.py           # SQLite database models
│   ├── lnd_client.py       # LND REST API client
│   ├── polar_detect.py     # Polar auto-detection
│   └── requirements.txt    # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── api.js                      # API client functions
│   │   ├── App.jsx                     # Root component + routing
│   │   ├── App.css                     # Application styles
│   │   ├── components/
│   │   │   ├── Header.jsx              # App header with node status
│   │   │   ├── GoalCard.jsx            # Goal summary card
│   │   │   ├── PaymentModal.jsx        # Incoming invoice + QR modal
│   │   │   ├── CelebrationCard.jsx     # Shown when goal is reached
│   │   │   ├── SendModal.jsx           # Outgoing payment flow
│   │   │   ├── ContributorList.jsx     # Contributor leaderboard
│   │   │   └── ActivityFeed.jsx        # Recent contributions feed
│   │   └── pages/
│   │       ├── Dashboard.jsx           # Goals listing with filters
│   │       ├── CreateGoal.jsx          # New goal form + invite code reveal
│   │       └── GoalDetail.jsx          # Goal detail, contribute, send
│   ├── package.json
│   └── vite.config.js
├── .gitignore
└── README.md

Prerequisites

• Python 3.8+
• Node.js 18+
• Polar (Lightning Network simulator) or a live LND node

Setup

1. Backend

cd backend

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

# Install dependencies
pip install -r requirements.txt

# Start the API server
python app.py

The backend runs at http://127.0.0.1:5001. The SQLite database (savr.db) is created automatically on first run inside the backend/ folder.

2. Frontend

cd frontend

# Install dependencies
npm install

# Start the dev server
npm run dev

The frontend dev server runs at http://localhost:3000 and proxies API calls to the backend on port 5001.

To build for production:

npm run build
# Serve via the Flask backend at http://127.0.0.1:5001

3. LND Configuration

With Polar (recommended for development):

1. Install and open Polar
2. Create a network with an LND node named bob
3. Start the network
4. Savr auto-detects the node — no extra config needed

python app.py

## Usage

1. **Create a Goal** — Set a name, target (in sats), type (personal/collaborative), and saving frequency
2. **Share the Invite Code** — For collaborative goals, share the generated 6-character code with participants
3. **Contribute** — Enter your name and amount, scan the QR code or copy the invoice, pay from any Lightning wallet
4. **Track Progress** — Watch the progress bar fill and see the live contributor leaderboard
5. **Spend Sats** — Once the goal is reached, a celebration screen appears with a **Send Sats** button — paste any BOLT11 invoice to pay out

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/goals` | List all active goals |
| POST | `/api/goals` | Create a new goal |
| GET | `/api/goals/:id` | Get goal details + contributions |
| GET | `/api/goals/:id/contributors` | Contributor leaderboard |
| POST | `/api/goals/:id/verify_code` | Validate an invite code |
| POST | `/api/goals/:id/contribute` | Create a Lightning invoice for a contribution |
| POST | `/api/goals/:id/decode_invoice` | Decode a BOLT11 invoice (preview before sending) |
| POST | `/api/goals/:id/send` | Pay a BOLT11 invoice from the goal's funds |
| GET | `/api/check_payment/:r_hash` | Poll payment status |
| GET | `/api/node_info` | LND node info |