ONS-4: Service Model for Recurring LN Subscriptions




The goal is to enable a LN-based subscription model for service providers, where


SE Engine Room: Service operated by the Service Provider, ideally near the LN node to minimize latency. It acts as a translator between authorized Nostr messages and the Service Provider's LN node. Upon request, it can query the LN node and return a list of settled invoices as encrypted Nostr messages.

SE Deck: Service operated by the Service Provider, ideally close to the Premium Service that needs to check whether an account is authorized. It provides an API to determine if an account (a pubkey) has an active membership or not. It periodically queries the SE Engine Room for newly settled invoices.

Satship Enterprise: reference implementation of this spec

No components need to keep any state. The Deck could persist the query results across restarts, but to avoid inconsistencies it's best to do a full sync on each startup.

Event Types

Kind 20100 (Query): Executed periodically by the Deck. Indicates a query for all settled invoices where the memo is an npub. The event content is an optional epoch timestamp. If set, it means an earliest cutoff date for the queried invoices.

Kind 20101 (Response Payload): When the Engine Room receives the above message from a paired pubkey, it queries the LN node for settled invoices and prepares a response. For each settled invoice it found that matched the query, it returns it wrapped into such an event with the content:

  "npub": "...",         // npub from the invoice memo
  "amount_sat": ...,     // Settled amount
  "ts": ...              // Settled timestamp

Kind 20102 (End of Transmission): The Engine Room sends this message when there are no more settled invoices to return.

All events are encrypted according to the NIP-04 Encrypted Messages scheme and have an identical structure, except for the kind.

Membership View

The Deck is building a dynamic view of past and current memberships, based on the settled invoices and their memos.

To achieve this, the first query to the Engine Room is one for "all settled invoices". Each subsequent query uses the optional timestamp argument to only query newly settled invoices since the previous query.

Subscription Lifecycle

To register, a new user simply has to send a payment to the Service Provider's LN Address and set the according npub as memo (payment description).

Based on the service provider's rate (sats per unit of time), the list of settled payments of an account are converted to a list of membership periods.

An account is considered to have an active membership if, after all its settled payments are accounted for, they result in a membership end date that is in the future.

As a consequence, any new payments will automatically extend the membership. Similarly, if payments stop, the membership will expire automatically.