mirror of
https://github.com/Routstr/protocol.git
synced 2026-10-05 15:48:24 +00:00
initial RIPs
This commit is contained in:
Shroominic
@@ -1,2 +1,17 @@
|
||||
# protocol
|
||||
technical specification and improvement protocol
|
||||
# Routstr Improvement Protocols (RIPs)
|
||||
|
||||
|
||||
|
||||
Routstr Improvement Protocols (RIPs) are modular specification documents defining the events, behaviors, and interfaces for the decentralized AI inference network. They complement the core protocol by specifying discrete improvements, standards, and guidelines that implementations can adopt to enhance interoperability, security, and user experience.
|
||||
|
||||
## List of RIPs
|
||||
|
||||
| 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-02 | [Node Listing](RIP-02.md) | Nostr event spec for announcing inference node presence and capabilities |
|
||||
| RIP-03 | [Frontend Discovery](RIP-03.md) | Specification for the discovery UI to browse and filter available nodes |
|
||||
| RIP-04 | [Evaluations & Quality Control](RIP-04.md) | Guidelines for randomized, anonymized evaluations to ensure provider quality |
|
||||
| RIP-05 | [Smart Clients & Token Management](RIP-05.md) | Client behaviors for token cycling, proxy/Tor usage, and provider optimization |
|
||||
|
||||
Refer to each RIP file in this directory for detailed implementation guidance.
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# RIP-00: OpenAI-API Proxy with Cashu Payments
|
||||
|
||||
Defines the HTTP proxy interface forwarding OpenAI-compatible API requests, with per-request micropayment handling via Cashu tokens.
|
||||
|
||||
## Endpoints
|
||||
|
||||
### POST /{path:path}
|
||||
|
||||
Forward proxied requests to the upstream AI service at `UPSTREAM_BASE_URL`.
|
||||
|
||||
#### Authorization
|
||||
|
||||
- Header: `Authorization: Bearer <api-key>` or `Bearer <cashu-token>`
|
||||
- API keys: prefixed `sk-`, validated against stored hashed keys.
|
||||
- Cashu tokens: prefixed `cashu`, redeemed via Cashu L3 mint.
|
||||
|
||||
#### Payment Flow
|
||||
|
||||
1. **Validation**: Verify bearer key and ensure balance ≥ `COST_PER_REQUEST` msats.
|
||||
2. **Charge Base**: Deduct `COST_PER_REQUEST` from user balance; record request count.
|
||||
3. **Forward**: Send request upstream, applying `UPSTREAM_API_KEY` override if set.
|
||||
4. **Token-Based Pricing (Optional)**: For chat/completions when `MODEL_BASED_PRICING`=true:
|
||||
- Parse upstream `usage.prompt_tokens` and `usage.completion_tokens`.
|
||||
- Compute `input_msats` = prompt_tokens/1000 × model.prompt_price.
|
||||
- Compute `output_msats` = completion_tokens/1000 × model.completion_price.
|
||||
- Charge or refund the difference via balance adjustment.
|
||||
- Emit SSE event `data: {"cost": {...}}` appended to stream.
|
||||
|
||||
#### Responses
|
||||
|
||||
- **Streaming** (`text/event-stream`): Proxy SSE chunks and inject a final cost event.
|
||||
- **Non-Streaming** (`application/json`): Embed a top-level `"cost": {...}` field in JSON.
|
||||
|
||||
#### Error Codes
|
||||
|
||||
- `401 Unauthorized`: Missing or invalid API key/Cashu token.
|
||||
- `402 Payment Required`: Insufficient balance.
|
||||
- `502 Bad Gateway`: Upstream service unavailable.
|
||||
- `500 Internal Server Error`: Unexpected errors.
|
||||
|
||||
## Configuration
|
||||
|
||||
- `COST_PER_REQUEST`: Base cost in msats (env `COST_PER_REQUEST`).
|
||||
- `MODEL_BASED_PRICING`: Enable token pricing (env `MODEL_BASED_PRICING`).
|
||||
- `COST_PER_1K_INPUT_TOKENS` & `COST_PER_1K_OUTPUT_TOKENS`: Fallback pricing if `models.json` not present.
|
||||
@@ -0,0 +1,24 @@
|
||||
# RIP-01: Node Listing
|
||||
|
||||
Nodes announce their presence and capabilities via a Nostr event for client discovery.
|
||||
|
||||
**Kind**: 40500
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": 40500,
|
||||
"created_at": <unix-timestamp>,
|
||||
"tags": [
|
||||
["d", "<node-id>"], // Unique node identifier
|
||||
["p", "<operator-pubkey>"],
|
||||
["url", "https://..."], // Inference endpoint
|
||||
["model", "<model-id>"], // Repeatable
|
||||
["price", "<msats>"], // mSAT per request
|
||||
["region", "<ISO-region>"],
|
||||
["latency_ms", "<avg-ms>"]
|
||||
],
|
||||
"content": "Human-readable description"
|
||||
}
|
||||
```
|
||||
|
||||
Clients subscribe to Kind 40500, index by `d` tag, and override older listings with newer events.
|
||||
@@ -0,0 +1,37 @@
|
||||
# RIP-02: Frontend Discovery
|
||||
|
||||
Defines the web or app interface for browsing and filtering available inference nodes based on social network and evolving evals.
|
||||
|
||||
## Features
|
||||
|
||||
- List active nodes from Nostr Kind 40500.
|
||||
- Filter by:
|
||||
- Supported model(s)
|
||||
- Region
|
||||
- Price range
|
||||
- Social network proximity (follow graph)
|
||||
- Average rating (from evals)
|
||||
- Future: Toggle eval visibility once RIP-03 is live.
|
||||
|
||||
## UI Components
|
||||
|
||||
- **Search Bar**: Free text for node-id or description.
|
||||
- **Filters Panel**: Sliders and checkboxes.
|
||||
- **Node Card**:
|
||||
- Description
|
||||
- Models
|
||||
- Price
|
||||
- Rating summary
|
||||
- Connect button (opens external client)
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. Subscribe to Nostr Kind 40500 & 31555 events.
|
||||
2. Maintain in-memory index, update on new events.
|
||||
3. Join with evals to compute live scores.
|
||||
4. Render node list with applied filters.
|
||||
|
||||
## Metrics
|
||||
|
||||
- Query performance: ≤200 ms for 1 k nodes.
|
||||
- Real-time updates: UI refresh on new events.
|
||||
@@ -0,0 +1,44 @@
|
||||
# RIP-03: Evaluations & Quality Control
|
||||
|
||||
Specifies how clients anonymize and randomize evaluation submissions to mimic normal inference requests.
|
||||
|
||||
## Goals
|
||||
|
||||
- Prevent provider bias by making evals indistinguishable from real inference calls.
|
||||
- Collect unbiased metrics on quality, latency, and cost.
|
||||
|
||||
## Eval Flow
|
||||
|
||||
1. Client selects a subset of providers based on discovery.
|
||||
2. For each eval job:
|
||||
- Generate randomized inference parameters.
|
||||
- Send inference request off-chain via usual API.
|
||||
- Measure latency, output quality against ground truth.
|
||||
3. Assemble eval result and prepare Nostr event:
|
||||
- Use new random ephemeral Nostr key per eval.
|
||||
- Publish Kind 31555 with standard rating tags:
|
||||
- `d`: provider node-id
|
||||
- `rating` categories: `quality`, `latency`, `value`
|
||||
- No direct link to client's main pubkey.
|
||||
|
||||
## Tags
|
||||
|
||||
- `d`: provider node-id
|
||||
- `rating`:
|
||||
- `quality`: 0–1 match to ground truth
|
||||
- `latency`: normalized inverse latency score
|
||||
- `value`: cost vs performance
|
||||
- `content`: optional detailed notes
|
||||
|
||||
## Anonymity
|
||||
|
||||
- Ephemeral keys rotated per session.
|
||||
- Randomized send times & intervals.
|
||||
|
||||
## Aggregation
|
||||
|
||||
- Clients can batch multiple evaluations in one event by repeating `rating` tags.
|
||||
|
||||
## Frequency
|
||||
|
||||
- Limit eval jobs to ≤5% of overall requests to avoid load spikes.
|
||||
@@ -0,0 +1,39 @@
|
||||
# RIP-04: Smart Clients & Token Management
|
||||
|
||||
Defines client-side behavior for automated token cycling, proxy/Tor usage, and provider optimization.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Maintain local Cashu wallet and balance.
|
||||
- Auto-redeem and split tokens into per-request msat units.
|
||||
- Route inference requests through proxies or Tor to obfuscate origin.
|
||||
- Continuously monitor discovery for better providers (price, latency, rating).
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Initialization**
|
||||
- Load master wallet token.
|
||||
- Pre-split tokens into request-sized shards.
|
||||
2. **Request Execution**
|
||||
- Select provider based on weighted metrics (price, latency, rating).
|
||||
- Choose random proxy or Tor circuit.
|
||||
- Attach one token shard as payment credential.
|
||||
- Send inference request off-chain.
|
||||
3. **Monitoring**
|
||||
- Track per-provider performance over time.
|
||||
- On token exhaustion, auto-top-up from wallet.
|
||||
- Adjust provider weights for future selection.
|
||||
|
||||
## Metrics & Adaptation
|
||||
|
||||
- Dynamic scoring: lower price & latency, higher rating favored.
|
||||
- Decay older measurements; prioritize recent data.
|
||||
|
||||
## Security & Privacy
|
||||
|
||||
- Rotate Tor circuits per request.
|
||||
- Limit request rate per provider to avoid fingerprinting.
|
||||
|
||||
---
|
||||
|
||||
_End of RIP specs._
|
||||
Reference in New Issue
Block a user