Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .changeset/paid-peering-lifecycle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
"nostream": minor
---

feat(peering): renew, lapse and expose paid peering access

The billing worker now issues renewal invoices before a period ends, rechecks
pending payments before lapsing a peer, closes live peer sockets on lapse, and
keeps stored events and sync state for a later resume. `GET /admin/peering` and
the dashboard show billing status, access end, the open invoice and the last
processor error. NEG-MSG rechecks paid access so an open NIP-77 session cannot
keep syncing after the paid period ends.
36 changes: 36 additions & 0 deletions docs/PEERING.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,3 +191,39 @@ authenticate the remote relay, because NIP-42 is a client-to-relay proof. The
remote relay's identity is established separately by the configured
`peering.peers` pubkey (and, in later phases, by discovery and owner
attestation).

## Paid peering

When `peering.terms` contains exactly one positive term, this relay sells the
feed instead of serving it settlement-free. Terms use the NIP-11 fee-object
shape (`amount`, `unit`, `period`); `unit` must be `msats`, `sats` or `btc`, and
a paid `msats` amount must be a whole number of satoshis so every payment
processor charges the same value. Payments must be enabled.

The buyer, Relay A, has no relationship with this relay's payment processor.
The invoice travels over the authenticated relay connection:

1. Relay A authenticates with NIP-42 and sends
`REQ {"kinds":[402],"#p":["<A pubkey>"],"#t":["peering"],"limit":1}`.
2. Relay B creates a BOLT11 invoice with its existing payments processor and
persists it with `invoices.purpose = peering` and a snapshot of the term.
3. Relay B publishes a signed `kind 402` event tagged `p` (Relay A), `t`
(`peering`), `bolt11`, `i` (processor invoice id) and `expiration`.
4. Relay A pays the invoice. The processor calls Relay B's existing callback,
or the billing worker finds the payment by polling. Settlement validates the
amount and extends `peering_payments.period_end` exactly once.
5. Feed access is allowed while `period_end` is in the future. An unpaid period
marks the peer `lapsed`, closes its peer sockets, and refuses feed `REQ`,
`COUNT` and `NIP-77`; it does not delete events or sync state.
6. Renewal is the same loop: the billing worker issues a renewal invoice before
the period ends and publishes it on the same `kind 402` path.

An expired invoice is retired and reissued on request after a short cooldown.
Before denying access, the relay rechecks a pending invoice with the processor,
so a missed webhook heals on its own. A peer can always authenticate and ask for
its invoice, even while lapsed, but cannot read the feed.

Billing state is stored in `peering_payments`, one row per peer and direction
(`sell` here; `buy` is reserved for the paying side). `GET /admin/peering`
merges it with the sync and request rows, showing status, access end, the open
invoice and the last processor error.
14 changes: 13 additions & 1 deletion resources/admin/assets/admin-ops.js
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,16 @@
return `${Math.round(seconds / 86400)}d`
}

const peeringBillingBadge = (billing) => {
if (!billing?.status) {
return '<span class="status-badge"><span class="status-led" aria-hidden="true"></span>Not billed</span>'
}

const status = String(billing.status)
const degraded = status === 'lapsed' || status === 'unpaid'
return `<span class="status-badge${degraded ? ' status-degraded' : ''}"><span class="status-led" aria-hidden="true"></span>${escapeHtml(status)}</span>`
}

const peeringSignalBadge = (row) => {
if (!row.configured || !row.enabled) {
return '<span class="status-badge"><span class="status-led" aria-hidden="true"></span>Disabled</span>'
Expand Down Expand Up @@ -145,7 +155,7 @@
const renderPeering = (rows) => {
if (!Array.isArray(rows) || !rows.length) {
elements.peeringBody.innerHTML =
'<tr><td colspan="8" class="admin-muted small">No peering peers configured.</td></tr>'
'<tr><td colspan="10" class="admin-muted small">No peering peers configured.</td></tr>'
return
}

Expand All @@ -158,6 +168,8 @@
return `<tr>
<td><code class="small" title="${escapeAttr(title)}">${escapeHtml(shortPubkey(row.pubkey))}</code></td>
<td class="small">${escapeHtml(row.relayUrl)}</td>
<td>${peeringBillingBadge(row.billing)}</td>
<td class="small">${escapeHtml(formatTime(row.billing?.periodEnd))}</td>
Comment thread
Ferryx349 marked this conversation as resolved.
Resolved
<td class="small">${escapeHtml(formatTime(state?.lastReconciledAt))}</td>
<td>${escapeHtml(formatLag(state?.lagSeconds))}</td>
<td>${escapeHtml(state?.missingEvents ?? '—')}</td>
Expand Down
4 changes: 3 additions & 1 deletion resources/admin/dashboard.html
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,8 @@ <h2 class="section-title">Peering</h2>
<tr>
<th scope="col">Peer</th>
<th scope="col">Relay</th>
<th scope="col">Billing</th>
<th scope="col">Access until</th>
<th scope="col">Last reconciliation</th>
<th scope="col">Lag</th>
<th scope="col">Missing</th>
Expand All @@ -245,7 +247,7 @@ <h2 class="section-title">Peering</h2>
</tr>
</thead>
<tbody id="peering-body">
<tr><td colspan="8" class="admin-muted small">No peering peers configured.</td></tr>
<tr><td colspan="10" class="admin-muted small">No peering peers configured.</td></tr>
</tbody>
</table>
</div>
Expand Down
2 changes: 2 additions & 0 deletions src/@types/negentropy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ export interface INegentropySessions {
): boolean
/** The live session for an id, with its idle timer restarted. */
touch(subscriptionId: SubscriptionId): NegentropySession | undefined
/** The live session for an id, without restarting its idle timer. */
peek(subscriptionId: SubscriptionId): NegentropySession | undefined
/** Drops a reservation that never became a session; a no-op if it has since been replaced. */
release(subscriptionId: SubscriptionId, token: NegentropySessionToken): void
close(subscriptionId: SubscriptionId): boolean
Expand Down
2 changes: 2 additions & 0 deletions src/@types/services.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ export interface IPeeringBillingService {
ensureInvoice(peerPubkey: Pubkey, options?: { now?: Date; renewal?: boolean }): Promise<Invoice | undefined>
/** Ends expired periods once, marking them lapsed and alerting the operator. */
processLapses(now?: Date): Promise<number>
/** Renewal window, period end/lapse, and invoice expiry bookkeeping. */
processLifecycle(now?: Date): Promise<number>
/** Clears a pointer and updates status after the processor confirms an invoice expired. */
handleInvoiceExpired(invoice: Invoice): Promise<void>
}
Expand Down
11 changes: 10 additions & 1 deletion src/adapters/web-socket-adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -197,10 +197,12 @@ export class WebSocketAdapter extends EventEmitter implements IWebSocketAdapter
check: () => Promise<Date | null | false>,
): Promise<void> {
let nextPeriodEnd: Date | null | false = false
let checkFailed = false

try {
nextPeriodEnd = await check()
} catch (error) {
checkFailed = true
logger.error('unable to check paid subscription expiry for %s: %o', subscriptionId, error)
}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

Expand All @@ -222,7 +224,14 @@ export class WebSocketAdapter extends EventEmitter implements IWebSocketAdapter

this.clearSubscriptionExpiry(subscriptionId)
this.endSubscription(subscriptionId)
this.sendMessage(createClosedMessage(subscriptionId, 'payment-required: peering access expired'))
this.sendMessage(
createClosedMessage(
subscriptionId,
checkFailed
? 'error: unable to check peering access'
: 'payment-required: peering access expired',
),
)
}

private clearSubscriptionExpiry(subscriptionId: SubscriptionId): void {
Expand Down
18 changes: 18 additions & 0 deletions src/adapters/web-socket-server-adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ export class WebSocketServerAdapter extends WebServerAdapter implements IWebSock
this.webSocketsAdapters = new WeakMap()

this.on(WebSocketServerAdapterEvent.Broadcast, this.onBroadcast.bind(this))
this.on(WebSocketServerAdapterEvent.PeeringRevoke, this.onPeeringRevoke.bind(this))

this.webSocketServer
.on(WebSocketServerAdapterEvent.Connection, this.onConnection.bind(this))
Expand Down Expand Up @@ -123,6 +124,23 @@ export class WebSocketServerAdapter extends WebServerAdapter implements IWebSock
})
}

private onPeeringRevoke(payload: { pubkey?: unknown }) {
const pubkey = typeof payload?.pubkey === 'string' ? payload.pubkey : undefined
if (!pubkey) {
return
}

this.webSocketServer.clients.forEach((webSocket: WebSocket) => {
const webSocketAdapter = this.webSocketsAdapters.get(webSocket)
if (webSocketAdapter?.getPeerPubkey() !== pubkey) {
return
}

logger('closing peer %s: peering access ended', pubkey)
webSocket.close(4001, 'payment-required: peering access expired')
})
}

private onBroadcast(event: Event) {
this.webSocketServer.clients.forEach((webSocket: WebSocket) => {
if (!propEq('readyState', OPEN)(webSocket)) {
Expand Down
21 changes: 12 additions & 9 deletions src/app/maintenance-worker.ts
Original file line number Diff line number Diff line change
Expand Up @@ -272,10 +272,13 @@ export class MaintenanceWorker implements IRunnable {
mergeDeepLeft({ amountPaid }),
)(invoice)

await Promise.all([
this.paymentsService.confirmInvoice(update),
this.paymentsService.sendInvoiceUpdateNotification(update),
])
await this.paymentsService.confirmInvoice(update)

// Peering settlement is complete once confirmInvoice applies the period;
// a generic “invoice paid” notice would not match the peer's peering filter.
if (invoice.purpose !== InvoicePurpose.PEERING) {
await this.paymentsService.sendInvoiceUpdateNotification(update)
}

await delay()
}
Expand Down Expand Up @@ -313,7 +316,7 @@ export class MaintenanceWorker implements IRunnable {
}

await this.processSubscriptions()
await this.processPeeringLapses()
await this.processPeering()

await clearOldEventsPromise
await this.publishOpsHeartbeat({
Expand All @@ -333,14 +336,14 @@ export class MaintenanceWorker implements IRunnable {
}
}

private async processPeeringLapses(): Promise<void> {
private async processPeering(): Promise<void> {
try {
const changed = await this.peeringBillingService?.processLapses()
const changed = await this.peeringBillingService?.processLifecycle()
if (changed) {
logger('lapsed %d peering relationship(s)', changed)
logger('moved %d peering relationship(s) through their lifecycle', changed)
}
} catch (error) {
logger.error('Unable to process peering lapses', error)
logger.error('Unable to process peering billing', error)
}
}

Expand Down
2 changes: 2 additions & 0 deletions src/constants/adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,6 @@ export enum WebSocketAdapterEvent {
export enum WebSocketServerAdapterEvent {
Broadcast = 'broadcast',
Connection = 'connection',
/** Close any socket currently authenticated as a peer whose paid access ended. */
PeeringRevoke = 'peering-revoke',
}
7 changes: 5 additions & 2 deletions src/controllers/admin/get-admin-peering-controller.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { Request, Response } from 'express'

import { IController } from '../../@types/controllers'
import { IPeeringPaymentRepository } from '../../@types/repositories'
import { Settings } from '../../@types/settings'
import { mergePeeringRows } from '../../utils/admin-peering'
import { PeeringRequestStatsStore } from '../../utils/peering-request-stats'
Expand All @@ -12,15 +13,17 @@ export class GetAdminPeeringController implements IController {
private readonly stateStore: PeeringSyncStateStore,
private readonly getSettings: () => Settings = loadMergedSettings,
private readonly requestStatsStore?: PeeringRequestStatsStore,
private readonly peeringPaymentRepository?: IPeeringPaymentRepository,
) {}

public async handleRequest(_request: Request, response: Response): Promise<void> {
const [states, settings, requestStats] = await Promise.all([
const [states, settings, requestStats, billing] = await Promise.all([
this.stateStore.list(),
this.getSettings(),
this.requestStatsStore?.list() ?? [],
this.peeringPaymentRepository?.list() ?? [],
])
const peers = mergePeeringRows(settings, states, undefined, requestStats)
const peers = mergePeeringRows(settings, states, undefined, requestStats, billing)

response.status(200).setHeader('content-type', 'application/json').send({ peers })
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ import { IController } from '../../@types/controllers'
import { RedisAdapter } from '../../adapters/redis-adapter'
import { getCacheClient } from '../../cache/client'
import { GetAdminPeeringController } from '../../controllers/admin/get-admin-peering-controller'
import { getMasterDbClient } from '../../database/client'
import { PeeringPaymentRepository } from '../../repositories/peering-payment-repository'
import { PeeringRequestStatsStore } from '../../utils/peering-request-stats'
import { PeeringSyncStateStore } from '../../utils/peering-sync-state'

Expand All @@ -13,7 +15,12 @@ export const createGetAdminPeeringController = (): IController => {
const cache = new RedisAdapter(getCacheClient())
const stateStore = new PeeringSyncStateStore(cache)
const requestStatsStore = new PeeringRequestStatsStore(cache)
sharedController = new GetAdminPeeringController(stateStore, undefined, requestStatsStore)
sharedController = new GetAdminPeeringController(
stateStore,
undefined,
requestStatsStore,
new PeeringPaymentRepository(getMasterDbClient()),
)
}

return sharedController
Expand Down
2 changes: 1 addition & 1 deletion src/factories/message-handler-factory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ export const messageHandlerFactory =
peeringBillingServiceFor(adapter),
)
case MessageType.NEG_MSG:
return new NegMsgMessageHandler(adapter, createSettings)
return new NegMsgMessageHandler(adapter, createSettings, peeringBillingServiceFor(adapter))
case MessageType.NEG_CLOSE:
return new NegCloseMessageHandler(adapter)
default:
Expand Down
18 changes: 18 additions & 0 deletions src/factories/peering-billing-service-factory.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import cluster from 'cluster'
import { WebSocketServerAdapterEvent } from '../constants/adapter'
import { getMasterDbClient } from '../database/client'
import { InvoiceRepository } from '../repositories/invoice-repository'
import { NotificationOutboxRepository } from '../repositories/notification-outbox-repository'
Expand All @@ -6,6 +8,21 @@ import { PeeringBillingService } from '../services/peering-billing-service'
import { createPaymentsService } from './payments-service-factory'
import { createSettings } from './settings-factory'

/**
* A worker cannot reach another worker's sockets. The primary fans this message out
* to every client worker, and WebSocketServerAdapter closes the matching peer sockets.
*/
const revokePeer = (pubkey: string): void => {
if (!cluster.isWorker || typeof process.send !== 'function') {
return
}

process.send({
eventName: WebSocketServerAdapterEvent.PeeringRevoke,
event: { pubkey },
})
}

export const createPeeringBillingService = (): PeeringBillingService => {
const dbClient = getMasterDbClient()

Expand All @@ -16,5 +33,6 @@ export const createPeeringBillingService = (): PeeringBillingService => {
createPaymentsService(),
new NotificationOutboxRepository(dbClient),
createSettings,
revokePeer,
)
}
5 changes: 2 additions & 3 deletions src/handlers/count-message-handler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import { createClosedMessage, createCountResultMessage } from '../utils/messages
import { isCountAuthorized } from '../utils/nip42'
import { subscriptionLimitsFor } from '../utils/peer-limits'
import { getPeerRequestRetryAfterMs } from '../utils/peer-requests'
import { peeringPaymentRequiredReason } from '../utils/peering-billing'
import { PeeringRequestStatsStore } from '../utils/peering-request-stats'

const debug = createLogger('count-message-handler')
Expand Down Expand Up @@ -70,9 +71,7 @@ export class CountMessageHandler implements IMessageHandler {
}

if (!access.allowed) {
const reason = access.reason?.startsWith('payment-required:')
? access.reason
: `payment-required: ${access.reason ?? 'peering payment required; request the kind 402 peering invoice'}`
const reason = peeringPaymentRequiredReason(access)
this.webSocket.emit(WebSocketAdapterEvent.Message, createClosedMessage(queryId, reason))
return
}
Expand Down
Loading
Loading