nips/69.md
landonMutch a55a79e4e3
adjust poll format
-reorder, refine poll format
-modify TODOs
2023-03-02 14:05:49 +09:00

4.2 KiB

Poll event

A poll note is a nostr event type (kind 6969) for conducting valuation polls. A poll presents two or more voting options, which participants my vote on by sending zap events indicating a single chosen option. Poll results may be blinded, until after users have voted. Polls may specify a closing time, after which results should be unblinded, closed to new votes, and considered final. Polls may also specify a consensus threshold.

Purpose

The purpose of poll notes is to conduct quantitative public opinion polls over nostr by requiring voters pay to participate. By tying vote amounts and counts to real satoshi valuations, nostr polls intend to provide superior signal compared with other free polling models. Imposing real monetary costs on participants should also discourage attempts at fraudulent result manipulation, by automated or other means.

Poll format

A poll is a self-contained nostr event which MUST have a primary description along with a predefined number of voting options. A poll MUST include at least 2 unique voting options, and each option MUST contain a corresponding secondary description. A poll MUST specify a primary tally method (value or count) and SHOULD specify a closing_time. When specified, a closing_time MUST be greater than the created_at field. Polls MAY also include a consensus_threshold integar (0-100), representing a percentage threshold to achieve poll consensus.

{
  "id": <32-bytes lowercase hex-encoded sha256 of the the serialized event data>
  "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,
  "created_at": <unix timestamp in seconds>,
  "kind": 6969,
  "tags": [
    ["e", <32-bytes hex of the id of another event>, <recommended relay URL>],
    ["p", <32-bytes hex of the key>, <recommended relay URL>],
    ["poll_options": [
      ["0", <poll option 0 description string>],
      ["1", <poll option 1 description string>],
      ["n", <poll option n description string>],
    ],
    ["tally_method", "value"||"count"],
    ["consensus_threshold", <integar (0..100)>],
    ["closing_time", <unix timestamp in seconds>],
  ],
  "content": <primary poll description string>,
  "sig": <64-bytes hex of the signature of the sha256 hash of the serialized event data, which is the same as the "id" field>
}

Poll options are voted on by referencing a chosen option, using the poll_option tag, within zap events sent to the original poll note. poll_option tags MUST include exactly 1 option selected from the list of voting options, predefined in the original poll event.

Poll outcomes

Votes may be tallied either by value or by count. To avoid ambiguity of a winning outcome, a primary tally method MUST be specified as either value or count. When a count tally method is specified, only a single vote (the most recent) per unique voter MUST be included in the tally, zap amounts MUST be ignored, and anonymous zaps MUST NOT be counted.

If a closing time is specified, after it is passed, a poll should be unblinded publicly and MUST be treated as closed (late votes must not be tallied). Once closed, the option associated with either the most satoshis (value) or the most votes (counts), depending on tally method, MUST be treated as the winning option; while the distribution percentages across all vote options MUST be considered respresentative of the distribution of opinion amongst participants.

Additionally, if a consensus threshold percentage is specified, and any single option's associated value (or vote count) percentage of the poll's total value (or vote count, respectively) exceeds the consensus threshold, then consensus MUST be considered attained.

Strict adherence to these requirements should enable a formal means of quantitatively assessing the distribution of opinion regarding a poll's content amongst poll participants, determining a winning outcome, and possibly acheiving consensus. However, until this protocol is further tested, refined, and proven robust, polls should probably not be considered authoritative nor binding.

TODO

  • define standardized voting zap format
  • refine standardized polling format
  • send pull request (RFC) to nostr-protocol/NIPs
  • implement polls in 1 relay
  • implement polls in 2 clients
  • merge with nostr-protocol/NIPs