ODIN OMB — Meter & Billing

Verifiable usage metering & cryptographically signed export bundles with optional Stripe integration. Build trust by letting customers independently verify their billed usage.

OMB provides a lightweight library + reference API for generating Signed Usage Records (SUR) and bundle exports. Targets platforms that need transparent, auditable usage‑based billing without heavy vendor lock‑in.

Deterministic CIDs

Canonical JSON + sha256 hashing (sha256:<hex>) to fingerprint every usage record & bundle.

Ed25519 Signatures

Per‑record signatures + aggregate bundle signature for tamper evidence & provenance.

Pluggable Storage

JSONL append‑only default; prototype SQLite layer; wrap to bring your own datastore.

Reference API (FastAPI)

Simple endpoints for record ingest, export initiation, Stripe session stubs.

Verification Helpers

Offline validation via JWKS → recompute CIDs + Ed25519 verify for independent reconciliation.

CLI Workflow

omb-cli to record, export, bundle, and verify in shell & CI.

Signed Usage Record (SUR)

{
  "version": 1,
  "tenant_id": "tn_9f2c1",
  "resource": "llm_tokens",
  "quantity": 5120,
  "unit_cost_usd": 0.000002,
  "period_start": 1735171200,
  "period_end": 1735171259,
  "cid": "sha256:0b4e6b...",
  "sig_alg": "ed25519",
  "sig": "dGhpc2lzYXNpZ25hdHVyZQ...",
  "ts": 1735171260000
}

Canonicalized JSON → sha256 hash becomes cid; signature computed over "{cid}|{tenant_id}|{ts}".

Bundle Export (Excerpt)

{
  "bundle_id": "bnd_2025-08-25_tn_9f2c1",
  "tenant_id": "tn_9f2c1",
  "range": { "from": 1735171200, "to": 1735257599 },
  "record_cids": ["sha256:0b4e6b...", "sha256:91acff..."],
  "cid": "sha256:3fe2d1...",           // canonical hash of bundle sans signature
  "sig_alg": "ed25519",
  "sig": "bW9yZXNpZ25lZGVuY29kaW5n..."
}

Bundle signature proves included SUR list & metadata; consumer can fetch SURs & recompute.

Verification (Pseudo‑Code)

canon = canonical_json(record_without_sig)
if sha256(canon) != record.cid_hash: fail("cid_mismatch")
msg = f"{record.cid}|{record.tenant_id}|{record.ts}"
if !ed25519_verify(pubkey, msg, record.sig): fail("signature_invalid")
return OK

Same pattern scales for bundle: canonicalize bundle (without sig) then verify signature.

Stripe (Optional)

  • Create checkout session & store price mapping.
  • Map metered resource → price id(s).
  • Aggregate SUR quantities → usage report payload.
  • Future: push signed usage to Stripe (usage API) & attach bundle CID reference.

Separation ensures local verifiability even if billing vendor changes later.

Roadmap Highlights

  • JWKS rotation & key usage windows
  • Streaming export (NDJSON / S3 multipart)
  • Deterministic compression pre‑hash (opt‑in)
  • Stripe usage reporter adapter
  • Multi‑tenant quota & alert hooks
  • mTLS ingest variant