# Protocols

## Finance
Layer 1: Bitcoin on-chain
Layer 2: Bitcoin Lightning 
Layer 2+: LNBits

## Communication
NOSTR

### Resources
https://nostr.how
https://github.com/nostr-protocol/nips

## Notes on integration
NOSTR and Bitcoin lightning are closely integrated. Each NOSTR profile will have a lightning "zap" address that is likely to be `<username>@<domain>.<ext>`. We want users to be easily able to "zap" each other

### resources

[What are Zaps](https://nostr.how/en/zaps)

# Objective

The objective of this project is to make an app for a social network that serve people in a close physical community. This core tenets of this app are that it be made with FOSS so that it may easily be reproduced.

This app will be able to function on a LAN that is not connected to WAN.

We want this app to foster a strong social network that allows for easy exchange of value. On the server that hosts the application will be a NOSTR Relay which will be the database that stores any content. 

## Components

- LNBits Server
- LNBits User Web app
- Front end app designed for enhanced UX/UI

The vast majority of the backend will be handled by the LNBits stack. LNBits includes both a server that facilitates the exchange of value compatible with the lightning network. Technically, this would be described as layer 2+ in the context of Bitcoin. While it is fully compatible with the lightning network, it can also have internal payments that occur mostly at the database level.

LNBits has a collection of extensions that we will leverage in order to super-charge the user experience. When we make a user for a person, we will be creating an lnbits user. A user has access to their lnbits settings through the lnbits front end that is run in tandem with the lnbits server.

We will also create a UI that provides a streamlined experience for less technical users who do not need the level of control that the lnbits quasar web app provides. For this, we will be using Vue3, shadcn-vue (implying tailwind v4), vite, etc. This UI will focus on displaying the content in a visually pleasing way that also provides the ability to interact through their nostr profile. E.g., they can send messages to friends, purchase items from the nostr marketplace, exchange money with friends, etc


### LNBits Server + Extensions
  - NOSTR Relay
  - NOSTR Client
  - NOSTR Marketplace

# Features

- Newsfeed page with filters. E.g., Important Announcements, GenPop, Event notifications, etc
- Communal calendar page
- Communal Marketplace 
- Events Page (already present)

# User Experience Details

## Authentication & User Management
- User registration creates both LNBits user and NOSTR key-pair via LNBits API
- Keys stored securely, minimal technical exposure to users
- Simplified onboarding for non-technical users

## User Profiles
- **Displayed Info**: Avatar, username, display name, bio
- **Zap Address**: `<username>@<hostname>` format
- **Wallet Integration**: Show LNBits wallet balance
- **Future Features**: Badges and gamification elements

## Content & Interactions
- **Primary Content**: Moderator posts and automated system posts (e.g., event creation notifications)
- **User Actions**: Reply and react to existing content (limited user-generated content initially)
- **Real-time Updates**: WebSocket-based NOSTR client for live feed updates
- **Data Persistence**: Local storage for offline capability and improved UX

## Technical Architecture
- **PWA Deployment**: Mobile-optimized progressive web app
- **Network**: Functions on LAN without WAN dependency
- **API Integration**: All transactions through LNBits API
- **User Roles**: Admin/moderator/user permissions handled via LNBits

## Development Phases
**Phase 1 (Current Focus)**: Newsfeed and Events
**Phase 2 (Future)**: Marketplace integration  
**Phase 3 (Future)**: Location-aware features and maps

# Technical Integration Specifications

## Environment Variables
```
VITE_LNBITS_BASE_URL=http://localhost:5000  # LNBits server URL
VITE_NOSTR_RELAY_URL=ws://localhost:5000/nostrrelay/<relay-id>  # NOSTR relay WebSocket
VITE_HOSTNAME=localhost  # For zap addresses (username@hostname)
```

## LNBits API Integration Points

### User Management
- **Create User**: `POST /api/v1/user` - Creates LNBits user with NOSTR key-pair
- **Get User**: `GET /api/v1/user/{user_id}` - Retrieve user profile data
- **Update User**: `PUT /api/v1/user/{user_id}` - Update profile (avatar, username, display name, bio)

### Wallet Operations  
- **Get Wallet Balance**: `GET /api/v1/wallet` - Retrieve current wallet balance
- **Create Payment**: `POST /api/v1/payments` - Handle zap transactions
- **Payment Status**: `GET /api/v1/payments/{payment_hash}` - Check payment status

### NOSTR Integration
- **NOSTR Client Extension**: `/extensions/nostrclient` - Manages NOSTR connections and messaging
- **NOSTR Relay Extension**: `/extensions/nostrrelay` - Local relay for community content
- **WebSocket Connection**: Real-time event streaming via relay WebSocket

## UI/UX Component Architecture

### Main Navigation
- **Newsfeed** (tabs: All, Important, Events, General)
- **Events** (existing page, integrate with newsfeed notifications)  
- **Profile** (modal: user info, wallet balance, settings)

### Newsfeed Features
- Real-time WebSocket updates from NOSTR relay
- Visual priority system for Important Announcements
- Reply and reaction capabilities (zap, like, comment)
- Local storage for offline content persistence

### Zapping Interface
- Quick zap buttons (preset amounts: 10, 50, 100 sats)
- Custom amount modal for larger transactions
- Visual feedback for successful zaps
- Integration with LNBits payment API

### Profile Management
- Editable: avatar, username, display name, bio
- Read-only: zap address (username@hostname), wallet balance
- Future: badges and gamification elements

## Data Flow
1. **User Registration**: Vue app → LNBits API → NOSTR key-pair generation
2. **Content Publishing**: Moderator/System → NOSTR relay → WebSocket → Vue app
3. **User Interactions**: Vue app → LNBits API (payments) + NOSTR relay (social)
4. **Real-time Updates**: NOSTR relay WebSocket → Vue app state management

# NOSTR Event Types for Implementation

Based on NOSTR Improvement Proposals (NIPs), the following event types are relevant for our community app:

## Core Event Types

### User Profile (Kind 0 - NIP-01)
```json
{
  "kind": 0,
  "content": "{\"name\":\"username\", \"about\":\"bio text\", \"picture\":\"avatar_url\"}"
}
```
- **Usage**: User profile management
- **UI Components**: Profile modal, user avatar/name display

### Text Notes (Kind 1 - NIP-10)
```json
{
  "kind": 1,
  "content": "Post content text",
  "tags": [
    ["p", "pubkey", "relay_url"],  // mentions
    ["e", "event_id", "relay_url", "marker"]  // replies/threads
  ]
}
```
- **Usage**: Main newsfeed content, moderator announcements
- **UI Components**: Post display, reply threads

### Reactions (Kind 7 - NIP-25)
```json
{
  "kind": 7,
  "content": "+",  // or "-", or emoji
  "tags": [
    ["e", "target_event_id", "relay_url", "target_pubkey"],
    ["p", "target_pubkey", "relay_url"],
    ["k", "target_event_kind"]
  ]
}
```
- **Usage**: Like/dislike posts, emoji reactions
- **UI Components**: Reaction buttons, reaction counts

### Calendar Events (Kind 31922/31923 - NIP-52)
```json
{
  "kind": 31922,  // date-based events
  "content": "Event description",
  "tags": [
    ["d", "unique_identifier"],
    ["title", "Event Title"],
    ["start", "YYYY-MM-DD"],
    ["end", "YYYY-MM-DD"],
    ["location", "Event location"],
    ["p", "participant_pubkey", "relay_url", "role"]
  ]
}
```
- **Usage**: Community calendar, event announcements
- **UI Components**: Event cards, calendar integration, automatic newsfeed posts

## Lightning/Payment Events

### Zap Requests (Kind 9734 - NIP-57)
```json
{
  "kind": 9734,
  "content": "Zap message",
  "tags": [
    ["relays", "relay1", "relay2"],
    ["amount", "21000"],  // millisats
    ["p", "recipient_pubkey"],
    ["e", "target_event_id"]  // if zapping a post
  ]
}
```
- **Usage**: Lightning zap payments
- **UI Components**: Zap buttons, amount selection, payment confirmation

### Zap Receipts (Kind 9735 - NIP-57)
```json
{
  "kind": 9735,
  "content": "",
  "tags": [
    ["bolt11", "lightning_invoice"],
    ["description", "zap_request_json"],
    ["p", "recipient_pubkey"],
    ["e", "target_event_id"]
  ]
}
```
- **Usage**: Payment confirmation display
- **UI Components**: Zap success indicators, payment history

## Content Types for Future Implementation

### Long-form Content (Kind 30023 - NIP-23)
- **Usage**: Community announcements, detailed posts
- **Tags**: `title`, `summary`, `image`, `published_at`

### Marketplace Events (NIP-15)
- **Usage**: Community marketplace integration (Phase 2)

## Implementation Notes

### Event Filtering for Newsfeed Tabs
- **All**: Subscribe to kinds [0, 1, 7, 31922, 31923, 9735]
- **Important**: Filter by specific pubkeys (moderators) or tags
- **Events**: Filter specifically for kinds [31922, 31923] 
- **General**: Filter for kind 1 excluding moderator pubkeys

### WebSocket Subscription Filters
```json
{
  "kinds": [1, 7, 31922, 31923, 9735],
  "since": <timestamp>,
  "limit": 50
}
```

### Local Storage Schema
- Events by kind and timestamp
- User profiles by pubkey  
- Reaction counts by event_id
- Zap totals by event_id and recipient
