feat(billing): add live FX rates and integer ledger history - #5
Open
1amKhush wants to merge 10 commits into
Open
feat(billing): add live FX rates and integer ledger history#51amKhush wants to merge 10 commits into
1amKhush wants to merge 10 commits into
Conversation
- Introduce model visibility policies via MUXLL_MODELS_ALLOW / DENY and config file - Add gated admin tools (admin.models.setPolicy, admin.balance.credit) controlled by MUXLL_ADMIN_PUBKEYS - Implement prepaid billing infrastructure: ledger DB, markup, min charge, option to enable via MUXLL_BILLING - Update ENV example and developer docs to reflect new capabilities and code organization
There was a problem hiding this comment.
Pull request overview
Adds Phase 1 billing + model-policy controls to the muxll server, including CEP-8 gating/top-ups, live FX quoting, and integer nano-USD ledger storage, while extending the client/CLI to support balance + top-up flows.
Changes:
- Introduces server-side billing primitives (Ledger, PriceBook, CEP-8 resolvePrice/top-up) and live FX rate fetching with caching.
- Adds a model visibility policy layer (Catalog) plus admin tools to manage it at runtime, with persistence.
- Extends client and CLI surfaces (and tests) to support
balance.*,topup, and new models.list search/limit semantics.
Reviewed changes
Copilot reviewed 28 out of 28 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates project positioning and documents model policy/admin tools + billing CLI usage. |
| packages/server/tests/pricing.test.ts | Regression coverage for free-output computeOutputCap behavior. |
| packages/server/tests/policy.test.ts | End-to-end tests for model policy list/resolve hiding and admin gating. |
| packages/server/tests/ledger.test.ts | Verifies nano-USD integer storage and legacy REAL-column migration. |
| packages/server/tests/integration.test.ts | Adds reasoning-effort forwarding tests and mapReasoning unit coverage. |
| packages/server/tests/fx.test.ts | Tests FX provider min-selection, caching, partial failure tolerance, fail-closed. |
| packages/server/tests/catalog.test.ts | Unit tests for Catalog policy matching/patching/merge semantics. |
| packages/server/tests/billing.test.ts | End-to-end billing tests (balances, caps, debits, CEP-8 top-up flow). |
| packages/server/src/wire.ts | Adds mapReasoning for per-provider reasoning/thinking option mapping. |
| packages/server/src/server.ts | Integrates Catalog, admin tools, billing cap+settle, and CEP-8 transport wrapping. |
| packages/server/src/pricing.ts | Adds PriceBook (markup mode) and computeOutputCap token ceiling logic. |
| packages/server/src/payments.ts | Implements CEP-8 resolvePrice policy for waive/reject and top-up quoting. |
| packages/server/src/main.ts | Wires env-driven billing/policy config, persistence, and NWC payment processor. |
| packages/server/src/ledger.ts | Implements SQLite-backed nano-USD ledger and transactional migration logic. |
| packages/server/src/index.ts | Exposes new server public API exports (catalog/billing/fx/ledger/pricing). |
| packages/server/src/fx.ts | Adds live USD/sat rate from multiple providers with TTL cache. |
| packages/server/src/catalog.ts | Adds model visibility policy layer (list/resolve) with patch semantics. |
| packages/core/src/index.ts | Adds new tool methods, schemas, and types for policy + billing + models.list params. |
| packages/client/tests/client.test.ts | Adds client-side CEP-8 rejection/top-up identity regression test. |
| packages/client/src/index.ts | Exports balance response types. |
| packages/client/src/client.ts | Adds payments transport, balance/topup APIs, and streaming pre-rejection handling. |
| packages/cli/tests/cli.test.ts | Adds test for actionable insufficient-balance CLI error formatting. |
| packages/cli/src/index.ts | Adds balance / topup commands and CEP-8 payment interaction UX. |
| packages/cli/package.json | Moves @contextvm/sdk to dependencies for runtime payments usage. |
| design/idea.md | Adds design note for overall router intent (reference material). |
| design/billing.md | Adds detailed billing/payout design document for current direction and next phases. |
| AGENTS.md | Updates contributor guide for new model resolution/visibility and billing behavior. |
| .env.example | Documents new env vars for model policy, admin tools, and billing/top-up config. |
Suppressed comments (1)
packages/core/src/index.ts:341
- admin.balance.credit accepts
amountUsdasz.number().positive(), which may still allowInfinity. Constrain this to a finite number to avoid corrupting ledger state.
export const adminBalanceCreditInput = {
pubkey: z.string(),
amountUsd: z.number().positive(),
note: z.string().optional(),
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+103
to
+109
| // Free output (no priced output): cap by the caller/model limit only. | ||
| if (i.rates.outputPerToken <= 0) { | ||
| const cap = Math.min( | ||
| i.userMaxTokens ?? Infinity, | ||
| i.modelMaxTokens ?? Infinity, | ||
| i.contextWindow ?? Infinity, | ||
| ); |
Comment on lines
+302
to
+305
| // balance.topup: payment is verified by CEP-8 before the handler runs. | ||
| export const balanceTopupInput = { | ||
| amountUsd: z.number().positive(), | ||
| }; |
Comment on lines
9
to
+12
| This repository currently holds a **proof of concept**: chat completions (with | ||
| and without streaming) and model listing. Payments, quotas, and provider config | ||
| files are intentionally out of scope for now. | ||
| and without streaming) and model listing. Billing is in progress (Phase 1: | ||
| a prepaid USD balance ledger funded by admin grants, with a markup over | ||
| upstream cost); see [`docs/billing.md`](docs/billing.md) for the design. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Addresses the two billing follow-ups identified during the review of #1:
This PR is independent of the
pi-aidependency upgrade.Changes
Live FX rates
Fxcomponent that queries Kraken, Coinbase, and Binance.MUXLL_TOPUP_BUFFER_PCTwhen calculating Lightning quotes.MUXLL_USD_PER_SATconfiguration.Integer ledger storage
cost_nusdcharge_nusdamount_nusdREALhistory columns.Documentation
.env.example,README.md,AGENTS.md, anddesign/billing.md.Verification
Bun.serve({ port: 0 })EADDRINUSEissue.Refs #1