NIP-90
======

Data Vending Machines
---------------------

`draft` `optional`

This NIP defines listings for service providers, AKA "Data Vending Machines".

## Flows

A flow is an independently-defined specification for how users ineract with a given service. The flow may be identified using any one of the following:

- A `DVM-XX` number, referring to a specification contained in this document, e.g. `["n", "DVM-01"]`.
- A url pointing to a web page containing a flow specification, e.g. `["n", "https://example.com/my-dvm"]`.
- A nostr event address pointing to any event which contains a flow specification, e.g. `["n", "<kind>:<pubkey>:<d>"]`.

Flow specifications MAY describe ANY flow, but SHOULD use nostr events as the primary means of communication between parties. Nostr events SHOULD specify the address of the `kind 31999` service announcement event when relevant, rather than the serivce provider's pubkey. Events SHOULD be posted to the recipient's inbox relays unless specified otherwise.

## Discovery

Service Providers MAY use a `kind 31999` service announcement event to advertise their support for a given flow:

- `n` is a [flow](#flows) identifier
- `name` is the name of the service
- `about` is a description of the service
- `picture` is a logo URL representing the service

```yaml
{
  "kind": 31999,
  "pubkey": "<provider_pubkey>",
  "created_at": 1000000000,
  "content": "",
  "tags": [
    ["d", "<service_identifier>"],
    ["n", "<flow_identifier>"],
    ["name", "<service_name>"],
    ["about", "<service_description>"],
    ["picture", "<service_logo_url>"],
    ["other_tag", "<defined by the flow documentation>"]
  ]
}
```

Flows MAY define additional tags that should be included on service announcement events.

Note that in the past DVMs were announced using kind `31990` application handler events, as defined in [NIP-89](./89.md). Publishing and consuming these events for DVMs is not recommended, but MAY be supported for backwards compatibility.

## Heartbeat Events

Service providers MAY publish kind `1999` heartbeat events to indicate service availability. Heartbeat events MUST include an `expiration` tag. The event's `content` MAY include human-readable information about the service's current status.

```yaml
{
  "kind": 1999,
  "pubkey": "<provider_pubkey>",
  "content": "<status_information>",
  "created_at": 1000000000,
  "tags": [
    ["a", "<address of 31999 event>"],
    ["expiration", "<unix-timestamp>"]
  ]
}
```

## Flow Specifications

### DVM-01 - Content Discovery

User publishes a `kind 5300` request for recommended content, including the following tags:

- `param, max_results` with the max number of requested recommendations
- `param, user` with the pubkey of the user making the request
- `relays` with one or more relays on which the service provider should respond
- `p` the pubkey of the service provider (optionally, to request a specific provider)

```yaml
{
    "id": "3706c9b6d150a8dd81596bbb7af2c7483b12b3342abea789365812426500057d",
    "pubkey": "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322",
    "created_at": 1748535017,
    "kind": 5300,
    "tags": [
        ["param", "max_results", "200"],
        ["param", "user", "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322"],
        ["relays", "wss://relay.nostrdvm.com", "wss://nostr.mom", "wss://nostr.oxtr.dev"],
        ["p", "96945c769ef9e91be05570fef1003633f5bb9d072ba2453781b5140013ab35b3"]
    ],
    "content": "NIP 90 Content Discovery request",
}
```

The service then responds with a `kind 6300` with the `content` set to a stringified tag list of e-tagged events. These are the recommendations. In addition, the response SHOULD include the following tags:

- `status` - `success` if successful
- `request` - the stringified `kind 5300` request event JSON
- `e` - the `kind 5300` request event id
- `p` - the author of the `kind 5300` event

```yaml
{
    "content": "[[\"e\", \"5614552b203ed72011d52afe03aa022491fbc0aa7dc7b51fc72d132f1f4e58d5\"]]",
    "created_at": 1748535020,
    "id": "66c83248e174bfeef852f80278290700627bf12e00aec3afe3785c8d607443d7",
    "kind": 6300,
    "pubkey": "96945c769ef9e91be05570fef1003633f5bb9d072ba2453781b5140013ab35b3",
    "tags": [
        ["request", "<stringified 5300 request event>"],
        ["e", "3706c9b6d150a8dd81596bbb7af2c7483b12b3342abea789365812426500057d"],
        ["p", "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322"],
        ["alt", "This is the result of a NIP90 DVM task with kind 5300"],
        ["status", "success"],
        ["relays", "wss://relay.nostrdvm.com", "wss://nostr.mom", "wss://nostr.oxtr.dev"]
    ]
}
```