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#

Kind	Description
31402	SARA Revenue Share Offering (addressable, replaceable per pubkey+d)

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#

Tag	Required	Description
d	✅	Unique slug for this offering. Stable across updates.
name	✅	Human-readable name of the issuing project or service.
url	✅	Base URL of the SARA API (where GET /api/sara is served).
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.
payout_trigger	✅	When payouts are triggered: per_transaction, threshold, daily, weekly, or monthly. Issuer-defined.
threshold_sats	⬜	Minimum accumulated sats before a payout is sent. Required when payout_trigger is threshold. Issuer-defined.
term_months	✅	Duration of the agreement in months. Issuer-defined.
call_rebate	⬜	Decimal discount on API calls for SARA holders. E.g. "0.10" for 10%. Omit or use "0" if not offered.
tiers	✅	JSON array of tier objects (see below). Issuer-defined — count, cost, and pool fraction are not prescribed.
lightning	✅	Issuer's Lightning Address for identity and contact.
t	✅	Must include "sara". Additional topic tags optional.

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
  }
]

Field	Type	Description
id	string	Unique identifier for this tier. Used in POST /api/sara/subscribe.
label	string	Human-readable tier name.
cost_sats	int	Cost to purchase this tier in satoshis. Issuer-defined.
pool_fraction	float	Fraction of the pool allocated to one holder of this tier. E.g. 0.01 = 1% of the pool. Issuer-defined.

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

Value	Description
per_transaction	A micropayment is sent to all holders immediately after each billable API call.
threshold	Payouts are batched until each holder's accumulated share reaches threshold_sats.
daily	A single payout cycle runs once per calendar day.
weekly	A single payout cycle runs once per week.
monthly	A single payout cycle runs once per calendar month.

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 lightning=myapi@wallet.ln \
  --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 (pool_share, payout_trigger, 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", "example@wallet.ln"],
    ["t", "sara"]
  ]
}

Implementations#

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

See Also#

• NIP-30402 — L402 Service Registry
• NIP-01 — Basic protocol
• NIP-07 — Browser signer
• NIP-09 — Event deletion