Compare commits

..

No commits in common. "main" and "v1.0.0" have entirely different histories.

19 changed files with 2804 additions and 2542 deletions

View file

@ -11,9 +11,14 @@ jobs:
tests:
runs-on: ubuntu-latest
needs: [lint]
strategy:
matrix:
python-version: ['3.9', '3.10']
steps:
- uses: actions/checkout@v4
- uses: lnbits/lnbits/.github/actions/prepare@dev
with:
python-version: ${{ matrix.python-version }}
- name: Run pytest
uses: pavelzw/pytest-action@v2
env:
@ -25,5 +30,5 @@ jobs:
job-summary: true
emoji: false
click-to-expand: true
custom-pytest: uv run pytest
report-title: 'test'
custom-pytest: poetry run pytest
report-title: 'test (${{ matrix.python-version }})'

View file

@ -5,27 +5,27 @@ format: prettier black ruff
check: mypy pyright checkblack checkruff checkprettier
prettier:
uv run ./node_modules/.bin/prettier --write .
poetry run ./node_modules/.bin/prettier --write .
pyright:
uv run ./node_modules/.bin/pyright
poetry run ./node_modules/.bin/pyright
mypy:
uv run mypy .
poetry run mypy .
black:
uv run black .
poetry run black .
ruff:
uv run ruff check . --fix
poetry run ruff check . --fix
checkruff:
uv run ruff check .
poetry run ruff check .
checkprettier:
uv run ./node_modules/.bin/prettier --check .
poetry run ./node_modules/.bin/prettier --check .
checkblack:
uv run black --check .
poetry run black --check .
checkeditorconfig:
editorconfig-checker
@ -33,14 +33,14 @@ checkeditorconfig:
test:
PYTHONUNBUFFERED=1 \
DEBUG=true \
uv run pytest
poetry run pytest
install-pre-commit-hook:
@echo "Installing pre-commit hook to git"
@echo "Uninstall the hook with uv run pre-commit uninstall"
uv run pre-commit install
@echo "Uninstall the hook with poetry run pre-commit uninstall"
poetry run pre-commit install
pre-commit:
uv run pre-commit run --all-files
poetry run pre-commit run --all-files
checkbundle:

119
README.md
View file

@ -2,123 +2,14 @@
<small>For more about LNBits extension check [this tutorial](https://github.com/lnbits/lnbits/wiki/LNbits-Extensions)</small>
## Overview
`nostrclient` is an always-on extension that can open multiple connections to nostr relays and act as a multiplexer for other clients: You open a single websocket to `nostrclient` which then sends the data to multiple relays. The responses from these relays are then sent back to the client.
`nostrclient` is an always-on Nostr relay multiplexer that simplifies connecting to multiple Nostr relays. Instead of your Nostr client managing connections to dozens of relays, you connect to a single WebSocket endpoint provided by `nostrclient`, which then fans out your requests to all configured relays and aggregates the responses back to you.
![2023-03-08 18 11 07](https://user-images.githubusercontent.com/93376500/225265727-369f0f8a-196e-41df-a0d1-98b50a0228be.jpg)
### Why Use This?
### Troubleshoot
- **Simplified Client Configuration** - Connect to one endpoint instead of managing multiple relay connections
- **Always-On Connectivity** - Your LNbits instance maintains persistent connections to relays
- **Resource Efficient** - Share relay connections across multiple clients
- **Subscription Management** - Automatic subscription ID rewriting prevents conflicts between clients
The `Test Endpoint` functionality heps the user to check that the `nostrclient` web-socket endpoint works as expected.
## Architecture
```mermaid
flowchart LR
A[Client A] -->|WebSocket| N
B[Client B] -->|WebSocket| N
C[Client C] -->|WebSocket| N
N[nostrclient<br/>Router] -->|Fan Out| R1[Relay A]
N -->|Fan Out| R2[Relay B]
N -->|Fan Out| R3[Relay C]
N -->|Fan Out| R4[Relay D]
R1 -.->|Aggregate| N
R2 -.->|Aggregate| N
R3 -.->|Aggregate| N
R4 -.->|Aggregate| N
```
**Key Feature:** The router rewrites subscription IDs to prevent conflicts when multiple clients use the same IDs.
## Features
- **Multi-Relay Multiplexing** - Connect to multiple Nostr relays through a single WebSocket
- **Public & Private Endpoints** - Configurable public and private WebSocket access
- **Automatic Reconnection** - Failed relays are automatically retried with exponential backoff
- **Subscription Deduplication** - Events are deduplicated before being sent to clients
- **Health Monitoring** - Track relay connection status, latency, and error rates
- **Test Endpoint** - Send test messages to verify your setup is working
## How It Works
1. **Client Connection** - Your Nostr client connects to the nostrclient WebSocket endpoint
2. **Subscription Rewriting** - Each subscription ID is rewritten to prevent conflicts between multiple clients
3. **Fan-Out** - Subscription requests are sent to all configured relays
4. **Aggregation** - Events from all relays are collected and deduplicated
5. **Response** - Events are sent back to the client with the original subscription ID
## Configuration
### WebSocket Endpoints
- **Public Endpoint**: `/api/v1/relay` - Available to anyone (if enabled)
- **Private Endpoint**: `/api/v1/{encrypted_id}` - Requires valid encrypted endpoint ID
Configure endpoint access in the extension settings:
- `private_ws` - Enable/disable private WebSocket access
- `public_ws` - Enable/disable public WebSocket access
### Adding Relays
Use the nostrclient UI to add/remove Nostr relays. The extension will automatically:
- Connect to new relays
- Publish existing subscriptions to new relays
- Monitor relay health and reconnect as needed
## Testing
### Test Endpoint Functionality
The `Test Endpoint` feature helps verify that your nostrclient WebSocket endpoint works correctly.
**How to test:**
1. Navigate to the nostrclient extension in LNbits
2. Use the Test Endpoint feature
3. Send a DM to yourself (or a temporary account)
4. Verify that messages are sent and received correctly
The LNbits user can DM itself (or a temp account) from `nostrclient` and verify that the messages are sent and received correctly.
https://user-images.githubusercontent.com/2951406/236780745-929c33c2-2502-49be-84a3-db02a7aabc0e.mp4
## Troubleshooting
### Connection Issues
- **Check relay status** - View relay health in the nostrclient UI
- **Verify endpoint configuration** - Ensure public_ws or private_ws is enabled
- **Check logs** - Review LNbits logs for connection errors
### Subscription Not Receiving Events
- **Verify relays are connected** - Check the relay status in the UI
- **Test with known event** - Use the Test Endpoint to verify connectivity
- **Check relay compatibility** - Some relays may not support all Nostr features
## Development
This extension uses `uv` for dependency management.
### Quick Start
```bash
# Format code
make format
# Run type checks and linting
make check
# Run tests
make test
```
For more development commands, see the [Makefile](./Makefile).
## License
MIT License - see [LICENSE](./LICENSE)

View file

@ -53,7 +53,7 @@ def nostrclient_start():
__all__ = [
"db",
"nostrclient_ext",
"nostrclient_start",
"nostrclient_static_files",
"nostrclient_stop",
"nostrclient_start",
]

View file

@ -1,17 +1,7 @@
{
"name": "Nostr Client",
"short_description": "Nostr relay multiplexer",
"version": "1.1.0",
"short_description": "Nostr client for extensions",
"tile": "/nostrclient/static/images/nostr-bitcoin.png",
"contributors": ["calle", "motorina0", "dni"],
"min_lnbits_version": "1.4.0",
"images": [
{
"uri": "https://raw.githubusercontent.com/lnbits/nostrclient/add-extension-metadata/static/images/1.jpeg"
},
{
"uri": "https://raw.githubusercontent.com/lnbits/nostrclient/add-extension-metadata/static/images/2.jpeg"
}
],
"description_md": "https://raw.githubusercontent.com/lnbits/nostrclient/add-extension-metadata/description.md"
"min_lnbits_version": "1.0.0"
}

View file

@ -1,3 +1,5 @@
from typing import Optional
from lnbits.db import Database
from .models import Config, Relay, UserConfig
@ -38,7 +40,7 @@ async def update_config(owner_id: str, config: Config) -> Config:
return user_config.extra
async def get_config(owner_id: str) -> Config | None:
async def get_config(owner_id: str) -> Optional[Config]:
user_config: UserConfig = await db.fetchone(
"""
SELECT * FROM nostrclient.config

View file

@ -1,8 +1 @@
An always-on relay multiplexer that simplifies connecting to multiple Nostr relays.
Instead of your Nostr client managing connections to dozens of relays, you connect to a single WebSocket endpoint provided by `nostrclient`, which then fans out your requests to all configured relays and aggregates the responses back to you.
- **Simplified Client Configuration** - Connect to one endpoint instead of managing multiple relay connections
- **Always-On Connectivity** - Your LNbits instance maintains persistent connections to relays
- **Resource Efficient** - Share relay connections across multiple clients
- **Automatic Subscription Management** - Subscription ID rewriting prevents conflicts between clients
An always-on extension that can open multiple connections to nostr relays and act as a multiplexer for other clients: You open a single websocket to nostrclient which then sends the data to multiple relays. The responses from these relays are then sent back to the client.

View file

@ -1,25 +1,27 @@
from typing import Optional
from lnbits.helpers import urlsafe_short_hash
from pydantic import BaseModel, Field
class RelayStatus(BaseModel):
num_sent_events: int | None = 0
num_received_events: int | None = 0
error_counter: int | None = 0
error_list: list | None = []
notice_list: list | None = []
num_sent_events: Optional[int] = 0
num_received_events: Optional[int] = 0
error_counter: Optional[int] = 0
error_list: Optional[list] = []
notice_list: Optional[list] = []
class Relay(BaseModel):
id: str | None = None
url: str | None = None
active: bool | None = None
id: Optional[str] = None
url: Optional[str] = None
active: Optional[bool] = None
connected: bool | None = Field(default=None, no_database=True)
connected_string: str | None = Field(default=None, no_database=True)
status: RelayStatus | None = Field(default=None, no_database=True)
connected: Optional[bool] = Field(default=None, no_database=True)
connected_string: Optional[str] = Field(default=None, no_database=True)
status: Optional[RelayStatus] = Field(default=None, no_database=True)
ping: int | None = Field(default=None, no_database=True)
ping: Optional[int] = Field(default=None, no_database=True)
def _init__(self):
if not self.id:
@ -29,11 +31,11 @@ class Relay(BaseModel):
class RelayDb(BaseModel):
id: str
url: str
active: bool | None = True
active: Optional[bool] = True
class TestMessage(BaseModel):
sender_private_key: str | None
sender_private_key: Optional[str]
reciever_public_key: str
message: str

View file

@ -5,7 +5,7 @@ from enum import IntEnum
from hashlib import sha256
from typing import Optional
import coincurve
from secp256k1 import PublicKey
from .message_type import ClientMessageType
@ -75,8 +75,12 @@ class Event:
def verify(self) -> bool:
assert self.public_key
assert self.signature
pub_key = coincurve.PublicKeyXOnly(bytes.fromhex(self.public_key))
return pub_key.verify(bytes.fromhex(self.signature), bytes.fromhex(self.id))
pub_key = PublicKey(
bytes.fromhex("02" + self.public_key), True
) # add 02 for schnorr (bip340)
return pub_key.schnorr_verify(
bytes.fromhex(self.id), bytes.fromhex(self.signature), None, raw=True
)
def to_message(self) -> str:
return json.dumps(

View file

@ -1,7 +1,9 @@
import base64
import secrets
from typing import Optional
import coincurve
import secp256k1
from cffi import FFI
from cryptography.hazmat.primitives import padding
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
@ -21,13 +23,15 @@ class PublicKey:
return self.raw_bytes.hex()
def verify_signed_message_hash(self, message_hash: str, sig: str) -> bool:
pk = coincurve.PublicKeyXOnly(self.raw_bytes)
return pk.verify(bytes.fromhex(sig), bytes.fromhex(message_hash))
pk = secp256k1.PublicKey(b"\x02" + self.raw_bytes, True)
return pk.schnorr_verify(
bytes.fromhex(message_hash), bytes.fromhex(sig), None, True
)
@classmethod
def from_npub(cls, npub: str):
"""Load a PublicKey from its bech32/npub form"""
_, data, _ = bech32_decode(npub)
hrp, data, spec = bech32_decode(npub)
raw_data = convertbits(data, 5, 8)
assert raw_data
raw_public_key = raw_data[:-1]
@ -35,20 +39,20 @@ class PublicKey:
class PrivateKey:
def __init__(self, raw_secret: bytes | None = None) -> None:
def __init__(self, raw_secret: Optional[bytes] = None) -> None:
if raw_secret is not None:
self.raw_secret = raw_secret
else:
self.raw_secret = secrets.token_bytes(32)
sk = coincurve.PrivateKey(self.raw_secret)
assert sk.public_key
self.public_key = PublicKey(sk.public_key.format()[1:])
sk = secp256k1.PrivateKey(self.raw_secret)
assert sk.pubkey
self.public_key = PublicKey(sk.pubkey.serialize()[1:])
@classmethod
def from_nsec(cls, nsec: str):
"""Load a PrivateKey from its bech32/nsec form"""
_, data, _ = bech32_decode(nsec)
hrp, data, spec = bech32_decode(nsec)
raw_data = convertbits(data, 5, 8)
assert raw_data
raw_secret = raw_data[:-1]
@ -62,13 +66,12 @@ class PrivateKey:
return self.raw_secret.hex()
def tweak_add(self, scalar: bytes) -> bytes:
sk = coincurve.PrivateKey(self.raw_secret)
return sk.add(scalar).to_der()
sk = secp256k1.PrivateKey(self.raw_secret)
return sk.tweak_add(scalar)
def compute_shared_secret(self, public_key_hex: str) -> bytes:
pk = coincurve.PublicKey(bytes.fromhex("02" + public_key_hex))
sk = coincurve.PrivateKey(self.raw_secret)
return sk.ecdh(pk.format())
pk = secp256k1.PublicKey(bytes.fromhex("02" + public_key_hex), True)
return pk.ecdh(self.raw_secret, hashfn=copy_x)
def encrypt_message(self, message: str, public_key_hex: str) -> str:
padder = padding.PKCS7(128).padder()
@ -113,8 +116,8 @@ class PrivateKey:
return unpadded_data.decode()
def sign_message_hash(self, message_hash: bytes) -> str:
sk = coincurve.PrivateKey(self.raw_secret)
sig = sk.sign_schnorr(message_hash)
sk = secp256k1.PrivateKey(self.raw_secret)
sig = sk.schnorr_sign(message_hash, None, raw=True)
return sig.hex()
def sign_event(self, event: Event) -> None:
@ -128,7 +131,9 @@ class PrivateKey:
return self.raw_secret == other.raw_secret
def mine_vanity_key(prefix: str | None = None, suffix: str | None = None) -> PrivateKey:
def mine_vanity_key(
prefix: Optional[str] = None, suffix: Optional[str] = None
) -> PrivateKey:
if prefix is None and suffix is None:
raise ValueError("Expected at least one of 'prefix' or 'suffix' arguments")
@ -144,3 +149,14 @@ def mine_vanity_key(prefix: str | None = None, suffix: str | None = None) -> Pri
break
return sk
ffi = FFI()
@ffi.callback(
"int (unsigned char *, const unsigned char *, const unsigned char *, void *)"
)
def copy_x(output, x32, y32, data):
ffi.memmove(output, x32, 32)
return 1

2655
poetry.lock generated Normal file

File diff suppressed because it is too large Load diff

View file

@ -1,44 +1,47 @@
[project]
name = "lnbits-nostrclient"
version = "1.1.0"
requires-python = ">=3.10,<3.13"
description = "LNbits, free and open-source Lightning wallet and accounts system."
authors = [{ name = "Alan Bits", email = "alan@lnbits.com" }]
urls = { Homepage = "https://lnbits.com", Repository = "https://github.com/lnbits/nostrclient" }
dependencies = [ "lnbits>1" ]
[tool.poetry]
package-mode = false
name = "lnbits-nostrclient"
version = "0.0.0"
description = "LNbits, free and open-source Lightning wallet and accounts system."
authors = ["Alan Bits <alan@lnbits.com>"]
[tool.uv]
dev-dependencies = [
"black",
"pytest-asyncio",
"pytest",
"mypy",
"pre-commit",
"ruff",
"pytest-md",
"types-cffi",
]
[tool.poetry.dependencies]
python = "^3.10 | ^3.9"
lnbits = {allow-prereleases = true, version = "*"}
[tool.poetry.group.dev.dependencies]
black = "^24.3.0"
pytest-asyncio = "^0.21.0"
pytest = "^7.3.2"
mypy = "^1.5.1"
pre-commit = "^3.2.2"
ruff = "^0.3.2"
types-cffi = "^1.16.0.20240331"
pytest-md = "^0.2.0"
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
[tool.mypy]
exclude = "(nostr/*)"
plugins = ["pydantic.mypy"]
[[tool.mypy.overrides]]
module = [
"nostr.*",
"lnbits.*",
"lnurl.*",
"loguru.*",
"fastapi.*",
"pydantic.*",
"pyqrcode.*",
"shortuuid.*",
"httpx.*",
"secp256k1.*",
"websocket.*",
]
follow_imports = "skip"
ignore_missing_imports = "True"
[tool.pydantic-mypy]
init_forbid_extra = true
init_typed = true
warn_required_dynamic_aliases = true
warn_untyped_fields = true
[tool.pytest.ini_options]
log_cli = false
testpaths = [

View file

@ -1,6 +1,6 @@
import asyncio
import json
from typing import ClassVar
from typing import ClassVar, Dict, List
from fastapi import WebSocket, WebSocketDisconnect
from lnbits.helpers import urlsafe_short_hash
@ -16,7 +16,7 @@ all_routers: list["NostrRouter"] = []
class NostrRouter:
received_subscription_events: ClassVar[dict[str, list[EventMessage]]] = {}
received_subscription_events: ClassVar[dict[str, List[EventMessage]]] = {}
received_subscription_notices: ClassVar[list[NoticeMessage]] = []
received_subscription_eosenotices: ClassVar[dict[str, EndOfStoredEventsMessage]] = (
{}
@ -25,11 +25,11 @@ class NostrRouter:
def __init__(self, websocket: WebSocket):
self.connected: bool = True
self.websocket: WebSocket = websocket
self.tasks: list[asyncio.Task] = []
self.original_subscription_ids: dict[str, str] = {}
self.tasks: List[asyncio.Task] = []
self.original_subscription_ids: Dict[str, str] = {}
@property
def subscriptions(self) -> list[str]:
def subscriptions(self) -> List[str]:
return list(self.original_subscription_ids.keys())
def start(self):
@ -111,14 +111,10 @@ class NostrRouter:
# this reconstructs the original response from the relay
# reconstruct original subscription id
s_original = self.original_subscription_ids[s]
event_to_forward = json.dumps(
["EVENT", s_original, json.loads(event_json)]
)
event_to_forward = f"""["EVENT", "{s_original}", {event_json}]"""
await self.websocket.send_text(event_to_forward)
except Exception as e:
logger.warning(
f"[NOSTRCLIENT] Error in _handle_received_subscription_events: {e}"
)
logger.debug(e) # there are 2900 errors here
def _handle_notices(self):
while len(NostrRouter.received_subscription_notices):

Binary file not shown.

Before

Width:  |  Height:  |  Size: 488 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 300 KiB

View file

@ -466,7 +466,8 @@
predefinedRelays: [
'wss://relay.damus.io',
'wss://nostr-pub.wellorder.net',
'wss://relay.nostrconnect.com',
'wss://nostr.zebedee.cloud',
'wss://nodestr.fmt.wiz.biz',
'wss://nostr.oxtr.dev',
'wss://nostr.wine'
]
@ -476,7 +477,11 @@
getRelays: function () {
var self = this
LNbits.api
.request('GET', '/nostrclient/api/v1/relays')
.request(
'GET',
'/nostrclient/api/v1/relays?usr=' + this.g.user.id,
this.g.user.wallets[0].adminkey
)
.then(function (response) {
if (response.data) {
response.data.map(maplrelays)
@ -504,9 +509,12 @@
console.log('ADD RELAY ' + this.relayToAdd)
let that = this
LNbits.api
.request('POST', '/nostrclient/api/v1/relay', null, {
url: this.relayToAdd
})
.request(
'POST',
'/nostrclient/api/v1/relay?usr=' + this.g.user.id,
this.g.user.wallets[0].adminkey,
{url: this.relayToAdd}
)
.then(function (response) {
console.log('response:', response)
if (response.data) {
@ -533,7 +541,12 @@
},
deleteRelay(url) {
LNbits.api
.request('DELETE', '/nostrclient/api/v1/relay', null, {url: url})
.request(
'DELETE',
'/nostrclient/api/v1/relay?usr=' + this.g.user.id,
this.g.user.wallets[0].adminkey,
{url: url}
)
.then(response => {
const relayIndex = this.nostrrelayLinks.indexOf(r => r.url === url)
if (relayIndex !== -1) {
@ -549,7 +562,8 @@
try {
const {data} = await LNbits.api.request(
'GET',
'/nostrclient/api/v1/config'
'/nostrclient/api/v1/config',
this.g.user.wallets[0].adminkey
)
this.config.data = data
} catch (error) {
@ -561,7 +575,7 @@
const {data} = await LNbits.api.request(
'PUT',
'/nostrclient/api/v1/config',
null,
this.g.user.wallets[0].adminkey,
this.config.data
)
this.config.data = data
@ -610,7 +624,7 @@
const {data} = await LNbits.api.request(
'PUT',
'/nostrclient/api/v1/relay/test',
null,
this.g.user.wallets[0].adminkey,
{
sender_private_key: this.testData.senderPrivateKey,
reciever_public_key: this.testData.recieverPublicKey,

2305
uv.lock generated

File diff suppressed because it is too large Load diff

View file

@ -1,7 +1,6 @@
from fastapi import APIRouter, Depends, Request
from fastapi.responses import HTMLResponse
from lnbits.core.crud.users import get_user_from_account
from lnbits.core.models.users import Account
from lnbits.core.models import User
from lnbits.decorators import check_admin
from lnbits.helpers import template_renderer
@ -13,10 +12,7 @@ def nostr_renderer():
@nostrclient_generic_router.get("/", response_class=HTMLResponse)
async def index(request: Request, account: Account = Depends(check_admin)):
user = await get_user_from_account(account)
if not user:
return HTMLResponse("No user found", status_code=404)
async def index(request: Request, user: User = Depends(check_admin)):
return nostr_renderer().TemplateResponse(
"nostrclient/index.html", {"request": request, "user": user.json()}
)

View file

@ -131,7 +131,7 @@ async def ws_relay(ws_id: str, websocket: WebSocket) -> None:
else:
if not config.private_ws:
raise ValueError("Private websocket connections not accepted.")
if decrypt_internal_message(ws_id, urlsafe=True) != "relay":
if decrypt_internal_message(ws_id) != "relay":
raise ValueError("Invalid websocket endpoint.")
await websocket.accept()