buzz/docs/nips/NIP-CL.md

NIP-CL

Channel Identity and Discovery

draft optional relay

This NIP adds identity facts to the relay-signed NIP-29 channel-state events (kinds 39000–39002). With these facts, a client can find channels with ordinary NIP-01 filters. It needs no new filter key and no relay-specific API.

Motivation

Plugins and agents often create a channel for their own use and must find it again later, for example "the config channel that this agent created". With plain NIP-29, a client cannot:

• tell who created a channel;
• read the channel type from any event except kind:39000; or
• tell which of two channels is older. The created_at of a kind:39000 event is the time of the last edit, not the time of creation.

A client also cannot mark its own channels so that it can find them again. Channel labels (below) do this.

Also, every channel that a person belongs to shows in their client as a chat. So a group that exists only to control who can read some data appears in sidebars, search results and unread counts. System channels (below) fix this.

Channel identity tags

On every channel-state event that the relay signs, the relay MUST put these tags in this order, before any other t or P tag:

1. ["t", <channel type>], for example stream, forum, dm, workflow, system.
2. ["t", <label>] for each channel label, in stored order (see Channel labels).
3. ["P", <creator public key, hex>].

kind:39000 also carries ["created_at", <unix seconds>].

Example kind:39000 (signing fields and unrelated tags omitted):

{
  "kind": 39000,
  "pubkey": "<relay public key>",
  "created_at": 1760025600,
  "tags": [
    ["d", "9b353519-f4fe-4757-aef4-bec6cc0ae54c"],
    ["name", "agent-config"],
    ["t", "stream"],
    ["t", "agent-config"],
    ["P", "<creator public key>"],
    ["created_at", "1759939200"]
  ]
}

Tag	Kinds	Meaning
first t	39000–39002	Channel type.
later t	39000–39002	Channel labels.
P	39000–39002	Public key that signed the kind:9007 that created the channel.
created_at	39000	Time the channel was created, in unix seconds, as a decimal string.

Channel type. Clients MUST read the channel type from the first t tag. Later t tags are labels.

Creator. The relay writes P from its own record of the kind:9007 that created the channel. No client can set it. It does not change when ownership moves to another member or when the channel is edited.

Uppercase P follows NIP-22, NIP-34 and NIP-72, where P names the author of the root object. On these kinds, lowercase p already lists members, admins and DM participants. A filter matches tag values, not their roles, so #p would mix creators with members.

Creation time. The created_at tag does not change when the channel is edited. Use it, not the event's created_at, to compare the age of channels.

Older events. A relay adds these tags only when it publishes a channel-state event. An event that a relay version without this NIP published can lack them, including one published during an upgrade. Such an event stays until the channel next changes, for example on an edit or a membership change. A client MUST treat a missing tag as unknown. A missing P does not mean that a key did not create the channel.

Channel labels

A label groups channels across channel types, for example workspace or agent-config. Labels have no meaning to the relay.

Set labels. A kind:9007 (create group) MAY carry up to 8 distinct labels as ["t", <label>] tags. On kind:9002 (edit metadata):

• t tags replace the whole label set;
• ["t", ""] tags and no other t tag clear the set;
• no t tag leaves the labels as they are.

Only an owner or admin of the channel MAY change its labels.

Rules. A label is 1–64 characters from a-z, 0-9, ., : and -. A label MUST NOT be stream, forum, dm, workflow or system. These are channel type names, so this rule stops a label from making a channel look like another type. The relay MUST reject the whole event if it has more than 8 distinct labels, an invalid label, a reserved name, or ["t", ""] together with other labels. The relay stores repeated labels once, so a repeat does not count toward the 8, and repeated ["t", ""] tags clear the set like one.

Finding channels

Use ordinary NIP-01 filters on the channel-state kinds.

To find	Filter
Channels that a key created	{"kinds": [39000], "#P": ["<creator>"]}
Channels with a label	{"kinds": [39000], "#t": ["<label>"]}
One creator's channels with a label	{"kinds": [39000], "#P": ["<creator>"], "#t": ["<label>"]}
Channels of one type	{"kinds": [39000], "#t": ["<type>"]}

A #P filter does not return a channel whose events lack P (see Older events). So it can miss channels that a key created before the relay supported this NIP.

Values in one tag filter combine with OR, as in NIP-01. So "#t": ["workspace", "notes"] finds channels with either label. To require a label and a creator, use #t and #P together.

The relay MUST match #t and #P before it applies limit, as NIP-01 requires. A relay that reads the newest channel events first and matches tags after can return a short or empty page while matching channels exist.

Choosing one channel

The relay does not make labels unique. Many channels can share a label, and any owner or admin can set any label. So two creates for the same label can both succeed, for example when two processes of one agent start at the same time.

A client that needs one channel per creator and label:

1. queries {"kinds": [39000], "#P": ["<creator>"], "#t": ["<label>"]};
2. creates the channel only if the query returns nothing; and
3. when the query returns more than one channel, uses the oldest one.

The oldest channel has the lowest created_at tag value, compared as an integer. If two channels have the same value, the lowest channel ID (d tag, compared as a string) wins. A channel without a created_at tag ranks after every channel that has one, and two channels without one compare by channel ID. Every reader that follows this rule picks the same channel, even after either channel is edited.

System channels

A system channel exists only to control who can read some data, for example config that only an agent and its owner can read. It has the channel type system. In every other way it is an ordinary channel: it has members, roles, messages and labels.

Create. A kind:9007 with ["channel_type", "system"] creates a system channel. It is private unless the kind:9007 also has ["visibility", "open"].

Hidden. While a system channel is private, its kind:39000 carries the NIP-29 hidden tag.

Reads that leave system channels out

The relay leaves system channels out of every read that does not name them. Clients that do not know about system channels then stay correct with no change.

A client sees a channel only if it knows the channel's type. A read that does not name a channel returns only the legacy types: stream, forum, dm and workflow, the types that every client knew before this NIP. This list is frozen. The relay leaves out every other type, so a channel type added later is also hidden from clients that do not know it. A filter that names such a channel (see below) reads it under the ordinary rules, and no other filter in the same request gains it. The opt-in in "Asking for system channels" (#t:["system"] or #P) adds system channels only, never a channel of another type. Each new type needs its own way to ask for all its channels. This applies to:

• a filter without #h, for example the channels or messages a reader can see;
• kind:39002 #p:["<reader>"], the channels a reader belongs to;
• COUNT and NIP-50 search; and
• any relay-specific query API that does the same reads.

A filter names a channel when it has the channel ID in #h, or in #d on a filter whose kinds are all 39000–39003. This is the same for a system channel and for a type added later. Then the ordinary read rules apply: the reader can read the channel if they are a member or if it is open. A client that has the ID, for example from a link, can open the channel. Thus a system channel stays an ordinary NIP-29 group.

The relay decides this for each filter. A filter that names a channel does not add it to another filter in the same request.

Push notifications (NIP-PL) use the same rule. A lease filter wakes its author for an event in a system channel or a channel of a type added later only when the filter names that channel. A lease filter cannot have #t or #P, so here "names" means #h. The relay still checks that the author can read the event, as for every other channel.

Membership notices carry the channel type

Every kind:44100 (added) and kind:44101 (removed) notice has one more tag, ["t", <channel_type>], for example ["t", "stream"] or ["t", "system"]. The relay sets it from the channel type when it sends the notice. A channel's type does not change. The relay stores the notice like any other 44100/44101.

A client sees a notice only if it knows the notice's channel type. Old clients do not know types added later, such as system, and would show the channel from such a notice. So the relay MUST apply this rule:

• A filter with #t matches a notice only when the notice's type is one of the #t values.
• A filter without #t matches a notice only when its type is one of the legacy types: stream, forum, dm, workflow. This list is fixed. A type added later is never on it, so old clients never see its notices.
• A notice without a t tag was stored before this rule. Every such notice is about a legacy type, so the relay treats it as all of them: it matches a filter without #t, and a filter whose #t has a legacy type. On these two kinds, this replaces the plain NIP-01 #t match.

The rule applies on every path: REQ history, live delivery, COUNT, and any relay-specific query API. Existing clients do not send #t on these kinds, so they see no change.

A client that knows every current type sends one filter:

{"kinds": [44100, 44101], "#p": ["<me>"], "#t": ["stream", "forum", "dm", "workflow", "system"]}

When Buzz adds a type, a client adds its value to #t when it supports that type.

The #p rule for 44100/44101 still applies: it must be the reader's own pubkey. An ids filter does not lift it: the relay returns, counts or delivers a 44100/44101 only to the pubkey in its p tag, even to a reader who knows the event id.

Because the notices are stored, a client that reconnects can set since to the newest notice it has seen. One subscription then returns the notices it missed and the new ones, so no change falls between a read and a subscription. A notice is a hint: the channel's group-state events decide membership.

Asking for system channels

A filter whose kinds are all 39000–39003 also returns the system channels that the reader can read when it has:

• "#t" with the value system; or
• any "#P". A query for the channels of named creators returns a small result, so it does not fill generic channel lists.

The filter then matches as usual. A label alone does not ask for system channels. These filters add only system channels. A channel of a type added later reaches only a filter that names it.

To find	Filter
My system channels	{"kinds": [39002], "#p": ["<me>"], "#t": ["system"]}, then their kind:39000 by #d
Open system channels	{"kinds": [39000], "#t": ["system"]}
One creator's channel with a label, system or not	{"kinds": [39000], "#P": ["<creator>"], "#t": ["<label>"]}

"#t": ["system", "<label>"] means system or the label. It does not mean "a system channel with this label". Use #P and the label instead.

Private system channels stay hidden from non-members, as for every private channel.

Advertising support

Until this draft has an upstream integer NIP number, relays MUST NOT advertise it in NIP-11 supported_nips. A relay that supports this NIP adds "nip-cl" to its NIP-11 supported_extensions string array.

A relay without this NIP drops label tags on create and refuses channel_type=system. So a client SHOULD NOT create a channel with labels or a system channel on a relay whose NIP-11 document does not contain "nip-cl". Lookups by label on such a relay find nothing, which is safe.

Trust

A client that relies on these tags MUST check that the relay's key signed the event, as for all NIP-29 group-state events.

Labels give no trust. Any owner or admin can set them. Only P says who created a channel.

Relation to other NIPs

• NIP-29: the group-state events that this NIP adds tags to.
• NIP-01: the filters that find channels.
• NIP-22, NIP-34 and NIP-72: the convention for uppercase P.