support query name by labelhash

Author: brenzi

scripts/resolver/README.md

@@ -151,7 +151,8 @@ unknown.
 | `registered` | live; `expires` is when that ends |
 | `grace` | lapsed, but only the previous owner may renew it, until `graceEnds` |
 | `expired` | lapsed and past grace — anyone may register it now |
-| `unregistered` | never registered |
+| `unregistered` | never registered, and free to take |
+| `reserved` | not registered, and held for a brand — registration will be refused |
 | `noResolver` | registered, but points nowhere |
 | `unknown` | no `SNRC_REGISTRAR_<TLD>` configured, so status could not be read |
 
@@ -168,6 +169,31 @@ distinguish these: it is also true for a name nobody ever registered, since
 Subnames report the status of the 2LD they sit under, which is the useful
 answer — a subname is only as valid as the name above it.
 
+### Asking without naming the name
+
+A client checking whether a name is free is usually about to register it, so
+the question itself is worth front-running. Substitute the label's keccak hash
+for the label and the answer is identical:
+
+```sh
+# instead of /resolve/acme.testing
+curl -s http://127.0.0.1:8000/resolve/0x$(printf acme | keccak-256sum | cut -d' ' -f1).testing
+```
+
+namehash is defined as `keccak(parent || keccak(label))`, so supplying
+`keccak(label)` yields the same node — and the registrar keys both
+`nameExpires` and `reservedNames` on the labelhash, so status needs nothing
+else. Whoever runs the resolver sees a hash and learns which name you are
+interested in only if they already guessed it.
+
+The two forms cannot be confused: a hashed label is `0x` and 64 hex characters,
+66 in total, and the registrar caps real labels well below that. Only the
+leftmost label may be hashed, and only for a 2LD.
+
+Registration is still a public act — this hides the *interest*, not the
+eventual registration, and the commit-reveal in the controller is what protects
+the registration itself.
+
 ### Errors
 
 Every non-2xx body carries a stable `error` code to branch on and a human
@@ -179,9 +205,9 @@ Every non-2xx body carries a stable `error` code to branch on and a human
  "status": "unregistered", "expires": null, "graceEnds": null}
 ```
 
-Codes: `tldNotConfigured`, `notFullyQualified`, `unregistered`, `grace`,
-`expired`, `noResolver`, `badAddress`, `badOffset`, `noRegistrarConfigured`,
-`unauthorized`, `noSuchRoute`, `upstreamError`. For a name whose registration
+Codes: `tldNotConfigured`, `notFullyQualified`, `unregistered`, `reserved`,
+`grace`, `expired`, `noResolver`, `badAddress`, `badOffset`,
+`noRegistrarConfigured`, `unauthorized`, `noSuchRoute`, `upstreamError`. For a name whose registration
 is the problem, the code equals `status`.
 
 ### Status codes
@@ -239,12 +265,20 @@ what `/resolve` reads; it defaults to mainnet `.testing`, with `.simplex` unset
 until deployed. The **registrar** is the ERC-721 that can be asked the reverse
 and when a name expires — it is what `/owned-by` and every expiry field are
 read from. Without a registrar for a TLD, `/resolve` still works and reports
-`"status": "unknown"`, and `/owned-by` answers 400.
+`"status": "unknown"`, and `/owned-by` answers 400. The **controller** holds `reservedNames`, and is what the `reserved` status is
+read from; without one for a TLD, a reserved name reads as `unregistered`.
+
+Note that the controller address is the **proxy**, not `SimplexControllerImpl`:
+storage lives in the proxy, so the implementation answers nothing.
+`deployments.mainnet.testing.json` records it under the ENS role name
+`ETHRegistrarController` and `verification.mainnet.testing.json` names it
+`SimplexControllerProxy` — the same address, and the one defaulted to here.
 
 | Variable | Purpose |
 |---|---|
 | `SNRC_REGISTRY_<TLD>` | ENS registry; resolution |
 | `SNRC_REGISTRAR_<TLD>` | ERC-721 registrar; `/owned-by`, expiry and status |
+| `SNRC_CONTROLLER_<TLD>` | SimplexController; the `reserved` status |
 | `SNRC_MAX_OWNED` | names per `/owned-by` page (default 256) |
 
 Set them on the `resolver` service in `docker-compose.yml`, or as env vars for
@@ -296,6 +330,8 @@ any lookup, and carry none of the three.
 | Lapsed, still in grace | 410 | `grace` | `expires` (when it lapsed), `graceEnds` (last moment its owner can renew) |
 | Lapsed, past grace | 410 | `expired` | same fields; anyone may register it now |
 | Never registered | 404 | `unregistered` | `expires` and `graceEnds` are `null` |
+| Reserved for a brand | 404 | `reserved` | not registered and not registrable; overrides `unregistered` and `expired` |
+| Queried by labelhash (`0x…64hex.testing`) | as the label | as the label | identical answer; the label is never sent |
 | TLD has no registry configured | 400 | — | `error: tldNotConfigured`, plus `configuredTlds` |
 | TLD has no *registrar* configured | 200 / 404 | `unknown` | resolves as it otherwise would; expiry cannot be read, so `expires` and `graceEnds` are `null` |
 | Not fully qualified (`alice`) | 400 | — | `error` naming the expected form |

scripts/resolver/docker-compose.yml

@@ -156,6 +156,11 @@ services:
       # the expiry status on /resolve; without them status reads "unknown".
       # SNRC_REGISTRAR_TESTING: 0x...
       # SNRC_REGISTRAR_SIMPLEX: 0x...
+      # SimplexController, which holds reservedNames. No default: it is behind
+      # a UUPS proxy and deployments records the implementation, so the address
+      # has to be the proxy and has to be given.
+      # SNRC_CONTROLLER_TESTING: 0x...
+      # SNRC_CONTROLLER_SIMPLEX: 0x...
       # SNRC_MAX_OWNED: 256
       # SNRC_CACHE_TTL: 15          # seconds to memoise eth_call; 0 disables
       # SNRC_MAX_RPC_BYTES: 2097152 # refuse a larger JSON-RPC response

scripts/resolver/service/snrc-resolve.py

@@ -88,6 +88,18 @@
     "simplex": os.environ.get("SNRC_REGISTRY_SIMPLEX", ""),  # not deployed yet
 }
 
+# The SimplexController per TLD, which holds `reservedNames`. Without one for a
+# TLD, `reserved` is never reported and a reserved name reads as unregistered.
+CONTROLLERS = {
+    "testing": os.environ.get("SNRC_CONTROLLER_TESTING", "")
+    # The proxy, not SimplexControllerImpl: storage and events live in the
+    # proxy, so the implementation address answers nothing. deployments.json
+    # records this one under the ENS role name ETHRegistrarController;
+    # verification.json names it SimplexControllerProxy. Same address.
+    or "0xeeb9b6bf5fb68fb726005f7ba549c2f4b32f2dad",  # mainnet .testing
+    "simplex": os.environ.get("SNRC_CONTROLLER_SIMPLEX", ""),  # not deployed yet
+}
+
 # Shared secret the caller must present. Unset means no check - correct for a
 # loopback deployment, and the reason the check exists at all is that the
 # Haskell client has always been able to send `Authorization` and nothing here
@@ -526,22 +538,26 @@ def resolve(name: str):
             "configuredTlds": configured,
         }
 
-    node = namehash(name)
+    node = node_of(name)
     node_hex = node.hex()
 
     # Registration first, because it is the fact that separates the failures a
     # caller has to tell apart: a name nobody has taken, one whose registration
     # lapsed and may still be renewed, one that lapsed and is now open to
     # anyone, and one that is held but not pointed anywhere.
     reg = name_status(name)
-    if reg["status"] == "unregistered":
+    if reg["status"] in ("unregistered", "reserved"):
         return 404, {
             "name": name,
-            "status": "unregistered",
-            "expires": None,
-            "graceEnds": None,
-            "error": "unregistered",
-            "message": "this name has never been registered",
+            "status": reg["status"],
+            "expires": reg["expires"],
+            "graceEnds": reg["graceEnds"],
+            "error": reg["status"],
+            "message": (
+                "this name is held for its trademark owner and cannot be registered"
+                if reg["status"] == "reserved"
+                else "this name has never been registered"
+            ),
         }
     if reg["status"] in ("grace", "expired"):
         return 410, {
@@ -619,6 +635,57 @@ def grace_period(registrar: str) -> int:
     return decode_uint(eth_call(registrar, selector("GRACE_PERIOD()")))
 
 
+# A labelhash standing in for a label: "0x" and 32 bytes of hex. A real label
+# cannot collide with this, because the registrar caps labels well below the 66
+# characters this takes - so the two forms are distinguishable without a flag.
+HASHED_LABEL_LEN = 66
+
+
+def is_labelhash(label: str) -> bool:
+    return (
+        len(label) == HASHED_LABEL_LEN
+        and label.startswith("0x")
+        and all(c in "0123456789abcdef" for c in label[2:])
+    )
+
+
+def label_token(label: str) -> int:
+    """The registrar token id for a label, given either the label or its hash.
+
+    Querying by hash is what lets a client ask "is this name free?" without
+    telling the resolver which name it is about to register - the answer is
+    the same, and the intent does not leak to whoever runs the resolver.
+    """
+    return int(label, 16) if is_labelhash(label) else int.from_bytes(keccak(label.encode()), "big")
+
+
+def node_of(name: str) -> bytes:
+    """namehash, accepting a hashed leftmost label.
+
+    namehash is defined recursively as keccak(parent || keccak(label)), so a
+    caller who supplies keccak(label) directly gets the same node without ever
+    sending the label.
+    """
+    labels = name.split(".")
+    if len(labels) == 2 and is_labelhash(labels[0]):
+        return keccak(namehash(labels[1]) + bytes.fromhex(labels[0][2:]))
+    return namehash(name)
+
+
+def is_reserved(tld: str, token: int) -> bool:
+    """Whether the controller holds this label for a brand.
+
+    Keyed by labelhash on chain, so this answers for a hashed query too.
+    """
+    controller = CONTROLLERS.get(tld)
+    if not controller:
+        return False
+    raw = eth_call(
+        controller, selector("reservedNames(bytes32)") + encode_uint(token)
+    )
+    return decode_uint(raw) != 0
+
+
 def expiry_status(expires: int, grace: int, now: int) -> str:
     """Registration state from an expiry timestamp.
 
@@ -661,17 +728,27 @@ def name_status(name: str):
         # No registrar configured for this TLD: say so rather than guess.
         return {"status": "unknown", "expires": None, "graceEnds": None}
 
-    token = int.from_bytes(keccak(labels[-2].encode()), "big")
+    token = label_token(labels[-2])
     expires = decode_uint(
         eth_call(registrar, selector("nameExpires(uint256)") + encode_uint(token))
     )
     if expires == 0:
-        return {"status": "unregistered", "expires": None, "graceEnds": None}
-    grace = grace_period(registrar)
+        status, grace = "unregistered", 0
+    else:
+        grace = grace_period(registrar)
+        status = expiry_status(expires, grace, int(time.time()))
+
+    # `reserved` only displaces the two states that read as "you could take
+    # this". A registered name is registered, and one in grace belongs to its
+    # owner either way - in both cases the reservation is not the answer to the
+    # question being asked.
+    if status in ("unregistered", "expired") and is_reserved(tld, token):
+        status = "reserved"
+
     return {
-        "status": expiry_status(expires, grace, int(time.time())),
-        "expires": expires,
-        "graceEnds": expires + grace,
+        "status": status,
+        "expires": expires or None,
+        "graceEnds": (expires + grace) if expires else None,
     }
 
 

scripts/resolver/service/test_snrc_resolve.py

@@ -204,6 +204,117 @@ def test_no_configured_registrar_is_an_error_not_an_empty_list(self):
         self.assertEqual(body["configuredTlds"], [])
 
 
+class LabelhashQueryTests(unittest.TestCase):
+    """Asking by labelhash instead of by label.
+
+    A client checking whether a name is free is about to register it, so
+    telling the resolver which name that is hands whoever runs it a
+    front-running opportunity. namehash is keccak(parent || keccak(label)), so
+    a caller who supplies keccak(label) gets an identical answer having said
+    nothing about the name."""
+
+    REGISTRAR = "0xef47eb4384b46c89e4482a677c2cbcbd2a6fd85a"
+    GRACE = 90 * 86400
+
+    def setUp(self):
+        self._saved = (snrc.REGISTRARS, snrc.CONTROLLERS, snrc.eth_call)
+        snrc.REGISTRARS = {"testing": self.REGISTRAR}
+        snrc.CONTROLLERS = {"testing": ""}
+
+    def tearDown(self):
+        snrc.REGISTRARS, snrc.CONTROLLERS, snrc.eth_call = self._saved
+
+    def test_a_hashed_label_is_recognised_and_a_real_one_is_not(self):
+        self.assertTrue(snrc.is_labelhash("0x" + snrc.keccak(b"alice").hex()))
+        self.assertFalse(snrc.is_labelhash("alice"))
+        self.assertFalse(snrc.is_labelhash("0x" + "z" * 64))
+        # a label cannot be this long, which is what keeps the forms apart
+        self.assertFalse(snrc.is_labelhash("0x" + "a" * 62))
+
+    def test_hash_and_label_give_the_same_token_and_node(self):
+        h = "0x" + snrc.keccak(b"alice").hex()
+        self.assertEqual(snrc.label_token("alice"), snrc.label_token(h))
+        self.assertEqual(snrc.node_of("alice.testing"), snrc.node_of(h + ".testing"))
+
+    def test_status_by_hash_matches_status_by_name(self):
+        future = int(time.time()) + 86400
+        seen = []
+
+        def eth_call(to, data):
+            seen.append(data)
+            if data.startswith(snrc.selector("GRACE_PERIOD()")):
+                return "0x" + snrc.encode_uint(self.GRACE)
+            return "0x" + snrc.encode_uint(future)
+
+        snrc.eth_call = eth_call
+        h = "0x" + snrc.keccak(b"alice").hex()
+        by_name = snrc.name_status("alice.testing")
+        by_hash = snrc.name_status(h + ".testing")
+        self.assertEqual(by_name, by_hash)
+        self.assertEqual(by_name["status"], "registered")
+        # nothing in either request carried the label itself
+        self.assertTrue(all("alice".encode().hex() not in d for d in seen))
+
+
+class ReservedTests(unittest.TestCase):
+    """A reserved name is unregistered and still unavailable, which a client
+    intending to register needs to know before it tries."""
+
+    REGISTRAR = "0xef47eb4384b46c89e4482a677c2cbcbd2a6fd85a"
+    CONTROLLER = "0x281ca41311c2aa808c917c4674639d7567b75714"
+
+    def setUp(self):
+        self._saved = (snrc.REGISTRARS, snrc.CONTROLLERS, snrc.eth_call)
+        snrc.REGISTRARS = {"testing": self.REGISTRAR}
+        snrc.CONTROLLERS = {"testing": self.CONTROLLER}
+
+    def tearDown(self):
+        snrc.REGISTRARS, snrc.CONTROLLERS, snrc.eth_call = self._saved
+
+    def _chain(self, expires, reserved):
+        def eth_call(to, data):
+            if data.startswith(snrc.selector("reservedNames(bytes32)")):
+                self.assertEqual(to, self.CONTROLLER)
+                return "0x" + snrc.encode_uint(1 if reserved else 0)
+            if data.startswith(snrc.selector("GRACE_PERIOD()")):
+                return "0x" + snrc.encode_uint(90 * 86400)
+            return "0x" + snrc.encode_uint(expires)
+
+        return eth_call
+
+    def test_unregistered_and_reserved_reads_reserved(self):
+        snrc.eth_call = self._chain(0, True)
+        self.assertEqual(snrc.name_status("acme.testing")["status"], "reserved")
+
+    def test_unregistered_and_not_reserved_reads_unregistered(self):
+        snrc.eth_call = self._chain(0, False)
+        self.assertEqual(snrc.name_status("acme.testing")["status"], "unregistered")
+
+    def test_a_lapsed_reserved_name_is_reserved_not_claimable(self):
+        past = int(time.time()) - 91 * 86400
+        snrc.eth_call = self._chain(past, True)
+        self.assertEqual(snrc.name_status("acme.testing")["status"], "reserved")
+
+    def test_a_live_name_is_registered_even_if_reserved(self):
+        """It was handed to its brand; the reservation is no longer the answer."""
+        snrc.eth_call = self._chain(int(time.time()) + 86400, True)
+        self.assertEqual(snrc.name_status("acme.testing")["status"], "registered")
+
+    def test_a_name_in_grace_belongs_to_its_owner_not_the_reserved_set(self):
+        snrc.eth_call = self._chain(int(time.time()) - 3600, True)
+        self.assertEqual(snrc.name_status("acme.testing")["status"], "grace")
+
+    def test_no_controller_configured_means_reserved_is_never_reported(self):
+        snrc.CONTROLLERS = {"testing": ""}
+        snrc.eth_call = self._chain(0, True)  # would say reserved if asked
+        self.assertEqual(snrc.name_status("acme.testing")["status"], "unregistered")
+
+    def test_reserved_is_asked_by_labelhash_so_a_hashed_query_works(self):
+        h = "0x" + snrc.keccak(b"acme").hex()
+        snrc.eth_call = self._chain(0, True)
+        self.assertEqual(snrc.name_status(h + ".testing")["status"], "reserved")
+
+
 class NameStatusTests(unittest.TestCase):
     """simplexmq#1821: unresolvable has three causes and a caller has to tell
     them apart. Names expire lazily, so the chain still holds the answer."""
@@ -222,11 +333,14 @@ def eth_call(to, data):
         return eth_call
 
     def setUp(self):
-        self._registrars, self._eth_call = snrc.REGISTRARS, snrc.eth_call
+        self._saved = (snrc.REGISTRARS, snrc.CONTROLLERS, snrc.eth_call)
         snrc.REGISTRARS = {"testing": self.REGISTRAR}
+        # These cases are about expiry alone. ReservedTests covers what a
+        # configured controller adds.
+        snrc.CONTROLLERS = {"testing": ""}
 
     def tearDown(self):
-        snrc.REGISTRARS, snrc.eth_call = self._registrars, self._eth_call
+        snrc.REGISTRARS, snrc.CONTROLLERS, snrc.eth_call = self._saved
 
     def test_zero_expiry_means_never_registered(self):
         snrc.eth_call = self._expiry(0)