agent: ConnectTarget type for connection link or SimpleX name

protocol/simplex-messaging.md

@@ -1493,14 +1493,23 @@ name = %s"NAME" SP json-bytes   ; json-bytes consumes the remainder of the trans
 
 | Field | JSON type | Constraints |
 |---|---|---|
-| `displayName` | string | ≤ 255 bytes UTF-8 |
+| `name` | string | ≤ 255 bytes UTF-8 |
+| `nickname` | string or null | ≤ 255 bytes UTF-8; senders MUST emit `null` when unset; receivers MUST also accept absent keys as unset |
+| `website` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
+| `location` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
+| `simplex.contact` | string or null | ≤ 1024 bytes UTF-8; same null / absent rules |
+| `simplex.channel` | string or null | ≤ 1024 bytes UTF-8; same null / absent rules |
+| `ETH` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
+| `BTC` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
+| `XMR` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
+| `DOT` | string or null | ≤ 255 bytes UTF-8; same null / absent rules |
 | `owner` | string | `"0x"` followed by 40 lowercase hex characters (20 raw bytes) |
-| `channelLinks` | array of strings | each ≤ 1024 bytes UTF-8; combined count of `channelLinks + contactLinks` ≤ 8 |
-| `contactLinks` | array of strings | each ≤ 1024 bytes UTF-8; combined count cap shared with `channelLinks` |
-| `adminAddress` | string or null | ≤ 255 bytes UTF-8; senders MUST emit `null` when unset; receivers MUST also accept absent keys as unset |
-| `adminEmail` | string or null | ≤ 255 bytes UTF-8; senders MUST emit `null` when unset; receivers MUST also accept absent keys as unset |
-| `expiry` | integer | Int64 Unix seconds, MUST be ≥ 0; `0` means "never expires" |
-| `isTest` | boolean | true on testnet deployments |
+| `resolver` | string | `"0x"` followed by 40 lowercase hex characters; the SNRC contract address that produced the record |
+
+The server MUST filter expired records before constructing the response
+(returning `ERR AUTH` to the client), so the wire format carries no expiry
+field. Testnet-vs-mainnet status is derived from the queried TLD rather than
+an in-record flag.
 
 Receivers MUST tolerate extra unknown fields (forward-compatibility for future
 field additions). Adding a required field is a breaking change requiring an
@@ -1511,8 +1520,8 @@ producing the same `NameRecord` MUST emit byte-identical JSON: emit object
 keys in the order listed above, integers without decimal points, no
 insignificant whitespace.
 
-**Wire-size budget.** A maximal `nameRecord` (8 × 1024-byte links plus
-maximal admin / display strings) JSON-encodes to roughly 9 KB, well under the
+**Wire-size budget.** A maximal `nameRecord` (two 1024-byte SimpleX links
+plus the other capped strings) JSON-encodes to roughly 4 KB, well under the
 SMP proxied transmission budget of 16224 bytes.
 
 ## Transport connection with the SMP router

simplexmq.cabal

@@ -130,6 +130,8 @@ library
       Simplex.Messaging.Crypto.ShortLink
       Simplex.Messaging.Encoding
       Simplex.Messaging.Encoding.String
+      Simplex.Messaging.Names.Owner
+      Simplex.Messaging.Names.Record
       Simplex.Messaging.Notifications.Client
       Simplex.Messaging.Notifications.Protocol
       Simplex.Messaging.Notifications.Transport
@@ -142,6 +144,7 @@ library
       Simplex.Messaging.Server.QueueStore.QueueInfo
       Simplex.Messaging.ServiceScheme
       Simplex.Messaging.SimplexName
+      Simplex.Messaging.SimplexName.Contracts
       Simplex.Messaging.Session
       Simplex.Messaging.SystemTime
       Simplex.Messaging.TMap
@@ -496,10 +499,12 @@ test-suite simplexmq-test
       AgentTests.EqInstances
       AgentTests.FunctionalAPITests
       AgentTests.MigrationTests
+      AgentTests.ResolveNameTests
       AgentTests.ServerChoice
       AgentTests.ShortLinkTests
       CLITests
       CoreTests.BatchingTests
+      CoreTests.ConnectTargetTests
       CoreTests.CryptoFileTests
       CoreTests.CryptoTests
       CoreTests.EncodingTests
@@ -512,6 +517,7 @@ test-suite simplexmq-test
       CoreTests.VersionRangeTests
       FileDescriptionTests
       RemoteControl
+      RSLVTests
       ServerTests
       SMPAgentClient
       SMPClient

src/Simplex/Messaging/Agent.hs

@@ -65,6 +65,7 @@ module Simplex.Messaging.Agent
     setConnShortLink,
     deleteConnShortLink,
     getConnShortLink,
+    resolveSimplexName,
     getConnLinkPrivKey,
     deleteLocalInvShortLink,
     changeConnectionUser,
@@ -216,6 +217,7 @@ import Simplex.Messaging.Protocol
     ErrorType (AUTH),
     MsgBody,
     MsgFlags (..),
+    NameRecord,
     NtfServer,
     ProtoServerWithAuth (..),
     ProtocolServer (..),
@@ -237,6 +239,7 @@ import Simplex.Messaging.Protocol
   )
 import qualified Simplex.Messaging.Protocol as SMP
 import Simplex.Messaging.ServiceScheme (ServiceScheme (..))
+import Simplex.Messaging.SimplexName.Contracts (tldContract)
 import Simplex.Messaging.SystemTime
 import qualified Simplex.Messaging.TMap as TM
 import Simplex.Messaging.Transport (SMPVersion, THClientService' (..), THandleAuth (..), THandleParams (..))
@@ -440,6 +443,13 @@ getConnShortLink :: AgentClient -> NetworkRequestMode -> UserId -> ConnShortLink
 getConnShortLink c = withAgentEnv c .:. getConnShortLink' c
 {-# INLINE getConnShortLink #-}
 
+-- | Resolve a SimpleX name via the configured resolver SMP server (PFWD RSLV).
+-- The TLD->contract whitelist lives in the agent so chat clients only need to
+-- pass the resolver address and the parsed domain.
+resolveSimplexName :: AgentClient -> NetworkRequestMode -> UserId -> SMPServer -> SimplexNameDomain -> AE NameRecord
+resolveSimplexName c = withAgentEnv c .:: resolveSimplexName' c
+{-# INLINE resolveSimplexName #-}
+
 getConnLinkPrivKey :: AgentClient -> ConnId -> AE (Maybe C.PrivateKeyEd25519)
 getConnLinkPrivKey c = withAgentEnv c . getConnLinkPrivKey' c
 {-# INLINE getConnLinkPrivKey #-}
@@ -1182,6 +1192,11 @@ getConnShortLink' c nm userId = \case
 deleteLocalInvShortLink' :: AgentClient -> ConnShortLink 'CMInvitation -> AM ()
 deleteLocalInvShortLink' c (CSLInvitation _ srv linkId _) = withStore' c $ \db -> deleteInvShortLink db srv linkId
 
+resolveSimplexName' :: AgentClient -> NetworkRequestMode -> UserId -> SMPServer -> SimplexNameDomain -> AM NameRecord
+resolveSimplexName' c nm userId resolverSrv domain = case tldContract (nameTLD domain) of
+  Nothing -> throwE $ INTERNAL "resolveSimplexName: no resolver contract for TLD"
+  Just contract -> resolveName c nm userId resolverSrv contract (fullDomainName domain)
+
 changeConnectionUser' :: AgentClient -> UserId -> ConnId -> UserId -> AM ()
 changeConnectionUser' c oldUserId connId newUserId = do
   SomeConn _ conn <- withStore c (`getConn` connId)

src/Simplex/Messaging/Agent/Client.hs

@@ -68,6 +68,7 @@ module Simplex.Messaging.Agent.Client
     deleteQueueLink,
     secureGetQueueLink,
     getQueueLink,
+    resolveName,
     enableQueueNotifications,
     EnableQueueNtfReq (..),
     enableQueuesNtfs,
@@ -267,6 +268,8 @@ import Simplex.Messaging.Protocol
     NetworkError (..),
     MsgFlags (..),
     MsgId,
+    NameOwner,
+    NameRecord,
     NtfServer,
     NtfServerWithAuth,
     ProtoServer,
@@ -1990,6 +1993,17 @@ getQueueLink c nm userId server lnkId =
     getViaProxy smp proxySess = proxyGetSMPQueueLink smp nm proxySess lnkId
     getDirectly smp = getSMPQueueLink smp nm lnkId
 
+-- | Resolve a public-namespace name. Prefers PFWD (hides client IP from the
+-- resolver) and falls back to a direct send when the proxy is unavailable
+-- (faster but exposes the client IP). Mode selection is delegated to
+-- `sendOrProxySMPCommand`, which honours the network config (SPMNever etc.).
+resolveName :: AgentClient -> NetworkRequestMode -> UserId -> SMPServer -> NameOwner -> Text -> AM NameRecord
+resolveName c nm userId server contract name =
+  snd <$> sendOrProxySMPCommand c nm userId server "" "RSLV" NoEntity resolveViaProxy resolveDirectly
+  where
+    resolveViaProxy smp proxySess = proxyResolveName smp nm proxySess contract name
+    resolveDirectly smp = directResolveName smp nm contract name
+
 enableQueueNotifications :: AgentClient -> RcvQueue -> SMP.NtfPublicAuthKey -> SMP.RcvNtfPublicDhKey -> AM (SMP.NotifierId, SMP.RcvNtfPublicDhKey)
 enableQueueNotifications c rq@RcvQueue {rcvId, rcvPrivateKey} notifierKey rcvNtfPublicDhKey =
   withSMPClient c NRMBackground rq "NKEY <nkey>" $ \smp ->

src/Simplex/Messaging/Agent/Protocol.hs

@@ -122,6 +122,7 @@ module Simplex.Messaging.Agent.Protocol
     OwnerId,
     ConnectionLink (..),
     AConnectionLink (..),
+    ConnectTarget (..),
     SimplexNameInfo (..),
     SimplexNameDomain (..),
     SimplexTLD (..),
@@ -195,6 +196,7 @@ import qualified Data.Aeson.TH as J
 import qualified Data.Aeson.Types as JT
 import Data.Attoparsec.ByteString.Char8 (Parser)
 import qualified Data.Attoparsec.ByteString.Char8 as A
+import Data.Attoparsec.Combinator (lookAhead)
 import qualified Data.ByteString.Base64.URL as B64
 import Data.ByteString.Char8 (ByteString)
 import qualified Data.ByteString.Char8 as B
@@ -1596,6 +1598,24 @@ instance ToJSON AConnectionLink where
 instance FromJSON AConnectionLink where
   parseJSON = strParseJSON "AConnectionLink"
 
+data ConnectTarget = CTLink AConnectionLink | CTName SimplexNameInfo
+  deriving (Eq, Show)
+
+instance StrEncoding ConnectTarget where
+  strEncode = \case
+    CTLink l -> strEncode l
+    CTName n -> strEncode n
+  strP = CTName <$> (lookAhead nameStart *> strP) <|> CTLink <$> strP
+    where
+      nameStart = "@" <|> "#" <|> "simplex:/name"
+
+instance ToJSON ConnectTarget where
+  toEncoding = strToJEncoding
+  toJSON = strToJSON
+
+instance FromJSON ConnectTarget where
+  parseJSON = strParseJSON "ConnectTarget"
+
 instance ConnectionModeI m => StrEncoding (ConnShortLink m) where
   strEncode = \case
     CSLInvitation sch srv (SMP.EntityId lnkId) (LinkKey k) -> slEncode sch srv 'i' lnkId k

src/Simplex/Messaging/Client.hs

@@ -73,6 +73,8 @@ module Simplex.Messaging.Client
     deleteSMPQueues,
     connectSMPProxiedRelay,
     proxySMPMessage,
+    proxyResolveName,
+    directResolveName,
     forwardSMPTransmission,
     getSMPQueueInfo,
     sendProtocolCommand,
@@ -1046,6 +1048,26 @@ sendSMPMessage c nm spKey sId flags msg =
 proxySMPMessage :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> Maybe SndPrivateAuthKey -> SenderId -> MsgFlags -> MsgBody -> ExceptT SMPClientError IO (Either ProxyClientError ())
 proxySMPMessage c nm proxiedRelay spKey sId flags msg = proxyOKSMPCommand c nm proxiedRelay spKey sId (SEND flags msg)
 
+-- | Resolve a public-namespace name via PFWD. Preferred path - hides the
+-- client IP from the resolver. Mirrors `proxySMPMessage`'s shape; routes
+-- through `proxySMPCommand` and pattern-matches the expected NAME response.
+proxyResolveName :: SMPClient -> NetworkRequestMode -> ProxiedRelay -> NameOwner -> Text -> ExceptT SMPClientError IO (Either ProxyClientError NameRecord)
+proxyResolveName c nm proxiedRelay contract name =
+  proxySMPCommand c nm proxiedRelay Nothing NoEntity (RSLV RslvRequest {name, contract}) >>= \case
+    Right (NAME nr) -> pure $ Right nr
+    Right r -> throwE $ unexpectedResponse r
+    Left e -> pure $ Left e
+
+-- | Direct (non-PFWD) name resolution. Exposes the client IP to the resolver;
+-- callers that want anonymity should use `proxyResolveName` via the standard
+-- proxy fallback in the agent. RSLV requires no entity ID or authorization
+-- (see `noAuthCmd` in Protocol.hs).
+directResolveName :: SMPClient -> NetworkRequestMode -> NameOwner -> Text -> ExceptT SMPClientError IO NameRecord
+directResolveName c nm contract name =
+  sendProtocolCommand c nm Nothing NoEntity (Cmd SResolver (RSLV RslvRequest {name, contract})) >>= \case
+    NAME nr -> pure nr
+    r -> throwE $ unexpectedResponse r
+
 -- | Acknowledge message delivery (server deletes the message).
 --
 -- https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md#acknowledge-message-delivery

src/Simplex/Messaging/Names/Owner.hs

@@ -0,0 +1,46 @@
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE StrictData #-}
+
+module Simplex.Messaging.Names.Owner
+  ( NameOwner,
+    mkNameOwner,
+    unNameOwner,
+  )
+where
+
+import Control.Applicative ((<|>))
+import qualified Data.Aeson as J
+import qualified Data.ByteArray.Encoding as BAE
+import Data.ByteString.Char8 (ByteString)
+import qualified Data.ByteString.Char8 as B
+import Data.Maybe (fromMaybe)
+import qualified Data.Text as T
+import Data.Text.Encoding (decodeLatin1, encodeUtf8)
+
+-- | 20-byte Ethereum address (NameRecord owner). Bare constructor not exported;
+-- use `mkNameOwner` to enforce the 20-byte invariant.
+newtype NameOwner = NameOwner ByteString
+  deriving (Eq)
+
+-- Render the 20 raw bytes as "0x"-prefixed lowercase hex so log lines /
+-- traceShow output match the on-the-wire JSON form instead of Latin-1 garbage.
+instance Show NameOwner where
+  show (NameOwner bs) = "NameOwner 0x" <> B.unpack (BAE.convertToBase BAE.Base16 bs)
+
+mkNameOwner :: ByteString -> Either String NameOwner
+mkNameOwner bs
+  | B.length bs == 20 = Right (NameOwner bs)
+  | otherwise = Left "NameOwner must be 20 bytes"
+
+unNameOwner :: NameOwner -> ByteString
+unNameOwner (NameOwner bs) = bs
+{-# INLINE unNameOwner #-}
+
+instance J.ToJSON NameOwner where
+  toJSON (NameOwner bs) = J.String $ "0x" <> decodeLatin1 (BAE.convertToBase BAE.Base16 bs)
+
+instance J.FromJSON NameOwner where
+  parseJSON = J.withText "NameOwner" $ \t -> do
+    -- Accept "0x" and "0X" prefixes (matches the Server-side hex decoder).
+    let hex = fromMaybe t (T.stripPrefix "0x" t <|> T.stripPrefix "0X" t)
+    either fail pure $ BAE.convertFromBase BAE.Base16 (encodeUtf8 hex) >>= mkNameOwner

src/Simplex/Messaging/Names/Record.hs

@@ -0,0 +1,91 @@
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE StrictData #-}
+{-# LANGUAGE TemplateHaskell #-}
+
+module Simplex.Messaging.Names.Record
+  ( NameRecord (..),
+  )
+where
+
+import qualified Data.Aeson as J
+import qualified Data.Aeson.TH as JQ
+import qualified Data.ByteString.Char8 as B
+import Data.Text (Text)
+import Data.Text.Encoding (encodeUtf8)
+import Simplex.Messaging.Names.Owner (NameOwner)
+import Simplex.Messaging.Parsers (defaultJSON)
+
+-- | Resolved name record returned by the names role.
+--   Wire format is JSON — change requires an SMP version bump.
+--   JSON keys match the Python resolver (PR #1795 `snrc-resolve.py`) so the
+--   same server can be backed by either the direct-ETH-RPC resolver or the
+--   Python REST resolver without changing the wire format clients see.
+data NameRecord = NameRecord
+  { nrName :: Text,
+    nrNickname :: Maybe Text,
+    nrWebsite :: Maybe Text,
+    nrLocation :: Maybe Text,
+    nrSimplexContact :: Maybe Text,
+    nrSimplexChannel :: Maybe Text,
+    nrEth :: Maybe Text,
+    nrBtc :: Maybe Text,
+    nrXmr :: Maybe Text,
+    nrDot :: Maybe Text,
+    nrOwner :: NameOwner,
+    nrResolver :: NameOwner -- SNRC contract address that produced the record
+  }
+  deriving (Eq, Show)
+
+-- ToJSON / toEncoding are TH-derived from a single Options value so both Aeson
+-- paths emit byte-identical output in declaration order. The default
+-- fieldLabelModifier cannot express dot-keys ("simplex.contact",
+-- "simplex.channel") or uppercase coin keys ("ETH", "BTC", "XMR", "DOT").
+-- omitNothingFields is set to False to preserve the previous hand-rolled
+-- shape (absent optionals emitted as JSON `null`); FromJSON tolerates both
+-- missing and null keys for forward-compat with sparse Python output.
+-- Options inlined at the splice site because TH stage restriction forbids a
+-- module-local helper.
+$( JQ.deriveToJSON
+    defaultJSON
+      { J.omitNothingFields = False,
+        J.fieldLabelModifier = \case
+          "nrName" -> "name"
+          "nrNickname" -> "nickname"
+          "nrWebsite" -> "website"
+          "nrLocation" -> "location"
+          "nrSimplexContact" -> "simplex.contact"
+          "nrSimplexChannel" -> "simplex.channel"
+          "nrEth" -> "ETH"
+          "nrBtc" -> "BTC"
+          "nrXmr" -> "XMR"
+          "nrDot" -> "DOT"
+          "nrOwner" -> "owner"
+          "nrResolver" -> "resolver"
+          s -> s
+      }
+    ''NameRecord
+ )
+
+-- FromJSON is hand-rolled to enforce per-field UTF-8 byte-length caps that the
+-- TH derivation cannot express.
+instance J.FromJSON NameRecord where
+  parseJSON = J.withObject "NameRecord" $ \o -> do
+    nrName <- o J..: "name" >>= capUtf8 "name" 255
+    nrNickname <- o J..:? "nickname" >>= traverse (capUtf8 "nickname" 255)
+    nrWebsite <- o J..:? "website" >>= traverse (capUtf8 "website" 255)
+    nrLocation <- o J..:? "location" >>= traverse (capUtf8 "location" 255)
+    nrSimplexContact <- o J..:? "simplex.contact" >>= traverse (capUtf8 "simplex.contact" 1024)
+    nrSimplexChannel <- o J..:? "simplex.channel" >>= traverse (capUtf8 "simplex.channel" 1024)
+    nrEth <- o J..:? "ETH" >>= traverse (capUtf8 "ETH" 255)
+    nrBtc <- o J..:? "BTC" >>= traverse (capUtf8 "BTC" 255)
+    nrXmr <- o J..:? "XMR" >>= traverse (capUtf8 "XMR" 255)
+    nrDot <- o J..:? "DOT" >>= traverse (capUtf8 "DOT" 255)
+    nrOwner <- o J..: "owner"
+    nrResolver <- o J..: "resolver"
+    pure NameRecord {nrName, nrNickname, nrWebsite, nrLocation, nrSimplexContact, nrSimplexChannel, nrEth, nrBtc, nrXmr, nrDot, nrOwner, nrResolver}
+    where
+      capUtf8 fld lim t
+        | B.length (encodeUtf8 t) <= lim = pure t
+        | otherwise = fail $ fld <> " exceeds " <> show lim <> " bytes UTF-8"