nips/97.md

NIP-97
======

Nostr Name System (NNS)
-----------------------

`draft` `optional`

Event `30053` defines a DNS record for Nostr. `ip4` and `ip6` tags represent DNS's `A` records. 

```js
{
  "kind": 30053,
  "tags": [
    ["d", "<subdomain-like-name or empty for root>"],

    ["ip4", "230.22.120.232", "<time-to-live in seconds>"],
    ["ip4", "230.22.120.233", "<time-to-live in seconds>"], // mirrored servers / client-based load balancing
    ["ip4", "230.22.120.234", "<time-to-live in seconds>"], // mirrored servers / client-based load balancing

    ["ip6", "FE80:0000:0000:0000:0202:B3FF:FE1E:8329"] // same content as ipv4
  ],
  // ...
}
```

Multiple pubkeys can point to the same IP address. 

The server must reply with an IP-only request, such as: `wss://230.22.120.232` or `https://230.22.120.232`. 

# Addressing

[NIP-19](19.md)'s `naddr1` addresses of kind `30053` replace the domain name on any URL or URI. 

Examples 
- `http://naddr1...ccpzu/image.jpg` makes an http request for `https://<ip4>/image.jpg`
- `wss://naddr1...ccpzu:443/` makes an websocket request at `wss://<ip4>:443/`

The `naddr1`'s `relay` field SHOULD have the IP-based URI to the relay (e.g.: `wss://<ip4>/`) hosting the NNS record at the time of creating the `naddr1`.

# Resolving

Clients SHOULD intercept the DNS resolution of any `naddr1` domain name and resolve to IP using the latest version of the NNS replaceable event. 

If the NNS event cannot be found locally, Clients SHOULD in parallel:  
1. Connect to the IP in the `relay` field of the `naddr1` to download a potentially outdated version of the NNS record.
2. Retrieve the latest version of this replaceable from the [NIP-65](65.md) WRITE relays of the `naddr1`'s pubkey.

# HTTP URLs (Media Servers)

Clients SHOULD use the NNS address (e.g. `http://naddr1...ccpzu/<rest of the url>`), if available, instead of the regular domain name in all URLs, both in tags and in the content of events. 

For example, this loads an image without a domain name:

```js
{
  "kind": 1,
  "tags": [],
  "content": "NNS is amazing: http://naddr1...ccpzu/image.jpg",
  // ...other fields
}
```

# Relay Hints

Clients SHOULD use the NNS record (e.g. `wss://naddr1...ccpzu`), if available, instead of the regular domain name in all relay hints.

For example, this is a reply using an NNS relay hint

```js
{
  "kind": 1,
  "tags": [
    ["e", "<event id>", "<wss://naddr1...ccpzu>", "root"],
  ],
  "content": "",
  // ...other fields
}
```

# Relay Lists

Clients SHOULD use the NNS record (e.g. `wss://naddr1...ccpzu`), if available, instead of the DNS in all relay lists.

The NNS events to resolve those addresses MUST be broadcasted to the same relays as their kind `10002`

For example, this is a relay list using NNS addresses

```js
{
  "kind": 10002,
  "tags": [
    ["r", "wss://naddr1...ccpzu"],
    ["r", "wss://naddr1...2d90k", "write"],
    ["r", "wss://naddr1...um5wg", "read"]
  ],
  "content": "",
  // ...other fields
}
```