15514283f3
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.
2.3 KiB
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.