Finalize Draft

118.md

@@ -4,33 +4,86 @@
 
 `draft` `optional`
 
-The purpose of this nip is to create a mechanism for polling on nostr.
+This NIP defines the event scheme that describe Polls on nostr.
-The NIP aims to have the following properties.
 
-1. Provide a method for gauging eligibility. Only eligible votes should be counted.
+The NIP makes the following tradeoffs.
-2. Provide a method for maintaining anonymity. Participants should be able to not reveal their identities to everyone, yet their votes should be counted.
+
-3. Provide a mechanism for verifiability. Participants should be able to verify that their votes have been counted, under an eligibility criteria.
+1. All votes are public.
+2. All responses are editable (latest by timestamp considered last response)
 
 ## Events
 
 ### Poll Content
 
-The poll event is defined as a `kind:1068` event. This event carries over the `name` , `description` and `field` tags as defined in [nip-101](https://github.com/nostr-protocol/nips/pull/1190/files).
+The poll event is defined as a `kind:1068` event. Major tags in the poll event are:
-This event has no other tags and completely defines the poll content, which is uneditable.
+
+- **label**: The accompanying text of the poll.
+- **option**: The option tags contain an OptionId(any alphanumeric) field, followed by an option label field.
+- **relays**: Set of relays that the poll is expecting respondents to respond on.
+- **settings**: A JSON stringified object that may hold poll level configs and client specific configs.
+
+Example Event
+
+```json
+{
+  "content": "",
+  "created_at": 1719888496,
+  "id": "9d1b6b9562e66f2ecf35eb0a3c2decc736c47fddb13d6fb8f87185a153ea3634",
+  "kind": 1068,
+  "pubkey": "dee45a23c4f1d93f3a2043650c5081e4ac14a778e0acbef03de3768e4f81ac7b",
+  "sig": "7fa93bf3c430eaef784b0dacc217d3cd5eff1c520e7ef5d961381bc0f014dde6286618048d924808e54d1be03f2f2c2f0f8b5c9c2082a4480caf45a565ca9797",
+  "tags": [
+    ["label", "Pineapple on Pizza"],
+    ["option", "qj518h583", "Yay"],
+    ["option", "gga6cdnqj", "Nay"],
+    ["relays", "<relay1 url>", "<relay 2 url>"],
+    ["settings", "{\"PollType\": \"singlechoice\" }"]
+  ]
+}
+```
 
 ### Responses
 
-The response event is the same as the one on [nip-101](https://github.com/nostr-protocol/nips/pull/1190/files)
+The response event is a `kind:1018` event. It contains an e tag referencing the poll event it is referencing, followed by one or more response tags.
 
-### Eligibilty
+- **response** : The tag contains "response" as it's first positional argument followed by the option Id selected.
 
-Eligibility to a vote is determined by another `kind:30180` event that can be created by anyone and is essentially a reference to a list of pubkeys, the author of the eligibility event is interested in. The eligibility event MUST contain an "e" tag to the poll event, and
+Example Response Event
-"list" tags which references either a `kind:3` (contact list) or a `kind:30000`(follow sets) containing a list of "p" tags.
 
-### Counting Results.
+```json
+{
+  "content": "",
+  "created_at": 1720097117,
+  "id": "60a005e32e9596c3f544a841a9bc4e46d3020ca3650d6a739c95c1568e33f6d8",
+  "kind": 1018,
+  "pubkey": "1bc70a0148b3f316da33fe7e89f23e3e71ac4ff998027ec712b905cd24f6a411",
+  "sig": "30071a633c65db8f3a075c7a8de757fbd8ce65e3607f4ba287fe6d7fbf839a380f94ff4e826fbba593f6faaa13683b7ea9114ade140720ecf4927010ebf3e44f",
+  "tags": [
+    ["e", "1fc80cf813f1af33d5a435862b7ef7fb96b47e68a48f1abcadf8081f5a545550"],
+    ["response", "gga6cdnqj"]
+  ]
+}
+```
 
-Results can be counted for different eligibility events, by querying for `kind:1069` events only authored by the pubkeys mentioned in the eligibility event.
+### Poll Types
 
-### Anonymous Voting
+Poll Types can be configured in the settings object of the poll, the setting dictates how multiple response tags are handled in the `kind:1018` event.
 
-For people that wish to maintain anonymity, while still having their votes counted can do so by signing the response event with a random private key and sending over the corresponding pubkey to the author of a `kind:30180` eligibility event. The author of the eligibility event may demand "proofs of eligibility" before adding the pubkey in any of the lists.
+- **PollType: singlechoice**: The first response tag is to be considered the actual response.
+- **PollType: multiplechoice**: The first response tag pointing to each id is considered the actual response, without considering the order.
+- **PollType: rankedchoice**: The first response tag pointing to each id is the considered the actual response, while also taking into account the order of the response tags.
+
+### Counting Results
+
+Results can be queried by fetching `kind:1018` events from the relays specified in the poll.
+The results displayed should only be 1 vote per pubkey.
+In case of multiple events for a pubkey, the event with the largest timestamp should be considered.
+
+### Curation
+
+The clients may configure fetching results by specific people. This can be achieved by creating `kind:30000` follow sets, and fetching results only from the follow set.
+Clients can also employ other curation algorithms, like Proof Of Work and Web of Trust scores for result curations.
+
+### Private Polls
+
+This nip does not cover private polling, Clients may follow [forms nip](https://github.com/nostr-protocol/nips/pull/1190) for private polling.