...

specs/billingmanager_research/conceptnote.md

@@ -0,0 +1,225 @@
+
+# Concept Note: Generic Billing & Tracking Framework
+
+## 1) Purpose
+
+The model is designed to support a **flexible, generic, and auditable** billing environment that can be applied across diverse services and providers — from compute time billing to per-request API usage, across multiple currencies, with dynamic provider-specific overrides.
+
+It is **not tied to a single business domain** — the same framework can be used for:
+
+* Cloud compute time (per second)
+* API transactions (per request)
+* Data transfer charges
+* Managed service subscriptions
+* Brokered third-party service reselling
+
+---
+
+## 2) Key Concepts
+
+### 2.1 Accounts
+
+An **account** represents an economic actor in the system — typically a customer or a service provider.
+
+* Identified by a **public key** (for authentication & cryptographic signing).
+* Every billing action traces back to an account.
+
+---
+
+### 2.2 Currencies & Asset Codes
+
+The system supports **multiple currencies** (crypto or fiat) via **asset codes**.
+
+* Asset codes identify the unit of billing (e.g. `USDC-ETH`, `EUR`, `LND`).
+* Currencies are **decoupled from services** so you can add or remove supported assets at any time.
+
+---
+
+### 2.3 Services & Groups
+
+* **Service** = a billable offering (e.g., "Speech-to-Text", "VM Hosting").
+
+  * Has a **billing mode** (`per_second` or `per_request`).
+  * Has a **default price** and **default currency**.
+  * Supports **multiple accepted currencies** with optional per-currency pricing overrides.
+  * Has execution constraints (e.g. `max_request_seconds`).
+  * Includes structured schemas for request payloads.
+
+* **Service Group** = a logical grouping of services.
+
+  * Groups make it easy to **bundle related services** and manage them together.
+  * Providers can offer entire groups rather than individual services.
+
+---
+
+### 2.4 Service Providers
+
+A **service provider** is an **account** that offers services or service groups.
+They can:
+
+* Override **pricing** for their offered services (per currency).
+* Route requests to their own **runners** (execution agents).
+* Manage multiple **service groups** under one provider identity.
+
+---
+
+### 2.5 Runners
+
+A **runner** is an execution agent — a node, VM, or service endpoint that can fulfill requests.
+
+* Identified by an **IPv6 address** (supports Mycelium or other overlay networks).
+* Can be owned by one or multiple providers.
+* Providers map **services/groups → runners** to define routing.
+
+---
+
+### 2.6 Subscriptions
+
+A **subscription** is **the authorization mechanism** for usage and spending control:
+
+* Links an **account** to a **service** or **service group**.
+* Defines **spending limits** (amount, currency, period: hour/day/month).
+* Restricts which **providers** are allowed to serve the subscription.
+* Uses a **secret** chosen by the subscriber — providers use this to claim charges.
+
+---
+
+### 2.7 Requests
+
+A **request** represents a single execution under a subscription:
+
+* Tied to **account**, **subscription**, **provider**, **service**, and optionally **runner**.
+* Has **status** (`pending`, `running`, `succeeded`, `failed`, `canceled`).
+* Records start/end times for duration-based billing.
+
+---
+
+### 2.8 Billing Ledger
+
+The **ledger** is **append-only** — the source of truth for all charges and credits.
+
+* Each entry records:
+
+  * `amount` (positive = debit, negative = credit/refund)
+  * `asset_code`
+  * Links to `account`, `provider`, `service`, and/or `request`
+* From the ledger, **balances** can be reconstructed at any time.
+
+---
+
+## 3) How Billing Works — Step by Step
+
+### 3.1 Setup
+
+1. **Define services** with default pricing & schemas.
+2. **Define currencies** and accepted currencies for services.
+3. **Group services** into service groups.
+4. **Onboard providers** (accounts) and associate them with service groups.
+5. **Assign runners** to services or groups for execution routing.
+
+---
+
+### 3.2 Subscription Creation
+
+1. Customer **creates a subscription**:
+
+   * Chooses service or service group.
+   * Sets **spending limit** (amount, currency, period).
+   * Chooses **secret**.
+   * Selects **allowed providers**.
+2. Subscription is stored in DB.
+
+---
+
+### 3.3 Request Execution
+
+1. Customer sends a request to broker/API with:
+
+   * `subscription_id`
+   * Target `service_id`
+   * Payload + signature using account pubkey.
+2. Broker:
+
+   * Validates **subscription active**.
+   * Validates **provider allowed**.
+   * Checks **spend limit** hasn’t been exceeded for current period.
+   * Resolves **effective price** via:
+
+     1. Provider override (currency-specific)
+     2. Service accepted currency override
+     3. Service default
+3. Broker selects **runner** from provider’s routing tables.
+4. Runner executes request and returns result.
+
+---
+
+### 3.4 Billing Entry
+
+1. When the request completes:
+
+   * If `per_second` mode → calculate `duration × rate`.
+   * If `per_request` mode → apply flat rate.
+2. Broker **inserts ledger entry**:
+
+   * Debit from customer account.
+   * Credit to provider account (can be separate entries or aggregated).
+3. Ledger is append-only — historical billing cannot be altered.
+
+---
+
+### 3.5 Balance & Tracking
+
+* **Current balances** are a sum of all ledger entries per account+currency.
+* Spend limits are enforced by **querying the ledger** for the current period before each charge.
+* Audit trails are guaranteed via immutable ledger entries.
+
+---
+
+## 4) Why This is Generic & Reusable
+
+This design **decouples**:
+
+* **Service definition** from **provider pricing** → multiple providers can sell the same service at different rates.
+* **Execution agents** (runners) from **service definitions** → easy scaling or outsourcing of execution.
+* **Billing rules** (per-second vs per-request) from **subscription limits** → same service can be sold in different billing modes.
+* **Currencies** from the service → enabling multi-asset billing without changing the service definition.
+
+Because of these separations, you can:
+
+* Reuse the model for **compute**, **APIs**, **storage**, **SaaS features**, etc.
+* Plug in different **payment backends** (on-chain, centralized payment processor, prepaid balance).
+* Use the same model for **internal cost allocation** or **external customer billing**.
+
+---
+
+## 5) Potential Extensions
+
+* **Prepaid model**: enforce that ledger debits can’t exceed balance.
+* **On-chain settlement**: periodically export ledger entries to blockchain transactions.
+* **Discount models**: percentage or fixed-amount discounts per subscription.
+* **Usage analytics**: aggregate requests/billing by time period, provider, or service.
+* **SLAs**: link billing adjustments to performance metrics in requests.
+
+---
+
+## 6) Conceptual Diagram — Billing Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Customer Account
+    participant B as Broker/API
+    participant P as Provider
+    participant R as Runner
+    participant DB as Ledger DB
+
+    C->>B: Request(service, subscription, payload, secret)
+    B->>DB: Validate subscription & spend limit
+    DB-->>B: OK + effective pricing
+    B->>P: Forward request
+    P->>R: Execute request
+    R-->>P: Result + execution time
+    P->>B: Return result
+    B->>DB: Insert debit (customer) + credit (provider)
+    DB-->>B: Ledger updated
+    B-->>C: Return result + charge info
+```