feat(peering): add paid peering billing ledger - #1087

This change adds invoice-purpose and term data, peering-payment tracking, and service logic for creating and settling peering invoices. The payments service updates payment periods and publishes peering invoice notifications.

Changes: Paid peering billing

Layer / File(s)	Summary
Invoice and peering ledger schema src/@types/invoice.ts, src/@types/peering.ts, src/@types/repositories.ts, migrations/20261109_120000_add_peering_billing.js	Invoice-purpose and peering-payment types are added. The migration adds invoice purpose and term fields, backfills invoice purposes, and creates the peering_payments table.
Payment persistence and mapping src/repositories/invoice-repository.ts, src/repositories/peering-payment-repository.ts, src/utils/transform.ts, test/unit/repositories/peering-payment-repository.spec.ts, src/factories/payments-service-factory.ts	Invoice persistence stores term snapshots and can update invoice periods. The peering-payment repository supports peer lookups, locking, saves, and period queries. Mappers convert database records to application types, and the service factory supplies the repository. Repository tests cover mapping and query behavior.
Peering invoice issuance and notifications src/@types/services.ts, src/@types/operator-notifications.ts, src/constants/base.ts, src/services/payments-service.ts, src/utils/peering-billing.ts, test/unit/services/payments-service.spec.ts, test/unit/utils/peering-billing.spec.ts, .changeset/paid-peering-ledger.md	The service creates peering invoices and sends tagged notifications. Term helpers validate billing settings and match invoice filters. Tests cover invoice creation, notification behavior, and term validation. The changeset declares a minor release.
Peering invoice settlement migrations/20261109_120000_add_peering_billing.js, src/services/payments-service.ts, test/unit/services/payments-service.spec.ts	Confirmation processing skips user-balance credits for peering invoices. The service records underpayment or activates a paid period, updates invoice periods, and queues settlement notifications. Tests cover settlement, duplicate callbacks, period extension, and transaction rollback.

Estimated code review effort: 4 (Complex) | ~50 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant PaymentsService
  participant InvoiceRepository
  participant PeeringPaymentRepository
  participant NotificationOutboxRepository
  PaymentsService->>InvoiceRepository: Load stored invoice
  PaymentsService->>PeeringPaymentRepository: Lock peer payment row
  PaymentsService->>PeeringPaymentRepository: Save settlement state
  PaymentsService->>InvoiceRepository: Update invoice period
  PaymentsService->>NotificationOutboxRepository: Enqueue settlement notification

Loading

Possibly related PRs

• cameri/nostream#1089: Adds renewal, lapse, and feed-access behavior using the ledger and settlement code introduced here.
• cameri/nostream#1088: Adds peer invoice requests and feed gating using the invoice methods, repository, and billing utilities introduced here.

Merge Risk: Moderate · up to e45cd

A paid peering invoice may fail to grant its period if its ledger row is missing or settlement fails after the invoice is marked complete. Resolve row creation and confirmation retries before merging unless that risk is explicitly accepted.

Security architecture risk: Moderate · up to e45cd

The new billing lifecycle can issue an invoice without establishing the peer state required to settle it. Settlement failures can also leave paid invoices outside automatic recovery. Immediate exposure is limited because public peering invoice requests and feed enforcement are not enabled yet.

Retained concerns

• Medium · architecture · observed: The new standalone createPeeringInvoice API can successfully commit a payable invoice without creating or verifying the peer's SELL ledger row. Settlement subsequently throws when that row is absent. The interface does not declare this prerequisite, and the migration creates an empty ledger. This leaves issuance and settlement without an enforced ownership lifecycle. No production issuance caller exists yet, so this is an API integration concern rather than an observed customer payment failure.
• Medium · reliability · inferred: If polling saves COMPLETED status and the new peering settlement then fails, transaction rollback leaves the invoice completed but unconfirmed and the ledger unchanged. Pending-only polling will not retry it, and LNbits callbacks reject invoices already marked completed. This recovery gap predates the PR, but the new ledger settlement adds failure points and a separately owned billing state that can remain unsettled. Other providers may permit callback retries; delivery is not established. Current absence of a production peering issuance caller limits immediate exposure.

Security review details

Security Blast Radius

• inferred — The newly writable asset is the local relay's peer-payment ledger and purchased-period history, reached through existing confirmation paths when a stored PEERING invoice exists. The inspected production source does not yet expose peering invoice issuance to network clients, and this PR does not establish feed enforcement.

Security Findings and Attack Paths

• inferred — No newly reachable public exploit was established. Zebedee confirmation can supply peer identity and unit from its callback payload, while settlement takes purpose and terms from the stored invoice. A mismatched callback passing the provider's source-IP control could therefore target a different existing peer row. Callback-field trust predates this PR, and current peering issuance is not publicly reachable; this remains a trust-contract consideration rather than a verified introduced attack path.

Trust Boundaries and Controls

• observed — Persisted invoice purpose controls peering routing and balance-credit exclusion. Stored confirmedAt prevents a previously confirmed invoice from buying another period, including after newer settlements. A locked peer row and lastSettledInvoiceId provide additional same-invoice duplicate protection.

Resilience and Maintainability Implications

• inferred — The main failure-containment gap crosses transaction boundaries: rolling back peer settlement does not roll back a previously saved completed status. Recovery therefore needs to distinguish provider payment completion from successful local entitlement settlement rather than relying only on status transitions.

Hardening Proposals

• proposed — Before exposing peering issuance, bind settlement identity and currency to the stored invoice, enforce ledger initialization and locking at the issuance boundary, and provide reconciliation for paid-but-unsettled invoices. Treat downgrade with outstanding peering invoices as a guarded transition that preserves their classification and settlement history.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly summarizes the main change: adding a paid peering billing ledger.
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 16 files.

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

Adds a paid-peering billing ledger without enabling invoice requests or gating peer feeds.

• Invoices and peer records now keep the details of paid peering.
• Paid peering invoices now record a peer’s paid period.

Both previous unnumbered findings are addressed: the stored confirmation check prevents older callbacks from adding time, and the new service tests cover the requested payment paths. Neither thread contains an explanatory reply or dismissal.