NIP-20: Command Results

When submitting events to relays, clients currently have no way to know
if an event was successfully committed to the database. This NIP
introduces the concept of command results which are like NOTICE's except
provide more information about if an event was accepted or rejected.

20.md

@@ -0,0 +1,63 @@
+NIP-20
+======
+
+
+Command Results
+---------------
+
+`draft` `optional` `author:jb55`
+
+When submitting events to relays, clients currently have no way to know if an event was successfully committed to the database. This NIP introduces the concept of command results which are like NOTICE's except provide more information about if an event was accepted or rejected.
+
+A command result is a JSON object with the following structure that is returned when an event is successfully saved to the database or rejected:
+
+    ["OK", <event_id>, <true|false>, <message>]
+
+Relays MUST return `true` when the event is a duplicate and has already been saved. The `message` SHOULD start with `duplicate:` in this case.
+
+Relays MUST return `false` when the event was rejected and not saved.
+
+The `message` SHOULD provide additional information as to why the command succeeded or failed.
+
+The `message` SHOULD start with `blocked:` if the pubkey or network address has been blocked, banned or is not on a whitelist.
+
+The `message` SHOULD start with `rate-limited:` if the event was rejected due to rate limiting techniques.
+
+Ephemeral events are not acknowledged with OK responses, unless there is a failure.
+
+If the event is malformed and could not be parsed, a NOTICE message SHOULD be used instead of a command result.
+
+
+Examples
+--------
+
+Event successfully written to the database:
+
+    ["OK", "b1a649ebe8b435ec71d3784793f3bbf4b93e64e17568a741aecd4c7ddeafce30", true, ""]
+
+Event successfully written to the database because of a reason:
+
+    ["OK", "b1a649ebe8b435ec71d3784793f3bbf4b93e64e17568a741aecd4c7ddeafce30", true, "pow: difficulty 25>=24"]
+
+Event blocked due to ip filter
+
+    ["OK", "b1a649ebe8...", false, "blocked: tor exit nodes not allowed"]
+
+Event blocked due to pubkey ban
+
+    ["OK", "b1a649ebe8...", false, "blocked: you are banned from posting here"]
+
+Event blocked, pubkey not registered
+
+    ["OK", "b1a649ebe8...", false, "blocked: please register your pubkey at https://my-expensive-relay.example.com"]
+
+Event rejected, rate limited
+
+    ["OK", "b1a649ebe8...", false, "rate-limited: slow down there chief"]
+
+
+
+Future Extensions
+-----------------
+
+This proposal SHOULD be extended to support futher commands in the future, such as REQ and AUTH. They are left out of this initial version to keep things simpler.

README.md

@@ -18,6 +18,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
 - [NIP-14: Subject tag in text events.](14.md)
 - [NIP-15: End of Stored Events Notice](15.md)
 - [NIP-16: Event Treatment](16.md)
+- [NIP-20: Command Results](20.md)
 - [NIP-22: Event created_at Limits](22.md)
 - [NIP-25: Reactions](25.md)
 - [NIP-28: Public Chat](28.md)
@@ -58,6 +59,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
 | EVENT  | used to send events requested to clients                | [1](01.md)  |
 | NOTICE | used to send human-readable messages to clients         | [1](01.md)  |
 | EOSE   | used to notify clients all stored events have been sent | [15](15.md) |
+| OK     | used to notify clients if an EVENT was successuful      | [20](20.md) |
 
 Please update these lists when proposing NIPs introducing new event kinds.