Poll event

draft optional author:toadlyBroodle

A poll note is a nostr event (kind 6969) for conducting paid polls. A poll presents two or more voting options, which participants my vote on by sending regular zap events which include an additional poll_option vote tag. Poll results may be blinded, until after users have voted. Polls may specify a closed_at time, after which results should be unblinded, closed to new votes, and the tally considered final. Poll options may be tallied by either satoshi value or vote count. Polls may additionally specify a value_minimum to include votes in the tally and a consensus_threshold for assessing the state of consensus.

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 to 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 event:

MUST contain a primary description string, specified in the content field
MUST contain a predefined list of voting options, defined in a poll_options tag
MUST include at least 2 voting options, each with its own unique description string
MUST specify a primary tally_method: either value OR count
SHOULD specify a closed_at time:
- a closed_at value of less than or equal to the created_at field indicates a poll SHOULD NOT be closed.
MAY specify a value_minimum satoshi value for zapped votes to be included in the tally
MAY include a consensus_threshold (0-100), representing a percentage threshold for any single vote option to achieve poll consensus
- a consensus_threshold of '0' indicates no threshold is specified.

{
  "id": <32-bytes lowercase hex-encoded sha256 of 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"],
    ["value_minimum", "minimum zap value to vote"],
    ["consensus_threshold", "required percentage to attain consensus <0..100>"],
    ["closed_at", "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>
}

Zap vote format

Poll options are voted on by sending zap events (to the original poll event) which include 1 additional poll_option tag in the zap request event.

The zap request event (kind 9734):

MUST include exactly 1 poll_option tag
MUST reference the vote option by its corresponding integer n, chosen from the original poll event's list of predefined polling_options

"tags": [
  ...
  ["poll_option", "n"],
  ...
]

Poll outcome

To avoid ambiguity of results, strict adherence to the following rules is vital when tallying and rendering poll outcomes.

A tallying client:

MUST clearly indicate the tally_method and value_minimum (if specified) to potential participants before vote submission
MUST tally poll results according to the primary tally_method specified:
when tallying by value, clients:
- MUST include full satoshi values from all relevant zap events
- MUST include multiple zap events from single users
- MUST treat the vote option with the highest satoshi value as the winning option
when tallying by count, clients:
- MUST ONLY count the most recent zap from a unique user as 1 vote
- MUST NOT include zapped satoshi values in the tally
- MUST NOT count votes from anonymous users
- MUST treat the vote option with the most unique votes as the winning option
if a value_minimum is specified, clients:
- MUST ONLY include zaps exceeding the satoshi value_minimum in the tally
when a closed_at time is specified, clients:
- MUST NOT include late votes received after closed_at time
- SHOULD publicly blind results until after a user's vote has been received
- SHOULD publicly display results after the closed_at time has passed
when a closed_at time is NOT specified (is less than or equal to created_at), clients:
- SHOULD include all votes in tallies
- SHOULD treat the most recent tally as the definitive outcome

After the above rules are applied and clearly rendered, a tallying client:

MUST display the distribution percentages, from the total, for each vote option
if a non-zero consensus_threshold is specified, clients:
- MUST indicate the state of consensus by displaying its value relative to the final percentage of the winning vote
MAY display the secondary tally method result, for statistical purposes, along with other associated poll metrics and comments

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

TODO

refine NIP#69 based RFC feedback
implement polls in 1 relay
implement polls in 2 clients
merge with nostr-protocol/NIPs

5.7 KiB Raw Blame History