NIP-66: Define output tags for ssl, geo, and net checks; fix timeout/l-tag/c-tag docs

[VincenzoImp]

Summary

This PR proposes additions to NIP-66 to standardize the output format for checks that are already declarable in kind 10166 but lack defined result tags in kind 30166. It also fixes several inconsistencies in the current specification.

---

Part 1: Bug Fixes

1.1 Fix timeout tag format documentation

The current specification text contradicts the example:

Index 1 is the monitor's timeout in milliseconds. Index 2 describes what test the timeout is used for.

But the example shows:

[ "timeout", "open", "5000" ]

Here index 1 is the test type and index 2 is milliseconds. The example is correct, the text should be updated to match:

-- Index `1` is the monitor's timeout in milliseconds. Index `2` describes what test the timeout is used for.
+- Index `1` is the test type (e.g., `open`, `read`, `write`). Index `2` is the timeout in milliseconds.

1.2 Document the l (language) tag

The example includes ["l", "en", "ISO-639-1"] but the l tag is not documented. Add to the tags list:

+- `l` - Language tag. Index `1` is the ISO-639-1 language code, index `2` is the standard identifier (`ISO-639-1`).

1.3 Clarify c tag check values

The specification lists check examples as open, read, write, auth, nip11, dns, geo, but the example uses ws instead of open/read/write.

Clarify that:

• open - Tests WebSocket connection establishment
• read - Tests subscription/read capability
• write - Tests event publishing capability
• ssl - Tests SSL/TLS certificate (should be added to spec text)

Update the example to use consistent values:

-[ "c", "ws" ],
+[ "c", "open" ],
+[ "c", "read" ],
+[ "c", "write" ],

---

Part 2: New Output Tags

Current state

NIP-66 currently allows monitors to declare checks via the c tag, but while open, read, and write have corresponding output tags (rtt-open, rtt-read, rtt-write), the checks ssl, geo, and dns have no standardized output format.

2.1 Add SSL/TLS tags

Define output tags for the ssl check (clearnet wss:// relays only):

+- `ssl` - Certificate validity status: `valid` or `!valid`
+- `ssl-expires` - Certificate expiration as Unix timestamp in seconds
+- `ssl-issuer` - Certificate Authority (CA) organization name

2.2 Add Network tags

Define output tags for a new net check:

+- `net-ip` - Resolved IPv4 address of the relay
+- `net-ipv6` - Resolved IPv6 address of the relay (if available)
+- `net-asn` - Autonomous System Number
+- `net-asn-org` - ASN organization name

2.3 Add Geographic tags

Define output tags for the geo check, complementing the existing g (geohash) tag:

+- `geo-country` - ISO 3166-1 alpha-2 country code
+- `geo-city` - City name
+- `geo-lat` - Latitude coordinate as decimal string
+- `geo-lon` - Longitude coordinate as decimal string
+- `geo-tz` - IANA timezone identifier

2.4 Add net check type

Add net (network/ASN lookup) to the list of check types in kind 10166.

2.5 Formal check-to-output mapping

Replace the informal list of check examples with a formal table:

Check	Description	Output Tags
open	Connection test	rtt-open
read	Read/subscription test	rtt-read
write	Write/publish test	rtt-write
nip11	NIP-11 document fetch	content
ssl	SSL/TLS certificate check	ssl, ssl-expires, ssl-issuer
geo	Geographic location lookup	g, geo-country, geo-city, geo-lat, geo-lon, geo-tz
net	Network/ASN lookup	net-ip, net-ipv6, net-asn, net-asn-org

2.6 Reorganize tag documentation

Group tags by category for clarity:

• Basic Tags: d, n, T, N, R, t, k, l
• RTT Tags: rtt-open, rtt-read, rtt-write
• SSL/TLS Tags: ssl, ssl-expires, ssl-issuer
• Network Tags: net-ip, net-ipv6, net-asn, net-asn-org
• Geographic Tags: g, geo-country, geo-city, geo-lat, geo-lon, geo-tz

---

Design Decisions

Why separate net-* from geo-*?

ASN and IP are network identifiers, not geographic locations. A relay in Amsterdam hosted on Cloudflare would have:

• geo-city: Amsterdam (physical server location)
• net-asn-org: Cloudflare (network provider)

These are semantically different concepts derived from different data sources (GeoIP City vs GeoIP ASN databases).

Why include net-ipv6?

IPv6 adoption continues to grow. Some users/networks are IPv6-only or prefer IPv6 for direct connectivity (less NAT traversal). Knowing if a relay supports IPv6 helps clients make informed routing decisions.

Why include geo-lat/geo-lon when g (geohash) exists?

For convenience. Clients can read coordinates directly without implementing geohash decoding. The g tag remains the canonical location identifier for filtering.

Why only three SSL fields?

Minimalism. Only fields useful for client decision-making are included:

• ssl - Filter relays by certificate validity
• ssl-expires - Alert before expiration
• ssl-issuer - Trust assessment based on CA

Detailed SSL data (cipher, fingerprint, protocol version) is better suited for specialized security audit tools.

---

Examples

Kind 30166 (Relay Discovery Event)

{
  "kind": 30166,
  "tags": [
    ["d", "wss://relay.example.com/"],
    ["n", "clearnet"],
    ["N", "1"],
    ["R", "!payment"],
    ["l", "en", "ISO-639-1"],

    ["rtt-open", "89"],
    ["rtt-read", "123"],
    ["rtt-write", "156"],

    ["ssl", "valid"],
    ["ssl-expires", "1735689600"],
    ["ssl-issuer", "Let's Encrypt"],

    ["net-ip", "93.184.216.34"],
    ["net-ipv6", "2606:2800:220:1:248:1893:25c8:1946"],
    ["net-asn", "15169"],
    ["net-asn-org", "Google LLC"],

    ["g", "u173zq37x"],
    ["geo-country", "NL"],
    ["geo-city", "Amsterdam"],
    ["geo-lat", "52.3676"],
    ["geo-lon", "4.9041"],
    ["geo-tz", "Europe/Amsterdam"]
  ]
}

Kind 10166 (Monitor Announcement)

{
  "kind": 10166,
  "tags": [
    ["frequency", "3600"],
    ["timeout", "open", "5000"],
    ["timeout", "read", "3000"],
    ["timeout", "write", "3000"],
    ["timeout", "ssl", "5000"],
    ["c", "open"],
    ["c", "read"],
    ["c", "write"],
    ["c", "nip11"],
    ["c", "ssl"],
    ["c", "geo"],
    ["c", "net"],
    ["g", "u173zq37x"]
  ]
}

---

Backwards Compatibility

• All proposed tags are optional
• Existing clients can safely ignore unknown tags
• No changes to required fields or existing tag semantics
• Follows existing NIP-66 conventions (e.g., ! prefix for false values)
• Bug fixes clarify existing behavior without breaking changes

[VincenzoImp]

Hey @dskvr , since you're the main contributor of NIP-66, I'd really appreciate your feedback on this proposal.

I'm working on a relay monitoring implementation and noticed some gaps between what monitors can declare (via c tags) and what output tags are actually defined in the spec.

Feel free to reach out on Nostr if you prefer: npub1szgdn7q6g9huf8a4zd980khntyk2mwqa7s5rlqye6v3y3w7gs4zspmv73y

[dskvr]

@VincenzoImp Categorizing these as "bugs" is not remotely correct.

Basic Tags is mislabeled, they are Indexed Tags.

The l tags within the 30166 events that are published by @nostrwatch/relaymon are inline NIP-32 "labels" and this is intentionally undocumented. The labels were at one point documented similar to what you have proposed, but the bike-shedding that resulted from attempting to define these values led me to externalize it to ad-hoc definitions.

The primary argument against including these values in specification by detractors was that the event shouldn't have these values to begin with. By externalizing the values to NIP-32 I was able to include the data without it being specified or standardized; it was a workaround for NIP-66 actualization. Therefor the lack of standardized output format was intentional, had these been defined, NIP-66 would be on draft 22 right now and we would still be arguing over the legitimacy of including meta-data and/or the format of said meta-data. The only way I could get it through was by removing all these definitions. \

Yes there are gaps. I agree with many of your suggestions, they used to actually be one of the drafts, draft-5 i believe. However, some of your suggestions show a lack of understanding behind decision path and history of this nip, particularly this one:

    ["geo-country", "NL"],
    ["geo-city", "Amsterdam"],
    ["geo-tz", "Europe/Amsterdam"]

As defined, those values cannot be indexed, and thus, you cannot filter against NL, Amsterdam or Europe/Amsterdam. That's why I used l, I originally attempted to push forward ISO-3166 standards tag (twice), but couldn't get anywhere with it. These would have produced standardized and indexable (and actually usable) geotags.

This same critique applies to a few other of your changes as well. By moving them from indexed tags to named tags, we lose the ability to filter against them, which can result in an undesirable centralizing effect that requires API/DVM/CVM for the data to be filterable.

• I tried to help this one get traction: NIP-3166: Country code tag based on ISO-3166 #763
• I tried to improve g and then later concede to just G (non-breaking change, none of the gatekeepers would even review it, let alone approve it): NIP-115 Yet Another Geo Tag (ISO-3166-1/2/3) #952

I genuinely tried to do this "correctly" but the onslaught of non-compromising and often irrelevant rebuttals, as well as the segmented and weaponized PR approval gate-keeping, from everyone between random people and the high priests that that followed was enough to send most people to an insane asylum.

asides
Indexable g geohashes are completely useless for geospatial filtering, even with cascading g filters the closer a geopoint is on the boundary of the lowest precisions bbox of any given geohash, the less accurate any nearby filter will be. Dead center of each lowest precision geohash is 100% accurate, geohashes within 1km of lowest precision geohash boundaries are between 25-50% accurate (50% if in the middle of the boundary line, 25% if on the corner). It's absolutely useless as an indexable tag, and actual indexable ISO-3166-1/2/3 tags would provide substantially more value. Alas, logic and objective reality does not prevail over social clout around these parts.

To correct do geospatial filtering, geohashes should just be a named tag geohash and we should introduce an optional geospatial filter where relays provide ability to return nearby events (idea from @v0l if I remember correctly). g should be ISO-3166-1/2/3 IMO. One day this will be obvious to anyone who has thought about the problem for longer than 10 minutes.

[VincenzoImp]

Hey @dskvr, thanks for explaining the history and the NIP-32 workaround.

To be honest, as time passed, I wasn't happy with my PR either. I wanted things like country and ASN to be filterable, but I knew multi-letter tags wouldn't work for native relay queries. I just didn't know how else to solve it since I was completely unaware of your l tag workaround.

Your explanation makes perfect sense. I'll close that PR and submit a much lighter one. I'll drop the multi-letter filterable tags (and just use NIP-32 in my monitor's code as you intended) and only propose the read-only metadata (net-ip, ssl-expires) along with the actual typo fixes (like timeout).

Thanks again for the guidance and the elegant solution!

[dskvr]

@VincenzoImp Now that there is more than one person working on a full-scale monitoring system, it might be wise that we attempt to define standards for the NIP-32 l tags. We could use dot notation instead of the generic camel case I am using now, which would make the specification more discoverable (for example, nip66.label.countryCode or even watch.nostr.nip66.label.countryCode and bigbrothr.nip66.label.countryCode if there were disagreement)

LMK, down to hop on a call or a chat.

[VincenzoImp]

Hey @dskvr, that sounds like a solid approach. Using dot notation for the NIP-32 L tags makes perfect sense. I'll DM on nostr.