update and extende RIPs aka routstr protocol spec

2026-10-05 15:48:24 +00:00 · 2026-01-03 17:25:32 +01:00
parent d7d7274843
commit 6e70caa9e7
7 changed files with 375 additions and 7 deletions
@@ -6,12 +6,18 @@ Routstr Improvement Protocols (RIPs) are modular specification documents definin
 ## List of RIPs
-| ID     | Title                                            | Description                                                                  |
+| ID | Title | Description |
-|--------|--------------------------------------------------|------------------------------------------------------------------------------|
+|---|---|---|
-| RIP-01 | [OpenAI-API Proxy with Cashu Payments](RIP-01.md)         | Proxy spec for OpenAI-compatible API requests, with per-request Cashu payment |
+| RIP-01 | [Proxy / Payments](RIP-01.md) | Standard for OpenAI-compatible API Proxy with integrated Cashu micropayments. |
-| RIP-02 | [Node Listing](RIP-02.md)                                   | Nostr event spec for announcing inference node presence and capabilities     |
+| RIP-02 | [Discovery](RIP-02.md) | Nostr event specifications for Provider Announcements (Kind 38421) and Recommendations (Kind 38000). |
-| RIP-03 | [Frontend Discovery](RIP-03.md)                          | Specification for the discovery UI to browse and filter available nodes     |
+| RIP-03 | [Client Specification](RIP-03.md) | Standards for client behavior, including ephemeral auth, wallet management, and auto-topup. |
-| RIP-04 | [Evaluations & Quality Control](RIP-04.md)               | Guidelines for randomized, anonymized evaluations to ensure provider quality |
+| RIP-04 | [Auditing](RIP-04.md) | Protocols for basic Uptime, Reliability, and Feature Verification checks. |
-| RIP-05 | [Smart Clients & Token Management](RIP-05.md)              | Client behaviors for token cycling, proxy/Tor usage, and provider optimization |
+| RIP-05 | [Pricing Algorithm](RIP-05.md) | Standardized unit of account (Millisats), cost calculation logic, and client-side verification. |
 | RIP-06 | [Routing Algorithms](RIP-06.md) | Algorithms for provider selection, scoring (Price/Trust/Perf), and failover hierarchies. |
 | RIP-07 | [Admin API](RIP-07.md) | Internal API specification for node management (Settings, Upstreams, Models, Wallet). |
 | RIP-08 | [Payment Methods](RIP-08.md) | Gateways for funding sessions via Lightning (Bolt11), NWC, Bolt12, and On-Chain Bitcoin. |
 | RIP-09 | [Evaluations](RIP-09.md) | Advanced "Mystery Shopping" benchmarks for Model Authenticity, Performance, and Safety. |
 | RIP-10 | [Marketplace](RIP-10.md) | Dynamics of the decentralized order book: Limit Sell, Market Buy, Limit Buy (Batch), and Spot Markets. |
 | RIP-11 | [Specialized Nodes](RIP-11.md) | Configuration profiles for General, Personal, Worker, and Routing nodes. |
 Refer to each RIP file in this directory for detailed implementation guidance.
@@ -0,0 +1,69 @@
 # RIP-06: Routing Algorithms
 This document defines standard algorithms for provider selection, scoring, and failover. These algorithms are shared across the ecosystem—used by smart clients for local selection and by routing nodes (aggregators) for recursive request handling.
 ## 1. Goal
 The goal is to deterministically or probabilistically select the optimal provider for a given request from a potentially large set of discovered nodes. "Optimal" is defined by user preferences (price vs. speed vs. quality) and objective network metrics.
 ## 2. Inputs
 Algorithms consume data from three primary sources:
 1. **Announcement Events (Kind 38421)**:
    - `geo`: Geolocation tags.
    - `endpoint`: The base URL to fetch detailed info.
 2. **Provider Info Endpoint (/v1/info & /v1/models)**:
    - `price`: Cost per token/request (fetched live).
    - `models`: Supported models list (fetched live).
 3. **Audit/Evaluation Events**:
    - `uptime`: Reliability score.
    - `latency`: Measured response time.
    - `quality`: Benchmark scores from RIP-09 evals.
 4. **Social Graph (Web of Trust)**:
    - `trust_score`: Derived from the user's social graph (distance to provider pubkey).
 ## 3. Selection Algorithms
 ### 3.1. Basic Filtering (Hard Constraints)
 First, the candidate pool is filtered by hard requirements:
 - **Model Match**: Provider must support the requested model (e.g., `deepseek-r1`).
 - **Max Price**: Advertised price <= User's `max_price` budget.
 - **Min Trust**: Provider pubkey must be within `N` hops of the user's web of trust (optional).
 ### 3.2. Weighted Scoring (Soft Constraints)
 Once hard constraints are met, candidates are scored to determine the optimal choice. Different client implementations may prioritize different metrics based on user needs. Common scoring profiles include:
 - **Price-Sensitive**: Prioritizes lowest cost per token.
 - **Performance-Maximized**: Prioritizes lowest latency and highest uptime, willing to pay higher rates.
 - **Trust-Centric**: Heavily weights social graph proximity (friends and friends-of-friends) over performance or price.
 - **Quality-First**: Selection based primarily on high scores from RIP-09 evaluation benchmarks.
 Clients are encouraged to allow users to customize these weights or select from preset "profiles".
 ### 3.3. Probabilistic Selection
 To prevent thundering herds (all clients picking the single "best" node), selection should be probabilistic among top candidates:
 - **Top-N Random**: Select randomly from the top 5 highest-scoring nodes.
 - **Weighted Random**: Selection probability is proportional to the calculated score.
 ## 4. Recursive Routing & Fallback Hierarchies
 ### 4.1. Client-Side Fallback
 Smart Clients (RIP-03) construct a prioritized list of providers:
 1. **Primary**: The selected high-score provider.
 2. **Secondary/Tertiary**: Backup providers with slightly lower scores but different failure domains (e.g., different regions).
 3. **Failover Logic**: If Primary fails (network error, 5xx, insufficient balance refund), the client automatically retries with Secondary.
 ### 4.2. Aggregator Routing  (NotImplementedYet)
 Routing Nodes (aggregators) use these same algorithms to forward requests to upstream providers transparently.
 - **Recursive Depth**: An aggregator effectively acts as a client to the upstream network.
 - **Value Add**: Aggregators can provide stability by maintaining diverse, high-availability fallback sets that individual clients might not discover.
@@ -0,0 +1,59 @@
 # RIP-07: Admin API
 This document specifies the internal Administrative API for managing a Routstr provider node. The Admin API is intended for the node operator and is secured via a persistent secret token or password-based session.
 ## 1. Authentication
 Access to all Admin API endpoints requires authentication.
 - **Method**: Bearer Token or Session Cookie.
 - **Authorization**: `Authorization: Bearer <ADMIN_TOKEN>`
 - **Security**: This API should typically be exposed only on `localhost` or over a secure VPN/tunnel.
 ## 2. Endpoints Overview
 The API is divided into functional modules:
 ### 2.1. General Settings (`/admin/api/settings`)
 Manages the core configuration of the provider node.
 - **GET /api/settings**: Retrieve current configuration (redacting secrets).
 - **PATCH /api/settings**: Update configuration (e.g., `cashu_mints`, `description`, `name`).
 - **POST /api/settings/password**: Rotate the admin password.
 ### 2.2. Upstream Providers (`/admin/api/upstreams`)
 Manages connections to backend LLM providers (e.g., OpenAI, OpenRouter, vLLM).
 - **GET /api/upstreams**: List configured upstream providers.
 - **POST /api/upstreams**: Add a new upstream provider.
 - **PATCH /api/upstreams/{id}**: Update credentials or base URL.
 - **DELETE /api/upstreams/{id}**: Remove a provider.
 ### 2.3. Models Management (`/admin/api/models`)
 Controls the catalog of models offered to the public network.
 - **GET /api/models**: List all models (active and inactive).
 - **POST /api/models**: Manually add or import a model.
 - **PATCH /api/models/{id}**:
  - Enable/Disable a model.
  - Set custom pricing (overriding default calculation).
  - Set aliases (e.g., map `gpt-4o` to `my-custom-gpt4`).
 - **DELETE /api/models/{id}**: Remove a model from the catalog.
 ### 2.4. Wallet & Balances (`/admin/api/balances`, `/admin/api/temporary-balances`)
 Monitors the financial state of the node.
 - **GET /api/balances**: View total holdings in the internal Cashu wallet.
 - **GET /api/temporary-balances**: View active ephemeral sessions and their current "held" funds.
 - **POST /admin/withdraw**: Withdraw funds from the internal wallet to an external Cashu token.
 ### 2.5. Logs & Audits (`/admin/logs`)
 Investigative tools for debugging and monitoring.
 - **GET /logs/{request_id}**: Retrieve detailed trace logs for a specific request ID (useful for debugging client issues).
 - **GET /logs/recent**: Fetch a stream of recent system events.
@@ -0,0 +1,66 @@
 # RIP-08: Payment Methods
 This document defines standard protocols for funding Routstr balances using methods other than direct Cashu tokens. While Cashu is the core internal wallet, these extensions allow clients to interact with providers using broader payment networks like Lightning and On-Chain Bitcoin.
 ## 1. Overview
 To maintain the stateless, privacy-preserving properties of Routstr, all alternative payment methods function as **"Cashu Gateways"**:
 1. The client pays via Lightning/On-Chain.
 2. The provider's gateway receives the payment.
 3. The gateway internally mints or credits a Cashu token/balance.
 4. This balance is effectively used as the "bearer asset" for the balance, preserving the standard flow defined in RIP-03.
 ## 2. Lightning Network (Bolt11)
 Allows clients to purchase ephemeral API access via standard Lightning invoices.
 ### 2.1. Endpoints
 - **POST `/lightning/invoice`**:
  - **Purpose**: Create a new balance or top-up an existing one.
  - **Body**: `{"amount_sats": 1000, "purpose": "create"}`
  - **Response**: `{"invoice_id": "...", "bolt11": "lnbc...", "payment_hash": "..."}`
 - **GET `/lightning/invoice/{invoice_id}/status`**:
  - **Polling**: Client checks status until `paid`.
  - **Response**: `{"status": "paid", "api_key": "sk-..."}`
 ### 2.2. Flow
 1. Client requests an invoice for 1000 sats.
 2. Provider generates a Bolt11 invoice (mapped internally to a Cashu mint quote).
 3. Client pays the invoice via their Lightning wallet.
 4. Provider detects payment -> Mints internal Cashu tokens -> Associates them with a new temporary API key (`sk-...`).
 5. Client receives the `api_key` and uses it for standard `/v1/chat/completions` calls.
 ## 3. Nostr Wallet Connect (NotImplementedYet)
 Allows for seamless, one-click or automated payments without leaving the client interface.
 - **NIP-47**: The client connects to the user's NWC-enabled wallet.
 - **Auto-Pay**: When a Routstr provider requests payment (e.g., via a 402 Payment Required or during the handshake), the client automatically requests the user's wallet to pay the Bolt11 invoice.
 - **Benefit**: Provides a UX similar to a "streaming subscription" without custodial deposits.
 ## 4. Bolt12 (NotImplementedYet)
 Routstr nodes should support Bolt12 offers for static, reusable payment codes.
 - **Use Case**: A provider publishes a Bolt12 Offer in their Kind 38421 announcement.
 - **Flow**: Client fetches invoice from Offer -> Pays -> Receives credentials via blinded path.
 ## 5. On-Chain Bitcoin (NotImplementedYet)
 For high-value, long-term sessions (e.g., enterprise batch jobs).
 - **Mechanism**: Provider generates a unique address.
 - **Wait Time**: 1 confirmation required.
 - **Conversion**: Funds are swapped to Cashu tokens once confirmed.
 ## 6. Compatibility with RIP-03
 These methods are **additions** to the core protocol. A client using Lightning:
 1. Pays Invoice -> Gets `api_key` (which represents the Cashu balance).
 2. Uses `api_key` for requests.
 3. **Refunds**: When the session ends, the refund (via `/v1/balance/refund`) is returned as a **Cashu Token**.
 4. **Off-Ramp**: The client can then swap this Cashu token back to Lightning (melt) using any Cashu mint, effectively "withdrawing" their change to their Lightning wallet.
@@ -0,0 +1,67 @@
 # RIP-09: Evaluations & Quality Control
 This document defines the protocol for advanced, third-party verification of provider quality and honesty. While **RIP-04 (Auditing)** covers basic uptime and feature checks, RIP-09 specifies the methodology for running costly, anonymized, and qualitative benchmarks to detect sophisticated fraud (e.g., model substitution) and measure performance under load.
 ## 1. Goal
 To establish a "Web of Trust" where independent evaluators verify that providers are delivering the intelligence they advertise.
 - **Fraud Detection**: Detecting if a provider advertises `gpt-4` (expensive) but routes to `gpt-3.5-turbo` or `llama-3-70b` (cheaper) to pocket the difference.
 - **Performance Benchmarking**: Measuring real-world tokens-per-second (TPS) and time-to-first-token (TTFT).
 ## 2. Methodology: Anonymized "Mystery Shopping"
 To prevent providers from gaming the metrics (e.g., prioritizing traffic from known audit bots), evaluations MUST be indistinguishable from normal user traffic.
 1. **Ephemeral Identity**: The evaluator creates a fresh, one-time-use wallet and keypair for each benchmark run.
 2. **Paid Traffic**: The evaluator pays full market price for the request.
 3. **Real-World Prompts**: The benchmark uses diverse, realistic prompt sets (e.g., coding problems, reasoning tasks) rather than static "ping" strings that are easily fingerprinted.
 ## 3. Metrics
 ### 3.1. Model Authenticity (Fingerprinting)
 Verifying the underlying model identity.
 - **Deterministic Questions**: Asking questions where models have known, distinct biases or refusal patterns.
 - **Logprobs Analysis**: If supported, comparing token probabilities against a reference implementation (ground truth).
 - **Hard Reasoning**: Submitting complex reasoning tasks that smaller models typically fail.
 ### 3.2. Performance
 - **Time to First Token (TTFT)**: Latency from request to first byte.
 - **Tokens Per Second (TPS)**: Generation speed.
 - **Variance**: Consistency of performance over multiple samples.
 ### 3.3. Feature Verification
 - **Function Calling**: Verifying the model correctly triggers and formats tool calls.
 - **JSON Mode**: Testing strict schema adherence.
 - **Context Window**: Sending long-context inputs to verify the provider supports the full advertised window size (and doesn't silently truncate).
 ### 3.4. Security & Safety Verification
 Evaluators probe for vulnerabilities that could expose downstream users or agents to risk.
 - **Prompt Injection**: Testing if the model can be coerced into ignoring system instructions or executing arbitrary commands (especially relevant for models with tool-use/agent capabilities).
 - **Tool Sandbox Escape**: Attempting to manipulate tool arguments to access unauthorized resources.
 - **Data Leakage**: Checking if the model reveals sensitive training data or system prompts from other users in the same context (for cached contexts).
 ## 4. Reporting
 Evaluators publish their findings as **Kind 31555 (Evaluation Report)** events on Nostr.
 - **Content**:
  - `provider_pubkey`: The audited provider.
  - `model`: The specific model tested.
  - `authenticity_score`: 0.0 - 1.0 (confidence that the model is genuine).
  - `performance`: `{ "tps": 45.2, "ttft_ms": 120 }`
  - `timestamp`: Time of audit.
  - `proof`: Optional cryptographic proof or trace ID of the interaction.
 ## 5. Monetization & Incentives
 Running these benchmarks is costly (computational + API fees).
 - **Subscription Model**: Clients or Aggregators subscribe to the Evaluator's paid feed (encrypted Nostr events) to get real-time "whitelist/blacklist" intelligence.
 - **Bounties**: The network (or a DAO) funds a bounty pool for consistent high-quality audit reports.
@@ -0,0 +1,55 @@
 # RIP-10: Marketplace Dynamics & Order Types
 This document describes the emergent marketplace for AI compute created by the Routstr protocol. By using Nostr as a global, censorship-resistant message bus, Routstr effectively builds a decentralized **Order Book** where supply (Providers) and demand (Clients/Agents) meet without a central coordinator.
 ## 1. Market Structure
 The marketplace consists of three primary order types, mirroring traditional financial markets but adapted for compute resources:
 ### 1.1. Limit Sell (Fixed Price Providers)
 - **Actor**: Standard Providers (e.g., wrappers around OpenAI/Anthropic or stable GPU clusters).
 - **Mechanism**: Providers publish Kind 38421 announcements with a fixed `price` per token.
 - **Behavior**: "I will sell `gpt-4` inference at `10 sats/1k tokens`."
 - **Stability**: These prices change infrequently (hours/days), providing predictable costs for real-time users.
 ### 1.2. Market Buy (Time-Sensitive Demand)
 - **Actor**: Interactive Agents, Chat Clients, IDEs.
 - **Mechanism**: Clients query the registry (RIP-02) and select the best available provider *right now*, accepting the current "Limit Sell" price.
 - **Behavior**: "I need an answer *now*. I will pay the going rate of `10 sats`."
 - **Priority**: Latency > Price.
 ### 1.3. Limit Buy (Batch Processing / Data Augmentation)
 - **Actor**: Batch processing bots, data augmentation pipelines, fine-tuning scripts.
 - **Mechanism**: These actors have tasks that are **not time-sensitive**. They hold off on execution until a provider appears with a price below their target threshold.
 - **Behavior**: "I have 1M rows to process. I will buy `llama-3-70b` compute only if the price drops below `0.5 sats/1k tokens`."
 - **Implementation**:
  - **Node Level**: Routstr nodes implement the **OpenAI Batch API** (`/v1/batches`), allowing users to submit file-based batch jobs. The node internally holds these jobs and executes them only when market conditions meet the user's price criteria.
  - **Client Level**: Specialized clients can also run locally, observing the Kind 38421 stream and dispatching requests one-by-one or in parallel only when a suitable provider is detected.
 - **Effect**: This creates a "floor" price in the market, soaking up excess supply when providers lower prices.
 ## 2. Dynamic Pricing (Real-Time Spot Market)
 To maximize utilization, providers with self-hosted hardware (e.g., H100 clusters, mining rigs repurposed for AI) can implement **Dynamic Pricing Algorithms**.
 ### 2.1. Cost-Based Pricing
 - **Inputs**: Electricity cost, hardware amortization, cooling.
 - **Logic**: `Price = (Energy_Cost + Margin) * Utilization_Factor`
 - **Behavior**: If the GPU is idle, the price drops towards the marginal cost of electricity to attract "Limit Buy" batch jobs. If the GPU is busy, the price rises to capture high-value "Market Buy" traffic.
 ### 2.2. Market Sell (Real-Time Auctions)
 - **Mechanism**: Providers publish high-frequency price updates via ephemeral Nostr events (or a dedicated pricing stream).
 - **Discovery**: Smart Clients (RIP-03) and Aggregators monitor these streams.
 - **Arbitrage**: If a provider drops their price significantly, automated batch jobs (Limit Buys) immediately route traffic to them, filling the idle capacity.
 ## 3. Marketplace Efficiency
 This hybrid structure creates a highly efficient market:
 - **High Availability**: "Limit Sell" providers ensure there is always capacity for urgent tasks.
 - **High Utilization**: "Dynamic Pricing" + "Limit Buy" bots ensure that hardware rarely sits idle, as price drops automatically trigger deferrable workloads.
 - **Price Discovery**: The intersection of these forces reveals the true global market price for a token of intelligence at any given second.
@@ -0,0 +1,46 @@
 # RIP-11: Specialized Nodes
 This document defines standard configuration profiles (or specialized implementations) of the Routstr node software. While the core software is general-purpose, these profiles optimize for specific roles within the network ecosystem.
 ## 1. General Node (Default)
 The standard "full stack" deployment.
 - **Function**: Acts as both a Buyer (routing to upstreams) and a Seller (advertising to the network).
 - **Use Case**: Small ISPs, enthusiasts, or startups running a comprehensive gateway.
 - **Components Active**: All (Wallet, Discovery, Proxy, Advertisement, Admin API).
 ## 2. Personal Node (Client Gateway)
 A private, local-only node designed to serve a single user or organization.
 - **Function**: Acts exclusively as a **Buyer** / Client.
 - **Visibility**: Does NOT publish advertisements (Kind 38421) or listen on public ports.
 - **Features**:
  - **Local Proxy**: Exposes `localhost:8000/v1` for local apps.
  - **Unlimited Key**: Provides a static "Master API Key" (skips per-request funding) for the owner's convenience. The node handles all wallet/funding logic internally.
  - **Privacy**: The node runs locally, so no 3rd party sees the user's IP or request patterns (requests are routed through the network via Tor/Proxy if configured).
  - **Extra Features**: Allows for additional features for companies like usage tracking, custom pricing, etc.
 ## 3. Worker Node (Compute Provider)
 A node optimized solely for **selling** raw compute power from local hardware.
 - **Function**: Acts exclusively as a **Seller**.
 - **Visibility**: Advertises presence and pricing.
 - **Features**:
  - **No Recursive Routing**: It does not proxy to other providers; it *is* the provider.
  - **Dynamic Pricing**: Runs specialized logic (RIP-10) to adjust prices in real-time based on hardware telemetry (GPU temp, utilization) and environmental costs (electricity spot price).
  - **Lean Stack**: May run a stripped-down implementation (e.g., Rust/Go) for maximum throughput and minimal overhead, interacting directly with inference engines like vLLM or Ollama.
 ## 4. Routing Node (Aggregator)
 A node focused on traffic management, reliability, and arbitrage.
 - **Function**: Acts as a high-volume **Reseller**.
 - **Visibility**: Advertises highly reliable, stable endpoints.
 - **Features**:
  - **No Local Compute**: Does not run local models.
  - **Recursive Routing**: Its primary value add is **smart routing** (RIP-06). It maintains vast, high-performance web-of-trust indexes to find the best upstream nodes for every request.
  - **Load Balancing**: Aggregates traffic from many users and distributes it across many Worker Nodes, smoothing out volatility.
  - **Verification**: May run active Auditing (RIP-04) and Evaluations (RIP-09) to ensure the quality of its downstream supply chain.