nips/41.md

NIP-41
======

# Surveys / polls / quizzes
-----------------------------------

`draft` `optional` `require:nip-13` `require:nip-57`  `author:fernandolguevara`

The `surv` tag & `surv-answer` (kind: `30041`) enables users to have surveys/polls/quizzes experiences on the network.

## Spec

### surv

To start a survey on the network, an event with one or many 'surv' tags may be created.

```json
{"tags":[
  ["surv", "{single|multiple}", "ttl", "(label)", "option 1", "option 2", "option 3", "option 4"]
  ["nonce", "1", "32"]
  ["amount", "milli-satoshi value"]
]}
```

#### tags
- `surv`:
  - `{single|multiple}`: allow others to reply with single or multiple choice.
  - `ttl:unix-time`: when survey expires, `0` don't expire.
  - `(label):string`: if present, clients should use it as surv label.
  - `option:string`: survey options 
- `nonce`: if present, pow is mandatory for answer. ref: [13](13.md)
- `amount`: if present, zap is mandatory for answer. ref: [57](57.md)

### surv-answer

To reply to a survey on the network, an event of kind `30041` is created.

```meta
["surv-answer", "surv-index", "option-index", ...]
```

```json
{
  "kind": 30041,
  "tags":[
    ["e", "<event-id-root>", "wss://...", "root"]
    ["d", "surv-answer/{event-id-root}"]
    ["surv-answer", "0", "option-index:int", "{...}"]
    ["nonce", "1", "32"],
    ["amount", "milli-satoshi value"],
  ]
}
```
at least one selected option index should present on the answer event the tag `surv-answer`

tags:
 - `e`: `<event-id-root>` origin event.
 - `d`: the value should be an string formed using origin `event-id-root` for the survey.
 - `surv-answer`:
   - `surv-index:int`: starting at 0.
   - `option-index:int`: starting at 0.
 - `nonce`: if present, pow is mandatory for answer.
 - `amount`: if present, zap is mandatory for answer.


## Relay and client recommendations
- `surv` tag:
  - Should have at least `two` options.
  - The value of the `label` field should allow enough characters to express the questions.
  - The `options` items should be limited up to 4.
  - Each `option` should be 25 chars limited.

## Examples

### Example surv single

```json
{
  "pubkey": "<pub-key>",
  "created_at": 1000000000,
  "kind": 1,
  "tags": [
    ["t", "hastag"],
    ["surv", "single", "0", "", "option 1", "option 2", "options 3"],
  ],
  "content": "#hastag what is your favorite option?",
  "id": "<event-id>"
},
{
  "pubkey": "<pub-key>",
  "created_at": 1000000000,
  "kind": 30041,
  "tags": [
    ["e", "<event-id-root>", "wss://...", "root"],
    ["t", "tag"],
    ["surv-answer", "", "0"]
  ],
  "content": "here my favorite option is #option1 \n",
  "id": "<event-id>"
}
```

### Example surv multiple with expiration

```json
{
  "pubkey": "<pub-key>",
  "created_at": 1000000000,
  "kind": 1,
  "tags": [
    ["t", "hastag"],
    ["surv", "multiple", "1684599600"],
    ["options", "option 1", "option 2", "options 3"],
  ],
  "content": "#hastag what are your favorite options?",
  "id": "<event-id>"
},
{
  "pubkey": "<pub-key>",
  "created_at": 1000000000,
  "kind": 30041,
  "tags": [
    ["e", "<event-id-root>", "wss://...", "root"],
    ["t", "tag"],
    ["surv-answer", "", "0", "2"]
  ],
  "content": "here my favorite option is #option1 \n",
  "id": "<event-id>"
}
```
### Example multiple surv 

```json
{
  "pubkey": "<pub-key>",
  "created_at": 1000000000,
  "kind": 1,
  "tags": [
    ["t", "hastag"],
    ["surv", "single", "0", "surv 1?", "option 1", "option 2", "options 3"],
    ["surv", "multiple", "0", "surv 2?", "option 1", "option 2", "options 3"],
  ],
  "content": "#hastag Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do?",
  "id": "<event-id>"
},
{
  "pubkey": "<pub-key>",
  "created_at": 1000000000,
  "kind": 30041,
  "tags": [
    ["e", "<event-id-root>", "wss://...", "root"],
    ["surv-answer", "0", "0"]
    ["surv-answer", "1", "0", "2"]
  ],
  "content": "quis nostrud exercitation ullamco laboris!\n",
  "id": "<event-id>"
}
```