{"id":"0d2a2a1fbdccdf42049d81238480ebf7448b8e629e6deb65241cf82586779243","pubkey":"44a3a93660c84b21006efd96da8e9dd728abda4853371584c5b15c1a1eedf548","created_at":1772182913,"kind":30817,"tags":[["d","nip-31402"],["title","NIP-31402: SARA Revenue Share Offering Registry"],["summary","Standard Nostr event kind for publishing and discovering SARA revenue share offerings. Enables agents and humans to find, evaluate, and subscribe to Lightning-settled revenue share agreements autonomously."],["t","sara"],["t","lightning"],["t","l402"]],"content":"# NIP-31402 — SARA Revenue Share Offering Registry\n\n`draft` `optional`\n\n## Abstract\n\nThis NIP defines a standard Nostr event kind for publishing, discovering, and updating SARA (Simple Autonomous Revenue Agreement) offerings. Kind **31402** allows issuers to advertise revenue share agreements on public Nostr relays. Agents and humans can discover, evaluate, and subscribe to SARA offerings entirely autonomously.\n\n## Motivation\n\nSARA is a protocol for Lightning-settled revenue share agreements between API issuers and investors (human or agent). A decentralised registry of SARA offerings allows:\n\n- **Agents** to discover and subscribe to revenue share opportunities autonomously\n- **Issuers** to publish offerings permissionlessly without a central platform\n- **Investors** to verify terms on-chain and track issuers by reputation\n- **Clients** to aggregate across relays and filter by pool share, payout schedule, and tier\n\n## Event Kind\n\n| Kind  | Description |\n|-------|-------------|\n| 31402 | SARA Revenue Share Offering (addressable, replaceable per pubkey+d) |\n\nThe kind 31402 mirrors kind 30402 (L402 Service Registry) intentionally — SARA is the return leg of the L402 payment relationship.\n\n## Event Structure\n\n```json\n{\n  \"kind\": 31402,\n  \"pubkey\": \"<issuer pubkey>\",\n  \"created_at\": <unix timestamp>,\n  \"content\": \"<markdown description of the offering>\",\n  \"tags\": [\n    [\"d\", \"<issuer-slug>\"],\n    [\"name\", \"<project or service name>\"],\n    [\"url\", \"<SARA endpoint base URL>\"],\n    [\"pool_share\", \"<decimal>\"],\n    [\"payout_trigger\", \"<trigger>\"],\n    [\"threshold_sats\", \"<integer>\"],\n    [\"term_months\", \"<integer>\"],\n    [\"call_rebate\", \"<decimal>\"],\n    [\"tiers\", \"<JSON array>\"],\n    [\"lightning\", \"<issuer lightning address>\"],\n    [\"t\", \"sara\"]\n  ]\n}\n```\n\n## Tag Definitions\n\n| Tag               | Required | Description |\n|-------------------|----------|-------------|\n| `d`               | ✅       | Unique slug for this offering. Stable across updates. |\n| `name`            | ✅       | Human-readable name of the issuing project or service. |\n| `url`             | ✅       | Base URL of the SARA API (where `GET /api/sara` is served). |\n| `pool_share`      | ✅       | Decimal fraction of revenue allocated to all SARA holders combined. E.g. `\"0.15\"` for 15%. Issuer-defined — the protocol does not prescribe this value. |\n| `payout_trigger`  | ✅       | When payouts are triggered: `per_transaction`, `threshold`, `daily`, `weekly`, or `monthly`. Issuer-defined. |\n| `threshold_sats`  | ⬜       | Minimum accumulated sats before a payout is sent. Required when `payout_trigger` is `threshold`. Issuer-defined. |\n| `term_months`     | ✅       | Duration of the agreement in months. Issuer-defined. |\n| `call_rebate`     | ⬜       | Decimal discount on API calls for SARA holders. E.g. `\"0.10\"` for 10%. Omit or use `\"0\"` if not offered. |\n| `tiers`           | ✅       | JSON array of tier objects (see below). Issuer-defined — count, cost, and pool fraction are not prescribed. |\n| `lightning`       | ✅       | Issuer's Lightning Address for identity and contact. |\n| `t`               | ✅       | Must include `\"sara\"`. Additional topic tags optional. |\n\n## Tiers Format\n\nThe `tiers` tag value is a JSON array string. Each tier object:\n\n```json\n[\n  {\n    \"id\": \"standard\",\n    \"label\": \"Standard\",\n    \"cost_sats\": 100000,\n    \"pool_fraction\": 0.01\n  }\n]\n```\n\n| Field          | Type   | Description |\n|----------------|--------|-------------|\n| `id`           | string | Unique identifier for this tier. Used in `POST /api/sara/subscribe`. |\n| `label`        | string | Human-readable tier name. |\n| `cost_sats`    | int    | Cost to purchase this tier in satoshis. Issuer-defined. |\n| `pool_fraction`| float  | Fraction of the pool allocated to one holder of this tier. E.g. `0.01` = 1% of the pool. Issuer-defined. |\n\n> ⚠️ Tier counts, costs, and pool fractions are entirely issuer-defined. The protocol does not prescribe or recommend specific values. Any figures in examples are illustrative only.\n\n## Payout Triggers\n\n| Value            | Description |\n|------------------|-------------|\n| `per_transaction`| A micropayment is sent to all holders immediately after each billable API call. |\n| `threshold`      | Payouts are batched until each holder's accumulated share reaches `threshold_sats`. |\n| `daily`          | A single payout cycle runs once per calendar day. |\n| `weekly`         | A single payout cycle runs once per week. |\n| `monthly`        | A single payout cycle runs once per calendar month. |\n\n## Content Field\n\nThe `content` field SHOULD contain a Markdown description of the offering including:\n- What the issuing service does\n- How payout calculation works (formula: `revenue × pool_share × tier.pool_fraction`)\n- How to subscribe (the `POST /api/sara/subscribe` endpoint)\n- Links to the public ledger (`GET /api/sara/ledger`)\n- Any additional issuer notes or constraints\n\n## Payout Formula\n\nFor any payout period:\n\n```\nholder_payout_sats = period_revenue_sats × pool_share × tier.pool_fraction\n```\n\nWhere `period_revenue_sats` is total revenue received by the issuer in the period defined by `payout_trigger`.\n\n## Deletion / Closing\n\nTo close or delist a SARA offering, publish a NIP-09 deletion event:\n\n```json\n{\n  \"kind\": 5,\n  \"tags\": [[\"a\", \"31402:<pubkey>:<d-tag>\"]]\n}\n```\n\nActive subscriptions remain valid until their `term_end` date regardless of deletion.\n\n## Agent Submission Instructions\n\nAutonomous agents that wish to publish a SARA offering MUST:\n\n1. Deploy the four required SARA endpoints (`GET /api/sara`, `POST /api/sara/subscribe`, `GET /api/sara/status/:hash`, `GET /api/sara/ledger`).\n2. Construct a kind 31402 event with all required tags.\n3. Sign with the operator's private key (NIP-01).\n4. Publish to at least 3 relays.\n\nExample (using `nak` CLI):\n\n```bash\nTIERS='[{\"id\":\"standard\",\"label\":\"Standard\",\"cost_sats\":100000,\"pool_fraction\":0.01}]'\n\nnak event \\\n  --kind 31402 \\\n  --tag d=my-sara \\\n  --tag name=\"My API SARA\" \\\n  --tag url=\"https://api.example.com\" \\\n  --tag pool_share=0.15 \\\n  --tag payout_trigger=threshold \\\n  --tag threshold_sats=1000 \\\n  --tag term_months=12 \\\n  --tag call_rebate=0.10 \\\n  --tag \"tiers=$TIERS\" \\\n  --tag lightning=myapi@wallet.ln \\\n  --tag t=sara \\\n  --content \"## My API SARA Offering\\n\\n15% revenue pool. Threshold payouts at 1,000 sats.\" \\\n  wss://relay.damus.io wss://nos.lol wss://relay.primal.net\n```\n\n## Human Submission (NIP-07)\n\nClients implementing a SARA Index SHOULD provide a web form that:\n\n1. Collects required fields from the issuer.\n2. Constructs the kind 31402 event client-side.\n3. Calls `window.nostr.signEvent(event)` (NIP-07) to sign.\n4. Publishes to relays via WebSocket.\n\n## Agent Subscription Instructions\n\nAn agent wishing to subscribe to a SARA offering:\n\n1. Fetch kind 31402 events from relays: `{\"kinds\":[31402],\"#t\":[\"sara\"]}`\n2. Evaluate terms (pool_share, payout_trigger, term_months, tiers).\n3. Call `POST <url>/api/sara/subscribe` with `{\"tier\":\"<id>\",\"payout_address\":\"<lightning_address>\"}`.\n4. Pay the L402 Lightning invoice returned in the `402` response.\n5. Store the returned Yield Macaroon credential.\n6. Receive automatic Lightning payouts to the provided Lightning Address.\n\n## Discovery\n\n```json\n{\"kinds\": [31402], \"#t\": [\"sara\"]}\n```\n\nFilter by payout trigger:\n\n```json\n{\"kinds\": [31402], \"#payout_trigger\": [\"per_transaction\"]}\n```\n\n## Example Event\n\n```json\n{\n  \"kind\": 31402,\n  \"pubkey\": \"44a3a93660c84b21006efd96da8e9dd728abda4853371584c5b15c1a1eedf548\",\n  \"content\": \"## Example API SARA\\n\\n15% of monthly revenue shared with SARA holders.\",\n  \"tags\": [\n    [\"d\", \"example-api-sara\"],\n    [\"name\", \"Example API\"],\n    [\"url\", \"https://api.example.com\"],\n    [\"pool_share\", \"0.15\"],\n    [\"payout_trigger\", \"threshold\"],\n    [\"threshold_sats\", \"1000\"],\n    [\"term_months\", \"12\"],\n    [\"call_rebate\", \"0.10\"],\n    [\"tiers\", \"[{\\\"id\\\":\\\"standard\\\",\\\"label\\\":\\\"Standard\\\",\\\"cost_sats\\\":100000,\\\"pool_fraction\\\":0.01}]\"],\n    [\"lightning\", \"example@wallet.ln\"],\n    [\"t\", \"sara\"]\n  ]\n}\n```\n\n## Implementations\n\n- [SARA Index](https://sara-index.netlify.app) — community directory fetching kind 31402 events\n- [SARA Protocol](https://sara-protocol.netlify.app) — spec and implementation guide\n\n## See Also\n\n- [NIP-30402](./NIP-30402.md) — L402 Service Registry\n- [NIP-01](https://github.com/nostr-protocol/nostr/blob/master/01.md) — Basic protocol\n- [NIP-07](https://github.com/nostr-protocol/nostr/blob/master/07.md) — Browser signer\n- [NIP-09](https://github.com/nostr-protocol/nostr/blob/master/09.md) — Event deletion","sig":"06817725dbe6d52bc8cc2742b3dba46028513245ce49b68467a79fd2bf0eb721c6582dbab608798401a79d56f33d0695e3d02e0dd9eb9dc80fbede472dacb1a6"}