refactor: extract functions

This reverts commit e7c359c1e0e21a8aeea391fd5b2cd6316526d42c.

.dockerignore

@@ -23,3 +23,10 @@ mypy.ini
 package-lock.json
 package.json
 pytest.ini
+
+.mypy_cache
+.github
+.pytest_cache
+.vscode
+bin
+dist

.env.example

@@ -1,20 +1,41 @@
 #For more information on .env files, their content and format: https://pypi.org/project/python-dotenv/
 
 ######################################
-####### Auth Configurations ##########
+###### .env ONLY SETTINGS ############
 ######################################
-# Secret Key: will default to the hash of the super user.
-# !!!!! It is strongly recommended that you set your own strong random value !!!!
-AUTH_SECRET_KEY=""
-AUTH_TOKEN_EXPIRE_MINUTES=525600
-# Possible authorization methods: user-id-only, username-password, nostr-auth-nip98, google-auth, github-auth, keycloak-auth
-AUTH_ALLOWED_METHODS="user-id-only, username-password"
-# Set this flag if HTTP is used for OAuth
-# OAUTHLIB_INSECURE_TRANSPORT="1"
+# The following settings are ONLY set in your .env file.
+# They are NOT managed by the Admin UI and are not stored in the database.
 
-######################################
-########### Admin Settings ###########
-######################################
+# === First Install Token ===
+# If set the user is required to enter this token on the /first_install page
+# FIRST_INSTALL_TOKEN="myaccesstoken"
+
+# === Security ===
+# When enabled (recommended), auth cookies require HTTPS and SSO will reject insecure HTTP.
+AUTH_HTTPS_ONLY=true
+
+# === Logging and Development ===
+
+DEBUG=False
+DEBUG_DATABASE=False
+BUNDLE_ASSETS=True
+# add `?profiler=true` to the url to enable the profiler for that request
+PROFILER=False
+
+# logging into LNBITS_DATA_FOLDER/logs/
+ENABLE_LOG_TO_FILE=true
+
+# https://loguru.readthedocs.io/en/stable/api/logger.html#file
+LOG_ROTATION="100 MB"
+LOG_RETENTION="3 months"
+# for database cleanup commands
+# CLEANUP_WALLETS_DAYS=90
+# Hard limit for total created users. Set to 0 to disable the limit.
+# LNBITS_MAX_USERS=0
+# Hard limit for total installed extensions. Set to 0 to disable the limit.
+# LNBITS_MAX_EXTENSIONS=0
+
+# === Admin Settings ===
 
 # Enable Admin GUI, available for the first user in LNBITS_ADMIN_USERS if available.
 # Warning: Enabling this will make LNbits ignore most configurations in file. Only the
@@ -24,30 +45,92 @@ AUTH_ALLOWED_METHODS="user-id-only, username-password"
 # Disable this and clear `settings` table from database to make LNbits use this config file again.
 LNBITS_ADMIN_UI=true
 
+HOST=127.0.0.1
+PORT=5000
+# VERSION=
+# USER_AGENT=
+
+# === LNbits ===
+
+# Database: to use SQLite, specify LNBITS_DATA_FOLDER
+#           to use PostgreSQL, specify LNBITS_DATABASE_URL=postgres://...
+#           to use CockroachDB, specify LNBITS_DATABASE_URL=cockroachdb://...
+# for both PostgreSQL and CockroachDB, you'll need to install
+#   psycopg2 as an additional dependency
+LNBITS_DATA_FOLDER="./data"
+# LNBITS_DATABASE_URL="postgres://user:password@host:port/databasename"
+
+# Extensions to be installed by default. If an extension from this list is uninstalled then it will be re-installed on the next restart.
+# The extension must be removed from this list in order to not be re-installed.
+LNBITS_EXTENSIONS_DEFAULT_INSTALL="tpos"
+
+# LNBITS_EXTENSIONS_MANIFESTS="https://raw.githubusercontent.com/lnbits/lnbits-extensions/main/extensions.json,https://raw.githubusercontent.com/lnbits/lnbits-extensions/main/extensions-trial.json"
+# GitHub has rate-limits for its APIs. The limit can be increased specifying a GITHUB_TOKEN
+# LNBITS_EXT_GITHUB_TOKEN=github_pat_xxxxxxxxxxxxxxxxxx
+
+# which fundingsources are allowed in the admin ui
+# LNBITS_ALLOWED_FUNDING_SOURCES="VoidWallet, FakeWallet, CoreLightningWallet, CoreLightningRestWallet, LndRestWallet, EclairWallet, LndWallet, LnTipsWallet, LNPayWallet, LNbitsWallet, BlinkWallet, AlbyWallet, ZBDWallet, PhoenixdWallet, OpenNodeWallet, NWCWallet, BreezSdkWallet, BoltzWallet, StrikeWallet, CLNRestWallet, SparkWallet, SparkL2Wallet"
+
+# uvicorn variable, allow https behind a proxy
+# IMPORTANT: this also needs the webserver to be configured to forward the headers
+# http://docs.lnbits.org/guide/installation.html#running-behind-an-apache2-reverse-proxy-over-https
+FORWARDED_ALLOW_IPS="*"
+
+# Path where extensions will be installed (defaults to `./lnbits/`).
+# Inside this directory the `extensions` and `upgrades` sub-directories will be created.
+# LNBITS_EXTENSIONS_PATH="/path/to/some/dir"
+
+# ID of the super user. The user ID must exist.
+# SUPER_USER=""
+
+# LNBITS_TITLE="LNbits API"
+# LNBITS_PATH="folder/path"
+
+# === Auth Configurations ===
+
+# Secret Key: will default to the hash of the super user.
+# !!!!! It is strongly recommended that you set your own strong random value !!!!
+AUTH_SECRET_KEY=""
+
+# === Funding Source ===# How many times to retry connectiong to the Funding Source before defaulting to the VoidWallet
+# FUNDING_SOURCE_MAX_RETRIES=4
+
+######################################
+###### END .env ONLY SETTINGS ########
+######################################
+
+######################################
+####### Auth Configurations ##########
+######################################
+
+AUTH_TOKEN_EXPIRE_MINUTES=525600
+# Possible authorization methods: user-id-only, username-password, nostr-auth-nip98, google-auth, github-auth, keycloak-auth, oidc-auth
+AUTH_ALLOWED_METHODS="user-id-only, username-password"
+# Set this flag if HTTP is used for OAuth
+# OAUTHLIB_INSECURE_TRANSPORT="1"
+
+######################################
+########### Admin Settings ###########
+######################################
+
 # Change theme
 LNBITS_SITE_TITLE="LNbits"
 LNBITS_SITE_TAGLINE="Open Source Lightning Payments Platform"
 LNBITS_SITE_DESCRIPTION="The world's most powerful suite of bitcoin tools. Run for yourself, for others, or as part of a stack."
 # Choose from bitcoin, mint, flamingo, freedom, salvador, autumn, monochrome, classic, cyber
 LNBITS_THEME_OPTIONS="classic, bitcoin, flamingo, freedom, mint, autumn, monochrome, salvador, cyber"
+# Toggle the background styling on burger menus / drawers
+# LNBITS_DEFAULT_BURGER_MENU_BACKGROUND=true
 # LNBITS_CUSTOM_LOGO="https://lnbits.com/assets/images/logo/logo.svg"
 
-HOST=127.0.0.1
-PORT=5000
-
 ######################################
 ########## Funding Source ############
 ######################################
 
-# which fundingsources are allowed in the admin ui
-# LNBITS_ALLOWED_FUNDING_SOURCES="VoidWallet, FakeWallet, CoreLightningWallet, CoreLightningRestWallet, LndRestWallet, EclairWallet, LndWallet, LnTipsWallet, LNPayWallet, LNbitsWallet, BlinkWallet, AlbyWallet, ZBDWallet, PhoenixdWallet, OpenNodeWallet, NWCWallet, BreezSdkWallet, BoltzWallet"
-
 LNBITS_BACKEND_WALLET_CLASS=VoidWallet
 # VoidWallet is just a fallback that works without any actual Lightning capabilities,
 # just so you can see the UI before dealing with this file.
 
-# How many times to retry connectiong to the Funding Source before defaulting to the VoidWallet
-# FUNDING_SOURCE_MAX_RETRIES=4
 
 # Invoice expiry for LND, CLN, Eclair, LNbits funding sources
 LIGHTNING_INVOICE_EXPIRY=3600
@@ -61,6 +144,20 @@ CLICHE_ENDPOINT=ws://127.0.0.1:12000
 SPARK_URL=http://localhost:9737/rpc
 SPARK_TOKEN=myaccesstoken
 
+#CLNRest (using runes)
+CLNREST_URL=https://127.0.0.1:3010
+CLNREST_CA=/home/lightningd/.lightning/bitcoin/ca.pem
+CLNREST_CERT=/home/lightningd/.lightning/bitcoin/server.pem
+# CLNREST_CA = cat ca.pem | awk '{printf "%s\\n", $0} END {printf "\n"}'
+# CLNREST_CERT =  cat server.pem | awk '{printf "%s\\n", $0} END {printf "\n"}'
+
+CLNREST_READONLY_RUNE=lightning-cli createrune restrictions='[["method=listfunds", "method=listpays", "method=listinvoices", "method=getinfo", "method=summary", "method=waitanyinvoice"]]' | jq -r .rune
+CLNREST_INVOICE_RUNE=lightning-cli createrune restrictions='[["method=invoice"], ["pnameamount_msat<1000001"], ["pnamelabel^LNbits"], ["rate=60"]]' | jq -r .rune
+CLNREST_PAY_RUNE=lightning-cli createrune restrictions='[["method=pay"], ["pinvbolt11_amount<1001"],   ["pnamelabel^LNbits"], ["rate=1"]]' | jq -r .rune
+#CLNREST_RENEPAY_RUNE=lightning-cli createrune restrictions='[["method=renepay"], ["pinvinvstring_amount<1001"], ["pnamelabel^LNbits"], ["rate=1"]]' | jq -r .rune
+#CLNREST_LAST_PAY_INDEX='lightning-cli listinvoices | jq -r '.invoices | map(.created_index) | max'
+#CLNREST_NODEID=lightning-cli getinfo | jq -r .id # only required for v23.08
+
 # CoreLightningWallet
 CORELIGHTNING_RPC="/home/bob/.lightning/bitcoin/lightning-rpc"
 
@@ -101,9 +198,23 @@ ALBY_ACCESS_TOKEN=ALBY_ACCESS_TOKEN
 
 # BoltzWallet
 BOLTZ_CLIENT_ENDPOINT=127.0.0.1:9002
-BOLTZ_CLIENT_MACAROON="/home/bob/.boltz/macaroon" # or HEXSTRING
-BOLTZ_CLIENT_CERT="/home/bob/.boltz/tls.cert" # or HEXSTRING
-BOLTZ_CLIENT_WALLET="lnbits"
+# HEXSTRING instead of path also possible
+BOLTZ_CLIENT_MACAROON="/home/bob/.boltz/macaroons/admin.macaroon"
+# HEXSTRING instead of path also possible
+BOLTZ_CLIENT_CERT="/home/bob/.boltz/tls.cert"
+
+# SparkL2Wallet (external sidecar: https://github.com/lnbits/spark_sidecar)
+SPARK_L2_NETWORK=MAINNET
+SPARK_L2_EXTERNAL_ENDPOINT=http://127.0.0.1:8765
+SPARK_L2_EXTERNAL_API_KEY=
+# optional tuning
+# SPARK_L2_PAY_WAIT_MS=4000
+# SPARK_L2_PAY_POLL_MS=500
+# SPARK_L2_STREAM_KEEPALIVE_MS=15000
+
+# StrikeWallet
+STRIKE_API_ENDPOINT=https://api.strike.me/v1
+STRIKE_API_KEY=YOUR_STRIKE_API_KEY
 
 # ZBDWallet
 ZBD_API_ENDPOINT=https://api.zebedee.io/v0/
@@ -147,6 +258,12 @@ BREEZ_GREENLIGHT_DEVICE_KEY="/path/to/breezsdk/device.pem"  # or BASE64/HEXSTRIN
 BREEZ_GREENLIGHT_DEVICE_CERT="/path/to/breezsdk/device.crt"  # or BASE64/HEXSTRING
 # BREEZ_USE_TRAMPOLINE=true
 
+# BreezLiquidSdkWallet
+# get your own api key here https://breez.technology/request-api-key/#contact-us-form-sdk
+# or keep the api key empty to use the LNbits key for referrals (API key is not a secret)
+# BREEZ_LIQUID_API_KEY=""
+BREEZ_LIQUID_SEED="MNEMONIC SEED PHRASE"
+# BREEZ_LIQUID_FEE_OFFSET_SAT=50
 
 # Google OAuth Config
 # Make sure that the authorized redirect URIs contain https://{domain}/api/v1/auth/google/token
@@ -163,15 +280,56 @@ GITHUB_CLIENT_SECRET=""
 KEYCLOAK_CLIENT_ID=""
 KEYCLOAK_CLIENT_SECRET=""
 KEYCLOAK_DISCOVERY_URL=""
+KEYCLOAK_CLIENT_CUSTOM_ORG=""
+KEYCLOAK_CLIENT_CUSTOM_ICON=""
+
+# OIDC OAuth Config
+# Generic OIDC provider configuration
+# Make sure that the redirect URI in your OIDC provider is set to: https://{domain}/api/v1/auth/oidc/token
+# Required scopes: openid, email, profile
+# The discovery URL must be accessible from your LNbits server
+# Always use HTTPS in production environments
+# The CUSTOM_ORG and CUSTOM_ICON settings allow you to customize the login button
+# For example: "Login via Zitadel" with the Zitadel logo
+OIDC_DISCOVERY_URL=""
+OIDC_CLIENT_ID=""
+OIDC_CLIENT_SECRET=""
+OIDC_CLIENT_CUSTOM_ORG=""
+OIDC_CLIENT_CUSTOM_ICON=""
+
+# Example OIDC configurations for various providers:
+#
+# ZITADEL:
+# OIDC_DISCOVERY_URL=https://login.yourdomain.de/.well-known/openid-configuration
+# OIDC_CLIENT_ID=your-zitadel-client-id@project-id
+# OIDC_CLIENT_SECRET=your-zitadel-client-secret
+# OIDC_CLIENT_CUSTOM_ORG=Zitadel
+# OIDC_CLIENT_CUSTOM_ICON=/static/images/zitadel.png
+#
+# AUTHENTIK:
+# OIDC_DISCOVERY_URL=https://authentik.yourdomain.com/application/o/lnbits/.well-known/openid-configuration
+# OIDC_CLIENT_ID=your-authentik-client-id
+# OIDC_CLIENT_SECRET=your-authentik-client-secret
+# OIDC_CLIENT_CUSTOM_ORG=Authentik
+# OIDC_CLIENT_CUSTOM_ICON=/static/images/authentik.png
+#
+# AUTHELIA:
+# OIDC_DISCOVERY_URL=https://auth.yourdomain.com/.well-known/openid-configuration
+# OIDC_CLIENT_ID=your-authelia-client-id
+# OIDC_CLIENT_SECRET=your-authelia-client-secret
+# OIDC_CLIENT_CUSTOM_ORG=Authelia
+# OIDC_CLIENT_CUSTOM_ICON=/static/images/authelia.png
+#
+# OKTA:
+# OIDC_DISCOVERY_URL=https://your-domain.okta.com/.well-known/openid-configuration
+# OIDC_CLIENT_ID=your-okta-client-id
+# OIDC_CLIENT_SECRET=your-okta-client-secret
+# OIDC_CLIENT_CUSTOM_ORG=Okta
+# OIDC_CLIENT_CUSTOM_ICON=/static/images/okta.png
 
 
 ######################################
 
-# uvicorn variable, uncomment to allow https behind a proxy
-# IMPORTANT: this also needs the webserver to be configured to forward the headers
-# http://docs.lnbits.org/guide/installation.html#running-behind-an-apache2-reverse-proxy-over-https
-# FORWARDED_ALLOW_IPS="*"
-
 # Server security, rate limiting ips, blocked ips, allowed ips
 LNBITS_RATE_LIMIT_NO="200"
 LNBITS_RATE_LIMIT_UNIT="minute"
@@ -182,8 +340,7 @@ LNBITS_BLOCKED_IPS=""
 # if set new users will not be able to create accounts
 LNBITS_ALLOWED_USERS=""
 LNBITS_ADMIN_USERS=""
-# ID of the super user. The user ID must exist.
-# SUPER_USER=""
+
 
 # Extensions only admin can access
 LNBITS_ADMIN_EXTENSIONS="ngrok, nostrclient"
@@ -216,26 +373,6 @@ LNBITS_DEFAULT_WALLET_NAME="LNbits wallet"
 # Hides wallet api, extensions can choose to honor
 LNBITS_HIDE_API=false
 
-# LNBITS_EXTENSIONS_MANIFESTS="https://raw.githubusercontent.com/lnbits/lnbits-extensions/main/extensions.json,https://raw.githubusercontent.com/lnbits/lnbits-extensions/main/extensions-trial.json"
-# GitHub has rate-limits for its APIs. The limit can be increased specifying a GITHUB_TOKEN
-# LNBITS_EXT_GITHUB_TOKEN=github_pat_xxxxxxxxxxxxxxxxxx
-
-# Path where extensions will be installed (defaults to `./lnbits/`).
-# Inside this directory the `extensions` and `upgrades` sub-directories will be created.
-# LNBITS_EXTENSIONS_PATH="/path/to/some/dir"
-
-# Extensions to be installed by default. If an extension from this list is uninstalled then it will be re-installed on the next restart.
-# The extension must be removed from this list in order to not be re-installed.
-LNBITS_EXTENSIONS_DEFAULT_INSTALL="tpos"
-
-# Database: to use SQLite, specify LNBITS_DATA_FOLDER
-#           to use PostgreSQL, specify LNBITS_DATABASE_URL=postgres://...
-#           to use CockroachDB, specify LNBITS_DATABASE_URL=cockroachdb://...
-# for both PostgreSQL and CockroachDB, you'll need to install
-#   psycopg2 as an additional dependency
-LNBITS_DATA_FOLDER="./data"
-# LNBITS_DATABASE_URL="postgres://user:password@host:port/databasename"
-
 # the service fee (in percent)
 LNBITS_SERVICE_FEE=0.0
 # the wallet where fees go to
@@ -245,10 +382,12 @@ LNBITS_SERVICE_FEE=0.0
 # disable fees for internal transactions
 # LNBITS_SERVICE_FEE_IGNORE_INTERNAL=true
 
-# value in millisats
+# The minimum fee reserved per payment (millisats)
 LNBITS_RESERVE_FEE_MIN=2000
-# value in percent
+# The percentage of the payment amount to reserve for routing fees (percent)
 LNBITS_RESERVE_FEE_PERCENT=1.0
+# The default time to wait to for status response from the funding source when paying an invoice
+LNBITS_FUNDING_SOURCE_PAY_INVOICE_WAIT_SECONDS=5
 
 # limit the maximum balance for each wallet
 # throw an error if the wallet attempts to create a new invoice
@@ -263,17 +402,3 @@ LNBITS_RESERVE_FEE_PERCENT=1.0
 ######################################
 ###### Logging and Development #######
 ######################################
-
-DEBUG=false
-DEBUG_DATABASE=false
-BUNDLE_ASSETS=true
-
-# logging into LNBITS_DATA_FOLDER/logs/
-ENABLE_LOG_TO_FILE=true
-
-# https://loguru.readthedocs.io/en/stable/api/logger.html#file
-LOG_ROTATION="100 MB"
-LOG_RETENTION="3 months"
-
-# for database cleanup commands
-# CLEANUP_WALLETS_DAYS=90

.github/FUNDING.yml

@@ -1 +1 @@
-custom: https://demo.lnbits.com/lnurlp/link/fH59GD
+custom: https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg

.github/actions/prepare/action.yml

@@ -5,9 +5,6 @@ inputs:
     description: "Python Version"
     required: true
     default: "3.10"
-  poetry-version:
-    description: "Poetry Version"
-    default: "1.7.0"
   node-version:
     description: "Node Version"
     default: "20.x"
@@ -24,33 +21,16 @@ runs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ inputs.python-version }}
-        # cache poetry install via pip
-        cache: "pip"
 
-    - name: Set up Poetry ${{ inputs.poetry-version }}
-      uses: abatilo/actions-poetry@v2
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
       with:
-        poetry-version: ${{ inputs.poetry-version }}
-
-    - name: Setup a local virtual environment (if no poetry.toml file)
-      shell: bash
-      run: |
-        poetry config virtualenvs.create true --local
-        poetry config virtualenvs.in-project true --local
-
-    - uses: actions/cache@v4
-      name: Define a cache for the virtual environment based on the dependencies lock file
-      with:
-        path: ./.venv
-        key: venv-${{ hashFiles('poetry.lock') }}
+        enable-cache: true
+        python-version: ${{ inputs.python-version }}
 
     - name: Install the project dependencies
       shell: bash
-      run: |
-        poetry env use python${{ inputs.python-version }}
-        poetry install
-        # needed for conv tests
-        poetry add psycopg2-binary
+      run: uv sync --locked --all-extras --dev
 
     - name: Use Node.js ${{ inputs.node-version }}
       if: ${{ (inputs.npm == 'true') }}

.github/packaging/linux/AppDir/AppRun

@@ -36,7 +36,6 @@ LNBITS_DATA_FOLDER="${LNBITS_DATA_FOLDER:-$LAUNCH_DIR/lnbits/database}"
 LNBITS_EXTENSIONS_PATH="${LNBITS_EXTENSIONS_PATH:-$LAUNCH_DIR/lnbits/extensions}"
 export LNBITS_DATA_FOLDER
 export LNBITS_EXTENSIONS_PATH
-export LNBITS_ADMIN_UI=true
 
 # Define the LNbits URL
 URL="http://0.0.0.0:5000"

.github/workflows/appimage.yml

@@ -0,0 +1,123 @@
+name: Build LNbits AppImage
+
+on:
+  workflow_call:
+    inputs:
+      tag_name:
+        description: 'The tag name for the release'
+        required: true
+        type: string
+      upload_url:
+        description: 'The upload URL for the release'
+        required: true
+        type: string
+
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: 'The tag name for the release'
+        required: true
+        type: string
+      upload_url:
+        description: 'The upload URL for the release'
+        required: true
+        type: string
+
+jobs:
+  build-linux-package:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install system deps and uv
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libfuse2
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+        shell: bash
+
+      - name: Cache uv and venv
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock', 'pyproject.toml') }}
+
+      - name: Prepare packaging & clone LNbits
+        run: |
+          mv .github/packaging packaging
+          mkdir -p packaging/linux/AppDir/usr
+          git clone https://github.com/lnbits/lnbits.git packaging/linux/AppDir/usr/lnbits
+        shell: bash
+
+      - name: Build LNbits binary (uv + PyInstaller)
+        run: |
+          cd packaging/linux/AppDir/usr/lnbits
+          uv sync --all-extras --no-dev
+          uv pip install pyinstaller
+          uv run pyinstaller \
+            --onefile \
+            --name lnbits \
+            --hidden-import=embit \
+            --hidden-import=bitstring.bitstore_bitarray \
+            --collect-all embit \
+            --collect-all bitstring \
+            --collect-all bitarray \
+            --collect-all lnbits \
+            --collect-all sqlalchemy \
+            --collect-all breez_sdk \
+            --collect-binaries breez_sdk \
+            --collect-all breez_sdk_liquid \
+            --collect-binaries breez_sdk_liquid \
+            --collect-all aiosqlite \
+            --hidden-import=passlib.handlers.bcrypt \
+            "$(uv run which lnbits)"
+
+          cd ../../../../..
+          chmod +x packaging/linux/AppDir/AppRun
+          chmod +x packaging/linux/AppDir/lnbits.desktop
+          chmod +x packaging/linux/AppDir/usr/lnbits/dist/lnbits
+
+          # keep AppDir slim
+          find packaging/linux/AppDir/usr/lnbits -mindepth 1 -maxdepth 1 \
+              ! -name 'dist' \
+              ! -name 'lnbits' \
+              -exec rm -rf {} +
+
+          # Build AppImage
+          wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage
+          chmod +x appimagetool-x86_64.AppImage
+          TAG_NAME=${{ inputs.tag_name }}
+          APPIMAGE_NAME="LNbits-${TAG_NAME}.AppImage"
+          ./appimagetool-x86_64.AppImage \
+            --updateinformation "gh-releases-zsync|lnbits|lnbits|latest|*.AppImage.zsync" \
+            packaging/linux/AppDir "$APPIMAGE_NAME"
+          chmod +x "$APPIMAGE_NAME"
+          echo "APPIMAGE_NAME=$APPIMAGE_NAME" >> $GITHUB_ENV
+
+          # 🔎 quick audit: show glibc versions referenced by the binary
+          echo "Runner glibc:"
+          ldd --version | head -n1 || true
+          echo "Symbols needed by lnbits:"
+          strings "$APPIMAGE_NAME" | grep -o 'GLIBC_[0-9.]*' | sort -u || true
+        shell: bash
+
+      - name: Upload Linux Release Asset
+        uses: actions/upload-release-asset@v1
+        with:
+          upload_url: ${{ inputs.upload_url }}
+          asset_path: ${{ env.APPIMAGE_NAME }}
+          asset_name: ${{ env.APPIMAGE_NAME }}
+          asset_content_type: application/octet-stream
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/bundle.yml

@@ -0,0 +1,33 @@
+name: bundle
+on:
+  workflow_call:
+
+jobs:
+  bundle:
+    permissions:
+      contents: write
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.repo.full_name == github.repository && github.head_ref || github.event.pull_request.head.sha }}
+      - uses: lnbits/lnbits/.github/actions/prepare@dev
+        with:
+          python-version: "3.10"
+          node-version: "24.x"
+          npm: true
+      - name: Build and commit bundle (same-repo PR)
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        run: |
+          make bundle
+          git config user.name "alan"
+          git config user.email "alan@lnbits.com"
+          git add lnbits/static
+          if git diff --cached --quiet; then
+            exit 0
+          fi
+          git commit -m "chore: make bundle [skip ci]"
+          git push
+      - name: Check bundle is up-to-date (fork PR)
+        if: github.event.pull_request.head.repo.full_name != github.repository
+        run: make checkbundle

.github/workflows/ci.yml

@@ -1,14 +1,9 @@
 name: LNbits CI
 on:
-  push:
-    branches:
-      - main
-      - dev
   pull_request:
 
 
 jobs:
-
   lint:
     uses: ./.github/workflows/lint.yml
 
@@ -16,11 +11,11 @@ jobs:
     needs: [ lint ]
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.12"]
         db-url: ["", "postgres://lnbits:lnbits@0.0.0.0:5432/lnbits"]
     uses: ./.github/workflows/tests.yml
     with:
-      custom-pytest: "poetry run pytest tests/api"
+      custom-pytest: "uv run pytest tests/api"
       python-version: ${{ matrix.python-version }}
       db-url: ${{ matrix.db-url }}
     secrets:
@@ -30,11 +25,11 @@ jobs:
     needs: [ lint ]
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.12"]
         db-url: ["", "postgres://lnbits:lnbits@0.0.0.0:5432/lnbits"]
     uses: ./.github/workflows/tests.yml
     with:
-      custom-pytest: "poetry run pytest tests/wallets"
+      custom-pytest: "uv run pytest tests/wallets"
       python-version: ${{ matrix.python-version }}
       db-url: ${{ matrix.db-url }}
     secrets:
@@ -44,11 +39,11 @@ jobs:
     needs: [ lint ]
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.12"]
         db-url: ["", "postgres://lnbits:lnbits@0.0.0.0:5432/lnbits"]
     uses: ./.github/workflows/tests.yml
     with:
-      custom-pytest: "poetry run pytest tests/unit"
+      custom-pytest: "uv run pytest tests/unit"
       python-version: ${{ matrix.python-version }}
       db-url: ${{ matrix.db-url }}
     secrets:
@@ -58,7 +53,7 @@ jobs:
     needs: [ lint ]
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.12"]
     uses: ./.github/workflows/migration.yml
     with:
       python-version: ${{ matrix.python-version }}
@@ -74,10 +69,17 @@ jobs:
     uses: ./.github/workflows/regtest.yml
     strategy:
       matrix:
-        python-version: ["3.10"]
-        backend-wallet-class: ["LndRestWallet", "LndWallet", "CoreLightningWallet", "CoreLightningRestWallet", "LNbitsWallet", "EclairWallet"]
+        python-version: ["3.12"]
+        backend-wallet-class:
+          - BoltzWallet
+          - LndRestWallet
+          - LndWallet
+          - CoreLightningWallet
+          - CoreLightningRestWallet
+          - LNbitsWallet
+          - EclairWallet
     with:
-      custom-pytest: "poetry run pytest tests/regtest"
+      custom-pytest: "uv run pytest tests/regtest"
       python-version: ${{ matrix.python-version }}
       backend-wallet-class: ${{ matrix.backend-wallet-class }}
     secrets:
@@ -87,9 +89,11 @@ jobs:
     needs: [ lint ]
     strategy:
       matrix:
-        python-version: ["3.10"]
-        poetry-version: ["1.5.1"]
+        python-version: ["3.12"]
     uses: ./.github/workflows/jmeter.yml
     with:
       python-version: ${{ matrix.python-version }}
-      poetry-version: ${{ matrix.poetry-version }}
+
+  bundle:
+    needs: [ lint, test-api, test-wallets, test-unit, migration, openapi, regtest, jmeter ]
+    uses: ./.github/workflows/bundle.yml

.github/workflows/docker.yml

@@ -51,3 +51,25 @@ jobs:
             platforms: linux/amd64,linux/arm64
             cache-from: type=local,src=/tmp/.buildx-cache
             cache-to: type=local,dest=/tmp/.buildx-cache
+
+      - name: Build and push boltz
+        uses: docker/build-push-action@v5
+        with:
+            context: docker/boltzclient
+            push: true
+            tags: ${{ secrets.DOCKER_USERNAME }}/lnbits-boltz:${{ inputs.tag }}
+            platforms: linux/amd64,linux/arm64
+            cache-from: type=local,src=/tmp/.buildx-cache
+            cache-to: type=local,dest=/tmp/.buildx-cache
+            build-args: LNBITS_TAG=${{ inputs.tag }}
+
+      - name: Build and push sparkl2
+        uses: docker/build-push-action@v5
+        with:
+            context: docker/sparkl2
+            push: true
+            tags: ${{ secrets.DOCKER_USERNAME }}/lnbits-sparkl2:${{ inputs.tag }}
+            platforms: linux/amd64,linux/arm64
+            cache-from: type=local,src=/tmp/.buildx-cache
+            cache-to: type=local,dest=/tmp/.buildx-cache
+            build-args: LNBITS_TAG=${{ inputs.tag }}

.github/workflows/jmeter.yml

@@ -8,11 +8,6 @@ on:
         required: true
         default: "3.10"
         type: string
-      poetry-version:
-        description: "Poetry Version"
-        required: true
-        default: "1.5.1"
-        type: string
 
 jobs:
   jmeter:
@@ -27,10 +22,11 @@ jobs:
       - name: run LNbits
         env:
           LNBITS_ADMIN_UI: true
+          AUTH_HTTPS_ONLY: false
           LNBITS_EXTENSIONS_DEFAULT_INSTALL: "watchonly, satspay, tipjar, tpos, lnurlp, withdraw"
           LNBITS_BACKEND_WALLET_CLASS: FakeWallet
         run: |
-          poetry run lnbits &
+          uv run lnbits &
           sleep 10
 
       - name: setup java version

.github/workflows/lint.yml

@@ -6,50 +6,30 @@ jobs:
 
   black:
     uses: ./.github/workflows/make.yml
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
     with:
       make: checkblack
-      python-version: ${{ matrix.python-version }}
 
   ruff:
     uses: ./.github/workflows/make.yml
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
     with:
       make: checkruff
-      python-version: ${{ matrix.python-version }}
 
   mypy:
     uses: ./.github/workflows/make.yml
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
     with:
       make: mypy
-      python-version: ${{ matrix.python-version }}
 
   pyright:
     uses: ./.github/workflows/make.yml
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
     with:
       make: pyright
-      python-version: ${{ matrix.python-version }}
       npm: true
 
-
   prettier:
     uses: ./.github/workflows/make.yml
     with:
       make: checkprettier
       npm: true
 
-  bundle:
-    uses: ./.github/workflows/make.yml
-    with:
-      make: checkbundle
-      npm: true
+  poetry:
+    uses: ./.github/workflows/poetry.yml

.github/workflows/make.yml

@@ -14,7 +14,7 @@ on:
       python-version:
         description: "python version"
         type: string
-        default: "3.10"
+        default: "3.12"
 
 jobs:
   make:
@@ -22,7 +22,7 @@ jobs:
     strategy:
       matrix:
         os-version: ["ubuntu-24.04"]
-        node-version: ["18.x"]
+        node-version: ["24.x"]
     runs-on: ${{ matrix.os-version }}
     steps:
       - uses: actions/checkout@v4

.github/workflows/nix.yml

@@ -14,14 +14,14 @@ on:
       - 'flake.nix'
       - 'flake.lock'
       - 'pyproject.toml'
-      - 'poetry.lock'
+      - 'uv.lock'
       - '.github/workflows/nix.yml'
   pull_request:
     paths:
       - 'flake.nix'
       - 'flake.lock'
       - 'pyproject.toml'
-      - 'poetry.lock'
+      - 'uv.lock'
 
 jobs:
   nix:

.github/workflows/packaging.yml

@@ -1,72 +0,0 @@
-name: Build LNbits AppImage DMG
-
-on:
-  release:
-    types: [published]
-
-jobs:
-
-  build-linux-package:
-    runs-on: ubuntu-latest
-    steps:
-      # Step 1: Checkout the repository
-      - name: Checkout code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      # Step 2: Install Dependencies
-      - name: Install Dependencies
-        run: |
-          curl -sSL https://install.python-poetry.org | python3 -
-          echo "$HOME/.local/bin" >> $GITHUB_PATH
-          sudo apt-get update
-          sudo apt-get install -y libfuse2
-        shell: bash
-
-      # Step 3: Clone LNbits Repository
-      - name: Clone LNbits
-        run: |
-          mv .github/packaging packaging
-          mkdir -p packaging/linux/AppDir/usr
-          git clone https://github.com/lnbits/lnbits.git packaging/linux/AppDir/usr/lnbits
-        shell: bash
-
-      # Step 4: Make the AppImage Asset
-      - name: Make Asset
-        run: |
-          cd packaging/linux/AppDir/usr/lnbits
-          poetry install
-          poetry run pip install pyinstaller
-
-          # Build the LNbits binary
-          poetry run pyinstaller --onefile --name lnbits --hidden-import=embit --collect-all embit --collect-all lnbits --collect-all sqlalchemy --collect-all aiosqlite --hidden-import=passlib.handlers.bcrypt $(poetry run which lnbits)
-          cd ../../../../..
-          chmod +x packaging/linux/AppDir/AppRun
-          chmod +x packaging/linux/AppDir/lnbits.desktop
-          chmod +x packaging/linux/AppDir/usr/lnbits/dist/lnbits
-
-          find packaging/linux/AppDir/usr/lnbits -mindepth 1 -maxdepth 1 \
-              ! -name 'dist' \
-              ! -name 'lnbits' \
-              -exec rm -rf {} +
-
-          wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage
-          chmod +x appimagetool-x86_64.AppImage
-          TAG_NAME=${{ github.event.release.tag_name }}
-          APPIMAGE_NAME="LNbits-${TAG_NAME}.AppImage"
-          ./appimagetool-x86_64.AppImage --updateinformation "gh-releases-zsync|lnbits|lnbits|latest|*.AppImage.zsync" packaging/linux/AppDir "$APPIMAGE_NAME"
-          chmod +x "$APPIMAGE_NAME"
-          echo "APPIMAGE_NAME=$APPIMAGE_NAME" >> $GITHUB_ENV
-        shell: bash
-
-      # Step 5: Upload Linux Release Asset
-      - name: Upload Linux Release Asset
-        uses: actions/upload-release-asset@v1
-        with:
-          upload_url: ${{ github.event.release.upload_url }}
-          asset_path: ${{ env.APPIMAGE_NAME }}
-          asset_name: ${{ env.APPIMAGE_NAME }}
-          asset_content_type: application/octet-stream
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/poetry.yml

@@ -0,0 +1,24 @@
+name: poetry
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        description: "python version"
+        type: string
+        default: "3.10"
+
+jobs:
+  poetry:
+    name: run poetry install to check lock file
+    runs-on: "ubuntu-24.04"
+    steps:
+      - uses: actions/checkout@v4
+      - name: set up python ${{ inputs.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ inputs.python-version }}
+      - name: install poetry
+        run: |
+          curl -sSL https://install.python-poetry.org | python3 -
+          poetry install

.github/workflows/regtest.yml

@@ -8,7 +8,7 @@ on:
         required: true
         type: string
       python-version:
-        default: "3.10"
+        default: "3.12"
         type: string
       os-version:
         default: "ubuntu-24.04"
@@ -32,39 +32,41 @@ jobs:
         run: |
           docker build -t lnbits/lnbits .
 
-      - name: Setup Regtest
-        run: |
-          git clone https://github.com/lnbits/legend-regtest-enviroment.git docker
-          cd docker
-          chmod +x ./tests
-          ./tests
-          sudo chmod -R a+rwx .
-
       - uses: ./.github/actions/prepare
         with:
           python-version: ${{ inputs.python-version }}
 
+      - name: Setup Regtest
+        run: |
+          cd docker/regtest
+          chmod +x ./start-regtest
+          ./start-regtest
+          sudo chmod -R a+rwx .
+
       - name: Run pytest
         uses: pavelzw/pytest-action@v2
         env:
           LNBITS_DATABASE_URL: ${{ inputs.db-url }}
           LNBITS_BACKEND_WALLET_CLASS: ${{ inputs.backend-wallet-class }}
           LND_REST_ENDPOINT: https://localhost:8081/
-          LND_REST_CERT: ./docker/data/lnd-3/tls.cert
-          LND_REST_MACAROON: ./docker/data/lnd-3/data/chain/bitcoin/regtest/admin.macaroon
+          LND_REST_CERT: ./docker/regtest/data/lnd-3/tls.cert
+          LND_REST_MACAROON: ./docker/regtest/data/lnd-3/data/chain/bitcoin/regtest/admin.macaroon
           LND_GRPC_ENDPOINT: localhost
           LND_GRPC_PORT: 10009
-          LND_GRPC_CERT: docker/data/lnd-3/tls.cert
-          LND_GRPC_MACAROON: docker/data/lnd-3/data/chain/bitcoin/regtest/admin.macaroon
-          CORELIGHTNING_RPC: ./docker/data/clightning-1/regtest/lightning-rpc
+          LND_GRPC_CERT: ./docker/regtest/data/lnd-3/tls.cert
+          LND_GRPC_MACAROON: ./docker/regtest/data/lnd-3/data/chain/bitcoin/regtest/admin.macaroon
+          CORELIGHTNING_RPC: ./docker/regtest/data/clightning-1/regtest/lightning-rpc
           CORELIGHTNING_REST_URL: https://localhost:3001
-          CORELIGHTNING_REST_MACAROON: ./docker/data/clightning-2-rest/access.macaroon
-          CORELIGHTNING_REST_CERT: ./docker/data/clightning-2-rest/certificate.pem
+          CORELIGHTNING_REST_MACAROON: ./docker/regtest/data/clightning-2-rest/access.macaroon
+          CORELIGHTNING_REST_CERT: ./docker/regtest/data/clightning-2-rest/certificate.pem
           LNBITS_ENDPOINT: http://localhost:5001
           LNBITS_KEY: "d08a3313322a4514af75d488bcc27eee"
           ECLAIR_URL: http://127.0.0.1:8082
+          BOLTZ_CLIENT_ENDPOINT: 127.0.0.1:9002
+          BOLTZ_MNEMONIC: abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
           LNBITS_MAX_OUTGOING_PAYMENT_AMOUNT_SATS: 1000000000
           LNBITS_MAX_INCOMING_PAYMENT_AMOUNT_SATS: 1000000000
+          LNBITS_FUNDING_SOURCE_PAY_INVOICE_WAIT_SECONDS: ${{ inputs.backend-wallet-class == 'CoreLightningRestWallet' && 60 || 5 }}
           ECLAIR_PASS: lnbits
           PYTHONUNBUFFERED: 1
           DEBUG: true

.github/workflows/release-rc.yml

@@ -3,14 +3,37 @@ name: release-rc
 on:
   push:
     tags:
-      - "*-rc[0-9]"
+      - "*-rc[0-9]+"
 
 permissions:
   contents: write
 
 jobs:
 
+  release:
+    runs-on: ubuntu-24.04
+    outputs:
+      upload_url: ${{ steps.get_upload_url.outputs.upload_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create github pre-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref_name }}
+        run: |
+          gh release create "$tag" --prerelease --generate-notes --draft
+      - id: get_upload_url
+        name: Get upload url of Github release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref_name }}
+        run: |
+          upload_url=$(gh release view "$tag" --json uploadUrl -q ".uploadUrl")
+          echo "upload_url=$upload_url" >> "$GITHUB_OUTPUT"
+
   docker:
+    if: github.repository == 'lnbits/lnbits'
+    needs: [ release ]
     uses: ./.github/workflows/docker.yml
     with:
       tag: ${{ github.ref_name }}
@@ -18,15 +41,37 @@ jobs:
       DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
       DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
 
+  docker-latest-rc:
+    if: github.repository == 'lnbits/lnbits'
+    needs: [ release ]
+    uses: ./.github/workflows/docker.yml
+    with:
+      tag: latest-rc
+    secrets:
+      DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+      DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+
   pypi:
+    if: github.repository == 'lnbits/lnbits'
     runs-on: ubuntu-24.04
     steps:
-      - name: Install dependencies for building secp256k1
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y build-essential automake libtool libffi-dev libgmp-dev
       - uses: actions/checkout@v4
-      - name: Build and publish to pypi
-        uses: JRubics/poetry-publish@v1.15
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
         with:
-          pypi_token: ${{ secrets.PYPI_API_KEY }}
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build the project
+        run: uv build
+      - name: Publish to pypi
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_KEY }}
+        run: uv publish
+
+  appimage:
+    needs: [ release ]
+    uses: ./.github/workflows/appimage.yml
+    with:
+      tag_name: ${{ github.ref_name }}
+      upload_url: ${{ needs.release.outputs.upload_url }}

.github/workflows/release.yml

@@ -13,6 +13,8 @@ jobs:
 
   release:
     runs-on: ubuntu-24.04
+    outputs:
+      upload_url: ${{ steps.get_upload_url.outputs.upload_url }}
     steps:
       - uses: actions/checkout@v4
       - name: Create github release
@@ -21,8 +23,17 @@ jobs:
           tag: ${{ github.ref_name }}
         run: |
           gh release create "$tag" --generate-notes --draft
+      - id: get_upload_url
+        name: Get upload url of Github release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref_name }}
+        run: |
+          upload_url=$(gh release view "$tag" --json uploadUrl -q ".uploadUrl")
+          echo "upload_url=$upload_url" >> "$GITHUB_OUTPUT"
 
   docker:
+    if: github.repository == 'lnbits/lnbits'
     needs: [ release ]
     uses: ./.github/workflows/docker.yml
     with:
@@ -32,6 +43,7 @@ jobs:
       DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
 
   docker-latest:
+    if: github.repository == 'lnbits/lnbits'
     needs: [ release ]
     uses: ./.github/workflows/docker.yml
     with:
@@ -40,15 +52,37 @@ jobs:
       DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
       DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
 
+  docker-latest-rc:
+    if: github.repository == 'lnbits/lnbits'
+    needs: [ release ]
+    uses: ./.github/workflows/docker.yml
+    with:
+      tag: latest-rc
+    secrets:
+      DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+      DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+
   pypi:
+    if: github.repository == 'lnbits/lnbits'
     runs-on: ubuntu-24.04
     steps:
-      - name: Install dependencies for building secp256k1
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y build-essential automake libtool libffi-dev libgmp-dev
       - uses: actions/checkout@v4
-      - name: Build and publish to pypi
-        uses: JRubics/poetry-publish@v1.15
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
         with:
-          pypi_token: ${{ secrets.PYPI_API_KEY }}
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build the project
+        run: uv build
+      - name: Publish to pypi
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_KEY }}
+        run: uv publish
+
+  appimage:
+    needs: [ release ]
+    uses: ./.github/workflows/appimage.yml
+    with:
+      tag_name: ${{ github.ref_name }}
+      upload_url: ${{ needs.release.outputs.upload_url }}

.github/workflows/tests.yml

@@ -8,7 +8,7 @@ on:
         required: true
         type: string
       python-version:
-        default: "3.10"
+        default: "3.12"
         type: string
       os-version:
         default: "ubuntu-24.04"

.gitignore

@@ -6,7 +6,9 @@ __pycache__
 *$py.class
 .mypy_cache
 .vscode
+.codex
 *-lock.json
+.python-version
 
 *.egg
 *.egg-info
@@ -41,7 +43,6 @@ lnbits/static/bundle.min.js.old
 lnbits/static/bundle.min.css.old
 lnbits/static/bundle-components.min.js.old
 lnbits/upgrades
-docker
 
 # Nix
 *result*
@@ -60,3 +61,4 @@ dist
 
 # jetbrains
 .idea
+.venv

.npmrc

@@ -0,0 +1 @@
+min-release-age=7

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ exclude: '^lnbits/static/bundle.*|^docs/.*|^lnbits/static/vendor/.*|^lnbits/exte
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -14,16 +14,16 @@ repos:
       - id: mixed-line-ending
       - id: check-case-conflict
   - repo: https://github.com/psf/black
-    rev: 24.2.0
+    rev: 26.3.1
     hooks:
       - id: black
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.3.2
+    rev: v0.14.10
     hooks:
       - id: ruff
         args: [ --fix, --exit-non-zero-on-fix ]
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: "v4.0.0-alpha.8"
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.7.4
     hooks:
       - id: prettier
         types_or: [css, javascript, html, json]

AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md - AI Coding Agent Guide for LNbits
+
+This file guides AI coding agents working on LNbits. Keep changes small, verified, and aligned with existing project patterns.
+
+## Core Behavior
+
+- Think before coding. State material assumptions. Ask when ambiguity affects correctness, security, payments, wallets, or data migrations.
+- Prefer the simplest implementation that solves the request.
+- Make surgical changes. Every changed line should trace back to the task.
+- Do not refactor, reformat, rename, or clean adjacent code unless required.
+- Remove only dead code or imports created by your own changes.
+- Define success criteria for non-trivial work and verify them before reporting done.
+
+## LNbits Architecture
+
+- Keep core lean. Prefer/assess extensions for non-core features.
+- Preserve compatibility with existing extensions and wallet backends.
+- Follow existing patterns in `lnbits/core`, `lnbits/wallets`, `lnbits/extensions`, and frontend code.
+- Use existing CRUD, services, settings, and migration patterns.
+- Do not edit generated files, bundled vendor files, or unrelated extension code.
+
+## Security-Sensitive Areas
+
+Be extra cautious with payments, wallet balances, admin routes, keys, LNURL, Bolt11, funding sources, migrations, and authentication.
+
+Do not expose raw stack traces or sensitive values. Do not add synchronous blocking work in hot async paths without justification.
+
+## Commands and Verification
+
+Read `Makefile` before running project commands.
+
+Use Makefile targets instead of hand-written commands when available:
+
+- `make check` for full checks.
+- `make test-unit` for unit tests.
+- `make test-api` for API tests.
+- `make test-wallets` for wallet tests.
+- `make checkbundle` when bundled frontend assets may be affected.
+- `make format` only when formatting is intended.
+
+Do not run `make test` by default. Use the targeted tests available in the Makefile that are related to the work done, unless the user explicitly asks for broader test coverage.
+
+## Dependencies
+
+Do not add dependencies without approval. If approved, update the correct project files and explain why the dependency is necessary.
+
+## Maintenance
+
+LNbits maintainers own this file. They should update it when the development workflow, architecture, or verification commands materially change.
+
+Do not edit, commit, push, or include changes to this file in a PR as part of normal feature work unless the user explicitly asks for `AGENTS.md` changes.
+
+## Reporting
+
+When finished, report:
+
+- Summary of what changed.
+- Files touched.
+- Makefile targets or checks run.
+- Anything not verified and why.

Dockerfile

@@ -2,24 +2,20 @@ FROM python:3.12-slim-bookworm AS builder
 
 RUN apt-get clean
 RUN apt-get update
-RUN apt-get install -y curl pkg-config build-essential libnss-myhostname
+RUN apt-get install -y curl pkg-config build-essential libnss-myhostname automake
 
-RUN curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
 ENV PATH="/root/.local/bin:$PATH"
 
 WORKDIR /app
 
 # Only copy the files required to install the dependencies
-COPY pyproject.toml poetry.lock ./
+COPY pyproject.toml uv.lock ./
+RUN touch README.md
 
 RUN mkdir data
 
-ENV POETRY_NO_INTERACTION=1 \
-    POETRY_VIRTUALENVS_IN_PROJECT=1 \
-    POETRY_VIRTUALENVS_CREATE=1 \
-    POETRY_CACHE_DIR=/tmp/poetry_cache
-
-RUN poetry install --only main
+RUN uv sync --all-extras
 
 FROM python:3.12-slim-bookworm
 
@@ -32,25 +28,19 @@ RUN apt-get update && apt-get -y upgrade && \
     apt-get -y install postgresql-client-14 postgresql-client-common && \
     apt-get clean all && rm -rf /var/lib/apt/lists/*
 
-RUN curl -sSL https://install.python-poetry.org | python3 - --version 1.8.5
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
 ENV PATH="/root/.local/bin:$PATH"
 
-ENV POETRY_NO_INTERACTION=1 \
-    POETRY_VIRTUALENVS_IN_PROJECT=1 \
-    POETRY_VIRTUALENVS_CREATE=1 \
-    VIRTUAL_ENV=/app/.venv \
-    PATH="/app/.venv/bin:$PATH"
-
 WORKDIR /app
 
 COPY . .
 COPY --from=builder /app/.venv .venv
 
-RUN poetry install --only main
+RUN uv sync --all-extras
 
 ENV LNBITS_PORT="5000"
 ENV LNBITS_HOST="0.0.0.0"
 
 EXPOSE 5000
 
-CMD ["sh", "-c", "poetry run lnbits --port $LNBITS_PORT --host $LNBITS_HOST"]
+CMD ["sh", "-c", "uv --offline run lnbits --port $LNBITS_PORT --host $LNBITS_HOST --forwarded-allow-ips='*'"]

Makefile

@@ -9,34 +9,34 @@ check: mypy pyright checkblack checkruff checkprettier checkbundle
 test: test-unit test-wallets test-api test-regtest
 
 prettier:
-	poetry run ./node_modules/.bin/prettier --write .
+	uv run ./node_modules/.bin/prettier --write .
 
 pyright:
-	poetry run ./node_modules/.bin/pyright
+	uv run ./node_modules/.bin/pyright
 
 mypy:
-	poetry run mypy
+	uv run mypy
 
 black:
-	poetry run black .
+	uv run black .
 
 ruff:
-	poetry run ruff check . --fix
+	uv run ruff check . --fix
 
 checkruff:
-	poetry run ruff check .
+	uv run ruff check .
 
 checkprettier:
-	poetry run ./node_modules/.bin/prettier --check .
+	uv run ./node_modules/.bin/prettier --check .
 
 checkblack:
-	poetry run black --check .
+	uv run black --check .
 
 checkeditorconfig:
 	editorconfig-checker
 
 dev:
-	poetry run lnbits --reload
+	uv run lnbits --reload
 
 docker:
 	docker build -t lnbits/lnbits .
@@ -46,27 +46,28 @@ test-wallets:
 	LNBITS_BACKEND_WALLET_CLASS="FakeWallet" \
 	PYTHONUNBUFFERED=1 \
 	DEBUG=true \
-	poetry run pytest tests/wallets
+	uv run pytest tests/wallets
 
 test-unit:
 	LNBITS_DATA_FOLDER="./tests/data" \
 	LNBITS_BACKEND_WALLET_CLASS="FakeWallet" \
 	PYTHONUNBUFFERED=1 \
 	DEBUG=true \
-	poetry run pytest tests/unit
+	uv run pytest tests/unit
 
 test-api:
 	LNBITS_DATA_FOLDER="./tests/data" \
 	LNBITS_BACKEND_WALLET_CLASS="FakeWallet" \
 	PYTHONUNBUFFERED=1 \
 	DEBUG=true \
-	poetry run pytest tests/api
+	uv run pytest tests/api
 
 test-regtest:
 	LNBITS_DATA_FOLDER="./tests/data" \
 	PYTHONUNBUFFERED=1 \
 	DEBUG=true \
-	poetry run pytest tests/regtest
+	rm -rf ./tests/data \
+	uv run pytest tests/regtest
 
 test-migration:
 	LNBITS_ADMIN_UI=True \
@@ -74,18 +75,18 @@ test-migration:
 	HOST=0.0.0.0 \
 	PORT=5002 \
 	LNBITS_DATA_FOLDER="./tests/data" \
-	timeout 5s poetry run lnbits --host 0.0.0.0 --port 5002 || code=$?; if [[ $code -ne 124 && $code -ne 0 ]]; then exit $code; fi
+	timeout 5s uv run lnbits --host 0.0.0.0 --port 5002 || code=$?; if [[ $code -ne 124 && $code -ne 0 ]]; then exit $code; fi
 	HOST=0.0.0.0 \
 	PORT=5002 \
 	LNBITS_DATABASE_URL="postgres://lnbits:lnbits@localhost:5432/migration" \
 	LNBITS_ADMIN_UI=False \
-	timeout 5s poetry run lnbits --host 0.0.0.0 --port 5002 || code=$?; if [[ $code -ne 124 && $code -ne 0 ]]; then exit $code; fi
+	timeout 5s uv run lnbits --host 0.0.0.0 --port 5002 || code=$?; if [[ $code -ne 124 && $code -ne 0 ]]; then exit $code; fi
 	LNBITS_DATA_FOLDER="./tests/data" \
 	LNBITS_DATABASE_URL="postgres://lnbits:lnbits@localhost:5432/migration" \
-	poetry run python tools/conv.py
+	uv run python tools/conv.py
 
 migration:
-	poetry run python tools/conv.py
+	uv run python tools/conv.py
 
 openapi:
 	LNBITS_ADMIN_UI=False \
@@ -94,9 +95,9 @@ openapi:
 	PYTHONUNBUFFERED=1 \
 	HOST=0.0.0.0 \
 	PORT=5003 \
-	poetry run lnbits &
+	uv run lnbits &
 	sleep 15
-	curl -s http://0.0.0.0:5003/openapi.json | poetry run openapi-spec-validator --errors=all -
+	curl -s http://0.0.0.0:5003/openapi.json | uv run openapi-spec-validator --errors=all -
 	# kill -9 %1
 
 bak:
@@ -109,7 +110,7 @@ sass:
 bundle:
 	npm install
 	npm run bundle
-	poetry run ./node_modules/.bin/prettier -w ./lnbits/static/vendor.json
+	uv run ./node_modules/.bin/prettier -w ./lnbits/static/vendor.json
 
 checkbundle:
 	cp lnbits/static/bundle.min.js lnbits/static/bundle.min.js.old
@@ -126,8 +127,8 @@ checkbundle:
 
 install-pre-commit-hook:
 	@echo "Installing pre-commit hook to git"
-	@echo "Uninstall the hook with poetry run pre-commit uninstall"
-	poetry run pre-commit install
+	@echo "Uninstall the hook with uv run pre-commit uninstall"
+	uv run pre-commit install
 
 pre-commit:
-	poetry run pre-commit run --all-files
+	uv run pre-commit run --all-files

README.md

@@ -1,44 +1,52 @@
-<picture >
-  <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/QE6SIrs.png"  style="width:300px">
-  <img src="https://i.imgur.com/fyKPgVT.png" style="width:300px">
-</picture>
+<a href="https://lnbits.com" target="_blank" rel="noopener noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/logos/lnbits-full-inverse.svg">
+    <img src="docs/logos/lnbits-full.svg" alt="LNbits" style="width:300px">
+  </picture>
+</a>
 
-![phase: beta](https://img.shields.io/badge/phase-beta-C41E3A) [![license-badge]](LICENSE) [![docs-badge]][docs] ![PRs: welcome](https://img.shields.io/badge/PRs-Welcome-08A04B) [<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits) [<img src="https://img.shields.io/badge/supported_by-%3E__OpenSats-f97316">](https://opensats.org)
-![Lightning network wallet](https://i.imgur.com/DeIiO0y.png)
+![phase: stable](https://img.shields.io/badge/phase-stable-2EA043) [![license-badge]](LICENSE) [![docs-badge]][docs] ![PRs: welcome](https://img.shields.io/badge/PRs-Welcome-yellow) [![explore: LNbits extensions](https://img.shields.io/badge/explore-LNbits%20extensions-10B981)](https://extensions.lnbits.com/) [![hardware: LNBitsShop](https://img.shields.io/badge/hardware-LNBitsShop-7C3AED)](https://shop.lnbits.com/) [<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits)  
+<img alt="lnbits_head" src="docs/assets/header.jpg" />  
+[![tip-hero](https://img.shields.io/badge/TipJar-LNBits%20Hero-9b5cff?labelColor=6b7280&logo=lightning&logoColor=white)](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg)
 
-# The world's most powerful suite of bitcoin tools.
+# LNbits — The most powerful Bitcoin & Lightning toolkit
 
-## Run for yourself, for others, or as part of a stack.
+> Run it for yourself, for your community, or as part of a larger stack.
 
-LNbits is beta, for responsible disclosure of any concerns please contact an admin in the community chat.
+## What is LNbits?
 
-LNbits is a Python server that sits on top of any funding source. It can be used as:
+LNbits is a lightweight Python server that sits on top of your Lightning funding source. It gives you safe, isolated wallets, a clean API, and an extension system for rapidly adding features - without locking you into a single node implementation. The Inspiration for LNBits came from ideas pioneered by **OpenNode** and **LNPay** — both today work as funding sources for LNbits.
 
-- Accounts system to mitigate the risk of exposing applications to your full balance via unique API keys for each wallet
-- Extendable platform for exploring Lightning network functionality via the LNbits extension framework
-- Part of a development stack via LNbits API
-- Fallback wallet for the LNURL scheme
-- Instant wallet for LN demonstrations
+## What you can do with LNbits
 
-LNbits can run on top of almost all Lightning funding sources.
+- **Harden app security:** Create per-wallet API keys so individual apps never touch your full balance.
+- **Extend functionality fast:** Install extensions to explore and ship Lightning features with minimal code.
+- **Build into your stack:** Use the LNbits HTTP API to integrate payments, wallets, and accounting.
+- **Cover LNURL flows:** Use LNbits as a reliable fallback wallet for LNURL.
+- **Demo in minutes:** Spin up instant wallets for workshops, proofs-of-concept, and user testing.
 
-See [LNbits manual](https://docs.lnbits.org/guide/wallets.html) for more detailed documentation about each funding source.
+## Funding sources
 
-Checkout the LNbits [YouTube](https://www.youtube.com/playlist?list=PLPj3KCksGbSYG0ciIQUWJru1dWstPHshe) video series.
+LNbits runs on top of most Lightning backends. Choose the one you already operate - or swap later without changing your app architecture.
 
-LNbits is inspired by all the great work of [opennode.com](https://www.opennode.com/), and in particular [lnpay.co](https://lnpay.co/). Both work as funding sources for LNbits.
+- Read the [funding source guide](https://docs.lnbits.org/guide/wallets.html)
+
+## Learn more
+
+- Video series on [Youtube](https://www.youtube.com/@lnbits)
+- Introduction Video [LNBits V1](https://www.youtube.com/watch?v=PFAHKxvgI9Y&t=19s)
 
 ## Running LNbits
 
-Test on our demo server [demo.lnbits.com](https://demo.lnbits.com), or on [lnbits.com](https://lnbits.com) software as a service, where you can spin up an LNbits instance for 21sats per hr.
-
 See the [install guide](https://github.com/lnbits/lnbits/blob/main/docs/guide/installation.md) for details on installation and setup.
 
+Get yourself familiar and test on our demo server [demo.lnbits.com](https://demo.lnbits.com), or on [lnbits.com](https://lnbits.com) software as a service, where you can spin up an LNbits instance for 21sats per hr.
+
 ## LNbits account system
 
 LNbits is packaged with tools to help manage funds, such as a table of transactions, line chart of spending, export to csv. Each wallet also comes with its own API keys, to help partition the exposure of your funding source.
 
-<img src="https://i.imgur.com/w8jdGpF.png" style="width:800px">
+<img alt="lnbits_wallet" src="docs/assets/wallet.jpg" />
 
 ## LNbits extension universe
 
@@ -46,29 +54,35 @@ Extend YOUR LNbits to meet YOUR needs.
 
 All non-core features are installed as extensions, reducing your code base and making your LNbits unique to you. Extend your LNbits install in any direction, and even create and share your own extensions.
 
-<img src="https://i.imgur.com/aEBpwJF.png" style="width:800px">
+<img alt="lnbits_extensions" src="docs/assets/extensions.jpg" />
 
 ## LNbits API
 
 LNbits has a powerful API, many projects use LNbits to do the heavy lifting for their bitcoin/lightning services.
 
-<img src="https://i.imgur.com/V742sb9.png" style="width:800px">
+<img alt="lnbits_api" src="docs/assets/api.jpg" />
 
 ## LNbits node manager
 
 LNbits comes packaged with a light node management UI, to make running your node that much easier.
 
-<img src="https://i.imgur.com/TYqIK60.png" style="width:800px">
+<img alt="lnbits_api" src="docs/assets/lightning_node.jpg" />
 
-## LNbits across all your devices
+## LNbits merchant tools
 
-As well as working great in a browser, LNbits has native IoS and Android apps as well as a chrome extension. So you can enjoy the same UI across ALL your devices.
+The LNbits stack can process both bitcoin and fiat payments, making it a turnkey, all-in-one solution for merchants. With orders and inventory shared across extensions, and built-in notifications for Nostr, Telegram, and email, LNbits keeps everything in sync, freeing merchants to focus on their business.
 
-<img src="https://i.imgur.com/J96EbRf.png" style="width:800px">
+<img alt="lnbits_merchants" src="docs/assets/merchants_small.webp" />
 
-## Tip us
+## Powered by LNbits
 
-If you like this project [send some tip love](https://demo.lnbits.com/lnurlp/link/fH59GD)!
+LNbits empowers everyone with modular, open-source tools for building Bitcoin-based systems — fast, free, and extendable.
+
+[![LNbits Shop](https://demo.lnbits.com/static/images/bitcoin-shop-banner.png)](https://shop.lnbits.com/)  
+[![Visit LNbits Shop](https://img.shields.io/badge/Visit-LNbits%20Shop-7C3AED?logo=shopping-cart&logoColor=white&labelColor=5B21B6)](https://shop.lnbits.com/)
+[![Try myLNbits SaaS](https://img.shields.io/badge/Try-myLNbits%20SaaS-2563EB?logo=lightning&logoColor=white&labelColor=1E40AF)](https://my.lnbits.com/login)
+[![Read LNbits News](https://img.shields.io/badge/Read-LNbits%20News-F97316?logo=rss&logoColor=white&labelColor=C2410C)](https://news.lnbits.com/)
+[![Explore LNbits Extensions](https://img.shields.io/badge/Explore-LNbits%20Extensions-10B981?logo=puzzle-piece&logoColor=white&labelColor=065F46)](https://extensions.lnbits.com/) [![tip-hero](https://img.shields.io/badge/TipJar-LNBits%20Hero-9b5cff?labelColor=7c3aed&logo=lightning&logoColor=white)](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg)
 
 [docs]: https://github.com/lnbits/lnbits/wiki
 [docs-badge]: https://img.shields.io/badge/docs-lnbits.org-673ab7.svg

docker/boltzclient/Dockerfile

@@ -0,0 +1,34 @@
+ARG LNBITS_TAG=latest
+
+FROM boltz/boltz-client:latest AS boltz
+FROM lnbits/lnbits:${LNBITS_TAG}
+
+COPY --from=boltz /bin/boltzd /bin/boltzcli /usr/local/bin/
+RUN ls -l /usr/local/bin/boltzd
+RUN apt-get update && apt-get -y upgrade && \
+    apt-get install -y netcat-openbsd
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
+
+# Reinstall dependencies just in case (needed for CMD usage)
+RUN uv sync --all-extras
+
+# LNbits
+ENV LNBITS_PORT="5000"
+ENV LNBITS_HOST="0.0.0.0"
+ENV LNBITS_BACKEND_WALLET_CLASS="BoltzWallet"
+ENV FUNDING_SOURCE_MAX_RETRIES="10"
+
+# Boltzd
+ENV BOLTZ_CLIENT_ENDPOINT="127.0.0.1:9002"
+ENV BOLTZ_CLIENT_MACAROON="/root/.boltz/macaroons/admin.macaroon"
+ENV BOLTZ_CLIENT_CERT="/root/.boltz/tls.cert"
+ENV BOLTZ_CLIENT_WALLET="lnbits"
+
+EXPOSE 5000
+
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+CMD ["/entrypoint.sh"]

docker/boltzclient/entrypoint.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e
+
+boltzd --standalone --referralId lnbits &
+
+# Capture boltzd PID to monitor if needed
+BOLTZ_PID=$!
+
+# Wait for boltzd to start
+for i in {1..10}; do
+  if nc -z localhost 9002; then
+    echo "boltzd is up!"
+    break
+  fi
+  echo "Waiting for boltzd to start..."
+  sleep 1
+done
+
+# Optional: check if still not up
+if ! nc -z localhost 9002; then
+  echo "boltzd did not start successfully."
+  exit 1
+fi
+
+echo "Starting LNbits on $LNBITS_HOST:$LNBITS_PORT..."
+exec uv run lnbits --port "$LNBITS_PORT" --host "$LNBITS_HOST" --forwarded-allow-ips='*'

docker/regtest/.gitignore

@@ -0,0 +1,18 @@
+!data
+data/*
+
+!data/boltz
+data/boltz/*
+!data/boltz/boltz.conf
+
+!data/boltz-client
+data/boltz-client/*
+!data/boltz-client/boltz.toml
+
+!data/boltz-nginx
+data/boltz-nginx/*
+!data/boltz-nginx/default.conf
+
+!data/eclair
+data/eclair/*
+!data/eclair/eclair.conf

docker/regtest/README.md

@@ -0,0 +1,99 @@
+![TESTS](https://github.com/lnbits/legend-regtest-enviroment/actions/workflows/ci.yml/badge.svg)
+
+# nodes
+
+- lnd-1: for locally testing your current lnbits
+- lnd-2: used for boltz backend
+- lnd-3: used for lnbits inside docker
+- cln-1: for locally testing your current lnbits
+- cln-2: used for clightning-REST
+- eclair-1: for locally testing your current lnbits
+
+# Installing regtest
+
+get the regtest enviroment ready
+
+```sh
+# Install docker https://docs.docker.com/engine/install/
+# Make sure your user has permission to use docker 'sudo usermod -aG docker ${USER}' then reboot
+# Stop/start docker 'sudo systemctl stop docker' 'sudo systemctl start docker'
+
+sudo apt install jq
+git clone https://github.com/lnbits/lnbits.git
+cd lnbits
+docker build -t lnbits/lnbits .
+mkdir docker
+git clone https://github.com/lnbits/legend-regtest-enviroment.git docker
+cd docker
+chmod +x ./start-regtest
+./start-regtest # start the regtest and also run tests
+sudo chown -R $USER ./data # Give the data file permissions for user
+```
+
+# Running LNbits on regtest
+
+add this ENV variables to your `.env` file
+
+```sh
+DEBUG=true
+
+# LND
+LNBITS_BACKEND_WALLET_CLASS="LndRestWallet"
+LND_REST_ENDPOINT=https://127.0.0.1:8081/
+LND_REST_CERT=/home/user/repos/lnbits/docker/data/lnd-1/tls.cert
+LND_REST_MACAROON=/home/user/repos/lnbits/docker/data/lnd-1/data/chain/bitcoin/regtest/admin.macaroon
+
+# CLN
+LNBITS_BACKEND_WALLET_CLASS="CoreLightningWallet"
+CORELIGHTNING_RPC=./docker/data/clightning-1/regtest/lightning-rpc
+
+
+# Run LNbits
+uv run lnbits
+
+# Run LNbits with hot reload
+make dev
+```
+
+# testing
+
+```sh
+chmod +x ./start-regtest
+./start-regtest
+# short answer :)
+./start-regtest && echo "PASSED" || echo "FAILED" > /dev/null
+```
+
+usage of the `bitcoin-cli-sim`, `lightning-cli-sim` and `lncli-sim` aliases
+
+```sh
+cd ~/lnbits/docker
+source docker-scripts.sh
+# use bitcoin core, mine a block
+bitcoin-cli-sim -generate 1
+
+# use c-lightning nodes
+lightning-cli-sim 1 newaddr | jq -r '.bech32' # use node 1
+lightning-cli-sim 2 getinfo # use node 2
+lightning-cli-sim 3 getinfo # use node 3
+
+# use lnd nodes
+lncli-sim 1 newaddr p2wsh
+lncli-sim 2 listpeers
+```
+
+# urls
+
+- mempool: http://localhost:8080/
+- boltz api: http://localhost:9001/
+- lnd-1 rest: http://localhost:8081/
+- lnbits: http://localhost:5001/
+
+# debugging docker logs
+
+```sh
+docker logs lnbits-lnbits-1 -f
+docker logs lnbits-boltz-1 -f
+docker logs lnbits-clightning-1-1 -f
+docker logs lnbits-lnd-2-1 -f
+```

docker/regtest/data/boltz-client/boltz.toml

@@ -0,0 +1,49 @@
+standalone = true
+network = "regtest"
+
+# Path the the log file
+logfile = ""
+
+electrumUrl = "electrs:19001"
+electrumLiquidUrl = "electrs-liquid:19002"
+
+[BOLTZ]
+# By default the daemon automatically connects to the official Boltz instance for the network LND is on
+# This value is used to override that
+url = "http://boltz-nginx:9001"
+
+[DATABASE]
+# Path to the SQLite database file
+# path = "/home/michael/test.db"
+
+[RPC]
+# Host of
+host = "0.0.0.0"
+
+# Port of the gRPC interface
+port = 9002
+
+# Whether the REST proxy for the gRPC interface should be disabled
+restDisabled = false
+
+# Host of the REST proxy
+restHost = "0.0.0.0"
+
+# Port of the REST proxy
+restPort = 9003
+
+# Path to the TLS cert for the gRPC and REST interface
+tlsCert = ""
+
+# Path to the TLS private key for the gRPC and REST interface
+tlsKey = ""
+noTls = true
+
+# Whether the macaroon authentication for the gRPC and REST interface should be disabled
+noMacaroons = true
+
+# Path to the admin macaroon for the gRPC and REST interface
+adminMacaroonPath = ""
+
+# Path to the read only macaroon for the gRPC and REST interface
+readOnlyMacaroonPath = ""

docker/regtest/data/boltz-nginx/default.conf

@@ -0,0 +1,49 @@
+upstream boltz {
+    server boltz:9001;
+}
+
+upstream boltzr {
+    server boltz:9005;
+}
+
+upstream ws {
+    server boltz:9004;
+}
+
+server {
+    listen 9001;
+    listen [::]:9001;
+    server_name localhost;
+
+    add_header Access-Control-Allow-Origin "*" always;
+    add_header Access-Control-Allow-Methods 'GET, PATCH, DELETE, POST, OPTIONS' always;
+    add_header Access-Control-Allow-Headers "*" always;
+
+    proxy_set_header Host $http_host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    if ($request_method = OPTIONS) {
+        return 204;
+    }
+
+    location /v2/ws {
+        proxy_pass http://ws/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "Upgrade";
+    }
+
+    location ~ ^/v2/(lightning|swap/rescue|swap/restore) {
+        proxy_pass http://boltzr;
+    }
+
+    location /streamswapstatus {
+        proxy_pass http://boltzr;
+    }
+
+    location / {
+        proxy_pass http://boltz;
+    }
+}

docker/regtest/data/boltz/boltz.conf

@@ -0,0 +1,114 @@
+[api]
+host = "0.0.0.0"
+port = 9_001
+
+[grpc]
+host = "0.0.0.0"
+port = 9_000
+
+[postgres]
+host = "boltz-postgres"
+port = 5432
+database = "boltz"
+username = "boltz"
+password = "boltz"
+
+[sidecar]
+  [sidecar.grpc]
+  host = "127.0.0.1"
+  port = 9003
+
+  [sidecar.ws]
+  host = "0.0.0.0"
+  port = 9004
+
+  [sidecar.api]
+  host = "0.0.0.0"
+  port = 9005
+
+[swap]
+deferredClaimSymbols = ["BTC", "L-BTC"]
+
+[[pairs]]
+base = "BTC"
+quote = "BTC"
+rate = 1
+fee = 0.5
+swapInFee = 0.1
+maxSwapAmount = 40_294_967
+minSwapAmount = 50_000
+
+  [pairs.timeoutDelta]
+  chain = 1440
+  reverse = 1440
+  swapMinimal = 1440
+  swapMaximal = 2880
+  swapTaproot = 10080
+
+[[pairs]]
+base = "L-BTC"
+quote = "BTC"
+fee = 0.25
+swapInFee = 0.1
+rate = 1
+maxSwapAmount = 40_294_967
+minSwapAmount = 100
+
+  [pairs.submarineSwap]
+  minSwapAmount = 1_000
+  minBatchedAmount = 21
+
+  [pairs.chainSwap]
+  minSwapAmount = 25_000
+
+  [pairs.timeoutDelta]
+  chain = 1440
+  reverse = 1440
+  swapMinimal = 1440
+  swapMaximal = 2880
+  swapTaproot = 10080
+
+[[currencies]]
+symbol = "BTC"
+network = "bitcoinRegtest"
+minWalletBalance = 10_000_000
+minChannelBalance = 10_000_000
+maxSwapAmount = 40_294_967
+minSwapAmount = 10_000
+maxZeroConfAmount = 0
+
+  [currencies.chain]
+  # mempoolSpace = "http://mempool-web:8090/api"
+  host = "bitcoind"
+  zmqpubrawtx = "tcp://bitcoind:29000"
+  zmqpubrawblock = "tcp://bitcoind:29001"
+  port = 18_443
+  cookie = "/root/.bitcoin/regtest/.cookie"
+  feeFloor = 0.2
+
+  wallet = "lnbits"
+
+  [currencies.lnd]
+  host = "lnd-2"
+  port = 10_009
+  certpath = "/data/lnd/tls.cert"
+  macaroonpath = "/data/lnd/data/chain/bitcoin/regtest/admin.macaroon"
+
+
+[liquid]
+symbol = "L-BTC"
+network = "liquidRegtest"
+
+maxSwapAmount = 40_294_967
+minSwapAmount = 10_000
+maxZeroConfAmount = 40_294_967
+
+
+  [liquid.chain]
+  host = "elementsd"
+  port = 18884
+  cookie = "/root/.elements/liquidregtest/.cookie"
+  zmqpubrawtx = "tcp://elementsd:31000"
+  zmqpubhashblock = "tcp://elementsd:31002"
+
+  wallet = "lnbits"

docker/regtest/data/eclair/eclair.conf

@@ -0,0 +1,28 @@
+eclair {
+  chain = "regtest"
+
+  api {
+    binding-ip = "0.0.0.0"
+    enabled = true
+    port = 8080
+    password = "lnbits"
+  }
+
+  bitcoind {
+    host = "bitcoind"
+    rpcport = 18443
+    auth = "safecookie"
+    cookie = "/root/.bitcoin/regtest/.cookie"
+
+    zmqblock = "tcp://bitcoind:29002"
+    zmqtx = "tcp://bitcoind:29000"
+  }
+
+  channel {
+    max-funding-satoshis = 10000000000
+  }
+
+  features {
+    option_support_large_channel = mandatory
+  }
+}

docker/regtest/docker-compose.yml

@@ -0,0 +1,434 @@
+services:
+
+  lnbits:
+    hostname: lnbits
+    depends_on:
+      - lnd-3
+    image: lnbits/lnbits
+    restart: on-failure
+    user: "0:0"
+    environment:
+      LNBITS_PORT: 5001
+      DEBUG: true
+      LNBITS_ADMIN_UI: false
+      LNBITS_BACKEND_WALLET_CLASS: "LndRestWallet"
+      LNBITS_DATA_FOLDER: "./data"
+      LND_REST_ENDPOINT: "https://lnd-3:8081/"
+      LND_REST_CERT: "./lnd/tls.cert"
+      LND_REST_MACAROON: "./lnd/data/chain/bitcoin/regtest/admin.macaroon"
+    ports:
+      - 5001:5001
+    volumes:
+      - lnbits-data:/app/data
+      - ./data/lnd-3:/app/lnd:uid=1000,gid=1000
+
+  boltz:
+    hostname: boltz
+    depends_on:
+      - lnd-2
+      - boltz-postgres
+    restart: always
+    image: boltz/boltz:v3.12.1
+    ports:
+      - 9000:9000
+    entrypoint: "sh -c 'sleep 30; /boltz-backend/bin/boltzd'"
+    volumes:
+      - ./data/lnd-2:/data/lnd/
+      - ./data/boltz/:/root/.boltz/
+      - elements-data:/root/.elements
+      - bitcoin-data:/root/.bitcoin
+
+  boltz-client:
+    hostname: boltz-client
+    depends_on:
+      - boltz
+    restart: always
+    image: boltz/boltz-client:latest
+    ports:
+      - 9002:9002
+      - 9003:9003
+    expose:
+      - 9002
+    healthcheck:
+      test: ['CMD', 'boltzcli', '--host', 'boltz-client', 'getinfo']
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 0s
+    volumes:
+      - elements-data:/root/.elements
+      - ./data/boltz-client:/root/.boltz
+
+  boltz-backend-nginx:
+    hostname: boltz-nginx
+    restart: always
+    image: nginx:latest
+    ports:
+      - 9001:9001
+    volumes:
+      - nginx-data:/etc/nginx/conf.d
+    healthcheck:
+      test: ['CMD-SHELL', 'curl http://localhost:9001/version']
+      timeout: 1s
+      retries: 10
+      interval: 1s
+      start_period: 0s
+
+  boltz-postgres:
+    hostname: boltz-postgres
+    restart: always
+    image: postgres:14-alpine
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready --dbname boltz --username boltz"]
+      interval: 5s
+      timeout: 30s
+      retries: 10
+      start_period: 5s
+    environment:
+      - POSTGRES_DB=boltz
+      - POSTGRES_USER=boltz
+      - POSTGRES_PASSWORD=boltz
+    expose:
+      - 5432
+
+  bitcoind:
+    hostname: bitcoind
+    image: boltz/bitcoin-core:25.0
+    command:
+      - -regtest
+      - -fallbackfee=0.00000253
+      - -zmqpubrawtx=tcp://0.0.0.0:29000
+      - -zmqpubrawblock=tcp://0.0.0.0:29001
+      - -zmqpubhashblock=tcp://0.0.0.0:29002
+      - -txindex
+      - -rpcallowip=0.0.0.0/0
+      - -rpcbind=0.0.0.0
+      - -addresstype=bech32
+      - -changetype=bech32
+      - -dbcache=2048
+      - -rpcworkqueue=256
+    volumes:
+      - bitcoin-data:/root/.bitcoin
+    expose:
+      - 29000
+      - 29001
+      - 29002
+      - 18443
+      - 18444
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "bitcoin-cli",
+          "--rpccookiefile=/root/.bitcoin/regtest/.cookie",
+          "-regtest",
+          "getblockchaininfo",
+        ]
+      timeout: 1s
+      retries: 1
+      interval: 1s
+      start_period: 0s
+
+  clightning-1:
+    hostname: clightning-1
+    depends_on:
+      - bitcoind
+    image: boltz/c-lightning:24.11
+    command:
+      - --large-channels
+      - --network=regtest
+      - --grpc-port=9736
+      - --bind-addr=0.0.0.0:9735
+      - --bitcoin-rpcconnect=bitcoind
+      - --bitcoin-rpcport=18443
+      - --clnrest-host=0.0.0.0
+      - --clnrest-port=3010
+    expose:
+      - 9735
+    ports:
+      - 9736:9736
+      - 3010:3010
+    volumes:
+      - ./data/clightning-1:/root/.lightning/
+      - bitcoin-data:/root/.bitcoin
+
+  clightning-2:
+    hostname: clightning-2
+    depends_on:
+      - bitcoind
+    image: boltz/c-lightning:22.11.1
+    command:
+      - --large-channels
+      - --network=regtest
+      - --grpc-port=9737
+      - --bind-addr=0.0.0.0:9735
+      - --bitcoin-rpcconnect=bitcoind
+      - --bitcoin-rpcport=18443
+    expose:
+      - 9735
+    ports:
+      - 9737:9737
+    volumes:
+      - ./data/clightning-2:/root/.lightning/
+      - bitcoin-data:/root/.bitcoin
+
+  clightning-2-rest:
+    hostname: clightning-2-rest
+    depends_on:
+      - clightning-2
+    image: saubyk/c-lightning-rest:0.10.7
+    entrypoint: "sh -c 'sleep 35 && /sbin/tini -g -- ./docker-entrypoint.sh'"
+    ports:
+      - 3001:3001
+    expose:
+      - 3001
+    volumes:
+      - ./data/clightning-2:/root/.lightning/:uid=1000,gid=1000
+      - ./data/clightning-2-rest:/usr/src/app/certs/
+      - bitcoin-data:/root/.bitcoin
+
+  clightning-3:
+    hostname: clightning-3
+    depends_on:
+      - bitcoind
+    image: boltz/c-lightning:24.11
+    command:
+      - --large-channels
+      - --network=regtest
+      - --grpc-port=9738
+      - --bind-addr=0.0.0.0:9735
+      - --bitcoin-rpcconnect=bitcoind
+      - --bitcoin-rpcport=18443
+    expose:
+      - 9735
+    ports:
+      - 9738:9738
+    volumes:
+      - ./data/clightning-3:/root/.lightning/
+      - bitcoin-data:/root/.bitcoin
+
+  lnd-1:
+    hostname: lnd-1
+    depends_on:
+      - bitcoind
+    image: boltz/lnd:0.18.4-beta
+    restart: on-failure
+    command:
+      - --listen=lnd-1:9735
+      - --rpclisten=lnd-1:10009
+      - --restlisten=lnd-1:8081
+      - --bitcoin.active
+      - --bitcoin.regtest
+      - --bitcoin.node=bitcoind
+      - --bitcoind.rpchost=bitcoind
+      - --bitcoind.rpccookie=/root/.bitcoin/regtest/.cookie
+      - --bitcoind.zmqpubrawtx=bitcoind:29000
+      - --bitcoind.zmqpubrawblock=bitcoind:29001
+      - --noseedbackup
+      - --protocol.wumbo-channels
+    expose:
+      - 8081
+      - 9735
+      - 10009
+    volumes:
+      - ./data/lnd-1:/root/.lnd/
+      - bitcoin-data:/root/.bitcoin
+
+  lnd-2:
+    hostname: lnd-2
+    depends_on:
+      - bitcoind
+    image: boltz/lnd:0.19.3-beta
+    restart: on-failure
+    command:
+      - --listen=lnd-2:9735
+      - --rpclisten=lnd-2:10009
+      - --restlisten=lnd-2:8081
+      - --bitcoin.active
+      - --bitcoin.regtest
+      - --bitcoin.node=bitcoind
+      - --bitcoind.rpchost=bitcoind
+      - --bitcoind.rpccookie=/root/.bitcoin/regtest/.cookie
+      - --bitcoind.zmqpubrawtx=bitcoind:29000
+      - --bitcoind.zmqpubrawblock=bitcoind:29001
+      - --noseedbackup
+      - --protocol.wumbo-channels
+    expose:
+      - 8081
+      - 9735
+      - 10009
+    volumes:
+      - ./data/lnd-2:/root/.lnd/
+      - bitcoin-data:/root/.bitcoin
+
+  lnd-3:
+    hostname: lnd-3
+    depends_on:
+      - bitcoind
+    image: boltz/lnd:0.18.4-beta
+    restart: on-failure
+    command:
+      - --listen=lnd-3:9735
+      - --rpclisten=lnd-3:10009
+      - --restlisten=lnd-3:8081
+      - --bitcoin.active
+      - --bitcoin.regtest
+      - --bitcoin.node=bitcoind
+      - --bitcoind.rpchost=bitcoind
+      - --bitcoind.rpccookie=/root/.bitcoin/regtest/.cookie
+      - --bitcoind.zmqpubrawtx=bitcoind:29000
+      - --bitcoind.zmqpubrawblock=bitcoind:29001
+      - --noseedbackup
+      - --protocol.wumbo-channels
+    ports:
+      - 8081:8081
+      - 10009:10009
+    expose:
+      - 8081
+      - 9735
+      - 10009
+    volumes:
+      - ./data/lnd-3:/root/.lnd/
+      - bitcoin-data:/root/.bitcoin
+
+  lnd-4:
+    hostname: lnd-4
+    depends_on:
+      - bitcoind
+    image: boltz/lnd:0.18.4-beta
+    restart: on-failure
+    command:
+      - --listen=lnd-4:9735
+      - --rpclisten=lnd-4:10009
+      - --restlisten=lnd-4:8081
+      - --bitcoin.active
+      - --bitcoin.regtest
+      - --bitcoin.node=bitcoind
+      - --bitcoind.rpchost=bitcoind
+      - --bitcoind.rpccookie=/root/.bitcoin/regtest/.cookie
+      - --bitcoind.zmqpubrawtx=bitcoind:29000
+      - --bitcoind.zmqpubrawblock=bitcoind:29001
+      - --noseedbackup
+      - --protocol.wumbo-channels
+    expose:
+      - 8081
+      - 9735
+      - 10009
+    volumes:
+      - ./data/lnd-4:/root/.lnd/
+      - bitcoin-data:/root/.bitcoin
+
+  eclair:
+    hostname: eclair
+    depends_on:
+      - bitcoind
+    image: boltz/eclair:0.8.0
+    restart: on-failure
+    entrypoint: "sh -c 'JAVA_OPTS=-Xmx512m /eclair-node/bin/eclair-node.sh -Declair.datadir=/root/eclair -Declair.printToConsole'"
+    ports:
+      - 8082:8080
+    expose:
+      - 9735
+      - 8080
+    volumes:
+      - ./data/eclair:/root/eclair
+      - bitcoin-data:/root/.bitcoin
+
+  electrs:
+    hostname: electrs
+    restart: always
+    image: boltz/electrs:latest
+    entrypoint: ["electrs-bitcoin"]
+    command:
+      - --electrum-rpc-addr
+      - electrs:19001
+      - --http-addr
+      - electrs:3002
+      - --daemon-rpc-addr
+      - bitcoind:18443
+      - --network
+      - regtest
+      - --jsonrpc-import
+    healthcheck:
+      test: ["CMD-SHELL", "curl -s $(hostname):3002/blocks/tip/height"]
+      timeout: 1s
+      retries: 20
+      interval: 2s
+      start_period: 5s
+    ports:
+      - 19001:19001
+      - 3002:3002
+    volumes:
+      - bitcoin-data:/root/.bitcoin
+
+  elementsd:
+    hostname: elementsd
+    restart: always
+    image: boltz/elements:latest
+    expose:
+      - 31001
+    ports:
+      - 31000:31000
+      - 31002:31002
+      - 18884:18884
+    command:
+    - -chain=liquidregtest
+    - -txindex=1
+    - -rest=1
+    - -server=1
+    - -rpcallowip=0.0.0.0/0
+    - -validatepegin=0
+    - -initialfreecoins=2100000000000000
+    - -fallbackfee=0.000001
+    - -rpcbind=0.0.0.0
+    - -rpcport=18884
+    - -zmqpubrawtx=tcp://0.0.0.0:31000
+    - -zmqpubrawblock=tcp://0.0.0.0:31001
+    - -zmqpubhashblock=tcp://0.0.0.0:31002
+    - -acceptdiscountct=1
+    - -creatediscountct=1
+    volumes:
+      - elements-data:/root/.elements
+
+  electrs-liquid:
+    hostname: electrs-liquid
+    restart: always
+    image: boltz/electrs:latest
+    entrypoint: ["electrs-liquid"]
+    command:
+      - --electrum-rpc-addr
+      - electrs-liquid:19002
+      - --http-addr
+      - electrs-liquid:3003
+      - --daemon-rpc-addr
+      - elementsd:18884
+      - --daemon-dir
+      - /root/.elements
+      - --network
+      - liquidregtest
+      - --parent-network
+      - regtest
+      - --jsonrpc-import
+    healthcheck:
+      test: ["CMD-SHELL", "curl -s $(hostname):3003/blocks/tip/height"]
+      timeout: 15s
+      retries: 20
+      interval: 2s
+      start_period: 5s
+    ports:
+      - 19002:19002
+      - 3003:3003
+    volumes:
+      - elements-data:/root/.elements
+
+volumes:
+  lnbits-data:
+  bitcoin-data:
+  elements-data:
+  nginx-data:
+    name: nginx-data
+    driver: local
+    driver_opts:
+      type: none
+      o: bind
+      device: ./data/boltz-nginx/

docker/regtest/docker-scripts.sh

@@ -0,0 +1,322 @@
+#!/bin/sh
+export COMPOSE_PROJECT_NAME=lnbits
+
+boltzcli-sim() {
+  docker exec -it lnbits-boltz-client-1 boltzcli "$@"
+}
+
+bitcoin-cli-sim() {
+  docker exec lnbits-bitcoind-1 bitcoin-cli -regtest "$@"
+}
+
+elements-cli-sim() {
+  docker exec lnbits-elementsd-1 elements-cli -rpcport=18884 -chain=liquidregtest "$@"
+}
+
+# args(i, cmd)
+lightning-cli-sim() {
+  i=$1
+  shift # shift first argument so we can use $@
+  docker exec lnbits-clightning-$i-1 lightning-cli --network regtest "$@"
+}
+
+# args(i, cmd)
+lncli-sim() {
+  i=$1
+  shift # shift first argument so we can use $@
+  docker exec lnbits-lnd-$i-1 lncli --network regtest --rpcserver=lnd-$i:10009 "$@"
+}
+
+get-eclair-pubkey() {
+  while true; do
+    pubkey=$(docker exec lnbits-eclair-1 curl http://localhost:8080/getinfo -X POST -s -u :lnbits | jq -r .nodeId 2> /dev/null)
+    pubkeyPrefix=$(echo $pubkey | cut -c1,2)
+    if [[ "$pubkeyPrefix" == "02" || "$pubkeyPrefix" == "03" ]]; then
+      echo $pubkey
+      break
+    fi
+    sleep 1
+  done
+}
+
+wait-for-eclair-channel() {
+  while true; do
+    state=$(docker exec lnbits-eclair-1 curl http://localhost:8080/channels -X POST -s -u :lnbits | jq -r ".[0].state")
+    pending=$(docker exec lnbits-eclair-1 curl -s http://localhost:8080/channels -X POST -u :lnbits| jq '. | length')
+    echo "eclair-1 pendingchannels: $pending, current state: $state"
+    if [[ "$state" == "NORMAL" ]]; then
+      break
+    fi
+    sleep 1
+  done
+}
+
+# args(i)
+fund_boltz_client() {
+  # first address of seed: abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
+  address="el1qq2xvpcvfup5j8zscjq05u2wxxjcyewk7979f3mmz5l7uw5pqmx6xf5xy50hsn6vhkm5euwt72x878eq6zxx2z0z676mna6kdq"
+  echo "funding: $address on boltz-client"
+  elements-cli-sim -named sendtoaddress address=$address amount=30 fee_rate=100 > /dev/null
+}
+
+
+# args(i)
+fund_clightning_node() {
+  address=$(lightning-cli-sim $1 newaddr | jq -r .bech32)
+  echo "funding: $address on clightning-node: $1"
+  bitcoin-cli-sim -named sendtoaddress address=$address amount=30 fee_rate=100 > /dev/null
+}
+
+# args(i)
+fund_lnd_node() {
+  address=$(lncli-sim $1 newaddress p2wkh | jq -r .address)
+  echo "funding: $address on lnd-node: $1"
+  bitcoin-cli-sim -named sendtoaddress address=$address amount=30 fee_rate=100 > /dev/null
+}
+
+# args(i, j)
+connect_clightning_node() {
+  pubkey=$(lightning-cli-sim $2 getinfo | jq -r '.id')
+  lightning-cli-sim $1 connect $pubkey@lnbits-clightning-$2-1:9735 | jq -r '.id'
+}
+
+lnbits-regtest-start(){
+  if ! command -v jq &> /dev/null
+  then
+      echo "jq is not installed"
+      exit
+  fi
+  if ! command -v docker &> /dev/null
+  then
+      echo "docker is not installed"
+      exit
+  fi
+  if ! command -v docker version &> /dev/null
+  then
+      echo "dockerd is not running"
+      exit
+  fi
+  lnbits-regtest-stop
+  docker compose up -d --remove-orphans
+  lnbits-regtest-init
+}
+
+lnbits-regtest-start-log(){
+  lnbits-regtest-stop
+  docker compose up --remove-orphans
+  lnbits-regtest-init
+}
+
+lnbits-regtest-stop(){
+  docker compose down --volumes
+  # clean up lightning node data
+  sudo rm -rf ./data/clightning-1 ./data/clightning-2 ./data/clightning-3 ./data/lnd-1  ./data/lnd-2 ./data/lnd-3 ./data/lnd-4 ./data/boltz/boltz.db ./data/eclair/regtest ./data/boltz-client/liquid-wallet ./data/boltz-client/bitcoin-wallet ./data/boltz-client/wallet ./data/boltz-client/boltz.db
+  # recreate lightning node data folders preventing permission errors
+  mkdir ./data/clightning-1 ./data/clightning-2 ./data/clightning-3 ./data/lnd-1 ./data/lnd-2 ./data/lnd-3 ./data/lnd-4
+}
+
+lnbits-regtest-restart(){
+  lnbits-regtest-stop
+  lnbits-regtest-start
+}
+
+boltz-client-init(){
+  for i in 0 1 2; do
+    fund_boltz_client
+  done
+  elements-cli-sim -generate 3 > /dev/null
+}
+
+lnbits-bitcoin-init(){
+  echo "init_bitcoin_wallet..."
+  bitcoin-cli-sim createwallet lnbits || bitcoin-cli-sim loadwallet lnbits
+  echo "mining 150 blocks..."
+  bitcoin-cli-sim -generate 150 > /dev/null
+}
+
+lnbits-elements-init(){
+  echo "init_elements_wallet..."
+  elements-cli-sim createwallet lnbits || elements-cli-sim loadwallet lnbits
+  echo "mining 150 blocks..."
+  elements-cli-sim -generate 150 > /dev/null
+  elements-cli-sim rescanblockchain
+}
+
+lnbits-init(){
+  echo "init_lnbits..."
+  docker exec lnbits-lnbits-1 uv run python tools/create_fake_admin.py
+}
+
+lnbits-regtest-init(){
+  lnbits-bitcoin-init
+  lnbits-elements-init
+  lnbits-lightning-sync
+  lnbits-lightning-init
+  boltz-client-init
+  lnbits-init
+}
+
+lnbits-lightning-sync(){
+  wait-for-clightning-sync 1
+  wait-for-clightning-sync 2
+  wait-for-clightning-sync 3
+  wait-for-lnd-sync 1
+  wait-for-lnd-sync 2
+  wait-for-lnd-sync 3
+  wait-for-lnd-sync 4
+}
+
+lnbits-lightning-init(){
+
+  # create 10 UTXOs for each node
+  for i in 0 1 2; do
+    fund_clightning_node 1
+    fund_clightning_node 2
+    fund_clightning_node 3
+    fund_lnd_node 1
+    fund_lnd_node 2
+    fund_lnd_node 3
+    fund_lnd_node 4
+  done
+
+  echo "mining 3 blocks..."
+  bitcoin-cli-sim -generate 3 > /dev/null
+
+  lnbits-lightning-sync
+
+  channel_confirms=6
+  channel_size=24000000 # 0.024 btc
+  balance_size=12000000 # 0.12 btc
+  balance_size_msat=12000000000 # 0.12 btc
+
+  # lnd-1 -> lnd-2
+  lncli-sim 1 connect $(lncli-sim 2 getinfo | jq -r '.identity_pubkey')@lnbits-lnd-2-1 > /dev/null
+  echo "open channel from lnd-1 to lnd-2"
+  lncli-sim 1 openchannel $(lncli-sim 2 getinfo | jq -r '.identity_pubkey') $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 1
+
+  # lnd-1 -> lnd-3
+  lncli-sim 1 connect $(lncli-sim 3 getinfo | jq -r '.identity_pubkey')@lnbits-lnd-3-1 > /dev/null
+  echo "open channel from lnd-1 to lnd-3"
+  lncli-sim 1 openchannel $(lncli-sim 3 getinfo | jq -r '.identity_pubkey') $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 1
+
+  # lnd-1 -> cln-1
+  lncli-sim 1 connect $(lightning-cli-sim 1 getinfo | jq -r '.id')@lnbits-clightning-1-1 > /dev/null
+  echo "open channel from lnd-1 to cln-1"
+  lncli-sim 1 openchannel $(lightning-cli-sim 1 getinfo | jq -r '.id') $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 1
+
+  # lnd-1 -> cln-2
+  lncli-sim 1 connect $(lightning-cli-sim 2 getinfo | jq -r '.id')@lnbits-clightning-2-1 > /dev/null
+  echo "open channel from lnd-1 to cln-2"
+  lncli-sim 1 openchannel $(lightning-cli-sim 2 getinfo | jq -r '.id') $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 1
+
+  # lnd-1 -> cln-3
+  lncli-sim 1 connect $(lightning-cli-sim 3 getinfo | jq -r '.id')@lnbits-clightning-3-1 > /dev/null
+  echo "open channel from lnd-1 to cln-3"
+  lncli-sim 1 openchannel $(lightning-cli-sim 3 getinfo | jq -r '.id') $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 1
+
+  # lnd-2 -> cln-2
+  lncli-sim 2 connect $(lightning-cli-sim 2 getinfo | jq -r '.id')@lnbits-clightning-2-1 > /dev/null
+  echo "open channel from lnd-2 to cln-2"
+  lncli-sim 2 openchannel $(lightning-cli-sim 2 getinfo | jq -r '.id') $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 2
+
+  # lnd-3 -> cln-3
+  lncli-sim 3 connect $(lightning-cli-sim 3 getinfo | jq -r '.id')@lnbits-clightning-3-1 > /dev/null
+  echo "open channel from lnd-3 to cln-1"
+  lncli-sim 3 openchannel $(lightning-cli-sim 3 getinfo | jq -r '.id') $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 3
+
+  # lnd-3 -> cln-1
+  lncli-sim 3 connect $(lightning-cli-sim 1 getinfo | jq -r '.id')@lnbits-clightning-1-1 > /dev/null
+  echo "open channel from lnd-3 to cln-1"
+  lncli-sim 3 openchannel $(lightning-cli-sim 1 getinfo | jq -r '.id') $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 3
+
+  # lnd-1 -> eclair-1
+  lncli-sim 1 connect $(get-eclair-pubkey)@lnbits-eclair-1 > /dev/null
+  echo "open channel from lnd-2 to eclair-1"
+  lncli-sim 1 openchannel $(get-eclair-pubkey) $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 1
+
+  # lnd-2 -> eclair-1
+  lncli-sim 2 connect $(get-eclair-pubkey)@lnbits-eclair-1 > /dev/null
+  echo "open channel from lnd-2 to eclair-1"
+  lncli-sim 2 openchannel $(get-eclair-pubkey) $channel_size $balance_size > /dev/null
+  bitcoin-cli-sim -generate $channel_confirms > /dev/null
+  wait-for-lnd-channel 2
+
+  wait-for-clightning-channel 1
+  wait-for-clightning-channel 2
+  wait-for-clightning-channel 3
+
+  wait-for-eclair-channel
+
+  lnbits-lightning-sync
+
+}
+
+wait-for-lnd-channel(){
+  while true; do
+    pending=$(lncli-sim $1 pendingchannels | jq -r '.pending_open_channels | length')
+    echo "lnd-$1 pendingchannels: $pending"
+    if [[ "$pending" == "0" ]]; then
+      break
+    fi
+    sleep 1
+  done
+}
+
+wait-for-lnd-sync(){
+  while true; do
+    if [[ "$(lncli-sim $1 getinfo 2>&1 | jq -r '.synced_to_chain' 2> /dev/null)" == "true" ]]; then
+      echo "lnd-$1 is synced!"
+      break
+    fi
+    echo "waiting for lnd-$1 to sync..."
+    sleep 1
+  done
+}
+
+wait-for-clightning-channel(){
+  while true; do
+    pending=$(lightning-cli-sim $1 getinfo | jq -r '.num_pending_channels | length')
+    echo "cln-$1 pendingchannels: $pending"
+    if [[ "$pending" == "0" ]]; then
+      if [[ "$(lightning-cli-sim $1 getinfo 2>&1 | jq -r '.warning_bitcoind_sync' 2> /dev/null)" == "null" ]]; then
+        if [[ "$(lightning-cli-sim $1 getinfo 2>&1 | jq -r '.warning_lightningd_sync' 2> /dev/null)" == "null" ]]; then
+          break
+        fi
+      fi
+    fi
+    sleep 1
+  done
+}
+
+wait-for-clightning-sync(){
+  while true; do
+    if [[ ! "$(lightning-cli-sim $1 getinfo 2>&1 | jq -r '.id' 2> /dev/null)" == "null" ]]; then
+      if [[ "$(lightning-cli-sim $1 getinfo 2>&1 | jq -r '.warning_bitcoind_sync' 2> /dev/null)" == "null" ]]; then
+        if [[ "$(lightning-cli-sim $1 getinfo 2>&1 | jq -r '.warning_lightningd_sync' 2> /dev/null)" == "null" ]]; then
+          echo "cln-$1 is synced!"
+          break
+        fi
+      fi
+    fi
+    echo "waiting for cln-$1 to sync..."
+    sleep 1
+  done
+}

docker/regtest/start-regtest

@@ -0,0 +1,74 @@
+#!/bin/bash
+print_success() {
+  printf "\033[;1;32mPASSED\033[;0m $1\n"
+}
+
+print_error() {
+  printf "\033[;1;31mFAILED\033[;0m $1\n"
+}
+
+run(){
+  label=$1
+  value=$2
+  cmd=$3
+  if [[ "$cmd" == "$value" ]]; then
+    print_success "$label is $cmd"
+  else
+    print_error "$label is $cmd, should be $value"
+    failed="true"
+  fi
+}
+
+failed="false"
+blockheight=213
+utxos=3
+channel_size=24000000 # 0.024 btc
+balance_size=12000000 # 0.012 btc
+
+source $(pwd)/docker-scripts.sh
+lnbits-regtest-start
+echo "=================================="
+printf "\033[;1;36mregtest started! starting tests...\033[;0m\n"
+echo "=================================="
+echo ""
+
+for i in 1 2 3; do
+  run "lnd-$i .synced_to_chain" "true" $(lncli-sim $i getinfo | jq -r ".synced_to_chain")
+  run "lnd-$i utxo count" $utxos $(lncli-sim $i listunspent | jq -r ".utxos | length")
+  run "lnd-$i .block_height" $blockheight $(lncli-sim $i getinfo | jq -r ".block_height")
+  if [[ "$i" == "1" ]]; then
+    channel_count=6
+  else
+    channel_count=3
+  fi
+  run "lnd-$i openchannels" $channel_count $(lncli-sim $i listchannels | jq -r ".channels | length")
+  run "lnd-$i .channels[0].capacity" $channel_size $(lncli-sim $i listchannels | jq -r ".channels[0].capacity")
+  run "lnd-$i .channels[0].push_amount_sat" $balance_size $(lncli-sim $i listchannels | jq -r ".channels[0].push_amount_sat")
+done
+for i in 1 2 3; do
+  # run "cln-$i blockheight" $blockheight $(lightning-cli-sim $i getinfo | jq -r ".blockheight")
+  run "cln-$i utxo count" $utxos $(lightning-cli-sim $i listfunds | jq -r ".outputs | length")
+  run "cln-$i openchannels" 2 $(lightning-cli-sim $i getinfo | jq -r ".num_active_channels")
+  run "cln-$i channel[0].state" "CHANNELD_NORMAL" $(lightning-cli-sim $i listfunds | jq -r ".channels[0].state")
+  run "cln-$i channel[0].amount_msat" $(($channel_size * 1000)) $(lightning-cli-sim $i listfunds | jq -r ".channels[0].amount_msat" | sed 's/msat//g')
+  run "cln-$i channel[0].our_amount_msat" $(($balance_size * 1000)) $(lightning-cli-sim $i listfunds | jq -r ".channels[0].our_amount_msat" | sed 's/msat//g')
+done
+
+run "eclair-1 openchannels" 2 $(docker exec lnbits-eclair-1 curl -s http://localhost:8080/channels -X POST -u :lnbits| jq '. | length')
+run "eclair-1 blockHeight" $blockheight $(docker exec lnbits-eclair-1 curl -s http://localhost:8080/getinfo -X POST -u :lnbits| jq '.blockHeight')
+run "lnbits service status" "200" $(curl -s -o /dev/null -w "%{http_code}" "http://localhost:5001/")
+run "boltz service status" "200" $(curl -s -o /dev/null --head -w "%{http_code}" "http://localhost:9001/version")
+
+# return non-zero exit code if a test fails
+if [[ "$failed" == "true" ]]; then
+  echo ""
+  echo "=================================="
+  print_error "one more more tests failed"
+  echo "=================================="
+  exit 1
+else
+  echo ""
+  echo "=================================="
+  print_success "all tests passed! yay!"
+  echo "=================================="
+fi

docker/sparkl2/Dockerfile

@@ -0,0 +1,41 @@
+ARG LNBITS_TAG=latest
+
+FROM lnbits/lnbits:${LNBITS_TAG}
+
+RUN curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
+
+RUN apt-get update && apt-get -y upgrade
+RUN apt-get install -y ca-certificates curl gnupg netcat-openbsd git nodejs
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
+
+# install sparksidecar
+RUN git clone https://github.com/lnbits/spark_sidecar
+RUN cd spark_sidecar && npm ci
+
+# Reinstall dependencies for lnbits just in case (needed for CMD usage)
+RUN uv sync --all-extras
+
+# LNBITS
+ENV LNBITS_PORT="5000"
+ENV LNBITS_HOST="0.0.0.0"
+ENV LNBITS_BACKEND_WALLET_CLASS="SparkL2Wallet"
+ENV LNBITS_RESERVE_FEE_MIN="20000"
+ENV LNBITS_RESERVE_FEE_PERCENT="1"
+ENV LNBITS_FUNDING_SOURCE_PAY_INVOICE_WAIT_SECONDS="20"
+ENV FUNDING_SOURCE_MAX_RETRIES="10"
+
+# spark sidecar
+ENV SPARK_NETWORK="MAINNET"
+ENV SPARK_SIDECAR_PORT="8765"
+ENV SPARK_PAY_WAIT_MS="20000"
+ENV SPARK_MULTIPLICITY="3"
+
+EXPOSE 5000
+
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Entrypoint to start sparksidebar and LNbits
+CMD ["/entrypoint.sh"]

docker/sparkl2/entrypoint.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -e
+
+node spark_sidecar/server.mjs &
+
+SIDECAR_PID=$!
+
+# Wait for startup
+for i in {1..10}; do
+  if nc -z localhost $SPARK_SIDECAR_PORT; then
+    echo "sparksidebar is up!"
+    break
+  fi
+  echo "Waiting for sparksidebar to start..."
+  sleep 1
+done
+
+# Optional: check if still not up
+if ! nc -z localhost $SPARK_SIDECAR_PORT; then
+  echo "sparksidebar did not start successfully."
+  exit 1
+fi
+
+echo "Starting LNbits on $LNBITS_HOST:$LNBITS_PORT..."
+exec uv run lnbits --port "$LNBITS_PORT" --host "$LNBITS_HOST" --forwarded-allow-ips='*'

docs/_config.yml

@@ -4,6 +4,7 @@ color_scheme: dark
 logo: "/logos/lnbits-full-inverse.png"
 search_enabled: true
 url: https://docs.lnbits.org
+markdown: gfm
 aux_links:
   "LNbits on GitHub":
     - "//github.com/lnbits/lnbits"

docs/devs/development.md

@@ -11,13 +11,13 @@ Thanks for contributing :)
 
 # Run
 
-Follow the [Basic installation: Option 1 (recommended): poetry](https://docs.lnbits.org/guide/installation.html#option-1-recommended-poetry)
-guide to install poetry and other dependencies.
+Follow the [Option 2 (recommended): UV](https://docs.lnbits.org/guide/installation.html)
+guide to install uv and other dependencies.
 
 Then you can start LNbits uvicorn server with:
 
 ```bash
-poetry run lnbits
+uv run lnbits
 ```
 
 Or you can use the following to start uvicorn with hot reloading enabled:
@@ -25,7 +25,7 @@ Or you can use the following to start uvicorn with hot reloading enabled:
 ```bash
 make dev
 # or
-poetry run lnbits --reload
+uv run lnbits --reload
 ```
 
 You might need the following extra dependencies on clean installation of Debian:
@@ -50,7 +50,7 @@ make install-pre-commit-hook
 This project has unit tests that help prevent regressions. Before you can run the tests, you must install a few dependencies:
 
 ```bash
-poetry install
+uv sync --all-extras --dev
 npm i
 ```
 
@@ -69,7 +69,7 @@ make format
 Run mypy checks:
 
 ```bash
-poetry run mypy
+make mypy
 ```
 
 Run everything:

docs/devs/extensions.md

@@ -42,14 +42,10 @@ mv templates/example templates/mysuperplugin # Rename templates folder.
 
 DO NOT ADD NEW DEPENDENCIES. Try to use the dependencies that are available in `pyproject.toml`. Getting the LNbits project to accept a new dependency is time consuming and uncertain, and may result in your extension NOT being made available to others.
 
-If for some reason your extensions must have a new python package to work, and its nees are not met in `pyproject.toml`, you can add a new package using `poerty`:
-
-```sh
-$ poetry add <package>
-```
+If for some reason your extensions must have a new python package to work, and its nees are not met in `pyproject.toml`, you can add a new package using `poerty` or `uv`:
 
 **But we need an extra step to make sure LNbits doesn't break in production.**
-Dependencies need to be added to `pyproject.toml`, then tested by running on `poetry` compatibility can be tested with `nix build .#checks.x86_64-linux.vmTest`.
+Dependencies need to be added to `pyproject.toml`, then tested by running on `uv` and `poetry` compatibility can be tested with `nix build .#checks.x86_64-linux.vmTest`.
 
 ## SQLite to PostgreSQL migration
 

docs/devs/fastapi_transition.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: FastAPI extension upgrade
+nav_order: 1
+---
+
 ## Defining a route with path parameters
 
 **old:**

docs/guide/admin_ui.md

@@ -1,78 +1,133 @@
 ---
 layout: default
 title: Admin UI
-nav_order: 4
+nav_order: 1
 ---
 
-# Admin UI
+<a href="https://lnbits.com" target="_blank" rel="noopener noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/QE6SIrs.png">
+    <img src="https://i.imgur.com/fyKPgVT.png" alt="LNbits" style="width:300px">
+  </picture>
+</a>
 
-The LNbits Admin UI lets you change LNbits settings via the LNbits frontend.
-It is disabled by default and the first time you set the environment variable `LNBITS_ADMIN_UI=true`
-the settings are initialized and saved to the database and will be used from there as long the UI is enabled.
-From there on the settings from the database are used.
+![phase: stable](https://img.shields.io/badge/phase-stable-2EA043)
+![PRs: welcome](https://img.shields.io/badge/PRs-Welcome-yellow)
+[<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits)
 
-# Super User
+# LNBits Admin UI
 
-With the Admin UI we introduced the super user, it is created with the initialisation of the Admin UI and will be shown with a success message in the server logs.
-The super user has access to the server and can change settings that may crash the server and make it unresponsive via the frontend and api, like changing funding sources.
+[What you can do](#what-you-can-do-with-the-admin-ui) · [First Run](#first-run-and-super-user-id) · [Enable/Disable](#enabling-or-disabling-the-admin-ui) · [Reset](#reset-to-defaults) · [Allowed Users](#allowed-users) · [Guides](#additional-guides)
 
-Also only the super user can brrrr satoshis to different wallets.
+**We introduced the Admin UI as the new default to make setup simpler and more straightforward**. Instead of hand editing the `.env` file, you configure key server settings directly in the frontend with clear labels and guardrails.
 
-The super user is only stored inside the settings table of the database and after the settings are "reset to defaults" and a restart happened,
-a new super user is created.
+<ins>On a fresh install the Admin UI is enabled by default</ins>, and at first launch you are prompted to create **Super User** credentials so that sensitive operations, such as switching funding sources, remain in trusted hands. When the Admin UI is enabled, configuration is written to and read from the database; for all settings managed by the UI, the parameters in `.env` are largely no longer used. If you disable the Admin UI, the `.env` file becomes the single source of truth again.
 
-The super user is never sent over the api and the frontend only receives a bool if you are super user or not.
+For privileged actions and role details see **[Super User](./super_user.md)** & [User Roles](./user_roles.md)
+For a complete reference of legacy variables consult **[.env.example](../../.env.example)**.
 
-We also added a decorator for the API routes to check for super user.
+<img width="900" height="640" alt="grafik" src="https://github.com/user-attachments/assets/d8852b4b-21be-446f-a1e7-d3eb794d3505" />
 
-There is also the possibility of posting the super user via webhook to another service when it is created. you can look it up here https://github.com/lnbits/lnbits/blob/main/lnbits/settings.py `class SaaSSettings`
+> [!WARNING]
+> Some settings remain `.env` only. Use **[.env.example](../../.env.example#L3-L87)** as the authoritative reference for those variables.
 
-# Admin Users
+## What you can do with the Admin UI
 
-environment variable: `LNBITS_ADMIN_USERS`, comma-separated list of user ids
-Admin Users can change settings in the admin ui as well, with the exception of funding source settings, because they require e server restart and could potentially make the server inaccessible. Also they have access to all the extension defined in `LNBITS_ADMIN_EXTENSIONS`.
+- Switch funding sources and other server level settings
+- Manage who can access LNbits (**[Allowed Users](#allowed-users)**)
+- Promote or demote Admin Users
+- Gate extensions to Admins only or disable them globally
+- Adjust balances with credit or debit
+- Adjust site customization
 
-# Allowed Users
+> [!NOTE]
+> See **[Super User](./super_user.md)** for the role and permission differences compared to Admin Users.
 
-environment variable: `LNBITS_ALLOWED_USERS`, comma-separated list of user ids
-By defining this users, LNbits will no longer be usable by the public, only defined users and admins can then access the LNbits frontend.
+## First run and Super User ID
 
-Setting this environment variable also disables account creation.
-Account creation can be also disabled by setting `LNBITS_ALLOW_NEW_ACCOUNTS=false`
+On first start with the Admin UI enabled you will be prompted to generate a Super User.
 
-# How to activate
+<img width="1573" height="976" alt="Admin_UI_first_install" src="https://github.com/user-attachments/assets/05aa634f-06ec-4a4d-a5c6-d90927c90991" />
 
-```
-$ sudo systemctl stop lnbits.service
-$ cd ~/lnbits
-$ sudo nano .env
-```
+If you need to read it from disk later:
 
--> set: `LNBITS_ADMIN_UI=true`
-
-Now start LNbits once in the terminal window
-
-```
-$ poetry run lnbits
-```
-
-You can now `cat` the Super User ID:
-
-```
-$ cat data/.super_user
+```bash
+cat /lnbits/data/.super_user
+# example
 123de4bfdddddbbeb48c8bc8382fe123
 ```
 
-You can access your super user account at `/wallet?usr=super_user_id`. You just have to append it to your normal LNbits web domain.
+> [!WARNING]
+> For security reasons, Super Users and Admin users must authenticate with credentials (username and password).
 
-After that you will find the **`Admin` / `Manage Server`** between `Wallets` and `Extensions`
+After login you will see **Settings** and **Users** in the sidebar between **Wallets** and **Extensions**, plus a role badge in the top left.
 
-Here you can design the interface, it has credit/debit to change wallets balances and you can restrict access rights to extensions only for admins or generally deactivated for everyone. You can make users admins or set up Allowed Users if you want to restrict access. And of course the classic settings of the .env file, e.g. to change the funding source wallet or set a charge fee.
+<img width="1353" height="914" alt="grafik" src="https://github.com/user-attachments/assets/06bb4f36-a23a-4058-87ec-60440d322c25" />
 
-Do not forget
+## Enabling or disabling the Admin UI
 
-```
-sudo systemctl start lnbits.service
-```
+The Admin UI is enabled by default on new installs. To change the state:
 
-A little hint, if you set `RESET TO DEFAULTS`, then a new Super User Account will also be created. The old one is then no longer valid.
+1. Stop LNbits
+
+   ```bash
+   sudo systemctl stop lnbits.service
+   ```
+
+2. Edit your `.env`
+
+   ```
+   cd ~/lnbits
+   sudo nano .env
+   ```
+
+3. Set one of
+
+   ```
+   # Enable Admin UI
+   LNBITS_ADMIN_UI=true
+
+   # Disable Admin UI
+   LNBITS_ADMIN_UI=false
+   ```
+
+4. Start LNbits
+
+   ```
+   sudo systemctl start lnbits.service
+   ```
+
+> [!NOTE]
+> With the Admin UI enabled, config is DB-backed and UI-managed settings ignore .env. Disable it to revert to [.env](../../.env.example) as the single source of truth.
+
+## Reset to defaults
+
+Using `Reset to defaults` in the Admin UI wipes stored settings. After a restart, a new `Super User` is created and the old one is no longer valid.
+
+## Allowed Users
+
+When set **at least one**, LNbits becomes private: only the listed users and Admins can access the frontend. Account creation is disabled automatically. You can also disable account creation explicitly.
+
+<img width="1889" height="870" alt="grafik" src="https://github.com/user-attachments/assets/89011b75-a267-44ea-971a-1517968b7af5" />
+
+> [!WARNING]
+> Assign your own account first when enabling **Allowed Users** to avoid locking yourself out. If you do get locked out, use your Super User to recover access.
+
+## Additional Guides
+
+- **[Backend Wallets](./wallets.md)** — Explore options to fund your LNbits instance.
+- **[User Roles](./user_roles.md)** — Overview of existing roles in LNbits.
+- **[Funding sources](./funding-sources-table.md)** — What is available and how to configure each.
+- **[Install LNBits](./installation.md)** — Choose your prefared way to install LNBits.
+
+## Powered by LNbits
+
+LNbits empowers everyone with modular, open source tools for building Bitcoin based systems — fast, free, and extendable.
+
+If you like this project, [send some tip love](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg) or visit our [Shop](https://shop.lnbits.de)
+
+[![LNbits Shop](https://demo.lnbits.com/static/images/bitcoin-shop-banner.png)](https://shop.lnbits.com/)
+[![Visit LNbits Shop](https://img.shields.io/badge/Visit-LNbits%20Shop-7C3AED?logo=shopping-cart&logoColor=white&labelColor=5B21B6)](https://shop.lnbits.com/)
+[![Try myLNbits SaaS](https://img.shields.io/badge/Try-myLNbits%20SaaS-2563EB?logo=lightning&logoColor=white&labelColor=1E40AF)](https://my.lnbits.com/login)
+[![Read LNbits News](https://img.shields.io/badge/Read-LNbits%20News-F97316?logo=rss&logoColor=white&labelColor=C2410C)](https://news.lnbits.com/)
+[![Explore LNbits Extensions](https://img.shields.io/badge/Explore-LNbits%20Extensions-10B981?logo=puzzle-piece&logoColor=white&labelColor=065F46)](https://extensions.lnbits.com/)

docs/guide/extension-install.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Extension Install
+nav_order: 1
+---
+
 # Extension Install
 
 Anyone can create an extension by following the [example extension](https://github.com/lnbits/example) and [making extensions](https://github.com/lnbits/lnbits/blob/main/docs/devs/extensions.md) dev guide.

docs/guide/funding-sources-table.md

@@ -0,0 +1,87 @@
+---
+layout: default
+title: Wallet comparison
+nav_order: 1
+---
+
+<a href="https://lnbits.com" target="_blank" rel="noopener noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/QE6SIrs.png">
+    <img src="https://i.imgur.com/fyKPgVT.png" alt="LNbits" style="width:300px">
+  </picture>
+</a>
+
+![phase: stable](https://img.shields.io/badge/phase-stable-2EA043)
+![PRs: welcome](https://img.shields.io/badge/PRs-Welcome-yellow)
+[<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits)
+
+# Backend Wallet Comparison Table
+
+LNbits lets you choose **how your wallets are funded** — from fully self-custodial nodes to simple hosted services. You can switch the funding source **without touching your apps, users, or extensions**. That means you can start fast, learn, and later upgrade to more control and privacy when you are ready.
+
+**Why this matters**
+
+- **Flexibility:** Pick the backend that fits your skills and constraints today, change it later with minimal friction.
+- **Speed to ship:** Use a hosted option to get live quickly; move to a node when you need more control.
+- **Scalability:** Match cost and maintenance to your stage — from hobby to production.
+- **Privacy and compliance:** Choose between self-custody and provider-managed options depending on your requirements.
+
+Below is a side-by-side comparison of Lightning funding sources you can use with LNbits.
+
+> [!NOTE]
+> “Backend Wallet” and “Funding Source” mean the same thing — the wallet or service that funds your LNbits.
+
+## LNbits Lightning Network Funding Sources Comparison Table
+
+| **Funding Source**             | **Custodial Type**       | **KYC Required**    | **Technical Knowledge Needed** | **Node Hosting Required** | **Privacy Level** | **Liquidity Management** | **Ease of Setup** | **Maintenance Effort** | **Cost Implications**                        | **Scalability** | **Notes**                                                                                  |
+| ------------------------------ | ------------------------ | ------------------- | ------------------------------ | ------------------------- | ----------------- | ------------------------ | ----------------- | ---------------------- | -------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------ |
+| **LND (gRPC)**                 | Self-custodial           | ❌                  | Higher                         | ✅                        | High              | Manual                   | Moderate          | High                   | Infrastructure cost and channel opening fees | High            | gRPC interface for LND; suitable for advanced integrations.                                |
+| **CoreLightning (CLN)**        | Self-custodial           | ❌                  | Higher                         | ✅                        | High              | Manual                   | Moderate          | High                   | Infrastructure cost and channel opening fees | High            | Requires setting up and managing your own CLN node.                                        |
+| **Phoenixd**                   | Self-custodial           | ❌                  | Medium                         | ❌                        | Medium            | Automatic                | Moderate          | Low                    | Minimal fees                                 | Medium          | Mobile wallet backend; suitable for mobile integrations.                                   |
+| **Nostr Wallet Connect (NWC)** | Custodial                | Depends on provider | Low                            | ❌                        | Variable          | Provider-managed         | Easy              | Low                    | May incur fees                               | Medium          | Connects via Nostr protocol; depends on provider's policies.                               |
+| **Boltz**                      | Self-custodial           | ❌                  | Medium                         | ❌                        | Medium            | Provider-managed         | Moderate          | Moderate               | Minimal fees                                 | Medium          | Uses submarine swaps; connects to Boltz client.                                            |
+| **LND (REST)**                 | Self-custodial           | ❌                  | Higher                         | ✅                        | High              | Manual                   | Moderate          | High                   | Infrastructure cost and channel opening fees | High            | REST interface for LND; suitable for web integrations.                                     |
+| **CoreLightning REST**         | Self-custodial           | ❌                  | Higher                         | ✅                        | High              | Manual                   | Moderate          | High                   | Infrastructure cost and channel opening fees | High            | REST interface for CLN; suitable for web integrations.                                     |
+| **LNbits (another instance)**  | Custodial                | Depends on host     | Low                            | ❌                        | Variable          | Provider-managed         | Easy              | Low                    | May incur hosting fees                       | Medium          | Connects to another LNbits instance; depends on host's policies.                           |
+| **Alby**                       | Custodial                | ✅                  | Low                            | ❌                        | Low               | Provider-managed         | Easy              | Low                    | Transaction fees apply                       | Medium          | Browser extension wallet; suitable for web users.                                          |
+| **Breez SDK**                  | Self-custodial           | ❌                  | Medium                         | ❌                        | High              | Automatic                | Moderate          | Low                    | Minimal fees                                 | Medium          | SDK for integrating Breez wallet functionalities.                                          |
+| **OpenNode**                   | Custodial                | ✅                  | Low                            | ❌                        | Low               | Provider-managed         | Easy              | Low                    | Transaction fees apply                       | Medium          | Third-party service; suitable for merchants.                                               |
+| **Blink**                      | Custodial                | ✅                  | Low                            | ❌                        | Low               | Provider-managed         | Easy              | Low                    | Transaction fees apply                       | Medium          | Third-party service; focuses on mobile integrations.                                       |
+| **ZBD**                        | Custodial                | ✅                  | Low                            | ❌                        | Low               | Provider-managed         | Easy              | Low                    | Transaction fees apply                       | Medium          | Gaming-focused payment platform.                                                           |
+| **Spark (CLN)**                | Self-custodial           | ❌                  | Higher                         | ✅                        | High              | Manual                   | Moderate          | High                   | Infrastructure cost and channel opening fees | High            | Web interface for CLN; requires Spark server setup.                                        |
+| **Spark (L2)**                 | Self-custodial           | ❌                  | Medium                         | ❌                        | High              | Automatic                | Easy              | Low                    | Minimal fees                                 | Medium          | Runs via Spark sidecar; seed-based self-custody.                                           |
+| **Cliche Wallet**              | Self-custodial           | ❌                  | Medium                         | ❌                        | Medium            | Manual                   | Moderate          | Moderate               | Minimal fees                                 | Medium          | Lightweight wallet; suitable for embedded systems.                                         |
+| **Strike**                     | Custodial                | ✅                  | Low                            | ❌                        | Low               | Provider-managed         | Easy              | Low                    | Transaction fees apply                       | Medium          | Third-party service; suitable for quick setups.                                            |
+| **LNPay**                      | Custodial                | ✅                  | Low                            | ❌                        | Low               | Provider-managed         | Easy              | Low                    | Transaction fees apply                       | Medium          | Third-party service; suitable for quick setups.                                            |
+| **Eclair (ACINQ)**             | Self-custodial           | ❌                  | Higher                         | ✅                        | High              | Manual                   | Moderate          | High                   | Infrastructure cost and channel opening fees | High            | Connects via API; you run and manage your Eclair node.                                     |
+| **LN.tips**                    | Custodial/Self-Custodial | Depends on provider | Medium                         | ❌                        | Low               | Provider-managed         | Moderate          | Low                    | Transaction fees may apply                   | Medium          | Simple hosted service; use LN.tips API as your backend.                                    |
+| **Fake Wallet**                | Testing (simulated)      | ❌                  | Low                            | ❌                        | N/A               | N/A                      | Easy              | Low                    | None (test only)                             | N/A             | For testing only; mints accounting units in LNbits (no real sats, unit name configurable). |
+
+## Spark (L2)
+
+Spark L2 uses a local Node.js sidecar to expose an HTTP API that LNbits can use as a funding source. It is self-custodial and secured by a standard mnemonic seed. Sidecar repo `https://github.com/lnbits/spark_sidecar`.
+
+### Notes for readers
+
+- These are typical characteristics; your exact experience may vary by configuration and provider policy.
+- Pick based on your constraints: compliance (KYC), privacy, ops effort, and time-to-ship.
+
+---
+
+## Additional Guides
+
+- **[Admin UI](./admin_ui.md)** — Manage server settings via a clean UI (avoid editing `.env` by hand).
+- **[User Roles](./User_Roles.md)** — Quick Overview of existing Roles in LNBits.
+- **[Funding sources](./funding-sources_table.md)** — What’s available and how to enable/configure each.
+
+## Powered by LNbits
+
+LNbits empowers everyone with modular, open-source tools for building Bitcoin-based systems — fast, free, and extendable.
+
+If you like this project, [send some tip love](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg) or visit our [Shop](https://shop.lnbits.de)
+
+[![LNbits Shop](https://demo.lnbits.com/static/images/bitcoin-shop-banner.png)](https://shop.lnbits.com/)
+[![Visit LNbits Shop](https://img.shields.io/badge/Visit-LNbits%20Shop-7C3AED?logo=shopping-cart&logoColor=white&labelColor=5B21B6)](https://shop.lnbits.com/)
+[![Try myLNbits SaaS](https://img.shields.io/badge/Try-myLNbits%20SaaS-2563EB?logo=lightning&logoColor=white&labelColor=1E40AF)](https://my.lnbits.com/login)
+[![Read LNbits News](https://img.shields.io/badge/Read-LNbits%20News-F97316?logo=rss&logoColor=white&labelColor=C2410C)](https://news.lnbits.com/)
+[![Explore LNbits Extensions](https://img.shields.io/badge/Explore-LNbits%20Extensions-10B981?logo=puzzle-piece&logoColor=white&labelColor=065F46)](https://extensions.lnbits.com/)

docs/guide/installation.md

@@ -1,39 +1,146 @@
 ---
 layout: default
-title: Basic installation
-nav_order: 2
+title: Installation
+nav_order: 1
 ---
 
+<a href="https://lnbits.com" target="_blank" rel="noopener noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/QE6SIrs.png">
+    <img src="https://i.imgur.com/fyKPgVT.png" alt="LNbits" style="width:300px">
+  </picture>
+</a>
+
+![phase: stable](https://img.shields.io/badge/phase-stable-2EA043) ![License: MIT](https://img.shields.io/badge/License-MIT-blue) ![PRs: welcome](https://img.shields.io/badge/PRs-Welcome-yellow) [![explore: LNbits extensions](https://img.shields.io/badge/explore-LNbits%20extensions-10B981)](https://extensions.lnbits.com/) [<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits)
+
 # Basic installation
 
-Note that by default LNbits uses SQLite as its database, which is simple and effective but you can configure it to use PostgreSQL instead which is also described in a section below.
+> [!NOTE]
+> **Default DB:** LNbits uses SQLite by default (simple & effective). You can switch to PostgreSQL — see the section below.
 
-## Option 1: AppImage (LInux)
+## Table of contents
 
-### AppImage (Linux)
+- [Option 1: AppImage (Linux)](#option-1-appimage-linux)
+- [Option 2: UV (recommended for developers)](#option-2-uv-recommended-for-developers)
+- [Option 2a (Legacy): Poetry — Replaced by UV](#option-2a-legacy-poetry--replaced-by-uv)
+- [Option 3: Install script (Debian/Ubuntu)](#option-3-install-script-debianubuntu)
+- [Option 4: Nix](#option-4-nix)
+- [Option 5: Docker](#option-5-docker)
+- [Option 6: Fly.io](#option-6-flyio)
+- [Troubleshooting](#troubleshooting)
+- [Optional: PostgreSQL database](#optional-postgresql-database)
+- [Using LNbits](#using-lnbits)
+- [Additional guides](#additional-guides)
+  - [Update LNbits (all methods)](#update-lnbits-all-methods)
+  - [SQLite → PostgreSQL migration](#sqlite--postgresql-migration)
+  - [LNbits as a systemd service](#lnbits-as-a-systemd-service)
+  - [Reverse proxy with automatic HTTPS (Caddy)](#reverse-proxy-with-automatic-https-caddy)
+  - [Apache2 reverse proxy over HTTPS](#apache2-reverse-proxy-over-https)
+  - [Nginx reverse proxy over HTTPS](#nginx-reverse-proxy-over-https)
+  - [HTTPS without a reverse proxy (self-signed)](#https-without-a-reverse-proxy-self-signed)
+  - [LNbits on Umbrel behind Tor](#lnbits-on-umbrel-behind-tor)
+  - [FreeBSD notes](#freebsd-notes)
 
-Go to [releases](https://github.com/lnbits/lnbits/releases) and pull latest AppImage, or:
+## Option 1: AppImage (Linux)
+
+**Quickstart**
+
+1. Download latest AppImage from [releases](https://github.com/lnbits/lnbits/releases) **or** run:
 
 ```sh
-sudo apt-get install libfuse2
+sudo apt-get install jq libfuse2
 wget $(curl -s https://api.github.com/repos/lnbits/lnbits/releases/latest | jq -r '.assets[] | select(.name | endswith(".AppImage")) | .browser_download_url') -O LNbits-latest.AppImage
 chmod +x LNbits-latest.AppImage
-./LNbits-latest.AppImage --host 0.0.0.0 --port 5000
+LNBITS_ADMIN_UI=true HOST=0.0.0.0 PORT=5000 AUTH_HTTPS_ONLY=false ./LNbits-latest.AppImage # most system settings are now in the admin UI, but pass additional .env variables here
 ```
 
-LNbits will create a folder for db and extension files in the folder the AppImage runs from.
+- LNbits will create a folder for DB and extension files **in the same directory** as the AppImage.
 
-## Option 2: Poetry (recommended for developers)
+> [!NOTE]
+> **Next steps**
+> Install complete → **[Running LNbits](#run-the-server)**
+> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
 
-It is recommended to use the latest version of Poetry. Make sure you have Python version `3.12` installed.
+## Option 2: UV (recommended for developers)
 
-### Install Python 3.12
+> [!IMPORTANT]
+> **It is recommended to use the latest version of UV & Make sure you have Python version 3.12 installed.**
+
+### Verify Python
+
+```sh
+python3 --version
+```
+
+### Install UV
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Install LNbits
+
+```sh
+git clone https://github.com/lnbits/lnbits.git
+cd lnbits
+git checkout main
+uv sync --all-extras
+
+cp .env.example .env
+# Optional: set funding source and other options in .env (e.g., `nano .env`)
+```
+
+### Run the server
+
+```sh
+uv run lnbits
+# To change port/host: uv run lnbits --port 9000 --host 0.0.0.0
+# Add --debug to the command above and set DEBUG=true in .env for verbose output
+```
+
+### LNbits CLI
+
+```sh
+# Useful for superuser ID, updating extensions, etc.
+uv run lnbits-cli --help
+```
+
+### Update LNbits
+
+```sh
+cd lnbits
+# Stop LNbits with Ctrl + X or your service manager
+# sudo systemctl stop lnbits
+
+# Update code
+git pull --rebase
+
+uv sync --all-extras
+uv run lnbits
+```
+
+#### Use Admin UI → Extensions → "Update All" to bring extensions up to the proper level
+
+> [!NOTE]
+> **Next steps**
+> Install complete → **[Running LNbits](#run-the-server)**
+> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
+
+## Option 2a (Legacy): Poetry — _Replaced by UV_
+
+<details>
+<summary><strong>Poetry install and update (legacy workflow)</summary>
+
+This legacy section is preserved for older environments.
+**UV is the recommended (and faster) tool** for new installs. Use Poetry only if you have personal preferences or must support an older workflow.
+
+> ![IMPORTANT](https://img.shields.io/badge/IMPORTANT-7c3aed?labelColor=494949)
+> **It is recommended to use the latest version of Poetry & Make sure you have Python version 3.12 installed.**
+
+### Verify Python version
 
 ```sh
-sudo add-apt-repository -y ppa:deadsnakes/ppa
-sudo apt update -y
-sudo apt install -y python3.12 python3.12-dev # ensure correct headers needed for secp256k1
-sudo apt install -y pkg-config python3-dev build-essential # ensure correct headers
 python3 --version
 ```
 
@@ -44,7 +151,7 @@ python3 --version
 curl -sSL https://install.python-poetry.org | python3 - && export PATH="$HOME/.local/bin:$PATH"
 ```
 
-### install LNbits
+### Install LNbits
 
 ```sh
 git clone https://github.com/lnbits/lnbits.git
@@ -60,15 +167,14 @@ cp .env.example .env
 
 ```sh
 poetry run lnbits
-# To change port/host pass 'poetry run lnbits --port 9000 --host 0.0.0.0'
-# adding --debug in the start-up command above to help your troubleshooting and generate a more verbose output
-# Note that you have to add the line DEBUG=true in your .env file, too.
+# To change port/host: poetry run lnbits --port 9000 --host 0.0.0.0
+# Add --debug to help troubleshooting (also set DEBUG=true in .env)
 ```
 
-#### LNbits-cli
+#### LNbits CLI
 
 ```sh
-# A very useful terminal client for getting the supersuer ID, updating extensions, etc
+# A very useful terminal client for getting the superuser ID, updating extensions, etc.
 poetry run lnbits-cli --help
 ```
 
@@ -76,32 +182,96 @@ poetry run lnbits-cli --help
 
 ```sh
 cd lnbits
-# Stop LNbits with `ctrl + x`
-git pull
-# Keep your poetry install up to date, this can be done with `poetry self update`
+# Stop LNbits with Ctrl + X or with your service manager
+# sudo systemctl stop lnbits
+
+# Update LNbits
+git pull --rebase
+
+# Check your Poetry Python version
+poetry env list
+# If version is less than 3.12, update it:
+poetry env use python3.12
+poetry env remove python3.X
+poetry env list
+
+# Reinstall and start
 poetry install --only main
-# Start LNbits with `poetry run lnbits`
+poetry run lnbits
 ```
 
-## Option 3: Nix
+#### Use Admin UI → Extensions → "Update All" to bring extensions up to the proper level
+
+> ![NOTE](https://img.shields.io/badge/NOTE-3b82f6?labelColor=494949)
+> **Next steps**
+> Install complete → **[Running LNbits](#run-the-server)**
+> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
+
+</details>
+
+## Option 3: Install script (Debian/Ubuntu)
+
+<details>
+<summary><strong>Show install script</strong> (one-line setup)</summary>
+
+```sh
+wget https://raw.githubusercontent.com/lnbits/lnbits/main/lnbits.sh &&
+chmod +x lnbits.sh &&
+./lnbits.sh
+```
+
+- You can use `./lnbits.sh` to run, but for more control: `cd lnbits` and use `uv run lnbits` (see Option 2).
+
+> ![NOTE](https://img.shields.io/badge/NOTE-3b82f6?labelColor=494949)
+> **Next steps**
+> Install complete → **[Running LNbits](#run-the-server)**
+> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
+
+</details>
+
+## Option 4: Nix
+
+<details>
+<summary><strong>Show Nix instructions</strong> (flakes, cachix, run)</summary>
 
 ```sh
 # Install nix. If you have installed via another manager, remove and use this install (from https://nixos.org/download)
-sh <(curl -L https://nixos.org/nix/install) --daemon
+sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon --yes
 
 # Enable nix-command and flakes experimental features for nix:
-echo 'experimental-features = nix-command flakes' >> /etc/nix/nix.conf
+grep -qxF 'experimental-features = nix-command flakes' /etc/nix/nix.conf || \
+echo 'experimental-features = nix-command flakes' | sudo tee -a /etc/nix/nix.conf
+
+# Add user to Nix
+grep -qxF "trusted-users = root $USER" /etc/nix/nix.conf || \
+echo "trusted-users = root $USER" | sudo tee -a /etc/nix/nix.conf
+
+# Restart daemon so changes apply
+sudo systemctl restart nix-daemon
+
+# Clone and build LNbits
+git clone https://github.com/lnbits/lnbits.git
+cd lnbits
+
+# Make data directory and persist data/extension folders
+mkdir data
+PROJECT_DIR="$(pwd)"
+{
+  echo "export PYTHONPATH=\"$PROJECT_DIR/ns:\$PYTHONPATH\""
+  echo "export LNBITS_DATA_FOLDER=\"$PROJECT_DIR/data\""
+  echo "export LNBITS_EXTENSIONS_PATH=\"$PROJECT_DIR\""
+} >> ~/.bashrc
+grep -qxF '. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ~/.bashrc || \
+  echo '. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' >> ~/.bashrc
+. ~/.bashrc
 
 # Add cachix for cached binaries
 nix-env -iA cachix -f https://cachix.org/api/v1/install
 cachix use lnbits
 
-# Clone and build LNbits
-git clone https://github.com/lnbits/lnbits.git
-cd lnbits
+# Build LNbits
 nix build
 
-mkdir data
 ```
 
 #### Running the server
@@ -115,24 +285,39 @@ but you can also set the env variables or pass command line arguments:
 
 ```sh
 # .env variables are currently passed when running, but LNbits can be managed with the admin UI.
-LNBITS_ADMIN_UI=true ./result/bin/lnbits --port 9000
-
-# Once you have created a user, you can set as the super_user
-SUPER_USER=be54db7f245346c8833eaa430e1e0405 LNBITS_ADMIN_UI=true ./result/bin/lnbits --port 9000
+LNBITS_ADMIN_UI=true AUTH_HTTPS_ONLY=false ./result/bin/lnbits --port 9000 --host 0.0.0.0
 ```
 
-## Option 4: Docker
+> ![NOTE](https://img.shields.io/badge/NOTE-3b82f6?labelColor=494949)
+> **Next steps**
+> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
 
-use latest version from docker hub
+</details>
+
+## Option 5: Docker
+
+<details>
+<summary><strong>Show Docker instructions</strong> (official image, volumes, extensions)</summary>
+
+**Use latest image**
 
 ```sh
 docker pull lnbits/lnbits
 wget https://raw.githubusercontent.com/lnbits/lnbits/main/.env.example -O .env
 mkdir data
-docker run --detach --publish 5000:5000 --name lnbits --volume ${PWD}/.env:/app/.env --volume ${PWD}/data/:/app/data lnbits/lnbits
+docker run --detach --publish 5000:5000 --name lnbits \
+  --volume ${PWD}/.env:/app/.env \
+  --volume ${PWD}/data/:/app/data \
+  lnbits/lnbits
 ```
 
-build the image yourself
+- The LNbits Docker image ships **without any extensions**; by default, any extensions you install are stored **inside the container** and will be **lost** when the container is removed, so you should set `LNBITS_EXTENSIONS_PATH` to a directory that’s **mapped to a persistent host volume** so extensions **survive rebuilds/recreates**—for example:
+
+```sh
+docker run ... -e "LNBITS_EXTENSIONS_PATH='/app/data/extensions'" --volume ${PWD}/data/:/app/data ...
+```
+
+**Build image yourself**
 
 ```sh
 git clone https://github.com/lnbits/lnbits.git
@@ -140,18 +325,39 @@ cd lnbits
 docker build -t lnbits/lnbits .
 cp .env.example .env
 mkdir data
-docker run --detach --publish 5000:5000 --name lnbits --volume ${PWD}/.env:/app/.env --volume ${PWD}/data/:/app/data lnbits/lnbits
+docker run --detach --publish 5000:5000 --name lnbits \
+  --volume ${PWD}/.env:/app/.env \
+  --volume ${PWD}/data/:/app/data \
+  lnbits/lnbits
 ```
 
-## Option 5: Fly.io
+You can optionally override the install extras for both **Poetry** and **UV** to include optional features during build or setup:
 
-Fly.io is a docker container hosting platform that has a generous free tier. You can host LNbits for free on Fly.io for personal use.
+- with Poetry, pass extras via the `POETRY_INSTALL_ARGS` Docker build-arg (e.g., to enable the **Breez** funding source: `docker build --build-arg POETRY_INSTALL_ARGS="-E breez" -t lnbits/lnbits .`);
+- with UV, enable extras during environment sync (e.g., locally run `uv sync --extra breez` or `uv sync --all-extras`), and—**if your Dockerfile supports it**—you can mirror the same at build time via a build-arg such as `UV_SYNC_ARGS` (example pattern: `docker build --build-arg UV_SYNC_ARGS="--extra breez" -t lnbits/lnbits .`).
 
-First, sign up for an account at [Fly.io](https://fly.io) (no credit card required).
+**Enable Breez funding source at build**
 
-Then, install the Fly.io CLI onto your device [here](https://fly.io/docs/getting-started/installing-flyctl/).
+```sh
+docker build --build-arg POETRY_INSTALL_ARGS="-E breez" -t lnbits/lnbits .
+```
 
-After install is complete, the command will output a command you should copy/paste/run to get `fly` into your `$PATH`. Something like:
+> ![NOTE](https://img.shields.io/badge/NOTE-3b82f6?labelColor=494949)
+> **Next steps**
+> Install complete → **[Running LNbits](#run-the-server)**
+> Update LNBits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
+
+</details>
+
+## Option 6: Fly.io
+
+<details>
+<summary><strong>Deploy LNbits on Fly.io (free tier friendly)</summary>
+
+**Fly.io is a docker container hosting platform that has a generous free tier. You can host LNbits for free on Fly.io for personal use.**
+
+1. Create an account at [Fly.io](https://fly.io).
+2. Install the Fly.io CLI ([guide](https://fly.io/docs/getting-started/installing-flyctl/)).
 
 ```
 flyctl was installed successfully to /home/ubuntu/.fly/bin/flyctl
@@ -160,9 +366,9 @@ Manually add the directory to your $HOME/.bash_profile (or similar)
   export PATH="$FLYCTL_INSTALL/bin:$PATH"
 ```
 
-You can either run those commands, then `source ~/.bash_profile` or, if you don't, you'll have to call Fly from `~/.fly/bin/flyctl`.
+3. You can either run those commands, then `source ~/.bash_profile` or, if you don't, you'll have to call Fly from `~/.fly/bin/flyctl`.
 
-Once installed, run the following commands.
+- Once installed, run the following commands.
 
 ```
 git clone https://github.com/lnbits/lnbits.git
@@ -176,9 +382,16 @@ You'll be prompted to enter an app name, region, postgres (choose no), deploy no
 
 You'll now find a file in the directory called `fly.toml`. Open that file and modify/add the following settings.
 
-Note: Be sure to replace `${PUT_YOUR_LNBITS_ENV_VARS_HERE}` with all relevant environment variables in `.env` or `.env.example`. Environment variable strings should be quoted here, so if in `.env` you have `LNBITS_ENDPOINT=https://demo.lnbits.com` in `fly.toml` you should have `LNBITS_ENDPOINT="https://demo.lnbits.com"`.
+> ![IMPORTANT](https://img.shields.io/badge/IMPORTANT-7c3aed?labelColor=494949)
+> Be sure to replace `${PUT_YOUR_LNBITS_ENV_VARS_HERE}` with all relevant environment variables in `.env` or `.env.example`.
+> Environment variable strings should be quoted here. For example, if `.env` has
+> `LNBITS_ENDPOINT=https://demo.lnbits.com`, then in `fly.toml` use
+> `LNBITS_ENDPOINT="https://demo.lnbits.com"`.
 
-Note: Don't enter secret environment variables here. Fly.io offers secrets (via the `fly secrets` command) that are exposed as environment variables in your runtime. So, for example, if using the LND_REST funding source, you can run `fly secrets set LND_REST_MACAROON=<hex_macaroon_data>`.
+> ![WARNING](https://img.shields.io/badge/WARNING-ea580c?labelColor=494949)
+> Don't enter secret environment variables here. Fly.io offers **secrets** (via `fly secrets`) that are exposed as env vars at runtime.
+> Example (LND REST funding source):
+> `fly secrets set LND_REST_MACAROON=<hex_macaroon_data>`
 
 ```
 ...
@@ -233,26 +446,49 @@ sudo apt install python3.10-dev gcc build-essential
 poetry add setuptools wheel
 ```
 
-### Optional: PostgreSQL database
+> ![NOTE](https://img.shields.io/badge/NOTE-3b82f6?labelColor=0b0b0b)
+>
+> **Next steps**
+> Install complete → **[Running LNbits](#run-the-server)**
+> Update LNbits → **[Update LNbits (all methods)](#update-lnbits-all-methods)**
 
-If you want to use LNbits at scale, we recommend using PostgreSQL as the backend database. Install Postgres and setup a database for LNbits:
+## Troubleshooting
 
 ```sh
-# on debian/ubuntu 'sudo apt-get -y install postgresql'
-# or follow instructions at https://www.postgresql.org/download/linux/
+sudo apt install pkg-config libffi-dev libpq-dev
 
-# Postgres doesn't have a default password, so we'll create one.
+# build essentials (Debian/Ubuntu)
+sudo apt install python3.10-dev gcc build-essential
+
+# if secp256k1 build fails and you used poetry
+poetry add setuptools wheel
+```
+
+</details>
+
+</details>
+
+## Optional: PostgreSQL database
+
+> [!TIP]
+> If you want to use LNbits at scale, we recommend using PostgreSQL as the backend database. Install Postgres and set up a database for LNbits.
+
+```sh
+# Debian/Ubuntu: sudo apt-get -y install postgresql
+# or see https://www.postgresql.org/download/linux/
+
+# Create a password for the postgres user
 sudo -i -u postgres
 psql
-# on psql
-ALTER USER postgres PASSWORD 'myPassword'; # choose whatever password you want
+# in psql
+ALTER USER postgres PASSWORD 'myPassword';
 \q
-# on postgres user
+# back as postgres user
 createdb lnbits
 exit
 ```
 
-You need to edit the `.env` file.
+**Configure LNbits**
 
 ```sh
 # add the database connection string to .env 'nano .env' LNBITS_DATABASE_URL=
@@ -263,44 +499,189 @@ LNBITS_DATABASE_URL="postgres://postgres:postgres@localhost:5432/lnbits"
 
 # Using LNbits
 
-Now you can visit your LNbits at http://localhost:5000/.
+Visit **[http://localhost:5000/](http://localhost:5000/)** (or `0.0.0.0:5000`).
 
-Now modify the `.env` file with any settings you prefer and add a proper [funding source](./wallets.md) by modifying the value of `LNBITS_BACKEND_WALLET_CLASS` and providing the extra information and credentials related to the chosen funding source.
+### Option A — First-run setup in the Browser (UI)
 
-Then you can restart it and it will be using the new settings.
+1. On the **first start**, LNbits will **prompt you to Setup a SuperUser**.
+2. After creating it, you’ll be **redirected to the Admin UI as SuperUser**.
+3. In the Admin UI, **set your funding source** (backend wallet) and other preferences.
+4. **Restart LNbits** if prompted or after changing critical settings.
 
-You might also need to install additional packages or perform additional setup steps, depending on the chosen backend. See [the short guide](./wallets.md) on each different funding source.
+> [!IMPORTANT]
+> Use the **SuperUser only** for initial setup and instance settings (funding source, configuration, Topup).
+> For maintenance, create a separate **Admin** account. For everyday usage (payments, wallets, etc.), **do not use the SuperUser** — use admin or regular user accounts instead. Its a bad behaviour.
+> Read more about [SuperUser](./super_user.md) and [Admin UI](./admin_ui.md)
 
-Take a look at [Polar](https://lightningpolar.com/) for an excellent way of spinning up a Lightning Network dev environment.
+### Option B — Configure via `.env`
+
+1. Edit your `.env` with preferred settings (funding, base URL, etc.).
+2. Set a funding source by configuring:
+   - `LNBITS_BACKEND_WALLET_CLASS`
+   - plus the required credentials for your chosen backend (see **[wallets.md](./wallets.md)**).
+
+3. **Restart LNbits** to apply changes.
+
+---
+
+> [!NOTE]
+> **Paths overview**
+>
+> - **SuperUser file:** `<lnbits_root>/data/.super_user`
+>   Example: `~/lnbits/data/.super_user` • View: `cat ~/lnbits/data/.super_user`
+> - **Environment file:** `<lnbits_root>/.env` (for bare-metal installs)
+> - **Docker:** bind a host directory to `/app/data`.
+>   On the host the SuperUser file is at `<host_data_dir>/.super_user`.
+>   The container reads `/app/.env` (usually bind-mounted from your project root).
+
+> [!TIP]
+> **Local Lightning test network**
+> Use **Polar** to spin up a safe local Lightning environment and test LNbits without touching your live setup.
+> https://lightningpolar.com/
+
+> [!TIP]
+> **API comparison before updates**
+> Use **TableTown** to diff your LNbits instance against another (dev vs prod) or the upstream dev branch. Spot endpoint changes before updating.
+> Crafted by [Arbadacarbayk](https://github.com/arbadacarbaYK) - a standout contribution that makes pre-release reviews fast and reliable.
+> https://arbadacarbayk.github.io/LNbits_TableTown/
 
 # Additional guides
 
-## SQLite to PostgreSQL migration
+## Update LNbits (all methods)
 
-If you already have LNbits installed and running, on an SQLite database, we **highly** recommend you migrate to postgres if you are planning to run LNbits on scale.
+> After updating, open **Admin UI → Extensions → “Update All”** to make sure extensions match the core version.
 
-There's a script included that can do the migration easy. You should have Postgres already installed and there should be a password for the user (see Postgres install guide above). Additionally, your LNbits instance should run once on postgres to implement the database schema before the migration works:
+<details>
+<summary><strong>UV (recommended)</strong></summary>
+
+```sh
+cd lnbits
+git pull --rebase
+uv sync --all-extras
+# restart (dev)
+uv run lnbits
+```
+
+</details>
+
+<details>
+<summary><strong>Poetry (legacy)</strong></summary>
+
+```sh
+cd lnbits
+git pull --rebase
+# Optional: ensure Python 3.12
+poetry env list
+poetry env use python3.12
+poetry install --only main
+# restart (dev)
+poetry run lnbits
+```
+
+</details>
+
+<details>
+<summary><strong>AppImage</strong></summary>
+
+Download the latest AppImage from Releases and replace your old file **in the same directory** to keep the `./data` folder (DB, extensions).
+
+</details>
+
+<details>
+<summary><strong>Install script (Debian/Ubuntu)</strong></summary>
+
+```sh
+# If you installed via lnbits.sh:
+cd lnbits
+git pull --rebase
+# then use your chosen runner (UV recommended)
+uv sync --all-extras
+uv run lnbits
+```
+
+</details>
+
+<details>
+<summary><strong>Nix</strong></summary>
+
+```sh
+cd lnbits
+git pull --rebase
+nix build
+# restart
+nix run
+```
+
+</details>
+
+<details>
+<summary><strong>Docker (official image)</strong></summary>
+
+```sh
+docker pull lnbits/lnbits
+docker stop lnbits && docker rm lnbits
+docker run --detach --publish 5000:5000 --name lnbits \
+  --volume ${PWD}/.env:/app/.env \
+  --volume ${PWD}/data/:/app/data \
+  lnbits/lnbits
+```
+
+</details>
+
+<details>
+<summary><strong>Docker (build yourself)</strong></summary>
+
+```sh
+cd lnbits
+git pull --rebase
+docker build -t lnbits/lnbits .
+docker stop lnbits && docker rm lnbits
+docker run --detach --publish 5000:5000 --name lnbits \
+  --volume ${PWD}/.env:/app/.env \
+  --volume ${PWD}/data/:/app/data \
+  lnbits/lnbits
+```
+
+</details>
+
+<details>
+<summary><strong>Fly.io</strong></summary>
+
+```sh
+# If using Dockerfile in repo (recommended)
+cd lnbits
+git pull --rebase
+fly deploy
+# Logs & shell if needed
+fly logs
+fly ssh console
+```
+
+</details>
+
+## SQLite → PostgreSQL migration
+
+> [!TIP]
+> If you run on SQLite and plan to scale, migrate to Postgres.
 
 ```sh
 # STOP LNbits
 
-# add the database connection string to .env 'nano .env' LNBITS_DATABASE_URL=
-# postgres://<user>:<password>@<host>/<database> - alter line bellow with your user, password and db name
+# Edit .env with Postgres URL
 LNBITS_DATABASE_URL="postgres://postgres:postgres@localhost/lnbits"
 # save and exit
 
-# START LNbits
-# STOP LNbits
-poetry run python tools/conv.py
+# START then STOP LNbits once to apply schema
+uv run python tools/conv.py
 # or
 make migration
 ```
 
-Hopefully, everything works and get migrated... Launch LNbits again and check if everything is working properly.
+- Launch LNbits again and verify.
 
 ## LNbits as a systemd service
 
-Systemd is great for taking care of your LNbits instance. It will start it on boot and restart it in case it crashes. If you want to run LNbits as a systemd service on your Debian/Ubuntu/Raspbian server, create a file at `/etc/systemd/system/lnbits.service` with the following content:
+Create `/etc/systemd/system/lnbits.service`:
 
 ```
 # Systemd unit for lnbits
@@ -308,17 +689,14 @@ Systemd is great for taking care of your LNbits instance. It will start it on bo
 
 [Unit]
 Description=LNbits
-# you can uncomment these lines if you know what you're doing
-# it will make sure that lnbits starts after lnd (replace with your own backend service)
+# Optional: start after your backend
 #Wants=lnd.service
 #After=lnd.service
 
 [Service]
-# replace with the absolute path of your lnbits installation
 WorkingDirectory=/home/lnbits/lnbits
-# same here. run `which poetry` if you can't find the poetry binary
-ExecStart=/home/lnbits/.local/bin/poetry run lnbits
-# replace with the user that you're running lnbits on
+# Find uv path via `which uv`
+ExecStart=/home/lnbits/.local/bin/uv run lnbits
 User=lnbits
 Restart=always
 TimeoutSec=120
@@ -329,33 +707,23 @@ Environment=PYTHONUNBUFFERED=1
 WantedBy=multi-user.target
 ```
 
-Save the file and run the following commands:
+Enable & start:
 
 ```sh
 sudo systemctl enable lnbits.service
 sudo systemctl start lnbits.service
 ```
 
-## Reverse proxy with automatic HTTPS using Caddy
+## Reverse proxy with automatic HTTPS (Caddy)
 
-Use Caddy to make your LNbits install accessible over clearnet with a domain and https cert.
+Point your domain A-record to your server IP. Install Caddy: [Caddy install guide](https://caddyserver.com/docs/install#debian-ubuntu-raspbian)
 
-Point your domain at the IP of the server you're running LNbits on, by making an `A` record.
-
-Install Caddy on the server
-https://caddyserver.com/docs/install#debian-ubuntu-raspbian
-
-```
+```sh
 sudo caddy stop
-```
-
-Create a Caddyfile
-
-```
 sudo nano Caddyfile
 ```
 
-Assuming your LNbits is running on port `5000` add:
+Add:
 
 ```
 yourdomain.com {
@@ -365,28 +733,21 @@ yourdomain.com {
 }
 ```
 
-Save and exit `CTRL + x`
+Save (Ctrl+X) and start:
 
-```
+```sh
 sudo caddy start
 ```
 
-## Running behind an Apache2 reverse proxy over HTTPS
-
-Install Apache2 and enable Apache2 mods:
+## Apache2 reverse proxy over HTTPS
 
 ```sh
 apt-get install apache2 certbot
 a2enmod headers ssl proxy proxy_http
-```
-
-Create a SSL certificate with LetsEncrypt:
-
-```sh
 certbot certonly --webroot --agree-tos --non-interactive --webroot-path /var/www/html -d lnbits.org
 ```
 
-Create an Apache2 vhost at: `/etc/apache2/sites-enabled/lnbits.conf`:
+Create `/etc/apache2/sites-enabled/lnbits.conf`:
 
 ```sh
 cat <<EOF > /etc/apache2/sites-enabled/lnbits.conf
@@ -413,27 +774,20 @@ cat <<EOF > /etc/apache2/sites-enabled/lnbits.conf
 EOF
 ```
 
-Restart Apache2:
+Restart:
 
 ```sh
 service apache2 restart
 ```
 
-## Running behind an Nginx reverse proxy over HTTPS
-
-Install nginx:
+## Nginx reverse proxy over HTTPS
 
 ```sh
 apt-get install nginx certbot
-```
-
-Create a SSL certificate with LetsEncrypt:
-
-```sh
 certbot certonly --nginx --agree-tos -d lnbits.org
 ```
 
-Create an nginx vhost at `/etc/nginx/sites-enabled/lnbits.org`:
+Create `/etc/nginx/sites-enabled/lnbits.org`:
 
 ```sh
 cat <<EOF > /etc/nginx/sites-enabled/lnbits.org
@@ -467,23 +821,22 @@ server {
 EOF
 ```
 
-Restart nginx:
+Restart:
 
 ```sh
 service nginx restart
 ```
 
-## Using https without reverse proxy
+---
 
-The most common way of using LNbits via https is to use a reverse proxy such as Caddy, nginx, or ngriok. However, you can also run LNbits via https without additional software. This is useful for development purposes or if you want to use LNbits in your local network.
+## HTTPS without a reverse proxy (self-signed)
 
-We have to create a self-signed certificate using `mkcert`. Note that this certificate is not "trusted" by most browsers but that's fine (since you know that you have created it) and encryption is always better than clear text.
+Create a self-signed cert (useful for local/dev). Browsers won’t trust it by default.
 
-#### Install mkcert
+### Install mkcert
 
-You can find the install instructions for `mkcert` [here](https://github.com/FiloSottile/mkcert).
-
-Install mkcert on Ubuntu:
+- Install instructions: [mkcert README](https://github.com/FiloSottile/mkcert)
+- Ubuntu example:
 
 ```sh
 sudo apt install libnss3-tools
@@ -492,61 +845,47 @@ chmod +x mkcert-v*-linux-amd64
 sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
 ```
 
-#### Create certificate
+### Create certificate
 
-To create a certificate, first `cd` into your LNbits folder and execute the following command on Linux:
+**OpenSSL**
 
 ```sh
 openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out cert.pem -keyout key.pem
 ```
 
-This will create two new files (`key.pem` and `cert.pem `).
-
-Alternatively, you can use mkcert ([more info](https://kifarunix.com/how-to-create-self-signed-ssl-certificate-with-mkcert-on-ubuntu-18-04/)):
+**mkcert** (alternative)
 
 ```sh
-# add your local IP (192.x.x.x) as well if you want to use it in your local network
+# include your local IP (e.g., 192.x.x.x) if needed
 mkcert localhost 127.0.0.1 ::1
 ```
 
-You can then pass the certificate files to uvicorn when you start LNbits:
+**Run with certs**
 
 ```sh
 poetry run uvicorn lnbits.__main__:app --host 0.0.0.0 --port 5000 --ssl-keyfile ./key.pem --ssl-certfile ./cert.pem
 ```
 
-## LNbits running on Umbrel behind Tor
+## LNbits on Umbrel behind Tor
 
-If you want to run LNbits on your Umbrel but want it to be reached through clearnet, _Uxellodunum_ made an extensive [guide](https://community.getumbrel.com/t/guide-lnbits-without-tor/604) on how to do it.
+See this community [guide](https://community.getumbrel.com/t/guide-lnbits-without-tor/604).
 
-## Docker installation
+## FreeBSD notes
 
-To install using docker you first need to build the docker image as:
+Issue with secp256k1 0.14.0 on FreeBSD (thanks @GitKalle):
 
-```
-git clone https://github.com/lnbits/lnbits.git
-cd lnbits
-docker build -t lnbits/lnbits .
-```
+1. Install `py311-secp256k1` with `pkg install py311-secp256k1`.
+2. Change version in `pyproject.toml` from `0.14.0` to `0.13.2`.
+3. Rewrite `poetry.lock` with `poetry lock`.
+4. Follow install instructions with Poetry.
 
-You can launch the docker in a different directory, but make sure to copy `.env.example` from lnbits there
+---
 
-```
-cp <lnbits_repo>/.env.example .env
-```
+## Powered by LNbits
 
-and change the configuration in `.env` as required.
+LNbits empowers everyone with modular, open-source tools for building Bitcoin-based systems — fast, free, and extendable.
 
-Then create the data directory
+If you like this project [send some tip love](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg) or visiting our [Shop](https://shop.lnbits.com)
 
-```
-mkdir data
-```
-
-Then the image can be run as:
-
-```
-docker run --detach --publish 5000:5000 --name lnbits -e "LNBITS_BACKEND_WALLET_CLASS='FakeWallet'" --volume ${PWD}/.env:/app/.env --volume ${PWD}/data/:/app/data lnbits
-```
-
-Finally you can access your lnbits on your machine at port 5000.
+[![LNbits Shop](https://demo.lnbits.com/static/images/bitcoin-shop-banner.png)](https://shop.lnbits.com/)
+[![Visit LNbits Shop](https://img.shields.io/badge/Visit-LNbits%20Shop-7C3AED?logo=shopping-cart&logoColor=white&labelColor=5B21B6)](https://shop.lnbits.com/) [![Try myLNbits SaaS](https://img.shields.io/badge/Try-myLNbits%20SaaS-2563EB?logo=lightning&logoColor=white&labelColor=1E40AF)](https://my.lnbits.com/login) [![Read LNbits News](https://img.shields.io/badge/Read-LNbits%20News-F97316?logo=rss&logoColor=white&labelColor=C2410C)](https://news.lnbits.com/) [![Explore LNbits Extensions](https://img.shields.io/badge/Explore-LNbits%20Extensions-10B981?logo=puzzle-piece&logoColor=white&labelColor=065F46)](https://extensions.lnbits.com/)

docs/guide/oidc-authentication.md

@@ -0,0 +1,139 @@
+# Generic OIDC Authentication Configuration
+
+This document explains how to configure generic OIDC authentication for LNbits, which allows integration with various OIDC-compliant authentication providers such as Zitadel, Authentik, and others.
+
+## Overview
+
+The generic OIDC provider (`oidc`) complements the existing Keycloak provider and allows you to integrate any OIDC-compliant authentication service. You can customize the login button with your own organization name and icon.
+
+## Configuration
+
+Add the following environment variables to your `.env` file or system environment:
+
+### Required Settings
+
+```bash
+# Enable OIDC authentication
+LNBITS_AUTH_ALLOWED_METHODS=oidc-auth
+
+# OIDC Discovery URL (well-known endpoint)
+LNBITS_OIDC_DISCOVERY_URL=https://your-oidc-provider-domain/.well-known/openid-configuration
+
+# Client credentials from your OIDC provider
+LNBITS_OIDC_CLIENT_ID=your-client-id
+LNBITS_OIDC_CLIENT_SECRET=your-client-secret
+```
+
+### Optional Settings - Customize the Login Button
+
+You can customize how the OIDC login button appears to your users:
+
+```bash
+# Custom organization name (displayed on the login button)
+# Example: "Login via Zitadel" or "Login via Authentik"
+LNBITS_OIDC_CLIENT_CUSTOM_ORG="Zitadel"
+
+# Custom icon URL (displayed on the login button)
+# Can be a full URL or a path to a local image
+LNBITS_OIDC_CLIENT_CUSTOM_ICON=https://zitadel.com/favicon.svg
+```
+
+If not set, the button will display "Login via OIDC" with a generic lock icon.
+
+## Zitadel Configuration Example
+
+For Zitadel, configure as follows:
+
+1. Create a new application in Zitadel
+2. Choose "Web" application type
+3. Configure the redirect URI: `https://your-lnbits-domain/api/v1/auth/oidc/token`
+4. Save the Client ID and Client Secret
+5. Use these environment variables:
+
+```bash
+LNBITS_AUTH_ALLOWED_METHODS=oidc-auth
+LNBITS_OIDC_DISCOVERY_URL=https://your-oidc-provider-domain/.well-known/openid-configuration
+LNBITS_OIDC_CLIENT_ID=your-zitadel-client-id
+LNBITS_OIDC_CLIENT_SECRET=your-zitadel-client-secret
+# Customize the button to show "Login via Zitadel" with Zitadel's logo
+LNBITS_OIDC_CLIENT_CUSTOM_ORG="Zitadel"
+LNBITS_OIDC_CLIENT_CUSTOM_ICON="https://zitadel.com/favicon.svg"
+```
+
+**Result**: The login page will display a button with the text "Login via Zitadel" and the Zitadel logo.
+
+## Authentik Configuration Example
+
+For Authentik:
+
+1. Create a new OAuth2/OpenID Provider
+2. Set the redirect URI: `https://your-lnbits-domain/api/v1/auth/oidc/token`
+3. Configure scopes: `openid`, `email`, `profile`
+4. Get the Client ID and Client Secret
+
+```bash
+LNBITS_AUTH_ALLOWED_METHODS=oidc-auth
+LNBITS_OIDC_DISCOVERY_URL=https://authentik.yourdomain.com/application/o/your-app/.well-known/openid-configuration
+LNBITS_OIDC_CLIENT_ID=your-authentik-client-id
+LNBITS_OIDC_CLIENT_SECRET=your-authentik-client-secret
+LNBITS_OIDC_CLIENT_CUSTOM_ORG="Authentik"
+```
+
+## Multiple Auth Methods
+
+You can enable multiple authentication methods simultaneously:
+
+```bash
+LNBITS_AUTH_ALLOWED_METHODS=username-password,oidc-auth,keycloak-auth
+```
+
+## Discovery Endpoint Requirements
+
+Your OIDC provider must expose a standard discovery endpoint (`.well-known/openid-configuration`) that includes:
+
+- `authorization_endpoint`
+- `token_endpoint`
+- `userinfo_endpoint`
+- `jwks_uri` (JSON Web Key Set)
+
+The OIDC implementation will automatically fetch these endpoints from the discovery URL.
+
+## User Mapping
+
+The OIDC provider maps user information from the OIDC userinfo endpoint:
+
+- `sub` → User ID
+- `email` → Email address
+- `given_name` → First name
+- `family_name` → Last name
+- `name` or `preferred_username` → Display name
+- `picture` → Profile picture URL
+
+## Troubleshooting
+
+### Authentication fails
+
+1. Verify the discovery URL is accessible
+2. Check that Client ID and Client Secret are correct
+3. Ensure redirect URI in your OIDC provider matches: `https://your-lnbits-domain/api/v1/auth/oidc/token`
+4. Check LNbits logs for detailed error messages
+
+### User info not populated
+
+Some OIDC providers may use different claim names. If user information is not correctly populated, check your provider's userinfo endpoint response format and adjust the provider class if needed.
+
+## Security Considerations
+
+- Always use HTTPS in production
+- Keep client secrets secure and never commit them to version control
+- Use environment variables or secure configuration management
+- Regularly rotate client secrets
+- Review OIDC provider's security best practices
+
+## Implementation Details
+
+The OIDC provider is implemented in `lnbits/core/models/sso/oidc.py` and extends the `fastapi_sso` library's `SSOBase` class. It uses the standard OpenID Connect flow with:
+
+- Scopes: `openid`, `email`, `profile`
+- Response type: `code` (authorization code flow)
+- Discovery document for automatic endpoint resolution

docs/guide/super_user.md

@@ -0,0 +1,132 @@
+---
+layout: default
+title: Super user
+nav_order: 1
+---
+
+<a href="https://lnbits.com" target="_blank" rel="noopener noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/QE6SIrs.png">
+    <img src="https://i.imgur.com/fyKPgVT.png" alt="LNbits" style="width:300px">
+  </picture>
+</a>
+
+![phase: stable](https://img.shields.io/badge/phase-stable-2EA043)
+![PRs: welcome](https://img.shields.io/badge/PRs-Welcome-yellow)
+[<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits)
+
+# LNbits Super User (SU)
+
+**Table of Contents**
+
+- [What is the Super User?](#what-is-the-super-user)
+- [When is the Super User created?](#when-is-the-super-user-created)
+- [Disabeling the Admin UI](#disabeling-the-admin-ui)
+- [Super User identity and storage](#super-user-identity-and-storage)
+- [Security model since v1](#security-model-since-v1)
+- [Admin vs Super User](#admin-vs-super-user)
+- [Operational guidance](#operational-guidance)
+- [Additional guides](#additional-guides)
+
+<details>
+  <summary><strong>TLDR</strong></summary>
+
+- **No Admin UI → No Super User.** The Super User (SU) exists only when `LNBITS_ADMIN_UI=true`.
+- **Why SU exists:** SU can do a few high impact actions regular admins cannot, like **changing the funding source**, **restarting the server from the UI**, and **crediting or debiting accounts**.
+- **Login changes since v1:** Logging in by **user ID** for SU and admins is **disabled**. On first visit after enabling the Admin UI you will be prompted to set a **username and password** for the SU.
+- **Trust model:** Admins and the SU share about **99 percent of the same powers**, but the SU is the one trusted with funding source control and cannot be demoted by regular admins.
+
+</details>
+
+## What is the Super User?
+
+The **Super User** is the owner-operator account of an LNbits instance. Think of it as your “break glass” operator with a few capabilities that are intentionally reserved for the person ultimately responsible for the server and the funding rails.
+
+The SU is created alongside the [Admin UI](./admin_ui.md) and is meant to keep enviroment operations pleasant in the UI while keeping the most sensitive knobs in trusted hands.
+
+**Key SU capabilities**
+
+- **Change the funding source** for the instance
+- **Restart the LNbits server** from the web UI
+- **Credit or debit accounts** for operational corrections
+
+> Note
+> These are separated from regular admin tasks on purpose. It helps maintain least privilege and reduces the chance of accidental or malicious changes.
+
+## Admin vs Super User
+
+| Capability               | Admin      | Super User |
+| ------------------------ | ---------- | ---------- |
+| View Admin UI            | If enabled | If enabled |
+| Change funding source    | —          | ✓          |
+| Credit or debit accounts | —          | ✓          |
+| Restart server from UI   | —          | ✓          |
+| Manage users and wallets | ✓          | ✓          |
+| Instance-level settings  | ✓          | ✓          |
+| Manage notifications     | ✓          | ✓          |
+| Exchange rates           | ✓          | ✓          |
+| View all Payments        | ✓          | ✓          |
+
+**Why both roles?**
+In many teams the person running the server prefers to **delegate day-to-day admin work** while keeping funding and final authority safe. Admins can do almost everything; the SU retains the last few high risk powers.
+
+## When is the Super User created?
+
+- The SU is created **only** when you enable the Admin UI: `LNBITS_ADMIN_UI=true`.
+- If the Admin UI is **disabled**, there is **no SU** and all SU-only UI is hidden.
+
+## Disabeling the Admin UI
+
+> [!IMPORTANT]
+> Read the [Admin UI guide](./admin_ui.md) before Disabeling. You are turning on a management surface; do it deliberately.
+
+Set the environment variable in your deployment:
+
+```bash
+# .env
+LNBITS_ADMIN_UI=false
+```
+
+## Super User identity and storage
+
+LNbits stores the **Super User ID** at:
+
+```
+/lnbits/data/.super_user
+```
+
+- Back this up along with the rest of `/lnbits/data` as part of your secure backup routine.
+- **Changing who is the SU** can only be done by someone with **CLI access to the host OS** where LNbits runs. **Regular admins cannot revoke or replace the SU in the Admin UI.**
+
+## Security model since v1
+
+- **User-ID logins are disabled** for SU and admin roles.
+- **Credentialed login is required:** set a **username and password** for the SU at first run of the Admin UI.
+- **SU secrecy:** Regular users and admins **cannot discover the SU user ID** through normal UI flows.
+
+## Operational guidance
+
+These are practical tips for running a safe and friendly instance.
+
+- It is normal to **delegate admin** duties to trusted people. Admins have about **99 percent** of SU powers for day-to-day work.
+- Keep the **SU** reserved for the person legally or operationally responsible for the **funding source**.
+- Use admin roles for regular day-to-day management and keep the SU for reserved SU tasks only.
+
+## Additional guides
+
+- **[Admin UI](./admin_ui.md)** — Manage server settings in the browser instead of editing `.env` or using the CLI for routine tasks.
+- **[User Roles](./user_roles.md)** — Overview of roles and what they can do.
+- **[Funding sources](./funding-sources-table.md)** — Available options and how to enable and configure them.
+- **[Install LNBits](./installation.md)** — Choose your prefared way to install LNBits.
+
+## Powered by LNbits
+
+LNbits empowers everyone with modular, open source tools for building Bitcoin-based systems — fast, free, and extendable.
+
+If you like this project, [send some tip love](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg) or visit our [Shop](https://shop.lnbits.de)
+
+[![LNbits Shop](https://demo.lnbits.com/static/images/bitcoin-shop-banner.png)](https://shop.lnbits.com/)
+[![Visit LNbits Shop](https://img.shields.io/badge/Visit-LNbits%20Shop-7C3AED?logo=shopping-cart&logoColor=white&labelColor=5B21B6)](https://shop.lnbits.com/)
+[![Try myLNbits SaaS](https://img.shields.io/badge/Try-myLNbits%20SaaS-2563EB?logo=lightning&logoColor=white&labelColor=1E40AF)](https://my.lnbits.com/login)
+[![Read LNbits News](https://img.shields.io/badge/Read-LNbits%20News-F97316?logo=rss&logoColor=white&labelColor=C2410C)](https://news.lnbits.com/)
+[![Explore LNbits Extensions](https://img.shields.io/badge/Explore-LNbits%20Extensions-10B981?logo=puzzle-piece&logoColor=white&labelColor=065F46)](https://extensions.lnbits.com/)

docs/guide/user_roles.md

@@ -0,0 +1,101 @@
+---
+layout: default
+title: User Roles
+nav_order: 1
+---
+
+<a href="https://lnbits.com" target="_blank" rel="noopener noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/QE6SIrs.png">
+    <img src="https://i.imgur.com/fyKPgVT.png" alt="LNbits" style="width:300px">
+  </picture>
+</a>
+
+![phase: stable](https://img.shields.io/badge/phase-stable-2EA043)
+![PRs: welcome](https://img.shields.io/badge/PRs-Welcome-yellow)
+[<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits)
+
+# LNbits Roles: A Quick Overview
+
+### Understand **who can do what** in seconds: `Super User`, `Admin`, and `Regular User`.
+
+**Jump to:**
+[Roles at a Glance](#roles-at-a-glance) •
+[Super User](#super-user--master-control) •
+[Admin](#admin--day-to-day-manager) •
+[Regular User](#regular-user--everyday-use) •
+[Best Practices](#best-practices) •
+[Additional Guides](#additional-guides)
+
+---
+
+## Roles at a Glance
+
+| Capability                       | **Super User** (owner) | **Admin** (manager) | **Regular User** (end user) |
+| -------------------------------- | :--------------------: | :-----------------: | :-------------------------: |
+| Change **funding source**        |           ✅           |         ❌          |             ❌              |
+| Credit/Debit any wallet          |           ✅           |         ❌          |             ❌              |
+| Manage Admins & Users            |           ✅           |         ✅          |             ❌              |
+| Enable/disable extensions        |           ✅           |         ✅          |             ❌              |
+| Use wallets & allowed extensions |           ✅           |         ✅          |             ✅              |
+
+> **Plain talk:** **Super User** = Owner • **Admin** = Trusted manager • **Regular User** = End user
+
+## Role Snapshots
+
+### Super User — Master Control
+
+For initial setup and rare, high-impact changes.
+
+- Configure **server-level settings** (e.g., funding source).
+- **Credit/Debit** any wallet.
+- Create and manage initial **Admin(s)**.
+
+> **Sign-in:** username + password (v1+). The old query-string login is retired.
+
+### Admin — Day-to-Day Manager
+
+For running the service without touching the most sensitive knobs.
+
+- Manage **Users**, **Admins**, and **Extensions** in the Admin UI.
+- Adjust security-related settings (e.g., `rate_limiter`, `ip_blocker`).
+- Handle operations settings (e.g., `service_fee`, `invoice_expiry`).
+- Build brand design in **Site Customization**.
+- Update user accounts.
+
+**Typical tasks:** onboarding users, enabling extensions, tidying wallets, reviewing activity.
+
+> **Sign-in:** username + password (v1+). The old query-string login is retired.
+
+### Regular User — Everyday Use
+
+For using LNbits, not administering it.
+
+- Access **personal wallets** and **allowed extensions**.
+- No server/admin privileges.
+
+**Typical tasks:** receive and send payments, use enabled extensions.
+
+## Best Practices
+
+- **Minimize risk:** Reserve **Super User** for rare, sensitive actions (funding source, debit/credit). Use **Admin** for daily operations.
+- **Keep access tidy:** Review your Admin list occasionally; remove unused accounts.
+- **Change management:** Test risky changes (like funding) in a staging setup first.
+
+## Additional Guides
+
+- **[Admin UI](./admin_ui.md)** — Manage server settings via a clean UI (avoid editing `.env` by hand).
+- **[Super User](./super_user.md)** — Deep dive on responsibilities and safe usage patterns.
+- **[Funding sources](./funding-sources-table.md)** — What’s available and how to enable/configure each.
+
+## Powered by LNbits
+
+LNbits empowers everyone with modular, open-source tools for building Bitcoin-based systems—fast, free, and extendable.
+
+If you like this project, [send some tip love](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg) or visit our [Shop](https://shop.lnbits.de)
+
+[![LNbits Shop](https://demo.lnbits.com/static/images/bitcoin-shop-banner.png)](https://shop.lnbits.com/)
+[![Visit LNbits Shop](https://img.shields.io/badge/Visit-LNbits%20Shop-7C3AED?logo=shopping-cart&logoColor=white&labelColor=5B21B6)](https://shop.lnbits.com/)
+[![Try myLNbits SaaS](https://img.shields.io/badge/Try-myLNbits%20SaaS-2563EB?logo=lightning&logoColor=white&labelColor=1E40AF)](https://my.lnbits.com/login)
+[![Read LNbits News](https://img.shields.io/badge/Read-LNbits%20News-F97316?logo=rss&logoColor=white&labelColor=C2410C)](https://news.lnbits.com/)
+[![Explore LNbits Extensions](https://img.shields.io/badge/Explore-LNbits%20Extensions-10B981?logo=puzzle-piece&logoColor=white&labelColor=065F46)](https://extensions.lnbits.com/)

docs/guide/wallets.md

@@ -4,144 +4,394 @@ title: Backend wallets
 nav_order: 3
 ---
 
+<a href="https://lnbits.com" target="_blank" rel="noopener noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/QE6SIrs.png">
+    <img src="https://i.imgur.com/fyKPgVT.png" alt="LNbits" style="width:300px">
+  </picture>
+</a>
+
+![phase: stable](https://img.shields.io/badge/phase-stable-2EA043)
+![PRs: welcome](https://img.shields.io/badge/PRs-Welcome-yellow)
+[<img src="https://img.shields.io/badge/community_chat-Telegram-24A1DE">](https://t.me/lnbits)
+
 # Backend wallets
 
-LNbits can run on top of many Lightning Network funding sources with more being added regularly.
+**LNbits is modular**: You can switch the funding source (backend wallet) **without changing anything else** in your setup. Keep your extensions, apps, users, and config as-is — just point LNbits to a different backend via environment variables.
 
-A backend wallet can be configured using the following LNbits environment variables:
+**What stays the same when you switch backends**
 
-### CoreLightning
+- Your LNbits setup and extensions
+- Your API keys and endpoints
+- Your server and deployment setup
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **CoreLightningWallet**
-- `CORELIGHTNING_RPC`: /file/path/lightning-rpc
+A backend wallet is selected and configured entirely through LNbits environment variables. See the options and variables below, and compare them here: [Funding-Source-Table.md](funding-sources-table.md)
 
-### CoreLightning REST
+> [!NOTE]
+> **Terminology:** “Backend Wallet” and “Funding Source” mean the same thing — the wallet or service that funds your LNbits.
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **CoreLightningRestWallet**
-- `CORELIGHTNING_REST_URL`: http://127.0.0.1:8185/
-- `CORELIGHTNING_REST_MACAROON`: /file/path/admin.macaroon or Base64/Hex
-- `CORELIGHTNING_REST_CERT`: /home/lightning/clnrest/tls.cert
+## Funding Sources
 
-### Spark (Core Lightning)
+## Funding Sources
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **SparkWallet**
-- `SPARK_URL`: http://10.147.17.230:9737/rpc
-- `SPARK_TOKEN`: secret_access_key
+|                                                 |                                       |                                                   |
+| ----------------------------------------------- | ------------------------------------- | ------------------------------------------------- |
+| [CLNRest (runes)](#clnrest-runes)               | [LND (REST)](#lnd-rest)               | [OpenNode](#opennode)                             |
+| [CoreLightning](#corelightning)                 | [LND (gRPC)](#lnd-grpc)               | [Blink](#blink)                                   |
+| [CoreLightning REST](#corelightning-rest)       | [LNbits](#lnbits)                     | [Alby](#alby)                                     |
+| [Spark (Core Lightning)](#spark-core-lightning) | [LNPay](#lnpay)                       | [Boltz](#boltz)                                   |
+| [Spark L2](#spark-l2)                           | [ZBD](#zbd)                           | [Phoenixd](#phoenixd)                             |
+| [Cliche Wallet](#cliche-wallet)                 |                                       |                                                   |
+| [Breez SDK](#breez-sdk)                         | [Breez Liquid SDK](#breez-liquid-sdk) | [Nostr Wallet Connect](#nostr-wallet-connect-nwc) |
+| [Strike](#strike)                               | [Eclair (ACINQ)](#eclair-acinq)       | [LN.tips](#lntips)                                |
+| [Fake Wallet](#fake-wallet)                     |                                       |                                                   |
 
-### LND (REST)
+---
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **LndRestWallet**
-- `LND_REST_ENDPOINT`: http://10.147.17.230:8080/
-- `LND_REST_CERT`: /file/path/tls.cert
-- `LND_REST_MACAROON`: /file/path/admin.macaroon or Base64/Hex
+<a id="clnrest-runes"></a>
 
-or
+### CLNRest (using [runes](https://docs.corelightning.org/reference/lightning-createrune))
 
-- `LND_REST_MACAROON_ENCRYPTED`: eNcRyPtEdMaCaRoOn
+[Core Lightning REST API docs](https://docs.corelightning.org/docs/rest)
+Should also work with the [Rust version of CLNRest](https://github.com/daywalker90/clnrest-rs)
 
-### LND (gRPC)
+**Environment variables**
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **LndWallet**
-- `LND_GRPC_ENDPOINT`: ip_address
-- `LND_GRPC_PORT`: port
-- `LND_GRPC_CERT`: /file/path/tls.cert
-- `LND_GRPC_MACAROON`: /file/path/admin.macaroon or Base64/Hex
+- `LNBITS_BACKEND_WALLET_CLASS`: `CLNRestWallet`
+- `CLNREST_URL`: `https://127.0.0.1:3010`
+- `CLNREST_CA`: `/home/lightningd/.lightning/bitcoin/ca.pem` (or the content of the file)
+- `CLNREST_CERT`: `/home/lightningd/.lightning/bitcoin/server.pem` (or the content of the file)
+- `CLNREST_LAST_PAY_INDEX`: `lightning-cli listinvoices | jq -r '.invoices | map(.created_index) | max'`
+- `CLNREST_NODEID`: `lightning-cli getinfo | jq -r .id` (only required for v23.08)
 
-You can also use an AES-encrypted macaroon (more info) instead by using
+**Create runes (copy/paste)**
 
-- `LND_GRPC_MACAROON_ENCRYPTED`: eNcRyPtEdMaCaRoOn
+```bash
+# Read-only: funds, pays, invoices, info, summary, and invoice listener
+lightning-cli createrune \
+  restrictions='[["method=listfunds","method=listpays","method=listinvoices","method=getinfo","method=summary","method=waitanyinvoice"]]' \
+| jq -r .rune
+```
 
-To encrypt your macaroon, run `poetry run python lnbits/wallets/macaroon/macaroon.py`.
+```bash
+# Invoice: max 1,000,001 msat, label must start with "LNbits", 60 req/min
+lightning-cli createrune \
+  restrictions='[["method=invoice"], ["pnameamount_msat<1000001"], ["pnamelabel^LNbits"], ["rate=60"]]' \
+| jq -r .rune
+```
 
-### LNbits
+```bash
+# Pay: bolt11 amount < 1001 (msat), label must start with "LNbits", 1 req/min
+lightning-cli createrune \
+  restrictions='[["method=pay"], ["pinvbolt11_amount<1001"], ["pnamelabel^LNbits"], ["rate=1"]]' \
+| jq -r .rune
+```
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **LNbitsWallet**
-- `LNBITS_ENDPOINT`: e.g. https://lnbits.com
-- `LNBITS_KEY`: lnbitsAdminKey
+```bash
+# Renepay: invstring amount < 1001 (msat), label must start with "LNbits", 1 req/min
+lightning-cli createrune \
+  restrictions='[["method=renepay"], ["pinvinvstring_amount<1001"], ["pnamelabel^LNbits"], ["rate=1"]]' \
+| jq -r .rune
+```
 
-### LNPay
+Set the resulting values into:
 
-For the invoice listener to work you have a publicly accessible URL in your LNbits and must set up [LNPay webhooks](https://dashboard.lnpay.co/webhook/) pointing to `<your LNbits host>/wallet/webhook` with the "Wallet Receive" event and no secret. For example, `https://mylnbits/wallet/webhook` will be the Endpoint Url that gets notified about the payment.
+- `CLNREST_READONLY_RUNE`
+- `CLNREST_INVOICE_RUNE`
+- `CLNREST_PAY_RUNE`
+- `CLNREST_RENEPAY_RUNE`
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **LNPayWallet**
-- `LNPAY_API_ENDPOINT`: https://api.lnpay.co/v1/
-- `LNPAY_API_KEY`: sak_apiKey
-- `LNPAY_WALLET_KEY`: waka_apiKey
+## CoreLightning
 
-### OpenNode
+**Required env vars**
 
-For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook setting is necessary.
+- `LNBITS_BACKEND_WALLET_CLASS`: `CoreLightningWallet`
+- `CORELIGHTNING_RPC`: `/file/path/lightning-rpc`
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **OpenNodeWallet**
-- `OPENNODE_API_ENDPOINT`: https://api.opennode.com/
-- `OPENNODE_KEY`: opennodeAdminApiKey
+## CoreLightning REST
 
-### Blink
+Old REST interface using [RTL c-lightning-REST](https://github.com/Ride-The-Lightning/c-lightning-REST)
 
-For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook setting is necessary. You can generate a Blink API key after logging in or creating a new Blink account at: https://dashboard.blink.sv. For more info visit: https://dev.blink.sv/api/auth#create-an-api-key```
+**Required env vars**
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **BlinkWallet**
-- `BLINK_API_ENDPOINT`: https://api.blink.sv/graphql
-- `BLINK_WS_ENDPOINT`: wss://ws.blink.sv/graphql
-- `BLINK_TOKEN`: BlinkToken
+- `LNBITS_BACKEND_WALLET_CLASS`: `CoreLightningRestWallet`
+- `CORELIGHTNING_REST_URL`: `http://127.0.0.1:8185/`
+- `CORELIGHTNING_REST_MACAROON`: `/file/path/admin.macaroon` or Base64/Hex
+- `CORELIGHTNING_REST_CERT`: `/home/lightning/clnrest/tls.cert`
 
-### Alby
+## Spark (Core Lightning)
 
-For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook setting is necessary. You can generate an alby access token here: https://getalby.com/developer/access_tokens/new
+**Required env vars**
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **AlbyWallet**
-- `ALBY_API_ENDPOINT`: https://api.getalby.com/
-- `ALBY_ACCESS_TOKEN`: AlbyAccessToken
+- `LNBITS_BACKEND_WALLET_CLASS`: `SparkWallet`
+- `SPARK_URL`: `http://10.147.17.230:9737/rpc`
+- `SPARK_TOKEN`: `secret_access_key`
 
-### Boltz
+## Spark L2
 
-This funding source connects to a running [boltz-client](https://docs.boltz.exchange/v/boltz-client) and handles all lightning payments through submarine swaps on the liquid network.
-You can configure the daemon to run in standalone mode by `standalone = True` in the config file or using the cli flag (`boltzd --standalone`).
-Once running, you can create a liquid wallet using `boltzcli wallet create lnbits lbtc`.
+Self-custodial funding source using the [Spark L2](https://docs.spark.money/start/overview) network. Requires a Node.js [sidecar](https://github.com/lnbits/spark_sidecar) that bridges lnbits talking to Spark. Works in addition with any Spark-compatible seed (Wallet of Satoshi, BuhoGO, BlitzWallet).
+If the sidecar is started with a `mnemonic` then that mnemonic will be used. Otherwhise if a mnemonic is set for the `Spark L2` LNbits funding source then that mnemonic will be used.
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **BoltzWallet**
-- `BOLTZ_CLIENT_ENDPOINT`: 127.0.0.1:9002
-- `BOLTZ_CLIENT_MACAROON`: /home/bob/.boltz/macaroons/admin.macaroon or Base64/Hex
-- `BOLTZ_CLIENT_CERT`: /home/bob/.boltz/tls.cert or Base64/Hex
-- `BOLTZ_CLIENT_WALLET`: lnbits
+### Optional tuning
 
-### ZBD
+- `SPARK_L2_PAY_WAIT_MS`: `4000` _(payment timeout in ms)_
+- `SPARK_L2_PAY_POLL_MS`: `500` _(polling interval in ms)_
+- `SPARK_L2_STREAM_KEEPALIVE_MS`: `15000` _(SSE keepalive in ms)_
 
-For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook setting is necessary. You can generate an ZBD API Key here: https://zbd.dev/docs/dashboard/projects/api
+### Example: run the sidecar
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **ZBDWallet**
-- `ZBD_API_ENDPOINT`: https://api.zebedee.io/v0/
-- `ZBD_API_KEY`: ZBDApiKey
+```bash
+git clone https://github.com/lnbits/spark_sidecar.git
+cd spark_sidecar
+npm install
 
-### Phoenixd
+SPARK_MNEMONIC="bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom" \
+SPARK_NETWORK=MAINNET \
+SPARK_SIDECAR_PORT=8765 \
+SPARK_PAY_WAIT_MS=20000 \
+node server.mjs
+```
 
-For the invoice to work you must have a publicly accessible URL in your LNbits. You can get a phoenixd API key from the install
-~/.phoenix/phoenix.conf, also see the documentation for phoenixd.
+For testing, you can generate a 12-word mnemonic at https://iancoleman.io/bip39/. Store it securely — it controls your funds. Then select Spark (L2) as the funding source in LNbits.
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **PhoenixdWallet**
-- `PHOENIXD_API_ENDPOINT`: http://localhost:9740/
-- `PHOENIXD_API_PASSWORD`: PhoenixdApiPassword
+## LND (REST)
 
-### Breez SDK
+**Required env vars**
 
-A Greenlight invite code or Greenlight partner certificate/key can be used to register a new node with Greenlight. If the Greenlight node already exists, neither are required.
+- `LNBITS_BACKEND_WALLET_CLASS`: `LndRestWallet`
+- `LND_REST_ENDPOINT`: `http://10.147.17.230:8080/`
+- `LND_REST_CERT`: `/file/path/tls.cert`
+- `LND_REST_MACAROON`: `/file/path/admin.macaroon` or Base64/Hex
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **BreezSdkWallet**
-- `BREEZ_API_KEY`: ...
-- `BREEZ_GREENLIGHT_SEED`: ...
-- `BREEZ_GREENLIGHT_INVITE_CODE`: ...
-- `BREEZ_GREENLIGHT_DEVICE_KEY`: /path/to/breezsdk/device.pem or Base64/Hex
-- `BREEZ_GREENLIGHT_DEVICE_CERT`: /path/to/breezsdk/device.crt or Base64/Hex
+or:
 
-### Cliche Wallet
+- `LND_REST_MACAROON_ENCRYPTED`: `eNcRyPtEdMaCaRoOn`
 
-- `CLICHE_ENDPOINT`: ws://127.0.0.1:12000
+## LND (gRPC)
 
-### Nostr Wallet Connect (NWC)
+**Required env vars**
 
-To use NWC as funding source in LNbits you'll need a pairing URL (also known as pairing secret) from a NWC service provider. You can find a list of providers [here](https://github.com/getAlby/awesome-nwc?tab=readme-ov-file#nwc-wallets).
+- `LNBITS_BACKEND_WALLET_CLASS`: `LndWallet`
+- `LND_GRPC_ENDPOINT`: `ip_address`
+- `LND_GRPC_PORT`: `port`
+- `LND_GRPC_CERT`: `/file/path/tls.cert`
+- `LND_GRPC_MACAROON`: `/file/path/admin.macaroon` or Base64/Hex
 
-You can configure Nostr Wallet Connect in the admin ui or using the following environment variables:
+You can also use an AES-encrypted macaroon instead:
 
-- `LNBITS_BACKEND_WALLET_CLASS`: **NWCWallet**
-- `NWC_PAIRING_URL`: **nostr+walletconnect://...your...pairing...secret...**
+- `LND_GRPC_MACAROON_ENCRYPTED`: `eNcRyPtEdMaCaRoOn`
+
+To encrypt your macaroon:
+
+```bash
+uv run lnbits-cli encrypt macaroon
+```
+
+## LNbits
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `LNbitsWallet`
+- `LNBITS_ENDPOINT`: for example `https://lnbits.com`
+- `LNBITS_KEY`: `lnbitsAdminKey`
+
+## LNPay
+
+For the invoice listener to work you must have a publicly accessible URL in your LNbits and set up [LNPay webhooks](https://dashboard.lnpay.co/webhook/) pointing to `<your LNbits host>/wallet/webhook` with the event **Wallet Receive** and no secret. Example: [https://mylnbits/wallet/webhook](`https://mylnbits/wallet/webhook).
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `LNPayWallet`
+- `LNPAY_API_ENDPOINT`: `https://api.lnpay.co/v1/`
+- `LNPAY_API_KEY`: `sak_apiKey`
+- `LNPAY_WALLET_KEY`: `waka_apiKey`
+
+## OpenNode
+
+For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook configuration required.
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `OpenNodeWallet`
+- `OPENNODE_API_ENDPOINT`: `https://api.opennode.com/`
+- `OPENNODE_KEY`: `opennodeAdminApiKey`
+
+## Blink
+
+For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook configuration required.
+
+You can generate a Blink API key at [https://dashboard.blink.sv](https://dashboard.blink.sv). More info: [https://dev.blink.sv/api/auth#create-an-api-key](https://dev.blink.sv/api/auth#create-an-api-key)
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `BlinkWallet`
+- `BLINK_API_ENDPOINT`: `https://api.blink.sv/graphql`
+- `BLINK_WS_ENDPOINT`: `wss://ws.blink.sv/graphql`
+- `BLINK_TOKEN`: `BlinkToken`
+
+## Alby
+
+For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook configuration required.
+
+Generate an Alby access token here: [https://getalby.com/developer/access_tokens/new](https://getalby.com/developer/access_tokens/new)
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `AlbyWallet`
+- `ALBY_API_ENDPOINT`: `https://api.getalby.com/`
+- `ALBY_ACCESS_TOKEN`: `AlbyAccessToken`
+
+## Boltz
+
+This connects to a running [boltz-client](https://docs.boltz.exchange/v/boltz-client) and handles Lightning payments through submarine swaps on the Liquid network.
+
+You can run the daemon in standalone mode via `standalone = True` in the config or `boltzd --standalone`. Create a Liquid wallet with:
+
+```bash
+boltzcli wallet create lnbits lbtc
+```
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `BoltzWallet`
+- `BOLTZ_CLIENT_ENDPOINT`: `127.0.0.1:9002`
+- `BOLTZ_CLIENT_MACAROON`: `/home/bob/.boltz/macaroons/admin.macaroon` or Base64/Hex
+- `BOLTZ_CLIENT_CERT`: `/home/bob/.boltz/tls.cert` or Base64/Hex
+- `BOLTZ_CLIENT_WALLET`: `lnbits`
+
+## ZBD
+
+For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook configuration required.
+
+Generate a ZBD API key here: [https://zbd.dev/docs/dashboard/projects/api](https://zbd.dev/docs/dashboard/projects/api)
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `ZBDWallet`
+- `ZBD_API_ENDPOINT`: `https://api.zebedee.io/v0/`
+- `ZBD_API_KEY`: `ZBDApiKey`
+
+## Phoenixd
+
+For the invoice to work you must have a publicly accessible URL in your LNbits.
+
+You can get a phoenixd API key from `~/.phoenix/phoenix.conf`. See the phoenixd documentation for details.
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `PhoenixdWallet`
+- `PHOENIXD_API_ENDPOINT`: `http://localhost:9740/`
+- `PHOENIXD_API_PASSWORD`: `PhoenixdApiPassword`
+
+## Eclair (ACINQ)
+
+<a id="eclair-acinq"></a>
+
+Connect to an existing Eclair node so your backend handles invoices and payments.
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `EclairWallet`
+- `ECLAIR_URL`: `http://127.0.0.1:8283`
+- `ECLAIR_PASSWORD`: `eclairpw`
+
+## Fake Wallet
+
+<a id="fake-wallet"></a>
+
+A testing-only backend that mints accounting units inside LNbits accounting (no real sats).
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `FakeWallet`
+- `FAKE_SECRET`: `ToTheMoon1`
+- `FAKE_UNIT`: `sats`
+
+## LN.tips
+
+<a id="lntips"></a>
+
+As the initinal LN.tips bot is no longer active the code still exists and is widly used. Connect one of custodial services as your backend to create and pay Lightning invoices through their API or selfhost this service and run it as funding source.
+Resources: https://github.com/massmux/SatsMobiBot
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `LNTipsWallet`
+- `LNTIPS_API_ENDPOINT`: `https://ln.tips`
+- `LNTIPS_API_KEY`: `LNTIPS_ADMIN_KEY`
+
+## Breez SDK
+
+A Greenlight invite code or Greenlight partner certificate/key can register a new node with Greenlight. If the Greenlight node already exists, neither is required.
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `BreezSdkWallet`
+- `BREEZ_API_KEY`: `...`
+- `BREEZ_GREENLIGHT_SEED`: `...`
+- `BREEZ_GREENLIGHT_INVITE_CODE`: `...`
+- `BREEZ_GREENLIGHT_DEVICE_KEY`: `/path/to/breezsdk/device.pem` or Base64/Hex
+- `BREEZ_GREENLIGHT_DEVICE_CERT`: `/path/to/breezsdk/device.crt` or Base64/Hex
+
+## Breez Liquid SDK
+
+This uses the [Breez SDK - Liquid](https://sdk-doc-liquid.breez.technology/) to manage Lightning payments via submarine swaps on the Liquid network. Provide a mnemonic seed phrase (for example, generate one with a Liquid wallet like [Blockstream Green](https://blockstream.com/green/)) and set it in the environment or admin UI.
+
+**Required env vars**
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `BreezLiquidSdkWallet`
+- `BREEZ_LIQUID_SEED`: `...`
+
+Fees apply for each submarine swap. You may need to increase the reserve fee under **Settings → Funding** or via:
+
+- `LNBITS_RESERVE_FEE_MIN`: `...`
+- `LNBITS_RESERVE_FEE_PERCENT`: `...`
+
+## Cliche Wallet
+
+**Required env vars**
+
+- `CLICHE_ENDPOINT`: `ws://127.0.0.1:12000`
+
+## Nostr Wallet Connect (NWC)
+
+To use NWC as a funding source you need a pairing URL (pairing secret) from an NWC provider. See providers here:
+[https://github.com/getAlby/awesome-nwc?tab=readme-ov-file#nwc-wallets](https://github.com/getAlby/awesome-nwc?tab=readme-ov-file#nwc-wallets)
+
+Configure in the admin UI or via env vars:
+
+- `LNBITS_BACKEND_WALLET_CLASS`: `NWCWallet`
+- `NWC_PAIRING_URL`: `nostr+walletconnect://...your...pairing...secret...`
+
+<a id="strike"></a>
+
+## Strike (alpha)
+
+Custodial provider integrated via **Strike OAuth Connect** (OAuth 2.0 / OIDC). Authenticate a Strike user in your app, then call Strike APIs on the user’s behalf once scopes are granted. Requires a Strike business account, registered OAuth client, minimal scopes, and login/logout redirect URLs.
+
+Get more info here [https://docs.strike.me/strike-oauth-connect/](https://docs.strike.me/strike-oauth-connect/)
+
+**Integration endpoints**
+
+- `STRIKE_API_ENDPOINT`: `https://api.strike.me/v1`
+- `STRIKE_API_KEY`: `YOUR_STRIKE_API_KEY`
+
+---
+
+## Additional Guides
+
+- **[Admin UI](./admin_ui.md)** — Manage server settings via a clean UI (avoid editing `.env` by hand).
+- **[User Roles](./user_roles.md)** — Quick Overview of existing Roles in LNBits.
+- **[Funding sources](./funding-sources-table.md)** — What’s available and how to enable/configure each.
+
+## Powered by LNbits
+
+LNbits empowers everyone with modular, open-source tools for building Bitcoin-based systems — fast, free, and extendable.
+
+If you like this project, [send some tip love](https://demo.lnbits.com/tipjar/DwaUiE4kBX6mUW6pj3X5Kg) or visit our [Shop](https://shop.lnbits.de)
+
+[![LNbits Shop](https://demo.lnbits.com/static/images/bitcoin-shop-banner.png)](https://shop.lnbits.com/)
+[![Visit LNbits Shop](https://img.shields.io/badge/Visit-LNbits%20Shop-7C3AED?logo=shopping-cart&logoColor=white&labelColor=5B21B6)](https://shop.lnbits.com/)
+[![Try myLNbits SaaS](https://img.shields.io/badge/Try-myLNbits%20SaaS-2563EB?logo=lightning&logoColor=white&labelColor=1E40AF)](https://my.lnbits.com/login)
+[![Read LNbits News](https://img.shields.io/badge/Read-LNbits%20News-F97316?logo=rss&logoColor=white&labelColor=C2410C)](https://news.lnbits.com/)
+[![Explore LNbits Extensions](https://img.shields.io/badge/Explore-LNbits%20Extensions-10B981?logo=puzzle-piece&logoColor=white&labelColor=065F46)](https://extensions.lnbits.com/)

flake.lock

@@ -1,15 +1,39 @@
 {
   "nodes": {
+    "build-system-pkgs": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "pyproject-nix": [
+          "pyproject-nix"
+        ],
+        "uv2nix": "uv2nix"
+      },
+      "locked": {
+        "lastModified": 1755484659,
+        "narHash": "sha256-2FfbqsaHVQd12XFFUAinIMAuGO3853LONmva1gT3vKw=",
+        "owner": "pyproject-nix",
+        "repo": "build-system-pkgs",
+        "rev": "9778e87c2361810ff15e287ca5895c9da4a0e900",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "build-system-pkgs",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "inputs": {
         "systems": "systems"
       },
       "locked": {
-        "lastModified": 1710146030,
-        "narHash": "sha256-SZ5L6eA7HJ/nmkzGG7/ISclqe6oZdOZTNoesiInkXPQ=",
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
         "owner": "numtide",
         "repo": "flake-utils",
-        "rev": "b1d9ab70662946ef0850d488da1c9019f3a9752a",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
         "type": "github"
       },
       "original": {
@@ -18,71 +42,49 @@
         "type": "github"
       }
     },
-    "nix-github-actions": {
-      "inputs": {
-        "nixpkgs": [
-          "poetry2nix",
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1703863825,
-        "narHash": "sha256-rXwqjtwiGKJheXB43ybM8NwWB8rO2dSRrEqes0S7F5Y=",
-        "owner": "nix-community",
-        "repo": "nix-github-actions",
-        "rev": "5163432afc817cf8bd1f031418d1869e4c9d5547",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-community",
-        "repo": "nix-github-actions",
-        "type": "github"
-      }
-    },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1735563628,
-        "narHash": "sha256-OnSAY7XDSx7CtDoqNh8jwVwh4xNL/2HaJxGjryLWzX8=",
-        "owner": "nixos",
+        "lastModified": 1751274312,
+        "narHash": "sha256-/bVBlRpECLVzjV19t5KMdMFWSwKLtb5RyXdjz3LJT+g=",
+        "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "b134951a4c9f3c995fd7be05f3243f8ecd65d798",
+        "rev": "50ab793786d9de88ee30ec4e4c24fb4236fc2674",
         "type": "github"
       },
       "original": {
-        "owner": "nixos",
-        "ref": "nixos-24.05",
+        "owner": "NixOS",
+        "ref": "nixos-24.11",
         "repo": "nixpkgs",
         "type": "github"
       }
     },
-    "poetry2nix": {
+    "pyproject-nix": {
       "inputs": {
-        "flake-utils": "flake-utils",
-        "nix-github-actions": "nix-github-actions",
         "nixpkgs": [
           "nixpkgs"
-        ],
-        "systems": "systems_2",
-        "treefmt-nix": "treefmt-nix"
+        ]
       },
       "locked": {
-        "lastModified": 1724134185,
-        "narHash": "sha256-nDqpGjz7cq3ThdC98BPe1ANCNlsJds/LLZ3/MdIXjA0=",
-        "owner": "nix-community",
-        "repo": "poetry2nix",
-        "rev": "5ee730a8752264e463c0eaf06cc060fd07f6dae9",
+        "lastModified": 1754923840,
+        "narHash": "sha256-QSKpYg+Ts9HYF155ltlj40iBex39c05cpOF8gjoE2EM=",
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "rev": "023cd4be230eacae52635be09eef100c37ef78da",
         "type": "github"
       },
       "original": {
-        "owner": "nix-community",
-        "repo": "poetry2nix",
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
         "type": "github"
       }
     },
     "root": {
       "inputs": {
+        "build-system-pkgs": "build-system-pkgs",
+        "flake-utils": "flake-utils",
         "nixpkgs": "nixpkgs",
-        "poetry2nix": "poetry2nix"
+        "pyproject-nix": "pyproject-nix",
+        "uv2nix": "uv2nix_2"
       }
     },
     "systems": {
@@ -100,38 +102,51 @@
         "type": "github"
       }
     },
-    "systems_2": {
-      "locked": {
-        "lastModified": 1681028828,
-        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
-        "owner": "nix-systems",
-        "repo": "default",
-        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
-        "type": "github"
-      },
-      "original": {
-        "id": "systems",
-        "type": "indirect"
-      }
-    },
-    "treefmt-nix": {
+    "uv2nix": {
       "inputs": {
         "nixpkgs": [
-          "poetry2nix",
+          "build-system-pkgs",
           "nixpkgs"
+        ],
+        "pyproject-nix": [
+          "build-system-pkgs",
+          "pyproject-nix"
         ]
       },
       "locked": {
-        "lastModified": 1719749022,
-        "narHash": "sha256-ddPKHcqaKCIFSFc/cvxS14goUhCOAwsM1PbMr0ZtHMg=",
-        "owner": "numtide",
-        "repo": "treefmt-nix",
-        "rev": "8df5ff62195d4e67e2264df0b7f5e8c9995fd0bd",
+        "lastModified": 1755210905,
+        "narHash": "sha256-WnoFEk79ysjL85TNP7bvImzhxvQw9B6uNtnLd4oJntw=",
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "rev": "87bcba013ef304bbfd67c8e8a257aee634ed5a4c",
         "type": "github"
       },
       "original": {
-        "owner": "numtide",
-        "repo": "treefmt-nix",
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "type": "github"
+      }
+    },
+    "uv2nix_2": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "pyproject-nix": [
+          "pyproject-nix"
+        ]
+      },
+      "locked": {
+        "lastModified": 1755485731,
+        "narHash": "sha256-k8kxwVs8Oze6q/jAaRa3RvZbb50I/K0b5uptlsh0HXI=",
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "rev": "bebbd80bf56110fcd20b425589814af28f1939eb",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
         "type": "github"
       }
     }

flake.nix

@@ -1,70 +1,151 @@
 {
-  description = "LNbits, free and open-source Lightning wallet and accounts system";
+  description = "LNbits, free and open-source Lightning wallet and accounts system (uv2nix)";
 
   inputs = {
-    nixpkgs.url = "github:nixos/nixpkgs/nixos-24.05";
-    poetry2nix = {
-      url = "github:nix-community/poetry2nix";
-      inputs.nixpkgs.follows = "nixpkgs";
-    };
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
+    flake-utils.url = "github:numtide/flake-utils";
+
+    pyproject-nix.url = "github:pyproject-nix/pyproject.nix";
+    uv2nix.url = "github:pyproject-nix/uv2nix";
+    build-system-pkgs.url = "github:pyproject-nix/build-system-pkgs";
+
+    pyproject-nix.inputs.nixpkgs.follows = "nixpkgs";
+    uv2nix.inputs.nixpkgs.follows = "nixpkgs";
+    build-system-pkgs.inputs.nixpkgs.follows = "nixpkgs";
+    uv2nix.inputs.pyproject-nix.follows = "pyproject-nix";
+    build-system-pkgs.inputs.pyproject-nix.follows = "pyproject-nix";
   };
-  outputs = { self, nixpkgs, poetry2nix }@inputs:
-    let
-      supportedSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
-      forSystems = systems: f:
-        nixpkgs.lib.genAttrs systems
-        (system: f system (import nixpkgs { inherit system; overlays = [ poetry2nix.overlays.default self.overlays.default ]; }));
-      forAllSystems = forSystems supportedSystems;
-      projectName = "lnbits";
-    in
-    {
-      overlays = {
-        default = final: prev: {
-          ${projectName} = self.packages.${prev.stdenv.hostPlatform.system}.${projectName};
-        };
-      };
-      packages = forAllSystems (system: pkgs: {
-        default = self.packages.${system}.${projectName};
-        ${projectName} = pkgs.poetry2nix.mkPoetryApplication {
-          projectDir = ./.;
-          meta.rev = self.dirtyRev or self.rev;
-          meta.mainProgram = projectName;
-          overrides = pkgs.poetry2nix.overrides.withDefaults (final: prev: {
-            coincurve = prev.coincurve.override { preferWheel = true; };
-            protobuf = prev.protobuf.override { preferWheel = true; };
-            ruff = prev.ruff.override { preferWheel = true; };
-            wallycore = prev.wallycore.override { preferWheel = true; };
-            tlv8 = prev.tlv8.overrideAttrs (old: {
-              nativeBuildInputs = (old.nativeBuildInputs or [ ]) ++ [
-                prev.setuptools
-              ];
+
+  outputs = { self, nixpkgs, flake-utils, uv2nix, pyproject-nix, build-system-pkgs, ... }:
+    flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ]
+      (system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+          lib = pkgs.lib;
+
+          python = pkgs.python312;
+
+          # Read uv.lock / pyproject via uv2nix
+          workspace = uv2nix.lib.workspace.loadWorkspace { workspaceRoot = ./.; };
+
+          # Prefer wheels when available
+          uvLockedOverlay = workspace.mkPyprojectOverlay { sourcePreference = "wheel"; };
+
+          # Helper for extending lists safely (works if a is null)
+          plus = a: b: lib.unique (((if a == null then [] else a)) ++ b);
+
+          # Extra build inputs for troublesome sdists
+          myOverrides = (final: prev: {
+            # embit needs setuptools at build time
+            embit = prev.embit.overrideAttrs (old: {
+              nativeBuildInputs = plus (old.nativeBuildInputs or []) [ prev.setuptools ];
             });
-            pynostr = prev.pynostr.overrideAttrs (old: {
-              nativeBuildInputs = (old.nativeBuildInputs or [ ]) ++ [
-                prev.setuptools-scm
+
+            # http-ece (pywebpush dep) needs setuptools
+            "http-ece" = prev."http-ece".overrideAttrs (old: {
+              nativeBuildInputs = plus (old.nativeBuildInputs or []) [ prev.setuptools ];
+            });
+
+            # pyqrcode needs setuptools
+            pyqrcode = prev.pyqrcode.overrideAttrs (old: {
+              nativeBuildInputs = plus (old.nativeBuildInputs or []) [ prev.setuptools ];
+            });
+
+            # tlv8 needs setuptools
+            tlv8 = prev.tlv8.overrideAttrs (old: {
+              nativeBuildInputs = plus (old.nativeBuildInputs or []) [ prev.setuptools ];
+            });
+
+            # secp256k1 Python binding:
+            #  - setuptools, pkg-config
+            #  - cffi + pycparser
+            #  - system libsecp256k1 for headers/libs
+            secp256k1 = prev.secp256k1.overrideAttrs (old: {
+              nativeBuildInputs = plus (old.nativeBuildInputs or []) [
+                prev.setuptools
+                pkgs.pkg-config
+                prev.cffi
+                prev.pycparser
               ];
+              buildInputs = plus (old.buildInputs or []) [ pkgs.secp256k1 ];
+              propagatedBuildInputs = plus (old.propagatedBuildInputs or []) [ prev.cffi prev.pycparser ];
+              env = (old.env or { }) // { PKG_CONFIG = "${pkgs.pkg-config}/bin/pkg-config"; };
+            });
+
+            # pynostr uses setuptools-scm for versioning
+            pynostr = prev.pynostr.overrideAttrs (old: {
+              nativeBuildInputs = plus (old.nativeBuildInputs or []) [ prev.setuptools-scm ];
             });
           });
-        };
-      });
-      nixosModules = {
-        default = { pkgs, lib, config, ... }: {
-          imports = [ "${./nix/modules/${projectName}-service.nix}" ];
-          nixpkgs.overlays = [ self.overlays.default ];
-        };
-      };
-      checks = forAllSystems (system: pkgs:
-        let
-          vmTests = import ./nix/tests {
-            makeTest = (import (nixpkgs + "/nixos/lib/testing-python.nix") { inherit system; }).makeTest;
-            inherit inputs pkgs;
+
+          # Compose Python package set honoring uv.lock
+          pythonSet =
+            (pkgs.callPackage pyproject-nix.build.packages { inherit python; })
+              .overrideScope (lib.composeManyExtensions [
+                build-system-pkgs.overlays.default
+                uvLockedOverlay
+                myOverrides
+              ]);
+
+          projectName = "lnbits";
+
+          # Build a venv from the locked spec (this installs the resolved wheels)
+          runtimeVenv = pythonSet.mkVirtualEnv "${projectName}-env" workspace.deps.default;
+
+          # Wrapper so `nix run` behaves like `uv run` (use local source tree for templates/static/extensions)
+          lnbitsApp = pkgs.writeShellApplication {
+            name = "lnbits";
+            text = ''
+              export SSL_CERT_FILE=${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt
+              export REQUESTS_CA_BUNDLE=$SSL_CERT_FILE
+              export PYTHONPATH="$PWD:${PYTHONPATH:-}"
+              exec ${runtimeVenv}/bin/lnbits "$@"
+            '';
+          };
+
+          lnbitsCliApp = pkgs.writeShellApplication {
+            name = "lnbits-cli";
+            text = ''
+              export PYTHONPATH="$PWD:${PYTHONPATH:-}"
+              exec ${runtimeVenv}/bin/lnbits-cli "$@"
+            '';
           };
         in
-        pkgs.lib.optionalAttrs pkgs.stdenv.isLinux vmTests # vmTests can only be ran on Linux, so append them only if on Linux.
-        //
         {
-          # Other checks here...
-        }
-      );
-    };
+          # nix build → produces the venv in ./result
+          packages.default = runtimeVenv;
+          packages.${projectName} = runtimeVenv;
+
+          # nix run . → launches via wrapper that imports from source tree
+          apps.default = { type = "app"; program = "${lnbitsApp}/bin/lnbits"; };
+          apps.${projectName} = self.apps.${system}.default;
+          apps."${projectName}-cli" = { type = "app"; program = "${lnbitsCliApp}/bin/lnbits-cli"; };
+
+          # dev shell with locked deps + tools
+          devShells.default = pkgs.mkShell {
+            packages = [
+              runtimeVenv
+              pkgs.uv
+              pkgs.ruff
+              pkgs.black
+              pkgs.mypy
+              pkgs.pre-commit
+              pkgs.openapi-generator-cli
+            ];
+          };
+
+          overlays.default = final: prev: {
+            ${projectName} = self.packages.${final.stdenv.hostPlatform.system}.${projectName};
+            replaceVars = prev.replaceVars or (path: vars: prev.substituteAll ({ src = path; } // vars));
+          };
+
+          # System-specific nixos modules to avoid circular dependency
+          nixosModules.default = { pkgs, lib, config, ... }: {
+            imports = [ "${./nix/modules/lnbits-service.nix}" ];
+            nixpkgs.overlays = [ self.overlays.${system}.default ];
+          };
+
+          checks =
+            import ./nix/tests { inherit pkgs; flake = self; };
+        });
 }

lnbits.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# --- Config you might tweak ---
+REPO_URL="https://github.com/lnbits/lnbits.git"
+BRANCH="main"
+APP_DIR="${PWD}/lnbits"
+HOST="${HOST:-0.0.0.0}"
+PORT="${PORT:-5000}"
+ADMIN_UI="${LNBITS_ADMIN_UI:-true}"
+# -------------------------------
+
+export DEBIAN_FRONTEND=noninteractive
+
+# Ensure basic tooling
+if ! command -v curl >/dev/null 2>&1 || ! command -v git >/dev/null 2>&1; then
+  sudo apt-get update -y
+  sudo apt-get install -y curl git
+fi
+
+# System build deps and secp headers
+if command -v apt-get >/dev/null 2>&1; then
+  sudo apt-get update -y
+  sudo apt-get install -y \
+    pkg-config \
+    build-essential \
+    libsecp256k1-dev \
+    automake \
+    autoconf \
+    libtool \
+    m4
+fi
+
+# Install uv (if missing)
+if ! command -v uv >/dev/null 2>&1; then
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  export PATH="$HOME/.local/bin:$PATH"
+fi
+# Ensure PATH for current session
+if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
+  export PATH="$HOME/.local/bin:$PATH"
+fi
+
+# Clone or reuse repo
+if [[ ! -d "$APP_DIR/.git" ]]; then
+  git clone "$REPO_URL" "$APP_DIR"
+fi
+
+cd "$APP_DIR"
+git fetch --all --prune
+git checkout "$BRANCH"
+git pull --ff-only || true
+
+# First-run setup
+mkdir -p data
+[[ -f .env ]] || cp .env.example .env || true
+
+# Prefer system libsecp256k1 (avoid autotools path)
+export SECP_BUNDLED=0
+
+# Sync dependencies with Python 3.12
+uv sync --python 3.12 --all-extras --no-dev
+
+# Environment
+export LNBITS_ADMIN_UI="$ADMIN_UI"
+export HOST="$HOST"
+export PORT="$PORT"
+
+# Open firewall (optional)
+if command -v ufw >/dev/null 2>&1; then
+  sudo ufw allow "$PORT"/tcp || true
+fi
+
+# Run LNbits with Python 3.12 via uv
+exec uv run --python 3.12 lnbits

lnbits/__init__.py

@@ -1,5 +1,6 @@
 from .core.services import create_invoice, pay_invoice
 from .decorators import (
+    check_account_exists,
     check_admin,
     check_super_user,
     check_user_exists,
@@ -9,16 +10,14 @@ from .decorators import (
 from .exceptions import InvoiceError, PaymentError
 
 __all__ = [
-    # decorators
-    "require_admin_key",
-    "require_invoice_key",
+    "InvoiceError",
+    "PaymentError",
+    "check_account_exists",
     "check_admin",
     "check_super_user",
     "check_user_exists",
-    # services
-    "pay_invoice",
     "create_invoice",
-    # exceptions
-    "PaymentError",
-    "InvoiceError",
+    "pay_invoice",
+    "require_admin_key",
+    "require_invoice_key",
 ]

lnbits/app.py

@@ -4,9 +4,10 @@ import importlib
 import os
 import shutil
 import sys
+import time
+from collections.abc import Callable
 from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import Callable, Optional
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -23,10 +24,17 @@ from lnbits.core.crud import (
     update_installed_extension_state,
 )
 from lnbits.core.crud.extensions import create_installed_extension
+from lnbits.core.extensions.events import dispatch_wasm_invoice_paid
+from lnbits.core.extensions.loader import (
+    is_wasm_extension_dir,
+    is_wasm_extension_id,
+)
+from lnbits.core.extensions.routes import register_wasm_extension
 from lnbits.core.helpers import migrate_extension_database
 from lnbits.core.models.notifications import NotificationType
 from lnbits.core.services.extensions import deactivate_extension, get_valid_extensions
-from lnbits.core.services.notifications import enqueue_notification
+from lnbits.core.services.notifications import enqueue_admin_notification
+from lnbits.core.services.payments import check_pending_payments
 from lnbits.core.tasks import (
     audit_queue,
     collect_exchange_rates_data,
@@ -38,6 +46,7 @@ from lnbits.core.tasks import (
 )
 from lnbits.exceptions import register_exception_handlers
 from lnbits.helpers import version_parse
+from lnbits.llms_txt import create_llms_txt_route
 from lnbits.settings import settings
 from lnbits.tasks import (
     cancel_all_tasks,
@@ -63,19 +72,16 @@ from .middleware import (
     InstalledExtensionMiddleware,
     add_first_install_middleware,
     add_ip_block_middleware,
+    add_profiler_middleware,
     add_ratelimit_middleware,
 )
-from .requestvars import g
-from .tasks import (
-    check_pending_payments,
-    internal_invoice_listener,
-    invoice_listener,
-)
+from .tasks import internal_invoice_listener, invoice_listener, run_interval
 
 
 async def startup(app: FastAPI):
+    logger.info(f"Starting LNbits Version: {settings.version}")
+    start = time.perf_counter()
     settings.lnbits_running = True
-
     # wait till migration is done
     await migrate_databases()
 
@@ -103,10 +109,13 @@ async def startup(app: FastAPI):
     # register core routes
     init_core_routers(app)
 
+    # register llms.txt endpoint for AI agents
+    create_llms_txt_route(app)
+
     # initialize tasks
     register_async_tasks()
 
-    enqueue_notification(
+    enqueue_admin_notification(
         NotificationType.server_start_stop,
         {
             "message": "LNbits server started.",
@@ -114,10 +123,13 @@ async def startup(app: FastAPI):
         },
     )
 
+    end = time.perf_counter()
+    logger.success(f"LNbits started in {end - start:.2f} seconds.")
+
 
 async def shutdown():
     logger.warning("LNbits shutting down...")
-    enqueue_notification(
+    enqueue_admin_notification(
         NotificationType.server_start_stop,
         {
             "message": "LNbits server shutting down...",
@@ -160,14 +172,17 @@ def create_app() -> FastAPI:
 
     # Allow registering new extensions routes without direct access to the `app` object
     core_app_extra.register_new_ext_routes = register_new_ext_routes(app)
+    core_app_extra.register_new_wasm_ext_routes = register_new_wasm_ext_routes(app)
     core_app_extra.register_new_ratelimiter = register_new_ratelimiter(app)
 
     # register static files
-    static_path = Path("lnbits", "static")
-    static = StaticFiles(directory=static_path)
-    app.mount("/static", static, name="static")
-
-    g().base_url = f"http://{settings.host}:{settings.port}"
+    app.mount("/static", StaticFiles(directory=Path("lnbits", "static")), name="static")
+    Path(settings.lnbits_data_folder, "images").mkdir(parents=True, exist_ok=True)
+    app.mount(
+        "/library",
+        StaticFiles(directory=Path(settings.lnbits_data_folder, "images")),
+        name="library",
+    )
 
     app.add_middleware(
         CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"]
@@ -193,6 +208,9 @@ def create_app() -> FastAPI:
 
     register_exception_handlers(app)
 
+    if settings.profiler:
+        add_profiler_middleware(app)
+
     return app
 
 
@@ -276,8 +294,8 @@ async def check_installed_extensions(app: FastAPI):
         logger.info(f"{ext.id} ({ext.installed_version})")
 
 
-async def build_all_installed_extensions_list(
-    include_deactivated: Optional[bool] = True,
+async def build_all_installed_extensions_list(  # noqa: C901
+    include_deactivated: bool | None = True,
 ) -> list[InstallableExtension]:
     """
     Returns a list of all the installed extensions plus the extensions that
@@ -299,8 +317,9 @@ async def build_all_installed_extensions_list(
 
             installed_extensions.append(ext_info)
             await create_installed_extension(ext_info)
-            current_version = await get_db_version(ext_id)
-            await migrate_extension_database(ext_info, current_version)
+            if not is_wasm_extension_dir(ext_dir):
+                current_version = await get_db_version(ext_id)
+                await migrate_extension_database(ext_info, current_version)
 
         except Exception as e:
             logger.warning(e)
@@ -401,6 +420,13 @@ def register_new_ext_routes(app: FastAPI) -> Callable:
     return register_new_ext_routes_fn
 
 
+def register_new_wasm_ext_routes(app: FastAPI) -> Callable:
+    def register_new_wasm_ext_routes_fn(ext_id: str):
+        register_wasm_extension(app, ext_id)
+
+    return register_new_wasm_ext_routes_fn
+
+
 def register_new_ratelimiter(app: FastAPI) -> Callable:
     def register_new_ratelimiter_fn():
         limiter = Limiter(
@@ -450,22 +476,31 @@ def register_ext_routes(app: FastAPI, ext: Extension) -> None:
     app.include_router(router=ext_route, prefix=prefix)
 
 
-async def check_and_register_extensions(app: FastAPI):
+async def check_and_register_extensions(app: FastAPI) -> None:
     await check_installed_extensions(app)
     for ext in await get_valid_extensions(False):
         try:
+            if is_wasm_extension_id(ext.code):
+                register_wasm_extension(app, ext.code)
+                continue
             register_ext_routes(app, ext)
             register_ext_tasks(ext)
         except Exception as exc:
             logger.error(f"Could not load extension `{ext.code}`: {exc!s}")
+            await update_installed_extension_state(ext_id=ext.code, active=False)
 
 
-def register_async_tasks():
+def register_async_tasks() -> None:
 
     create_permanent_task(wait_for_audit_data)
     create_permanent_task(wait_notification_messages)
 
-    create_permanent_task(check_pending_payments)
+    create_permanent_task(
+        run_interval(
+            settings.lnbits_funding_source_pending_interval_seconds,
+            check_pending_payments,
+        )
+    )
     create_permanent_task(invoice_listener)
     create_permanent_task(internal_invoice_listener)
     create_permanent_task(cache.invalidate_forever)
@@ -473,6 +508,11 @@ def register_async_tasks():
     # core invoice listener
     invoice_queue: asyncio.Queue = asyncio.Queue()
     register_invoice_listener(invoice_queue, "core")
+
+    async def dispatch_extension_invoice_paid(payment) -> None:
+        await dispatch_wasm_invoice_paid(payment)
+
+    core_app_extra.dispatch_extension_invoice_paid = dispatch_extension_invoice_paid
     create_permanent_task(lambda: wait_for_paid_invoices(invoice_queue))
 
     create_permanent_task(run_by_the_minute_tasks)

lnbits/commands.py

@@ -3,8 +3,9 @@ import importlib
 import sys
 import time
 from functools import wraps
+from getpass import getpass
 from pathlib import Path
-from typing import Optional
+from uuid import uuid4
 
 import click
 import httpx
@@ -27,19 +28,21 @@ from lnbits.core.crud import (
     update_payment,
 )
 from lnbits.core.helpers import is_valid_url, migrate_databases
-from lnbits.core.models import Payment, PaymentState
+from lnbits.core.models import Account, Payment, PaymentState
 from lnbits.core.models.extensions import (
     CreateExtension,
     ExtensionRelease,
     InstallableExtension,
 )
-from lnbits.core.services import check_admin_settings
+from lnbits.core.services import check_admin_settings, create_user_account_no_ckeck
 from lnbits.core.views.extension_api import (
     api_install_extension,
     api_uninstall_extension,
 )
 from lnbits.settings import settings
+from lnbits.utils.crypto import AESCipher
 from lnbits.wallets.base import Wallet
+from lnbits.wallets.macaroon import load_macaroon
 
 
 def coro(f):
@@ -64,6 +67,13 @@ def db():
     """
 
 
+@lnbits_cli.group()
+def users():
+    """
+    Users related commands
+    """
+
+
 @lnbits_cli.group()
 def extensions():
     """
@@ -71,7 +81,21 @@ def extensions():
     """
 
 
-def get_super_user() -> Optional[str]:
+@lnbits_cli.group()
+def encrypt():
+    """
+    Encryption commands
+    """
+
+
+@lnbits_cli.group()
+def decrypt():
+    """
+    Decryption commands
+    """
+
+
+def get_super_user() -> str | None:
     """Get the superuser"""
     superuser_file = Path(settings.lnbits_data_folder, ".super_user")
     if not superuser_file.exists() or not superuser_file.is_file():
@@ -109,7 +133,7 @@ async def delete_settings():
     """Deletes the settings"""
 
     async with core_db.connect() as conn:
-        await conn.execute("DELETE from settings")
+        await conn.execute("DELETE from system_settings")
 
 
 @db.command("migrate")
@@ -130,7 +154,7 @@ async def db_versions():
 @db.command("cleanup-wallets")
 @click.argument("days", type=int, required=False)
 @coro
-async def database_cleanup_wallets(days: Optional[int] = None):
+async def database_cleanup_wallets(days: int | None = None):
     """Delete all wallets that never had any transaction"""
     async with core_db.connect() as conn:
         delta = days or settings.cleanup_wallets_days
@@ -180,17 +204,6 @@ async def database_revert_payment(checking_id: str):
         click.echo(f"Payment '{checking_id}' marked as pending.")
 
 
-@db.command("cleanup-accounts")
-@click.argument("days", type=int, required=False)
-@coro
-async def database_cleanup_accounts(days: Optional[int] = None):
-    """Delete all accounts that have no wallets"""
-    async with core_db.connect() as conn:
-        delta = days or settings.cleanup_wallets_days
-        delta = delta * 24 * 60 * 60
-        await delete_accounts_no_wallets(delta, conn)
-
-
 @db.command("check-payments")
 @click.option("-d", "--days", help="Maximum age of payments in days.")
 @click.option("-l", "--limit", help="Maximum number of payments to be checked.")
@@ -198,10 +211,10 @@ async def database_cleanup_accounts(days: Optional[int] = None):
 @click.option("-v", "--verbose", is_flag=True, help="Detailed log.")
 @coro
 async def check_invalid_payments(
-    days: Optional[int] = None,
-    limit: Optional[int] = None,
-    wallet: Optional[str] = None,
-    verbose: Optional[bool] = False,
+    days: int | None = None,
+    limit: int | None = None,
+    wallet: str | None = None,
+    verbose: bool | None = False,
 ):
     """Check payments that are settled in the DB but pending on the Funding Source"""
     await check_admin_settings()
@@ -271,6 +284,32 @@ async def check_invalid_payments(
         click.echo(" ".join([w, str(data[0]), str(data[1] / 1000).ljust(10)]))
 
 
+@users.command("new")
+@click.option("-u", "--username", required=True, help="Username.")
+@click.option("-p", "--password", required=True, help="Password.")
+@coro
+async def create_user(username: str, password: str):
+    """Create a new user bypassing the system 'new_accounts_allowed' rules"""
+    account = Account(
+        id=uuid4().hex,
+        username=username,
+    )
+    account.hash_password(password)
+    user = await create_user_account_no_ckeck(account)
+    click.echo(f"User '{user.username}' created. Id: '{user.id}'")
+
+
+@users.command("cleanup-accounts")
+@click.argument("days", type=int, required=False)
+@coro
+async def database_cleanup_accounts(days: int | None = None):
+    """Delete all accounts that have no wallets"""
+    async with core_db.connect() as conn:
+        delta = days or settings.cleanup_wallets_days
+        delta = delta * 24 * 60 * 60
+        await delete_accounts_no_wallets(delta, conn)
+
+
 @extensions.command("list")
 @coro
 async def extensions_list():
@@ -280,9 +319,8 @@ async def extensions_list():
     from lnbits.app import build_all_installed_extensions_list
 
     for ext in await build_all_installed_extensions_list():
-        assert (
-            ext.meta and ext.meta.installed_release
-        ), f"Extension {ext.id} has no installed_release"
+        if not ext.meta or not ext.meta.installed_release:
+            raise ValueError(f"Extension {ext.id} has no installed_release")
         click.echo(f"  - {ext.id} ({ext.meta.installed_release.version})")
 
 
@@ -313,13 +351,13 @@ async def extensions_list():
     help="Admin user ID (must have permissions to install extensions).",
 )
 @coro
-async def extensions_update(
-    extension: Optional[str] = None,
-    all_extensions: Optional[bool] = False,
-    repo_index: Optional[str] = None,
-    source_repo: Optional[str] = None,
-    url: Optional[str] = None,
-    admin_user: Optional[str] = None,
+async def extensions_update(  # noqa: C901
+    extension: str | None = None,
+    all_extensions: bool | None = False,
+    repo_index: str | None = None,
+    source_repo: str | None = None,
+    url: str | None = None,
+    admin_user: str | None = None,
 ):
     """
     Update extension to the latest version.
@@ -404,10 +442,10 @@ async def extensions_update(
 @coro
 async def extensions_install(
     extension: str,
-    repo_index: Optional[str] = None,
-    source_repo: Optional[str] = None,
-    url: Optional[str] = None,
-    admin_user: Optional[str] = None,
+    repo_index: str | None = None,
+    source_repo: str | None = None,
+    url: str | None = None,
+    admin_user: str | None = None,
 ):
     """Install a extension"""
     click.echo(f"Installing {extension}... {repo_index}")
@@ -434,7 +472,7 @@ async def extensions_install(
 )
 @coro
 async def extensions_uninstall(
-    extension: str, url: Optional[str] = None, admin_user: Optional[str] = None
+    extension: str, url: str | None = None, admin_user: str | None = None
 ):
     """Uninstall a extension"""
     click.echo(f"Uninstalling '{extension}'...")
@@ -456,6 +494,62 @@ async def extensions_uninstall(
         return False, str(ex)
 
 
+@encrypt.command("macaroon")
+def encrypt_macaroon():
+    """Encrypts a macaroon (LND wallets)"""
+    _macaroon = getpass("Enter macaroon: ")
+    try:
+        macaroon = load_macaroon(_macaroon)
+    except Exception as ex:
+        click.echo(f"Error loading macaroon: {ex}")
+        return
+    key = getpass("Enter encryption key: ")
+    aes = AESCipher(key.encode())
+    try:
+        encrypted_macaroon = aes.encrypt(bytes.fromhex(macaroon))
+    except Exception as ex:
+        click.echo(f"Error encrypting macaroon: {ex}")
+        return
+    click.echo("Encrypted macaroon: ")
+    click.echo(encrypted_macaroon)
+
+
+@encrypt.command("aes")
+@click.option("-p", "--payload", required=True, help="Payload to encrypt.")
+@click.option(
+    "-u", "--urlsafe", is_flag=True, required=False, help="Urlsafe b64encode."
+)
+def encrypt_aes(payload: str, urlsafe: bool = False):
+    """AES encrypts a payload"""
+    key = getpass("Enter encryption key: ")
+    aes = AESCipher(key.encode())
+    try:
+        encrypted = aes.encrypt(payload.encode(), urlsafe=urlsafe)
+    except Exception as ex:
+        click.echo(f"Error encrypting payload: {ex}")
+        return
+    click.echo("Encrypted payload: ")
+    click.echo(encrypted)
+
+
+@decrypt.command("aes")
+@click.option("-p", "--payload", required=True, help="Payload to decrypt.")
+@click.option(
+    "-u", "--urlsafe", is_flag=True, required=False, help="Urlsafe b64decode."
+)
+def decrypt_aes(payload: str, urlsafe: bool = False):
+    """AES decrypts a payload"""
+    key = getpass("Enter encryption key: ")
+    aes = AESCipher(key.encode())
+    try:
+        decrypted = aes.decrypt(payload, urlsafe=urlsafe)
+    except Exception as ex:
+        click.echo(f"Error decrypting payload: {ex}")
+        return
+    click.echo("Decrypted payload: ")
+    click.echo(decrypted)
+
+
 def main():
     """main function"""
     lnbits_cli()
@@ -467,10 +561,10 @@ if __name__ == "__main__":
 
 async def install_extension(
     extension: str,
-    repo_index: Optional[str] = None,
-    source_repo: Optional[str] = None,
-    url: Optional[str] = None,
-    admin_user: Optional[str] = None,
+    repo_index: str | None = None,
+    source_repo: str | None = None,
+    url: str | None = None,
+    admin_user: str | None = None,
 ) -> tuple[bool, str]:
     try:
         release = await _select_release(extension, repo_index, source_repo)
@@ -496,10 +590,10 @@ async def install_extension(
 
 async def update_extension(
     extension: str,
-    repo_index: Optional[str] = None,
-    source_repo: Optional[str] = None,
-    url: Optional[str] = None,
-    admin_user: Optional[str] = None,
+    repo_index: str | None = None,
+    source_repo: str | None = None,
+    url: str | None = None,
+    admin_user: str | None = None,
 ) -> tuple[bool, str]:
     try:
         click.echo(f"Updating '{extension}' extension.")
@@ -512,9 +606,10 @@ async def update_extension(
 
         click.echo(f"Current '{extension}' version: {installed_ext.installed_version}.")
 
-        assert (
-            installed_ext.meta and installed_ext.meta.installed_release
-        ), "Cannot find previously installed release. Please uninstall first."
+        if not installed_ext.meta or not installed_ext.meta.installed_release:
+            raise ValueError(
+                "Cannot find previously installed release. Please uninstall first."
+            )
 
         release = await _select_release(extension, repo_index, source_repo)
         if not release:
@@ -548,9 +643,9 @@ async def update_extension(
 
 async def _select_release(
     extension: str,
-    repo_index: Optional[str] = None,
-    source_repo: Optional[str] = None,
-) -> Optional[ExtensionRelease]:
+    repo_index: str | None = None,
+    source_repo: str | None = None,
+) -> ExtensionRelease | None:
     all_releases = await InstallableExtension.get_extension_releases(extension)
     if len(all_releases) == 0:
         click.echo(f"No repository found for extension '{extension}'.")
@@ -610,7 +705,7 @@ def _get_latest_release_per_repo(all_releases):
 
 
 async def _call_install_extension(
-    data: CreateExtension, url: Optional[str], user_id: Optional[str] = None
+    data: CreateExtension, url: str | None, user_id: str | None = None
 ):
     if url:
         user_id = user_id or get_super_user()
@@ -624,7 +719,7 @@ async def _call_install_extension(
 
 
 async def _call_uninstall_extension(
-    extension: str, url: Optional[str], user_id: Optional[str] = None
+    extension: str, url: str | None, user_id: str | None = None
 ):
     if url:
         user_id = user_id or get_super_user()
@@ -660,7 +755,7 @@ async def _can_run_operation(url) -> bool:
     return True
 
 
-async def _is_lnbits_started(url: Optional[str]):
+async def _is_lnbits_started(url: str | None):
     try:
         url = url or f"http://{settings.host}:{settings.port}/api/v1/health"
         async with httpx.AsyncClient() as client:

lnbits/core/__init__.py

@@ -3,12 +3,17 @@ from fastapi import APIRouter, FastAPI
 from .db import core_app_extra, db
 from .views.admin_api import admin_router
 from .views.api import api_router
+from .views.asset_api import asset_router
 from .views.audit_api import audit_router
 from .views.auth_api import auth_router
+from .views.callback_api import callback_router
 from .views.extension_api import extension_router
+from .views.extensions_builder_api import extension_builder_router
+from .views.fiat_api import fiat_router
 
 # this compat is needed for usermanager extension
 from .views.generic import generic_router
+from .views.lnurl_api import lnurl_router
 from .views.node_api import node_router, public_node_router, super_node_router
 from .views.payment_api import payment_router
 from .views.tinyurl_api import tinyurl_router
@@ -28,16 +33,21 @@ def init_core_routers(app: FastAPI):
     app.include_router(admin_router)
     app.include_router(node_router)
     app.include_router(extension_router)
+    app.include_router(extension_builder_router)
     app.include_router(super_node_router)
     app.include_router(public_node_router)
     app.include_router(payment_router)
     app.include_router(wallet_router)
     app.include_router(api_router)
     app.include_router(websocket_router)
+    app.include_router(callback_router)
     app.include_router(tinyurl_router)
     app.include_router(webpush_router)
     app.include_router(users_router)
     app.include_router(audit_router)
+    app.include_router(asset_router)
+    app.include_router(fiat_router)
+    app.include_router(lnurl_router)
 
 
 __all__ = ["core_app", "core_app_extra", "db"]

lnbits/core/crud/__init__.py

@@ -12,6 +12,7 @@ from .extensions import (
     drop_extension_db,
     get_installed_extension,
     get_installed_extensions,
+    get_installed_extensions_count,
     get_user_active_extensions_ids,
     get_user_extension,
     get_user_extensions,
@@ -43,6 +44,7 @@ from .settings import (
     delete_admin_settings,
     get_admin_settings,
     get_super_settings,
+    reset_core_settings,
     update_admin_settings,
     update_super_user,
 )
@@ -57,6 +59,7 @@ from .users import (
     get_account_by_username,
     get_account_by_username_or_email,
     get_accounts,
+    get_accounts_count,
     get_user,
     get_user_access_control_lists,
     get_user_from_account,
@@ -84,86 +87,80 @@ from .webpush import (
 )
 
 __all__ = [
-    # audit
-    "create_audit_entry",
-    # db_versions
-    "get_db_version",
-    "get_db_versions",
-    "update_migration_version",
-    "delete_dbversion",
-    # extensions
-    "create_installed_extension",
-    "create_user_extension",
-    "delete_installed_extension",
-    "drop_extension_db",
-    "get_installed_extension",
-    "get_installed_extensions",
-    "get_user_active_extensions_ids",
-    "get_user_extension",
-    "update_installed_extension",
-    "update_installed_extension_state",
-    "update_user_extension",
-    "get_user_extensions",
-    # payments
     "DateTrunc",
     "check_internal",
-    "create_payment",
-    "delete_expired_invoices",
-    "delete_wallet_payment",
-    "get_latest_payments_by_extension",
-    "get_payment",
-    "get_payments",
-    "get_payments_history",
-    "get_payments_paginated",
-    "get_standalone_payment",
-    "get_wallet_payment",
-    "is_internal_status_success",
-    "mark_webhook_sent",
-    "update_payment",
-    "update_payment_checking_id",
-    "update_payment_extra",
-    # settings
-    "create_admin_settings",
-    "delete_admin_settings",
-    "get_admin_settings",
-    "get_super_settings",
-    "update_admin_settings",
-    "update_super_user",
-    # tinyurl
-    "create_tinyurl",
-    "delete_tinyurl",
-    "get_tinyurl",
-    "get_tinyurl_by_url",
-    # users
     "create_account",
+    "create_admin_settings",
+    "create_audit_entry",
+    "create_installed_extension",
+    "create_payment",
+    "create_tinyurl",
+    "create_user_extension",
+    "create_wallet",
+    "create_webpush_subscription",
     "delete_account",
     "delete_accounts_no_wallets",
+    "delete_admin_settings",
+    "delete_dbversion",
+    "delete_expired_invoices",
+    "delete_installed_extension",
+    "delete_tinyurl",
+    "delete_unused_wallets",
+    "delete_wallet",
+    "delete_wallet_by_id",
+    "delete_wallet_payment",
+    "delete_webpush_subscription",
+    "delete_webpush_subscriptions",
+    "drop_extension_db",
+    "force_delete_wallet",
     "get_account",
     "get_account_by_email",
     "get_account_by_pubkey",
     "get_account_by_username",
     "get_account_by_username_or_email",
     "get_accounts",
-    "get_user",
-    "get_user_from_account",
-    "get_user_access_control_lists",
-    "update_account",
-    # wallets
-    "create_wallet",
-    "delete_unused_wallets",
-    "delete_wallet",
-    "delete_wallet_by_id",
-    "force_delete_wallet",
+    "get_accounts_count",
+    "get_admin_settings",
+    "get_db_version",
+    "get_db_versions",
+    "get_installed_extension",
+    "get_installed_extensions",
+    "get_installed_extensions_count",
+    "get_latest_payments_by_extension",
+    "get_payment",
+    "get_payments",
+    "get_payments_history",
+    "get_payments_paginated",
+    "get_standalone_payment",
+    "get_super_settings",
+    "get_tinyurl",
+    "get_tinyurl_by_url",
     "get_total_balance",
+    "get_user",
+    "get_user_access_control_lists",
+    "get_user_active_extensions_ids",
+    "get_user_extension",
+    "get_user_extensions",
+    "get_user_from_account",
     "get_wallet",
     "get_wallet_for_key",
+    "get_wallet_payment",
     "get_wallets",
-    "remove_deleted_wallets",
-    "update_wallet",
-    # webpush
-    "create_webpush_subscription",
-    "delete_webpush_subscription",
-    "delete_webpush_subscriptions",
     "get_webpush_subscription",
     "get_webpush_subscriptions_for_user",
+    "is_internal_status_success",
+    "mark_webhook_sent",
+    "remove_deleted_wallets",
+    "reset_core_settings",
+    "update_account",
+    "update_admin_settings",
+    "update_installed_extension",
+    "update_installed_extension_state",
+    "update_migration_version",
+    "update_payment",
+    "update_payment_checking_id",
+    "update_payment_extra",
+    "update_super_user",
+    "update_user_extension",
+    "update_wallet",
 ]

lnbits/core/crud/assets.py

@@ -0,0 +1,108 @@
+from lnbits.core.db import db
+from lnbits.core.models.assets import Asset, AssetFilters, AssetInfo
+from lnbits.db import Connection, Filters, Page
+
+
+async def create_asset(
+    entry: Asset,
+    conn: Connection | None = None,
+) -> None:
+    await (conn or db).insert("assets", entry)
+
+
+async def get_user_asset_info(
+    user_id: str,
+    asset_id: str,
+    conn: Connection | None = None,
+) -> AssetInfo | None:
+    return await (conn or db).fetchone(
+        query="SELECT * from assets WHERE id = :asset_id AND user_id = :user_id",
+        values={"asset_id": asset_id, "user_id": user_id},
+        model=AssetInfo,
+    )
+
+
+async def get_asset_info(
+    asset_id: str, conn: Connection | None = None
+) -> AssetInfo | None:
+    return await (conn or db).fetchone(
+        query="SELECT * from assets WHERE id = :asset_id",
+        values={"asset_id": asset_id},
+        model=AssetInfo,
+    )
+
+
+async def get_user_asset(
+    user_id: str,
+    asset_id: str,
+    conn: Connection | None = None,
+) -> Asset | None:
+    return await (conn or db).fetchone(
+        query="SELECT * from assets WHERE id = :asset_id AND user_id = :user_id",
+        values={"asset_id": asset_id, "user_id": user_id},
+        model=Asset,
+    )
+
+
+async def get_public_asset(
+    asset_id: str,
+    conn: Connection | None = None,
+) -> Asset | None:
+    return await (conn or db).fetchone(
+        query="SELECT * from assets WHERE id = :asset_id AND is_public = true",
+        values={"asset_id": asset_id},
+        model=Asset,
+    )
+
+
+async def get_public_asset_info(
+    asset_id: str,
+    conn: Connection | None = None,
+) -> AssetInfo | None:
+    return await (conn or db).fetchone(
+        query="SELECT * from assets WHERE id = :asset_id AND is_public = true",
+        values={"asset_id": asset_id},
+        model=AssetInfo,
+    )
+
+
+async def update_user_asset_info(
+    asset: AssetInfo,
+) -> AssetInfo:
+    await db.update("assets", asset)
+    return asset
+
+
+async def delete_user_asset(
+    user_id: str, asset_id: str, conn: Connection | None = None
+) -> None:
+    await (conn or db).execute(
+        query="DELETE FROM assets WHERE id = :asset_id AND user_id = :user_id",
+        values={"asset_id": asset_id, "user_id": user_id},
+    )
+
+
+async def get_user_assets(
+    user_id: str,
+    filters: Filters[AssetFilters] | None = None,
+    conn: Connection | None = None,
+) -> Page[AssetInfo]:
+    filters = filters or Filters()
+    filters.sortby = filters.sortby or "created_at"
+    return await (conn or db).fetch_page(
+        query="SELECT * FROM assets",
+        where=["user_id = :user_id"],
+        values={"user_id": user_id},
+        filters=filters,
+        model=AssetInfo,
+        table_name="assets",
+    )
+
+
+async def get_user_assets_count(user_id: str) -> int:
+    result = await db.execute(
+        query="SELECT COUNT(*) as count FROM assets WHERE user_id = :user_id",
+        values={"user_id": user_id},
+    )
+    row = result.mappings().first()
+    return row.get("count", 0)

lnbits/core/crud/audit.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 from lnbits.core.db import db
 from lnbits.core.models import AuditEntry, AuditFilters
 from lnbits.core.models.audit import AuditCountStat
@@ -8,39 +6,41 @@ from lnbits.db import Connection, Filters, Page
 
 async def create_audit_entry(
     entry: AuditEntry,
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ) -> None:
     await (conn or db).insert("audit", entry)
 
 
 async def get_audit_entries(
-    filters: Optional[Filters[AuditFilters]] = None,
-    conn: Optional[Connection] = None,
+    filters: Filters[AuditFilters] | None = None,
+    conn: Connection | None = None,
 ) -> Page[AuditEntry]:
     return await (conn or db).fetch_page(
-        "SELECT * from audit",
+        "SELECT * FROM audit",
         [],
         {},
         filters=filters,
         model=AuditEntry,
+        table_name="audit",
     )
 
 
 async def delete_expired_audit_entries(
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ):
     await (conn or db).execute(
+        # Timestamp placeholder is safe from SQL injection (not user input)
         f"""
             DELETE from audit
             WHERE delete_at < {db.timestamp_now}
-        """,
+        """,  # noqa: S608
     )
 
 
 async def get_count_stats(
     field: str,
-    filters: Optional[Filters[AuditFilters]] = None,
-    conn: Optional[Connection] = None,
+    filters: Filters[AuditFilters] | None = None,
+    conn: Connection | None = None,
 ) -> list[AuditCountStat]:
     if field not in ["request_method", "component", "response_code"]:
         return []
@@ -48,13 +48,16 @@ async def get_count_stats(
         filters = Filters()
     clause = filters.where()
     data = await (conn or db).fetchall(
+        # SQL injection vectors safety:
+        # - `field` is a static string, not user input
+        # - `clause` is generated from filters, which are validated and sanitized
         query=f"""
             SELECT {field} as field, count({field}) as total
             FROM audit
             {clause}
             GROUP BY {field}
             ORDER BY {field}
-        """,
+        """,  # noqa: S608
         values=filters.values(),
         model=AuditCountStat,
     )
@@ -63,20 +66,22 @@ async def get_count_stats(
 
 
 async def get_long_duration_stats(
-    filters: Optional[Filters[AuditFilters]] = None,
-    conn: Optional[Connection] = None,
+    filters: Filters[AuditFilters] | None = None,
+    conn: Connection | None = None,
 ) -> list[AuditCountStat]:
     if not filters:
         filters = Filters()
     clause = filters.where()
     long_duration_paths = await (conn or db).fetchall(
+        # This query is safe from SQL injection
+        # The `clause` is constructed from sanitized inputs
         query=f"""
             SELECT path as field, max(duration) as total FROM audit
             {clause}
             GROUP BY path
             ORDER BY total DESC
             LIMIT 5
-        """,
+        """,  # noqa: S608
         values=filters.values(),
         model=AuditCountStat,
     )

lnbits/core/crud/db_versions.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 from lnbits.core.db import db
 from lnbits.db import Connection
 
@@ -7,8 +5,8 @@ from ..models import DbVersion
 
 
 async def get_db_version(
-    ext_id: str, conn: Optional[Connection] = None
-) -> Optional[DbVersion]:
+    ext_id: str, conn: Connection | None = None
+) -> DbVersion | None:
     return await (conn or db).fetchone(
         "SELECT * FROM dbversions WHERE db = :ext_id",
         {"ext_id": ext_id},
@@ -16,7 +14,7 @@ async def get_db_version(
     )
 
 
-async def get_db_versions(conn: Optional[Connection] = None) -> list[DbVersion]:
+async def get_db_versions(conn: Connection | None = None) -> list[DbVersion]:
     return await (conn or db).fetchall("SELECT * FROM dbversions", model=DbVersion)
 
 
@@ -30,7 +28,7 @@ async def update_migration_version(conn, db_name, version):
     )
 
 
-async def delete_dbversion(*, ext_id: str, conn: Optional[Connection] = None) -> None:
+async def delete_dbversion(*, ext_id: str, conn: Connection | None = None) -> None:
     await (conn or db).execute(
         """
         DELETE FROM dbversions WHERE db = :ext

lnbits/core/crud/extensions.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 from lnbits.core.db import db
 from lnbits.core.models.extensions import (
     InstallableExtension,
@@ -10,20 +8,20 @@ from lnbits.db import Connection, Database
 
 async def create_installed_extension(
     ext: InstallableExtension,
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ) -> None:
     await (conn or db).insert("installed_extensions", ext)
 
 
 async def update_installed_extension(
     ext: InstallableExtension,
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ) -> None:
     await (conn or db).update("installed_extensions", ext)
 
 
 async def update_installed_extension_state(
-    *, ext_id: str, active: bool, conn: Optional[Connection] = None
+    *, ext_id: str, active: bool, conn: Connection | None = None
 ) -> None:
     await (conn or db).execute(
         """
@@ -34,7 +32,7 @@ async def update_installed_extension_state(
 
 
 async def delete_installed_extension(
-    *, ext_id: str, conn: Optional[Connection] = None
+    *, ext_id: str, conn: Connection | None = None
 ) -> None:
     await (conn or db).execute(
         """
@@ -44,13 +42,14 @@ async def delete_installed_extension(
     )
 
 
-async def drop_extension_db(ext_id: str, conn: Optional[Connection] = None) -> None:
+async def drop_extension_db(ext_id: str, conn: Connection | None = None) -> None:
     row: dict = await (conn or db).fetchone(
         "SELECT * FROM dbversions WHERE db = :id",
         {"id": ext_id},
     )
     # Check that 'ext_id' is a valid extension id and not a malicious string
-    assert row, f"Extension '{ext_id}' db version cannot be found"
+    if not row:
+        raise Exception(f"Extension '{ext_id}' db version cannot be found")
 
     is_file_based_db = await Database.clean_ext_db_files(ext_id)
     if is_file_based_db:
@@ -64,8 +63,8 @@ async def drop_extension_db(ext_id: str, conn: Optional[Connection] = None) -> N
 
 
 async def get_installed_extension(
-    ext_id: str, conn: Optional[Connection] = None
-) -> Optional[InstallableExtension]:
+    ext_id: str, conn: Connection | None = None
+) -> InstallableExtension | None:
     extension = await (conn or db).fetchone(
         "SELECT * FROM installed_extensions WHERE id = :id",
         {"id": ext_id},
@@ -75,22 +74,32 @@ async def get_installed_extension(
 
 
 async def get_installed_extensions(
-    active: Optional[bool] = None,
-    conn: Optional[Connection] = None,
+    active: bool | None = None,
+    conn: Connection | None = None,
 ) -> list[InstallableExtension]:
-    where = "WHERE active = :active" if active is not None else ""
+    query = "SELECT * FROM installed_extensions"
+    if active is not None:
+        query += " WHERE active = :active"
+
     values = {"active": active} if active is not None else {}
     all_extensions = await (conn or db).fetchall(
-        f"SELECT * FROM installed_extensions {where}",
+        query,
         values,
         model=InstallableExtension,
     )
     return all_extensions
 
 
+async def get_installed_extensions_count(conn: Connection | None = None) -> int:
+    row: dict | None = await (conn or db).fetchone(
+        "SELECT COUNT(*) as count FROM installed_extensions"
+    )
+    return int(row["count"]) if row else 0
+
+
 async def get_user_extension(
-    user_id: str, extension: str, conn: Optional[Connection] = None
-) -> Optional[UserExtension]:
+    user_id: str, extension: str, conn: Connection | None = None
+) -> UserExtension | None:
     return await (conn or db).fetchone(
         """
         SELECT * FROM extensions
@@ -102,7 +111,7 @@ async def get_user_extension(
 
 
 async def get_user_extensions(
-    user_id: str, conn: Optional[Connection] = None
+    user_id: str, conn: Connection | None = None
 ) -> list[UserExtension]:
     return await (conn or db).fetchall(
         """SELECT * FROM extensions WHERE "user" = :user""",
@@ -112,20 +121,20 @@ async def get_user_extensions(
 
 
 async def create_user_extension(
-    user_extension: UserExtension, conn: Optional[Connection] = None
+    user_extension: UserExtension, conn: Connection | None = None
 ) -> None:
     await (conn or db).insert("extensions", user_extension)
 
 
 async def update_user_extension(
-    user_extension: UserExtension, conn: Optional[Connection] = None
+    user_extension: UserExtension, conn: Connection | None = None
 ) -> None:
     where = """WHERE extension = :extension AND "user" = :user"""
     await (conn or db).update("extensions", user_extension, where)
 
 
 async def get_user_active_extensions_ids(
-    user_id: str, conn: Optional[Connection] = None
+    user_id: str, conn: Connection | None = None
 ) -> list[str]:
     exts = await (conn or db).fetchall(
         """

lnbits/core/crud/payments.py

@@ -1,7 +1,8 @@
+from datetime import datetime, timezone
 from time import time
-from typing import Optional, Tuple
+from typing import Any
 
-from lnbits.core.crud.wallets import get_total_balance, get_wallet
+from lnbits.core.crud.wallets import get_total_balance, get_wallet, get_wallets_ids
 from lnbits.core.db import db
 from lnbits.core.models import PaymentState
 from lnbits.db import Connection, DateTrunc, Filters, Page
@@ -23,7 +24,7 @@ def update_payment_extra():
     pass
 
 
-async def get_payment(checking_id: str, conn: Optional[Connection] = None) -> Payment:
+async def get_payment(checking_id: str, conn: Connection | None = None) -> Payment:
     return await (conn or db).fetchone(
         "SELECT * FROM apipayments WHERE checking_id = :checking_id",
         {"checking_id": checking_id},
@@ -33,13 +34,12 @@ async def get_payment(checking_id: str, conn: Optional[Connection] = None) -> Pa
 
 async def get_standalone_payment(
     checking_id_or_hash: str,
-    conn: Optional[Connection] = None,
-    incoming: Optional[bool] = False,
-    wallet_id: Optional[str] = None,
-) -> Optional[Payment]:
+    incoming: bool | None = False,
+    wallet_id: str | None = None,
+    conn: Connection | None = None,
+) -> Payment | None:
     clause: str = "checking_id = :checking_id OR payment_hash = :hash"
     values = {
-        "wallet_id": wallet_id,
         "checking_id": checking_id_or_hash,
         "hash": checking_id_or_hash,
     }
@@ -47,14 +47,20 @@ async def get_standalone_payment(
         clause = f"({clause}) AND amount > 0"
 
     if wallet_id:
+        wallet = await get_wallet(wallet_id, conn=conn)
+        if not wallet or not wallet.can_view_payments:
+            return None
+        values["wallet_id"] = wallet.source_wallet_id
         clause = f"({clause}) AND wallet_id = :wallet_id"
 
     row = await (conn or db).fetchone(
+        # This query is safe from SQL injection
+        # The `clause` is constructed from sanitized inputs
         f"""
         SELECT * FROM apipayments
         WHERE {clause}
         ORDER BY amount LIMIT 1
-        """,
+        """,  # noqa: S608
         values,
         Payment,
     )
@@ -62,15 +68,18 @@ async def get_standalone_payment(
 
 
 async def get_wallet_payment(
-    wallet_id: str, payment_hash: str, conn: Optional[Connection] = None
-) -> Optional[Payment]:
+    wallet_id: str, payment_hash: str, conn: Connection | None = None
+) -> Payment | None:
+    wallet = await get_wallet(wallet_id, conn=conn)
+    if not wallet or not wallet.can_view_payments:
+        return None
     payment = await (conn or db).fetchone(
         """
         SELECT *
         FROM apipayments
         WHERE wallet_id = :wallet AND payment_hash = :hash
         """,
-        {"wallet": wallet_id, "hash": payment_hash},
+        {"wallet": wallet.source_wallet_id, "hash": payment_hash},
         Payment,
     )
     return payment
@@ -80,38 +89,43 @@ async def get_latest_payments_by_extension(
     ext_name: str, ext_id: str, limit: int = 5
 ) -> list[Payment]:
     return await db.fetchall(
+        # This query is safe from SQL injection
+        # The limtit is an integer and not user input
         f"""
         SELECT * FROM apipayments
-        WHERE status = '{PaymentState.SUCCESS}'
+        WHERE status = :status
         AND extra LIKE :ext_name
         AND extra LIKE :ext_id
         ORDER BY time DESC LIMIT {int(limit)}
-        """,
-        {"ext_name": f"%{ext_name}%", "ext_id": f"%{ext_id}%"},
+        """,  # noqa: S608
+        {
+            "status": f"{PaymentState.SUCCESS}",
+            "ext_name": f"%{ext_name}%",
+            "ext_id": f"%{ext_id}%",
+        },
         Payment,
     )
 
 
-async def get_payments_paginated(
+async def get_payments_paginated(  # noqa: C901
     *,
-    wallet_id: Optional[str] = None,
+    wallet_id: str | None = None,
+    user_id: str | None = None,
     complete: bool = False,
     pending: bool = False,
     failed: bool = False,
     outgoing: bool = False,
     incoming: bool = False,
-    since: Optional[int] = None,
+    since: int | None = None,
     exclude_uncheckable: bool = False,
-    filters: Optional[Filters[PaymentFilters]] = None,
-    conn: Optional[Connection] = None,
+    filters: Filters[PaymentFilters] | None = None,
+    conn: Connection | None = None,
 ) -> Page[Payment]:
     """
     Filters payments to be returned by:
       - complete | pending | failed | outgoing | incoming.
     """
-
-    values: dict = {
-        "wallet_id": wallet_id,
+    values: dict[str, Any] = {
         "time": since,
     }
     clause: list[str] = []
@@ -120,21 +134,27 @@ async def get_payments_paginated(
         clause.append(f"time > {db.timestamp_placeholder('time')}")
 
     if wallet_id:
+        wallet = await get_wallet(wallet_id, conn=conn)
+        if not wallet or not wallet.can_view_payments:
+            return Page(data=[], total=0)
+
+        values["wallet_id"] = wallet.source_wallet_id
         clause.append("wallet_id = :wallet_id")
+    elif user_id:
+        only_user_wallets = await _only_user_wallets_statement(user_id, conn=conn)
+        clause.append(only_user_wallets)
 
     if complete and pending:
         clause.append(
             f"(status = '{PaymentState.SUCCESS}' OR status = '{PaymentState.PENDING}')"
         )
     elif complete:
-        clause.append(
-            f"""
+        clause.append(f"""
             (
                 status = '{PaymentState.SUCCESS}'
                 OR (amount < 0 AND status = '{PaymentState.PENDING}')
             )
-            """
-        )
+            """)
     elif pending:
         clause.append(f"status = '{PaymentState.PENDING}'")
     elif failed:
@@ -159,22 +179,23 @@ async def get_payments_paginated(
         values,
         filters=filters,
         model=Payment,
+        table_name="apipayments",
     )
 
 
 async def get_payments(
     *,
-    wallet_id: Optional[str] = None,
+    wallet_id: str | None = None,
     complete: bool = False,
     pending: bool = False,
     outgoing: bool = False,
     incoming: bool = False,
-    since: Optional[int] = None,
+    since: int | None = None,
     exclude_uncheckable: bool = False,
-    filters: Optional[Filters[PaymentFilters]] = None,
-    conn: Optional[Connection] = None,
-    limit: Optional[int] = None,
-    offset: Optional[int] = None,
+    filters: Filters[PaymentFilters] | None = None,
+    conn: Connection | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
 ) -> list[Payment]:
     """
     Filters payments to be returned by complete | pending | outgoing | incoming.
@@ -218,26 +239,28 @@ async def get_payments_status_count() -> PaymentsStatusCount:
 
 
 async def delete_expired_invoices(
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ) -> None:
     # first we delete all invoices older than one month
 
     await (conn or db).execute(
+        # Timestamp placeholder is safe from SQL injection (not user input)
         f"""
         DELETE FROM apipayments
-        WHERE status = '{PaymentState.PENDING}' AND amount > 0
+        WHERE status = :status AND amount > 0
         AND time < {db.timestamp_placeholder("delta")}
-        """,
-        {"delta": int(time() - 2592000)},
+        """,  # noqa: S608
+        {"status": f"{PaymentState.PENDING}", "delta": int(time() - 2592000)},
     )
     # then we delete all invoices whose expiry date is in the past
     await (conn or db).execute(
+        # Timestamp placeholder is safe from SQL injection (not user input)
         f"""
         DELETE FROM apipayments
-        WHERE status = '{PaymentState.PENDING}' AND amount > 0
+        WHERE status = :status AND amount > 0
         AND expiry < {db.timestamp_placeholder("now")}
-        """,
-        {"now": int(time())},
+        """,  # noqa: S608
+        {"status": f"{PaymentState.PENDING}", "now": int(time())},
     )
 
 
@@ -245,12 +268,13 @@ async def create_payment(
     checking_id: str,
     data: CreatePayment,
     status: PaymentState = PaymentState.PENDING,
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ) -> Payment:
     # we don't allow the creation of the same invoice twice
     # note: this can be removed if the db uniqueness constraints are set appropriately
     previous_payment = await get_standalone_payment(checking_id, conn=conn)
-    assert previous_payment is None, "Payment already exists"
+    if previous_payment is not None:
+        raise ValueError("Payment already exists")
     extra = data.extra or {}
 
     payment = Payment(
@@ -264,9 +288,12 @@ async def create_payment(
         preimage=data.preimage,
         expiry=data.expiry,
         webhook=data.webhook,
-        fee=data.fee,
+        fee=-abs(data.fee),
         tag=extra.get("tag", None),
+        extension=data.extension,
         extra=extra,
+        labels=data.labels or [],
+        external_id=data.external_id,
     )
 
     await (conn or db).insert("apipayments", payment)
@@ -275,68 +302,82 @@ async def create_payment(
 
 
 async def update_payment_checking_id(
-    checking_id: str, new_checking_id: str, conn: Optional[Connection] = None
+    checking_id: str, new_checking_id: str, conn: Connection | None = None
 ) -> None:
     await (conn or db).execute(
-        "UPDATE apipayments SET checking_id = :new_id WHERE checking_id = :old_id",
-        {"new_id": new_checking_id, "old_id": checking_id},
+        f"""
+            UPDATE apipayments
+            SET checking_id = :new_id, updated_at = {db.timestamp_placeholder("now")}
+            WHERE checking_id = :old_id
+        """,  # noqa: S608
+        {
+            "new_id": new_checking_id,
+            "old_id": checking_id,
+            "now": int(time()),
+        },
     )
 
 
 async def update_payment(
     payment: Payment,
-    new_checking_id: Optional[str] = None,
-    conn: Optional[Connection] = None,
-) -> None:
+    new_checking_id: str | None = None,
+    conn: Connection | None = None,
+) -> Payment:
+    payment.updated_at = datetime.now(timezone.utc)
     await (conn or db).update(
         "apipayments", payment, "WHERE checking_id = :checking_id"
     )
     if new_checking_id and new_checking_id != payment.checking_id:
         await update_payment_checking_id(payment.checking_id, new_checking_id, conn)
+        payment.checking_id = new_checking_id
+    return payment
 
 
 async def get_payments_history(
-    wallet_id: Optional[str] = None,
+    wallet_id: str | None = None,
     group: DateTrunc = "day",
-    filters: Optional[Filters] = None,
+    filters: Filters | None = None,
+    conn: Connection | None = None,
 ) -> list[PaymentHistoryPoint]:
     if not filters:
         filters = Filters()
 
     date_trunc = db.datetime_grouping(group)
 
-    values = {
+    values: dict[str, Any] = {
         "wallet_id": wallet_id,
     }
     # count outgoing payments if they are still pending
-    where = [
-        f"""
+    where = [f"""
         wallet_id = :wallet_id AND (
             status = '{PaymentState.SUCCESS}'
             OR (amount < 0 AND status = '{PaymentState.PENDING}')
         )
-        """
-    ]
+        """]
+    clause = filters.where(where)
     transactions: list[dict] = await db.fetchall(
+        # This query is safe from SQL injection:
+        # - `date_trunc` is a static string, not user input
+        # - `clause` is generated from filters, which are validated and sanitized
         f"""
         SELECT {date_trunc} date,
                SUM(CASE WHEN amount > 0 THEN amount ELSE 0 END) income,
                SUM(CASE WHEN amount < 0 THEN abs(amount) + abs(fee) ELSE 0 END) spending
         FROM apipayments
-        {filters.where(where)}
+        {clause}
         GROUP BY date
         ORDER BY date DESC
-        """,
+        """,  # noqa: S608
         filters.values(values),
     )
     if wallet_id:
-        wallet = await get_wallet(wallet_id)
-        if wallet:
-            balance = wallet.balance_msat
-        else:
-            raise ValueError("Unknown wallet")
+        wallet = await get_wallet(wallet_id, conn=conn)
+        if not wallet or not wallet.can_view_payments:
+            return []
+        balance = wallet.balance_msat
+        values["wallet_id"] = wallet.source_wallet_id
     else:
-        balance = await get_total_balance()
+        balance = await get_total_balance(conn=conn)
 
     # since we dont know the balance at the starting point,
     # we take the current balance and walk backwards
@@ -357,21 +398,30 @@ async def get_payments_history(
 
 async def get_payment_count_stats(
     field: PaymentCountField,
-    filters: Optional[Filters[PaymentFilters]] = None,
-    conn: Optional[Connection] = None,
+    filters: Filters[PaymentFilters] | None = None,
+    user_id: str | None = None,
+    conn: Connection | None = None,
 ) -> list[PaymentCountStat]:
-
     if not filters:
         filters = Filters()
-    clause = filters.where()
+    extra_stmts = []
+
+    if user_id:
+        only_user_wallets = await _only_user_wallets_statement(user_id, conn=conn)
+        extra_stmts.append(only_user_wallets)
+
+    clause = filters.where(extra_stmts)
     data = await (conn or db).fetchall(
+        # SQL injection vectors safety:
+        # - `field` is a static string, not user input
+        # - `clause` is generated from filters, which are validated and sanitized
         query=f"""
             SELECT {field} as field, count(*) as total
             FROM apipayments
             {clause}
             GROUP BY {field}
             ORDER BY {field}
-        """,
+        """,  # noqa: S608
         values=filters.values(),
         model=PaymentCountStat,
     )
@@ -380,19 +430,26 @@ async def get_payment_count_stats(
 
 
 async def get_daily_stats(
-    filters: Optional[Filters[PaymentFilters]] = None,
-    conn: Optional[Connection] = None,
-) -> Tuple[list[PaymentDailyStats], list[PaymentDailyStats]]:
-
+    filters: Filters[PaymentFilters] | None = None,
+    user_id: str | None = None,
+    conn: Connection | None = None,
+) -> tuple[list[PaymentDailyStats], list[PaymentDailyStats]]:
     if not filters:
         filters = Filters()
 
-    in_clause = filters.where(
-        ["(apipayments.status = 'success' AND apipayments.amount > 0)"]
-    )
-    out_clause = filters.where(
-        ["(apipayments.status IN ('success', 'pending') AND apipayments.amount < 0)"]
-    )
+    in_where_stmts = ["(apipayments.status = 'success' AND apipayments.amount > 0)"]
+    out_where_stmts = [
+        "(apipayments.status IN ('success', 'pending') AND apipayments.amount < 0)"
+    ]
+
+    if user_id:
+        only_user_wallets = await _only_user_wallets_statement(user_id, conn=conn)
+        in_where_stmts.append(only_user_wallets)
+        out_where_stmts.append(only_user_wallets)
+
+    in_clause = filters.where(in_where_stmts)
+    out_clause = filters.where(out_where_stmts)
+
     date_trunc = db.datetime_grouping("day")
     query = """
         SELECT {date_trunc} date,
@@ -422,10 +479,10 @@ async def get_daily_stats(
 
 
 async def get_wallets_stats(
-    filters: Optional[Filters[PaymentFilters]] = None,
-    conn: Optional[Connection] = None,
+    filters: Filters[PaymentFilters] | None = None,
+    user_id: str | None = None,
+    conn: Connection | None = None,
 ) -> list[PaymentWalletStats]:
-
     if not filters:
         filters = Filters()
 
@@ -441,9 +498,15 @@ async def get_wallets_stats(
         )
         """,
     ]
+    if user_id:
+        only_user_wallets = await _only_user_wallets_statement(user_id, conn=conn)
+        where_stmts.append(only_user_wallets)
+
     clauses = filters.where(where_stmts)
 
     data = await (conn or db).fetchall(
+        # This query is safe from SQL injection
+        # The `clauses` is constructed from sanitized inputs
         query=f"""
             SELECT apipayments.wallet_id,
                     MAX(wallets.name) AS wallet_name,
@@ -455,7 +518,7 @@ async def get_wallets_stats(
             {clauses}
             GROUP BY apipayments.wallet_id
             ORDER BY payments_count
-        """,
+        """,  # noqa: S608
         values=filters.values(),
         model=PaymentWalletStats,
     )
@@ -464,7 +527,7 @@ async def get_wallets_stats(
 
 
 async def delete_wallet_payment(
-    checking_id: str, wallet_id: str, conn: Optional[Connection] = None
+    checking_id: str, wallet_id: str, conn: Connection | None = None
 ) -> None:
     await (conn or db).execute(
         "DELETE FROM apipayments WHERE checking_id = :checking_id AND wallet = :wallet",
@@ -473,24 +536,24 @@ async def delete_wallet_payment(
 
 
 async def check_internal(
-    payment_hash: str, conn: Optional[Connection] = None
-) -> Optional[Payment]:
+    payment_hash: str, conn: Connection | None = None
+) -> Payment | None:
     """
     Returns the checking_id of the internal payment if it exists,
     otherwise None
     """
     return await (conn or db).fetchone(
-        f"""
+        """
         SELECT * FROM apipayments
-        WHERE payment_hash = :hash AND status = '{PaymentState.PENDING}' AND amount > 0
+        WHERE payment_hash = :hash AND status = :status AND amount > 0
         """,
-        {"hash": payment_hash},
+        {"status": f"{PaymentState.PENDING}", "hash": payment_hash},
         Payment,
     )
 
 
 async def is_internal_status_success(
-    payment_hash: str, conn: Optional[Connection] = None
+    payment_hash: str, conn: Connection | None = None
 ) -> bool:
     """
     Returns True if the internal payment was found and is successful,
@@ -508,7 +571,7 @@ async def is_internal_status_success(
     return payment.status == PaymentState.SUCCESS.value
 
 
-async def mark_webhook_sent(payment_hash: str, status: int) -> None:
+async def mark_webhook_sent(payment_hash: str, status: str) -> None:
     await db.execute(
         """
         UPDATE apipayments SET webhook_status = :status
@@ -516,3 +579,14 @@ async def mark_webhook_sent(payment_hash: str, status: int) -> None:
         """,
         {"status": status, "hash": payment_hash},
     )
+
+
+async def _only_user_wallets_statement(
+    user_id: str, conn: Connection | None = None
+) -> str:
+    wallet_ids = await get_wallets_ids(user_id=user_id, conn=conn) or [
+        "no-wallets-for-user"
+    ]
+    # wallet ids are safe to use in sql queries
+    wallet_ids_str = [f"'{w}'" for w in wallet_ids]
+    return f""" wallet_id IN ({", ".join(wallet_ids_str)}) """

lnbits/core/crud/settings.py

@@ -1,5 +1,5 @@
 import json
-from typing import Any, Optional
+from typing import Any
 
 from loguru import logger
 
@@ -14,7 +14,7 @@ from lnbits.settings import (
 )
 
 
-async def get_super_settings() -> Optional[SuperSettings]:
+async def get_super_settings() -> SuperSettings | None:
     data = await get_settings_by_tag("core")
     if data:
         super_user = await get_settings_field("super_user")
@@ -24,7 +24,7 @@ async def get_super_settings() -> Optional[SuperSettings]:
     return None
 
 
-async def get_admin_settings(is_super_user: bool = False) -> Optional[AdminSettings]:
+async def get_admin_settings(is_super_user: bool = False) -> AdminSettings | None:
     sets = await get_super_settings()
     if not sets:
         return None
@@ -41,7 +41,7 @@ async def get_admin_settings(is_super_user: bool = False) -> Optional[AdminSetti
 
 
 async def update_admin_settings(
-    data: EditableSettings, tag: Optional[str] = "core"
+    data: EditableSettings, tag: str | None = "core"
 ) -> None:
     editable_settings = await get_settings_by_tag("core") or {}
     editable_settings.update(data.dict(exclude_unset=True))
@@ -56,12 +56,29 @@ async def update_admin_settings(
 async def update_super_user(super_user: str) -> SuperSettings:
     await set_settings_field("super_user", super_user)
     settings = await get_super_settings()
-    assert settings, "updated super_user settings could not be retrieved"
+    if not settings:
+        raise ValueError("updated super_user settings could not be retrieved")
     return settings
 
 
-async def delete_admin_settings(tag: Optional[str] = "core") -> None:
-    await db.execute("DELETE FROM settings WHERE tag = :tag", {"tag": tag})
+async def delete_admin_settings(tag: str | None = "core") -> None:
+    await db.execute(
+        "DELETE FROM system_settings WHERE tag = :tag",
+        {"tag": tag},
+    )
+
+
+async def reset_core_settings() -> None:
+    await db.execute(
+        """
+        DELETE FROM system_settings WHERE tag = 'core'
+        AND id NOT IN (
+            'super_user',
+            'lnbits_webpush_pubkey',
+            'lnbits_webpush_privkey'
+        )
+        """,
+    )
 
 
 async def create_admin_settings(super_user: str, new_settings: dict) -> SuperSettings:
@@ -70,13 +87,14 @@ async def create_admin_settings(super_user: str, new_settings: dict) -> SuperSet
         await set_settings_field(key, value)
 
     settings = await get_super_settings()
-    assert settings, "created admin settings could not be retrieved"
+    if not settings:
+        raise ValueError("created admin settings could not be retrieved")
     return settings
 
 
 async def get_settings_field(
-    id_: str, tag: Optional[str] = "core"
-) -> Optional[SettingsField]:
+    id_: str, tag: str | None = "core"
+) -> SettingsField | None:
 
     row: dict = await db.fetchone(
         """
@@ -87,12 +105,11 @@ async def get_settings_field(
     )
     if not row:
         return None
-    return SettingsField(id=row["id"], value=json.loads(row["value"]), tag=row["tag"])
+    value = json.loads(row["value"]) if row["value"] else None
+    return SettingsField(id=row["id"], value=value, tag=row["tag"])
 
 
-async def set_settings_field(
-    id_: str, value: Optional[Any], tag: Optional[str] = "core"
-):
+async def set_settings_field(id_: str, value: Any | None, tag: str | None = "core"):
     value = json.dumps(value) if value is not None else None
     await db.execute(
         """
@@ -104,7 +121,7 @@ async def set_settings_field(
     )
 
 
-async def get_settings_by_tag(tag: str) -> Optional[dict[str, Any]]:
+async def get_settings_by_tag(tag: str) -> dict[str, Any] | None:
     rows: list[dict] = await db.fetchall(
         "SELECT * FROM system_settings WHERE tag = :tag", {"tag": tag}
     )

lnbits/core/crud/tinyurl.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 import shortuuid
 
 from lnbits.core.db import db
@@ -19,7 +17,7 @@ async def create_tinyurl(domain: str, endless: bool, wallet: str):
     return await get_tinyurl(tinyurl_id)
 
 
-async def get_tinyurl(tinyurl_id: str) -> Optional[TinyURL]:
+async def get_tinyurl(tinyurl_id: str) -> TinyURL | None:
     return await db.fetchone(
         "SELECT * FROM tiny_url WHERE id = :tinyurl",
         {"tinyurl": tinyurl_id},

lnbits/core/crud/users.py

@@ -1,13 +1,20 @@
 from datetime import datetime, timezone
 from time import time
-from typing import Any, Optional
+from typing import Any
 from uuid import uuid4
 
 from lnbits.core.crud.extensions import get_user_active_extensions_ids
-from lnbits.core.crud.wallets import get_wallets
+from lnbits.core.crud.wallets import (
+    clear_wallet_cache,
+    create_wallet,
+    get_standalone_wallet,
+    get_wallets,
+)
 from lnbits.core.db import db
 from lnbits.core.models import UserAcls
 from lnbits.db import Connection, Filters, Page
+from lnbits.helpers import sha256s
+from lnbits.utils.cache import cache
 
 from ..models import (
     Account,
@@ -18,8 +25,8 @@ from ..models import (
 
 
 async def create_account(
-    account: Optional[Account] = None,
-    conn: Optional[Connection] = None,
+    account: Account | None = None,
+    conn: Connection | None = None,
 ) -> Account:
     if account:
         account.validate_fields()
@@ -30,36 +37,49 @@ async def create_account(
     return account
 
 
-async def update_account(account: Account) -> Account:
+async def get_accounts_count(conn: Connection | None = None) -> int:
+    row: dict | None = await (conn or db).fetchone(
+        "SELECT COUNT(*) as count FROM accounts"
+    )
+    return int(row["count"]) if row else 0
+
+
+async def update_account(account: Account, conn: Connection | None = None) -> Account:
     account.updated_at = datetime.now(timezone.utc)
-    await db.update("accounts", account)
+    await (conn or db).update("accounts", account)
     return account
 
 
-async def delete_account(user_id: str, conn: Optional[Connection] = None) -> None:
+async def delete_account(user_id: str, conn: Connection | None = None) -> None:
     await (conn or db).execute(
         "DELETE from accounts WHERE id = :user",
         {"user": user_id},
     )
+    await clear_user_id_cache(user_id)
 
 
 async def get_accounts(
-    filters: Optional[Filters[AccountFilters]] = None,
-    conn: Optional[Connection] = None,
+    filters: Filters[AccountFilters] | None = None,
+    conn: Connection | None = None,
 ) -> Page[AccountOverview]:
     where_clauses = []
     values: dict[str, Any] = {}
+    filters = filters or Filters()
 
-    # Make wallet filter explicit
-    wallet_filter = (
-        next((f for f in filters.filters if f.field == "wallet_id"), None)
-        if filters
-        else None
-    )
-    if filters and wallet_filter and wallet_filter.values:
-        where_clauses.append("wallets.id = :wallet_id")
-        values = {**values, "wallet_id": next(iter(wallet_filter.values.values()))}
-        filters.filters = [f for f in filters.filters if f.field != "wallet_id"]
+    wallet_filter = filters.get_filter_by_field("wallet_id")
+
+    if wallet_filter and wallet_filter.values:
+        wallet_id_value = next(iter(wallet_filter.values.values()), None)
+        wallet = (
+            await get_standalone_wallet(wallet_id_value, deleted=None, conn=conn)
+            if wallet_id_value
+            else None
+        )
+        if not wallet:
+            return Page(data=[], total=0)
+        where_clauses.append("accounts.id = :account_id")
+        values = {**values, "account_id": wallet.user}
+        filters.remove_filter_by_field("wallet_id")
 
     return await (conn or db).fetch_page(
         """
@@ -68,6 +88,8 @@ async def get_accounts(
             accounts.username,
             accounts.email,
             accounts.pubkey,
+            accounts.external_id,
+            accounts.activated,
             SUM(COALESCE((
                 SELECT balance FROM balances WHERE wallet_id = wallets.id
             ), 0)) as balance_msat,
@@ -88,27 +110,33 @@ async def get_accounts(
         filters=filters,
         model=AccountOverview,
         group_by=["accounts.id"],
+        table_name="accounts",
     )
 
 
 async def get_account(
-    user_id: str, conn: Optional[Connection] = None
-) -> Optional[Account]:
+    user_id: str, active_only: bool = True, conn: Connection | None = None
+) -> Account | None:
     if len(user_id) == 0:
         return None
+
     return await (conn or db).fetchone(
-        "SELECT * FROM accounts WHERE id = :id",
-        {"id": user_id},
+        """
+            SELECT * FROM accounts
+            WHERE id = :id AND (activated = true OR activated = :activated)
+        """,
+        {"id": user_id, "activated": active_only},
         Account,
     )
 
 
 async def delete_accounts_no_wallets(
     time_delta: int,
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ) -> None:
     delta = int(time()) - time_delta
     await (conn or db).execute(
+        # Timestamp placeholder is safe from SQL injection (not user input)
         f"""
         DELETE FROM accounts
         WHERE NOT EXISTS (
@@ -117,72 +145,108 @@ async def delete_accounts_no_wallets(
             (updated_at is null AND created_at < :delta)
             OR updated_at < {db.timestamp_placeholder("delta")}
         )
-        """,
+        """,  # noqa: S608
         {"delta": delta},
     )
 
 
 async def get_account_by_username(
-    username: str, conn: Optional[Connection] = None
-) -> Optional[Account]:
+    username: str, active_only: bool = True, conn: Connection | None = None
+) -> Account | None:
     if len(username) == 0:
         return None
+
     return await (conn or db).fetchone(
-        "SELECT * FROM accounts WHERE username = :username",
-        {"username": username},
+        """
+            SELECT * FROM accounts
+            WHERE
+                LOWER(username) = :username
+                AND (activated = true OR activated = :activated)
+        """,
+        {"username": username.lower(), "activated": active_only},
         Account,
     )
 
 
 async def get_account_by_pubkey(
-    pubkey: str, conn: Optional[Connection] = None
-) -> Optional[Account]:
+    pubkey: str, active_only: bool = True, conn: Connection | None = None
+) -> Account | None:
     return await (conn or db).fetchone(
-        "SELECT * FROM accounts WHERE pubkey = :pubkey",
-        {"pubkey": pubkey},
+        """
+            SELECT * FROM accounts
+            WHERE
+                LOWER(pubkey) = :pubkey
+                AND (activated = true OR activated = :activated)
+        """,
+        {"pubkey": pubkey.lower(), "activated": active_only},
         Account,
     )
 
 
 async def get_account_by_email(
-    email: str, conn: Optional[Connection] = None
-) -> Optional[Account]:
+    email: str, active_only: bool = True, conn: Connection | None = None
+) -> Account | None:
     if len(email) == 0:
         return None
+
     return await (conn or db).fetchone(
-        "SELECT * FROM accounts WHERE email = :email",
-        {"email": email},
+        """
+            SELECT * FROM accounts
+            WHERE
+                LOWER(email) = :email
+                AND (activated = true OR activated = :activated)
+        """,
+        {"email": email.lower(), "activated": active_only},
         Account,
     )
 
 
 async def get_account_by_username_or_email(
-    username_or_email: str, conn: Optional[Connection] = None
-) -> Optional[Account]:
+    username_or_email: str,
+    active_only: bool = True,
+    conn: Connection | None = None,
+) -> Account | None:
+
     return await (conn or db).fetchone(
-        "SELECT * FROM accounts WHERE email = :value or username = :value",
-        {"value": username_or_email},
+        """
+            SELECT * FROM accounts
+            WHERE
+                (LOWER(email) = :value or LOWER(username) = :value)
+                AND (activated = true OR activated = :activated)
+        """,
+        {"value": username_or_email.lower(), "activated": active_only},
         Account,
     )
 
 
-async def get_user(user_id: str, conn: Optional[Connection] = None) -> Optional[User]:
-    account = await get_account(user_id, conn)
-    if not account:
-        return None
-    return await get_user_from_account(account, conn)
+async def get_user(
+    user_id: str, active_only: bool = True, conn: Connection | None = None
+) -> User | None:
+    async with db.reuse_conn(conn) if conn else db.connect() as conn:
+        account = await get_account(user_id, active_only, conn=conn)
+        if not account:
+            return None
+        return await get_user_from_account(account, conn=conn)
 
 
 async def get_user_from_account(
-    account: Account, conn: Optional[Connection] = None
-) -> Optional[User]:
-    extensions = await get_user_active_extensions_ids(account.id, conn)
-    wallets = await get_wallets(account.id, False, conn=conn)
+    account: Account, conn: Connection | None = None
+) -> User | None:
+    async with db.reuse_conn(conn) if conn else db.connect() as conn:
+        extensions = await get_user_active_extensions_ids(account.id, conn=conn)
+        wallets = await get_wallets(account.id, deleted=False, conn=conn)
+
+        if len(wallets) == 0:
+            wallet = await create_wallet(user_id=account.id, conn=conn)
+            wallets.append(wallet)
+
     return User(
         id=account.id,
+        activated=account.activated,
         email=account.email,
         username=account.username,
         pubkey=account.pubkey,
+        external_id=account.external_id,
         extra=account.extra,
         created_at=account.created_at,
         updated_at=account.updated_at,
@@ -190,22 +254,45 @@ async def get_user_from_account(
         wallets=wallets,
         admin=account.is_admin,
         super_user=account.is_super_user,
+        fiat_providers=account.fiat_providers,
         has_password=account.password_hash is not None,
+        ui_customization=account.ui_customization or {},
     )
 
 
-async def update_user_access_control_list(user_acls: UserAcls):
+async def update_user_access_control_list(
+    user_acls: UserAcls, conn: Connection | None = None
+):
     user_acls.updated_at = datetime.now(timezone.utc)
-    await db.update("accounts", user_acls)
+    await (conn or db).update("accounts", user_acls)
 
 
 async def get_user_access_control_lists(
-    user_id: str, conn: Optional[Connection] = None
+    user_id: str, active_only: bool = True, conn: Connection | None = None
 ) -> UserAcls:
     user_acls = await (conn or db).fetchone(
-        "SELECT id, access_control_list FROM accounts WHERE id = :id",
-        {"id": user_id},
+        """
+            SELECT id, access_control_list FROM accounts
+            WHERE id = :user_id AND (activated = true OR activated = :activated)
+        """,
+        {"user_id": user_id, "activated": active_only},
         UserAcls,
     )
 
     return user_acls or UserAcls(id=user_id)
+
+
+async def clear_user_id_cache(user_id: str):
+    user = await get_user(user_id, active_only=True)
+    if user:
+        clear_user_cache(user)
+
+
+def clear_user_cache(user: User):
+    user_cache_key: str | None = cache.pop(
+        f"auth:user:cache_key:{sha256s(user.id)}", None
+    )
+    if user_cache_key:
+        cache.pop(user_cache_key)
+    for wallet in user.wallets:
+        clear_wallet_cache(wallet)

lnbits/core/crud/wallets.py

@@ -1,11 +1,12 @@
 from datetime import datetime, timezone
 from time import time
-from typing import Optional
 from uuid import uuid4
 
 from lnbits.core.db import db
-from lnbits.db import Connection
+from lnbits.core.models.wallets import BaseWallet, WalletsFilters, WalletType
+from lnbits.db import Connection, Filters, Page
 from lnbits.settings import settings
+from lnbits.utils.cache import cache
 
 from ..models import Wallet
 
@@ -13,52 +14,58 @@ from ..models import Wallet
 async def create_wallet(
     *,
     user_id: str,
-    wallet_name: Optional[str] = None,
-    conn: Optional[Connection] = None,
+    wallet_name: str | None = None,
+    wallet_type: WalletType = WalletType.LIGHTNING,
+    shared_wallet_id: str | None = None,
+    conn: Connection | None = None,
 ) -> Wallet:
     wallet_id = uuid4().hex
     wallet = Wallet(
         id=wallet_id,
         name=wallet_name or settings.lnbits_default_wallet_name,
+        wallet_type=wallet_type.value,
+        shared_wallet_id=shared_wallet_id,
         user=user_id,
         adminkey=uuid4().hex,
         inkey=uuid4().hex,
         currency=settings.lnbits_default_accounting_currency or "USD",
     )
+
     await (conn or db).insert("wallets", wallet)
     return wallet
 
 
 async def update_wallet(
     wallet: Wallet,
-    conn: Optional[Connection] = None,
-) -> Optional[Wallet]:
+    conn: Connection | None = None,
+) -> Wallet:
     wallet.updated_at = datetime.now(timezone.utc)
     await (conn or db).update("wallets", wallet)
     return wallet
 
 
 async def delete_wallet(
-    *,
     user_id: str,
     wallet_id: str,
     deleted: bool = True,
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ) -> None:
+    clear_wallet_id_cache(wallet_id)
     now = int(time())
+
     await (conn or db).execute(
+        # Timestamp placeholder is safe from SQL injection (not user input)
         f"""
         UPDATE wallets
         SET deleted = :deleted, updated_at = {db.timestamp_placeholder('now')}
         WHERE id = :wallet AND "user" = :user
-        """,
+        """,  # noqa: S608
         {"wallet": wallet_id, "user": user_id, "deleted": deleted, "now": now},
     )
 
 
-async def force_delete_wallet(
-    wallet_id: str, conn: Optional[Connection] = None
-) -> None:
+async def force_delete_wallet(wallet_id: str, conn: Connection | None = None) -> None:
+    clear_wallet_id_cache(wallet_id)
     await (conn or db).execute(
         "DELETE FROM wallets WHERE id = :wallet",
         {"wallet": wallet_id},
@@ -66,27 +73,29 @@ async def force_delete_wallet(
 
 
 async def delete_wallet_by_id(
-    wallet_id: str, conn: Optional[Connection] = None
-) -> Optional[int]:
+    wallet_id: str, conn: Connection | None = None
+) -> int | None:
+    clear_wallet_id_cache(wallet_id)
     now = int(time())
     result = await (conn or db).execute(
+        # Timestamp placeholder is safe from SQL injection (not user input)
         f"""
         UPDATE wallets
         SET deleted = true, updated_at = {db.timestamp_placeholder('now')}
         WHERE id = :wallet
-        """,
+        """,  # noqa: S608
         {"wallet": wallet_id, "now": now},
     )
     return result.rowcount
 
 
-async def remove_deleted_wallets(conn: Optional[Connection] = None) -> None:
+async def remove_deleted_wallets(conn: Connection | None = None) -> None:
     await (conn or db).execute("DELETE FROM wallets WHERE deleted = true")
 
 
 async def delete_unused_wallets(
     time_delta: int,
-    conn: Optional[Connection] = None,
+    conn: Connection | None = None,
 ) -> None:
     delta = int(time()) - time_delta
     await (conn or db).execute(
@@ -103,37 +112,107 @@ async def delete_unused_wallets(
     )
 
 
-async def get_wallet(
-    wallet_id: str, deleted: Optional[bool] = None, conn: Optional[Connection] = None
-) -> Optional[Wallet]:
-    where = "AND deleted = :deleted" if deleted is not None else ""
+async def get_standalone_wallet(
+    wallet_id: str, deleted: bool | None = False, conn: Connection | None = None
+) -> Wallet | None:
+    query = """
+            SELECT *, COALESCE((
+                SELECT balance FROM balances WHERE wallet_id = wallets.id
+            ), 0) AS balance_msat FROM wallets
+            WHERE id = :wallet
+            """
+    if deleted is not None:
+        query += " AND deleted = :deleted "
     return await (conn or db).fetchone(
-        f"""
-        SELECT *, COALESCE((
-            SELECT balance FROM balances WHERE wallet_id = wallets.id
-        ), 0) AS balance_msat FROM wallets
-        WHERE id = :wallet {where}
-        """,
+        query,
         {"wallet": wallet_id, "deleted": deleted},
         Wallet,
     )
 
 
+async def get_wallet(
+    wallet_id: str, deleted: bool | None = False, conn: Connection | None = None
+) -> Wallet | None:
+    wallet = await get_standalone_wallet(wallet_id, deleted, conn)
+    if not wallet:
+        return None
+    if wallet.is_lightning_shared_wallet:
+        return await get_source_wallet(wallet, conn)
+
+    return wallet
+
+
 async def get_wallets(
-    user_id: str, deleted: Optional[bool] = None, conn: Optional[Connection] = None
+    user_id: str,
+    deleted: bool | None = False,
+    wallet_type: WalletType | None = None,
+    conn: Connection | None = None,
 ) -> list[Wallet]:
-    where = "AND deleted = :deleted" if deleted is not None else ""
-    return await (conn or db).fetchall(
-        f"""
-        SELECT *, COALESCE((
-            SELECT balance FROM balances WHERE wallet_id = wallets.id
-        ), 0) AS balance_msat FROM wallets
-        WHERE "user" = :user {where}
+    query = """
+            SELECT *, COALESCE((
+                SELECT balance FROM balances WHERE wallet_id = wallets.id
+            ), 0) AS balance_msat FROM wallets
+            WHERE "user" = :user
+            """
+    if deleted is not None:
+        query += " AND deleted = :deleted "
+    if wallet_type is not None:
+        query += " AND wallet_type = :wallet_type "
+    wallets = await (conn or db).fetchall(
+        query,
+        {
+            "user": user_id,
+            "deleted": deleted,
+            "wallet_type": wallet_type.value if wallet_type else None,
+        },
+        Wallet,
+    )
+
+    return await get_source_wallets(wallets, conn)
+
+
+async def get_wallets_paginated(
+    user_id: str,
+    deleted: bool | None = None,
+    filters: Filters[WalletsFilters] | None = None,
+    conn: Connection | None = None,
+) -> Page[Wallet]:
+    if deleted is None:
+        deleted = False
+
+    where: list[str] = [""" "user" = :user AND deleted = :deleted """]
+    wallets = await (conn or db).fetch_page(
+        """
+            SELECT *, COALESCE((
+                SELECT balance FROM balances WHERE wallet_id = wallets.id
+            ), 0) AS balance_msat FROM wallets
         """,
+        where=where,
+        values={"user": user_id, "deleted": deleted},
+        filters=filters,
+        model=Wallet,
+        table_name="wallets",
+    )
+
+    wallets.data = await get_source_wallets(wallets.data, conn)
+    return wallets
+
+
+async def get_wallets_ids(
+    user_id: str, deleted: bool | None = False, conn: Connection | None = None
+) -> list[str]:
+    query = """SELECT * FROM wallets WHERE "user" = :user"""
+    if deleted is not None:
+        query += " AND deleted = :deleted "
+    wallets = await (conn or db).fetchall(
+        query,
         {"user": user_id, "deleted": deleted},
         Wallet,
     )
 
+    wallets = await get_source_wallets(wallets, conn)
+    return [w.source_wallet_id for w in wallets if w.can_view_payments]
+
 
 async def get_wallets_count():
     result = await db.execute("SELECT COUNT(*) as count FROM wallets")
@@ -143,22 +222,92 @@ async def get_wallets_count():
 
 async def get_wallet_for_key(
     key: str,
-    conn: Optional[Connection] = None,
-) -> Optional[Wallet]:
-    return await (conn or db).fetchone(
+    conn: Connection | None = None,
+) -> Wallet | None:
+    wallet = await (conn or db).fetchone(
         """
-        SELECT *, COALESCE((
+        SELECT wallets.*, COALESCE((
             SELECT balance FROM balances WHERE wallet_id = wallets.id
         ), 0)
         AS balance_msat FROM wallets
-        WHERE (adminkey = :key OR inkey = :key) AND deleted = false
+        INNER JOIN accounts ON wallets.user = accounts.id
+        WHERE (adminkey = :key OR inkey = :key)
+            AND deleted = false
+            AND accounts.activated = true
         """,
         {"key": key},
         Wallet,
     )
+    if not wallet:
+        return None
+
+    if wallet.is_lightning_shared_wallet:
+        mw = await get_source_wallet(wallet, conn)
+        return mw
+    return wallet
 
 
-async def get_total_balance(conn: Optional[Connection] = None):
+async def get_base_wallet_for_key(
+    key: str,
+    conn: Connection | None = None,
+) -> BaseWallet | None:
+    wallet = await (conn or db).fetchone(
+        """
+        SELECT wallets.id, "user", wallet_type, adminkey, inkey FROM wallets
+        INNER JOIN accounts ON wallets.user = accounts.id
+        WHERE (adminkey = :key OR inkey = :key)
+            AND deleted = false
+            AND accounts.activated = true
+        """,
+        {"key": key},
+        BaseWallet,
+    )
+    if not wallet:
+        return None
+
+    return wallet
+
+
+async def get_source_wallet(
+    wallet: Wallet, conn: Connection | None = None
+) -> Wallet | None:
+    if not wallet.is_lightning_shared_wallet:
+        return wallet
+    if not wallet.shared_wallet_id:
+        return None
+
+    shared_wallet = await get_standalone_wallet(wallet.shared_wallet_id, False, conn)
+    if not shared_wallet:
+        return None
+    wallet.mirror_shared_wallet(shared_wallet)
+    return wallet
+
+
+async def get_source_wallets(
+    wallet: list[Wallet], conn: Connection | None = None
+) -> list[Wallet]:
+    source_wallets = []
+    for w in wallet:
+        source_wallet = await get_source_wallet(w, conn)
+        if source_wallet:
+            source_wallets.append(source_wallet)
+    return source_wallets
+
+
+async def get_total_balance(conn: Connection | None = None):
     result = await (conn or db).execute("SELECT SUM(balance) as balance FROM balances")
     row = result.mappings().first()
     return row.get("balance", 0) or 0
+
+
+def clear_wallet_id_cache(wallet_id: str):
+    cached_wallet: BaseWallet | None = cache.pop(f"auth:wallet:{wallet_id}")
+    if cached_wallet:
+        cache.pop(f"auth:x-api-key:{cached_wallet.adminkey}")
+        cache.pop(f"auth:x-api-key:{cached_wallet.inkey}")
+
+
+def clear_wallet_cache(wallet: Wallet):
+    cache.pop(f"auth:wallet:{wallet.id}")
+    cache.pop(f"auth:x-api-key:{wallet.adminkey}")
+    cache.pop(f"auth:x-api-key:{wallet.inkey}")

lnbits/core/crud/webpush.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 from lnbits.core.db import db
 
 from ..models import WebPushSubscription
@@ -7,7 +5,7 @@ from ..models import WebPushSubscription
 
 async def get_webpush_subscription(
     endpoint: str, user: str
-) -> Optional[WebPushSubscription]:
+) -> WebPushSubscription | None:
     return await db.fetchone(
         """
         SELECT * FROM webpush_subscriptions
@@ -37,7 +35,8 @@ async def create_webpush_subscription(
         {"endpoint": endpoint, "user": user, "data": data, "host": host},
     )
     subscription = await get_webpush_subscription(endpoint, user)
-    assert subscription, "Newly created webpush subscription couldn't be retrieved"
+    if not subscription:
+        raise ValueError("Newly created webpush subscription couldn't be retrieved")
     return subscription
 
 

lnbits/core/extensions/__init__.py

@@ -0,0 +1,28 @@
+"""Extension runtime contracts."""
+
+from .api import (
+    ExtensionAPI,
+    ExtensionAPIMethod,
+    extension_api_contract,
+    extension_api_method,
+    get_extension_api_method,
+    list_extension_api_methods,
+)
+from .loader import WasmExtension, load_wasm_extension
+from .routes import register_wasm_extension
+from .runtime import ExtensionAPIHost
+from .wasm import invoke_wasm_extension_export
+
+__all__ = [
+    "ExtensionAPI",
+    "ExtensionAPIHost",
+    "ExtensionAPIMethod",
+    "WasmExtension",
+    "extension_api_contract",
+    "extension_api_method",
+    "get_extension_api_method",
+    "invoke_wasm_extension_export",
+    "list_extension_api_methods",
+    "load_wasm_extension",
+    "register_wasm_extension",
+]

lnbits/core/extensions/api.py

@@ -0,0 +1,777 @@
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+import secrets
+import time
+from collections.abc import Awaitable, Callable, Iterable, Mapping
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, TypeVar, cast, get_type_hints
+
+from pydantic import BaseModel
+
+from lnbits.helpers import sha256s
+
+from .models import (
+    CreateInvoicePublicRequest,
+    CreateInvoiceRequest,
+    CreateInvoiceResponse,
+    EmptyRequest,
+    ExtensionApiRequest,
+    HttpRequest,
+    HttpResponse,
+    ListUserWalletsResponse,
+    LogRequest,
+    LogResponse,
+    NowResponse,
+    PayInvoiceRequest,
+    PayInvoiceResponse,
+    RandomIdRequest,
+    RandomIdResponse,
+    StorageDeleteRequest,
+    StorageDeleteResponse,
+    StorageGetRequest,
+    StorageGetResponse,
+    StoragePaginatedRequest,
+    StoragePaginatedResponse,
+    StorageSetRequest,
+    StorageSetResponse,
+    UserWalletSummary,
+    WalletBalanceRequest,
+    WalletBalanceResponse,
+)
+from .storage import (
+    storage_delete_row,
+    storage_get_paginated_rows,
+    storage_get_public_row,
+    storage_get_row,
+    storage_set_row,
+)
+
+logger = logging.getLogger("lnbits.extensions")
+
+_EXTENSION_API_METHOD_ATTR = "__lnbits_extension_api_method__"
+_EXTENSION_RUNTIME_PERMISSION_IDS = {"ui.camera.scan_qr"}
+_RequestModel = TypeVar("_RequestModel", bound=BaseModel)
+_ResponseModel = TypeVar("_ResponseModel", bound=BaseModel)
+
+
+@dataclass(frozen=True)
+class ExtensionAPIMethodExport:
+    method_id: str
+    namespace: str
+    name: str
+    host_interface: str
+    host_name: str
+    sdk_name: str
+    description: str
+    required_permission: str | None = None
+    require_auth: bool = True
+
+
+@dataclass(frozen=True)
+class ExtensionAPIMethod:
+    method_id: str
+    namespace: str
+    name: str
+    python_name: str
+    host_interface: str
+    host_name: str
+    sdk_name: str
+    description: str
+    request_model: type[BaseModel]
+    response_model: type[BaseModel]
+    required_permission: str | None = None
+    require_auth: bool = True
+
+    @property
+    def sdk_qualified_name(self) -> str:
+        return f"{self.namespace}.{self.sdk_name}"
+
+
+def extension_api_method(
+    *,
+    method_id: str,
+    namespace: str,
+    name: str,
+    host_name: str,
+    sdk_name: str,
+    description: str,
+    host_interface: str = "host",
+    required_permission: str | None = None,
+    require_auth: bool = True,
+) -> Callable[
+    [Callable[[Any, _RequestModel], Awaitable[_ResponseModel]]],
+    Callable[[Any, _RequestModel], Awaitable[_ResponseModel]],
+]:
+    export = ExtensionAPIMethodExport(
+        method_id=method_id,
+        namespace=namespace,
+        name=name,
+        host_interface=host_interface,
+        host_name=host_name,
+        sdk_name=sdk_name,
+        description=description,
+        required_permission=required_permission,
+        require_auth=require_auth,
+    )
+
+    def decorator(
+        function: Callable[[Any, _RequestModel], Awaitable[_ResponseModel]],
+    ) -> Callable[[Any, _RequestModel], Awaitable[_ResponseModel]]:
+        @wraps(function)
+        async def wrapper(self: Any, request: _RequestModel) -> _ResponseModel:
+            api = getattr(self, "api", self)
+            if require_auth and not api.has_authenticated_context():
+                raise PermissionError(
+                    f"Extension API method '{method_id}' requires authentication."
+                )
+            api.require_permission(required_permission)
+            return await function(self, request)
+
+        setattr(wrapper, _EXTENSION_API_METHOD_ATTR, export)
+        return wrapper
+
+    return decorator
+
+
+class ExtensionAPI:
+    def __init__(
+        self,
+        extension_id: str,
+        permissions: Iterable[Any],
+        *,
+        user_id: str | None = None,
+        access_token: str | None = None,
+        context: str = "user",
+        owner_id: str | None = None,
+    ) -> None:
+        self.extension_id = extension_id
+        self.permissions, self.permission_policies = self._permission_data(permissions)
+        self.user_id = user_id
+        self.access_token = access_token
+        self.context = context
+        self.owner_id = sha256s(user_id) if user_id else owner_id
+        self._uuid = secrets.token_urlsafe(12).replace("-", "_")
+        from .api_utils import ExtensionAPIUtils
+
+        self.utils = ExtensionAPIUtils(self)
+
+    def __repr__(self) -> str:
+        return (
+            "ExtensionAPI("
+            f"extension_id={self.extension_id!r}, "
+            f"context={self.context!r}, "
+            f"_uuid={self._uuid!r}"
+            ")"
+        )
+
+    def require_permission(self, permission: str | None) -> None:
+        if permission and permission not in self.permissions:
+            raise PermissionError(
+                f"Extension '{self.extension_id}' is missing permission '{permission}'."
+            )
+
+    def has_authenticated_context(self) -> bool:
+        return bool(self.user_id) or self.context == "event"
+
+    def _require_owner_id(self) -> str:
+        if not self.owner_id:
+            raise PermissionError("Extension API method requires an owner context.")
+        return self.owner_id
+
+    @extension_api_method(
+        method_id="storage.get",
+        namespace="storage",
+        name="Get storage row",
+        host_name="storage_get",
+        sdk_name="get",
+        description="Read one row from an extension storage table.",
+        required_permission="ext.storage.read",
+        require_auth=True,
+    )
+    async def storage_get(self, request: StorageGetRequest) -> StorageGetResponse:
+        row = await storage_get_row(
+            self.extension_id,
+            request.table,
+            request.id,
+            self._require_owner_id(),
+        )
+        return StorageGetResponse(data_json=json.dumps(row) if row else None)
+
+    @extension_api_method(
+        method_id="storage.get_public",
+        namespace="storage",
+        name="Get public storage row",
+        host_name="storage_get_public",
+        sdk_name="getPublic",
+        description="Read one public row from an extension storage table.",
+        required_permission="ext.storage.read_public",
+        require_auth=False,
+    )
+    async def storage_get_public(
+        self, request: StorageGetRequest
+    ) -> StorageGetResponse:
+        public_fields = self._public_storage_fields(request.table)
+        row = await storage_get_public_row(self.extension_id, request.table, request.id)
+        if not row:
+            return StorageGetResponse()
+        public_row = {
+            field_name: value
+            for field_name, value in row.items()
+            if field_name in public_fields
+        }
+        return StorageGetResponse(data_json=json.dumps(public_row))
+
+    @extension_api_method(
+        method_id="storage.set",
+        namespace="storage",
+        name="Set storage row",
+        host_name="storage_set",
+        sdk_name="set",
+        description="Create or update one row in an extension storage table.",
+        required_permission="ext.storage.write",
+        require_auth=True,
+    )
+    async def storage_set(self, request: StorageSetRequest) -> StorageSetResponse:
+        await storage_set_row(
+            self.extension_id,
+            request.table,
+            request.data,
+            self._require_owner_id(),
+        )
+        return StorageSetResponse()
+
+    @extension_api_method(
+        method_id="storage.get_paginated",
+        namespace="storage",
+        name="Get paginated storage rows",
+        host_name="storage_get_paginated",
+        sdk_name="getPaginated",
+        description="Get filtered, searched, sorted, paginated storage rows.",
+        required_permission="ext.storage.read",
+        require_auth=True,
+    )
+    async def storage_get_paginated(
+        self, request: StoragePaginatedRequest
+    ) -> StoragePaginatedResponse:
+        page = await storage_get_paginated_rows(
+            self.extension_id,
+            request.table,
+            request.filters,
+            owner_id=self._require_owner_id(),
+            search=request.search,
+            search_fields=request.search_fields,
+            sort_by=request.sort_by,
+            descending=request.descending,
+            limit=request.limit,
+            offset=request.offset,
+        )
+        return StoragePaginatedResponse(
+            rows_json=json.dumps(page["data"]),
+            total=page["total"],
+        )
+
+    @extension_api_method(
+        method_id="storage.delete",
+        namespace="storage",
+        name="Delete storage row",
+        host_name="storage_delete",
+        sdk_name="delete",
+        description="Delete one row from an extension storage table.",
+        required_permission="ext.storage.write",
+        require_auth=True,
+    )
+    async def storage_delete(
+        self, request: StorageDeleteRequest
+    ) -> StorageDeleteResponse:
+        await storage_delete_row(
+            self.extension_id,
+            request.table,
+            request.id,
+            self._require_owner_id(),
+        )
+        return StorageDeleteResponse()
+
+    @extension_api_method(
+        method_id="wallet.create_invoice",
+        namespace="wallet",
+        name="Create invoice",
+        host_name="create_invoice",
+        sdk_name="createInvoice",
+        description="Create an incoming Lightning invoice for an allowed wallet.",
+        required_permission="wallet.create_invoice",
+        require_auth=True,
+    )
+    async def wallet_create_invoice(
+        self, request: CreateInvoiceRequest
+    ) -> CreateInvoiceResponse:
+        from lnbits.core.crud.wallets import get_wallet
+        from lnbits.core.models.payments import CreateInvoice
+        from lnbits.core.services.payments import create_payment_request
+
+        if self.user_id:
+            wallet = await get_wallet(request.wallet_id)
+            if wallet is None or wallet.user != self.user_id:
+                raise PermissionError(
+                    "Creating an invoice for this wallet requires an "
+                    "authenticated user context."
+                )
+        else:
+            pass
+            # todo: security stuff here
+
+        payment = await create_payment_request(
+            request.wallet_id,
+            CreateInvoice(
+                amount=request.amount,
+                unit=request.currency,
+                memo=request.memo,
+                extra=request.extra,
+                extension=self.extension_id,
+            ),
+        )
+        return CreateInvoiceResponse(
+            payment_hash=payment.payment_hash,
+            payment_request=payment.payment_request or payment.bolt11,
+            checking_id=payment.checking_id,
+        )
+
+    @extension_api_method(
+        method_id="wallet.create_invoice_public",
+        namespace="wallet",
+        name="Create public invoice",
+        host_name="create_invoice_public",
+        sdk_name="createInvoicePublic",
+        description="Create a public incoming Lightning invoice.",
+        required_permission="wallet.create_invoice_public",
+        require_auth=False,
+    )
+    async def wallet_create_invoice_public(
+        self, request: CreateInvoicePublicRequest
+    ) -> CreateInvoiceResponse:
+        from lnbits.core.models.payments import CreateInvoice
+        from lnbits.core.services.payments import create_payment_request
+
+        table, wallet_field = self._public_invoice_wallet_source()
+        row = await storage_get_public_row(self.extension_id, table, request.source_id)
+        if not row:
+            raise PermissionError("Public invoice source was not found.")
+
+        wallet_id = row.get(wallet_field)
+        if not isinstance(wallet_id, str) or not wallet_id:
+            raise PermissionError("Public invoice source has no valid wallet.")
+
+        payment = await create_payment_request(
+            wallet_id,
+            CreateInvoice(
+                amount=request.amount,
+                unit=request.currency,
+                memo=request.memo,
+                extra={
+                    "tag": self.extension_id,
+                    "source_id": request.source_id,
+                    f"extra_{self.extension_id}": request.extra,
+                },
+                extension=self.extension_id,
+            ),
+        )
+        return CreateInvoiceResponse(
+            payment_hash=payment.payment_hash,
+            payment_request=payment.payment_request or payment.bolt11,
+            checking_id=payment.checking_id,
+        )
+
+    @extension_api_method(
+        method_id="wallet.list_user_wallets",
+        namespace="wallet",
+        name="List user wallets",
+        host_name="list_user_wallets",
+        sdk_name="listUserWallets",
+        description="List wallets available to the authenticated extension user.",
+        required_permission="wallet.list",
+    )
+    async def wallet_list_user_wallets(
+        self, request: EmptyRequest
+    ) -> ListUserWalletsResponse:
+        if not self.user_id:
+            raise PermissionError(
+                "Listing user wallets requires an authenticated user context."
+            )
+
+        from lnbits.core.crud.wallets import get_wallets
+
+        user_wallets = await get_wallets(self.user_id)
+        if user_wallets is None:
+            raise PermissionError(
+                "Listing user wallets requires an authenticated user context."
+            )
+        return ListUserWalletsResponse(
+            wallets=[
+                UserWalletSummary(id=w.id, name=w.name, currency=w.currency)
+                for w in user_wallets
+            ]
+        )
+
+    @extension_api_method(
+        method_id="wallet.balance",
+        namespace="wallet",
+        name="Read wallet balance",
+        host_name="wallet_balance",
+        sdk_name="balance",
+        description="Read the balance of a wallet available to the user.",
+        required_permission="wallet.balance.read",
+    )
+    async def wallet_balance(
+        self, request: WalletBalanceRequest
+    ) -> WalletBalanceResponse:
+        from lnbits.core.crud.wallets import get_wallet
+
+        if not self.user_id:
+            raise PermissionError(
+                "Reading a wallet balance requires an authenticated user context."
+            )
+
+        wallet = await get_wallet(request.wallet_id)
+        if wallet is None or wallet.user != self.user_id:
+            raise PermissionError("Reading this wallet balance is not allowed.")
+
+        withdrawable_msat = max(wallet.withdrawable_balance, 0)
+        fee_reserve_msat = max(wallet.balance_msat - withdrawable_msat, 0)
+        return WalletBalanceResponse(
+            wallet_id=wallet.id,
+            name=wallet.name,
+            currency=wallet.currency,
+            balance_msat=wallet.balance_msat,
+            balance_sat=wallet.balance,
+            withdrawable_msat=withdrawable_msat,
+            withdrawable_sat=withdrawable_msat // 1000,
+            fee_reserve_msat=fee_reserve_msat,
+            fee_reserve_sat=fee_reserve_msat // 1000,
+            can_send_payments=wallet.can_send_payments,
+        )
+
+    @extension_api_method(
+        method_id="wallet.pay_invoice",
+        namespace="wallet",
+        name="Pay invoice",
+        host_name="pay_invoice",
+        sdk_name="payInvoice",
+        description="Pay a Lightning invoice from a wallet available to the user.",
+        required_permission="wallet.pay_invoice",
+    )
+    async def wallet_pay_invoice(
+        self, request: PayInvoiceRequest
+    ) -> PayInvoiceResponse:
+        from lnbits.core.crud.wallets import get_wallet
+        from lnbits.core.services.payments import pay_invoice
+        from lnbits.exceptions import PaymentError
+
+        if not self.user_id:
+            raise PermissionError(
+                "Paying an invoice requires an authenticated user context."
+            )
+
+        wallet = await get_wallet(request.wallet_id)
+        if wallet is None or wallet.user != self.user_id:
+            raise PermissionError("Paying invoices from this wallet is not allowed.")
+
+        try:
+            payment = await pay_invoice(
+                wallet_id=request.wallet_id,
+                payment_request=request.payment_request,
+                max_sat=request.max_sat,
+                extra={"tag": self.extension_id, **request.extra},
+                description=request.description,
+                tag=self.extension_id,
+            )
+        except (PaymentError, ValueError) as exc:
+            return PayInvoiceResponse(ok=False, error=str(exc))
+
+        return PayInvoiceResponse(
+            ok=True,
+            checking_id=payment.checking_id,
+            payment_hash=payment.payment_hash,
+            status=payment.status,
+            amount_msat=abs(payment.amount),
+            fee_msat=abs(payment.fee),
+            pending=payment.pending,
+            success=payment.success,
+        )
+
+    @extension_api_method(
+        method_id="http.request",
+        namespace="http",
+        name="HTTP request",
+        host_name="http_request",
+        sdk_name="request",
+        description="Make an outbound HTTP request to an allowed host.",
+        required_permission="http.request",
+        require_auth=True,
+    )
+    async def http_request(self, request: HttpRequest) -> HttpResponse:
+        from .http_client import send_extension_http_request
+
+        policy = self.permission_policies.get("http.request") or {}
+        return await send_extension_http_request(self.extension_id, policy, request)
+
+    @extension_api_method(
+        method_id="extension.api.request",
+        namespace="extension",
+        name="Extension API request",
+        host_name="extension_api_request",
+        sdk_name="request",
+        description="Call an allowed installed extension API.",
+        required_permission="extension.api.request",
+        require_auth=True,
+    )
+    async def extension_api_request(self, request: ExtensionApiRequest) -> HttpResponse:
+        from .extension_client import send_extension_api_request
+
+        policy = self.permission_policies.get("extension.api.request") or {}
+        return await send_extension_api_request(
+            self.extension_id,
+            policy,
+            self.user_id,
+            self.access_token,
+            request,
+        )
+
+    @extension_api_method(
+        method_id="system.random_id",
+        namespace="system",
+        name="Random ID",
+        host_name="random_id",
+        sdk_name="id",
+        description="Create a random extension-local identifier.",
+        require_auth=False,
+    )
+    async def system_random_id(self, request: RandomIdRequest) -> RandomIdResponse:
+        return RandomIdResponse(
+            id=f"{request.prefix}_{secrets.token_urlsafe(12).replace('-', '_')}"
+        )
+
+    @extension_api_method(
+        method_id="system.now",
+        namespace="system",
+        name="Current timestamp",
+        host_name="now",
+        sdk_name="now",
+        description="Return the current Unix timestamp.",
+        require_auth=False,
+    )
+    async def system_now(self, request: EmptyRequest) -> NowResponse:
+        return NowResponse(timestamp=int(time.time()))
+
+    @extension_api_method(
+        method_id="system.log",
+        namespace="system",
+        name="Log message",
+        host_name="log",
+        sdk_name="log",
+        description="Write a bounded message to the extension log.",
+        require_auth=False,
+    )
+    async def system_log(self, request: LogRequest) -> LogResponse:
+        log = getattr(logger, request.level)
+        log("extension:%s %s", self.extension_id, request.message)
+        return LogResponse()
+
+    @staticmethod
+    def _permission_data(
+        permissions: Iterable[Any],
+    ) -> tuple[set[str], dict[str, dict[str, Any]]]:
+        permission_ids: set[str] = set()
+        policies: dict[str, dict[str, Any]] = {}
+
+        for permission in permissions:
+            if isinstance(permission, str):
+                permission_ids.add(permission)
+                continue
+
+            permission_id: str | None = None
+            policy: Any = None
+            if isinstance(permission, Mapping):
+                permission_id = permission.get("id")  # type: ignore[assignment]
+                policy = permission.get("policy")
+            else:
+                permission_id = getattr(permission, "id", None)
+                policy = getattr(permission, "policy", None)
+
+            if not permission_id:
+                continue
+            permission_ids.add(permission_id)
+            if isinstance(policy, dict):
+                policies[permission_id] = policy
+
+        return permission_ids, policies
+
+    def _public_storage_fields(self, table: str) -> set[str]:
+        policy = self.permission_policies.get("ext.storage.read_public") or {}
+        tables = policy.get("tables")
+        if not isinstance(tables, list):
+            raise PermissionError(
+                "Public storage reads require a tables policy for "
+                "'ext.storage.read_public'."
+            )
+
+        for table_policy in tables:
+            if not isinstance(table_policy, dict):
+                continue
+            if table_policy.get("table_name") != table:
+                continue
+            public_fields = table_policy.get("public_fields")
+            if not isinstance(public_fields, list) or not all(
+                isinstance(field, str) and field for field in public_fields
+            ):
+                raise PermissionError(
+                    f"Public storage table '{table}' has no valid public fields."
+                )
+            return set(public_fields)
+
+        raise PermissionError(f"Storage table '{table}' is not publicly readable.")
+
+    def _public_invoice_wallet_source(self) -> tuple[str, str]:
+        policy = self.permission_policies.get("wallet.create_invoice_public") or {}
+        table = policy.get("table")
+        wallet_field = policy.get("wallet_field")
+        if not isinstance(table, str) or not table:
+            raise PermissionError(
+                "Public invoice creation requires a storage table policy."
+            )
+        if not isinstance(wallet_field, str) or not wallet_field:
+            raise PermissionError(
+                "Public invoice creation requires a wallet field policy."
+            )
+        return table, wallet_field
+
+
+def list_extension_api_methods(
+    api_cls: type[ExtensionAPI] = ExtensionAPI,
+) -> list[ExtensionAPIMethod]:
+    methods: list[ExtensionAPIMethod] = []
+
+    for prefix, method_cls in _extension_api_method_sources(api_cls):
+        for python_name, function in inspect.getmembers(method_cls, inspect.isfunction):
+            export = getattr(function, _EXTENSION_API_METHOD_ATTR, None)
+            if not export:
+                continue
+
+            request_model, response_model = _get_method_models(function)
+            methods.append(
+                ExtensionAPIMethod(
+                    method_id=export.method_id,
+                    namespace=export.namespace,
+                    name=export.name,
+                    python_name=f"{prefix}.{python_name}" if prefix else python_name,
+                    host_interface=export.host_interface,
+                    host_name=export.host_name,
+                    sdk_name=export.sdk_name,
+                    description=export.description,
+                    request_model=request_model,
+                    response_model=response_model,
+                    required_permission=export.required_permission,
+                    require_auth=export.require_auth,
+                )
+            )
+
+    return sorted(methods, key=lambda method: method.method_id)
+
+
+def _extension_api_method_sources(
+    api_cls: type[ExtensionAPI],
+) -> list[tuple[str, type[Any]]]:
+    sources: list[tuple[str, type[Any]]] = [("", api_cls)]
+    if issubclass(api_cls, ExtensionAPI):
+        from .api_utils import extension_api_utils_method_classes
+
+        sources.extend(extension_api_utils_method_classes().items())
+    return sources
+
+
+def extension_api_permission_ids(
+    api_cls: type[ExtensionAPI] = ExtensionAPI,
+) -> set[str]:
+    permissions = {
+        method.required_permission
+        for method in list_extension_api_methods(api_cls)
+        if method.required_permission
+    }
+    permissions.update(_EXTENSION_RUNTIME_PERMISSION_IDS)
+    return permissions
+
+
+def get_extension_api_method(
+    method_id: str,
+    api_cls: type[ExtensionAPI] = ExtensionAPI,
+) -> ExtensionAPIMethod:
+    for method in list_extension_api_methods(api_cls):
+        if method.method_id == method_id:
+            return method
+    raise KeyError(f"Unknown extension API method '{method_id}'.")
+
+
+def extension_api_contract(
+    api_cls: type[ExtensionAPI] = ExtensionAPI,
+) -> dict[str, object]:
+    return {
+        "version": 1,
+        "methods": [
+            {
+                "id": method.method_id,
+                "namespace": method.namespace,
+                "name": method.name,
+                "python_name": method.python_name,
+                "host_interface": method.host_interface,
+                "host_name": method.host_name,
+                "sdk_name": method.sdk_name,
+                "sdk_qualified_name": method.sdk_qualified_name,
+                "description": method.description,
+                "required_permission": method.required_permission,
+                "require_auth": method.require_auth,
+                "request_schema": method.request_model.schema(
+                    ref_template="#/definitions/{model}"
+                ),
+                "response_schema": method.response_model.schema(
+                    ref_template="#/definitions/{model}"
+                ),
+            }
+            for method in list_extension_api_methods(api_cls)
+        ],
+    }
+
+
+def _get_method_models(
+    function: Callable[..., object],
+) -> tuple[type[BaseModel], type[BaseModel]]:
+    signature = inspect.signature(function)
+    request_parameters = [
+        parameter
+        for parameter in signature.parameters.values()
+        if parameter.name != "self"
+    ]
+    if len(request_parameters) != 1:
+        raise TypeError(
+            f"Extension API method '{function.__name__}' must accept one request model."
+        )
+
+    hints = get_type_hints(function)
+    request_model = hints.get(request_parameters[0].name)
+    response_model = hints.get("return")
+
+    if not _is_pydantic_model(request_model):
+        raise TypeError(
+            f"Extension API method '{function.__name__}' request must be a BaseModel."
+        )
+    if not _is_pydantic_model(response_model):
+        raise TypeError(
+            f"Extension API method '{function.__name__}' response must be a BaseModel."
+        )
+
+    return cast(type[BaseModel], request_model), cast(type[BaseModel], response_model)
+
+
+def _is_pydantic_model(value: object) -> bool:
+    return isinstance(value, type) and issubclass(value, BaseModel)

lnbits/core/extensions/api_utils.py

@@ -0,0 +1,381 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from .api import extension_api_method
+from .models import (
+    Bolt11Request,
+    CurrencyConvertRequest,
+    CurrencyConvertResponse,
+    CurrencyListResponse,
+    CurrencyRateRequest,
+    CurrencyRateResponse,
+    DecodeInvoiceResponse,
+    EmptyRequest,
+    FiatToSatsRequest,
+    FiatToSatsResponse,
+    InvoiceAmountMsatResponse,
+    InvoiceExpiryResponse,
+    InvoiceMemoResponse,
+    InvoicePaymentHashResponse,
+    RandomSecretAndHashRequest,
+    RandomSecretAndHashResponse,
+    SatsToFiatRequest,
+    SatsToFiatResponse,
+    ServerHealthResponse,
+    ValidateInvoiceResponse,
+    VerifyPreimageRequest,
+    VerifyPreimageResponse,
+)
+
+if TYPE_CHECKING:
+    from .api import ExtensionAPI
+
+
+class ExtensionAPIUtils:
+    def __init__(self, api: ExtensionAPI) -> None:
+        self.api = api
+        self.currencies = ExtensionCurrencyUtils(api)
+        self.server = ExtensionServerUtils(api)
+        self.lightning = ExtensionLightningUtils(api)
+
+
+class _ExtensionAPIUtilsGroup:
+    def __init__(self, api: ExtensionAPI) -> None:
+        self.api = api
+
+
+class ExtensionCurrencyUtils(_ExtensionAPIUtilsGroup):
+    @extension_api_method(
+        method_id="utils.currencies.list",
+        namespace="utils.currencies",
+        name="List currencies",
+        host_interface="utils-currencies",
+        host_name="list_currencies",
+        sdk_name="list",
+        description="List currencies supported by LNbits exchange-rate conversion.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def list(self, request: EmptyRequest) -> CurrencyListResponse:
+        from lnbits.utils.exchange_rates import allowed_currencies
+
+        return CurrencyListResponse(currencies=allowed_currencies())
+
+    @extension_api_method(
+        method_id="utils.currencies.rate",
+        namespace="utils.currencies",
+        name="Get currency rate",
+        host_interface="utils-currencies",
+        host_name="rate",
+        sdk_name="rate",
+        description="Get sats-per-fiat and BTC price for a currency.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def rate(self, request: CurrencyRateRequest) -> CurrencyRateResponse:
+        from lnbits.utils.exchange_rates import get_fiat_rate_and_price_satoshis
+
+        rate, price = await get_fiat_rate_and_price_satoshis(request.currency)
+        return CurrencyRateResponse(rate=rate, price=price)
+
+    @extension_api_method(
+        method_id="utils.currencies.convert",
+        namespace="utils.currencies",
+        name="Convert currency amount",
+        host_interface="utils-currencies",
+        host_name="convert",
+        sdk_name="convert",
+        description="Convert between sats, BTC, and supported fiat currencies.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def convert(self, request: CurrencyConvertRequest) -> CurrencyConvertResponse:
+        from lnbits.utils.exchange_rates import (
+            fiat_amount_as_satoshis,
+            satoshis_amount_as_fiat,
+        )
+
+        from_currency = request.from_currency
+        if from_currency == "sats":
+            from_currency = "sat"
+
+        amounts: list[tuple[str, float]] = []
+        if from_currency == "sat":
+            sats = int(request.amount)
+            amounts.append(("BTC", sats / 100_000_000))
+            amounts.append(("sats", sats))
+            for currency in request.to.split(","):
+                currency = currency.strip()
+                if currency:
+                    amounts.append(
+                        (
+                            currency.upper(),
+                            await satoshis_amount_as_fiat(sats, currency),
+                        )
+                    )
+        else:
+            sats = await fiat_amount_as_satoshis(request.amount, from_currency)
+            amounts.append((from_currency.upper(), request.amount))
+            amounts.append(("sats", sats))
+            amounts.append(("BTC", sats / 100_000_000))
+        return CurrencyConvertResponse(amounts=amounts)
+
+    @extension_api_method(
+        method_id="utils.currencies.fiat_to_sats",
+        namespace="utils.currencies",
+        name="Convert fiat to sats",
+        host_interface="utils-currencies",
+        host_name="fiat_to_sats",
+        sdk_name="fiatToSats",
+        description="Convert a fiat amount to sats.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def fiat_to_sats(self, request: FiatToSatsRequest) -> FiatToSatsResponse:
+        from lnbits.utils.exchange_rates import fiat_amount_as_satoshis
+
+        return FiatToSatsResponse(
+            amount_sat=await fiat_amount_as_satoshis(
+                request.amount,
+                request.currency,
+            )
+        )
+
+    @extension_api_method(
+        method_id="utils.currencies.sats_to_fiat",
+        namespace="utils.currencies",
+        name="Convert sats to fiat",
+        host_interface="utils-currencies",
+        host_name="sats_to_fiat",
+        sdk_name="satsToFiat",
+        description="Convert a sats amount to fiat.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def sats_to_fiat(self, request: SatsToFiatRequest) -> SatsToFiatResponse:
+        from lnbits.utils.exchange_rates import satoshis_amount_as_fiat
+
+        return SatsToFiatResponse(
+            amount=await satoshis_amount_as_fiat(request.amount, request.currency)
+        )
+
+
+class ExtensionServerUtils(_ExtensionAPIUtilsGroup):
+    @extension_api_method(
+        method_id="utils.server.health",
+        namespace="utils.server",
+        name="Server health",
+        host_interface="utils-server",
+        host_name="health",
+        sdk_name="health",
+        description="Return basic public LNbits server health data.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def health(self, request: EmptyRequest) -> ServerHealthResponse:
+        from lnbits.settings import settings
+
+        return ServerHealthResponse(
+            server_time=int(time.time()),
+            up_time=settings.lnbits_server_up_time,
+        )
+
+
+class ExtensionLightningUtils(_ExtensionAPIUtilsGroup):
+    @extension_api_method(
+        method_id="utils.lightning.decode_invoice",
+        namespace="utils.lightning",
+        name="Decode Lightning invoice",
+        host_interface="utils-lightning",
+        host_name="decode_invoice",
+        sdk_name="decodeInvoice",
+        description="Decode a BOLT11 Lightning invoice.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def decode_invoice(self, request: Bolt11Request) -> DecodeInvoiceResponse:
+        invoice = _decode_bolt11(request.bolt11)
+        return _decoded_invoice_response(invoice)
+
+    @extension_api_method(
+        method_id="utils.lightning.validate_invoice",
+        namespace="utils.lightning",
+        name="Validate Lightning invoice",
+        host_interface="utils-lightning",
+        host_name="validate_invoice",
+        sdk_name="validateInvoice",
+        description="Validate whether a string is a BOLT11 Lightning invoice.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def validate_invoice(self, request: Bolt11Request) -> ValidateInvoiceResponse:
+        try:
+            _decode_bolt11(request.bolt11)
+            return ValidateInvoiceResponse(valid=True)
+        except Exception as exc:
+            return ValidateInvoiceResponse(valid=False, error=str(exc))
+
+    @extension_api_method(
+        method_id="utils.lightning.invoice_payment_hash",
+        namespace="utils.lightning",
+        name="Get Lightning invoice payment hash",
+        host_interface="utils-lightning",
+        host_name="invoice_payment_hash",
+        sdk_name="invoicePaymentHash",
+        description="Get the payment hash from a BOLT11 Lightning invoice.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def invoice_payment_hash(
+        self, request: Bolt11Request
+    ) -> InvoicePaymentHashResponse:
+        return InvoicePaymentHashResponse(
+            payment_hash=str(_decode_bolt11(request.bolt11).payment_hash)
+        )
+
+    @extension_api_method(
+        method_id="utils.lightning.invoice_amount_msat",
+        namespace="utils.lightning",
+        name="Get Lightning invoice amount",
+        host_interface="utils-lightning",
+        host_name="invoice_amount_msat",
+        sdk_name="invoiceAmountMsat",
+        description="Get the amount in msat from a BOLT11 Lightning invoice.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def invoice_amount_msat(
+        self, request: Bolt11Request
+    ) -> InvoiceAmountMsatResponse:
+        return InvoiceAmountMsatResponse(
+            amount_msat=_invoice_amount_msat(_decode_bolt11(request.bolt11))
+        )
+
+    @extension_api_method(
+        method_id="utils.lightning.invoice_expiry",
+        namespace="utils.lightning",
+        name="Get Lightning invoice expiry",
+        host_interface="utils-lightning",
+        host_name="invoice_expiry",
+        sdk_name="invoiceExpiry",
+        description="Get the expiry timestamp from a BOLT11 Lightning invoice.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def invoice_expiry(self, request: Bolt11Request) -> InvoiceExpiryResponse:
+        return InvoiceExpiryResponse(
+            expires_at=_invoice_expires_at(_decode_bolt11(request.bolt11))
+        )
+
+    @extension_api_method(
+        method_id="utils.lightning.invoice_memo",
+        namespace="utils.lightning",
+        name="Get Lightning invoice memo",
+        host_interface="utils-lightning",
+        host_name="invoice_memo",
+        sdk_name="invoiceMemo",
+        description="Get the memo from a BOLT11 Lightning invoice.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def invoice_memo(self, request: Bolt11Request) -> InvoiceMemoResponse:
+        return InvoiceMemoResponse(memo=_invoice_memo(_decode_bolt11(request.bolt11)))
+
+    @extension_api_method(
+        method_id="utils.lightning.verify_preimage",
+        namespace="utils.lightning",
+        name="Verify Lightning preimage",
+        host_interface="utils-lightning",
+        host_name="verify_preimage",
+        sdk_name="verifyPreimage",
+        description="Verify that a preimage matches a payment hash.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def verify_preimage(
+        self, request: VerifyPreimageRequest
+    ) -> VerifyPreimageResponse:
+        from lnbits.utils.crypto import verify_preimage
+
+        return VerifyPreimageResponse(
+            valid=verify_preimage(request.preimage, request.payment_hash)
+        )
+
+    @extension_api_method(
+        method_id="utils.lightning.random_secret_and_hash",
+        namespace="utils.lightning",
+        name="Random Lightning secret and hash",
+        host_interface="utils-lightning",
+        host_name="random_secret_and_hash",
+        sdk_name="randomSecretAndHash",
+        description="Create a random secret and matching SHA256 hash.",
+        required_permission="utils.basic",
+        require_auth=False,
+    )
+    async def random_secret_and_hash(
+        self, request: RandomSecretAndHashRequest
+    ) -> RandomSecretAndHashResponse:
+        from lnbits.utils.crypto import random_secret_and_hash
+
+        secret, payment_hash = random_secret_and_hash(request.length)
+        return RandomSecretAndHashResponse(secret=secret, hash=payment_hash)
+
+
+def extension_api_utils_method_classes() -> dict[str, type[_ExtensionAPIUtilsGroup]]:
+    return {
+        "utils.currencies": ExtensionCurrencyUtils,
+        "utils.server": ExtensionServerUtils,
+        "utils.lightning": ExtensionLightningUtils,
+    }
+
+
+def _decode_bolt11(payment_request: str) -> Any:
+    from lnbits import bolt11
+
+    return bolt11.decode(payment_request)
+
+
+def _decoded_invoice_response(invoice: Any) -> DecodeInvoiceResponse:
+    return DecodeInvoiceResponse(
+        payment_hash=str(getattr(invoice, "payment_hash", "")) or None,
+        amount_msat=_invoice_amount_msat(invoice),
+        expiry=_invoice_expiry(invoice),
+        expires_at=_invoice_expires_at(invoice),
+        memo=_invoice_memo(invoice),
+    )
+
+
+def _invoice_amount_msat(invoice: Any) -> int | None:
+    amount_msat = getattr(invoice, "amount_msat", None)
+    if amount_msat is None:
+        return None
+    return int(amount_msat)
+
+
+def _invoice_expiry(invoice: Any) -> int | None:
+    expiry = getattr(invoice, "expiry", None)
+    if expiry is None:
+        return None
+    return int(expiry)
+
+
+def _invoice_expires_at(invoice: Any) -> int | None:
+    expiry_date = getattr(invoice, "expiry_date", None)
+    if isinstance(expiry_date, datetime):
+        return int(expiry_date.timestamp())
+
+    date = getattr(invoice, "date", None)
+    expiry = getattr(invoice, "expiry", None)
+    if isinstance(date, datetime) and expiry is not None:
+        return int(date.timestamp() + int(expiry))
+    if isinstance(date, (int, float)) and expiry is not None:
+        return int(date + int(expiry))
+    return None
+
+
+def _invoice_memo(invoice: Any) -> str | None:
+    memo = getattr(invoice, "description", None)
+    return str(memo) if memo is not None else None

lnbits/core/extensions/events.py

@@ -0,0 +1,113 @@
+import json
+from typing import Any
+
+from loguru import logger
+
+from lnbits.core.db import core_app_extra
+
+
+async def dispatch_wasm_invoice_paid(payment: Any) -> None:
+    extension_id = _payment_extension_id(payment)
+    if not extension_id:
+        return
+
+    extension = core_app_extra.wasm_extension_registry.get(extension_id)
+    if not extension:
+        return
+
+    export_name = _wasm_invoice_paid_export(extension.config)
+    if not export_name:
+        return
+
+    if not _is_wasm_event_export(extension, export_name):
+        logger.warning(
+            f"WASM extension '{extension.id}' declares invalid onInvoicePaid "
+            f"export '{export_name}'."
+        )
+        return
+
+    try:
+        from lnbits.core.extensions.wasm import invoke_wasm_extension_export
+
+        await invoke_wasm_extension_export(
+            extension.id,
+            export_name,
+            _wasm_invoice_paid_payload(payment),
+            context="event",
+            owner_id=await _wasm_invoice_paid_owner_id(extension, payment),
+        )
+    except Exception as exc:
+        logger.warning(
+            f"WASM extension '{extension.id}' failed to handle paid invoice "
+            f"'{payment.payment_hash}': {exc!s}"
+        )
+
+
+def _payment_extension_id(payment: Any) -> str | None:
+    if isinstance(payment.extension, str) and payment.extension:
+        return payment.extension
+
+    extra = payment.extra or {}
+    tag = extra.get("tag") or payment.tag
+    return tag if isinstance(tag, str) and tag else None
+
+
+async def _wasm_invoice_paid_owner_id(extension: Any, payment: Any) -> str | None:
+    source_id = _payment_source_id(payment)
+    source_table = _wasm_public_invoice_source_table(extension.config)
+    if not source_id or not source_table:
+        return None
+
+    from lnbits.core.extensions.storage import storage_get_row_owner_id
+
+    return await storage_get_row_owner_id(extension.id, source_table, source_id)
+
+
+def _payment_source_id(payment: Any) -> str | None:
+    extra = payment.extra or {}
+    source_id = extra.get("source_id")
+    return source_id if isinstance(source_id, str) and source_id else None
+
+
+def _wasm_public_invoice_source_table(config: dict[str, Any]) -> str | None:
+    permissions = config.get("permissions") or []
+    for permission in permissions:
+        if not isinstance(permission, dict):
+            continue
+        if permission.get("id") != "wallet.create_invoice_public":
+            continue
+        policy = permission.get("policy") or {}
+        table = policy.get("table")
+        return table if isinstance(table, str) and table else None
+    return None
+
+
+def _wasm_invoice_paid_export(config: dict[str, Any]) -> str | None:
+    events = config.get("events") or {}
+    export_name = events.get("onInvoicePaid")
+    return export_name if isinstance(export_name, str) and export_name else None
+
+
+def _is_wasm_event_export(extension: Any, export_name: str) -> bool:
+    for export in extension.exports:
+        if export.get("name") == export_name:
+            return export.get("visibility") == "event"
+    return False
+
+
+def _wasm_invoice_paid_payload(payment: Any) -> dict[str, Any]:
+    return {
+        "checkingId": payment.checking_id,
+        "paymentHash": payment.payment_hash,
+        "walletId": payment.wallet_id,
+        "amount": payment.amount,
+        "fee": payment.fee,
+        "bolt11": payment.bolt11,
+        "memo": payment.memo,
+        "pending": payment.pending,
+        "status": payment.status,
+        "tag": payment.tag,
+        "extension": payment.extension,
+        "extra": payment.extra or {},
+        "payment": json.loads(payment.json()),
+    }

lnbits/core/extensions/extension_client.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import posixpath
+import re
+from typing import Any
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+import httpx
+
+from lnbits.core.crud.extensions import (
+    get_installed_extension,
+    get_user_active_extensions_ids,
+)
+from lnbits.settings import settings
+
+from .models import ExtensionApiRequest, HttpResponse
+
+EXTENSION_API_TIMEOUT_SECONDS = 10.0
+EXTENSION_API_MAX_RESPONSE_BYTES = 262_144
+
+_READ_METHODS = {"GET", "HEAD"}
+_WRITE_METHODS = {"DELETE", "PATCH", "POST", "PUT"}
+_EXTENSION_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+_FORBIDDEN_RESPONSE_HEADERS = {
+    "connection",
+    "content-length",
+    "set-cookie",
+    "transfer-encoding",
+}
+
+
+async def send_extension_api_request(
+    caller_extension_id: str,
+    policy: dict[str, Any],
+    user_id: str | None,
+    access_token: str | None,
+    request: ExtensionApiRequest,
+) -> HttpResponse:
+    if not user_id:
+        raise PermissionError("Extension API requests require authentication.")
+    if not access_token:
+        raise PermissionError("Extension API requests require an account access token.")
+
+    target_extension_id = _target_extension_id(request.extension_id)
+    access = _target_extension_access(policy, target_extension_id)
+    _require_method_access(caller_extension_id, target_extension_id, access, request)
+    await _require_enabled_extension(target_extension_id, user_id)
+
+    path = _extension_api_path(request.path)
+    body = request.body.encode() if request.body is not None else b""
+    if len(body) > 65_536:
+        raise ValueError("Extension API request body is too large.")
+
+    url = f"http://{settings.host}:{settings.port}/{target_extension_id}{path}"
+    try:
+        async with httpx.AsyncClient(
+            follow_redirects=False,
+            timeout=EXTENSION_API_TIMEOUT_SECONDS,
+            trust_env=False,
+        ) as client:
+            async with client.stream(
+                request.method,
+                url,
+                headers={"Authorization": f"Bearer {access_token}"},
+                content=body,
+            ) as response:
+                response_body = await _read_limited_response(response)
+                return HttpResponse(
+                    status_code=response.status_code,
+                    headers=_response_headers(dict(response.headers)),
+                    body=response_body.decode(response.encoding or "utf-8", "replace"),
+                )
+    except httpx.RequestError as exc:
+        raise ValueError("Extension API request failed.") from exc
+
+
+def _target_extension_id(extension_id: str) -> str:
+    target = extension_id.strip()
+    if not target or not _EXTENSION_ID_RE.match(target):
+        raise PermissionError("Extension API request has an invalid target extension.")
+    return target
+
+
+def _target_extension_access(
+    policy: dict[str, Any], target_extension_id: str
+) -> set[str]:
+    extensions = policy.get("extensions")
+    if not isinstance(extensions, list) or not extensions:
+        raise PermissionError(
+            "Extension API requests require a non-empty extensions policy."
+        )
+
+    for extension in extensions:
+        if isinstance(extension, str):
+            extension_id = extension
+            access = ["read"]
+        elif isinstance(extension, dict):
+            raw_extension_id = extension.get("id")
+            raw_access = extension.get("access")
+            if not isinstance(raw_extension_id, str):
+                continue
+            if not isinstance(raw_access, list):
+                raise PermissionError(
+                    f"Extension API target '{target_extension_id}' "
+                    "has no access policy."
+                )
+            extension_id = raw_extension_id
+            access = raw_access
+        else:
+            continue
+
+        if extension_id != target_extension_id:
+            continue
+        clean_access = {
+            item
+            for item in access
+            if isinstance(item, str) and item in {"read", "write"}
+        }
+        if clean_access:
+            return clean_access
+        break
+
+    raise PermissionError(
+        f"Extension API target '{target_extension_id}' is not allowed."
+    )
+
+
+def _require_method_access(
+    caller_extension_id: str,
+    target_extension_id: str,
+    access: set[str],
+    request: ExtensionApiRequest,
+) -> None:
+    if request.method in _READ_METHODS:
+        required_access = "read"
+    elif request.method in _WRITE_METHODS:
+        required_access = "write"
+    else:
+        raise PermissionError("Extension API request method is not allowed.")
+
+    if required_access not in access:
+        raise PermissionError(
+            f"Extension '{caller_extension_id}' cannot {required_access} "
+            f"extension '{target_extension_id}'."
+        )
+
+
+async def _require_enabled_extension(target_extension_id: str, user_id: str) -> None:
+    extension = await get_installed_extension(target_extension_id)
+    if not extension or not extension.active:
+        raise PermissionError(
+            f"Target extension '{target_extension_id}' is not installed or enabled."
+        )
+
+    active_extensions = await get_user_active_extensions_ids(user_id)
+    if target_extension_id not in active_extensions:
+        raise PermissionError(
+            f"Target extension '{target_extension_id}' is not active for this user."
+        )
+
+
+def _extension_api_path(path: str) -> str:
+    parts = urlsplit(path)
+    if parts.scheme or parts.netloc:
+        raise PermissionError("Extension API request path must be relative.")
+    if parts.fragment:
+        raise PermissionError("Extension API request path cannot include a fragment.")
+    if not parts.path.startswith("/api/"):
+        raise PermissionError("Extension API request path must start with '/api/'.")
+
+    decoded_path = unquote(parts.path)
+    path_parts = decoded_path.split("/")
+    if any(part == ".." for part in path_parts):
+        raise PermissionError("Extension API request path cannot traverse directories.")
+
+    normalized = posixpath.normpath(decoded_path)
+    if normalized != decoded_path.rstrip("/") or not normalized.startswith("/api/"):
+        raise PermissionError("Extension API request path is invalid.")
+
+    return urlunsplit(("", "", parts.path, parts.query, ""))
+
+
+async def _read_limited_response(response: httpx.Response) -> bytes:
+    chunks: list[bytes] = []
+    size = 0
+    async for chunk in response.aiter_bytes():
+        size += len(chunk)
+        if size > EXTENSION_API_MAX_RESPONSE_BYTES:
+            raise ValueError("Extension API response is too large.")
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def _response_headers(headers: dict[str, str]) -> dict[str, str]:
+    return {
+        key: value
+        for key, value in headers.items()
+        if key.lower() not in _FORBIDDEN_RESPONSE_HEADERS
+    }

lnbits/core/extensions/http_client.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import ipaddress
+import socket
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from .models import HttpRequest, HttpResponse
+
+HTTP_REQUEST_TIMEOUT_SECONDS = 10.0
+HTTP_MAX_RESPONSE_BYTES = 262_144
+
+_FORBIDDEN_REQUEST_HEADERS = {
+    "connection",
+    "content-length",
+    "cookie",
+    "host",
+    "proxy-authorization",
+    "transfer-encoding",
+}
+_FORBIDDEN_RESPONSE_HEADERS = {
+    "connection",
+    "content-length",
+    "set-cookie",
+    "transfer-encoding",
+}
+
+
+async def send_extension_http_request(
+    extension_id: str,
+    policy: dict[str, Any],
+    request: HttpRequest,
+) -> HttpResponse:
+    allowed_origins = _allowed_origins(policy)
+    origin = _request_origin(request.url)
+    if origin not in allowed_origins:
+        raise PermissionError(
+            f"Extension '{extension_id}' is not allowed to request '{origin}'."
+        )
+
+    await _reject_internal_host(request.url)
+    headers = _request_headers(request.headers)
+    body = request.body.encode() if request.body is not None else b""
+    if len(body) > 65_536:
+        raise ValueError("HTTP request body is too large.")
+
+    try:
+        async with httpx.AsyncClient(
+            follow_redirects=False,
+            timeout=HTTP_REQUEST_TIMEOUT_SECONDS,
+            trust_env=False,
+        ) as client:
+            async with client.stream(
+                request.method,
+                request.url,
+                headers=headers,
+                content=body,
+            ) as response:
+                response_body = await _read_limited_response(response)
+                return HttpResponse(
+                    status_code=response.status_code,
+                    headers=_response_headers(dict(response.headers)),
+                    body=response_body.decode(response.encoding or "utf-8", "replace"),
+                )
+    except httpx.RequestError as exc:
+        raise ValueError("HTTP request failed.") from exc
+
+
+def _allowed_origins(policy: dict[str, Any]) -> set[str]:
+    hosts = policy.get("hosts")
+    if not isinstance(hosts, list) or not hosts:
+        raise PermissionError("HTTP requests require a non-empty hosts policy.")
+
+    origins: set[str] = set()
+    for host in hosts:
+        if not isinstance(host, str) or not host:
+            continue
+        origins.add(_request_origin(host))
+    if not origins:
+        raise PermissionError("HTTP requests require at least one valid host.")
+    return origins
+
+
+def _request_origin(url: str) -> str:
+    parsed = urlparse(url)
+    if parsed.scheme != "https":
+        raise PermissionError("HTTP requests require https URLs.")
+    if parsed.username or parsed.password:
+        raise PermissionError("HTTP requests cannot include credentials in URLs.")
+    if not parsed.hostname:
+        raise PermissionError("HTTP requests require a hostname.")
+
+    hostname = parsed.hostname.lower()
+    port = _url_port(parsed)
+    if port is None or port == 443:
+        return f"https://{hostname}"
+    return f"https://{hostname}:{port}"
+
+
+def _url_port(parsed: Any) -> int | None:
+    try:
+        return parsed.port
+    except ValueError as exc:
+        raise PermissionError("HTTP request URL has an invalid port.") from exc
+
+
+async def _reject_internal_host(url: str) -> None:
+    parsed = urlparse(url)
+    hostname = parsed.hostname
+    if not hostname:
+        raise PermissionError("HTTP requests require a hostname.")
+    if hostname == "localhost" or hostname.endswith(".localhost"):
+        raise PermissionError("HTTP requests cannot target localhost.")
+
+    try:
+        address = ipaddress.ip_address(hostname)
+        _reject_internal_address(address)
+        return
+    except ValueError:
+        pass
+
+    for address in await _resolve_host(hostname):
+        _reject_internal_address(address)
+
+
+async def _resolve_host(
+    hostname: str,
+) -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    import asyncio
+
+    def resolve() -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+        try:
+            infos = socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM)
+        except socket.gaierror as exc:
+            raise PermissionError("HTTP request host could not be resolved.") from exc
+
+        addresses: list[ipaddress.IPv4Address | ipaddress.IPv6Address] = []
+        for info in infos:
+            sockaddr = info[4]
+            addresses.append(ipaddress.ip_address(sockaddr[0]))
+        return addresses
+
+    return await asyncio.to_thread(resolve)
+
+
+def _reject_internal_address(
+    address: ipaddress.IPv4Address | ipaddress.IPv6Address,
+) -> None:
+    if not address.is_global:
+        raise PermissionError("HTTP requests cannot target internal network addresses.")
+
+
+def _request_headers(headers: dict[str, str]) -> dict[str, str]:
+    clean: dict[str, str] = {}
+    for key, value in headers.items():
+        header = key.strip()
+        if not header:
+            continue
+        if header.lower() in _FORBIDDEN_REQUEST_HEADERS:
+            continue
+        clean[header] = value
+    return clean
+
+
+async def _read_limited_response(response: httpx.Response) -> bytes:
+    chunks: list[bytes] = []
+    size = 0
+    async for chunk in response.aiter_bytes():
+        size += len(chunk)
+        if size > HTTP_MAX_RESPONSE_BYTES:
+            raise ValueError("HTTP response is too large.")
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def _response_headers(headers: dict[str, str]) -> dict[str, str]:
+    return {
+        key: value
+        for key, value in headers.items()
+        if key.lower() not in _FORBIDDEN_RESPONSE_HEADERS
+    }

lnbits/core/extensions/loader.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from lnbits.settings import settings
+
+
+@dataclass(frozen=True)
+class WasmExtension:
+    id: str
+    name: str
+    version: str
+    root_path: Path
+    module_path: Path
+    wit_path: Path | None
+    world: str
+    host_api: str
+    exports: list[dict[str, Any]]
+    config: dict[str, Any]
+
+
+def is_wasm_extension_id(ext_id: str) -> bool:
+    config = load_wasm_extension_config(ext_id)
+    return bool(config and config.get("extension_type") == "wasm")
+
+
+def is_wasm_extension_dir(ext_dir: Path) -> bool:
+    config = _load_json(ext_dir / "config.json")
+    return bool(config and config.get("extension_type") == "wasm")
+
+
+def load_wasm_extension_config(ext_id: str) -> dict[str, Any] | None:
+    ext_dir = Path(settings.lnbits_extensions_path, "extensions", ext_id)
+    return _load_json(ext_dir / "config.json")
+
+
+def load_wasm_extension(ext_id: str) -> WasmExtension:
+    ext_dir = Path(settings.lnbits_extensions_path, "extensions", ext_id)
+    config = load_wasm_extension_config(ext_id)
+    if not config:
+        raise FileNotFoundError(f"Missing WASM extension config for '{ext_id}'.")
+    if config.get("extension_type") != "wasm":
+        raise ValueError(f"Extension '{ext_id}' is not a WASM extension.")
+
+    wasm_config = config.get("wasm") or {}
+    module_path = _extension_path(ext_dir, wasm_config.get("module"))
+    wit_path = _optional_extension_path(ext_dir, wasm_config.get("wit"))
+    _check_wasm_module(module_path)
+    if wit_path and not wit_path.is_file():
+        raise FileNotFoundError(f"WIT file not found: {wit_path}")
+
+    return WasmExtension(
+        id=config.get("id") or ext_id,
+        name=config.get("name") or ext_id,
+        version=config.get("version") or "0.0",
+        root_path=ext_dir,
+        module_path=module_path,
+        wit_path=wit_path,
+        world=wasm_config.get("world") or "",
+        host_api=wasm_config.get("host_api") or "lnbits.core.extensions.ExtensionAPI",
+        exports=wasm_config.get("exports") or [],
+        config=config,
+    )
+
+
+def _load_json(path: Path) -> dict[str, Any] | None:
+    if not path.is_file():
+        return None
+    with path.open("r", encoding="utf-8") as config_file:
+        value = json.load(config_file)
+    if not isinstance(value, dict):
+        raise ValueError(f"Expected JSON object in '{path}'.")
+    return value
+
+
+def _extension_path(ext_dir: Path, value: Any) -> Path:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"Missing relative path for extension '{ext_dir.name}'.")
+    path = (ext_dir / value).resolve()
+    if ext_dir.resolve() not in path.parents:
+        raise ValueError(f"Extension path escapes extension root: {value}")
+    return path
+
+
+def _optional_extension_path(ext_dir: Path, value: Any) -> Path | None:
+    if value is None:
+        return None
+    return _extension_path(ext_dir, value)
+
+
+def _check_wasm_module(path: Path) -> None:
+    if not path.is_file():
+        raise FileNotFoundError(f"WASM module not found: {path}")
+    with path.open("rb") as wasm_file:
+        magic = wasm_file.read(4)
+    if magic != b"\0asm":
+        raise ValueError(f"Invalid WASM module: {path}")

lnbits/core/extensions/models.py

@@ -0,0 +1,321 @@
+import json
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, root_validator
+
+
+class EmptyRequest(BaseModel):
+    pass
+
+
+class StorageGetRequest(BaseModel):
+    table: str = Field(..., min_length=1, max_length=128)
+    id: str = Field(..., min_length=1, max_length=512)
+
+
+class StorageGetResponse(BaseModel):
+    data_json: str | None = None
+
+
+class StorageSetRequest(BaseModel):
+    table: str = Field(..., min_length=1, max_length=128)
+    data: dict[str, Any] = Field(default_factory=dict)
+
+    @root_validator(pre=True)
+    def parse_data_json(cls, values: dict[str, Any]) -> dict[str, Any]:
+        data_json = values.get("data_json")
+        if data_json is not None and "data" not in values:
+            values["data"] = json.loads(data_json)
+        return values
+
+
+class StorageSetResponse(BaseModel):
+    ok: bool = True
+
+
+class StoragePaginatedRequest(BaseModel):
+    table: str = Field(..., min_length=1, max_length=128)
+    filters: dict[str, Any] = Field(default_factory=dict)
+    search: str | None = Field(None, max_length=256)
+    search_fields: list[str] = Field(default_factory=list)
+    sort_by: str | None = Field(None, min_length=1, max_length=128)
+    descending: bool = False
+    limit: int = Field(25, ge=1, le=1000)
+    offset: int = Field(0, ge=0)
+
+    @root_validator(pre=True)
+    def parse_json_fields(cls, values: dict[str, Any]) -> dict[str, Any]:
+        filters_json = values.get("filters_json")
+        if filters_json is not None and "filters" not in values:
+            values["filters"] = json.loads(filters_json)
+
+        search_fields_json = values.get("search_fields_json")
+        if search_fields_json is not None and "search_fields" not in values:
+            values["search_fields"] = json.loads(search_fields_json)
+
+        if values.get("sort_by") == "":
+            values["sort_by"] = None
+        return values
+
+
+class StoragePaginatedResponse(BaseModel):
+    rows_json: str = "[]"
+    total: int = 0
+
+
+class StorageDeleteRequest(BaseModel):
+    table: str = Field(..., min_length=1, max_length=128)
+    id: str = Field(..., min_length=1, max_length=512)
+
+
+class StorageDeleteResponse(BaseModel):
+    ok: bool = True
+
+
+class CreateInvoiceRequest(BaseModel):
+    wallet_id: str = Field(..., min_length=1, max_length=128)
+    amount: float = Field(..., gt=0)
+    currency: str = Field("sat", min_length=1, max_length=8)
+    memo: str = Field(..., max_length=512)
+    tag: str = Field(..., min_length=1, max_length=64)
+    extra: dict[str, str] = Field(default_factory=dict)
+
+
+class CreateInvoicePublicRequest(BaseModel):
+    source_id: str = Field(..., min_length=1, max_length=512)
+    amount: float = Field(..., gt=0)
+    currency: str = Field(..., min_length=1, max_length=8)
+    memo: str = Field("", max_length=512)
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+    @root_validator
+    def validate_extra_size(cls, values: dict[str, Any]) -> dict[str, Any]:
+        extra = values.get("extra") or {}
+        try:
+            encoded = json.dumps(extra, separators=(",", ":"))
+        except TypeError as exc:
+            raise ValueError("extra must be JSON serializable.") from exc
+        if len(encoded.encode()) > 4096:
+            raise ValueError("extra must not exceed 4096 bytes.")
+        values["extra"] = extra
+        return values
+
+
+class CreateInvoiceResponse(BaseModel):
+    payment_hash: str
+    payment_request: str
+    checking_id: str
+
+
+class UserWalletSummary(BaseModel):
+    id: str
+    name: str
+    currency: str | None = None
+
+
+class ListUserWalletsResponse(BaseModel):
+    wallets: list[UserWalletSummary] = Field(default_factory=list)
+
+
+class WalletBalanceRequest(BaseModel):
+    wallet_id: str = Field(..., min_length=1, max_length=128)
+
+
+class WalletBalanceResponse(BaseModel):
+    wallet_id: str
+    name: str
+    currency: str | None = None
+    balance_msat: int
+    balance_sat: int
+    withdrawable_msat: int
+    withdrawable_sat: int
+    fee_reserve_msat: int
+    fee_reserve_sat: int
+    can_send_payments: bool
+
+
+class PayInvoiceRequest(BaseModel):
+    wallet_id: str = Field(..., min_length=1, max_length=128)
+    payment_request: str = Field(..., min_length=1, max_length=8192)
+    max_sat: int | None = Field(None, gt=0)
+    description: str = Field("", max_length=512)
+    extra: dict[str, str] = Field(default_factory=dict)
+
+
+class PayInvoiceResponse(BaseModel):
+    ok: bool = True
+    error: str | None = None
+    checking_id: str | None = None
+    payment_hash: str | None = None
+    status: str | None = None
+    amount_msat: int = 0
+    fee_msat: int = 0
+    pending: bool = False
+    success: bool = False
+
+
+class HttpRequest(BaseModel):
+    method: Literal["DELETE", "GET", "HEAD", "PATCH", "POST", "PUT"] = "GET"
+    url: str = Field(..., min_length=1, max_length=2048)
+    headers: dict[str, str] = Field(default_factory=dict)
+    body: str | None = Field(None, max_length=65536)
+
+    @root_validator(pre=True)
+    def normalize_method(cls, values: dict[str, Any]) -> dict[str, Any]:
+        method = values.get("method")
+        if isinstance(method, str):
+            values["method"] = method.upper()
+        return values
+
+    @root_validator
+    def validate_headers_size(cls, values: dict[str, Any]) -> dict[str, Any]:
+        headers = values.get("headers") or {}
+        if len(headers) > 32:
+            raise ValueError("headers must not contain more than 32 entries.")
+        for key, value in headers.items():
+            if len(key) > 128 or len(value) > 4096:
+                raise ValueError("headers are too large.")
+        values["headers"] = headers
+        return values
+
+
+class HttpResponse(BaseModel):
+    status_code: int
+    headers: dict[str, str] = Field(default_factory=dict)
+    body: str = ""
+
+
+class ExtensionApiRequest(BaseModel):
+    extension_id: str = Field(..., min_length=1, max_length=128)
+    method: Literal["DELETE", "GET", "HEAD", "PATCH", "POST", "PUT"] = "GET"
+    path: str = Field(..., min_length=1, max_length=2048)
+    body: str | None = Field(None, max_length=65536)
+
+    @root_validator(pre=True)
+    def normalize_method(cls, values: dict[str, Any]) -> dict[str, Any]:
+        method = values.get("method")
+        if isinstance(method, str):
+            values["method"] = method.upper()
+        return values
+
+
+class CurrencyListResponse(BaseModel):
+    currencies: list[str] = Field(default_factory=list)
+
+
+class CurrencyRateRequest(BaseModel):
+    currency: str = Field(..., min_length=1, max_length=8)
+
+
+class CurrencyRateResponse(BaseModel):
+    rate: float
+    price: float
+
+
+class CurrencyConvertRequest(BaseModel):
+    amount: float = Field(..., gt=0)
+    from_currency: str = Field(..., alias="from", min_length=1, max_length=8)
+    to: str = Field(..., min_length=1, max_length=256)
+
+    class Config:
+        allow_population_by_field_name = True
+
+
+class CurrencyConvertResponse(BaseModel):
+    amounts: list[tuple[str, float]] = Field(default_factory=list)
+
+
+class FiatToSatsRequest(BaseModel):
+    amount: float = Field(..., gt=0)
+    currency: str = Field(..., min_length=1, max_length=8)
+
+
+class FiatToSatsResponse(BaseModel):
+    amount_sat: int
+
+
+class SatsToFiatRequest(BaseModel):
+    amount: float = Field(..., gt=0)
+    currency: str = Field(..., min_length=1, max_length=8)
+
+
+class SatsToFiatResponse(BaseModel):
+    amount: float
+
+
+class ServerHealthResponse(BaseModel):
+    server_time: int
+    up_time: str
+
+
+class Bolt11Request(BaseModel):
+    bolt11: str = Field(..., min_length=1, max_length=8192)
+
+
+class DecodeInvoiceResponse(BaseModel):
+    valid: bool = True
+    payment_hash: str | None = None
+    amount_msat: int | None = None
+    expiry: int | None = None
+    expires_at: int | None = None
+    memo: str | None = None
+
+
+class ValidateInvoiceResponse(BaseModel):
+    valid: bool
+    error: str | None = None
+
+
+class InvoicePaymentHashResponse(BaseModel):
+    payment_hash: str
+
+
+class InvoiceAmountMsatResponse(BaseModel):
+    amount_msat: int | None = None
+
+
+class InvoiceExpiryResponse(BaseModel):
+    expires_at: int | None = None
+
+
+class InvoiceMemoResponse(BaseModel):
+    memo: str | None = None
+
+
+class VerifyPreimageRequest(BaseModel):
+    preimage: str = Field(..., min_length=64, max_length=64)
+    payment_hash: str = Field(..., min_length=64, max_length=64)
+
+
+class VerifyPreimageResponse(BaseModel):
+    valid: bool
+
+
+class RandomSecretAndHashRequest(BaseModel):
+    length: int = Field(32, ge=16, le=64)
+
+
+class RandomSecretAndHashResponse(BaseModel):
+    secret: str
+    hash: str
+
+
+class RandomIdRequest(BaseModel):
+    prefix: str = Field(..., min_length=1, max_length=32)
+
+
+class RandomIdResponse(BaseModel):
+    id: str
+
+
+class NowResponse(BaseModel):
+    timestamp: int
+
+
+class LogRequest(BaseModel):
+    level: Literal["debug", "info", "warning", "error"] = "info"
+    message: str = Field(..., min_length=1, max_length=2048)
+
+
+class LogResponse(BaseModel):
+    ok: bool = True

lnbits/core/extensions/permissions.py

@@ -0,0 +1,59 @@
+from collections.abc import Iterable
+from typing import Any
+
+from lnbits.core.extensions.api import extension_api_permission_ids
+from lnbits.core.models.extensions import ExtensionPermission, InstallableExtension
+
+
+def validate_extension_permissions(
+    ext_id: str,
+    permissions: Iterable[ExtensionPermission],
+    *,
+    strict: bool = True,
+) -> list[ExtensionPermission]:
+    known_permission_ids = extension_api_permission_ids()
+    normalized_permissions: list[ExtensionPermission] = []
+    unknown_ids: list[str] = []
+
+    for permission in permissions:
+        if permission.id not in known_permission_ids:
+            unknown_ids.append(permission.id)
+            if strict:
+                continue
+        normalized_permissions.append(permission.copy(update={"label": None}))
+
+    if unknown_ids and strict:
+        raise ValueError(
+            f"Extension '{ext_id}' requests unknown permissions: "
+            + ", ".join(sorted(set(unknown_ids)))
+        )
+
+    return normalized_permissions
+
+
+def validate_wasm_extension_permissions(
+    ext_info: InstallableExtension,
+    granted_permissions: list[ExtensionPermission] | None,
+    extension_config: dict[str, Any],
+) -> list[ExtensionPermission]:
+    if extension_config.get("extension_type") != "wasm":
+        return []
+
+    requested_permissions = validate_extension_permissions(
+        ext_info.id,
+        ExtensionPermission.list_from_config(extension_config),
+    )
+    if not requested_permissions:
+        return []
+
+    if granted_permissions is None:
+        raise ValueError(f"Extension '{ext_info.id}' requires permission approval.")
+
+    requested_ids = {permission.id for permission in requested_permissions}
+    granted_ids = {permission.id for permission in granted_permissions}
+    if requested_ids != granted_ids:
+        raise ValueError(
+            f"Extension '{ext_info.id}' was not granted all requested permissions."
+        )
+
+    return requested_permissions

lnbits/core/extensions/routes.py

@@ -0,0 +1,777 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Annotated, Any, NoReturn
+from uuid import uuid4
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.responses import FileResponse, Response
+from fastapi.staticfiles import StaticFiles
+from loguru import logger
+from pydantic import UUID4
+from starlette.staticfiles import PathLike as StaticFilesPathLike
+from starlette.types import Scope
+
+from lnbits.core.crud import get_installed_extension, get_user_from_account
+from lnbits.core.db import core_app_extra
+from lnbits.core.models import Account
+from lnbits.decorators import (
+    check_access_token,
+    check_account_exists,
+    optional_user_id,
+)
+from lnbits.helpers import template_renderer
+from lnbits.settings import settings
+from lnbits.utils.cache import cache
+
+from .loader import WasmExtension, load_wasm_extension
+from .wasm import invoke_wasm_extension_export, warm_wasm_extension
+
+WASM_FRAME_TOKEN_EXPIRY_SECONDS = 60
+WASM_EXTENSION_CORE_ASSET_PREFIX = "_lnbits"
+WASM_EXTENSION_CORE_STATIC_ASSETS = {
+    "bundle.min.css": ("static/bundle.min.css", "text/css; charset=utf-8"),
+    "material-icons-v50.woff2": (
+        "static/fonts/material-icons-v50.woff2",
+        "font/woff2",
+    ),
+    "quasar.css": ("static/vendor/quasar.css", "text/css; charset=utf-8"),
+    "quasar.umd.prod.js": (
+        "static/vendor/quasar.umd.prod.js",
+        "text/javascript; charset=utf-8",
+    ),
+    "qrcode.vue.browser.js": (
+        "static/vendor/qrcode.vue.browser.js",
+        "text/javascript; charset=utf-8",
+    ),
+    "vue.global.prod.js": (
+        "static/vendor/vue.global.prod.js",
+        "text/javascript; charset=utf-8",
+    ),
+}
+WASM_EXTENSION_GENERATED_CORE_ASSETS = {
+    "material-icons.css": (
+        """
+        @font-face {
+          font-family: 'Material Icons';
+          font-style: normal;
+          font-weight: 400;
+          src: url('./material-icons-v50.woff2') format('woff2');
+        }
+        """,
+        "text/css; charset=utf-8",
+    )
+}
+WASM_EXTENSION_STATIC_MIME_TYPES = {
+    ".css": "text/css; charset=utf-8",
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".js": "text/javascript; charset=utf-8",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+}
+WASM_EXTENSION_TEXT_STATIC_EXTENSIONS = {".css", ".js"}
+WASM_EXTENSION_HTML_PREFIXES = (b"<!doctype", b"<html", b"<script")
+
+
+class GuardedWasmExtensionStaticFiles(StaticFiles):
+    async def get_response(self, path: str, scope: Scope) -> Response:
+        if path.startswith(f"{WASM_EXTENSION_CORE_ASSET_PREFIX}/"):
+            return _wasm_extension_core_asset_response(path)
+        if Path(path).suffix.lower() not in WASM_EXTENSION_STATIC_MIME_TYPES:
+            raise HTTPException(status_code=404)
+        return await super().get_response(path, scope)
+
+    def file_response(
+        self,
+        full_path: StaticFilesPathLike,
+        stat_result: os.stat_result,
+        scope: Scope,
+        status_code: int = 200,
+    ) -> Response:
+        suffix = Path(full_path).suffix.lower()
+        if suffix in WASM_EXTENSION_TEXT_STATIC_EXTENSIONS:
+            _reject_html_like_wasm_static_asset(Path(full_path))
+
+        response = super().file_response(full_path, stat_result, scope, status_code)
+        response.headers["Content-Type"] = WASM_EXTENSION_STATIC_MIME_TYPES[suffix]
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Cache-Control"] = "no-store"
+        return response
+
+
+def register_wasm_extension(app: FastAPI, ext_id: str) -> WasmExtension:
+    loaded = load_wasm_extension(ext_id)
+
+    warm_wasm_extension(loaded)
+    _mount_wasm_extension_static(app, loaded)
+    _register_wasm_extension_ui_routes(app, loaded)
+    _register_wasm_extension_api_routes(app, loaded)
+
+    core_app_extra.wasm_extension_registry.register(loaded)
+
+    settings.activate_extension_paths(ext_id, "", [])
+    logger.info(
+        f"Loaded WASM extension '{loaded.id}' "
+        f"({loaded.module_path.stat().st_size} bytes)."
+    )
+    return loaded
+
+
+def _mount_wasm_extension_static(app: FastAPI, extension: WasmExtension) -> None:
+    static_path = extension.root_path / "static"
+
+    mount_path = f"/ext-assets/{extension.id}"
+    if any(getattr(route, "path", None) == mount_path for route in app.routes):
+        return
+
+    app.mount(
+        mount_path,
+        GuardedWasmExtensionStaticFiles(directory=static_path, check_dir=False),
+        name=f"{extension.id}-static",
+    )
+
+
+def _register_wasm_extension_ui_routes(app: FastAPI, extension: WasmExtension) -> None:
+    _add_wasm_extension_frame_config_route(app, extension)
+
+    for route_index, route_config in enumerate(extension.config.get("ui_routes") or []):
+        route_path = _wasm_extension_ui_route_path(extension, route_config.get("path"))
+        entrypoint = _wasm_extension_entrypoint(
+            extension, route_config.get("entrypoint")
+        )
+        frame_path = f"/ext-frame/{extension.id}/{route_index}"
+        auth = _wasm_extension_route_auth(extension, route_config.get("auth"))
+        _add_wasm_extension_frame_route(app, extension, frame_path, entrypoint)
+        _add_wasm_extension_wrapper_route(
+            app,
+            extension,
+            route_path,
+            auth,
+        )
+
+
+def _register_wasm_extension_api_routes(app: FastAPI, extension: WasmExtension) -> None:
+    for route_config in extension.config.get("api_routes") or []:
+        _add_wasm_extension_api_route(app, extension, route_config)
+
+
+def _add_wasm_extension_api_route(
+    app: FastAPI,
+    extension: WasmExtension,
+    route_config: dict[str, Any],
+) -> None:
+    method = _wasm_extension_api_method(extension, route_config.get("method"))
+    route_path = _wasm_extension_api_path(extension, route_config.get("path"))
+    export_name = _wasm_extension_api_export(extension, route_config.get("export"))
+    path_params = route_config.get("path_params") or {}
+    auth = _wasm_extension_route_auth(extension, route_config.get("auth"))
+
+    if _has_route(app, route_path, method):
+        return
+
+    async def invoke_wasm_api_request(
+        request: Request,
+        account: Account | None = None,
+        access_token: str | None = None,
+    ) -> dict[str, Any]:
+        try:
+            payload = await _read_api_payload(request, path_params)
+            return await invoke_wasm_extension_export(
+                extension.id,
+                export_name,
+                payload,
+                user=account,
+                access_token=access_token,
+            )
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc)) from exc
+        except (TypeError, ValueError) as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    async def invoke_private_wasm_extension_export(
+        request: Request,
+        access_token: Annotated[str | None, Depends(check_access_token)],
+        account: Account = Depends(check_account_exists),
+    ) -> dict[str, Any]:
+        return await invoke_wasm_api_request(request, account, access_token)
+
+    async def invoke_public_wasm_extension_export(request: Request) -> dict[str, Any]:
+        return await invoke_wasm_api_request(request)
+
+    app.add_api_route(
+        route_path,
+        (
+            invoke_public_wasm_extension_export
+            if auth == "public"
+            else invoke_private_wasm_extension_export
+        ),
+        methods=[method],
+        name=f"{extension.id}:{method}:{route_path}",
+        include_in_schema=False,
+    )
+
+
+def _add_wasm_extension_frame_config_route(
+    app: FastAPI,
+    extension: WasmExtension,
+) -> None:
+    route_path = _wasm_extension_frame_config_path(extension)
+    if _has_route(app, route_path, "POST"):
+        return
+
+    async def create_wasm_extension_frame_config(
+        request: Request,
+        access_token: Annotated[str | None, Depends(check_access_token)],
+        usr: UUID4 | None = None,
+    ) -> dict[str, Any]:
+        try:
+            body = await _read_json_object(request)
+        except (TypeError, ValueError) as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+        ui_route = _match_wasm_extension_ui_route(extension, body.get("path"))
+        auth = ui_route["auth"]
+
+        if auth == "user":
+            account = await check_account_exists(request, access_token, usr)
+            user_id: str | None = account.id
+        else:
+            user_id = await _optional_wasm_user_id(request, access_token, usr)
+
+        granted_permission_ids = await _wasm_extension_granted_permission_ids(extension)
+
+        return _wasm_extension_frame_config(
+            extension,
+            ui_route["frame_path"],
+            auth,
+            ui_route["path_params"],
+            ui_route["route_params"],
+            _read_wasm_extension_route_query(body.get("query")),
+            user_id,
+            granted_permission_ids,
+        )
+
+    app.add_api_route(
+        route_path,
+        create_wasm_extension_frame_config,
+        methods=["POST"],
+        name=f"{extension.id}:frame-config",
+        include_in_schema=False,
+    )
+
+
+async def _read_api_payload(
+    request: Request,
+    path_params: dict[str, str],
+) -> dict[str, Any]:
+    payload = _read_api_path_params(request, path_params)
+    payload.update(_read_api_query_params(request))
+    if request.method in {"POST", "PUT", "PATCH"}:
+        payload.update(await _read_json_object(request))
+    return payload
+
+
+async def _read_json_object(request: Request) -> dict[str, Any]:
+    body = await request.body()
+    if not body:
+        return {}
+    value = json.loads(body)
+    if not isinstance(value, dict):
+        raise TypeError("WASM extension API payload must be a JSON object.")
+    return value
+
+
+def _read_api_path_params(
+    request: Request,
+    path_params: dict[str, str],
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    for key, value in request.path_params.items():
+        target = path_params.get(key) or _snake_to_camel(key)
+        payload[target] = value
+    return payload
+
+
+def _read_api_query_params(request: Request) -> dict[str, Any]:
+    return {_snake_to_camel(key): value for key, value in request.query_params.items()}
+
+
+def _wasm_extension_api_export(extension: WasmExtension, export_name: Any) -> str:
+    if not isinstance(export_name, str) or not export_name:
+        raise ValueError(f"Invalid API export for WASM extension '{extension.id}'.")
+
+    for export in extension.exports:
+        if export.get("name") != export_name:
+            continue
+        if export.get("visibility") in {"public", "authenticated"}:
+            return export_name
+        raise PermissionError(f"WASM export '{export_name}' is not callable over HTTP.")
+    raise KeyError(f"WASM extension '{extension.id}' has no export '{export_name}'.")
+
+
+def _wasm_extension_api_method(extension: WasmExtension, method: Any) -> str:
+    if not isinstance(method, str):
+        raise ValueError(f"Invalid API method for WASM extension '{extension.id}'.")
+    method = method.upper()
+    if method not in {"GET", "POST", "PUT", "PATCH", "DELETE"}:
+        raise ValueError(f"Unsupported API method for WASM extension '{extension.id}'.")
+    return method
+
+
+def _wasm_extension_api_path(extension: WasmExtension, path: Any) -> str:
+    if not isinstance(path, str) or not path.startswith("/"):
+        raise ValueError(f"Invalid API path for WASM extension '{extension.id}'.")
+    if path == "/":
+        return f"/api/v1/ext/{extension.id}"
+    return f"/api/v1/ext/{extension.id}{path}"
+
+
+def _has_route(app: FastAPI, route_path: str, method: str) -> bool:
+    for route in app.routes:
+        if getattr(route, "path", None) != route_path:
+            continue
+        methods = getattr(route, "methods", set()) or set()
+        if method in methods:
+            return True
+    return False
+
+
+def _snake_to_camel(value: str) -> str:
+    head, *tail = value.split("_")
+    return head + "".join(part.capitalize() for part in tail)
+
+
+def _add_wasm_extension_wrapper_route(
+    app: FastAPI,
+    extension: WasmExtension,
+    route_path: str,
+    auth: str,
+) -> None:
+    if _has_route(app, route_path, "GET"):
+        return
+
+    async def serve_private_wasm_extension_page(
+        request: Request,
+        account: Account = Depends(check_account_exists),
+    ) -> Any:
+        user = await get_user_from_account(account)
+        return _wasm_extension_wrapper_response(
+            request,
+            extension,
+            auth,
+            user.json() if user else None,
+        )
+
+    async def serve_public_wasm_extension_page(request: Request) -> Any:
+        return _wasm_extension_wrapper_response(
+            request,
+            extension,
+            auth,
+            None,
+        )
+
+    app.add_api_route(
+        route_path,
+        (
+            serve_public_wasm_extension_page
+            if auth == "public"
+            else serve_private_wasm_extension_page
+        ),
+        methods=["GET"],
+        name=f"{extension.id}:{route_path}",
+        include_in_schema=False,
+    )
+
+
+def _add_wasm_extension_frame_route(
+    app: FastAPI,
+    extension: WasmExtension,
+    frame_path: str,
+    entrypoint: Path,
+) -> None:
+    if _has_route(app, frame_path, "GET"):
+        return
+
+    async def serve_wasm_extension_frame(
+        request: Request,
+        user_id: str | None = Depends(_optional_wasm_user_id),
+    ) -> FileResponse:
+        _consume_wasm_extension_frame_token(request, extension, frame_path, user_id)
+        response = FileResponse(entrypoint)
+        response.headers["Content-Security-Policy"] = _wasm_extension_frame_csp(
+            request, extension
+        )
+        response.headers["Cache-Control"] = "no-store"
+        response.headers["Cross-Origin-Opener-Policy"] = "same-origin"
+        response.headers["Cross-Origin-Resource-Policy"] = "same-origin"
+        # Extension access goes through the parent bridge.
+        response.headers["Permissions-Policy"] = (
+            "camera=(), microphone=(), geolocation=(), payment=(), "
+            "clipboard-read=(), usb=()"
+        )
+        response.headers["Referrer-Policy"] = "no-referrer"
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        return response
+
+    app.add_api_route(
+        frame_path,
+        serve_wasm_extension_frame,
+        methods=["GET"],
+        name=f"{extension.id}:frame:{frame_path}",
+        include_in_schema=False,
+    )
+
+
+def _wasm_extension_wrapper_response(
+    request: Request,
+    extension: WasmExtension,
+    auth: str,
+    user_json: str | None,
+) -> Any:
+    public = auth == "public"
+    response = template_renderer().TemplateResponse(
+        request,
+        "wasm_extension.html",
+        {
+            "extension": extension,
+            "public": public,
+            "user": user_json,
+        },
+    )
+    response.headers["Content-Security-Policy"] = "frame-ancestors 'self'"
+    response.headers["X-Frame-Options"] = "SAMEORIGIN"
+    return response
+
+
+def _wasm_extension_frame_csp(request: Request, extension: WasmExtension) -> str:
+    origin = str(request.base_url).rstrip("/")
+    extension_assets = f"{origin}/ext-assets/{extension.id}/"
+    return (
+        "sandbox allow-scripts; "
+        "default-src 'none'; "
+        f"script-src {extension_assets}; "
+        "script-src-attr 'none'; "
+        f"style-src {extension_assets}; "
+        "style-src-attr 'none'; "
+        f"img-src {extension_assets} data:; "
+        f"font-src {extension_assets}; "
+        "connect-src 'none'; "
+        "form-action 'none'; "
+        "object-src 'none'; "
+        "base-uri 'none'; "
+        "frame-src 'none'; "
+        "worker-src 'none'; "
+        "media-src 'none'; "
+        "manifest-src 'none'; "
+        "frame-ancestors 'self'"
+    )
+
+
+def _wasm_extension_frame_url(
+    extension: WasmExtension, frame_path: str, user_id: str | None
+) -> str:
+    token = _create_wasm_extension_frame_token(extension, frame_path, user_id)
+    return f"{frame_path}?frame_token={token}"
+
+
+def _create_wasm_extension_frame_token(
+    extension: WasmExtension,
+    frame_path: str,
+    user_id: str | None,
+) -> str:
+    token = uuid4().hex
+    cache.set(
+        _wasm_extension_frame_token_cache_key(token),
+        {
+            "extension_id": extension.id,
+            "frame_path": frame_path,
+            "user_id": user_id,
+        },
+        expiry=WASM_FRAME_TOKEN_EXPIRY_SECONDS,
+    )
+    return token
+
+
+def _consume_wasm_extension_frame_token(
+    request: Request,
+    extension: WasmExtension,
+    frame_path: str,
+    user_id: str | None,
+) -> None:
+    token = request.query_params.get("frame_token")
+    if not token:
+        _raise_wasm_extension_frame_not_found(extension, frame_path, "missing")
+
+    cache_key = _wasm_extension_frame_token_cache_key(token)
+    token_data = cache.get(cache_key)
+    if (
+        not isinstance(token_data, dict)
+        or token_data.get("extension_id") != extension.id
+        or token_data.get("frame_path") != frame_path
+    ):
+        _raise_wasm_extension_frame_not_found(
+            extension, frame_path, "unknown or expired"
+        )
+
+    token_user_id = token_data.get("user_id")
+    if token_user_id and token_user_id != user_id:
+        _raise_wasm_extension_frame_not_found(extension, frame_path, "wrong user")
+
+    cache.pop(cache_key)
+
+
+def _wasm_extension_frame_token_cache_key(token: str) -> str:
+    return f"wasm-frame-token:{token}"
+
+
+def _raise_wasm_extension_frame_not_found(
+    extension: WasmExtension,
+    frame_path: str,
+    reason: str,
+) -> NoReturn:
+    logger.warning(
+        f"WASM frame token {reason} for extension '{extension.id}' at '{frame_path}'."
+    )
+    raise HTTPException(status_code=404, detail="Not found")
+
+
+def _wasm_extension_bridge_api_routes(
+    extension: WasmExtension,
+    public: bool,
+) -> list[dict[str, str]]:
+    routes: list[dict[str, str]] = []
+    for route_config in extension.config.get("api_routes") or []:
+        auth = _wasm_extension_route_auth(extension, route_config.get("auth"))
+        if public and auth != "public":
+            continue
+        method = _wasm_extension_api_method(extension, route_config.get("method"))
+        path = _wasm_extension_api_path(extension, route_config.get("path"))
+        _wasm_extension_api_export(extension, route_config.get("export"))
+        routes.append(
+            {
+                "method": method,
+                "path": path,
+                "pattern": _path_template_pattern(path),
+            }
+        )
+    return routes
+
+
+def _wasm_extension_frame_config_path(extension: WasmExtension) -> str:
+    return f"/api/v1/ext/{extension.id}/_ui/frame"
+
+
+def _match_wasm_extension_ui_route(
+    extension: WasmExtension,
+    path: Any,
+) -> dict[str, Any]:
+    if not isinstance(path, str) or not path.startswith("/"):
+        raise HTTPException(status_code=404, detail="Not found")
+
+    for route_index, route_config in enumerate(extension.config.get("ui_routes") or []):
+        route_path = _wasm_extension_ui_route_path(extension, route_config.get("path"))
+        route_params = _path_template_params(route_path, path)
+        if route_params is None:
+            continue
+
+        return {
+            "frame_path": f"/ext-frame/{extension.id}/{route_index}",
+            "auth": _wasm_extension_route_auth(extension, route_config.get("auth")),
+            "path_params": route_config.get("path_params") or {},
+            "route_params": route_params,
+        }
+
+    raise HTTPException(status_code=404, detail="Not found")
+
+
+def _path_template_params(template: str, path: str) -> dict[str, str] | None:
+    template_parts = _path_parts(template)
+    path_parts = _path_parts(path)
+    if len(template_parts) != len(path_parts):
+        return None
+
+    params: dict[str, str] = {}
+    for template_part, path_part in zip(template_parts, path_parts, strict=False):
+        if template_part.startswith("{") and template_part.endswith("}"):
+            param_name = template_part[1:-1]
+            if not param_name:
+                return None
+            params[param_name] = path_part
+            continue
+
+        if template_part != path_part:
+            return None
+
+    return params
+
+
+def _path_parts(path: str) -> list[str]:
+    return [part for part in path.strip("/").split("/") if part]
+
+
+def _wasm_extension_frame_config(
+    extension: WasmExtension,
+    frame_path: str,
+    auth: str,
+    path_params: dict[str, str],
+    route_params: dict[str, str],
+    query: dict[str, Any],
+    user_id: str | None,
+    permissions: set[str],
+) -> dict[str, Any]:
+    public = auth == "public"
+    return {
+        "extension": {
+            "id": extension.id,
+            "name": extension.name,
+        },
+        "frameUrl": _wasm_extension_frame_url(extension, frame_path, user_id),
+        "bridge": {
+            "extensionId": extension.id,
+            "public": public,
+            "routeParams": _map_wasm_extension_route_params(route_params, path_params),
+            "query": query,
+            "permissions": sorted(permissions),
+            "apiRoutes": _wasm_extension_bridge_api_routes(extension, public),
+        },
+    }
+
+
+async def _wasm_extension_granted_permission_ids(
+    extension: WasmExtension,
+) -> set[str]:
+    installed_extension = await get_installed_extension(extension.id)
+    if not installed_extension:
+        return set()
+    return {permission.id for permission in installed_extension.permissions}
+
+
+def _map_wasm_extension_route_params(
+    route_params: dict[str, str],
+    path_params: dict[str, str],
+) -> dict[str, str]:
+    payload: dict[str, str] = {}
+    for key, value in route_params.items():
+        target = path_params.get(key) or _snake_to_camel(key)
+        payload[target] = value
+    return payload
+
+
+def _read_wasm_extension_route_query(query: Any) -> dict[str, Any]:
+    if not isinstance(query, dict):
+        return {}
+
+    payload: dict[str, Any] = {}
+    for key, value in query.items():
+        if value is None:
+            continue
+        payload[_snake_to_camel(str(key))] = value
+    return payload
+
+
+def _path_template_pattern(path: str) -> str:
+    pattern = re.sub(r"\\{[^/{}]+\\}", r"[^/]+", re.escape(path))
+    return f"^{pattern}$"
+
+
+async def _optional_wasm_user_id(
+    request: Request,
+    access_token: Annotated[str | None, Depends(check_access_token)],
+    usr: UUID4 | None = None,
+) -> str | None:
+    try:
+        return await optional_user_id(request, access_token, usr)
+    except HTTPException:
+        return None
+
+
+def _wasm_extension_route_auth(extension: WasmExtension, auth: Any) -> str:
+    if auth in {"public", "user"}:
+        return auth
+    raise ValueError(f"Invalid route auth for WASM extension '{extension.id}'.")
+
+
+def _wasm_extension_ui_route_path(extension: WasmExtension, path: Any) -> str:
+    if not isinstance(path, str) or not path.startswith("/"):
+        raise ValueError(f"Invalid route path for WASM extension '{extension.id}'.")
+    if path == "/":
+        return "/ext"
+    return f"/ext{path}"
+
+
+def _wasm_extension_entrypoint(extension: WasmExtension, entrypoint: Any) -> Path:
+    if not isinstance(entrypoint, str) or not entrypoint:
+        raise ValueError(
+            f"Invalid route entrypoint for WASM extension '{extension.id}'."
+        )
+    if entrypoint.startswith("/"):
+        raise ValueError(
+            f"Route entrypoint for WASM extension '{extension.id}' must be a "
+            "relative extension path."
+        )
+
+    path = (extension.root_path / entrypoint).resolve()
+    root_path = extension.root_path.resolve()
+    if path != root_path and root_path not in path.parents:
+        raise ValueError(f"Route entrypoint escapes extension root: {entrypoint}")
+
+    static_path = (extension.root_path / "static").resolve()
+    if path == static_path or static_path in path.parents:
+        raise ValueError(
+            f"Route entrypoint for WASM extension '{extension.id}' must not be "
+            "inside the static asset directory."
+        )
+    if path.suffix.lower() != ".html":
+        raise ValueError(
+            f"Route entrypoint for WASM extension '{extension.id}' must be "
+            "an HTML file."
+        )
+    if not path.is_file():
+        raise FileNotFoundError(f"Route entrypoint not found: {path}")
+    return path
+
+
+def _reject_html_like_wasm_static_asset(path: Path) -> None:
+    with path.open("rb") as asset_file:
+        prefix = asset_file.read(512).lstrip().lower()
+    if prefix.startswith(WASM_EXTENSION_HTML_PREFIXES):
+        raise HTTPException(status_code=404)
+
+
+def _wasm_extension_core_asset_response(path: str) -> Response:
+    asset_name = path.removeprefix(f"{WASM_EXTENSION_CORE_ASSET_PREFIX}/")
+    if not asset_name or "/" in asset_name or "\\" in asset_name:
+        raise HTTPException(status_code=404)
+
+    generated_asset = WASM_EXTENSION_GENERATED_CORE_ASSETS.get(asset_name)
+    if generated_asset:
+        content, content_type = generated_asset
+        response = Response(content=content, media_type=content_type)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Cache-Control"] = "no-store"
+        return response
+
+    asset_config = WASM_EXTENSION_CORE_STATIC_ASSETS.get(asset_name)
+    if not asset_config:
+        raise HTTPException(status_code=404)
+
+    relative_path, content_type = asset_config
+    asset_path = Path(settings.lnbits_path, relative_path)
+    if not asset_path.is_file():
+        raise HTTPException(status_code=404)
+
+    response = FileResponse(asset_path)
+    response.headers["Content-Type"] = content_type
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["Cache-Control"] = "no-store"
+    return response

lnbits/core/extensions/runtime.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any
+
+from pydantic import BaseModel
+
+from .api import ExtensionAPI, ExtensionAPIMethod, list_extension_api_methods
+
+HostImport = Callable[..., Awaitable[dict[str, Any]]]
+
+
+class ExtensionAPIHost:
+    def __init__(
+        self,
+        api: ExtensionAPI,
+        *,
+        api_cls: type[ExtensionAPI] = ExtensionAPI,
+    ) -> None:
+        self.api = api
+        self.methods = list_extension_api_methods(api_cls)
+        self._methods_by_host_name = self._index_methods(self.methods)
+
+    async def invoke(
+        self,
+        host_name: str,
+        payload: Mapping[str, Any] | BaseModel | None = None,
+    ) -> dict[str, Any]:
+        method = self._require_method(host_name)
+        request = self._request_model(method, payload)
+        handler = _resolve_attr_path(self.api, method.python_name)
+        response = handler(request)
+        if inspect.isawaitable(response):
+            response = await response
+        return self._response_payload(method, response)
+
+    def imports(self) -> dict[str, HostImport]:
+        return self.imports_for_interface("host")
+
+    def import_object(self) -> dict[str, dict[str, HostImport]]:
+        interfaces = sorted({method.host_interface for method in self.methods})
+        return {
+            f"lnbits:extension/{interface}": self.imports_for_interface(interface)
+            for interface in interfaces
+        }
+
+    def imports_for_interface(self, host_interface: str) -> dict[str, HostImport]:
+        return {
+            _snake_to_camel(method.host_name): self._make_import(method)
+            for method in self.methods
+            if method.host_interface == host_interface
+        }
+
+    def _make_import(self, method: ExtensionAPIMethod) -> HostImport:
+        async def host_import(
+            payload: Mapping[str, Any] | BaseModel | None = None,
+        ) -> dict[str, Any]:
+            return await self.invoke(method.method_id, payload)
+
+        return host_import
+
+    def _require_method(self, host_name: str) -> ExtensionAPIMethod:
+        method = self._methods_by_host_name.get(host_name)
+        if not method:
+            raise KeyError(f"Unknown extension host function '{host_name}'.")
+        return method
+
+    @staticmethod
+    def _index_methods(
+        methods: list[ExtensionAPIMethod],
+    ) -> dict[str, ExtensionAPIMethod]:
+        index: dict[str, ExtensionAPIMethod] = {}
+        for method in methods:
+            for host_name in {
+                method.method_id,
+                f"{method.host_interface}:{method.host_name}",
+                method.host_name,
+                _snake_to_camel(method.host_name),
+                method.host_name.replace("_", "-"),
+            }:
+                index[host_name] = method
+        return index
+
+    @staticmethod
+    def _request_model(
+        method: ExtensionAPIMethod,
+        payload: Mapping[str, Any] | BaseModel | None,
+    ) -> BaseModel:
+        if isinstance(payload, method.request_model):
+            return payload
+        if isinstance(payload, BaseModel):
+            payload = payload.dict()
+        if payload is None:
+            payload = {}
+        if not isinstance(payload, Mapping):
+            raise TypeError(
+                f"Host function '{method.host_name}' expects an object payload."
+            )
+        data = {_to_snake(key): value for key, value in payload.items()}
+        if isinstance(data.get("extra"), list):
+            data["extra"] = dict(data["extra"])
+        if isinstance(data.get("headers"), list):
+            data["headers"] = dict(data["headers"])
+        return method.request_model.parse_obj(data)
+
+    @staticmethod
+    def _response_payload(
+        method: ExtensionAPIMethod,
+        response: Any,
+    ) -> dict[str, Any]:
+        if not isinstance(response, method.response_model):
+            response = method.response_model.parse_obj(response)
+        payload = response.dict()
+        if method.method_id in {"http.request", "extension.api.request"} and isinstance(
+            payload.get("headers"), Mapping
+        ):
+            payload["headers"] = list(payload["headers"].items())
+        return {_snake_to_camel(key): value for key, value in payload.items()}
+
+
+def _snake_to_camel(value: str) -> str:
+    head, *tail = value.split("_")
+    return head + "".join(part.capitalize() for part in tail)
+
+
+def _to_snake(value: str) -> str:
+    value = value.replace("-", "_")
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", value).lower()
+
+
+def _resolve_attr_path(value: Any, path: str) -> Any:
+    for part in path.split("."):
+        value = getattr(value, part)
+    return value

lnbits/core/extensions/storage.py

@@ -0,0 +1,627 @@
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from lnbits.core.crud import update_migration_version
+from lnbits.core.db import db as core_db
+from lnbits.core.models import DbVersion
+from lnbits.core.models.extensions import InstallableExtension
+from lnbits.db import POSTGRES, SQLITE, Connection, Database
+from lnbits.settings import settings
+
+_MIGRATION_FILE_RE = re.compile(r"^(\d+)_.*\.json$")
+_SQL_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+OWNER_ID_FIELD = "__lnbits_owner_id__"
+
+
+async def storage_get_row(
+    ext_id: str,
+    table: str,
+    row_id: str,
+    owner_id: str,
+) -> dict[str, Any] | None:
+    table_schema = _load_table_schema(ext_id, table)
+    query = f"""
+        SELECT * FROM {_table_ref_for_schema(ext_id, table)}
+        WHERE id = :id AND {OWNER_ID_FIELD} = :owner_id
+    """  # noqa: S608
+    async with Database(f"ext_{ext_id}").connect() as conn:
+        row = await conn.fetchone(query, {"id": row_id, "owner_id": owner_id})
+    return _row_from_db(table_schema, row) if row else None
+
+
+async def storage_get_public_row(
+    ext_id: str,
+    table: str,
+    row_id: str,
+) -> dict[str, Any] | None:
+    table_schema = _load_table_schema(ext_id, table)
+    query = f"""
+        SELECT * FROM {_table_ref_for_schema(ext_id, table)}
+        WHERE id = :id
+    """  # noqa: S608
+    async with Database(f"ext_{ext_id}").connect() as conn:
+        row = await conn.fetchone(query, {"id": row_id})
+    return _row_from_db(table_schema, row) if row else None
+
+
+async def storage_get_row_owner_id(
+    ext_id: str,
+    table: str,
+    row_id: str,
+) -> str | None:
+    _load_table_schema(ext_id, table)
+    query = f"""
+        SELECT {OWNER_ID_FIELD} FROM {_table_ref_for_schema(ext_id, table)}
+        WHERE id = :id
+    """  # noqa: S608
+    async with Database(f"ext_{ext_id}").connect() as conn:
+        row = await conn.fetchone(query, {"id": row_id})
+
+    owner_id = row[OWNER_ID_FIELD] if row else None
+    return owner_id if isinstance(owner_id, str) and owner_id else None
+
+
+async def storage_set_row(
+    ext_id: str,
+    table: str,
+    data: dict[str, Any],
+    owner_id: str,
+) -> None:
+    table_schema = _load_table_schema(ext_id, table)
+    clean_data = _data_to_db(table_schema, data, require_id=True)
+    clean_data[OWNER_ID_FIELD] = owner_id
+    columns = list(clean_data.keys())
+    placeholders = [f":{column}" for column in columns]
+    updates = [
+        f"{column} = excluded.{column}"
+        for column in columns
+        if column not in ("id", OWNER_ID_FIELD)
+    ]
+    conflict_sql = (
+        "DO UPDATE SET "
+        + ", ".join(updates)
+        + f" WHERE {OWNER_ID_FIELD} = :{OWNER_ID_FIELD}"
+        if updates
+        else "DO NOTHING"
+    )
+    query = f"""
+        INSERT INTO {_table_ref_for_schema(ext_id, table)}
+            ({", ".join(columns)})
+        VALUES
+            ({", ".join(placeholders)})
+        ON CONFLICT (id) {conflict_sql}
+    """  # noqa: S608
+
+    async with Database(f"ext_{ext_id}").connect() as conn:
+        await conn.execute(query, clean_data)
+
+
+async def storage_get_paginated_rows(
+    ext_id: str,
+    table: str,
+    filters: dict[str, Any],
+    *,
+    owner_id: str,
+    search: str | None,
+    search_fields: list[str],
+    sort_by: str | None,
+    descending: bool,
+    limit: int,
+    offset: int,
+) -> dict[str, Any]:
+    table_schema = _load_table_schema(ext_id, table)
+    where_sql, values = _where_sql(table_schema, filters, search, search_fields)
+    where_sql = _append_owner_where_sql(where_sql)
+    values[OWNER_ID_FIELD] = owner_id
+    order_sql = _order_sql(table_schema, sort_by, descending)
+    count_values = dict(values)
+    values.update({"limit": min(limit, 1000), "offset": offset})
+
+    table_ref = _table_ref_for_schema(ext_id, table)
+    rows_query = f"""
+        SELECT * FROM {table_ref}
+        {where_sql}
+        {order_sql}
+        LIMIT :limit
+        OFFSET :offset
+    """  # noqa: S608
+    count_query = f"""
+        SELECT COUNT(*) AS count FROM {table_ref}
+        {where_sql}
+    """  # noqa: S608
+
+    async with Database(f"ext_{ext_id}").connect() as conn:
+        rows = await conn.fetchall(rows_query, values)
+        count_row = await conn.fetchone(count_query, count_values)
+
+    return {
+        "data": [_row_from_db(table_schema, row) for row in rows],
+        "total": int(count_row["count"]) if count_row else 0,
+    }
+
+
+async def storage_delete_row(
+    ext_id: str,
+    table: str,
+    row_id: str,
+    owner_id: str,
+) -> None:
+    _load_table_schema(ext_id, table)
+    query = f"""
+        DELETE FROM {_table_ref_for_schema(ext_id, table)}
+        WHERE id = :id AND {OWNER_ID_FIELD} = :owner_id
+    """  # noqa: S608
+    async with Database(f"ext_{ext_id}").connect() as conn:
+        await conn.execute(query, {"id": row_id, "owner_id": owner_id})
+
+
+async def migrate_wasm_extension_database(
+    ext: InstallableExtension,
+    current_version: DbVersion | None = None,
+) -> None:
+    migrations_dir = ext.ext_dir / "storage" / "migrations"
+    migration_files = _migration_files(migrations_dir)
+    if not migration_files:
+        logger.debug(f"No storage migrations for WASM extension '{ext.id}'.")
+        return
+
+    ext_db = Database(f"ext_{ext.id}")
+    async with ext_db.connect() as conn:
+        for version, path in migration_files:
+            if current_version and version <= current_version.version:
+                continue
+            logger.debug(f"running WASM storage migration {ext.id}.{version}")
+            print(f"running migration {ext.id}.{version}")
+            await _run_storage_migration(conn, path)
+            await _update_wasm_migration_version(conn, ext.id, version)
+
+
+def _migration_files(migrations_dir: Path) -> list[tuple[int, Path]]:
+    if not migrations_dir.is_dir():
+        return []
+
+    files: list[tuple[int, Path]] = []
+    for path in migrations_dir.glob("*.json"):
+        match = _MIGRATION_FILE_RE.match(path.name)
+        if not match:
+            raise ValueError(f"Invalid WASM storage migration filename: {path.name}")
+        files.append((int(match.group(1)), path))
+    return sorted(files)
+
+
+async def _run_storage_migration(db: Connection, path: Path) -> None:
+    migration = _load_json(path)
+    operations = migration.get("operations")
+    if not isinstance(operations, list):
+        raise ValueError(f"WASM storage migration '{path}' has no operations list.")
+
+    for operation in operations:
+        if not isinstance(operation, dict):
+            raise ValueError(f"WASM storage migration '{path}' has invalid operation.")
+        sql = _operation_sql(db, operation)
+        await db.execute(sql)
+
+
+def _operation_sql(db: Connection, operation: dict[str, Any]) -> str:
+    op = operation.get("op")
+    if op == "create_table":
+        return _create_table_sql(db, operation)
+    if op == "add_field":
+        return _add_field_sql(db, operation)
+    if op == "create_index":
+        return _create_index_sql(db, operation)
+    raise ValueError(f"Unsupported WASM storage migration operation: {op}")
+
+
+def _create_table_sql(db: Connection, operation: dict[str, Any]) -> str:
+    table = _require_identifier(operation, "table")
+    fields = _require_fields(operation)
+    if not any(field.get("name") == "id" for field in fields):
+        raise ValueError(f"WASM storage table '{table}' must define an id field.")
+    if any(field.get("name") == OWNER_ID_FIELD for field in fields):
+        raise ValueError(
+            f"WASM storage table '{table}' defines reserved field '{OWNER_ID_FIELD}'."
+        )
+
+    columns = [
+        _column_sql(db, field, primary_key=field.get("name") == "id")
+        for field in fields
+    ]
+    columns.append(f"{OWNER_ID_FIELD} TEXT NOT NULL")
+    return f"""
+        CREATE TABLE IF NOT EXISTS {_table_ref(db, table)} (
+            {", ".join(columns)}
+        );
+    """
+
+
+def _add_field_sql(db: Connection, operation: dict[str, Any]) -> str:
+    table = _require_identifier(operation, "table")
+    field = _field_from_add_field_operation(operation)
+    if field["name"] == OWNER_ID_FIELD:
+        raise ValueError(
+            f"WASM storage table '{table}' cannot add reserved field "
+            f"'{OWNER_ID_FIELD}'."
+        )
+    return f"""
+        ALTER TABLE {_table_ref(db, table)}
+        ADD COLUMN {_column_sql(db, field)};
+    """
+
+
+def _create_index_sql(db: Connection, operation: dict[str, Any]) -> str:
+    table = _require_identifier(operation, "table")
+    name = _require_identifier(operation, "name")
+    field = _require_identifier(operation, "field")
+    if field == OWNER_ID_FIELD:
+        raise ValueError(
+            f"WASM storage table '{table}' cannot index reserved field "
+            f"'{OWNER_ID_FIELD}'."
+        )
+
+    if db.type == SQLITE and db.schema:
+        return f"""
+            CREATE INDEX IF NOT EXISTS {_schema_ref(db, name)}
+            ON {table} ({field});
+        """
+
+    return f"""
+        CREATE INDEX IF NOT EXISTS {name}
+        ON {_table_ref(db, table)} ({field});
+    """
+
+
+def _column_sql(
+    db: Connection,
+    field: dict[str, Any],
+    *,
+    primary_key: bool = False,
+) -> str:
+    name = _require_identifier(field, "name")
+    column_type = _field_type_sql(db, field)
+    parts = [name, column_type]
+
+    if primary_key:
+        parts.append("PRIMARY KEY")
+    elif not field.get("nullable", False):
+        parts.append("NOT NULL")
+
+    if "default" in field:
+        parts.append(f"DEFAULT {_default_sql(field['default'])}")
+
+    return " ".join(parts)
+
+
+def _field_type_sql(db: Connection, field: dict[str, Any]) -> str:
+    if field.get("list") is True:
+        return "TEXT"
+
+    field_type = field.get("type")
+    if field_type == "string":
+        return "TEXT"
+    if field_type == "integer":
+        return db.big_int
+    if field_type == "number":
+        return "DOUBLE PRECISION" if db.type == POSTGRES else "REAL"
+    if field_type == "boolean":
+        return "BOOLEAN"
+    if field_type == "datetime":
+        return "TIMESTAMP"
+    raise ValueError(f"Unsupported WASM storage field type: {field_type}")
+
+
+def _load_table_schema(ext_id: str, table: str) -> dict[str, Any]:
+    schema = _load_storage_schema(ext_id)
+    tables = schema.get("tables")
+    if not isinstance(tables, dict):
+        raise ValueError(f"WASM extension '{ext_id}' has no storage tables schema.")
+
+    _require_identifier({"table": table}, "table")
+    table_schema = tables.get(table)
+    if not isinstance(table_schema, dict):
+        raise ValueError(f"WASM extension '{ext_id}' has no storage table '{table}'.")
+
+    fields = table_schema.get("fields")
+    if not isinstance(fields, list) or not fields:
+        raise ValueError(f"WASM storage table '{table}' has no fields schema.")
+
+    for field in fields:
+        if not isinstance(field, dict):
+            raise ValueError(f"WASM storage table '{table}' has invalid field schema.")
+        _require_identifier(field, "name")
+        if field["name"] == OWNER_ID_FIELD:
+            raise ValueError(
+                f"WASM storage table '{table}' defines reserved field "
+                f"'{OWNER_ID_FIELD}'."
+            )
+    return table_schema
+
+
+def _load_storage_schema(ext_id: str) -> dict[str, Any]:
+    schema_path = (
+        Path(settings.lnbits_extensions_path)
+        / "extensions"
+        / ext_id
+        / "storage"
+        / "schema.json"
+    )
+    if not schema_path.is_file():
+        raise ValueError(f"WASM extension '{ext_id}' has no storage schema.")
+    return _load_json(schema_path)
+
+
+def _data_to_db(
+    table_schema: dict[str, Any],
+    data: dict[str, Any],
+    *,
+    require_id: bool,
+) -> dict[str, Any]:
+    if not isinstance(data, dict):
+        raise ValueError("WASM storage row data must be an object.")
+    if require_id and not data.get("id"):
+        raise ValueError("WASM storage row data must include an id.")
+    _reject_reserved_owner_field(data, "row")
+
+    fields = _fields_by_name(table_schema)
+    unknown_fields = sorted(set(data) - set(fields))
+    if unknown_fields:
+        raise ValueError(
+            "WASM storage row has unknown fields: " + ", ".join(unknown_fields)
+        )
+
+    return {
+        field_name: _value_to_db(fields[field_name], value)
+        for field_name, value in data.items()
+    }
+
+
+def _filters_to_db(
+    table_schema: dict[str, Any],
+    filters: dict[str, Any],
+) -> dict[str, Any]:
+    if not isinstance(filters, dict):
+        raise ValueError("WASM storage filters must be an object.")
+    _reject_reserved_owner_field(filters, "filters")
+
+    fields = _fields_by_name(table_schema)
+    unknown_fields = sorted(set(filters) - set(fields))
+    if unknown_fields:
+        raise ValueError(
+            "WASM storage filters have unknown fields: " + ", ".join(unknown_fields)
+        )
+
+    return {
+        field_name: _value_to_db(fields[field_name], value)
+        for field_name, value in filters.items()
+    }
+
+
+def _where_sql(
+    table_schema: dict[str, Any],
+    filters: dict[str, Any],
+    search: str | None,
+    search_fields: list[str],
+) -> tuple[str, dict[str, Any]]:
+    clean_filters = _filters_to_db(table_schema, filters)
+    clauses = [f"{field} = :filter_{field}" for field in clean_filters]
+    values = {f"filter_{field}": value for field, value in clean_filters.items()}
+
+    clean_search = search.strip().lower() if search else ""
+    if clean_search:
+        fields = _fields_by_name(table_schema)
+        invalid_fields = sorted(set(search_fields) - set(fields))
+        if invalid_fields:
+            raise ValueError(
+                "WASM storage search has unknown fields: " + ", ".join(invalid_fields)
+            )
+        if search_fields:
+            search_clause = " OR ".join(
+                f"LOWER(CAST({field} AS TEXT)) LIKE :search" for field in search_fields
+            )
+            clauses.append(f"({search_clause})")
+            values["search"] = f"%{clean_search}%"
+
+    return ("WHERE " + " AND ".join(clauses), values) if clauses else ("", values)
+
+
+def _append_owner_where_sql(where_sql: str) -> str:
+    owner_clause = f"{OWNER_ID_FIELD} = :{OWNER_ID_FIELD}"
+    if where_sql:
+        return f"{where_sql} AND {owner_clause}"
+    return f"WHERE {owner_clause}"
+
+
+def _order_sql(
+    table_schema: dict[str, Any],
+    sort_by: str | None,
+    descending: bool,
+) -> str:
+    if not sort_by:
+        return ""
+    fields = _fields_by_name(table_schema)
+    if sort_by not in fields:
+        raise ValueError(f"WASM storage sort field is unknown: {sort_by}")
+    direction = "DESC" if descending else "ASC"
+    return f"ORDER BY {sort_by} {direction}"
+
+
+def _row_from_db(
+    table_schema: dict[str, Any],
+    row: dict[str, Any],
+) -> dict[str, Any]:
+    fields = _fields_by_name(table_schema)
+    return {
+        field_name: _value_from_db(fields[field_name], value)
+        for field_name, value in dict(row).items()
+        if field_name in fields
+    }
+
+
+def _fields_by_name(table_schema: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    fields = table_schema.get("fields")
+    if not isinstance(fields, list):
+        raise ValueError("WASM storage table schema fields must be a list.")
+    return {field["name"]: field for field in fields}
+
+
+def _reject_reserved_owner_field(data: dict[str, Any], value_name: str) -> None:
+    if OWNER_ID_FIELD in data:
+        raise ValueError(f"WASM storage {value_name} includes a reserved owner field.")
+
+
+def _value_to_db(field: dict[str, Any], value: Any) -> Any:  # noqa: C901
+    if value is None:
+        if field.get("nullable", False):
+            return None
+        raise ValueError(f"WASM storage field '{field['name']}' cannot be null.")
+
+    if field.get("list") is True:
+        if not isinstance(value, list):
+            raise ValueError(f"WASM storage field '{field['name']}' must be a list.")
+        return json.dumps(value)
+
+    field_type = field.get("type")
+    if field_type == "string":
+        if not isinstance(value, str):
+            raise ValueError(f"WASM storage field '{field['name']}' must be a string.")
+        return value
+    if field_type == "integer":
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValueError(
+                f"WASM storage field '{field['name']}' must be an integer."
+            )
+        return value
+    if field_type == "number":
+        if isinstance(value, bool) or not isinstance(value, int | float):
+            raise ValueError(f"WASM storage field '{field['name']}' must be a number.")
+        return value
+    if field_type == "boolean":
+        if not isinstance(value, bool):
+            raise ValueError(f"WASM storage field '{field['name']}' must be a boolean.")
+        return value
+    if field_type == "datetime":
+        if isinstance(value, int | float):
+            return datetime.fromtimestamp(value, tz=timezone.utc)
+        if isinstance(value, datetime):
+            return value
+        raise ValueError(
+            f"WASM storage field '{field['name']}' must be a Unix timestamp."
+        )
+    raise ValueError(f"Unsupported WASM storage field type: {field_type}")
+
+
+def _value_from_db(field: dict[str, Any], value: Any) -> Any:
+    if value is None:
+        return None
+
+    if field.get("list") is True:
+        if isinstance(value, str):
+            return json.loads(value)
+        return value
+
+    field_type = field.get("type")
+    if field_type == "boolean":
+        return bool(value)
+    if field_type == "datetime":
+        if isinstance(value, datetime):
+            return int(value.replace(tzinfo=timezone.utc).timestamp())
+        if isinstance(value, int | float):
+            return int(value)
+        if isinstance(value, str):
+            try:
+                return int(datetime.fromisoformat(value).timestamp())
+            except ValueError:
+                return value
+    return value
+
+
+def _default_sql(value: Any) -> str:
+    if value is None:
+        return "NULL"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float):
+        return str(value)
+    if isinstance(value, str):
+        return _quote_sql_string(value)
+    if isinstance(value, list | dict):
+        return _quote_sql_string(json.dumps(value))
+    raise ValueError(f"Unsupported WASM storage default value: {value}")
+
+
+def _field_from_add_field_operation(operation: dict[str, Any]) -> dict[str, Any]:
+    field = {
+        "name": operation.get("field"),
+        "type": operation.get("type"),
+    }
+    for key in ("default", "list", "nullable"):
+        if key in operation:
+            field[key] = operation[key]
+    return field
+
+
+def _require_fields(operation: dict[str, Any]) -> list[dict[str, Any]]:
+    fields = operation.get("fields")
+    if not isinstance(fields, list) or not fields:
+        raise ValueError("WASM storage create_table operation requires fields.")
+    if not all(isinstance(field, dict) for field in fields):
+        raise ValueError("WASM storage fields must be objects.")
+    return fields
+
+
+def _require_identifier(data: dict[str, Any], key: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not _SQL_IDENTIFIER_RE.match(value):
+        raise ValueError(f"Invalid WASM storage SQL identifier for '{key}': {value}")
+    return value
+
+
+def _table_ref(db: Connection, table: str) -> str:
+    if db.schema:
+        return f"{_schema_ref(db, table)}"
+    return table
+
+
+def _table_ref_for_schema(ext_id: str, table: str) -> str:
+    _require_identifier({"schema": ext_id}, "schema")
+    _require_identifier({"table": table}, "table")
+    return f"{ext_id}.{table}"
+
+
+def _schema_ref(db: Connection, name: str) -> str:
+    if not db.schema:
+        return name
+    if not _SQL_IDENTIFIER_RE.match(db.schema):
+        raise ValueError(f"Invalid WASM extension storage schema: {db.schema}")
+    return f"{db.schema}.{name}"
+
+
+def _quote_sql_string(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as json_file:
+        data = json.load(json_file)
+    if not isinstance(data, dict):
+        raise ValueError(f"WASM storage migration '{path}' must be a JSON object.")
+    return data
+
+
+async def _update_wasm_migration_version(
+    db: Connection,
+    ext_id: str,
+    version: int,
+) -> None:
+    if db.schema is None:
+        await update_migration_version(db, ext_id, version)
+    else:
+        async with core_db.connect() as conn:
+            await update_migration_version(conn, ext_id, version)

lnbits/core/extensions/wasm.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from collections.abc import Mapping
+from functools import lru_cache
+from typing import Any
+
+from lnbits.core.crud.extensions import get_installed_extension
+from lnbits.core.db import core_app_extra
+
+from .api import ExtensionAPI, list_extension_api_methods
+from .loader import WasmExtension
+from .runtime import ExtensionAPIHost
+
+
+async def invoke_wasm_extension_export(
+    ext_id: str,
+    export_name: str,
+    payload: Mapping[str, Any] | None = None,
+    *,
+    user: Any | None = None,
+    access_token: str | None = None,
+    context: str = "user",
+    owner_id: str | None = None,
+) -> dict[str, Any]:
+    extension = _get_registered_extension(ext_id)
+    permissions = await _extension_permissions(extension)
+    api = ExtensionAPI(
+        extension.id,
+        permissions,
+        user_id=_user_id(user),
+        access_token=access_token,
+        context=context,
+        owner_id=owner_id,
+    )
+    event_loop = asyncio.get_running_loop()
+
+    return await asyncio.to_thread(
+        _invoke_wasm_extension_export_sync,
+        extension,
+        export_name,
+        payload or {},
+        api,
+        event_loop,
+    )
+
+
+def warm_wasm_extension(extension: WasmExtension) -> None:
+    _wasm_component(extension)
+
+
+def _invoke_wasm_extension_export_sync(
+    extension: WasmExtension,
+    export_name: str,
+    payload: Mapping[str, Any],
+    api: ExtensionAPI,
+    event_loop: asyncio.AbstractEventLoop,
+) -> dict[str, Any]:
+    try:
+        from wasmtime import Store, WasiConfig, component
+    except ImportError as exc:
+        raise RuntimeError(
+            "WASM extension runtime is not installed. Install the 'wasmtime' "
+            "Python package to run WASM extensions."
+        ) from exc
+
+    engine = _wasm_engine()
+    store = Store(engine)
+    store.set_wasi(WasiConfig())
+
+    linker = component.Linker(engine)
+    linker.add_wasip2()
+    _add_extension_host_imports(linker, ExtensionAPIHost(api), event_loop)
+
+    wasm_component = _wasm_component(extension)
+    instance = linker.instantiate(store, wasm_component)
+    function = instance.get_func(store, export_name)
+    if not function:
+        raise KeyError(
+            f"WASM extension '{extension.id}' has no export '{export_name}'."
+        )
+
+    result = function(store, json.dumps(payload))
+    function.post_return(store)
+    return _parse_wasm_export_result(extension, result)
+
+
+@lru_cache(maxsize=1)
+def _wasm_engine() -> Any:
+    try:
+        from wasmtime import Config, Engine
+    except ImportError as exc:
+        raise RuntimeError(
+            "WASM extension runtime is not installed. Install the 'wasmtime' "
+            "Python package to run WASM extensions."
+        ) from exc
+
+    config = Config()
+    config.wasm_component_model = True
+    return Engine(config)
+
+
+def _wasm_component(extension: WasmExtension) -> Any:
+    stat = extension.module_path.stat()
+    return _cached_wasm_component(
+        str(extension.module_path),
+        stat.st_mtime_ns,
+        stat.st_size,
+    )
+
+
+@lru_cache(maxsize=32)
+def _cached_wasm_component(
+    module_path: str,
+    mtime_ns: int,
+    size: int,
+) -> Any:
+    from wasmtime import component
+
+    return component.Component.from_file(_wasm_engine(), module_path)
+
+
+def _add_extension_host_imports(
+    linker: Any,
+    api_host: ExtensionAPIHost,
+    event_loop: asyncio.AbstractEventLoop,
+) -> None:
+    with linker.root() as root:
+        methods_by_interface: dict[str, list[Any]] = {}
+        for method in list_extension_api_methods():
+            methods_by_interface.setdefault(method.host_interface, []).append(method)
+
+        for host_interface, methods in methods_by_interface.items():
+            with root.add_instance(f"lnbits:extension/{host_interface}") as host:
+                for method in methods:
+                    host.add_func(
+                        method.host_name.replace("_", "-"),
+                        _make_host_import(api_host, method.method_id, event_loop),
+                    )
+
+
+def _make_host_import(
+    api_host: ExtensionAPIHost,
+    host_name: str,
+    event_loop: asyncio.AbstractEventLoop,
+) -> Any:
+    def host_import(_store: Any, request: Any = None) -> Any:
+        payload = _component_payload_to_dict(request)
+        future = asyncio.run_coroutine_threadsafe(
+            api_host.invoke(host_name, payload), event_loop
+        )
+        response = future.result()
+        return _dict_to_component_record(response)
+
+    return host_import
+
+
+def _component_payload_to_dict(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if hasattr(value, "__dict__"):
+        return dict(value.__dict__)
+    if isinstance(value, Mapping):
+        return dict(value)
+    raise TypeError("WASM host function payload must be a record.")
+
+
+def _dict_to_component_record(value: Mapping[str, Any]) -> Any:
+    from wasmtime import component
+
+    record = component.Record()
+    for key, item in value.items():
+        setattr(record, _camel_to_kebab(key), _to_component_value(item))
+    return record
+
+
+def _to_component_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return _dict_to_component_record(value)
+    if isinstance(value, list):
+        return [_to_component_value(item) for item in value]
+    return value
+
+
+def _parse_wasm_export_result(extension: WasmExtension, value: Any) -> dict[str, Any]:
+    if isinstance(value, bytes):
+        value = value.decode()
+    if not isinstance(value, str):
+        return {"ok": True, "data": value}
+
+    max_response_bytes = (
+        (extension.config.get("wasm") or {})
+        .get("resource_limits", {})
+        .get("max_response_bytes")
+    )
+    if isinstance(max_response_bytes, int):
+        response_size = len(value.encode())
+        if response_size > max_response_bytes:
+            raise ValueError(
+                f"WASM extension response is too large: {response_size} bytes."
+            )
+
+    parsed = json.loads(value)
+    if isinstance(parsed, dict):
+        return parsed
+    return {"ok": True, "data": parsed}
+
+
+def _get_registered_extension(ext_id: str) -> WasmExtension:
+    extension = core_app_extra.wasm_extension_registry.get(ext_id)
+    if extension:
+        return extension
+    raise RuntimeError(f"WASM extension '{ext_id}' is not registered.")
+
+
+async def _extension_permissions(extension: WasmExtension) -> list[Any]:
+    installed_extension = await get_installed_extension(extension.id)
+    if not installed_extension:
+        return []
+    return installed_extension.permissions
+
+
+def _user_id(user: Any | None) -> str | None:
+    return getattr(user, "id", None) if user else None
+
+
+def _camel_to_kebab(value: str) -> str:
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", value).replace("_", "-").lower()

lnbits/core/helpers.py

@@ -1,6 +1,6 @@
 import importlib
 import re
-from typing import Any, Optional
+from typing import Any
 from urllib.parse import urlparse
 from uuid import UUID
 
@@ -13,6 +13,8 @@ from lnbits.core.crud import (
     update_migration_version,
 )
 from lnbits.core.db import db as core_db
+from lnbits.core.extensions.loader import is_wasm_extension_id
+from lnbits.core.extensions.storage import migrate_wasm_extension_database
 from lnbits.core.models import DbVersion
 from lnbits.core.models.extensions import InstallableExtension
 from lnbits.db import COCKROACH, POSTGRES, SQLITE, Connection
@@ -20,8 +22,11 @@ from lnbits.settings import settings
 
 
 async def migrate_extension_database(
-    ext: InstallableExtension, current_version: Optional[DbVersion] = None
+    ext: InstallableExtension, current_version: DbVersion | None = None
 ):
+    if is_wasm_extension_id(ext.id):
+        await migrate_wasm_extension_database(ext, current_version)
+        return
 
     try:
         ext_migrations = importlib.import_module(f"{ext.module_name}.migrations")
@@ -38,7 +43,7 @@ async def run_migration(
     db: Connection,
     migrations_module: Any,
     db_name: str,
-    current_version: Optional[DbVersion] = None,
+    current_version: DbVersion | None = None,
 ):
     matcher = re.compile(r"^m(\d\d\d)_")
 

lnbits/core/migrations.py

@@ -10,31 +10,26 @@ from lnbits.db import Connection
 
 
 async def m000_create_migrations_table(db: Connection):
-    await db.execute(
-        """
+    await db.execute("""
     CREATE TABLE IF NOT EXISTS dbversions (
         db TEXT PRIMARY KEY,
         version INT NOT NULL
     )
-    """
-    )
+    """)
 
 
 async def m001_initial(db: Connection):
     """
     Initial LNbits tables.
     """
-    await db.execute(
-        """
+    await db.execute("""
         CREATE TABLE IF NOT EXISTS accounts (
             id TEXT PRIMARY KEY,
             email TEXT,
             pass TEXT
         );
-    """
-    )
-    await db.execute(
-        """
+    """)
+    await db.execute("""
         CREATE TABLE IF NOT EXISTS extensions (
             "user" TEXT NOT NULL,
             extension TEXT NOT NULL,
@@ -42,10 +37,8 @@ async def m001_initial(db: Connection):
 
             UNIQUE ("user", extension)
         );
-    """
-    )
-    await db.execute(
-        """
+    """)
+    await db.execute("""
         CREATE TABLE IF NOT EXISTS wallets (
             id TEXT PRIMARY KEY,
             name TEXT NOT NULL,
@@ -53,10 +46,8 @@ async def m001_initial(db: Connection):
             adminkey TEXT NOT NULL,
             inkey TEXT
         );
-    """
-    )
-    await db.execute(
-        f"""
+    """)
+    await db.execute(f"""
         CREATE TABLE IF NOT EXISTS apipayments (
             payhash TEXT NOT NULL,
             amount {db.big_int} NOT NULL,
@@ -67,11 +58,9 @@ async def m001_initial(db: Connection):
             time TIMESTAMP NOT NULL DEFAULT {db.timestamp_now},
             UNIQUE (wallet, payhash)
         );
-    """
-    )
+    """)
 
-    await db.execute(
-        """
+    await db.execute("""
         CREATE VIEW balances AS
         SELECT wallet, COALESCE(SUM(s), 0) AS balance FROM (
             SELECT wallet, SUM(amount) AS s  -- incoming
@@ -85,8 +74,7 @@ async def m001_initial(db: Connection):
             GROUP BY wallet
         )x
         GROUP BY wallet;
-    """
-    )
+    """)
 
 
 async def m002_add_fields_to_apipayments(db: Connection):
@@ -149,8 +137,7 @@ async def m004_ensure_fees_are_always_negative(db: Connection):
     """
 
     await db.execute("DROP VIEW balances")
-    await db.execute(
-        """
+    await db.execute("""
         CREATE VIEW balances AS
         SELECT wallet, COALESCE(SUM(s), 0) AS balance FROM (
             SELECT wallet, SUM(amount) AS s  -- incoming
@@ -164,8 +151,7 @@ async def m004_ensure_fees_are_always_negative(db: Connection):
             GROUP BY wallet
         )x
         GROUP BY wallet;
-    """
-    )
+    """)
 
 
 async def m005_balance_check_balance_notify(db: Connection):
@@ -174,8 +160,7 @@ async def m005_balance_check_balance_notify(db: Connection):
     LNbits wallet and of balanceNotify URLs supplied by users to empty their wallets.
     """
 
-    await db.execute(
-        """
+    await db.execute("""
         CREATE TABLE IF NOT EXISTS balance_check (
           wallet TEXT NOT NULL REFERENCES wallets (id),
           service TEXT NOT NULL,
@@ -183,19 +168,16 @@ async def m005_balance_check_balance_notify(db: Connection):
 
           UNIQUE(wallet, service)
         );
-    """
-    )
+    """)
 
-    await db.execute(
-        """
+    await db.execute("""
         CREATE TABLE IF NOT EXISTS balance_notify (
           wallet TEXT NOT NULL REFERENCES wallets (id),
           url TEXT NOT NULL,
 
           UNIQUE(wallet, url)
         );
-    """
-    )
+    """)
 
 
 async def m006_add_invoice_expiry_to_apipayments(db: Connection):
@@ -214,6 +196,7 @@ async def m007_set_invoice_expiries(db: Connection):
     """
     try:
         result = await db.execute(
+            # Timestamp placeholder is safe from SQL injection (not user input)
             f"""
             SELECT bolt11, checking_id
             FROM apipayments
@@ -222,7 +205,7 @@ async def m007_set_invoice_expiries(db: Connection):
             AND bolt11 IS NOT NULL
             AND expiry IS NULL
             AND time < {db.timestamp_now}
-            """
+            """  # noqa: S608
         )
         rows = result.mappings().all()
         if len(rows):
@@ -242,13 +225,15 @@ async def m007_set_invoice_expiries(db: Connection):
                     f" {invoice.payment_hash} to {expiration_date}"
                 )
                 await db.execute(
+                    # Timestamp placeholder is safe from SQL injection (not user input)
                     f"""
                     UPDATE apipayments SET expiry = {db.timestamp_placeholder('expiry')}
                     WHERE checking_id = :checking_id AND amount > 0
-                    """,
+                    """,  # noqa: S608
                     {"expiry": expiration_date, "checking_id": checking_id},
                 )
-            except Exception:
+            except Exception as exc:
+                logger.debug(exc)
                 continue
     except OperationalError:
         # this is necessary now because it may be the case that this migration will
@@ -259,19 +244,16 @@ async def m007_set_invoice_expiries(db: Connection):
 
 
 async def m008_create_admin_settings_table(db: Connection):
-    await db.execute(
-        """
+    await db.execute("""
         CREATE TABLE IF NOT EXISTS settings (
             super_user TEXT,
             editable_settings TEXT NOT NULL DEFAULT '{}'
         );
-    """
-    )
+    """)
 
 
 async def m009_create_tinyurl_table(db: Connection):
-    await db.execute(
-        f"""
+    await db.execute(f"""
         CREATE TABLE IF NOT EXISTS tiny_url (
           id TEXT PRIMARY KEY,
           url TEXT,
@@ -279,13 +261,11 @@ async def m009_create_tinyurl_table(db: Connection):
           wallet TEXT,
           time TIMESTAMP NOT NULL DEFAULT {db.timestamp_now}
         );
-    """
-    )
+    """)
 
 
 async def m010_create_installed_extensions_table(db: Connection):
-    await db.execute(
-        """
+    await db.execute("""
         CREATE TABLE IF NOT EXISTS installed_extensions (
             id TEXT PRIMARY KEY,
             version TEXT NOT NULL,
@@ -296,8 +276,7 @@ async def m010_create_installed_extensions_table(db: Connection):
             active BOOLEAN DEFAULT false,
             meta TEXT NOT NULL DEFAULT '{}'
         );
-    """
-    )
+    """)
 
 
 async def m011_optimize_balances_view(db: Connection):
@@ -306,23 +285,19 @@ async def m011_optimize_balances_view(db: Connection):
     over the payments table instead of 2.
     """
     await db.execute("DROP VIEW balances")
-    await db.execute(
-        """
+    await db.execute("""
         CREATE VIEW balances AS
         SELECT wallet, SUM(amount - abs(fee)) AS balance
         FROM apipayments
         WHERE (pending = false AND amount > 0) OR amount < 0
         GROUP BY wallet
-    """
-    )
+    """)
 
 
 async def m012_add_currency_to_wallet(db: Connection):
-    await db.execute(
-        """
+    await db.execute("""
         ALTER TABLE wallets ADD COLUMN currency TEXT
-        """
-    )
+        """)
 
 
 async def m013_add_deleted_to_wallets(db: Connection):
@@ -342,15 +317,13 @@ async def m014_set_deleted_wallets(db: Connection):
     Sets deleted column to wallets.
     """
     try:
-        result = await db.execute(
-            """
+        result = await db.execute("""
             SELECT *
             FROM wallets
             WHERE user LIKE 'del:%'
             AND adminkey LIKE 'del:%'
             AND inkey LIKE 'del:%'
-            """
-        )
+            """)
         rows = result.mappings().all()
 
         for row in rows:
@@ -371,7 +344,8 @@ async def m014_set_deleted_wallets(db: Connection):
                         "wallet": row.get("id"),
                     },
                 )
-            except Exception:
+            except Exception as exc:
+                logger.debug(exc)
                 continue
     except OperationalError:
         # this is necessary now because it may be the case that this migration will
@@ -382,8 +356,7 @@ async def m014_set_deleted_wallets(db: Connection):
 
 
 async def m015_create_push_notification_subscriptions_table(db: Connection):
-    await db.execute(
-        f"""
+    await db.execute(f"""
         CREATE TABLE IF NOT EXISTS webpush_subscriptions (
             endpoint TEXT NOT NULL,
             "user" TEXT NOT NULL,
@@ -392,8 +365,7 @@ async def m015_create_push_notification_subscriptions_table(db: Connection):
             timestamp TIMESTAMP NOT NULL DEFAULT {db.timestamp_now},
             PRIMARY KEY (endpoint, "user")
         );
-    """
-    )
+    """)
 
 
 async def m016_add_username_column_to_accounts(db: Connection):
@@ -454,17 +426,19 @@ async def m017_add_timestamp_columns_to_accounts_and_wallets(db: Connection):
         # set all to now where they are null
         now = int(time())
         await db.execute(
+            # Timestamp placeholder is safe from SQL injection (not user input)
             f"""
             UPDATE wallets SET created_at = {db.timestamp_placeholder('now')}
             WHERE created_at IS NULL
-            """,
+            """,  # noqa: S608
             {"now": now},
         )
         await db.execute(
+            # Timestamp placeholder is safe from SQL injection (not user input)
             f"""
             UPDATE accounts SET created_at = {db.timestamp_placeholder('now')}
             WHERE created_at IS NULL
-            """,
+            """,  # noqa: S608
             {"now": now},
         )
 
@@ -478,8 +452,7 @@ async def m018_balances_view_exclude_deleted(db: Connection):
     Make deleted wallets not show up in the balances view.
     """
     await db.execute("DROP VIEW balances")
-    await db.execute(
-        """
+    await db.execute("""
         CREATE VIEW balances AS
         SELECT apipayments.wallet,
                SUM(apipayments.amount - ABS(apipayments.fee)) AS balance
@@ -489,8 +462,7 @@ async def m018_balances_view_exclude_deleted(db: Connection):
               AND ((apipayments.pending = false AND apipayments.amount > 0)
               OR apipayments.amount < 0)
         GROUP BY wallet
-    """
-    )
+    """)
 
 
 async def m019_balances_view_based_on_wallets(db: Connection):
@@ -499,8 +471,7 @@ async def m019_balances_view_based_on_wallets(db: Connection):
     Important for querying whole lnbits balances.
     """
     await db.execute("DROP VIEW balances")
-    await db.execute(
-        """
+    await db.execute("""
         CREATE VIEW balances AS
         SELECT apipayments.wallet,
                SUM(apipayments.amount - ABS(apipayments.fee)) AS balance
@@ -510,8 +481,7 @@ async def m019_balances_view_based_on_wallets(db: Connection):
               AND ((apipayments.pending = false AND apipayments.amount > 0)
               OR apipayments.amount < 0)
         GROUP BY apipayments.wallet
-    """
-    )
+    """)
 
 
 async def m020_add_column_column_to_user_extensions(db: Connection):
@@ -530,8 +500,7 @@ async def m021_add_success_failed_to_apipayments(db: Connection):
     await db.execute("UPDATE apipayments SET status = 'success' WHERE NOT pending")
 
     await db.execute("DROP VIEW balances")
-    await db.execute(
-        """
+    await db.execute("""
         CREATE VIEW balances AS
         SELECT apipayments.wallet,
                SUM(apipayments.amount - ABS(apipayments.fee)) AS balance
@@ -543,8 +512,7 @@ async def m021_add_success_failed_to_apipayments(db: Connection):
             OR (apipayments.status IN ('success', 'pending') AND apipayments.amount < 0)
         )
         GROUP BY apipayments.wallet
-    """
-    )
+    """)
 
 
 async def m022_add_pubkey_to_accounts(db: Connection):
@@ -575,8 +543,7 @@ async def m024_drop_pending(db: Connection):
 
 async def m025_refresh_view(db: Connection):
     await db.execute("DROP VIEW balances")
-    await db.execute(
-        """
+    await db.execute("""
         CREATE VIEW balances AS
         SELECT apipayments.wallet_id,
                SUM(apipayments.amount - ABS(apipayments.fee)) AS balance
@@ -588,8 +555,7 @@ async def m025_refresh_view(db: Connection):
             OR (apipayments.status IN ('success', 'pending') AND apipayments.amount < 0)
         )
         GROUP BY apipayments.wallet_id
-    """
-    )
+    """)
 
 
 async def m026_update_payment_table(db: Connection):
@@ -616,7 +582,12 @@ async def m027_update_apipayments_data(db: Connection):
         logger.info(f"Updating {offset} to {offset+limit}")
 
         result = await db.execute(
-            f"SELECT * FROM apipayments  ORDER BY time LIMIT {limit} OFFSET {offset}"
+            # Limit and Offset safe from SQL injection
+            # since they are integers and are not user input
+            f"""
+                SELECT * FROM apipayments
+                ORDER BY time LIMIT {int(limit)} OFFSET {int(offset)}
+            """  # noqa: S608
         )
         payments = result.mappings().all()
         logger.info(f"Payments count: {len(payments)}")
@@ -629,11 +600,12 @@ async def m027_update_apipayments_data(db: Connection):
                 tag = extra.get("tag")
             tsph = db.timestamp_placeholder("created_at")
             await db.execute(
+                # Timestamp placeholder is safe from SQL injection (not user input)
                 f"""
                 UPDATE apipayments
                 SET tag = :tag, created_at = {tsph}, updated_at = {tsph}
                 WHERE checking_id = :checking_id
-                """,
+                """,  # noqa: S608
                 {
                     "tag": tag,
                     "created_at": created_at,
@@ -646,8 +618,7 @@ async def m027_update_apipayments_data(db: Connection):
 
 async def m028_update_settings(db: Connection):
 
-    await db.execute(
-        """
+    await db.execute("""
         CREATE TABLE IF NOT EXISTS system_settings (
             id TEXT PRIMARY KEY,
             value TEXT,
@@ -655,8 +626,7 @@ async def m028_update_settings(db: Connection):
 
             UNIQUE (id, tag)
         );
-    """
-    )
+    """)
 
     async def _insert_key_value(id_: str, value: Any):
         await db.execute(
@@ -679,8 +649,7 @@ async def m028_update_settings(db: Connection):
 
 
 async def m029_create_audit_table(db: Connection):
-    await db.execute(
-        f"""
+    await db.execute(f"""
         CREATE TABLE IF NOT EXISTS audit (
             component TEXT,
             ip_address TEXT,
@@ -694,16 +663,13 @@ async def m029_create_audit_table(db: Connection):
             delete_at TIMESTAMP,
             created_at TIMESTAMP NOT NULL DEFAULT {db.timestamp_now}
         );
-        """
-    )
+        """)
 
 
 async def m030_add_user_api_tokens_column(db: Connection):
-    await db.execute(
-        """
+    await db.execute("""
         ALTER TABLE accounts ADD COLUMN access_control_list TEXT
-        """
-    )
+        """)
 
 
 async def m031_add_color_and_icon_to_wallets(db: Connection):
@@ -711,3 +677,150 @@ async def m031_add_color_and_icon_to_wallets(db: Connection):
     Adds icon and color columns to wallets.
     """
     await db.execute("ALTER TABLE wallets ADD COLUMN extra TEXT")
+
+
+async def m032_add_external_id_to_accounts(db: Connection):
+    """
+    Adds external_id column to accounts.
+    Used for external account linking.
+    """
+    await db.execute("ALTER TABLE accounts ADD COLUMN external_id TEXT")
+
+
+async def m033_update_payment_table(db: Connection):
+    await db.execute("ALTER TABLE apipayments ADD COLUMN fiat_provider TEXT")
+
+
+async def m034_add_stored_paylinks_to_wallet(db: Connection):
+    await db.execute("""
+        ALTER TABLE wallets ADD COLUMN stored_paylinks TEXT
+        """)
+
+
+async def m035_add_wallet_type_column(db: Connection):
+    await db.execute("""
+        ALTER TABLE wallets ADD COLUMN wallet_type TEXT DEFAULT 'lightning'
+        """)
+
+
+async def m036_add_shared_wallet_column(db: Connection):
+    await db.execute("""
+        ALTER TABLE wallets ADD COLUMN shared_wallet_id TEXT
+        """)
+
+
+async def m037_create_assets_table(db: Connection):
+    await db.execute(f"""
+        CREATE TABLE IF NOT EXISTS assets (
+            id TEXT PRIMARY KEY,
+            user_id TEXT NOT NULL,
+            mime_type TEXT NOT NULL,
+            is_public BOOLEAN NOT NULL DEFAULT false,
+            name TEXT NOT NULL,
+            size_bytes INT NOT NULL,
+            thumbnail_base64 TEXT,
+            thumbnail {db.blob},
+            data {db.blob} NOT NULL,
+            created_at TIMESTAMP NOT NULL DEFAULT {db.timestamp_now}
+        );
+        """)
+
+
+async def m038_add_labels_for_payments(db: Connection):
+    await db.execute("""
+        ALTER TABLE apipayments ADD COLUMN labels TEXT
+        """)
+
+
+async def m039_index_payments(db: Connection):
+    indexes = [
+        "wallet_id",
+        "checking_id",
+        "payment_hash",
+        "amount",
+        "fee",
+        "labels",
+        "time",
+        "status",
+        "memo",
+        "created_at",
+        "updated_at",
+    ]
+    for index in indexes:
+        logger.debug(f"Creating index idx_payments_{index}...")
+        await db.execute(f"""
+            CREATE INDEX IF NOT EXISTS idx_payments_{index} ON apipayments ({index});
+            """)
+
+
+async def m040_index_wallets(db: Connection):
+    indexes = [
+        "id",
+        "user",
+        "deleted",
+        "adminkey",
+        "inkey",
+        "wallet_type",
+        "created_at",
+        "updated_at",
+    ]
+
+    for index in indexes:
+        logger.debug(f"Creating index idx_wallets_{index}...")
+        await db.execute(f"""
+            CREATE INDEX IF NOT EXISTS idx_wallets_{index} ON wallets ("{index}");
+            """)
+
+
+async def m042_index_accounts(db: Connection):
+    indexes = [
+        "id",
+        "email",
+        "username",
+        "pubkey",
+        "external_id",
+    ]
+
+    for index in indexes:
+        logger.debug(f"Creating index idx_wallets_{index}...")
+        await db.execute(f"""
+            CREATE INDEX IF NOT EXISTS idx_accounts_{index} ON accounts ("{index}");
+            """)
+
+
+async def m043_add_ui_customization_to_accounts(db: Connection):
+    """
+    Adds ui_customization column to accounts.
+    Used for server side persistence of UI customization settings.
+    """
+    await db.execute("ALTER TABLE accounts ADD COLUMN ui_customization TEXT")
+
+
+async def m044_add_activated_to_accounts(db: Connection):
+    """
+    Adds activated column to accounts.
+    Used for account activation status.
+    """
+    await db.execute("ALTER TABLE accounts ADD COLUMN activated BOOLEAN DEFAULT true")
+
+
+async def m045_add_external_id_to_payments(db: Connection):
+    """
+    Adds external_id column to apipayments.
+    Used for external payment references.
+    """
+    await db.execute("ALTER TABLE apipayments ADD COLUMN external_id TEXT")
+    logger.debug("Creating index idx_payments_external_id...")
+    await db.execute("""
+        CREATE INDEX IF NOT EXISTS idx_payments_external_id
+        ON apipayments (external_id);
+        """)
+
+
+async def m046_add_permissions_to_installed_extensions(db: Connection):
+    """
+    Adds granted permissions to installed extensions.
+    """
+    await db.execute(
+        "ALTER TABLE installed_extensions ADD COLUMN permissions TEXT DEFAULT '[]'"
+    )

lnbits/core/models/__init__.py

@@ -1,5 +1,5 @@
 from .audit import AuditEntry, AuditFilters
-from .lnurl import CreateLnurl, CreateLnurlAuth, PayLnurlWData
+from .lnurl import CreateLnurlPayment, CreateLnurlWithdraw
 from .misc import (
     BalanceDelta,
     Callback,
@@ -9,6 +9,7 @@ from .misc import (
     SimpleStatus,
 )
 from .payments import (
+    CancelInvoice,
     CreateInvoice,
     CreatePayment,
     DecodePayment,
@@ -23,6 +24,8 @@ from .payments import (
     PaymentsStatusCount,
     PaymentState,
     PaymentWalletStats,
+    SettleInvoice,
+    UpdatePaymentExtra,
 )
 from .tinyurl import TinyURL
 from .users import (
@@ -44,66 +47,60 @@ from .users import (
     UserAcls,
     UserExtra,
 )
-from .wallets import BaseWallet, CreateWallet, KeyType, Wallet, WalletTypeInfo
+from .wallets import CreateWallet, KeyType, Wallet, WalletInfo, WalletTypeInfo
 from .webpush import CreateWebPushSubscription, WebPushSubscription
 
 __all__ = [
-    # audit
+    "AccessTokenPayload",
+    "Account",
+    "AccountFilters",
+    "AccountOverview",
     "AuditEntry",
     "AuditFilters",
-    # lnurl
-    "CreateLnurl",
-    "CreateLnurlAuth",
-    "PayLnurlWData",
-    # misc
     "BalanceDelta",
     "Callback",
+    "CancelInvoice",
     "ConversionData",
     "CoreAppExtra",
-    "DbVersion",
-    "SimpleStatus",
-    # payments
     "CreateInvoice",
+    "CreateLnurlPayment",
+    "CreateLnurlWithdraw",
     "CreatePayment",
+    "CreateUser",
+    "CreateWallet",
+    "CreateWebPushSubscription",
+    "DbVersion",
     "DecodePayment",
+    "KeyType",
+    "LoginUsernamePassword",
+    "LoginUsr",
     "PayInvoice",
     "Payment",
     "PaymentCountField",
     "PaymentCountStat",
     "PaymentDailyStats",
-    "PaymentsStatusCount",
-    "PaymentWalletStats",
     "PaymentExtra",
     "PaymentFilters",
     "PaymentHistoryPoint",
     "PaymentState",
-    # tinyurl
-    "TinyURL",
-    # users
-    "AccessTokenPayload",
-    "Account",
-    "AccountFilters",
-    "AccountOverview",
-    "UserAcls",
-    "CreateUser",
+    "PaymentWalletStats",
+    "PaymentsStatusCount",
     "RegisterUser",
-    "LoginUsernamePassword",
-    "LoginUsr",
     "ResetUserPassword",
+    "SettleInvoice",
+    "SimpleStatus",
+    "TinyURL",
     "UpdateBalance",
+    "UpdatePaymentExtra",
     "UpdateSuperuserPassword",
     "UpdateUser",
     "UpdateUserPassword",
     "UpdateUserPubkey",
     "User",
+    "UserAcls",
     "UserExtra",
-    # wallets
-    "BaseWallet",
-    "CreateWallet",
-    "KeyType",
     "Wallet",
+    "WalletInfo",
     "WalletTypeInfo",
-    # webpush
-    "CreateWebPushSubscription",
     "WebPushSubscription",
 ]

lnbits/core/models/assets.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field
+
+from lnbits.db import FilterModel
+
+
+class AssetInfo(BaseModel):
+    id: str
+    mime_type: str
+    name: str
+    is_public: bool = False
+    size_bytes: int
+    thumbnail_base64: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class Asset(AssetInfo):
+    user_id: str
+    data: bytes
+
+
+class AssetUpdate(BaseModel):
+    name: str | None = None
+    is_public: bool | None = None
+
+
+class AssetFilters(FilterModel):
+    __search_fields__ = ["name"]
+    __sort_fields__ = [
+        "created_at",
+        "name",
+    ]
+
+    name: str | None = None

lnbits/core/models/extensions.py

@@ -6,12 +6,14 @@ import json
 import os
 import shutil
 import zipfile
-from pathlib import Path
+from asyncio.tasks import create_task
+from collections.abc import Mapping
+from pathlib import Path, PurePosixPath
 from typing import Any
 
 import httpx
 from loguru import logger
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from lnbits.helpers import (
     download_url,
@@ -20,6 +22,7 @@ from lnbits.helpers import (
     version_parse,
 )
 from lnbits.settings import settings
+from lnbits.utils.cache import cache
 
 
 class ExplicitRelease(BaseModel):
@@ -39,6 +42,7 @@ class ExplicitRelease(BaseModel):
     info_notification: str | None
     critical_notification: str | None
     details_link: str | None
+    paid_features: str | None
     pay_link: str | None
 
     def is_version_compatible(self):
@@ -52,9 +56,10 @@ class GitHubRelease(BaseModel):
 
 
 class Manifest(BaseModel):
-    featured: list[str] = []
     extensions: list[ExplicitRelease] = []
     repos: list[GitHubRelease] = []
+    featured: list[str] = []
+    categories: dict[str, list[str]] = {}
 
 
 class GitHubRepoRelease(BaseModel):
@@ -73,6 +78,21 @@ class GitHubRepo(BaseModel):
     default_branch: str
 
 
+class ExtensionPermission(BaseModel):
+    id: str
+    label: str | None = None
+    description: str | None = None
+    policy: dict[str, Any] | None = None
+
+    @staticmethod
+    def list_from_config(config_json: Mapping[str, Any]) -> list[ExtensionPermission]:
+        return [
+            ExtensionPermission.parse_obj(permission)
+            for permission in config_json.get("permissions") or []
+            if isinstance(permission, dict) and permission.get("id")
+        ]
+
+
 class ExtensionConfig(BaseModel):
     name: str
     short_description: str
@@ -80,6 +100,8 @@ class ExtensionConfig(BaseModel):
     warning: str | None = ""
     min_lnbits_version: str | None
     max_lnbits_version: str | None
+    extension_type: str | None = None
+    permissions: list[ExtensionPermission] = []
 
     def is_version_compatible(self) -> bool:
         return is_lnbits_version_ok(self.min_lnbits_version, self.max_lnbits_version)
@@ -140,6 +162,7 @@ class UserExtension(BaseModel):
 class Extension(BaseModel):
     code: str
     is_valid: bool
+    is_wasm: bool = False
     name: str | None = None
     short_description: str | None = None
     tile: str | None = None
@@ -163,13 +186,22 @@ class Extension(BaseModel):
         return Extension(
             code=ext_info.id,
             is_valid=True,
+            is_wasm=ext_info.is_wasm,
             name=ext_info.name,
             short_description=ext_info.short_description,
-            tile=ext_info.icon,
+            tile=(
+                wasm_extension_icon_url(ext_info.id)
+                if ext_info.is_wasm
+                else ext_info.icon
+            ),
             upgrade_hash=ext_info.hash if ext_info.ext_upgrade_dir.is_dir() else "",
         )
 
 
+def wasm_extension_icon_url(ext_id: str) -> str:
+    return f"/ext-assets/{ext_id}/assets/icon.png"
+
+
 class ExtensionRelease(BaseModel):
     name: str
     version: str
@@ -187,6 +219,7 @@ class ExtensionRelease(BaseModel):
     icon: str | None = None
     details_link: str | None = None
 
+    paid_features: str | None = None
     pay_link: str | None = None
     cost_sats: int | None = None
     paid_sats: int | None = 0
@@ -211,7 +244,8 @@ class ExtensionRelease(BaseModel):
         self, amount: int | None = None
     ) -> ReleasePaymentInfo | None:
         url = f"{self.pay_link}?amount={amount}" if amount else self.pay_link
-        assert url, "Missing URL for payment info."
+        if not url:
+            raise ValueError("Missing URL for payment info.")
         try:
             async with httpx.AsyncClient() as client:
                 resp = await client.get(url)
@@ -255,6 +289,7 @@ class ExtensionRelease(BaseModel):
             html_url=e.html_url,
             details_link=e.details_link,
             pay_link=e.pay_link,
+            paid_features=e.paid_features,
             repo=e.repo,
             icon=e.icon,
         )
@@ -263,10 +298,30 @@ class ExtensionRelease(BaseModel):
     async def get_github_releases(cls, org: str, repo: str) -> list[ExtensionRelease]:
         try:
             github_releases = await cls.fetch_github_releases(org, repo)
-            return [
+            extension_releases = [
                 ExtensionRelease.from_github_release(f"{org}/{repo}", r)
                 for r in github_releases
             ]
+            for release in extension_releases:
+                if not release.details_link:
+                    continue
+                try:
+                    config = await ExtensionConfig.fetch_github_release_config(
+                        org, repo, release.version
+                    )
+                except Exception as e:
+                    logger.warning(e)
+                    config = None
+                if not config:
+                    continue
+
+                release.min_lnbits_version = config.min_lnbits_version
+                release.max_lnbits_version = config.max_lnbits_version
+                release.is_version_compatible = config.is_version_compatible()
+
+                release.icon = icon_to_github_url(f"{org}/{repo}", config.tile)
+
+            return extension_releases
         except Exception as e:
             logger.warning(e)
             return []
@@ -282,7 +337,6 @@ class ExtensionRelease(BaseModel):
 
     @classmethod
     async def fetch_release_details(cls, details_link: str) -> dict | None:
-
         try:
             async with httpx.AsyncClient() as client:
                 resp = await client.get(details_link)
@@ -307,6 +361,10 @@ class ExtensionMeta(BaseModel):
     dependencies: list[str] = []
     archive: str | None = None
     featured: bool = False
+    categories: list[str] = []
+    paid_features: str | None = None
+    has_paid_release: bool = False
+    has_free_release: bool = False
 
 
 class InstallableExtension(BaseModel):
@@ -318,6 +376,7 @@ class InstallableExtension(BaseModel):
     icon: str | None = None
     stars: int = 0
     meta: ExtensionMeta | None = None
+    permissions: list[ExtensionPermission] = []
 
     @property
     def hash(self) -> str:
@@ -370,15 +429,26 @@ class InstallableExtension(BaseModel):
             return False
         return self.meta.pay_to_enable.required is True
 
+    @property
+    def is_wasm(self) -> bool:
+        config_path = Path(self.ext_dir, "config.json")
+        if not config_path.is_file():
+            return False
+        try:
+            with open(config_path, encoding="utf-8") as json_file:
+                config_json = json.load(json_file)
+        except Exception:
+            return False
+        return config_json.get("extension_type") == "wasm"
+
     async def download_archive(self):
         logger.info(f"Downloading extension {self.name} ({self.installed_version}).")
         ext_zip_file = self.zip_path
         if ext_zip_file.is_file():
             os.remove(ext_zip_file)
         try:
-            assert (
-                self.meta and self.meta.installed_release
-            ), "installed_release is none."
+            if not self.meta or not self.meta.installed_release:
+                raise ValueError("No installed release.")
 
             self._restore_payment_info()
 
@@ -403,13 +473,36 @@ class InstallableExtension(BaseModel):
                 os.remove(ext_zip_file)
             raise AssertionError("File hash missmatch. Will not install.")
 
+    def load_archive_config(self) -> dict[str, Any]:
+        if not self.zip_path.is_file():
+            return {}
+
+        try:
+            with zipfile.ZipFile(self.zip_path, "r") as archive:
+                config_name = self._archive_config_name(archive.namelist())
+                if not config_name:
+                    return {}
+                with archive.open(config_name) as config_file:
+                    config = json.load(config_file)
+        except Exception as exc:
+            raise ValueError(f"Cannot read extension config for '{self.id}'.") from exc
+
+        return config if isinstance(config, dict) else {}
+
+    @staticmethod
+    def _archive_config_name(names: list[str]) -> str | None:
+        for name in names:
+            path = PurePosixPath(name)
+            if len(path.parts) == 2 and path.name == "config.json":
+                return name
+        return None
+
     def extract_archive(self):
         logger.info(f"Extracting extension {self.name} ({self.installed_version}).")
         Path(settings.lnbits_extensions_upgrade_path).mkdir(parents=True, exist_ok=True)
 
         tmp_dir = Path(settings.lnbits_data_folder, "unzip-temp", self.hash)
         shutil.rmtree(tmp_dir, True)
-
         with zipfile.ZipFile(self.zip_path, "r") as zip_ref:
             zip_ref.extractall(tmp_dir)
         generated_dir_name = os.listdir(tmp_dir)[0]
@@ -452,9 +545,23 @@ class InstallableExtension(BaseModel):
 
         shutil.rmtree(self.ext_upgrade_dir, True)
 
-    def check_latest_version(self, release: ExtensionRelease | None):
+    def check_release_updates(self, release: ExtensionRelease | None):
+        self._check_latest_version(release)
+        self._check_payment_link(release)
+
+    def find_existing_payment(self, pay_link: str | None) -> ReleasePaymentInfo | None:
+        if not pay_link or not self.meta or not self.meta.payments:
+            return None
+        return next(
+            (p for p in self.meta.payments if p.pay_link == pay_link),
+            None,
+        )
+
+    def _check_latest_version(self, release: ExtensionRelease | None):
         if not release:
             return
+        if not release.is_version_compatible:
+            return
         if not self.meta or not self.meta.latest_release:
             meta = self.meta or ExtensionMeta()
             meta.latest_release = release
@@ -465,13 +572,19 @@ class InstallableExtension(BaseModel):
         ):
             self.meta.latest_release = release
 
-    def find_existing_payment(self, pay_link: str | None) -> ReleasePaymentInfo | None:
-        if not pay_link or not self.meta or not self.meta.payments:
-            return None
-        return next(
-            (p for p in self.meta.payments if p.pay_link == pay_link),
-            None,
-        )
+    def _check_payment_link(self, release: ExtensionRelease | None):
+        if not release:
+            return
+        if not release.is_version_compatible:
+            return
+        if not self.meta:
+            self.meta = ExtensionMeta()
+        if release.pay_link:
+            self.meta.has_paid_release = True
+        else:
+            self.meta.has_free_release = True
+        if release.paid_features:
+            self.meta.paid_features = release.paid_features
 
     def _restore_payment_info(self):
         if (
@@ -562,6 +675,7 @@ class InstallableExtension(BaseModel):
                     version=version,
                     short_description=config_json.get("short_description"),
                     icon=config_json.get("tile"),
+                    permissions=ExtensionPermission.list_from_config(config_json),
                     meta=ExtensionMeta(
                         installed_release=ExtensionRelease(
                             name=ext_id,
@@ -581,6 +695,37 @@ class InstallableExtension(BaseModel):
 
     @classmethod
     async def get_installable_extensions(
+        cls, post_refresh_cache: bool = False
+    ) -> list[InstallableExtension]:
+        extension_list: list[InstallableExtension] = []
+
+        cache_key = "extensions:installable"
+        cache_value = cache.value(cache_key)
+        if not cache_value:
+            extension_list = await cls._get_installable_extensions()
+            cache.set(cache_key, extension_list, expiry=3600)  # one hour
+            return extension_list
+
+        if cache_value.older_than(10 * 60) or post_refresh_cache:
+            # refresh cache in background if older than 10 minutes or requested
+            create_task(cls._refresh_installable_extensions_cache())
+
+        extension_list = cache_value.value  # type: ignore
+        return extension_list
+
+    @classmethod
+    async def _refresh_installable_extensions_cache(
+        cls,
+    ) -> None:
+        cache_key = "extensions:installable"
+        extension_list: list[InstallableExtension] = (
+            await cls._get_installable_extensions()
+        )
+
+        cache.set(cache_key, extension_list, expiry=3600)
+
+    @classmethod
+    async def _get_installable_extensions(
         cls,
     ) -> list[InstallableExtension]:
         extension_list: list[InstallableExtension] = []
@@ -597,11 +742,16 @@ class InstallableExtension(BaseModel):
                         (ee for ee in extension_list if ee.id == r.id), None
                     )
                     if existing_ext and ext.meta:
-                        existing_ext.check_latest_version(ext.meta.latest_release)
+                        existing_ext.check_release_updates(ext.meta.latest_release)
                         continue
 
                     meta = ext.meta or ExtensionMeta()
                     meta.featured = ext.id in manifest.featured
+                    meta.categories = [
+                        category
+                        for category, ext_ids in manifest.categories.items()
+                        if ext.id in ext_ids
+                    ]
                     ext.meta = meta
                     extension_list += [ext]
 
@@ -611,12 +761,17 @@ class InstallableExtension(BaseModel):
                         (ee for ee in extension_list if ee.id == e.id), None
                     )
                     if existing_ext:
-                        existing_ext.check_latest_version(release)
+                        existing_ext.check_release_updates(release)
                         continue
                     ext = InstallableExtension.from_explicit_release(e)
-                    ext.check_latest_version(release)
+                    ext.check_release_updates(release)
                     meta = ext.meta or ExtensionMeta()
                     meta.featured = ext.id in manifest.featured
+                    meta.categories = [
+                        category
+                        for category, ext_ids in manifest.categories.items()
+                        if ext.id in ext_ids
+                    ]
                     ext.meta = meta
                     extension_list += [ext]
             except Exception as e:
@@ -628,8 +783,11 @@ class InstallableExtension(BaseModel):
     @classmethod
     async def get_extension_releases(cls, ext_id: str) -> list[ExtensionRelease]:
         extension_releases: list[ExtensionRelease] = []
-
-        for url in settings.lnbits_extensions_manifests:
+        all_manifests = [
+            *settings.lnbits_extensions_manifests,
+            settings.lnbits_extensions_builder_manifest_url,
+        ]
+        for url in all_manifests:
             try:
                 manifest = await cls.fetch_manifest(url)
                 for r in manifest.repos:
@@ -708,6 +866,7 @@ class CreateExtension(BaseModel):
     version: str
     cost_sats: int | None = 0
     payment_hash: str | None = None
+    permissions: list[ExtensionPermission] = []
 
 
 class ExtensionDetailsRequest(BaseModel):
@@ -716,6 +875,32 @@ class ExtensionDetailsRequest(BaseModel):
     version: str
 
 
+class ExtensionReviewsStatus(BaseModel):
+    tag: str
+    avg_rating: float
+    review_count: int
+
+
+class CreateExtensionReview(BaseModel):
+    tag: str
+    name: str | None = Field(None)
+    rating: int = Field(..., ge=0, le=1000)
+    comment: str | None = Field(None)
+
+
+class ExtensionReviewPaymentRequest(BaseModel):
+    payment_hash: str
+    payment_request: str
+
+
+class ExtensionReview(BaseModel):
+    id: str
+    name: str | None = Field(default=None)
+    tag: str | None = Field(default=None)
+    rating: int = Field(default=0, ge=0, le=1000)
+    comment: str | None = Field(default=None)
+
+
 async def github_api_get(url: str, error_msg: str | None) -> Any:
     headers = {"User-Agent": settings.user_agent}
     if settings.lnbits_ext_github_token:

lnbits/core/models/extensions_builder.py

@@ -0,0 +1,485 @@
+from __future__ import annotations
+
+import json
+import random
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Any, Literal
+
+from pydantic import BaseModel, validator
+
+from lnbits.helpers import (
+    camel_to_snake,
+    is_camel_case,
+    is_snake_case,
+    urlsafe_short_hash,
+)
+
+
+class DataField(BaseModel):
+    name: str
+    type: str
+    label: str | None = None
+    hint: str | None = None
+    optional: bool = False
+    editable: bool = False
+    searchable: bool = False
+    sortable: bool = False
+    fields: list[DataField] = []
+
+    def normalize(self) -> None:
+        self.name = self.name.strip()
+        self.type = self.type.strip()
+        if self.label:
+            self.label = self.label.strip()
+        if self.hint:
+            self.hint = self.hint.strip()
+        if self.type == "json":
+            self.editable = False
+            self.searchable = False
+            self.sortable = False
+        else:
+            self.fields = []
+
+        for field in self.fields:
+            field.normalize()
+
+    def field_to_py(self) -> str:
+        field_name = camel_to_snake(self.name)
+        field_type = self.type
+        if self.type == "json":
+            field_type = "dict"
+        elif self.type in ["wallet", "currency", "text"]:
+            field_type = "str"
+        if self.optional:
+            field_type += " | None"
+        if self.type == "currency":
+            field_type += ' = "sat"'
+        return f"{field_name}: {field_type}"
+
+    def field_to_random_value(self) -> str:
+        field_name = camel_to_snake(self.name)
+        field_value: Any = f'"{self.type}"'
+        if self.type == "json":
+            field_value = '"{}"'
+        elif self.type == "wallet":
+            field_value = f'"{uuid.uuid4()}"'
+        elif self.type == "currency":
+            field_value = '"sat"'
+        elif self.type in ["str", "text"]:
+            field_value = f'"{field_name}_{urlsafe_short_hash()}"'
+        elif self.type == "int":
+            field_value = random.randint(1, 100)  # noqa: S311
+        elif self.type == "float":
+            field_value = random.uniform(1.0, 100.0)  # noqa: S311
+        elif self.type == "bool":
+            field_value = random.choice([True, False])  # noqa: S311
+        elif self.type == "datetime":
+            random_days = random.randint(-30, 30)  # noqa: S311
+            random_date = datetime.now(timezone.utc) - timedelta(days=random_days)
+            field_value = f"""datetime.fromisoformat("{random_date.isoformat()}")"""
+        return f"{field_name} = {field_value},"
+
+    def field_to_js(self) -> str:
+        field_name = camel_to_snake(self.name)
+        default_value = "null"
+        if self.type == "json":
+            default_value = "{}"
+        if self.type == "currency":
+            default_value = '"sat"'
+        return f"{field_name}: {default_value}"
+
+    def field_to_ui_table_column(self) -> str:
+        column = {
+            "name": self.name,
+            "align": "left",
+            "label": self.label or self.name,
+            "field": self.name,
+            "sortable": self.sortable,
+        }
+
+        return json.dumps(column)
+
+    def field_to_db(self) -> str:
+        field_name = camel_to_snake(self.name)
+        field_type = self.type
+        if field_type == "str":
+            db_type = "TEXT"
+        elif field_type == "int":
+            db_type = "INT"
+        elif field_type == "float":
+            db_type = "REAL"
+        elif field_type == "bool":
+            db_type = "BOOLEAN"
+        elif field_type == "datetime":
+            db_type = "TIMESTAMP"
+        else:
+            db_type = "TEXT"
+
+        db_field = f"{field_name} {db_type}"
+        if not self.optional:
+            db_field += " NOT NULL"
+        if field_type == "json":
+            db_field += " DEFAULT '{empty_dict}'"
+        return db_field
+
+    def field_mock_value(self, index: int) -> Any:
+        if self.name == "id":
+            return urlsafe_short_hash()
+        if self.type == "int":
+            return index
+        elif self.type == "float":
+            return float(f"{index}.0{index * 2}")
+        elif self.type == "bool":
+            return True if index % 2 == 0 else False
+        elif self.type == "datetime":
+            return (datetime.now(timezone.utc) - timedelta(hours=index * 2)).isoformat()
+        elif self.type == "json":
+            return {"key": "value"}
+        elif self.type == "currency":
+            return "USD"
+        else:
+            return f"{self.name} {index}"
+
+    @validator("name")
+    def validate_name(cls, v: str) -> str:
+        if v.strip() == "":
+            raise ValueError("Field name is required.")
+        if not is_snake_case(v):
+            raise ValueError(f"Field Name must be snake_case. Found: {v}")
+        return v
+
+    @validator("type")
+    def validate_type(cls, v: str) -> str:
+        if v.strip() == "":
+            raise ValueError("Owner Data type is required")
+        if v not in [
+            "str",
+            "int",
+            "float",
+            "bool",
+            "datetime",
+            "json",
+            "wallet",
+            "currency",
+            "text",
+        ]:
+            raise ValueError(
+                "Field Type must be one of: "
+                "str, int, float, bool, datetime, json, wallet, currency, text."
+                f" Found: {v}"
+            )
+        return v
+
+    @validator("label")
+    def validate_label(cls, v: str | None) -> str | None:
+        if v and '"' in v:
+            raise ValueError(
+                f'Field label cannot contain double quotes ("). Value: {v}'
+            )
+        return v
+
+    @validator("hint")
+    def validate_hint(cls, v: str | None) -> str | None:
+        if v and '"' in v:
+            raise ValueError(f'Field hint cannot contain double quotes ("). Value: {v}')
+        return v
+
+
+class DataFields(BaseModel):
+    name: str
+    editable: bool = True
+    fields: list[DataField] = []
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        self.normalize()
+
+    def normalize(self) -> None:
+        self.name = self.name.strip()
+        for field in self.fields:
+            field.normalize()
+        if all(not field.editable for field in self.fields):
+            self.editable = False
+
+    def get_field_by_name(self, name: str | None) -> DataField | None:
+        if not name:
+            return None
+        for field in self.fields:
+            if field.name == name:
+                return field
+        return None
+
+    @validator("name")
+    def validate_name(cls, v: str) -> str:
+        if v.strip() == "":
+            raise ValueError("Data fields name is required")
+        if not is_camel_case(v):
+            raise ValueError(f"Data name must be CamelCase. Found: {v}")
+        return v
+
+
+class SettingsFields(DataFields):
+    enabled: bool = False
+    type: str = "user"
+
+    @validator("type")
+    def validate_type(cls, v: str) -> str:
+        if v.strip() == "":
+            raise ValueError("Settings type is required")
+        if v not in ["user", "admin"]:
+            raise ValueError("Field Type must be one of: user, admin." f" Found: {v}")
+        return v
+
+
+class ActionFields(BaseModel):
+    generate_action: bool = False
+    generate_payment_logic: bool = False
+    wallet_id: str | None = None
+    currency: str | None = None
+    amount: str | None = None
+    amount_source: Literal["owner_data", "client_data"] | None = None
+    paid_flag: str | None = None
+
+
+class OwnerDataFields(BaseModel):
+    name: str | None = None
+    description: str | None = None
+
+
+class ClientDataFields(BaseModel):
+    public_inputs: list[str] = []
+
+
+class PublicPageFields(BaseModel):
+    has_public_page: bool = False
+    owner_data_fields: OwnerDataFields
+    client_data_fields: ClientDataFields
+    action_fields: ActionFields
+
+
+class PreviewAction(BaseModel):
+    is_preview_mode: bool = False
+    is_settings_preview: bool = False
+    is_owner_data_preview: bool = False
+    is_client_data_preview: bool = False
+    is_public_page_preview: bool = False
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        if not self.is_preview_mode:
+            self.is_settings_preview = False
+            self.is_owner_data_preview = False
+            self.is_client_data_preview = False
+            self.is_public_page_preview = False
+
+
+class ExtensionData(BaseModel):
+    id: str
+    name: str
+    stub_version: str | None
+    short_description: str | None = None
+    description: str | None = None
+    owner_data: DataFields
+    client_data: DataFields
+    settings_data: SettingsFields
+    public_page: PublicPageFields
+    preview_action: PreviewAction = PreviewAction()
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        self.validate_data()
+        self.normalize()
+
+    def normalize(self) -> None:
+        self.id = self.id.strip()
+        self.name = self.name.strip()
+        if self.stub_version:
+            self.stub_version = self.stub_version.strip()
+        if self.short_description:
+            self.short_description = self.short_description.strip()
+        if self.description:
+            self.description = self.description.strip()
+        if not self.public_page.has_public_page:
+            self.public_page.action_fields.generate_action = False
+            self.public_page.action_fields.generate_payment_logic = False
+        if not self.public_page.action_fields.generate_action:
+            self.public_page.action_fields.generate_payment_logic = False
+
+    def validate_data(self) -> None:
+        self._validate_field_names()
+        self._validate_public_page_fields()
+        self._validate_action_fields()
+
+    def _validate_public_page_fields(self) -> None:
+        if not self.public_page.has_public_page:
+            return
+
+        public_page_name = self.public_page.owner_data_fields.name
+        if public_page_name:
+            public_page_name_field = self.owner_data.get_field_by_name(public_page_name)
+            if not public_page_name_field:
+                raise ValueError(
+                    "Public Page Name must be one of the owner data fields."
+                    f" Received: {public_page_name}."
+                )
+
+        public_page_description = self.public_page.owner_data_fields.description
+        if public_page_description:
+            public_page_description_field = self.owner_data.get_field_by_name(
+                public_page_description
+            )
+            if not public_page_description_field:
+                raise ValueError(
+                    "Public Page Description must be one of the owner data fields."
+                    f" Received: {public_page_description}."
+                )
+
+        public_page_inputs = self.public_page.client_data_fields.public_inputs
+        if public_page_inputs:
+            for input_field in public_page_inputs:
+                input_field_obj = self.client_data.get_field_by_name(input_field)
+                if not input_field_obj:
+                    raise ValueError(
+                        "Public Page Input fields"
+                        " must be one of the client data fields."
+                        f" Received: {input_field}."
+                    )
+
+    def _validate_action_fields(self) -> None:
+        if not self.public_page.action_fields.generate_action:
+            return
+        if not self.public_page.action_fields.generate_payment_logic:
+            return
+
+        self._validate_owner_data_fields()
+        self._validate_client_data_fields()
+
+    def _validate_owner_data_fields(self) -> None:
+        wallet_id = self.public_page.action_fields.wallet_id
+        if wallet_id:
+            wallet_id_field = self.owner_data.get_field_by_name(wallet_id)
+            if not wallet_id_field:
+                raise ValueError(
+                    "Action Wallet ID must be one of the owner data fields."
+                    f" Received: {wallet_id}."
+                )
+            if wallet_id_field.type != "wallet":
+                raise ValueError(
+                    "Action Wallet ID field type must be 'wallet'."
+                    f" Received: {wallet_id_field.type}."
+                )
+        currency = self.public_page.action_fields.currency
+        if currency:
+            currency_field = self.owner_data.get_field_by_name(currency)
+            if not currency_field:
+                raise ValueError(
+                    "Action Currency must be one of the owner data fields."
+                    f" Received: {currency}."
+                )
+            if currency_field.type != "currency":
+                raise ValueError(
+                    "Action Currency field type must be 'currency'."
+                    f" Received: {currency_field.type}."
+                )
+
+    def _validate_field_names(self) -> None:
+        reserved_names = {"id", "created_at", "updated_at"}
+        nok = {f.name for f in self.owner_data.fields}.intersection(reserved_names)
+        if nok:
+            raise ValueError(
+                f"Owner Data fields cannot have reserved names: '{', '.join(nok)}.'"
+            )
+        nok = {f.name for f in self.client_data.fields}.intersection(reserved_names)
+        if nok:
+            raise ValueError(
+                f"Client Data fields cannot have reserved names: '{', '.join(nok)}.'"
+            )
+        nok = {f.name for f in self.settings_data.fields}.intersection(reserved_names)
+        if nok:
+            raise ValueError(
+                f"Settings fields cannot have reserved names: '{', '.join(nok)}.'"
+            )
+
+    def _validate_client_data_fields(self) -> None:
+        amount = self.public_page.action_fields.amount
+        amount_source = self.public_page.action_fields.amount_source
+        if amount_source and amount:
+            if amount_source == "owner_data":
+                amount_field = self.owner_data.get_field_by_name(amount)
+            else:
+                amount_field = self.client_data.get_field_by_name(amount)
+            if not amount_field:
+                raise ValueError(
+                    "Action Amount must be one of the "
+                    "client data or owner data fields."
+                    f" Received: {amount}."
+                )
+            if amount_field.type not in ["int", "float"]:
+                raise ValueError(
+                    "Action Amount field type must be 'int' or 'float'."
+                    f" Received: {amount_field.type}."
+                )
+        paid_flag = self.public_page.action_fields.paid_flag
+        if paid_flag:
+            paid_flag_field = self.client_data.get_field_by_name(paid_flag)
+            if not paid_flag_field:
+                raise ValueError(
+                    "Action Paid Flag must be one of the client data fields."
+                    f" Received: {paid_flag}."
+                )
+            if paid_flag_field.type != "bool":
+                raise ValueError(
+                    "Action Paid Flag field type must be 'bool'."
+                    f" Received: {paid_flag_field.type}."
+                )
+
+    @validator("id")
+    def validate_id(cls, v: str) -> str:
+        if v.strip() == "":
+            raise ValueError("Extension ID is required")
+        if not is_snake_case(v):
+            raise ValueError(f"Extension Id must be snake_case. Found: {v}")
+        return v
+
+    @validator("name")
+    def validate_name(cls, v: str) -> str:
+        if v.strip() == "":
+            raise ValueError("Extension name is required")
+        return v
+
+    @validator("stub_version")
+    def validate_stub_version(cls, v: str | None) -> str | None:
+        if v and '"' in v:
+            raise ValueError(
+                f'Extension stub version cannot contain double quotes ("). Value: {v}'
+            )
+        return v
+
+    @validator("short_description")
+    def validate_short_description(cls, v: str | None) -> str | None:
+        if v and '"' in v:
+            raise ValueError(
+                f'Field short description cannot contain double quotes ("). Value: {v}'
+            )
+        return v
+
+    @validator("description")
+    def validate_description(cls, v: str | None) -> str | None:
+        if v and '"' in v:
+            raise ValueError(
+                f'Field description cannot contain double quotes ("). Value: {v}'
+            )
+        return v
+
+    @validator("owner_data")
+    def validate_owner_data(cls, v: DataFields) -> DataFields:
+        if len(v.fields) == 0:
+            raise ValueError("At least one owner data field is required")
+        return v
+
+    @validator("client_data")
+    def validate_client_data(cls, v: DataFields) -> DataFields:
+        if len(v.fields) == 0:
+            raise ValueError("At least one client data field is required")
+        return v

lnbits/core/models/lnurl.py

@@ -1,20 +1,31 @@
-from typing import Optional
+from time import time
 
-from pydantic import BaseModel
+from lnurl import LnAddress, Lnurl, LnurlPayResponse
+from pydantic import BaseModel, Field
 
 
-class CreateLnurl(BaseModel):
-    description_hash: str
-    callback: str
+class CreateLnurlPayment(BaseModel):
+    res: LnurlPayResponse | None = None
+    lnurl: Lnurl | LnAddress | None = None
     amount: int
-    comment: Optional[str] = None
-    description: Optional[str] = None
-    unit: Optional[str] = None
+    comment: str | None = None
+    unit: str | None = None
+    internal_memo: str | None = None
 
 
-class CreateLnurlAuth(BaseModel):
-    callback: str
+class CreateLnurlWithdraw(BaseModel):
+    lnurl_w: Lnurl
 
 
-class PayLnurlWData(BaseModel):
-    lnurl_w: str
+class LnurlScan(BaseModel):
+    lnurl: Lnurl | LnAddress
+
+
+class StoredPayLink(BaseModel):
+    lnurl: str
+    label: str
+    last_used: int = Field(default_factory=lambda: int(time()))
+
+
+class StoredPayLinks(BaseModel):
+    links: list[StoredPayLink] = []

lnbits/core/models/misc.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Callable
+from collections.abc import Awaitable, Callable
+from typing import Any
 
 from pydantic import BaseModel
 
@@ -9,9 +10,34 @@ def _do_nothing(*_):
     pass
 
 
+async def _do_nothing_async(_: Any) -> None:
+    pass
+
+
 class CoreAppExtra:
     register_new_ext_routes: Callable = _do_nothing
+    register_new_wasm_ext_routes: Callable = _do_nothing
     register_new_ratelimiter: Callable
+    dispatch_extension_invoice_paid: Callable[[Any], Awaitable[None]] = (
+        _do_nothing_async
+    )
+
+    def __init__(self) -> None:
+        self.wasm_extension_registry = WasmExtensionRegistry()
+
+
+class WasmExtensionRegistry:
+    def __init__(self) -> None:
+        self._extensions: dict[str, Any] = {}
+
+    def register(self, extension: Any) -> None:
+        self._extensions[extension.id] = extension
+
+    def get(self, ext_id: str) -> Any | None:
+        return self._extensions.get(ext_id)
+
+    def list(self) -> list[Any]:
+        return list(self._extensions.values())
 
 
 class ConversionData(BaseModel):
@@ -46,3 +72,8 @@ class SimpleItem(BaseModel):
 class DbVersion(BaseModel):
     db: str
     version: int
+
+
+class Image(BaseModel):
+    filename: str
+    directory: str = "library"

lnbits/core/models/notifications.py

@@ -2,6 +2,8 @@ from enum import Enum
 
 from pydantic import BaseModel
 
+from lnbits.core.models.users import UserNotifications
+
 
 class NotificationType(Enum):
     server_status = "server_status"
@@ -18,6 +20,7 @@ class NotificationType(Enum):
 class NotificationMessage(BaseModel):
     message_type: NotificationType
     values: dict
+    user_notifications: UserNotifications | None = None
 
 
 NOTIFICATION_TEMPLATES = {
@@ -29,7 +32,8 @@ NOTIFICATION_TEMPLATES = {
         *In/Out payments*: `{in_payments_count}`/`{out_payments_count}`.
         *Pending payments*: `{pending_payments_count}`.
         *Failed payments*: `{failed_payments_count}`.
-        *LNbits balance*: `{lnbits_balance_sats}` sats.""",
+        *LNbits balance*: `{lnbits_balance_sats}` sats.
+        *Node balance*: `{node_balance_sats}` sats.""",
     "server_start_stop": """*SERVER*
         {message}
         *Time*: `{up_time}` seconds.

lnbits/core/models/payments.py

@@ -5,16 +5,18 @@ from enum import Enum
 from typing import Literal
 
 from fastapi import Query
+from lnurl import LnurlWithdrawResponse
+from loguru import logger
 from pydantic import BaseModel, Field, validator
 
 from lnbits.db import FilterModel
+from lnbits.fiat.base import (
+    FiatPaymentStatus,
+)
+from lnbits.helpers import is_valid_external_id
 from lnbits.utils.exchange_rates import allowed_currencies
-from lnbits.wallets import get_funding_source
 from lnbits.wallets.base import (
-    PaymentFailedStatus,
-    PaymentPendingStatus,
     PaymentStatus,
-    PaymentSuccessStatus,
 )
 
 
@@ -33,6 +35,11 @@ class PaymentExtra(BaseModel):
     lnurl_response: str | None = None
 
 
+class UpdatePaymentExtra(BaseModel):
+    payment_hash: str
+    extra: dict = Field(default_factory=dict)
+
+
 class PayInvoice(BaseModel):
     payment_request: str
     description: str | None = None
@@ -47,10 +54,17 @@ class CreatePayment(BaseModel):
     amount_msat: int
     memo: str
     extra: dict | None = {}
+    extension: str | None = None
     preimage: str | None = None
     expiry: datetime | None = None
     webhook: str | None = None
     fee: int = 0
+    labels: list[str] | None = None
+    external_id: str | None = None
+
+    @validator("external_id")
+    def validate_external_id(cls, external_id):
+        return _validate_external_id(external_id)
 
 
 class Payment(BaseModel):
@@ -60,18 +74,33 @@ class Payment(BaseModel):
     amount: int
     fee: int
     bolt11: str
+    payment_request: str | None = Field(default=None, no_database=True)
+    fiat_provider: str | None = None
     status: str = PaymentState.PENDING
     memo: str | None = None
     expiry: datetime | None = None
     webhook: str | None = None
-    webhook_status: int | None = None
+    webhook_status: str | None = None
     preimage: str | None = None
     tag: str | None = None
     extension: str | None = None
     time: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
     created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
     updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    labels: list[str] = []
     extra: dict = {}
+    external_id: str | None = None
+
+    @validator("external_id")
+    def validate_external_id(cls, external_id):
+        return _validate_external_id(external_id)
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        if "fiat_payment_request" in self.extra:
+            self.payment_request = self.extra["fiat_payment_request"]
+        else:
+            self.payment_request = self.bolt11
 
     @property
     def pending(self) -> bool:
@@ -107,31 +136,52 @@ class Payment(BaseModel):
 
     @property
     def is_internal(self) -> bool:
-        return self.checking_id.startswith("internal_")
+        return self.checking_id.startswith("internal_") or self.checking_id.startswith(
+            "fiat_"
+        )
 
+    # DEPRECATED: in v1.5.0, use service check_payment_status instead
     async def check_status(self) -> PaymentStatus:
-        if self.is_internal:
-            if self.success:
-                return PaymentSuccessStatus()
-            if self.failed:
-                return PaymentFailedStatus()
-            return PaymentPendingStatus()
-        funding_source = get_funding_source()
-        if self.is_out:
-            status = await funding_source.get_payment_status(self.checking_id)
-        else:
-            status = await funding_source.get_invoice_status(self.checking_id)
-        return status
+        logger.warning("payment.check_status() is deprecated.")
+        from lnbits.core.services.payments import check_payment_status
+
+        return await check_payment_status(self)
+
+    # DEPRECATED: in v1.5.0, use service check_payment_status instead
+    async def check_fiat_status(self) -> FiatPaymentStatus:
+        logger.warning("payment.check_fiat_status() is deprecated.")
+        from lnbits.core.services.fiat_providers import check_fiat_status
+
+        return await check_fiat_status(self)
 
 
 class PaymentFilters(FilterModel):
-    __search_fields__ = ["memo", "amount", "wallet_id", "tag", "status", "time"]
+    __search_fields__ = [
+        "memo",
+        "amount",
+        "wallet_id",
+        "tag",
+        "status",
+        "time",
+        "labels",
+        "external_id",
+    ]
 
-    __sort_fields__ = ["created_at", "amount", "fee", "memo", "time", "tag"]
+    __sort_fields__ = [
+        "created_at",
+        "updated_at",
+        "amount",
+        "fee",
+        "memo",
+        "time",
+        "tag",
+        "external_id",
+    ]
 
     status: str | None
     tag: str | None
     checking_id: str | None
+    external_id: str | None
     amount: int
     fee: int
     memo: str | None
@@ -139,6 +189,7 @@ class PaymentFilters(FilterModel):
     preimage: str | None
     payment_hash: str | None
     wallet_id: str | None
+    labels: str | None
 
 
 class PaymentDataPoint(BaseModel):
@@ -198,14 +249,30 @@ class CreateInvoice(BaseModel):
     internal: bool = False
     out: bool = True
     amount: float = Query(None, ge=0)
-    memo: str | None = None
+    memo: str | None = Query(None, max_length=640)
     description_hash: str | None = None
     unhashed_description: str | None = None
+    payment_hash: str | None = Query(
+        None,
+        description="The payment hash of the hold invoice.",
+        min_length=64,
+        max_length=64,
+    )
     expiry: int | None = None
     extra: dict | None = None
+    extension: str | None = None
     webhook: str | None = None
     bolt11: str | None = None
-    lnurl_callback: str | None = None
+    lnurl_withdraw: LnurlWithdrawResponse | None = None
+    fiat_provider: str | None = None
+    labels: list[str] = []
+    external_id: str | None = Query(default=None, max_length=256)
+
+    @validator("payment_hash")
+    def check_hex(cls, v):
+        if v:
+            _ = bytes.fromhex(v)
+        return v
 
     @validator("unit")
     @classmethod
@@ -214,9 +281,54 @@ class CreateInvoice(BaseModel):
             raise ValueError("The provided unit is not supported")
         return v
 
+    @validator("external_id")
+    def validate_external_id(cls, external_id):
+        return _validate_external_id(external_id)
+
 
 class PaymentsStatusCount(BaseModel):
     incoming: int = 0
     outgoing: int = 0
     failed: int = 0
     pending: int = 0
+
+
+class SettleInvoice(BaseModel):
+    preimage: str = Field(
+        ...,
+        description="The preimage of the payment hash to settle the invoice.",
+        min_length=64,
+        max_length=64,
+    )
+
+    @validator("preimage")
+    def check_hex(cls, v):
+        _ = bytes.fromhex(v)
+        return v
+
+
+class CancelInvoice(BaseModel):
+    payment_hash: str = Field(
+        ...,
+        description="The payment hash of the invoice to cancel.",
+        min_length=64,
+        max_length=64,
+    )
+
+    @validator("payment_hash")
+    def check_hex(cls, v):
+        _ = bytes.fromhex(v)
+        return v
+
+
+class UpdatePaymentLabels(BaseModel):
+    labels: list[str] = []
+
+
+def _validate_external_id(external_id: str | None) -> str | None:
+    if external_id and not is_valid_external_id(external_id):
+        raise ValueError(
+            "Invalid external id. Max length is 256 characters. "
+            "Space and newlines are not allowed."
+        )
+    return external_id

lnbits/core/models/sso/__init__.py

@@ -0,0 +1 @@
+"""SSO authentication providers for LNbits"""

lnbits/core/models/sso/keycloak.py

@@ -1,5 +1,4 @@
-"""Keycloak SSO Login Helper
-"""
+"""Keycloak SSO Login Helper"""
 
 from typing import Optional