NIP-34 maintainers
The proposed NIP-34 maintainer update adds an explicit lead maintainer role, moderators, role history, and several subtler fixes and simplifications. ngit v3, ngit-grasp v3, and GitWorkshop v4 introduced the model together as coordinated implementations. They are not the only clients or services that can implement these protocol rules.
The maintainer model is documented at five levels:
- Maintainers explains how the model works for maintainers and users. Maintainers: going deeper covers the less common and more advanced workflows.
- The full NIP-34 specification presents the normative event definitions and rules with the maintainer update applied in context. Its proposed upstream change is PR #2324.
- Maintainer authority in ngit v3 explains the problems with the previous model and the reasons for the changes.
- This page explains the protocol model: how separately signed announcements become one repository, and how authority, lead routing, and history fit together.
- Maintainer protocol for AI implementers gives an exhaustive account for implementations that need every rule, failure mode, and conformance case made explicit.
Explanation, not a second specification
This page provides the mental model for the maintainer protocol. The full specification remains the source for exact tag syntax, interval grammar, precedence, and event ordering.
One repository, several signed views
NIP-34 does not give a multi-maintainer repository one global roster event. Each maintainer publishes their own addressable kind 30617 repository announcement. Announcements for the same project share a d identifier, but each still has a distinct coordinate because its author is part of the address.
A client starts from one selected maintainer's coordinate and follows the active role relationships to other announcements with the same identifier. The confirmed, connected result is the virtual repository for that starting point.
This distinction is load-bearing. Two people can independently use the same repository identifier without their state or permissions being combined. Their announcements become one virtual repository only when signed, reciprocal maintainer relationships join them.
Role records are signed relationships
An indexed role record belongs to the author of the announcement containing it. Alice's record naming Bob is Alice's statement about Bob; Bob's record naming Bob is a separate, signed statement.
| Record | Meaning while active |
|---|---|
M | A maintainer relationship that also identifies the lead path |
m | A co-maintainer relationship |
o | A moderator relationship |
Active M and m records carry the same maintainer authority. The capital letter does not make a signature stronger. It lets clients find the lead used to coordinate the roster. Moderators can manage issues and proposals, but cannot publish authoritative kind 30618 repository state or create and push a merge commit. They may report a merge that is already present in authorised repository state.
A one-person announcement needs none of these records. When no indexed role or legacy maintainers tag is present, the author is the implicit sole maintainer.
Assignment plus acceptance creates authority
Listing another pubkey is an invitation. It does not, by itself, make that person's repository state or maintainer actions authoritative.
The invitee accepts by publishing their own same-identifier announcement with an active maintainer relationship back to an already confirmed member. A client then resolves the reciprocal relationships recursively:
- A confirmed maintainer assigns
Mormto a candidate. - The candidate signs an active
Mormrelationship back into the confirmed component. - The candidate becomes confirmed, and their active assignments can extend the component in turn.
This is why adding a maintainer is a real delegation of authority. Once the relationship is reciprocal, valid active relationships in the new maintainer's announcement can bring further people and repository state into the same virtual repository. Clients should show that possible component join before publishing a membership change.
Reciprocity also prevents impersonation. A repository cannot borrow a well-known person's identity merely by listing their pubkey, and an unconfirmed group of invitees cannot bootstrap itself into authority. If a maintainer ends their own role, that signed departure takes precedence over another announcement continuing to list them.
The selected coordinate and the lead
The selected maintainer is the author named by the nostr:// URL, naddr, or other repository coordinate where discovery begins. Selection is not a vote and does not grant that author extra authority. It determines the root from which the client discovers a virtual repository and resolves its lead.
In the usual lead-shaped repository, an active M record forwards from a co-maintainer to the lead. The lead terminates that walk with an active self-M. The lead's announcement supplies the normal roster seed, while each candidate still needs a reciprocal acknowledgement before becoming authoritative.
The lead has no cryptographically stronger maintainer role. Lead-aware clients use the resolved lead to coordinate roster changes so the graph converges on one clear view. A leadless repository instead relies on the reciprocal maintainer graph rooted at the selected coordinate, which is why choosing a coordinate matters more in that topology.
Changing an M pointer changes where that author's coordinate leads. It does not transfer the coordinate's signing key, rewrite other maintainers' announcements, or rewrite a checkout's selected coordinate. During a handover, the incoming lead first publishes a complete self-led view; the outgoing lead can then forward to it without leaving an unresolved cycle.
Current authority and history answer different questions
The active graph answers who may act for the repository now. Role intervals answer whether a maintainer or moderator was authorised when an older issue, proposal, status, or state event was published.
Maintainers replicate that history in their own announcements so it survives later roster changes. A non-self record ending in defer preserves a known historical interval without making a current assignment or claiming an exact end time. It never creates a current graph edge, confirms an invitation, or forwards to a lead.
Keeping these questions separate prevents two opposite errors: removing a maintainer must not invalidate actions they were authorised to perform in the past, and retaining their history must not restore their current authority.
When historical copies disagree, the selected maintainer's view has precedence, followed by the shortest graph distance and then a deterministic pubkey tie-break. The specification defines the exact ordering rules.
Compatibility does not override indexed roles
Older announcements use the unindexed maintainers tag. Clients continue to read that legacy form, and may infer a lead for repositories that have not adopted indexed roles.
Once an announcement contains M, m, or o, those indexed records are its authoritative role model. A simultaneously emitted maintainers tag is only a compatibility projection for older clients. It lists the subjects of active M and m records, including invitations, but cannot by itself distinguish an invitation from an accepted role or express lead routing, moderation, or history.
Readers must also distinguish a non-canonical shape from an invalid one. For example, a co-maintainer's valid active assignment to a third party is a real relationship even though lead-aware clients normally avoid publishing that shape. A reader cannot silently turn it into historical defer data merely to recover the preferred topology.
Failure is unavailable authority, not erased data
Repository announcements are replaceable events published by independent signers, so clients can encounter missing targets, concurrent replacements, multiple lead pointers, malformed histories, or a forwarding cycle.
When a valid explicit lead path cannot resolve safely, clients fail closed for current authority instead of guessing a maintainer set from older or partial data. That state does not delete the announcements, Git objects, or historical snapshot. It means role-dependent writes and current maintainer authority are unavailable from that rooted view until a signer publishes a valid replacement.
This boundary matters while relay visibility is incomplete. As more relays answer, a client may discover a previously unknown announcement that wins the replaceable-event ordering and moves its view forward. If the client guessed authority while the path was unresolved, that event could exclude a signer or repository state the client had already accepted. Clients should expose the unresolved path and retain readable signed evidence until the authoritative view can be resolved.
Where exact rules live
Use the full NIP-34 specification for the normative event format, role-history grammar, precedence, addressable-event ordering, and repository-state merging rules.
Use the maintainer protocol for AI implementers for deterministic resolution procedures, publishing requirements, malformed input handling, worked graph examples, security invariants, and conformance fixtures.