226 lines
7.1 KiB
Markdown
226 lines
7.1 KiB
Markdown
|
||
# 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
|
||
```
|