satoshi-api 0.1.0__py3-none-any.whl

bitcoin_api/__init__.py

@@ -0,0 +1,8 @@
+"""Bitcoin REST API — developer-friendly access to your Bitcoin node."""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("bitcoin-api")
+except PackageNotFoundError:
+    __version__ = "0.1.0"

bitcoin_api/auth.py

@@ -0,0 +1,67 @@
+"""API key authentication."""
+
+import hashlib
+import logging
+from dataclasses import dataclass
+
+from fastapi import Request
+
+from .db import lookup_key
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class ApiKeyInfo:
+    tier: str  # "anonymous", "free", "pro", "enterprise", "invalid"
+    key_hash: str | None = None
+    label: str | None = None
+    query_param_used: bool = False
+
+
+def extract_api_key(request: Request) -> tuple[str | None, bool]:
+    key = request.headers.get("X-API-Key")
+    if key is not None:
+        return key, False
+    key = request.query_params.get("api_key")
+    if key is not None:
+        return key, True
+    return None, False
+
+
+def extract_l402_token(request: Request) -> tuple[str | None, str | None]:
+    """Extract L402 token from Authorization header. Returns (macaroon_b64, preimage_hex) or (None, None)."""
+    auth = request.headers.get("Authorization", "")
+    if not auth.startswith("L402 "):
+        return None, None
+    token_part = auth[5:].strip()
+    if ":" not in token_part:
+        return None, None
+    mac_b64, preimage_hex = token_part.split(":", 1)
+    return mac_b64, preimage_hex
+
+
+def hash_key(raw_key: str) -> str:
+    return hashlib.sha256(raw_key.encode()).hexdigest()
+
+
+def authenticate(request: Request) -> ApiKeyInfo:
+    raw_key, via_query = extract_api_key(request)
+    if raw_key is None:
+        return ApiKeyInfo(tier="anonymous")
+
+    if via_query:
+        log.warning("API key passed via query param (deprecated) from %s", request.client.host if request.client else "unknown")
+
+    key_hash = hash_key(raw_key)
+    record = lookup_key(key_hash)
+
+    if record is None or not record["active"]:
+        return ApiKeyInfo(tier="invalid", query_param_used=via_query)
+
+    return ApiKeyInfo(
+        tier=record["tier"],
+        key_hash=record["key_hash"],
+        label=record.get("label"),
+        query_param_used=via_query,
+    )

bitcoin_api/cache.py

@@ -0,0 +1,155 @@
+"""TTL caching for expensive RPC calls."""
+
+import threading
+
+from cachetools import LRUCache, TTLCache
+
+# Per-cache locks to avoid cross-cache contention
+_info_lock = threading.Lock()
+_count_lock = threading.Lock()
+_fee_lock = threading.Lock()
+_mempool_lock = threading.Lock()
+_status_lock = threading.Lock()
+_block_lock = threading.Lock()
+_nextblock_lock = threading.Lock()
+
+# Mutable data — short TTL
+_fee_cache: TTLCache = TTLCache(maxsize=1, ttl=10)
+_mempool_cache: TTLCache = TTLCache(maxsize=1, ttl=5)
+_status_cache: TTLCache = TTLCache(maxsize=1, ttl=30)
+_blockchain_info_cache: TTLCache = TTLCache(maxsize=1, ttl=10)
+_block_count_cache: TTLCache = TTLCache(maxsize=1, ttl=5)
+_nextblock_cache: TTLCache = TTLCache(maxsize=1, ttl=20)
+
+# Immutable data — confirmed blocks never change (deep confirmations)
+_block_cache: TTLCache = TTLCache(maxsize=64, ttl=3600)
+# Recent blocks near tip — short TTL to handle reorgs
+_recent_block_cache: TTLCache = TTLCache(maxsize=8, ttl=30)
+# Block hash → height mapping for cache lookups (bounded to prevent memory leak)
+_hash_to_height: LRUCache = LRUCache(maxsize=256)
+
+REORG_SAFE_DEPTH = 6
+
+
+def cached_blockchain_info(rpc):
+    key = "info"
+    with _info_lock:
+        if key in _blockchain_info_cache:
+            return _blockchain_info_cache[key]
+    result = rpc.call("getblockchaininfo")
+    with _info_lock:
+        _blockchain_info_cache[key] = result
+    return result
+
+
+def cached_block_count(rpc):
+    key = "count"
+    with _count_lock:
+        if key in _block_count_cache:
+            return _block_count_cache[key]
+    result = rpc.call("getblockcount")
+    with _count_lock:
+        _block_count_cache[key] = result
+    return result
+
+
+def cached_fee_estimates(rpc):
+    from bitcoinlib_rpc.fees import get_fee_estimates
+
+    key = "fees"
+    with _fee_lock:
+        if key in _fee_cache:
+            return _fee_cache[key]
+    result = get_fee_estimates(rpc)
+    with _fee_lock:
+        _fee_cache[key] = result
+    return result
+
+
+def cached_mempool_analysis(rpc):
+    from bitcoinlib_rpc.mempool import analyze_mempool
+
+    key = "mempool"
+    with _mempool_lock:
+        if key in _mempool_cache:
+            return _mempool_cache[key]
+    result = analyze_mempool(rpc)
+    with _mempool_lock:
+        _mempool_cache[key] = result
+    return result
+
+
+def cached_status(rpc):
+    from bitcoinlib_rpc.status import get_status
+
+    key = "status"
+    with _status_lock:
+        if key in _status_cache:
+            return _status_cache[key]
+    result = get_status(rpc)
+    with _status_lock:
+        _status_cache[key] = result
+    return result
+
+
+def cached_block_analysis(rpc, height: int):
+    from bitcoinlib_rpc.blocks import analyze_block
+
+    tip = cached_block_count(rpc)
+
+    # Blocks near tip use short-TTL cache (reorg safety)
+    if (tip - height) < REORG_SAFE_DEPTH:
+        with _block_lock:
+            if height in _recent_block_cache:
+                return _recent_block_cache[height]
+        result = analyze_block(rpc, height)
+        with _block_lock:
+            _recent_block_cache[height] = result
+        return result
+
+    # Deep blocks use long-TTL cache
+    with _block_lock:
+        if height in _block_cache:
+            return _block_cache[height]
+    result = analyze_block(rpc, height)
+    with _block_lock:
+        _block_cache[height] = result
+    return result
+
+
+def cached_block_by_hash(rpc, block_hash: str):
+    """Analyze a block by hash, caching the result by resolved height."""
+    from bitcoinlib_rpc.blocks import analyze_block
+
+    # Check if we already know this hash's height
+    with _block_lock:
+        height = _hash_to_height.get(block_hash)
+        if height is not None:
+            if height in _block_cache:
+                return _block_cache[height]
+            if height in _recent_block_cache:
+                return _recent_block_cache[height]
+
+    result = analyze_block(rpc, block_hash)
+    data = result.model_dump() if hasattr(result, "model_dump") else result
+    resolved_height = data.get("height")
+
+    if resolved_height is not None:
+        with _block_lock:
+            _hash_to_height[block_hash] = resolved_height
+            _block_cache[resolved_height] = result
+
+    return result
+
+
+def cached_next_block(rpc):
+    from bitcoinlib_rpc.nextblock import analyze_next_block
+
+    key = "nextblock"
+    with _nextblock_lock:
+        if key in _nextblock_cache:
+            return _nextblock_cache[key]
+    result = analyze_next_block(rpc)
+    with _nextblock_lock:
+        _nextblock_cache[key] = result
+    return result

bitcoin_api/config.py

@@ -0,0 +1,42 @@
+"""Application settings from environment variables."""
+
+from pathlib import Path
+
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    # Bitcoin Core RPC
+    bitcoin_rpc_host: str = "127.0.0.1"
+    bitcoin_rpc_port: int = 8332
+    bitcoin_rpc_user: str | None = None
+    bitcoin_rpc_password: SecretStr | None = None
+    bitcoin_datadir: str | None = None
+
+    # API server
+    api_host: str = "0.0.0.0"
+    api_port: int = 9332
+    api_db_path: Path = Path("data/bitcoin_api.db")
+
+    # CORS (comma-separated origins, or "*" for all — use "*" only for local/dev)
+    cors_origins: str = "http://localhost:3000,http://localhost:9332"
+
+    # Rate limits (requests per minute)
+    rate_limit_anonymous: int = 30
+    rate_limit_free: int = 100
+    rate_limit_pro: int = 500
+    rate_limit_enterprise: int = 2000
+
+    # L402 Lightning payments (disabled by default)
+    l402_enabled: bool = False
+    lightning_backend: str = "mock"  # "alby" or "mock"
+    alby_hub_url: str = ""
+    alby_hub_token: str = ""
+    l402_root_key: str = ""  # hex-encoded 32-byte key; auto-generated if empty
+    l402_default_expiry: int = 3600  # seconds
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+
+settings = Settings()

bitcoin_api/db.py

@@ -0,0 +1,136 @@
+"""SQLite database for API keys and usage tracking."""
+
+import sqlite3
+import threading
+from pathlib import Path
+
+from .config import settings
+
+_local = threading.local()
+_db_path: Path | None = None
+_initialized = False
+_init_lock = threading.Lock()
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS api_keys (
+    key_hash   TEXT PRIMARY KEY,
+    prefix     TEXT NOT NULL,
+    tier       TEXT NOT NULL DEFAULT 'free',
+    label      TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    active     INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE IF NOT EXISTS usage_log (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    key_hash   TEXT,
+    endpoint   TEXT NOT NULL,
+    status     INTEGER NOT NULL,
+    ts         TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_usage_ts ON usage_log(ts);
+CREATE INDEX IF NOT EXISTS idx_usage_key ON usage_log(key_hash);
+CREATE INDEX IF NOT EXISTS idx_usage_key_ts ON usage_log(key_hash, ts);
+
+CREATE TABLE IF NOT EXISTS l402_payments (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    payment_hash  TEXT NOT NULL UNIQUE,
+    macaroon_id   TEXT NOT NULL,
+    endpoint      TEXT NOT NULL,
+    amount_sats   INTEGER NOT NULL,
+    preimage      TEXT,
+    status        TEXT NOT NULL DEFAULT 'pending',
+    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    paid_at       TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_l402_payment_hash ON l402_payments(payment_hash);
+"""
+
+
+def _make_conn(path: Path) -> sqlite3.Connection:
+    conn = sqlite3.connect(str(path), check_same_thread=False)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=5000")
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def get_db(db_path: Path | None = None) -> sqlite3.Connection:
+    global _db_path, _initialized
+
+    # First call initializes the path and schema
+    if not _initialized:
+        with _init_lock:
+            if not _initialized:
+                _db_path = db_path or settings.api_db_path
+                _db_path.parent.mkdir(parents=True, exist_ok=True)
+                conn = _make_conn(_db_path)
+                conn.executescript(SCHEMA)
+                conn.close()
+                _initialized = True
+
+    # Each thread gets its own connection
+    conn = getattr(_local, "conn", None)
+    if conn is None:
+        _local.conn = _make_conn(_db_path)
+        conn = _local.conn
+    return conn
+
+
+def log_usage(key_hash: str | None, endpoint: str, status_code: int) -> None:
+    conn = get_db()
+    conn.execute(
+        "INSERT INTO usage_log (key_hash, endpoint, status) VALUES (?, ?, ?)",
+        (key_hash, endpoint, status_code),
+    )
+    conn.commit()
+
+
+def count_daily_usage(key_hash: str) -> int:
+    conn = get_db()
+    row = conn.execute(
+        "SELECT COUNT(*) FROM usage_log WHERE key_hash = ? AND ts >= date('now')",
+        (key_hash,),
+    ).fetchone()
+    return row[0] if row else 0
+
+
+def prune_old_logs(days: int = 90) -> int:
+    conn = get_db()
+    cursor = conn.execute(
+        "DELETE FROM usage_log WHERE ts < datetime('now', ?)",
+        (f"-{days} days",),
+    )
+    conn.commit()
+    return cursor.rowcount
+
+
+def lookup_key(key_hash: str) -> dict | None:
+    conn = get_db()
+    row = conn.execute(
+        "SELECT key_hash, prefix, tier, label, active FROM api_keys WHERE key_hash = ?",
+        (key_hash,),
+    ).fetchone()
+    if row is None:
+        return None
+    return dict(row)
+
+
+def log_l402_payment(payment_hash: str, macaroon_id: str, endpoint: str, amount_sats: int) -> None:
+    conn = get_db()
+    conn.execute(
+        "INSERT OR IGNORE INTO l402_payments (payment_hash, macaroon_id, endpoint, amount_sats) VALUES (?, ?, ?, ?)",
+        (payment_hash, macaroon_id, endpoint, amount_sats),
+    )
+    conn.commit()
+
+
+def mark_l402_paid(payment_hash: str, preimage: str) -> None:
+    conn = get_db()
+    conn.execute(
+        "UPDATE l402_payments SET status = 'paid', preimage = ?, paid_at = datetime('now') WHERE payment_hash = ?",
+        (preimage, payment_hash),
+    )
+    conn.commit()

bitcoin_api/dependencies.py

@@ -0,0 +1,39 @@
+"""FastAPI dependencies — RPC client singleton, auth, rate limiting."""
+
+from __future__ import annotations
+
+import threading
+
+from bitcoinlib_rpc import BitcoinRPC
+
+from .config import settings
+
+_rpc: BitcoinRPC | None = None
+_rpc_lock = threading.Lock()
+
+
+def _create_rpc() -> BitcoinRPC:
+    return BitcoinRPC(
+        host=settings.bitcoin_rpc_host,
+        port=settings.bitcoin_rpc_port,
+        user=settings.bitcoin_rpc_user,
+        password=settings.bitcoin_rpc_password.get_secret_value() if settings.bitcoin_rpc_password else None,
+        datadir=settings.bitcoin_datadir,
+    )
+
+
+def get_rpc() -> BitcoinRPC:
+    """Lazy singleton for the Bitcoin RPC connection. Resets on connection failure."""
+    global _rpc
+    if _rpc is None:
+        with _rpc_lock:
+            if _rpc is None:
+                _rpc = _create_rpc()
+    return _rpc
+
+
+def reset_rpc() -> None:
+    """Reset the RPC singleton (called on connection failure to allow recovery)."""
+    global _rpc
+    with _rpc_lock:
+        _rpc = None

bitcoin_api/l402.py

@@ -0,0 +1,120 @@
+"""L402 Lightning payment protocol — macaroon minting, verification, and challenges."""
+
+import base64
+import hashlib
+import hmac
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class L402Token:
+    """Parsed L402 authorization token."""
+    macaroon_bytes: bytes
+    preimage: str  # hex
+
+
+@dataclass
+class Macaroon:
+    """Simple macaroon for L402 — identifier contains payment_hash, signed with root key."""
+    identifier: str  # JSON: {"payment_hash": "...", "endpoint": "...", "amount": N, "expires": T}
+    signature: str  # HMAC-SHA256 hex
+
+
+def mint_macaroon(
+    root_key: bytes,
+    payment_hash: str,
+    endpoint: str,
+    amount_sats: int,
+    expiry_seconds: int = 3600,
+) -> Macaroon:
+    """Create a new macaroon tied to a Lightning payment."""
+    identifier = json.dumps({
+        "payment_hash": payment_hash,
+        "endpoint": endpoint,
+        "amount_sats": amount_sats,
+        "expires": int(time.time()) + expiry_seconds,
+        "version": 1,
+    }, separators=(",", ":"))
+
+    signature = hmac.new(root_key, identifier.encode(), hashlib.sha256).hexdigest()
+
+    return Macaroon(identifier=identifier, signature=signature)
+
+
+def serialize_macaroon(mac: Macaroon) -> str:
+    """Serialize macaroon to base64 string for HTTP headers."""
+    payload = json.dumps({
+        "identifier": mac.identifier,
+        "signature": mac.signature,
+    }, separators=(",", ":"))
+    return base64.urlsafe_b64encode(payload.encode()).decode()
+
+
+def deserialize_macaroon(b64_str: str) -> Macaroon:
+    """Deserialize macaroon from base64 string."""
+    payload = json.loads(base64.urlsafe_b64decode(b64_str))
+    return Macaroon(
+        identifier=payload["identifier"],
+        signature=payload["signature"],
+    )
+
+
+def verify_macaroon(root_key: bytes, mac: Macaroon) -> tuple[bool, str]:
+    """Verify macaroon signature and expiry. Returns (valid, reason)."""
+    # Verify signature
+    expected = hmac.new(root_key, mac.identifier.encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, mac.signature):
+        return False, "invalid signature"
+
+    # Parse identifier
+    try:
+        ident = json.loads(mac.identifier)
+    except json.JSONDecodeError:
+        return False, "malformed identifier"
+
+    # Check expiry
+    if time.time() > ident.get("expires", 0):
+        return False, "macaroon expired"
+
+    return True, "ok"
+
+
+def verify_preimage(payment_hash: str, preimage_hex: str) -> bool:
+    """Verify that SHA256(preimage) == payment_hash."""
+    try:
+        preimage_bytes = bytes.fromhex(preimage_hex)
+        computed_hash = hashlib.sha256(preimage_bytes).hexdigest()
+        return hmac.compare_digest(computed_hash, payment_hash)
+    except (ValueError, TypeError):
+        return False
+
+
+def parse_l402_header(auth_header: str) -> L402Token | None:
+    """Parse Authorization: L402 <macaroon>:<preimage> header."""
+    if not auth_header.startswith("L402 "):
+        return None
+    token_part = auth_header[5:].strip()
+    if ":" not in token_part:
+        return None
+    mac_b64, preimage_hex = token_part.split(":", 1)
+    try:
+        mac_bytes = base64.urlsafe_b64decode(mac_b64)
+    except Exception:
+        return None
+    return L402Token(macaroon_bytes=mac_bytes, preimage=preimage_hex)
+
+
+def create_challenge(macaroon_b64: str, invoice: str) -> str:
+    """Create WWW-Authenticate header value for 402 response."""
+    return f'L402 macaroon="{macaroon_b64}", invoice="{invoice}"'
+
+
+def generate_root_key() -> bytes:
+    """Generate a random 32-byte root key for macaroon signing."""
+    return os.urandom(32)

bitcoin_api/lightning.py

@@ -0,0 +1,97 @@
+"""Lightning Network client abstraction for L402 payments."""
+
+import hashlib
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class Invoice:
+    payment_hash: str
+    payment_request: str
+    amount_sats: int
+    expiry: int
+
+
+class LightningClient(ABC):
+    @abstractmethod
+    def create_invoice(self, amount_sats: int, memo: str, expiry: int = 3600) -> Invoice:
+        ...
+
+    @abstractmethod
+    def verify_payment(self, payment_hash: str) -> bool:
+        ...
+
+    @abstractmethod
+    def get_balance(self) -> int:
+        ...
+
+
+class AlbyHubClient(LightningClient):
+    def __init__(self, base_url: str, token: str):
+        self.base_url = base_url.rstrip("/")
+        self.client = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10.0,
+        )
+
+    def create_invoice(self, amount_sats: int, memo: str, expiry: int = 3600) -> Invoice:
+        resp = self.client.post("/api/v1/invoices", json={
+            "amount": amount_sats * 1000,  # Alby uses millisats
+            "description": memo,
+            "expiry": expiry,
+        })
+        resp.raise_for_status()
+        data = resp.json()
+        return Invoice(
+            payment_hash=data["payment_hash"],
+            payment_request=data["payment_request"],
+            amount_sats=amount_sats,
+            expiry=expiry,
+        )
+
+    def verify_payment(self, payment_hash: str) -> bool:
+        resp = self.client.get(f"/api/v1/invoices/{payment_hash}")
+        if resp.status_code == 404:
+            return False
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("settled", False) or data.get("state") == "settled"
+
+    def get_balance(self) -> int:
+        resp = self.client.get("/api/v1/balance")
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("balance", 0) // 1000  # Convert millisats to sats
+
+
+class MockLightningClient(LightningClient):
+    def __init__(self):
+        self.invoices: dict[str, Invoice] = {}
+        self.paid: set[str] = set()
+
+    def create_invoice(self, amount_sats: int, memo: str, expiry: int = 3600) -> Invoice:
+        payment_hash = hashlib.sha256(memo.encode()).hexdigest()
+        invoice = Invoice(
+            payment_hash=payment_hash,
+            payment_request=f"lnbc{amount_sats}n1mock{payment_hash[:20]}",
+            amount_sats=amount_sats,
+            expiry=expiry,
+        )
+        self.invoices[payment_hash] = invoice
+        return invoice
+
+    def verify_payment(self, payment_hash: str) -> bool:
+        return payment_hash in self.paid
+
+    def get_balance(self) -> int:
+        return 100000
+
+    def simulate_payment(self, payment_hash: str) -> None:
+        self.paid.add(payment_hash)