NIP-31402: SARA Revenue Share Offering Registry

NIP-31402 — SARA Revenue Share Offering Registry

draft optional

Abstract

This 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.

Motivation

SARA is a protocol for Lightning-settled revenue share agreements between API issuers and investors (human or agent). A decentralised registry of SARA offerings allows:

• Agents to discover and subscribe to revenue share opportunities autonomously
• Issuers to publish offerings permissionlessly without a central platform
• Investors to verify terms on-chain and track issuers by reputation
• Clients to aggregate across relays and filter by pool share, payout schedule, and tier

Event Kind

The kind 31402 mirrors kind 30402 (L402 Service Registry) intentionally — SARA is the return leg of the L402 payment relationship.

Event Structure

{
  "kind": 31402,
  "pubkey": "<issuer pubkey>",
  "created_at": <unix timestamp>,
  "content": "<markdown description of the offering>",
  "tags": [
    ["d", "<issuer-slug>"],
    ["name", "<project or service name>"],
    ["url", "<SARA endpoint base URL>"],
    ["pool_share", "<decimal>"],
    ["payout_trigger", "<trigger>"],
    ["threshold_sats", "<integer>"],
    ["term_months", "<integer>"],
    ["call_rebate", "<decimal>"],
    ["tiers", "<JSON array>"],
    ["lightning", "<issuer lightning address>"],
    ["t", "sara"]
  ]
}

Tag Definitions

Tiers Format

The tiers tag value is a JSON array string. Each tier object:

[
  {
    "id": "standard",
    "label": "Standard",
    "cost_sats": 100000,
    "pool_fraction": 0.01
  }
]

⚠️ 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.

Payout Triggers

Content Field

The content field SHOULD contain a Markdown description of the offering including:

• What the issuing service does
• How payout calculation works (formula: revenue × pool_share × tier.pool_fraction)
• How to subscribe (the POST /api/sara/subscribe endpoint)
• Links to the public ledger (GET /api/sara/ledger)
• Any additional issuer notes or constraints

Payout Formula

For any payout period:

holder_payout_sats = period_revenue_sats × pool_share × tier.pool_fraction

Where period_revenue_sats is total revenue received by the issuer in the period defined by payout_trigger.

Deletion / Closing

To close or delist a SARA offering, publish a NIP-09 deletion event:

{
  "kind": 5,
  "tags": [["a", "31402:<pubkey>:<d-tag>"]]
}

Active subscriptions remain valid until their term_end date regardless of deletion.

Agent Submission Instructions

Autonomous agents that wish to publish a SARA offering MUST:

1. Deploy the four required SARA endpoints (GET /api/sara, POST /api/sara/subscribe, GET /api/sara/status/:hash, GET /api/sara/ledger).
2. Construct a kind 31402 event with all required tags.
3. Sign with the operator's private key (NIP-01).
4. Publish to at least 3 relays.

Example (using nak CLI):

TIERS='[{"id":"standard","label":"Standard","cost_sats":100000,"pool_fraction":0.01}]'

nak event \
  --kind 31402 \
  --tag d=my-sara \
  --tag name="My API SARA" \
  --tag url="https://api.example.com" \
  --tag pool_share=0.15 \
  --tag payout_trigger=threshold \
  --tag threshold_sats=1000 \
  --tag term_months=12 \
  --tag call_rebate=0.10 \
  --tag "tiers=$TIERS" \
  --tag [email protected] \
  --tag t=sara \
  --content "## My API SARA Offering\n\n15% revenue pool. Threshold payouts at 1,000 sats." \
  wss://relay.damus.io wss://nos.lol wss://relay.primal.net

Human Submission (NIP-07)

Clients implementing a SARA Index SHOULD provide a web form that:

1. Collects required fields from the issuer.
2. Constructs the kind 31402 event client-side.
3. Calls window.nostr.signEvent(event) (NIP-07) to sign.
4. Publishes to relays via WebSocket.

Agent Subscription Instructions

An agent wishing to subscribe to a SARA offering:

1. Fetch kind 31402 events from relays: {"kinds":[31402],"#t":["sara"]}
2. Evaluate terms (poolshare, payouttrigger, term_months, tiers).
3. Call POST <url>/api/sara/subscribe with {"tier":"<id>","payout_address":"<lightning_address>"}.
4. Pay the L402 Lightning invoice returned in the 402 response.
5. Store the returned Yield Macaroon credential.
6. Receive automatic Lightning payouts to the provided Lightning Address.

Discovery

{"kinds": [31402], "#t": ["sara"]}

Filter by payout trigger:

{"kinds": [31402], "#payout_trigger": ["per_transaction"]}

Example Event

{
  "kind": 31402,
  "pubkey": "44a3a93660c84b21006efd96da8e9dd728abda4853371584c5b15c1a1eedf548",
  "content": "## Example API SARA\n\n15% of monthly revenue shared with SARA holders.",
  "tags": [
    ["d", "example-api-sara"],
    ["name", "Example API"],
    ["url", "https://api.example.com"],
    ["pool_share", "0.15"],
    ["payout_trigger", "threshold"],
    ["threshold_sats", "1000"],
    ["term_months", "12"],
    ["call_rebate", "0.10"],
    ["tiers", "[{\"id\":\"standard\",\"label\":\"Standard\",\"cost_sats\":100000,\"pool_fraction\":0.01}]"],
    ["lightning", "[email protected]"],
    ["t", "sara"]
  ]
}

Implementations

• SARA Index — community directory fetching kind 31402 events
• SARA Protocol — spec and implementation guide

See Also

• [NIP-30402](./NIP-30402.md) — L402 Service Registry
• NIP-01 — Basic protocol
• NIP-07 — Browser signer
• NIP-09 — Event deletion