Elinor — protocol documentation

Elinor is a Telegram bot + Mini App that coordinates recurring community shifts (cooking, cleaning, …) for the Valley of the Commons. **All shift data lives on a public Nostr relay as standard NIP-52 calendar events** — the bot is just one client. Any agent can read the schedule, watch changes in real time, and sign people up by publishing ordinary Nostr events. This page documents everything needed to interoperate.

Connecting

Relay: wss://relay.commonshub.dev (strfry; open reads, open writes)
Coordinator (bot) pubkey: 3f432836bece7b0a06dcbaef023f113fdcb10f96fbf98f35dd2e3b3a3c0e2dcb

(npub18apjsd47eeas5pkuhthsy0c38lwtzrukl0uc7dwa9can50qw9h9s0n2qfd)

Timezone: all shift times are local Europe/Brussels; event timestamps are unix UTC.
Location: Valley of the Commons

Data model

Two event kinds, both addressable (NIP-01 kinds 30000–39999: for a given (kind, pubkey, d-tag) the relay keeps only the newest event — publishing a new version replaces the old one).

Every event identifier embeds a group id (the Telegram chat id of a community, a negative integer like -5343036390): each group is a fully independent calendar on the same relay.

Kind 31923 — shift occurrence (NIP-52 time-based calendar event)

One event per shift, per day, per group. Signed by the coordinator pubkey.


{
  "kind": 31923,
  "pubkey": "3f432836bece7b0a06dcbaef023f113fdcb10f96fbf98f35dd2e3b3a3c0e2dcb",
  "tags": [
    ["d", "shift-<groupId>-<YYYY-MM-DD>-<code>"],
    ["title", "Lunch Preparation"],
    ["start", "1782376200"],
    ["end", "1782383400"],
    ["start_tzid", "Europe/Brussels"],
    ["location", "Valley of the Commons"],
    ["capacity", "2"],
    ["t", "shift"],
    ["t", "<code>"],
    ["t", "group-<groupId>"]
  ],
  "content": "Lunch Preparation shift, 10:30–12:30 (Valley of the Commons) — optional description"
}

d — shift-<groupId>-<date>-<code>; code is a short slug per shift

type, [a-z0-9]{1,16} (defaults: mc Morning Cleaning, lp Lunch Preparation, lc Lunch Cleaning, dp Dinner Preparation, dc Dinner Cleaning).

start/end — unix seconds (UTC).
capacity — how many people the shift needs. Not enforced by the relay;

writers must check it (see Writing).

Occurrences are (re)published daily ~14 days ahead. Editing a shift's

definition republishes future occurrences with the same d tags.

Kind 31925 — signup (NIP-52 RSVP)

One event per person, per occurrence. Signed by the participant's key (the bot derives a keypair per Telegram user; external agents use their own key).


{
  "kind": 31925,
  "pubkey": "<participant pubkey>",
  "tags": [
    ["a", "31923:3f432836bece7b0a06dcbaef023f113fdcb10f96fbf98f35dd2e3b3a3c0e2dcb:shift-<groupId>-<date>-<code>"],
    ["d", "rsvp-<groupId>-<date>-<code>"],
    ["status", "accepted"],
    ["t", "shift"],
    ["p", "<actor pubkey>", "", "changed-by"]
  ],
  "content": ""
}

status — accepted (signed up) or declined (canceled). Canceling is

republishing the same d with declined — never deletion, so history and attribution survive.

["p", <pubkey>, "", "changed-by"] — optional; present when someone made

the change on the participant's behalf (anyone may — transparency, not permissions, is the governance model here).

Resolution rule

For any (author, a) pair, the event with the highest created_at wins; ties break to the lexically smallest id. A participant is on a shift iff their latest RSVP for it has status=accepted.

Reading

Who is signed up for one shift:


{"kinds": [31925], "#a": ["31923:3f432836bece7b0a06dcbaef023f113fdcb10f96fbf98f35dd2e3b3a3c0e2dcb:shift-<groupId>-<date>-<code>"]}

All shift occurrences of a group (next/past days):


{"kinds": [31923], "authors": ["3f432836bece7b0a06dcbaef023f113fdcb10f96fbf98f35dd2e3b3a3c0e2dcb"], "#t": ["group-<groupId>"]}

Everything one person signed up for:


{"kinds": [31925], "authors": ["<participant pubkey>"], "#t": ["shift"]}

Watch live changes: keep a subscription open on {"kinds": [31923, 31925]} (optionally filtered by #t: group-<groupId> for occurrences, or #a prefixes for RSVPs).

Discover groups: query the occurrences filter above without #t and collect the distinct group-* hashtags.

Writing

To sign someone up (or yourself — agents are welcome):

1. Read the occurrence (kind 31923) to get capacity, and the current RSVPs for its address; count accepted after applying the resolution rule. 2. If there is room, publish a kind 31925 as above with status=accepted. 3. created_at must be strictly greater than your previous RSVP for the same d, or the relay rejects it with "replaced: have newer event". 4. To cancel, republish with status=declined.

Caveats:

Capacity is cooperative — the relay does not enforce it. Check before you

write, and expect races to be rare but possible.

The Telegram app displays names only for participants it knows (people who

have interacted with the bot). An RSVP from an unknown pubkey is valid and counted, but shows without a name until the identity is introduced.

Do not publish kind 31923 under your own key — occurrences are only

authoritative from the coordinator pubkey above.

Calendar feeds (read-only convenience)

Per group: https://elinor.commonshub.dev/calendar/g/<token>.ics (token shared in the group)
Per person: https://elinor.commonshub.dev/calendar/u/<token>.ics
Single occurrence: https://elinor.commonshub.dev/calendar/event/<d-tag>.ics

Using the app

Telegram Mini App: https://t.me/ElinorOstromBot/shifts
Add the bot to a Telegram group: https://t.me/ElinorOstromBot — it seeds the

default shift catalog and posts an intro; /shifts shows the day's schedule.

This page: HTML · Markdown · machine index: llms.txt

Valley of the Commons · protocol docs · docs.md · llms.txt · relay: wss://relay.commonshub.dev