NIP-29: add subgroups spec

[Anderson-Juhasc]

Adds a Subgroups section to NIP-29, letting groups be organized hierarchically. No new kinds: it reuses kind:39000/kind:9002 and adds two tag names, parent and child.

• A parent tag on kind:39000 points at the parent's d identifier; no parent (or an empty one) means the group is a root. Clients build the tree locally from kind:39000 events.
• Parenting, re-parenting and promotion to root all happen via kind:9002 (edit-metadata). The relay updates the group's kind:39000 and keeps both sides in sync: it adds/removes the matching child tag on the parent (and on the previous parent when moving).
• The parent's kind:39000 MUST list every child as an ordered ["child", "<id>"] tag; relays reject metadata edits that drop existing children. Order is the tag position; admins can rearrange it.
• Relationships are relay-enforced, not client-negotiated: a kind:9002 setting ["parent", "X"] is rejected unless the author is an admin of X as well (per X's kind:39001). Editing the child already requires admin on the child, so both sides must consent.
• Relays MUST reject cycles (including self-reference) and reject a parent pointing at a group that doesn't exist on the relay. When a parent is deleted (kind:9008), its remaining children automatically become roots.
• Membership and admin roles are fully independent per group: nothing is inherited across the parent-child link. A relay MAY emit its own kind:9000/kind:9001 to cascade members, but clients MUST NOT assume it.
• The tree is scoped to a single relay; across relays, the kind:39000 from the relay serving the group is authoritative. Relays advertise subgroup support via NIP-11 (nip29: { subgroups: true }).
• Migration is incremental: an existing group becomes a subgroup just by an admin editing its metadata to add a parent; historical events under its h tag stay valid.

[staab]

The deletion behavior is going to be confusing for users who use a client that doesn't have subgroups (because they don't see the hierarchy), and won't be actionable for them. I would prefer orphan sub groups to this (and cascading, yeesh). If parent is invalid, the group is not a sub-group. This is a case clients will have to cover anyway, because they might not have a complete list of group events at any given time.

I also don't think implicit membership inheritance is a good idea. I'm working on this here at a relay level, which has the same problem. Policy inheritance should be explicit — since the relay is the one enforcing the policy, if it wants to cascade membership it should update sub-groups to match parent groups instead of expecting clients to infer it (which clients that don't support sub-groups won't).

I think this PR is too complex (just because of the nature of the problem), and something more laissez faire would be better. For example:

39000 events MAY include a `parent` tag. Clients MAY display groups in a hierarchy. Relays MAY implement whatever policy they want for nested groups.

[Anderson-Juhasc]

That makes sense @staab, I'll simplify it.

[Anderson-Juhasc]

@staab I think it's following your recommendations now, but one point I'm a little unsure about is how to identify if the relay supports subgroups, maybe using something like this in nip-11:
"nip29": { "subgroups": true }
Any ideas?

[fiatjaf]

I didn't read the original proposal, but I like the way it is now.

[Anderson-Juhasc]

Another point is how to prevent groups from becoming children without the parent group's permission. Any ideas, @staab, @fiatjaf?

Something like the following might solve the problem, what do you think?

To require explicit approval from the parent: the parent admin issues a kind:9002 event on the parent with a tag of type ["allow-child", ""] or a new event of type kind:9010 adopt-child. Relay only accepts parent: Y in X if there is prior consent from Y.

[staab]

Much better.

how to identify if the relay supports subgroups

I don't know that it should. NIP 29 in the supported_nips field should be enough; relays that don't support sub-groups should ignore instead of reject parent tags. Required logic should be handled by clients; relays can augment them with additional policy. This is the only way to get full compatibility. Which means this NIP has to fully define parent tag semantics when relays don't support it at all.

Another point is how to prevent groups from becoming children without the parent group's permission.

You're right, this is annoying. Probably leave this up to the relay. I could see this being handled in a few ways:

• The relay auto-updates the child group's permissions/ownership to match the parent. The original sub-group admin would be basically donating its group to the parent's admin.
• Leave permissions alone, and just live with weird hierarchies. Probably bad.
• Don't allow moving groups; force delete/re-create. Only group admins can create child groups.

None of these is very satisfying to me.

[staab]

Admins creating or re-parenting subgroups probe by attempting the kind:9002 event — a relay that does not implement subgroups rejects it via the OK response.

I don't think you can rely on relays not supporting this part of the spec to detect/reject this.

[staab]

Probably SHOULD, current implementations won't do this.

[1amKhush]

@staab @Anderson-Juhasc Was reading through the thread, had a few suggestions;

• Imo parent consent and ownership transfer should be stated as relay policy, not a protocol-level guarantee.
• Also client fallback should be explicit, so if a parent is missing, unknown, or cyclic in the client’s current view - render that group as a root until the graph becomes consistent.
• Support detection should come from observed 39000 parent metadata, not from expecting a relay to reject 9002 edits, since some relays may ignore unsupported subgroup behavior (though i think this one was pointed out earlier).

[luthen-seas]

Spec text looks sound and backwards-compat is clean — zero new kinds, four new tag names (parent, child, closed-children, open-children) all currently unused elsewhere in the registry. The v2 simplification (orphan handling delegated to clients, support self-advertised via observed parent tags) is the right call.

Three small non-blocking suggestions:

1. Replacement-on-touch on child is a real footgun. "If any child tag is present, the relay SHOULD replace the parent's full child list" — a client adding one child must re-send every existing one or silently drop them. This is materially different from how clients usually treat tags. Worth an explicit implementation note plus a worked "add-one-child" example so tooling authors don't get bitten.

2. ["closed-children"] with no child tags = "accepts no children" is correct but easy to misread. A reader can plausibly parse it as "the list is sealed but existing entries remain legitimate," which is the opposite of the intended semantics. A short worked example of a parent that refuses all children would remove the ambiguity.

3. Cross-relay tiebreaker is circular. "When aggregating across relays … the kind:39000 from the relay currently serving the group's events is authoritative" — but a client in discovery mode usually doesn't know which relay is "currently serving." Suggest a deterministic fallback: prefer the most recent created_at for the same d, ties broken by the user's relay preference order from kind:10002.

One nit: parent is a generic token in a global tag namespace. NIP-29's h-scoping contains the collision risk, but a more specific name (e.g. g or parent-h) would future-proof against another NIP reaching for parent in a different domain. Acceptable as-is.

On interop: the subgroups feature is unimplemented today since it's brand new, and broader NIP-29 support outside of pippellia-btc/relay29 is still thin across the libraries and relays I've looked at. Worth tracking adoption alongside merge.

[Anderson-Juhasc]

@luthen-seas I implemented it in this relay: fiatjaf/relay29#21 and in this client https://web.nostrord.com/ behind an experimental toggle.

[luthen-seas]

Thanks @Anderson-Juhasc — that updates my interop point. The relay29 PR's integration suite khatru29/subgroups_test.go covers the parts I'd most want a reference implementation to nail down: cycle rejection at both RejectEvent and on startup replay against DB-planted rogue events, the replacement-on-touch child semantics (including the bare ["child"] clear marker), admin attestation round-trip, and parent-deletion → child promotion. With that plus the nostrord client behind a flag, the "≥2 client + ≥1 relay" framing is on much firmer ground than I gave it credit for.

Will keep an eye on the thread.

[fiatjaf]

Removed some text, there was too much. Rewrote some of the AI output to be more succinct. And made the "child" tags mandatory and enforced by the relay.

Looks good to me now.

[Anderson-Juhasc]

Excellent, well-crafted @fiatjaf!

[staab]

I'm happy with this.

[fiatjaf]

I really don't understand why you use the word "reparenting" here so much. Is this a term an LLM came up with? I don't know what it means. Is it for when you have a child but then you don't have anymore and then you adopt that child again? I don't see why this should be in the spec. "adopting" would be enough and more generic.

Also this last commit breaks things again. If you want to remove a parent you should just send an "edit-metadata" without any parent (since the "edit-metadata" overwrites all the group metadata), the ["parent", ""] syntax is unnecessary and ambiguous.

[Anderson-Juhasc]

I understood. “Reparenting” was a term suggested by LLM. I was trying to avoid sending all the tags to make the edits. But since kind:9002 includes all tags it doesn't make sense.

[fiatjaf]

Yeah, initially kind:9002 was supposed to only send the deltas, but @staab decided that it shouldn't be like that so we have to follow him. It is simpler this way.

[fiatjaf]

I was going to merge this and tried to fix the conflicts using the GitHub interface but I think I broke everything. Can you check, @Anderson-Juhasc?

[Anderson-Juhasc]

Implemented in https://gitworkshop.dev/fiatjaf.com/gitnostr.com/croissant/prs/nevent1qyf8wumn8ghj7emfw3hx7um5wghxxmmdqqs9jwwpck4hta052kw8sxe6m90lleqh4l64dv8asg494e3wvjpegtgfhm7e8