nostr/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2024-11-09 22:09:06 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

clarifications, hopefully

Browse Source
This commit is contained in:
pablof7z 2023-07-24 00:38:47 +03:00
parent 280483adc5
commit 4cb3ac871f
1 changed files with 93 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
vending-machine.md
View File

@ -1,4 +1,4 @@
NIP-XX NIP-90
====== ======
Data Vending Machine Data Vending Machine
@ -6,7 +6,9 @@ Data Vending Machine
`draft` `optional` `author:pablof7z` `draft` `optional` `author:pablof7z`
This NIP defines the interaction between customers and Service Providers to perform on-demand computation. This NIP defines the interaction between customers and Service Providers for performing on-demand computation.
Money in, data out.
## Kinds ## Kinds
This NIP reserves the range `65000-66000` for data vending machine use. This NIP reserves the range `65000-66000` for data vending machine use.
@ -20,18 +22,18 @@ This NIP reserves the range `65000-66000` for data vending machine use.
[Appendix 2](#appendix-2-job-types) defines the job types. [Appendix 2](#appendix-2-job-types) defines the job types.
## Rationale ## Rationale
Nostr can act as a marketplace for data processing, where users request jobs to be processed in certain ways (e.g. "speech-to-text", "summarization", etc.), but where they don't necessarily care about "who" processes the data. Nostr can act as a marketplace for data processing, where users request jobs to be processed in certain ways (e.g., "speech-to-text", "summarization", etc.), but they don't necessarily care about "who" processes the data.
This NIP is not to be confused with a 1:1 marketplace; but rather, a flow where user announces a desired output, willingness to pay, and service providers compete to fulfill the job requirement in the best way possible. This NIP is not to be confused with a 1:1 marketplace; instead, it describes a flow where a user announces a desired output, willingness to pay, and service providers compete to fulfill the job requirement in the best way possible.
### Actors ### Actors
There are two actors to the workflow described in this NIP: There are two actors in the workflow described in this NIP:
* Customers (npubs who request a job) * Customers (npubs who request a job)
* Service providers (npubs who fulfill jobs) * Service providers (npubs who fulfill jobs)
# Event Kinds # Event Kinds
## Job request ## Job request
A request to have data processed -- published by a customer A request to have data processed, published by a customer
```json ```json
{ {
@ -50,33 +52,34 @@ A request to have data processed -- published by a customer
All tags are optional. All tags are optional.
* `i` tag: Input data for the job, (zero or more inputs may exist) * `i` tag: Input data for the job (zero or more inputs may exist)
* `<data>`: The argument for the input * `<data>`: The argument for the input
* `<input-type>`: The way this argument should be interpreted, MUST be one of: * `<input-type>`: The way this argument should be interpreted, MUST be one of:
* `url`: a URL to be fetched * `url`: A URL to be fetched
* `event`: a nostr event ID, include an optional relay-url extra param * `event`: A Nostr event ID, include an optional relay-url extra param
* `job`: the output of a previous job with the specified event ID * `job`: The output of a previous job with the specified event ID
* `text`: `<data>` is the value of the input, no resolution is needed * `text`: `<data>` is the value of the input, no resolution is needed
* `<marker>`: an optional field indicating how this input should be used within the context of the job. * `<marker>`: An optional field indicating how this input should be used within the context of the job
* `<relay>`: if `event` or `job` input-type, the relay where the event/job was published, otherwise optional or empty string. * `<relay>`: If `event` or `job` input-type, the relay where the event/job was published, otherwise optional or empty string
* `output`: MIME type. Expected output format. Service Providers SHOULD publish the result of the job in this format if it has been specified. * `output`: MIME type. Expected output format. Service Providers SHOULD publish the result of the job in this format if it has been specified
* `bid`: Customer MAY specify a maximum amount (in millisats) they are willing to pay. * `bid`: Customer MAY specify a maximum amount (in millisats) they are willing to pay
* `relays`: relays where Service Providers SHOULD publish responses to. * `relays`: Relays where Service Providers SHOULD publish responses to
* `p`: Service Providers the customer is interested in. Other SP MIGHT still choose to process the job. * `p`: Service Providers the customer is interested in. Other SPs MIGHT still choose to process the job
* `exp`: expiration timestamp. Service Providers SHOULD not send results after this timestamp. * `exp`: Expiration timestamp. Service Providers SHOULD not send results after this timestamp
## Job result ## Job result
The output of processing the data -- published by the Service Provider. The output of processing the data -- published by the Service Provider.
```json ```json
{ {
"pubkey": "<service-provider pubkey>", "pubkey": "<service-provider pubkey>",
"content": "<payload>", "content": "<payload>",
"kind": 65001, "kind": 65001,
"tags" [ "tags": [
[ "request", "<job-request>" ], [ "request", "<job-request>" ],
[ "e", "<job-request-id>", "<relay-hint>" ], [ "e", "<job-request-id>", "<relay-hint>" ],
[ "p", "<Customer's pubkey>" ], [ "p", "<Customer's pubkey>" ],
[ "status", "success", "<more-info>" ],
[ "amount", "requested-payment-amount", "<optional-bolt11>" ] [ "amount", "requested-payment-amount", "<optional-bolt11>" ]
] ]
} }
@ -91,54 +94,35 @@ Both customers and service providers can give feedback about a job.
The result of the job SHOULD be included in the `content` field. The result of the job SHOULD be included in the `content` field.
* `status` tag: Service Providers MAY indicate errors or extra info about the results by including them in the `status` tag. * `status` tag: Service Providers MAY indicate errors or extra info about the results by including them in the `status` tag.
* `amount`: millisats that the Service Provider is requesting to be paid. An optional third value can be a bolt11 invoice. * `amount`: as defined in the [Job Result](#job-result) section.
# Protocol Flow # Protocol Flow
* Customer publishes a job request (e.g. `kind:65002`). * Customer publishes a job request (e.g. `kind:65002`).
* Service Prpvoders can submit `kind:65000` job-feedback events (e.g. `payment-required`, `processing`, `error`, etc.). * Service Providers can submit `kind:65000` job-feedback events (e.g. `payment-required`, `processing`, `error`, etc.).
* Upon completion, the service provider publishes the result of the job with a `kind:65001` job-result event. * Upon completion, the service provider publishes the result of the job with a `kind:65001` job-result event.
* At any point, the user can pay the included `bolt11` or zap any of the events the service provider has sent to the user. * At any point, the user can pay the included `bolt11` or zap any of the events the service provider has sent to the user.
`kind:65000` and `kind:65001` events MAY include an `amount` tag, this can be interpreted as a suggestion to pay. Service Providers SHOULD use the `payment-required` feedback event to signal that a payment is required and no further actions will be performed until the payment is sent. Customers are can always either pay the included `bolt11` invoice or zap the event requesting the payment and service providers should monitor for both if they choose to include a bolt11 invoice. `kind:65000` and `kind:65001` events MAY include an `amount` tag, this can be interpreted as a suggestion to pay. Service Providers SHOULD use the `payment-required` feedback event to signal that a payment is required and no further actions will be performed until the payment is sent. Customers can always either pay the included `bolt11` invoice or zap the event requesting the payment and service providers should monitor for both if they choose to include a bolt11 invoice.
## Notes about the protocol flow ## Notes about the protocol flow
The flow is deliverately ambiguos, allowing vast flexibility for the interaction between customers and service providers so that service providers can model their behavior based on their own decisions. Some service providers might choose to submit a `payment-required` as the first reaction before sending an `processing` or before delivering `kind:65001` results, some might choose to serve partial results for the job (e.g. as a sample), send a `payment-required`to deliver the rest of the results, and some service providers might choose to assess likelyhood of payment based on an npub's past behavior and thus serve the job results before requesting payment for the best possible UX. The flow is deliberately ambiguous, allowing vast flexibility for the interaction between customers and service providers so that service providers can model their behavior based on their own decisions/perceptions of risk.
Some service providers might choose to submit a `payment-required` as the first reaction before sending a `processing` or before delivering `kind:65001` results, some might choose to serve partial results for the job (e.g. as a sample), send a `payment-required` to deliver the rest of the results, and some service providers might choose to assess likelihood of payment based on an npub's past behavior and thus serve the job results before requesting payment for the best possible UX.
It's not up to this NIP to define how individual vending machines should choose to run their business. It's not up to this NIP to define how individual vending machines should choose to run their business.
# Payment
Customers SHOULD pay service providers whose job results they accept by either zapping the Service Provider and tagging the `kind:65001` job result or, if included, paying the bolt11 invoice.
Additionally, if a service provider requests full or partial prepayment via a `kind:65000` job-feedback event, the customer SHOULD zap that event to pay the service provider.
# Cancellation # Cancellation
A job request might be cancelled by publishing a `kind:5` delete request event tagging the job request event. A job request might be cancelled by publishing a `kind:5` delete request event tagging the job request event.
# Job chaining # Job chaining
A Customer MAY request multiple jobs to be processed in a chained form, so that the output of a job can be the input of the next job. (e.g. summarization of a podcast's transcription). This is done by specifying as `input` an eventID of a different job with the `job` marker. A Customer MAY request multiple jobs to be processed as a chain, where the output of a job can be the input of another job. (e.g. podcast transcription -> summarization of the transcription). This is done by specifying as input an event id of a different job with the `job` type.
Service Providers MAY begin processing a subsequent job the moment they see the prior job's result, but they will likely wait for a zap to be published first. This introduces a risk that Service Provider of job #1 might delay publishing the zap event in order to have an advantage. This risk is up to Service Providers to mitigate or to decide whether the service provider of job #1 tends to have good-enough results so as to not wait for a explicit zap to assume the job was accepted. Service Providers MAY begin processing a subsequent job the moment they see the prior job's result, but they will likely wait for a zap to be published first. This introduces a risk that Service Provider of job #1 might delay publishing the zap event in order to have an advantage. This risk is up to Service Providers to mitigate or to decide whether the service provider of job #1 tends to have good-enough results so as to not wait for an explicit zap to assume the job was accepted.
This gives a higher level of flexibility to service providers (which sophisticated service providers would take anyway).
Consult [Appendix 1: Example](#appendix-1-examples)'s [Summarization of a podcast](#summarization-of-a-podcast) Consult [Appendix 1: Example](#appendix-1-examples)'s [Summarization of a podcast](#summarization-of-a-podcast)
# Job Feedback
The parties to a job request can use `kind:65000` to provide feedback about the job, using a `status` tag to indicate the type of feedback.
Any job feedback event MIGHT include an `amount` tag, indicating the amount of millisats the party is requesting to be paid. An optional third value can be a bolt11 invoice.
| status | description |
|--------|-------------|
| `payment-required` | Service Provider requires payment before continuing. |
| `processing` | Service Provider is processing the job. |
| `error` | Service Provider was unable to process the job. |
| `success` | Service Provider successfully processed the job. |
| `failure` | Service Provider failed to process the job. |
| `partial` | Service Provider partially processed the job. The `.content` might include a sample of the partial results. |
Any job feedback event MIGHT include an `amount` tag, as described in the [Job Result](#job-result) section.
Any job feedback event MIGHT include results in the `.content` field, as described in the [Job Result](#job-result) section.
### E.g. Payment required (with sample content) ### E.g. Payment required (with sample content)
```json ```json
{ {
@ -153,20 +137,15 @@ Any job feedback event MIGHT include results in the `.content` field, as describ
} }
``` ```
## Job feedback
A user might choose to not accept a job result for any reason. A user can provide feedback via NIP-25 reactions.
The `content` of the `kind:7` event SHOULD include a description of how the user reacted to the job result.
## Not addressed in this NIP ## Not addressed in this NIP
### Reputation system ### Reputation system
Service providers are at obvious risk of having their results not compensated. Mitigation of this risk is up to service providers to figure out (i.e. building reputation systems, requiring npub "balances", etc, etc). Service providers are at an obvious risk of having their results not compensated. Mitigation of this risk is up to service providers to figure out (i.e., building reputation systems, requiring npub "balances", etc.). It's out of scope (and undesirable) to have this NIP address this issue; the market should.
It's out of scope (and undesirable) to have this NIP address this issue; the market should.
### Encrypted job requests ### Encrypted job requests
Not to be included in the first draft of this NIP, but encrypted job requests should be added. A few ways: Not to be included in the first draft of this NIP, but encrypted job requests should be added. A few ways:
* publish job requests with some useful metadata of the job "e.g. length of audio to be transcribed", service providers offer to do the job, the customer replies with a NIP-04-like encrypted job requested encrypted with the service provider's pubkey. * publish job requests with some useful metadata of the job "e.g., length of audio to be transcribed", service providers offer to do the job, the customer replies with a NIP-04-like encrypted job requested encrypted with the service provider's pubkey.
# Appendix 1: Examples # Appendix 1: Examples
@ -189,7 +168,7 @@ Not to be included in the first draft of this NIP, but encrypted job requests sh
} }
``` ```
### `kind:65001`: Job Feedback: request for (partial) payment ### `kind:65000`: Job Feedback: request for (partial) payment
* The SP is signaling here that it won't start processing until 100 sats are paid * The SP is signaling here that it won't start processing until 100 sats are paid
```json ```json
{ {
@ -228,7 +207,7 @@ User publishes event #1 and #2 together.
{ {
"id": "12345", "id": "12345",
"pubkey": "abcdef", "pubkey": "abcdef",
"kinds" 65002, "kind": 65002,
"content": "", "content": "",
"tags": [ "tags": [
[ "i", "https://bitcoin.review/episode1.mp3", "url" ], [ "i", "https://bitcoin.review/episode1.mp3", "url" ],
@ -244,7 +223,7 @@ User publishes event #1 and #2 together.
{ {
"id": "12346", "id": "12346",
"pubkey": "abcdef", "pubkey": "abcdef",
"kinds": 65003, "kind": 65003,
"content": "", "content": "",
"tags": [ "tags": [
[ "i", "12345", "job" ], // input is the output of job with id 12345 [ "i", "12345", "job" ], // input is the output of job with id 12345
@ -262,16 +241,17 @@ User publishes event #1 and #2 together.
"id": "12346", "id": "12346",
"pubkey": "abcdef", "pubkey": "abcdef",
"content": "", "content": "",
"kinds": 65004, "kind": 65004,
"tags": [ "tags": [
[ "i", "<hexid>", "event", "wss://relay.nostr.com" ] [ "i", "<hexid>", "event", "wss://relay.nostr.com" ]
[ "output", "text/plain" ],
[ "params", "lang", "es_AR" ], [ "params", "lang", "es_AR" ],
[ "bid", "5000" ] [ "bid", "5000" ]
] ]
} }
``` ```
### `kind:65001`: Job respomse ### `kind:65001`: Job result
```json ```json
{ {
"kind": 65001, "kind": 65001,
@ -290,7 +270,7 @@ User publishes event #1 and #2 together.
```json ```json
{ {
"id": "123", "id": "123",
"kind" 65002, "kind": 65002,
"tags": [ "tags": [
[ "i", "https://example.com/episode1.mp3", "url" ], [ "i", "https://example.com/episode1.mp3", "url" ],
[ "bid", "100000" ] [ "bid", "100000" ]
@ -302,7 +282,7 @@ User publishes event #1 and #2 together.
```json ```json
{ {
"id": "124", "id": "124",
"kind" 65002, "kind": 65002,
"tags": [ "tags": [
[ "i", "https://example.com/episode2.mp3", "url" ], [ "i", "https://example.com/episode2.mp3", "url" ],
[ "bid", "100000" ] [ "bid", "100000" ]
@ -310,7 +290,7 @@ User publishes event #1 and #2 together.
} }
``` ```
### `kind:65003`: Job request #3 (summarize both podcasts into one paragraph) ### `kind:65003`: Job request #3 (summarize the two job's outputs into one paragraph)
```json ```json
{ {
"id": "125", "id": "125",
@ -323,6 +303,21 @@ User publishes event #1 and #2 together.
] ]
} }
``` ```
### `kind:65005`: Job request #4 (generate image based on the summary)
```json
{
"id": "126",
"kind": 65004,
"tags": [
[ "i", "125", "job" ],
[ "param", "prompt", "photorealistic" ],
[ "param", "size", "4000x4000" ],
[ "bid", "500000" ]
]
}
``
## AI-image of embedded input ## AI-image of embedded input
### `kind:65005`: Job request ### `kind:65005`: Job request
@ -337,61 +332,60 @@ User publishes event #1 and #2 together.
} }
``` ```
### `kind:65006`: Job request #4 (generate image based on the summary)
```json
{
"id": "126",
"kind": 65004,
"tags": [
[ "i", "125", "job" ],
[ "param", "prompt", "photorealistic" ],
[ "param", "size", "4000x4000" ],
[ "bid", "500000" ]
]
}
```
# Appendix 2: Job types # Appendix 2: Job types
This is a list of all the supported job requests This is a list of all the supported job requests.
.
## speech-to-text: `kind:65002` ## speech-to-text: `kind:65002`
### params ### params
| param | req? | description
|--------------------------------|------|-------- | param | req? | description |
| `range` | opt | timestamp range (in seconds) of desired text to be transcribed |------------|------|-----------------------------------------------------------|
| `alignment` | opt | word, segment, raw: word-level, segment-level or raw outputs | `range` | opt | timestamp range (in seconds) of desired text to be transcribed |
| `alignment`| opt | word, segment, raw: word-level, segment-level, or raw outputs |
## summarization: `kind:65003` ## summarization: `kind:65003`
| param | req? | description
|--------------------------------|------|-------- | param | req? | description |
| `length` | opt | desired length |-----------|------|---------------|
| `length` | opt | desired length |
## translation: `kind:65004` ## translation: `kind:65004`
| param | req? | description
|--------------------------------|------|-------- | param | req? | description |
| `lang` | req | desired language in BCP 47 format. |-----------|------|--------------------------------------------|
| `lang` | req | desired language in BCP 47 format. |
## image generation: `kind:65005` ## image generation: `kind:65005`
| param | req? | description
|--------------------------------|------|--------
| `prompt` | opt | extra prompt to be used for the image generation
| `size` | opt | desired size of the image
# Notes | param | req? | description |
|-----------|------|-------------------------------------------------------|
| `prompt` | opt | extra prompt to be used for the image generation |
| `size` | opt | desired size of the image |
* Job acceptance ambiguity, particularly for job-chaining circumstances is deliberate: service providers could wait until explicit job result acceptance / payment to start working on the next item on the chain, or they could start working as soon as they see a result of the previous job computed.
That's up to each service provider to choose how to behave depending on the circumstances. This gives a higher level of flexibility to service providers (which sophisticated service providers would take anyway). # Appendix 3: Job feedback status
# Appendix 3: Service provider discoverability | status | description |
|--------|-------------|
| `payment-required` | Service Provider requires payment before continuing. |
| `processing` | Service Provider is processing the job. |
| `error` | Service Provider was unable to process the job. |
| `success` | Service Provider successfully processed the job. |
| `failure` | Service Provider failed to process the job. |
| `partial` | Service Provider partially processed the job. The `.content` might include a sample of the partial results. |
Any job feedback event MIGHT include results in the `.content` field, as described in the [Job Result](#job-result) section. This is useful for service providers to provide a sample of the results that have been processed so far.
# Appendix 4: Service provider discoverability
Service Providers can use NIP-89 announcements to advertise their support for job kinds: Service Providers can use NIP-89 announcements to advertise their support for job kinds:
```json ```json
{ {
"kind": 31990, "kind": 31990,
"pubkey": <pubkey>, "pubkey": "<pubkey>",
"tags": [ "tags": [
[ "k", 65002 ], // e.g. speech-to-text [ "k", 65002 ], // e.g. speech-to-text
[ "t", "bitcoin" ] // e.g. optionally advertises it specializes in bitcoin audio transcription that won't confuse "Drivechains" with "Ridechains" [ "t", "bitcoin" ] // e.g. optionally advertises it specializes in bitcoin audio transcription that won't confuse "Drivechains" with "Ridechains"