cut comments

scripts/resolver/service/snrc-resolve.py

@@ -126,10 +126,7 @@ COIN_DOT = 354
 
 ZERO_ADDR = "0x0000000000000000000000000000000000000000"
 
-# Names per registrar per /owned-by page, so a page holds this many times the
-# number of configured TLDs. Each carries a full NameResponse, and a relay caps
-# the body it reads at 16000 bytes while a client cannot ask for a smaller page,
-# so keep the product well under it.
+# Names per registrar per /owned-by page; times the configured TLDs, a full page of NameResponses must fit the 16000 bytes a relay reads.
 MAX_OWNED = max(1, int(os.environ.get("SNRC_MAX_OWNED", "8")))
 
 # The registry prices in attoUSD (1e-18 USD); the protocol carries US cents.
@@ -928,8 +925,7 @@ def owned_by(address: str, offset: int = 0):
             "configuredTlds": [],
         }
 
-    # the block the enumeration below is read at; each name resolved after it
-    # reports its own, and the oldest of them all is what the answer carries
+    # the oldest block behind the answer: this one, or any name's own
     last_block_ts = chain_now()
     names, truncated, total_held = [], False, 0
     for tld, registrar in configured.items():
@@ -946,8 +942,7 @@ def owned_by(address: str, offset: int = 0):
             if not label:
                 continue
             status, body = registration(label + "." + tld)
-            # only a name still held names itself; one past its grace answers as
-            # available, which says nothing about the token it is enumerated on
+            # one past its grace answers as available, naming nothing it holds
             if status == 200 and body["registration"]["type"] == "registered":
                 names.append(body)
                 if body["lastBlockTs"] is not None:
@@ -962,12 +957,9 @@ def owned_by(address: str, offset: int = 0):
         "names": names,
         "nonce": nonce,
         "balance": str(balance),
-        # every name the address holds, not just this page: a later page of a
-        # held name must not read as an account that owns nothing
+        # every name held, not just this page, or page two reads as owning nothing
         "inUse": total_held > 0 or nonce > 0 or balance > 0,
         "offset": offset,
-        # `nextOffset` is the cursor to resume from, or null when the listing is
-        # complete, so "there is more" and "how to get it" are one answer.
         "nextOffset": offset + MAX_OWNED if truncated else None,
         "checkedTlds": sorted(configured),
     }

scripts/resolver/service/test_snrc_resolve.py

@@ -1054,8 +1054,7 @@ class OwnedByTests(unittest.TestCase):
         snrc.REGISTRARS = {"testing": self.REGISTRAR, "simplex": ""}
         snrc.rpc = lambda method, params: "0x0"
         snrc.chain_now = lambda: self.BLOCK_TS
-        # resolving one name is RegistrationV2Tests' subject; what owned-by adds
-        # is which names to resolve, so the registration itself is stubbed
+        # RegistrationV2Tests covers resolving one; owned-by picks which
         snrc.registration = lambda name: (200, self.response(name, "registered"))
 
     def tearDown(self):

src/Simplex/Messaging/Agent.hs

@@ -468,8 +468,7 @@ resolveSimplexName :: AgentClient -> NetworkRequestMode -> UserId -> SimplexDoma
 resolveSimplexName c nm userId domain = withAgentEnv c $ resolveSimplexName' c nm userId domain
 {-# INLINE resolveSimplexName #-}
 
--- | Names an address owns. The relay used is returned so a scan can pass it
--- back as used and ask the next account elsewhere.
+-- | Names an address owns, with the relay used, so a scan can ask the next account elsewhere.
 ownedSimplexNames :: AgentClient -> NetworkRequestMode -> UserId -> [SMPServer] -> Address -> Word32 -> AE (SMPServer, OwnedNames)
 ownedSimplexNames c nm userId used addr offset = withAgentEnv c $ ownedSimplexNames' c nm userId used addr offset
 {-# INLINE ownedSimplexNames #-}
@@ -1286,8 +1285,7 @@ ownedSimplexNames' c nm userId used addr offset = tryRelays ownedNamesRelays use
       srv <- getNextNameServer c userId tried
       ((srv,) <$> ownedNames c nm userId srv addr offset) `catchError` \e ->
         if attempts > 1 && cannotAnswer e then tryRelays (attempts - 1) (srv : tried) else throwE e
-    -- a relay that cannot answer, as against one that answers: too old for ROWN,
-    -- unreachable, or with no resolver of its own behind it
+    -- cannot answer, as against answers: too old for ROWN, unreachable, or with no resolver
     cannotAnswer e = temporaryOrHostError e || case e of
       SMP _ (NAME _) -> True
       _ -> False

src/Simplex/Messaging/Agent/Client.hs

@@ -2032,8 +2032,7 @@ resolveName c nm userId server domain =
     resolveViaProxy smp proxySess = proxyResolveName smp nm proxySess domain
     resolveDirectly smp = directResolveName smp nm domain
 
--- | Names an address owns, from one names-capable relay. Mirrors resolveName:
--- proxied where the network config allows it, direct otherwise.
+-- | Names an address owns, from one names-capable relay, proxied as resolveName is.
 ownedNames :: AgentClient -> NetworkRequestMode -> UserId -> SMPServer -> Address -> Word32 -> AM OwnedNames
 ownedNames c nm userId server addr offset =
   snd <$> sendOrProxySMPCommand c nm userId server "" "ROWN" NoEntity ownedViaProxy ownedDirectly
@@ -2044,8 +2043,7 @@ ownedNames c nm userId server addr offset =
 -- | Pick a names-capable server for the user (the agent owns server selection,
 -- accounting for the names role). nameSrvs is opt-in (a plain list); empty means
 -- no server resolves names - a declared agent error, never a fallback.
--- Servers already used are avoided where the set allows, operator first: one
--- operator asked about every account of a scan learns they are one wallet.
+-- Used servers are avoided where the set allows, operator first: one operator asked about every account learns the wallet.
 getNextNameServer :: AgentClient -> UserId -> [SMPServer] -> AM SMPServer
 getNextNameServer c userId usedSrvs =
   liftIO (TM.lookupIO userId (userServers c :: TMap UserId (UserServers 'PSMP))) >>= \case

src/Simplex/Messaging/Client.hs

@@ -1081,9 +1081,7 @@ directResolveName c nm name
         r -> throwE $ unexpectedResponse r
   | otherwise = throwE $ PCETransportError TEVersion
 
--- | Names an address owns, via PFWD, when the network config selects a proxy. A
--- scan reveals which accounts belong to one wallet, so hiding the client IP
--- matters more here than for one name.
+-- | Names an address owns, via PFWD: a scan links accounts, so hiding the client IP matters more here than for one name.
 proxyOwnedNames :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> Address -> Word32 -> ExceptT SMPClientError IO (Either ProxyClientError OwnedNames)
 proxyOwnedNames c nm proxiedRelay addr offset
   | prVersion proxiedRelay >= nameOwnedSMPVersion =

src/Simplex/Messaging/Server.hs

@@ -1513,7 +1513,6 @@ client
     resolverMsg v nenv = \case
       RSLV d -> resolveNameMsg v nenv d
       ROWN addr offset -> ownedNamesMsg nenv addr offset
-    -- Forked for the same reason as RSLV: one owned-by is many eth_calls.
     ownedNamesMsg :: NamesEnv -> Address -> Word32 -> M s BrokerMsg
     ownedNamesMsg nenv addr offset = do
       st <- asks (rslvStats . serverStats)

src/Simplex/Messaging/Server/Names/HttpResolver.hs

@@ -120,8 +120,7 @@ resolveHttp env q =
   (>>= first InvalidJson . J.eitherDecodeStrict . BL.toStrict)
     <$> httpGet env ("/v2/resolve/" <> B.unpack (urlEncode True (encodeUtf8 q)))
 
--- | The address is EIP-55 hex, which is already URL-safe, but it is encoded
--- for the same reason the name is: nothing from a client reaches the path raw.
+-- | The address is encoded for the same reason the name is: nothing from a client reaches the path raw.
 ownedByHttp :: ResolverEnv -> Text -> Word32 -> IO (Either ResolverError OwnedNames)
 ownedByHttp env addr offset =
   (>>= first InvalidJson . J.eitherDecodeStrict . BL.toStrict)

src/Simplex/Messaging/Transport.hs

@@ -220,8 +220,7 @@ serverInfoSMPVersion = VersionSMP 21
 nameAvailSMPVersion :: VersionSMP
 nameAvailSMPVersion = VersionSMP 22
 
--- | ROWN lists the names an address owns. A server below this does not answer
--- it, which a recovery scan must not read as the address owning nothing.
+-- | ROWN lists the names an address owns; below this a server does not answer it, which is not the same as owning nothing.
 nameOwnedSMPVersion :: VersionSMP
 nameOwnedSMPVersion = VersionSMP 23
 
@@ -240,10 +239,7 @@ currentServerSMPRelayVersion = VersionSMP 23
 -- Max SMP protocol version to be used in e2e encrypted connection between
 -- client and server, as defined by SMP proxy. Normally set below the current
 -- version to prevent client version fingerprinting by the destination relays
--- when clients upgrade at different times. Pinned to the current version (23)
--- for this release because a proxied ROWN is only answered from
--- nameOwnedSMPVersion (23), and a scan that cannot proxy exposes its address
--- to the relay; the buffer reappears once the current version advances past 23.
+-- when clients upgrade at different times. Pinned to the current version (23) because a proxied ROWN needs it, and the buffer returns once current passes 23.
 proxiedSMPRelayVersion :: VersionSMP
 proxiedSMPRelayVersion = VersionSMP 23
 

tests/AgentTests/ResolveNameTests.hs

@@ -101,8 +101,7 @@ resolveNameTests = do
   describe "owned names" $
     it "a relay that cannot answer is not the end of the lookup" testOwnedRetriesRelays
 
--- | A relay too old for ROWN, unreachable, or with no resolver behind it must
--- not end a recovery scan at the account it was asked about.
+-- | A relay that cannot answer must not end a scan at the account it was asked about.
 testOwnedRetriesRelays :: HasCallStack => IO ()
 testOwnedRetriesRelays =
   withDirectResolverReqs (status502, "{}") $ \c reqs -> do

tests/NamesResolverServer.hs

@@ -47,8 +47,7 @@ withResolverServerDelayed delayMs handler action = do
       let (st, body) = handler (pathInfo req)
       send $ responseLBS st [(hContentType, "application/json")] body
 
--- | The resolver API is versioned on its own: v2 answers a name with
--- NameRegistration JSON, and an address with OwnedNames.
+-- | The resolver API is versioned on its own: v2 answers a name with NameRegistration, an address with OwnedNames.
 resolveResp :: Status -> LB.ByteString -> [Text] -> (Status, LB.ByteString)
 resolveResp st body = \case
   ["health"] -> (ok200, "{}")

tests/RSLVTests.hs

@@ -135,8 +135,7 @@ testRslvBackendHttpErr =
       (_, _, resp) <- sendRslv h "rs05" (domain "alice.simplex")
       resp `shouldBe` Right (ERR (NAME (RESOLVER "HTTP 502")))
 
--- | The scan reads inUse, so an account in use with no names must not arrive
--- looking the same as one that owns nothing.
+-- | The scan reads inUse, so in use with no names must not look like owning nothing.
 testRownOwned :: IO ()
 testRownOwned =
   withResolverServer (status200, ownedBody) $
@@ -149,8 +148,7 @@ testRownOwned =
           ownInUse owned `shouldBe` True
         r -> expectationFailure $ "unexpected " <> show r
 
--- A resolver that does not serve owned-by answers 404, which must reach the
--- client as a resolver error: read as "owns nothing" it would end a scan early.
+-- 404 must reach the client as a resolver error; read as "owns nothing" it would end a scan early.
 testRownUnsupported :: IO ()
 testRownUnsupported =
   withResolverServer (status404, "{}") $
@@ -218,8 +216,7 @@ testRslvForwardedSuccess =
       Right (Right NameResponse {registration = NRRegistered {nameRecord}}) -> nameRecord `shouldBe` testNameRecord
       _ -> expectationFailure $ "expected Right (Right NRRegistered), got: " <> show r
 
--- | Without this the scan has to fall back to a direct session, handing the
--- relay the address together with the client IP.
+-- | Without this a scan falls back to a direct session, handing the relay the address with the IP.
 testRownForwarded :: IO ()
 testRownForwarded =
   withProxyAndResolver (status200, ownedBody) $