conduit-lightning 0.1.0__tar.gz

conduit_lightning-0.1.0/.env.example

@@ -0,0 +1,64 @@
+# =============================================================================
+# Conduit Environment Configuration
+# Copy this file to .env and fill in your values
+# =============================================================================
+
+# --- App ---
+APP_NAME=Conduit
+APP_ENV=development
+DEBUG=false
+API_HOST=127.0.0.1
+API_PORT=8000
+
+# --- API Authentication ---
+# Generate a strong random key: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+CONDUIT_API_KEY=CHANGE-ME-generate-a-random-key
+
+# --- PostgreSQL ---
+DATABASE_URL=postgresql+asyncpg://conduit:conduit@localhost:5432/conduit
+
+# --- Redis (optional, falls back to in-memory rate limiting) ---
+REDIS_URL=redis://localhost:6379/0
+
+# --- Wallet Backend ---
+# "lnd" = direct gRPC to your LND node
+# "nwc" = Nostr Wallet Connect (Alby, Primal, Zeus, etc.)
+# "auto" = use NWC if connection string is set, else LND
+WALLET_BACKEND=auto
+
+# --- NWC (Nostr Wallet Connect) ---
+# Paste your connection string from your wallet app (e.g. Alby)
+# NWC_CONNECTION_STRING=nostr+walletconnect://...
+
+# --- LND Node (only needed if WALLET_BACKEND=lnd) ---
+LND_HOST=localhost
+LND_GRPC_PORT=10009
+LND_REST_PORT=8080
+LND_TLS_CERT_PATH=~/.lnd/tls.cert
+LND_MACAROON_PATH=~/.lnd/data/chain/bitcoin/regtest/admin.macaroon
+# Set to "mainnet", "testnet", or "regtest"
+LND_NETWORK=regtest
+
+# --- L402 Auth ---
+L402_ENABLED=false
+# Generate a unique secret: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+L402_SECRET_KEY=CHANGE-ME-generate-a-random-secret
+L402_TOKEN_EXPIRY_SECONDS=3600
+L402_DEFAULT_PRICE_SATS=10
+
+# --- Fees ---
+TRANSACTION_FEE_PERCENT=1.5
+
+# --- Spending Limits (sats, 0 = unlimited) ---
+SPENDING_LIMIT_PER_PAYMENT_SATS=10000
+SPENDING_LIMIT_HOURLY_SATS=50000
+SPENDING_LIMIT_DAILY_SATS=200000
+SPENDING_CONFIRM_ABOVE_SATS=1000
+
+# --- CORS ---
+# Comma-separated origins. Never use "*" in production.
+CORS_ALLOW_ORIGINS=http://localhost:3000
+
+# --- Nostr (optional) ---
+# NOSTR_PRIVATE_KEY=nsec1...
+# NOSTR_RELAYS=wss://relay.damus.io,wss://nos.lol

conduit_lightning-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment files
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Raw proto definitions (generated stubs ARE committed)
+src/conduit/services/protos/
+
+# Alembic auto-stamp
+alembic/versions/__pycache__/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# LND credentials (NEVER commit these)
+credentials/
+
+# L4: Catch credential files anywhere in the tree
+*.macaroon
+*.pem
+*.cert
+*.key
+*.nsec
+
+# Docker volumes
+postgres_data/
+get-pip.py
+
+# Sensitive scripts (keep local only)
+cleanup_db.py
+demo_e2e.py
+SECURITY_AUDIT.md
+
+# Internal strategy/architecture docs (keep local only)
+conduit_competitive_intel.md
+conduit_full_architecture.md
+conduit_noncustodial_architecture.md
+
+# Local-only project guide for Claude (loaded from disk; kept out of the public repo)
+CLAUDE.md
+CLAUDE.local.md

conduit_lightning-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conduit-Agentic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

conduit_lightning-0.1.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: conduit-lightning
+Version: 0.1.0
+Summary: Lightning Payment Rails for AI Agents — discover, pay for, and execute skills over Lightning via MCP or REST
+Project-URL: Homepage, https://github.com/Lightning-Linq/Conduit
+Project-URL: Repository, https://github.com/Lightning-Linq/Conduit
+Project-URL: Issues, https://github.com/Lightning-Linq/Conduit/issues
+Author: Lightning Linq
+License: MIT License
+        
+        Copyright (c) 2026 Conduit-Agentic
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-agents,bitcoin,l402,lightning,mcp,nostr,nwc,payments
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: coincurve>=20.0.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: grpcio>=1.64.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: protobuf>=5.27.0
+Requires-Dist: pydantic-settings>=2.3.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pymacaroons>=0.13.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: qrcode[pil]>=7.4.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.64.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: publish
+Requires-Dist: build>=1.2.0; extra == 'publish'
+Requires-Dist: twine>=5.0.0; extra == 'publish'
+Description-Content-Type: text/markdown
+
+# Conduit
+
+**Lightning Payment Rails for AI Agents** | by [Lightning Linq](https://lightninglinq.com)
+
+Conduit is a non-custodial payment infrastructure layer that lets AI agents transact over the Lightning Network. It exposes a skill marketplace and Lightning tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), enabling any MCP-compatible AI (like Claude) to discover, purchase, and rate agent-provided services -- all settled instantly in Bitcoin.
+
+Conduit never takes custody of funds. Payments flow directly between agents on Lightning. Conduit provides coordination, discovery, reputation, and security -- never custody.
+
+> Conduit is the first product from **Lightning Linq**, an open-source company building Lightning infrastructure for AI agents.
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                     Claude Desktop                        │
+│                  (or any MCP client)                      │
+└──────────────┬───────────────────────────────────────────┘
+               │ MCP (stdio)
+               ▼
+┌──────────────────────────────────────────────────────────┐
+│                   Conduit MCP Server                      │
+│                                                           │
+│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐ │
+│  │  Lightning   │  │  Marketplace │  │    Security      │ │
+│  │   Tools      │  │    Tools     │  │    Layer         │ │
+│  │             │  │              │  │                   │ │
+│  │ • invoices  │  │ • discover   │  │ • API key auth   │ │
+│  │ • payments  │  │ • register   │  │ • macaroons      │ │
+│  │ • balance   │  │ • execute    │  │ • spending limits │ │
+│  │ • decode    │  │ • rate       │  │ • rate limiting   │ │
+│  │             │  │ • verify     │  │ • anomaly detect  │ │
+│  └──────┬──────┘  └──────┬───────┘  └─────────────────┘ │
+│         │                │                                │
+└─────────┼────────────────┼────────────────────────────────┘
+          │                │
+          ▼                ▼
+┌──────────────┐   ┌──────────────┐
+│   LND Node   │   │  PostgreSQL  │
+│  (your node) │   │  (local DB)  │
+│              │   │              │
+│  non-custodial   │  skills,     │
+│  payments    │   │  executions, │
+│              │   │  ratings,    │
+│              │   │  audit logs  │
+└──────────────┘   └──────────────┘
+```
+
+## Features
+
+**Lightning Network Integration** — Create and pay invoices via your own LND node. Decode payment requests, check payment status, view node info and channel balances. Non-custodial: your keys, your node, your sats.
+
+**Skill Marketplace** — Register skills with pricing, categories, and input/output schemas. Discover skills by keyword, category, or price range. Request executions with automatic Lightning invoicing. Webhook-based execution engine with payment proof delivery. Rating system backed by cryptographic payment proofs.
+
+**Security Stack** — API key authentication, scoped macaroon authorization (8 permissions, 4 profiles), per-payment/hourly/daily spending limits, in-memory sliding window rate limiting, anomaly detection (self-payment, rapid repeat, structuring, volume spike), rating integrity (preimage verification, duplicate prevention, weighted averages), and provider verification via Lightning node signatures and domain proof.
+
+## Quick Start
+
+```bash
+git clone https://github.com/Lightning-Linq/conduit.git
+cd conduit
+chmod +x install.sh
+./install.sh
+```
+
+The install script handles everything: checks prerequisites (Python 3.11+, PostgreSQL), creates virtual environment, installs dependencies, generates a secure API key, sets up the database, runs migrations, and shows you how to wire it into Claude Desktop.
+
+### Prerequisites
+
+- **Python 3.11+** — `brew install python@3.11` or use pyenv
+- **PostgreSQL 16** — `brew install postgresql@16 && brew services start postgresql@16`
+- **LND node** — running and accessible (local, remote, or via Tor)
+
+### Claude Desktop Configuration
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "conduit-lightning": {
+      "command": "/path/to/conduit/.venv/bin/python",
+      "args": ["-m", "conduit.mcp_server"],
+      "env": {
+        "PYTHONPATH": "/path/to/conduit/src"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Ask Claude: *"What's my Lightning node balance?"*
+
+## MCP Tools Reference
+
+Conduit exposes 19 tools over the Model Context Protocol.
+
+### Lightning Tools
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `get_node_info` | lightning:read | Node alias, pubkey, active channels, peers |
+| `get_balance` | lightning:read | On-chain and channel balances |
+| `create_invoice` | lightning:invoice | Generate a Lightning invoice |
+| `pay_invoice` | lightning:pay | Pay a Lightning invoice (with spending limits) |
+| `decode_invoice` | lightning:read | Decode a payment request without paying |
+| `check_payment` | lightning:read | Check if a payment has settled |
+
+### Marketplace Tools
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `discover_skills` | marketplace:read | Search skills by keyword, category, price |
+| `get_skill_details` | marketplace:read | Full details including schemas and ratings |
+| `register_skill` | marketplace:write | List a new skill on the marketplace |
+| `request_skill_execution` | marketplace:execute | Request execution (generates invoice) |
+| `confirm_skill_execution` | marketplace:execute | Confirm payment and trigger webhook |
+| `submit_rating` | marketplace:execute | Rate a skill (requires payment proof) |
+
+### Verification Tools
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `request_verification` | marketplace:write | Start node or domain verification |
+| `submit_verification` | marketplace:write | Complete verification with proof |
+| `get_verification_status` | marketplace:read | Check a skill's verification badges |
+
+### Security Tools
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `get_spending_status` | security:read | Current spending vs. limits |
+| `create_macaroon` | security:admin | Mint a scoped authorization token |
+| `list_permissions` | security:read | Show active permissions |
+| `get_anomaly_report` | security:read | View flagged suspicious patterns |
+
+## Security Model
+
+Conduit uses defense-in-depth with multiple security layers.
+
+**Authentication** — An API key is required to start the server. Without it, the MCP server refuses to run.
+
+**Authorization** — Macaroon-based scoping with 8 permission levels. Create restricted tokens for specific use cases (read-only, marketplace-only, spending-only).
+
+**Spending Controls** — Configurable per-payment limits (default 10,000 sats), hourly caps (50,000 sats), daily caps (200,000 sats), and confirmation prompts for payments above a threshold.
+
+**Rate Limiting** — Per-tool sliding window rate limits. Write operations are tightly limited (e.g., 5 skill registrations per 10 minutes). Read operations are generous (60/min).
+
+**Anomaly Detection** — Runs after every payment and execution. Detects self-payment, rapid repeat transactions, structuring near limits, and volume spikes. Advisory mode: flags are logged but transactions aren't blocked.
+
+**Rating Integrity** — Ratings require a payment preimage (SHA-256 proof of purchase). One rating per execution (enforced by unique constraint). 30-second minimum delay. Weighted averages discount repeat reviewers (1/n diminishing weight).
+
+**Provider Verification** — Providers can prove identity via Lightning node signatures (`lncli signmessage`) or domain verification (`.well-known` URL). Verified skills display trust badges in marketplace listings.
+
+## Configuration
+
+All settings via environment variables or `.env`:
+
+```bash
+# API Key (required)
+CONDUIT_API_KEY=your-secret-key
+
+# LND Connection
+LND_HOST=192.168.1.x
+LND_GRPC_PORT=10009
+LND_TLS_CERT_PATH=credentials/full-chain.pem
+LND_MACAROON_PATH=credentials/admin.macaroon
+LND_NETWORK=mainnet
+
+# Database
+DATABASE_URL=postgresql+asyncpg://conduit:conduit@localhost:5432/conduit
+
+# Spending Limits (sats, 0 = no limit)
+SPENDING_LIMIT_PER_PAYMENT_SATS=10000
+SPENDING_LIMIT_HOURLY_SATS=50000
+SPENDING_LIMIT_DAILY_SATS=200000
+SPENDING_CONFIRM_ABOVE_SATS=5000
+
+# Keep false for MCP servers (echo corrupts stdio transport)
+DEBUG=false
+```
+
+## Project Structure
+
+```
+src/conduit/
+├── mcp_server.py                # MCP server entry point — 19 tools
+├── core/
+│   ├── config.py                # Settings from .env
+│   └── database.py              # Async SQLAlchemy + asyncpg
+├── models/
+│   ├── skill.py                 # Skill marketplace listings
+│   ├── execution.py             # Skill execution tracking
+│   ├── rating.py                # Payment-proof-backed ratings
+│   ├── spending_log.py          # Spending audit trail
+│   └── anomaly_flag.py          # Suspicious pattern flags
+├── services/
+│   ├── lnd.py                   # LND gRPC client (sign, verify, pay)
+│   ├── spending_limiter.py      # Payment limit enforcement
+│   ├── macaroon_auth.py         # Scoped authorization tokens
+│   ├── rate_limiter.py          # Sliding window rate limits
+│   ├── anomaly_detector.py      # Transaction pattern detection
+│   ├── rating_integrity.py      # Anti-gaming for ratings
+│   ├── provider_verification.py # Node + domain verification
+│   └── skill_executor.py        # Webhook-based execution engine
+└── alembic/                     # Database migrations
+```
+
+## Roadmap
+
+- [x] Lightning Network integration (LND gRPC)
+- [x] MCP server with 19 tools
+- [x] Skill marketplace (register, discover, execute, rate)
+- [x] PostgreSQL persistence with Alembic migrations
+- [x] Full security stack (auth, macaroons, limits, anomaly detection)
+- [x] Provider verification (Lightning node + domain)
+- [x] One-command install script
+- [x] Nostr protocol for decentralized skill discovery (NIP-01/19/33)
+- [x] Nostr Wallet Connect (NWC) with NIP-44 v2 encryption
+- [x] REST API layer alongside MCP (27 endpoints, FastAPI)
+- [ ] Multi-node federation
+- [ ] Package for distribution (`pip install conduit-lightning`)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

conduit_lightning-0.1.0/README.md

@@ -0,0 +1,225 @@
+# Conduit
+
+**Lightning Payment Rails for AI Agents** | by [Lightning Linq](https://lightninglinq.com)
+
+Conduit is a non-custodial payment infrastructure layer that lets AI agents transact over the Lightning Network. It exposes a skill marketplace and Lightning tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), enabling any MCP-compatible AI (like Claude) to discover, purchase, and rate agent-provided services -- all settled instantly in Bitcoin.
+
+Conduit never takes custody of funds. Payments flow directly between agents on Lightning. Conduit provides coordination, discovery, reputation, and security -- never custody.
+
+> Conduit is the first product from **Lightning Linq**, an open-source company building Lightning infrastructure for AI agents.
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                     Claude Desktop                        │
+│                  (or any MCP client)                      │
+└──────────────┬───────────────────────────────────────────┘
+               │ MCP (stdio)
+               ▼
+┌──────────────────────────────────────────────────────────┐
+│                   Conduit MCP Server                      │
+│                                                           │
+│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐ │
+│  │  Lightning   │  │  Marketplace │  │    Security      │ │
+│  │   Tools      │  │    Tools     │  │    Layer         │ │
+│  │             │  │              │  │                   │ │
+│  │ • invoices  │  │ • discover   │  │ • API key auth   │ │
+│  │ • payments  │  │ • register   │  │ • macaroons      │ │
+│  │ • balance   │  │ • execute    │  │ • spending limits │ │
+│  │ • decode    │  │ • rate       │  │ • rate limiting   │ │
+│  │             │  │ • verify     │  │ • anomaly detect  │ │
+│  └──────┬──────┘  └──────┬───────┘  └─────────────────┘ │
+│         │                │                                │
+└─────────┼────────────────┼────────────────────────────────┘
+          │                │
+          ▼                ▼
+┌──────────────┐   ┌──────────────┐
+│   LND Node   │   │  PostgreSQL  │
+│  (your node) │   │  (local DB)  │
+│              │   │              │
+│  non-custodial   │  skills,     │
+│  payments    │   │  executions, │
+│              │   │  ratings,    │
+│              │   │  audit logs  │
+└──────────────┘   └──────────────┘
+```
+
+## Features
+
+**Lightning Network Integration** — Create and pay invoices via your own LND node. Decode payment requests, check payment status, view node info and channel balances. Non-custodial: your keys, your node, your sats.
+
+**Skill Marketplace** — Register skills with pricing, categories, and input/output schemas. Discover skills by keyword, category, or price range. Request executions with automatic Lightning invoicing. Webhook-based execution engine with payment proof delivery. Rating system backed by cryptographic payment proofs.
+
+**Security Stack** — API key authentication, scoped macaroon authorization (8 permissions, 4 profiles), per-payment/hourly/daily spending limits, in-memory sliding window rate limiting, anomaly detection (self-payment, rapid repeat, structuring, volume spike), rating integrity (preimage verification, duplicate prevention, weighted averages), and provider verification via Lightning node signatures and domain proof.
+
+## Quick Start
+
+```bash
+git clone https://github.com/Lightning-Linq/conduit.git
+cd conduit
+chmod +x install.sh
+./install.sh
+```
+
+The install script handles everything: checks prerequisites (Python 3.11+, PostgreSQL), creates virtual environment, installs dependencies, generates a secure API key, sets up the database, runs migrations, and shows you how to wire it into Claude Desktop.
+
+### Prerequisites
+
+- **Python 3.11+** — `brew install python@3.11` or use pyenv
+- **PostgreSQL 16** — `brew install postgresql@16 && brew services start postgresql@16`
+- **LND node** — running and accessible (local, remote, or via Tor)
+
+### Claude Desktop Configuration
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "conduit-lightning": {
+      "command": "/path/to/conduit/.venv/bin/python",
+      "args": ["-m", "conduit.mcp_server"],
+      "env": {
+        "PYTHONPATH": "/path/to/conduit/src"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Ask Claude: *"What's my Lightning node balance?"*
+
+## MCP Tools Reference
+
+Conduit exposes 19 tools over the Model Context Protocol.
+
+### Lightning Tools
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `get_node_info` | lightning:read | Node alias, pubkey, active channels, peers |
+| `get_balance` | lightning:read | On-chain and channel balances |
+| `create_invoice` | lightning:invoice | Generate a Lightning invoice |
+| `pay_invoice` | lightning:pay | Pay a Lightning invoice (with spending limits) |
+| `decode_invoice` | lightning:read | Decode a payment request without paying |
+| `check_payment` | lightning:read | Check if a payment has settled |
+
+### Marketplace Tools
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `discover_skills` | marketplace:read | Search skills by keyword, category, price |
+| `get_skill_details` | marketplace:read | Full details including schemas and ratings |
+| `register_skill` | marketplace:write | List a new skill on the marketplace |
+| `request_skill_execution` | marketplace:execute | Request execution (generates invoice) |
+| `confirm_skill_execution` | marketplace:execute | Confirm payment and trigger webhook |
+| `submit_rating` | marketplace:execute | Rate a skill (requires payment proof) |
+
+### Verification Tools
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `request_verification` | marketplace:write | Start node or domain verification |
+| `submit_verification` | marketplace:write | Complete verification with proof |
+| `get_verification_status` | marketplace:read | Check a skill's verification badges |
+
+### Security Tools
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `get_spending_status` | security:read | Current spending vs. limits |
+| `create_macaroon` | security:admin | Mint a scoped authorization token |
+| `list_permissions` | security:read | Show active permissions |
+| `get_anomaly_report` | security:read | View flagged suspicious patterns |
+
+## Security Model
+
+Conduit uses defense-in-depth with multiple security layers.
+
+**Authentication** — An API key is required to start the server. Without it, the MCP server refuses to run.
+
+**Authorization** — Macaroon-based scoping with 8 permission levels. Create restricted tokens for specific use cases (read-only, marketplace-only, spending-only).
+
+**Spending Controls** — Configurable per-payment limits (default 10,000 sats), hourly caps (50,000 sats), daily caps (200,000 sats), and confirmation prompts for payments above a threshold.
+
+**Rate Limiting** — Per-tool sliding window rate limits. Write operations are tightly limited (e.g., 5 skill registrations per 10 minutes). Read operations are generous (60/min).
+
+**Anomaly Detection** — Runs after every payment and execution. Detects self-payment, rapid repeat transactions, structuring near limits, and volume spikes. Advisory mode: flags are logged but transactions aren't blocked.
+
+**Rating Integrity** — Ratings require a payment preimage (SHA-256 proof of purchase). One rating per execution (enforced by unique constraint). 30-second minimum delay. Weighted averages discount repeat reviewers (1/n diminishing weight).
+
+**Provider Verification** — Providers can prove identity via Lightning node signatures (`lncli signmessage`) or domain verification (`.well-known` URL). Verified skills display trust badges in marketplace listings.
+
+## Configuration
+
+All settings via environment variables or `.env`:
+
+```bash
+# API Key (required)
+CONDUIT_API_KEY=your-secret-key
+
+# LND Connection
+LND_HOST=192.168.1.x
+LND_GRPC_PORT=10009
+LND_TLS_CERT_PATH=credentials/full-chain.pem
+LND_MACAROON_PATH=credentials/admin.macaroon
+LND_NETWORK=mainnet
+
+# Database
+DATABASE_URL=postgresql+asyncpg://conduit:conduit@localhost:5432/conduit
+
+# Spending Limits (sats, 0 = no limit)
+SPENDING_LIMIT_PER_PAYMENT_SATS=10000
+SPENDING_LIMIT_HOURLY_SATS=50000
+SPENDING_LIMIT_DAILY_SATS=200000
+SPENDING_CONFIRM_ABOVE_SATS=5000
+
+# Keep false for MCP servers (echo corrupts stdio transport)
+DEBUG=false
+```
+
+## Project Structure
+
+```
+src/conduit/
+├── mcp_server.py                # MCP server entry point — 19 tools
+├── core/
+│   ├── config.py                # Settings from .env
+│   └── database.py              # Async SQLAlchemy + asyncpg
+├── models/
+│   ├── skill.py                 # Skill marketplace listings
+│   ├── execution.py             # Skill execution tracking
+│   ├── rating.py                # Payment-proof-backed ratings
+│   ├── spending_log.py          # Spending audit trail
+│   └── anomaly_flag.py          # Suspicious pattern flags
+├── services/
+│   ├── lnd.py                   # LND gRPC client (sign, verify, pay)
+│   ├── spending_limiter.py      # Payment limit enforcement
+│   ├── macaroon_auth.py         # Scoped authorization tokens
+│   ├── rate_limiter.py          # Sliding window rate limits
+│   ├── anomaly_detector.py      # Transaction pattern detection
+│   ├── rating_integrity.py      # Anti-gaming for ratings
+│   ├── provider_verification.py # Node + domain verification
+│   └── skill_executor.py        # Webhook-based execution engine
+└── alembic/                     # Database migrations
+```
+
+## Roadmap
+
+- [x] Lightning Network integration (LND gRPC)
+- [x] MCP server with 19 tools
+- [x] Skill marketplace (register, discover, execute, rate)
+- [x] PostgreSQL persistence with Alembic migrations
+- [x] Full security stack (auth, macaroons, limits, anomaly detection)
+- [x] Provider verification (Lightning node + domain)
+- [x] One-command install script
+- [x] Nostr protocol for decentralized skill discovery (NIP-01/19/33)
+- [x] Nostr Wallet Connect (NWC) with NIP-44 v2 encryption
+- [x] REST API layer alongside MCP (27 endpoints, FastAPI)
+- [ ] Multi-node federation
+- [ ] Package for distribution (`pip install conduit-lightning`)
+
+## License
+
+MIT — see [LICENSE](LICENSE).