db/specs/billingmanager_research/conceptnote.md

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

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