payment verification, relay where content can be found, perks, actor definitions

88.md

@@ -8,8 +8,19 @@ Recurring Subscriptions
 
 This NIP defines a way for a pubkey to create recurring subscription payments to another pubkey.
 
-## Tier Event
+Actors in this flow:
-A pubkey can create "tiers". These tiers might provide certain benefits to the supporters who subscribe to these.
+* Recipient: A pubkey that receives recurring payments
+* Subscriber: A pubkey that sends recurring payments
+* Payment verifier: An optional pubkey recipients can designate to verify payments on their behalf
+
+# Kinds
+`kind:37001` - Tier Event -- Optionally published by recipients
+`kind:7001` - Subscribe Event -- Published by subscribers
+`kind:7002` - Unsubscribe Event -- Published by subscribers
+`kind:7003` - Subscription Payment Receipt -- Published by payment-verifier-pubkey
+
+## `kind:37001`: Tier Event
+A pubkey that wants to provide others the ability to subscribe to them can create "tiers". These tiers might provide certain benefits to the supporters who subscribe to these.
 
 ```js
 {
@@ -18,34 +29,49 @@ A pubkey can create "tiers". These tiers might provide certain benefits to the s
     "tags": [
         [ "title", "..." ],
         [ "image", "..." ],
+
+        // Perks
+        [ "perk", "<description>" ],
+        [ "perk", "<description>" ],
+
+        // Amount possibilities
         [ "amount", "<amount-in-base-unit>", "currency", "<monthly>" ],
         [ "amount", "<amount-in-base-unit>", "currency", "<quarterly>" ],
+
+        // Zap-splits
         [ "zap", "<recipient-pubkey>", "relay-url", "19" ], // 95%
         [ "zap", "", "relay-url", "1" ], // 5%
+
+        // Relay and payment-verification
+        [ "r", "wss://my-subscribers-only-relay.com" ],
+        [ "p", "<payment-verifier-pubkey>" ],
     ]
 }
 ```
 
-This event is generated by a pubkey who wants to allow users to support with different tiers.
+`.content`: description of what subscribers can expect.
-
-`.content` SHOULD be a description of what users who subscribe can expect.
 Tag `title` is an optional title for the tier.
 Tag `image` is an optional image for the tier.
-Tag `amount` MUST specify the payment required for this tier and its cadence.
+Zero or more `perk` tags specify the benefits of the tier; these can be rendered as a list of benefits to the user in addition to the content.
-    * The first argument should be the stringified amount and the second argument the currency
+One or more `amount` tags specify the payment required for this tier and its cadence.
+    * The first argument should be the stringified amount in cents or msats, and the second argument the currency
     * The third argument SHOULD be one of `daily`, `monthly`, `yearly`
 One or more `amount` tags MUST exist.
 Zero or more `zap` tags can exist as defined in NIP-57.
 
 A `zap` tag with no pubkey indicates that the client can include any pubkey in the `kind:7001` event (and in the resulting recurring zaps). This way, users can offer a "referral" fee to other clients.
 
+An `r` tag can be included to specify a relay where clients can find special content for this tier.
+
+Zero or more `p` tags can be included to specify a pubkey that is trusted by the tier creator to verify payments on their behalf.
+
 #### Examples
 * `[ "amount", "100", "usd", "daily" ]`, $1.00 a day.
 * `[ "amount", "1000000", "msats", "daily" ]`, 1000000 millisats a day.
 
 ## Subscribe Event
 
-```json
+```js
 {
     "kind": 7001,
     "content": "<optional-message>",
@@ -54,11 +80,10 @@ A `zap` tag with no pubkey indicates that the client can include any pubkey in t
         [ "a", "<supporting-tier-event-id>" ],
         [ "event", "<stringied-event-subscribed-to>" ],
         [ "amount", "<amount-in-base-unit>", "<currency>", "<cadence>" ],
+
+        // Zap-splits
         [ "zap", "<recipient-pubkey>", "19" ], // 95%
         [ "zap", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52", "1" ], // 5% to client developer where subscription was created
-        [ "alt", "This is a subscription event" ],
-        [ "client", "highlighter", "31990:73c6bb92440a9344279f7a36aa3de1710c9198b1e9e8a394cd13e0dd5c994c63:1704502265408" ],
-
     ]
 }
 ```
@@ -80,7 +105,7 @@ The `kind:7001` event can be created without an `e` tag so that users can create
 ## Paying
 The supporting user should create a zap `p`-tagging the receiver and e-tagging the `kind:7001`. There MUST be a single `p` and a single `e` tag in the zap request.
 
-```json
+```js
 {
     "kind": 9734,
     "content": "",
@@ -94,18 +119,10 @@ Clients supporting this NIP can check for zaps e-tagging the `kind:7001` event t
 
 The same `kind:7001` is re-zapped on a regular basis per the cadence specified in the event.
 
-## Verifying Payment
-The following conditions must be met to verify a payment:
-
-* Time between zap receipts should be equal or less than the cadence specified in the `kind:7001` event.
-* Amount of the zap receipt should be equal or greater than the amount specified in the `kind:7001` event. For currencies not directly supported by the zap spec, clients should do a best effort conversion to the currency specified in the `kind:7001` event at the time of zap receipt.
-* Zap-receipts should include a zap request `e`-tagging the `kind:7001` event. Zap-receipts might not include a signature (for NWC-automated payments where the subscriber is not present to sign the zap request).
-* Validations specified in [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md).
-
 ## Stopping a subscription
 A user who wants to signal they are no longer subscribed can publish a `kind:7002` event tagging the `kind:7001` they are stopping and `p`-tagging the pubkey they are no longer subscribed to.
 
-```json
+```js
 {
     "kind": 7002,
     "content": "<optional-message>",
@@ -114,4 +131,37 @@ A user who wants to signal they are no longer subscribed can publish a `kind:700
         [ "e", "<kind-7001-event-id>" ],
     ]
 }
-```
+```
+
+## Subscription Payment Receipt
+When a subscription payment is made and a `payment-verifier-pubkey` is set on the `kind:37001` this pubkey publishes `kind:7003` events tagging the `kind:7001` event that was paid and `p`-tagging the pubkey that received the payment.
+
+```js
+{
+    "kind": 7003,
+    "content": "<optional-message>",
+    "tags": [
+        [ "p", "<recipient-pubkey>" ],
+        [ "P", "<subscriber-pubkey>" ],
+        [ "e", "<kind-7001-event-id>" ],
+        [ "valid", "<from-timestamp>", "<to-timestamp>" ]
+        [ "tier", "kind:37001-d-tag" ]
+    ]
+}
+```
+
+`p` is the pubkey that received the payment.
+`P` is the pubkey that made the payment.
+`e` is the `kind:7001` event that was paid.
+`valid` is the period for which the payment is valid.
+`tier` is the d-tag of the `kind:37001` that this subscription is for.
+
+# Appendix 0: Verifying Payment
+The following conditions must be met to verify a payment:
+
+* Time between zap receipts should be equal or less than the cadence specified in the `kind:7001` event.
+* Amount of the zap receipt should be equal or greater than the amount specified in the `kind:7001` event. For currencies not directly supported by the zap spec, clients should do a best effort conversion to the currency specified in the `kind:7001` event at the time of zap receipt.
+* Zap-receipts should include a zap request `e`-tagging the `kind:7001` event. Zap-receipts might not include a signature (for NWC-automated payments where the subscriber is not present to sign the zap request).
+* Validations specified in [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md).
+
+If `kind:7003` events are published by the payment-verifier-pubkey, clients can use these to verify payments more simply.