nip34: add refs to repo event

so that the event can be used as a source of truth for the state of refs
such as branches and tags

this could be useful as:

1. a way to reduce trust in git server(s) so they no longer act as a
   source of truth. a nip34 git remote-helper could proxy requests to
   git servers and only pull updates when they match the state listed in
   the repo event.
2. a form of authorisation for nip34 git server implementations
   such as song
3. a way of enabling experimentation with other protocols for hosting
   and accessing git data. eg a blossom git remote helper

1 files changed, 30 insertions, 0 deletions

diff --git a/34.md b/34.md
index 52e23b5..4989803 100644
--- a/34.md
+++ b/34.md
@@ -35,6 +35,36 @@ The `r` tag annotated with the `"euc"` marker should be the commit ID of the ear
 
 Except `d`, all tags are optional.
 
+## Repository state announcements
+
+An optional source of truth for the state of branches and tags in a repository.
+
+```jsonc
+{
+  "kind": 30618,
+  "content": "",
+  "tags": [
+    ["d", "<repo-id>"], // matches the identifier in the coresponding repository announcement
+    ["refs/<heads|tags>/<branch-or-tag-name>","<commit-id>"]
+    ["HEAD", "ref: refs/heads/<branch-name>"]
+  ]
+}
+```
+
+The `refs` tag may appear multiple times, or none.
+
+If no `refs` tags are present, the author is no longer tracking repository state using this event. This approach enables the author to restart tracking state at a later time unlike [NIP-09](09.md) deletion.
+
+The `refs` tag can be optionally extended to enable clients to identify how many commits ahead a ref is:
+
+```jsonc
+{
+  "tags": [
+    ["refs/<heads|tags>/<branch-or-tag-name>", "<commit-id>", "<shorthand-parent-commit-id>", "<shorthand-grandparent>", ...],
+  ]
+}
+```
+
 ## Patches
 
 Patches can be sent by anyone to any repository. Patches to a specific repository SHOULD be sent to the relays specified in that repository's announcement event's `"relays"` tag. Patch events SHOULD include an `a` tag pointing to that repository's announcement address.