Skip to content

Commit 43d1ce3

Browse files
wpfleger96npub16v54tttfqacx9ycvc3k0ut0npj564ahcuajzy6qjvh57ntmsf4uq4806j2
andauthored
docs(nip-rs): add optional thread read context scheme (#1006)
Signed-off-by: Will Pfleger <[email protected]> Co-authored-by: npub16v54tttfqacx9ycvc3k0ut0npj564ahcuajzy6qjvh57ntmsf4uq4806j2 <d32955ad69077062930cc46cfe2df30ca9aaf6f8e76422681265e9e9af704d78@sprout-oss.stage.blox.sqprod.co>
1 parent 1243307 commit 43d1ce3

1 file changed

Lines changed: 128 additions & 1 deletion

File tree

‎docs/nips/NIP-RS.md‎

Lines changed: 128 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ This NIP defines a minimal, privacy-preserving protocol for propagating read sta
2525
## Non-Goals
2626

2727
This NIP does not define a durable log of all read messages — blobs are best-effort recent activity hints bounded by a time horizon.
28-
This NIP does not define cross-client interoperability on context ID format — context identifiers are opaque to this NIP and meaningful only within a single client family.
28+
This NIP does not define cross-client interoperability on context ID format — context identifiers are opaque by default and meaningful only within a single client family, except for OPTIONAL well-known schemes defined in this NIP (currently only `thread:<root-event-id>`, defined under Thread Read Contexts), which are provided for cross-client thread-read interoperability.
2929
This NIP does not define mark-as-unread — the merge rule is monotonic by design.
3030
This NIP does not guarantee ordering of read events across devices.
3131
This NIP does not require relay-side logic.
@@ -112,6 +112,133 @@ After decryption, clients MUST apply the following validation rules:
112112

113113
Context identifier format is not prescribed by this NIP. Clients choose identifiers appropriate to their context type (e.g., a NIP-28 channel event ID, a NIP-29 group address, a pubkey for DMs). Interoperability between different client implementations on context ID conventions is outside the scope of this NIP.
114114

115+
#### Thread Read Contexts (Optional)
116+
117+
This subsection defines an OPTIONAL well-known context scheme for tracking read
118+
state of threads (reply chains) independently from the channel they belong to.
119+
It is a pure interpretation layer over the flat `contexts` map — it introduces
120+
no new fields, no nesting, and no change to the merge rule, event structure,
121+
validation, or fetching. The schema version `v` remains `1`. Clients that do
122+
not implement this subsection remain fully interoperable (see Backwards
123+
Compatibility below).
124+
125+
A client implementing this scheme MUST use the context key `thread:<root-event-id>`
126+
for a thread, where `<root-event-id>` is the 64-character lowercase hex event ID
127+
of the thread's root event. A bare channel identifier (e.g., the NIP-28 channel
128+
event ID) remains the channel context, exactly as before — this is grandfathered
129+
existing behavior and is unchanged.
130+
131+
Keys beginning with `thread:` whose remainder does not match `^[0-9a-f]{64}$`
132+
MUST be treated as ordinary opaque contexts, not as thread contexts. This
133+
protects an existing client family that may already use a `thread:`-prefixed
134+
convention from being misinterpreted under this scheme.
135+
136+
The relationship between a thread and its parent channel is DERIVED from the
137+
Nostr event graph at evaluation time (the root event's channel reference, e.g.
138+
its `h` tag) and MUST NOT be serialized into the blob. The blob remains a flat
139+
`{<context-id>: <unix-timestamp>}` map.
140+
141+
##### Hierarchical Frontier Rule
142+
143+
The effective read frontier of a context is the maximum of its own merged
144+
timestamp and the effective frontier of its parent:
145+
146+
```
147+
effective(ctx) = max(merged[ctx], effective(parent(ctx)))
148+
```
149+
150+
A channel has no parent, so its effective frontier is simply its own merged
151+
value. For a thread, the parent is its channel:
152+
153+
```
154+
effective(thread:<root>) = max(merged[thread:<root>], merged[<channelId>])
155+
```
156+
157+
A thread is unread iff `latestReplyAt > effective(thread:<root>)`, where
158+
`latestReplyAt` is the `created_at` of the thread's most recent reply. Because
159+
this rule is a `max()` over the same grow-only registers defined in the Merge
160+
Rule, it remains a monotone state-based CvRDT — no change to the merge rule is
161+
required. Marking a channel read therefore clears unread state on all of its
162+
threads for free, since each thread's effective frontier inherits the channel
163+
term.
164+
165+
If the thread root event (and therefore its parent channel) cannot be resolved
166+
from the event graph, `effective(thread:<root>)` degrades to
167+
`merged[thread:<root>]` alone.
168+
169+
##### Write Discipline
170+
171+
Marking a thread read MUST advance only its own `thread:<root>` context. It MUST
172+
NOT advance the parent channel context. Otherwise, reading a single thread would
173+
silently mark later top-level channel messages as read. Marking a channel read
174+
advances only the channel context (which the hierarchical rule then propagates
175+
to threads at read time). Because the channel frontier is the parent term for
176+
every thread, marking a channel read SHOULD advance the channel context to the
177+
maximum `created_at` across all messages in the channel, including thread
178+
replies — otherwise threads whose `latestReplyAt` exceeds the newest top-level
179+
message remain unread and the channel read does not clear them.
180+
181+
##### Eviction
182+
183+
A `thread:<root>` entry whose value is `<= effective(parent)` is semantically
184+
inert: the parent (channel) frontier already covers it, so its presence or
185+
absence does not change the result of `effective(thread:<root>)`. Clients MAY
186+
drop such dominated entries before publishing to bound blob size, consistent
187+
with the Debounce and Pruning section.
188+
189+
This eviction is bounded best-effort, NOT a guaranteed garbage-collection or
190+
per-key tombstone mechanism. Because the merge rule re-merges any context
191+
present in another instance's blob (see Merge Rule and Live Subscription and
192+
Convergence), a dropped `thread:<root>` key MAY be re-added by a peer instance
193+
that still carries it. A dropped key stays gone only once it is dominated on
194+
every instance or has aged past the time horizon everywhere. Clients SHOULD
195+
treat thread-context eviction as a companion to the existing time-horizon
196+
pruning, not as a standalone guarantee that the context count or blob size will
197+
shrink immediately.
198+
199+
To avoid a re-publish loop with peers that still carry an evicted key, an
200+
incoming context entry whose value is `<= effective(parent(ctx))` MUST NOT by
201+
itself trigger a re-publish. Clients SHOULD evaluate the Live Subscription
202+
re-publish trigger and the suppression comparison (Live Subscription and
203+
Convergence rules 2–3) AFTER applying their eviction policy, so that re-merging
204+
a dominated key a peer still carries does not force a write that changes nothing
205+
semantically. This is backwards-safe: it only suppresses writes with no semantic
206+
effect.
207+
208+
##### Backwards Compatibility
209+
210+
A client that does not implement this scheme treats a `thread:<root>` key as an
211+
ordinary opaque context. It carries the key through the merge unchanged (already
212+
required by the Merge Rule) and simply computes no thread-level unread state.
213+
There is no validation change and no interop break: an unaware client and an
214+
aware client can share a blob and both produce correct results for the contexts
215+
they understand.
216+
217+
##### Example
218+
219+
Two blobs merge to the following effective state for a thread `X` and its parent
220+
channel:
221+
222+
```json
223+
{
224+
"thread:X": 100,
225+
"<channelId>": 150
226+
}
227+
```
228+
229+
The thread's effective frontier is computed through the channel parent term:
230+
231+
```
232+
effective(thread:X) = max(merged[thread:X], merged[<channelId>])
233+
= max(100, 150) = 150
234+
```
235+
236+
A thread reply with `created_at = 140` is `<= 150`, so it reads as **read** (the
237+
channel frontier already covers it). A reply with `created_at = 160` is `> 150`,
238+
so the thread reads as **unread**. The thread's own entry (`100`) is dominated by
239+
the channel frontier (`150`) and is therefore inert — a client MAY evict it
240+
before publishing.
241+
115242
#### Timestamp Accuracy
116243

117244
Clients SHOULD use the `created_at` of the message being marked as read as the context timestamp — not the local wall clock and not the relay receive time.

0 commit comments

Comments
 (0)