aiolabs/nostrmarket
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 1 Packages Wiki Activity Actions

Merge branch 'main' into feature/update-icon

Browse source
This commit is contained in:
Arc 2025-12-24 03:31:02 +00:00 • committed by GitHub
commit 9bdc54e57a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 362 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.gitignore vendored
View file

@ -22,4 +22,7 @@ node_modules
*.swp
*.pyo
*.pyc
*.env
*.env
# Claude Code config
CLAUDE.md

104
CLAUDE.md Normal file
View file

@ -0,0 +1,104 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
Nostr Market is an LNbits extension implementing NIP-15 (decentralized marketplace protocol) on Nostr. It enables merchants to create webshops (stalls) and sell products with Lightning Network payments, featuring encrypted customer-merchant communication via NIP-04.
**Prerequisites:** Requires the LNbits [nostrclient](https://github.com/lnbits/nostrclient) extension to be installed and configured.
## Common Commands
All commands are in the Makefile:
```bash
make format # Run prettier, black, and ruff formatters
make check # Run mypy, pyright, black check, ruff check, prettier check
make test # Run pytest with debug mode
make all # Run format and check
```
Individual tools:
```bash
make black # Format Python files
make ruff # Check and fix Python linting
make mypy # Static type checking
make pyright # Python static type checker
make prettier # Format JS/HTML/CSS files
```
## Local Development Setup
To run checks locally, install dependencies:
```bash
# Install Python autotools dependencies (needed for secp256k1)
sudo apt-get install -y automake autoconf libtool
# Install Python dependencies
uv sync
# Install Node dependencies (for prettier)
npm install
# Run all checks
make check
```
## Architecture
### Core Layers
1. **API Layer** (`views_api.py`) - REST endpoints for merchants, stalls, products, zones, orders, direct messages
2. **Business Logic** (`services.py`) - Order processing, Nostr event signing/publishing, message routing, invoice handling
3. **Data Layer** (`crud.py`) - Async SQLite operations via LNbits db module
4. **Models** (`models.py`) - Pydantic models for all entities
### Nostr Integration (`nostr/`)
- `nostr_client.py` - WebSocket client connecting to nostrclient extension for relay communication
- `event.py` - Nostr event model, serialization, ID computation (SHA256), Schnorr signatures
### Background Tasks (`__init__.py`, `tasks.py`)
Three permanent async tasks:
- `wait_for_paid_invoices()` - Lightning payment listener
- `wait_for_nostr_events()` - Incoming Nostr message processor
- `_subscribe_to_nostr_client()` - WebSocket connection manager
### Frontend (`static/`, `templates/`)
- Merchant dashboard: `templates/nostrmarket/index.html`
- Customer marketplace: `templates/nostrmarket/market.html` with Vue.js/Quasar in `static/market/`
- Use Quasar UI components when possible: https://quasar.dev/components
### Key Data Models
- **Merchant** - Shop owner with Nostr keypair, handles event signing and DM encryption
- **Stall** - Individual shop with products and shipping zones (kind 30017)
- **Product** - Items for sale with categories, images, quantity (kind 30018)
- **Zone** - Shipping configuration by region
- **Order** - Customer purchases with Lightning invoice tracking
- **DirectMessage** - Encrypted chat (NIP-04)
- **Customer** - Buyer profile with Nostr pubkey
### Key Patterns
- **Nostrable Interface** - Base class for models convertible to Nostr events (`to_nostr_event()`, `to_nostr_delete_event()`)
- **Parameterized Replaceable Events** - Stalls (kind 30017) and Products (kind 30018) per NIP-33
- **AES-256 Encryption** - Customer-merchant DMs use shared secret from ECDH
- **JSON Meta Fields** - Complex data (zones, items, config) stored as JSON in database
### Cryptography (`helpers.py`)
- Schnorr signatures for Nostr events
- NIP-04 encryption/decryption
- Key derivation and bech32 encoding (npub/nsec)
## Workflow
- Always check GitHub Actions after pushing to verify CI passes
- Run `make check` locally before pushing to catch issues early

11
static/components/shipping-zones.js
View file

@ -19,7 +19,6 @@ window.app.component('shipping-zones', {
currencies: [],
shippingZoneOptions: [
'Free (digital)',
'Flat rate',
'Worldwide',
'Europe',
'Australia',
@ -27,6 +26,7 @@ window.app.component('shipping-zones', {
'Belgium',
'Brazil',
'Canada',
'China',
'Denmark',
'Finland',
'France',
@ -34,8 +34,8 @@ window.app.component('shipping-zones', {
'Greece',
'Hong Kong',
'Hungary',
'Ireland',
'Indonesia',
'Ireland',
'Israel',
'Italy',
'Japan',
@ -59,10 +59,9 @@ window.app.component('shipping-zones', {
'Thailand',
'Turkey',
'Ukraine',
'United Kingdom**',
'United States***',
'Vietnam',
'China'
'United Kingdom',
'United States',
'Vietnam'
]
}
},

243
templates/nostrmarket/_api_docs.html
View file

@ -1,44 +1,213 @@
<q-card>
<q-card-section>
<p>
Nostr Market<br />
<small>
Created by,
<q-expansion-item
icon="help_outline"
label="What is Nostr?"
header-class="text-weight-medium"
>
<q-card>
<q-card-section class="text-body2">
<p>
<strong>Nostr</strong> (Notes and Other Stuff Transmitted by Relays) is
a decentralized protocol for censorship-resistant communication. Unlike
traditional platforms, your identity and data aren't controlled by any
single company.
</p>
<p class="q-mb-none">
Your Nostr identity is a cryptographic key pair - a public key (npub)
that others use to find you, and a private key (nsec) that proves you
are you. Keep your nsec safe and never share it!
</p>
</q-card-section>
</q-card>
</q-expansion-item>
<q-expansion-item
icon="flag"
label="Getting Started"
header-class="text-weight-medium"
>
<q-card>
<q-card-section class="text-body2">
<p><strong>1. Generate or Import Keys</strong></p>
<p class="q-mb-md">
Create a new Nostr identity or import an existing one using your nsec.
Your keys are used to sign all marketplace events.
</p>
<p><strong>2. Create a Stall</strong></p>
<p class="q-mb-md">
A stall is your shop. Give it a name, description, and configure
shipping zones for delivery.
</p>
<p><strong>3. Add Products</strong></p>
<p class="q-mb-md">
List items for sale with images, descriptions, and prices in your
preferred currency.
</p>
<p><strong>4. Publish to Nostr</strong></p>
<p class="q-mb-none">
Your stall and products are published to Nostr relays where customers
can discover them using any compatible marketplace client.
</p>
</q-card-section>
</q-card>
</q-expansion-item>
<q-expansion-item
icon="storefront"
label="For Merchants"
header-class="text-weight-medium"
>
<q-card>
<q-card-section class="text-body2">
<p>
<strong>Decentralized Commerce</strong> - Your shop exists on Nostr
relays, not a single server. No platform fees, no deplatforming risk.
</p>
<p>
<strong>Lightning Payments</strong> - Accept instant, low-fee Bitcoin
payments via the Lightning Network.
</p>
<p>
<strong>Encrypted Messages</strong> - Communicate privately with
customers using NIP-04 encrypted direct messages.
</p>
<p>
<strong>Portable Identity</strong> - Your merchant reputation travels
with your Nostr keys across any compatible marketplace.
</p>
<p class="q-mb-none">
<strong>Global Reach</strong> - Your stalls and products are
automatically visible on any Nostr marketplace client that supports
NIP-15, including Amethyst, Plebeian Market, and others.
</p>
</q-card-section>
</q-card>
</q-expansion-item>
<q-expansion-item
icon="shopping_cart"
label="For Customers"
header-class="text-weight-medium"
>
<q-card>
<q-card-section class="text-body2">
<p>
<strong>Browse the Market</strong> - Use the Market Client to discover
stalls and products from merchants around the world.
</p>
<p>
<strong>Pay with Lightning</strong> - Fast, private payments with
minimal fees using Bitcoin's Lightning Network.
</p>
<p class="q-mb-none">
<strong>Direct Communication</strong> - Message merchants directly via
encrypted Nostr DMs for questions, custom orders, or support.
</p>
</q-card-section>
</q-card>
</q-expansion-item>
<q-expansion-item
icon="people"
label="Contributors"
header-class="text-weight-medium"
>
<q-card>
<q-card-section class="text-body2">
<p class="q-mb-sm">This extension was created by:</p>
<div class="q-gutter-sm">
<a
class="text-secondary"
target="_blank"
style="color: unset"
href="https://github.com/talvasconcelos"
>Tal Vasconcelos</a
>
<a
class="text-secondary"
target="_blank"
style="color: unset"
href="https://github.com/benarc"
>Ben Arc</a
class="text-decoration-none"
>
<q-chip clickable icon="person">Tal Vasconcelos</q-chip>
</a>
<a
class="text-secondary"
href="https://github.com/arcbtc"
target="_blank"
style="color: unset"
class="text-decoration-none"
>
<q-chip clickable icon="person">Ben Arc</q-chip>
</a>
<a
href="https://github.com/motorina0"
>motorina0</a
></small
>
</p>
<a
class="text-secondary"
target="_blank"
href="/docs#/nostrmarket"
class="text-white"
>Swagger REST API Documentation</a
>
</q-card-section>
<q-card-section>
<a class="text-secondary" target="_blank" href="/nostrmarket/market"
><q-tooltip>Visit the market client</q-tooltip
><q-icon name="storefront" class="q-mr-sm"></q-icon>Market client</a
>
</q-card-section>
</q-card>
target="_blank"
class="text-decoration-none"
>
<q-chip clickable icon="person">motorina0</q-chip>
</a>
<a
href="https://github.com/BenGWeeks"
target="_blank"
class="text-decoration-none"
>
<q-chip clickable icon="person">Ben Weeks</q-chip>
</a>
</div>
</q-card-section>
</q-card>
</q-expansion-item>
<q-separator></q-separator>
<q-item clickable tag="a" target="_blank" href="/nostrmarket/market">
<q-item-section avatar>
<q-icon name="storefront" color="primary"></q-icon>
</q-item-section>
<q-item-section>
<q-item-label>Market Client</q-item-label>
<q-item-label caption>Browse and shop from stalls</q-item-label>
</q-item-section>
<q-item-section side>
<q-icon name="open_in_new" size="xs"></q-icon>
</q-item-section>
</q-item>
<q-item clickable tag="a" target="_blank" href="/docs#/nostrmarket">
<q-item-section avatar>
<q-icon name="api" color="primary"></q-icon>
</q-item-section>
<q-item-section>
<q-item-label>API Documentation</q-item-label>
<q-item-label caption>Swagger REST API reference</q-item-label>
</q-item-section>
<q-item-section side>
<q-icon name="open_in_new" size="xs"></q-icon>
</q-item-section>
</q-item>
<q-item
clickable
tag="a"
target="_blank"
href="https://github.com/nostr-protocol/nips/blob/master/15.md"
>
<q-item-section avatar>
<q-icon name="description" color="secondary"></q-icon>
</q-item-section>
<q-item-section>
<q-item-label>NIP-15 Specification</q-item-label>
<q-item-label caption>Nostr Marketplace protocol</q-item-label>
</q-item-section>
<q-item-section side>
<q-icon name="open_in_new" size="xs"></q-icon>
</q-item-section>
</q-item>
<q-item
clickable
tag="a"
target="_blank"
href="https://github.com/lnbits/nostrmarket/issues"
>
<q-item-section avatar>
<q-icon name="bug_report" color="warning"></q-icon>
</q-item-section>
<q-item-section>
<q-item-label>Report Issues / Feedback</q-item-label>
<q-item-label caption>GitHub Issues</q-item-label>
</q-item-section>
<q-item-section side>
<q-icon name="open_in_new" size="xs"></q-icon>
</q-item-section>
</q-item>

52
templates/nostrmarket/components/shipping-zones.html
View file

@ -48,26 +48,36 @@
label="Countries"
v-model="zoneDialog.data.countries"
></q-select>
<q-select
:disabled="!!zoneDialog.data.id"
:readonly="!!zoneDialog.data.id"
filled
dense
v-model="zoneDialog.data.currency"
type="text"
label="Unit"
:options="currencies"
></q-select>
<q-input
filled
dense
:label="'Cost of Shipping (' + zoneDialog.data.currency + ') *'"
fill-mask="0"
reverse-fill-mask
:step="zoneDialog.data.currency != 'sat' ? '0.01' : '1'"
type="number"
v-model.trim="zoneDialog.data.cost"
></q-input>
<div class="row items-start">
<div class="col q-mr-sm">
<q-input
filled
dense
label="Default shipping cost"
fill-mask="0"
reverse-fill-mask
:step="zoneDialog.data.currency != 'sat' ? '0.01' : '1'"
type="number"
v-model.trim="zoneDialog.data.cost"
:error="(zoneDialog.data.currency === 'sat' && zoneDialog.data.cost % 1 !== 0) || (zoneDialog.data.currency !== 'sat' && (zoneDialog.data.cost * 100) % 1 !== 0)"
:error-message="zoneDialog.data.currency === 'sat' ? 'Satoshis must be whole numbers' : 'Maximum 2 decimal places allowed'"
hint="Additional costs can be set per product"
></q-input>
</div>
<div class="col-auto">
<q-select
:disabled="!!zoneDialog.data.id"
:readonly="!!zoneDialog.data.id"
filled
dense
v-model="zoneDialog.data.currency"
type="text"
label="Currency"
:options="currencies"
style="min-width: 100px"
></q-select>
</div>
</div>
<div class="row q-mt-lg">
<div v-if="zoneDialog.data.id">
<q-btn unelevated color="primary" type="submit">Update</q-btn>
@ -83,7 +93,7 @@
<q-btn
unelevated
color="primary"
:disable="!zoneDialog.data.countries || !zoneDialog.data.countries.length"
:disable="!zoneDialog.data.name || !zoneDialog.data.countries || !zoneDialog.data.countries.length || (zoneDialog.data.currency === 'sat' && zoneDialog.data.cost % 1 !== 0) || (zoneDialog.data.currency !== 'sat' && (zoneDialog.data.cost * 100) % 1 !== 0)"
type="submit"
>Create Shipping Zone</q-btn
>

16
templates/nostrmarket/index.html
View file

@ -166,13 +166,21 @@
</div>
<div class="col-12">
<q-card>
<q-img
src="/nostrmarket/static/market/images/nostr-cover.png"
:ratio="3"
fit="cover"
></q-img>
<q-card-section>
<h6 class="text-subtitle1 q-my-none">
{{SITE_TITLE}} Nostr Market Extension
</h6>
<div class="text-h6 q-mb-sm">Nostr Market</div>
<div class="text-body2 text-grey">
A decentralized marketplace extension for LNbits implementing the
NIP-15 protocol. Create stalls, list products, and accept Lightning
payments while communicating with customers via encrypted Nostr
direct messages.
</div>
</q-card-section>
<q-card-section class="q-pa-none">
<q-separator></q-separator>
<q-list> {% include "nostrmarket/_api_docs.html" %} </q-list>
</q-card-section>
</q-card>