Agent Name System (ANS)

1.1. Problem Statement

Agents in a decentralized network need stable, human-readable names that can be resolved to the cryptographic peer identifiers used for datagram delivery. The Agent Internet Protocol (AIP) [I-D.song-anp-aip] defines agent:// URIs as the addressing scheme for datagrams, but AIP itself does not specify how a name such as "agent://translator-zh-en" is bound to a particular peer or how that binding is disseminated across the network.¶

Without a name system, agents must exchange raw cryptographic peer identifiers — opaque strings that are neither memorable nor semantic. A name system provides the indirection layer that allows agent names to persist across peer-identity rotations, enables human operators to refer to agents by meaningful labels, and supports anycast routing where a single name resolves to the best available instance.¶

1.2. Scope

This document is one of four core Internet-Drafts in the Agent Network Protocol (ANP) suite: AIP [I-D.song-anp-aip] (datagram delivery), AITP [I-D.song-anp-aitp] (invocation transport), ANS (this document, name system), and ADP [I-D.song-anp-adp] (description and discovery). The four drafts are designed to co-evolve as a self-contained protocol suite; no additional specification is required for baseline interoperability. AIP's local-resolver semantic extension MAY be backed by an implementation that consults ADP discovery services for ranked capability matching; ANS core provides name-to-peer binding but does not itself perform ranked semantic discovery.¶

ANS is a name-layer protocol within the ANP suite. It sits between the human-facing name space and the peer-identity layer used by AIP.¶

This document specifies:¶

1. The agent:// URI syntax as used by ANS, refining the base grammar defined in AIP with namespace, version, and addressing-mode semantics. AIP remains the scheme authority ([I-D.song-anp-aip]); ANS defines name-layer interpretation only.¶
2. The Name Record format — a JSON object that binds an agent:// name to a peer identifier, skill tags, and temporal metadata.¶
3. Four AITP method names (ans.register, ans.resolve, ans.unregister, ans.lookup) for name operations over the Agent Invocation Transport Protocol (AITP) [I-D.song-anp-aitp].¶
4. A multi-layer resolution algorithm (local cache, persistent store, DHT, peer-assisted query).¶
5. Two dissemination mechanisms: GossipSub announcements for real-time propagation and DHT records for persistent storage.¶
6. The name lifecycle: registration, freshness, renewal, ownership, transfer, expiration, and release.¶

This document does not cover:¶

1. Agent capability description — specified by the Agent Description Protocol (ADP) [I-D.song-anp-adp].¶
2. Ranked capability discovery — the five-factor scoring algorithm is defined in ADP [I-D.song-anp-adp].¶
3. Economic mechanisms for name registration (token burn, auction, pricing) — these are deployment-specific policies.¶
4. DNS-based discovery (DNS-SD, well-known URIs) — discussed informatively in Appendix A.¶
5. Agent identity, key management, or credential issuance — these belong to AIP and deployment- context mechanisms.¶

1.3. Positioning

ANS is to agent:// URIs what DNS is to domain names: a name-to-address resolution service. ANS differs from DNS in three respects: (1) registrations are self-certified via Ed25519 signatures rather than delegated to registrars; (2) resolution is peer-to-peer (DHT + gossip) rather than hierarchical; (3) the name space supports anycast and channel addressing modes natively. Of these three modes, only unicast and anycast names are registered; channel names are derived from the URI syntax and map deterministically to GossipSub topics without creating a Name Record (see Section 7.4).¶

Unlike ADP's adp.discover, which ranks agents by a multi-factor scoring algorithm, ANS's ans.lookup performs tag-based filtering without scoring — a narrow-waist lookup analogous to DNS SRV queries. The two protocols are complementary: ANS provides name→peer binding; ADP provides capability→ranking.¶

1.4. Design Rationale

ANS is justified when the following conditions hold:¶

1. Agents need stable, human-readable identifiers.¶

   Cryptographic peer IDs (e.g., 12D3KooW...) are unsuitable for human reference, configuration files, and documentation. A name layer provides stability across peer-ID rotation.¶

2. Multiple resolution paths improve availability.¶

   A single DHT lookup may fail due to network partition. A layered resolution stack (local cache → persistent store → DHT → peer-assisted RPC) maximizes the probability of successful resolution.¶

3. Anycast requires a name-to-set mapping.¶

   When multiple instances serve the same logical service, the name system must resolve a single name to a set of candidates. Instance selection is then delegated to the caller or to a companion ranking protocol (ADP).¶

1.5. Assumptions

ANS assumes:¶

1. An AIP module providing agent:// datagram delivery with Ed25519-signed peer identities.¶
2. An AITP module capable of REQUEST/RESPONSE exchanges with the method names defined in this document.¶
3. A GossipSub implementation supporting topic-based pub/sub (e.g., libp2p GossipSub v1.1).¶
4. A Kademlia DHT implementation supporting namespace-prefixed key-value storage.¶
5. Name Record documents are UTF-8 encoded JSON ([RFC8259]).¶

1.6. Relationship to Adjacent Specifications

ANS occupies a narrow role in the ANP suite. This section clarifies the boundary between ANS and its sibling protocols to prevent misattribution of responsibilities.¶

Agent Internet Protocol (AIP) [I-D.song-anp-aip]

AIP owns the agent:// URI scheme registration, the Ed25519 peer-identity model, and datagram delivery. ANS consumes the URI scheme and peer identities defined by AIP; it does not redefine them. The ABNF in Section 3.1 is a name-layer profile of the AIP base grammar, adding namespace, instance, and channel semantics for registration and resolution. The agent:// URI scheme registration belongs to AIP, not ANS.¶

Agent Invocation Transport Protocol (AITP) [I-D.song-anp-aitp]

AITP provides the reliable REQUEST/RESPONSE transport over which ANS method calls are carried. AITP is a pure bearer: it provides segment framing, flow control, and status codes, but has no awareness of name semantics. ANS defines its own method names (ans.*) and error detail bodies; AITP carries them unchanged.¶

Agent Description Protocol (ADP) [I-D.song-anp-adp]

ADP defines Agent Cards (rich capability descriptions) and the adp.discover method (five-factor ranked discovery). ANS provides the narrower primitive: name-to-peer binding and tag-based lookup without scoring. The two protocols are complementary — ANS resolves names, ADP ranks capabilities — and SHOULD be deployed together.¶

Web-Native Discovery Profiles

DNS-SD ([RFC6763]), .well-known URIs ([RFC8615]), and mDNS ([RFC6762]) are informative bridging mechanisms described in Appendix A. They are deployment profiles, not part of the ANS core protocol. An ANS implementation is fully conformant without supporting any web- native discovery profile.¶

1.7. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3.1. ABNF Grammar

The following ABNF ([RFC5234]) defines the syntax of agent:// URIs. The grammar uses the core rules from [RFC5234] Appendix B and the generic URI components from [RFC3986].¶

agent-uri     = "agent://" agent-path [ "@" version ]
agent-path    = service-path / channel-path

; Service addressing (unicast or anycast)
service-path  = [ namespace "/" ] name [ "/" instance ]

; Channel addressing (trailing "/" required)
channel-path  = [ namespace "/" ] name "/"

namespace     = identifier
name          = identifier
instance      = identifier
version       = 1*( ALPHA / DIGIT / "." / "-" )

identifier    = lo-alpha-digit *( lo-alpha-digit / "-" )
lo-alpha-digit = %x61-7A / DIGIT   ; a-z / 0-9

Constraints:¶

• Each "identifier" segment MUST be 1 to 63 octets.¶
• The total agent-path (excluding "agent://") MUST NOT exceed 255 octets, matching the AIP MaxURILen.¶
• Identifiers MUST be lowercase ASCII letters, digits, and hyphens. Underscores are NOT RECOMMENDED; implementations MAY normalize underscores to hyphens on input.¶
• An identifier MUST NOT start or end with a hyphen.¶

3.2. Addressing Modes

An agent:// URI carries one of three addressing modes, determined by syntactic inspection of the path:¶

Implementations MUST detect the addressing mode using the following algorithm:¶

if path ends with "/"           → Channel
else if path contains instance  → Unicast
else                            → Anycast

An agent:// URI with no namespace and no instance (e.g., "agent://translator-zh-en") is Anycast. This preserves backward compatibility with the flat names used by existing implementations.¶

3.3. Examples

# Anycast — route to any available translator
agent://translator-zh-en

# Anycast — namespace-scoped
agent://nlp/translator

# Unicast — specific instance
agent://nlp/translator/zh-en-01

# Unicast — versioned
agent://nlp/translator/zh-en-01@1.2.0

# Channel — multicast to all subscribers
agent://finance/market-updates/

3.4. Normalization

Implementations MUST normalize agent:// URIs before registration, resolution, and comparison by:¶

1. Converting the scheme and all identifier segments to lowercase.¶
2. Removing any trailing whitespace.¶

The normalized form retains the "agent://" prefix. Implementations that need a prefix-stripped key for DHT or database storage MAY derive it internally, but the canonical wire-format value is always the full URI.¶

Two URIs are considered equal if their normalized forms are byte-identical.¶

4.1. Record Fields

4.2. Signature Computation

The signature field authenticates the Name Record and binds it to the registrant's Ed25519 key pair. The signature is computed as follows:¶

1. Construct the signing input by concatenating the following fields in order, each encoded as UTF-8 with a newline (0x0A) separator: name, peer_id, namespace, skills (JSON-serialized array, e.g., '["nlp","translation"]'; empty array '[]' if absent), description, version, ttl (decimal string), registered_at, expires_at, owner_id, seq (decimal string).¶
2. Compute the Ed25519 signature ([RFC8032]) over the signing input using the registrant's private key.¶
3. Encode the 64-byte signature as unpadded Base64url ([RFC4648] §5).¶

Receivers MUST verify the signature before accepting a Name Record. Verification requires the Ed25519 public key corresponding to the peer_id. Implementations MUST reject records whose signature does not verify, whose peer_id does not correspond to the signing key, or whose owner_id does not match the peer_id (for initial registrations) or the stored owner_id (for updates).¶

4.3. Sequence Numbers

The seq field provides replay protection and consistent ordering of Name Record updates.¶

• The initial registration MUST set seq to 1.¶
• Each subsequent update MUST increment seq by at least 1.¶
• Receivers MUST reject a record if its seq is less than or equal to the seq of the currently stored record for the same name.¶
• Receivers MUST reject a record if the seq value is unreasonably large (implementation-defined threshold) to prevent seq-space exhaustion attacks.¶

4.4. Extension Mechanism

The "extensions" field provides a stable mounting point for deployment-specific data that does not belong in the core Name Record. Examples include anti-spam proof tokens, pricing metadata, transfer receipts, and deployment-policy hints.¶

• The value of "extensions" MUST be a JSON object.¶
• Each key within "extensions" SHOULD be a reverse-domain or URN-namespaced identifier to avoid collisions (e.g., "com.example.antispam").¶
• Implementations MUST preserve extension entries they do not understand when re-serializing or relaying a Name Record.¶
• Implementations MUST ignore extension entries they do not understand when processing a Name Record.¶

• The "extensions" object is excluded from the signature computation (Section 4.2). This is an intentional design trade-off: the core name-binding fields (name, peer_id, owner_id, seq, timestamps) are signed and tamper-evident — these fields fully cover the name-to-identity binding and temporal validity, so core record integrity does not depend on extensions. Extensions are left unsigned to allow deployment-local annotations and relay-added metadata (e.g., hop count, ingestion timestamp) that the originator cannot predict at signing time.¶

  Consequently, any peer on the relay path may add, modify, or remove extension entries. Deployment profiles that require stronger integrity for specific extensions SHOULD define an inner signature field within their own extension namespace.¶

4.5. Validation Rules

Implementations MUST validate Name Records on receipt, whether from ans.register requests, GossipSub messages, or DHT retrieval. The following rules apply:¶

Records that fail any MUST-level rule MUST be rejected. Records that fail a SHOULD-level rule SHOULD be accepted after corrective normalization (e.g., deduplicating skills).¶

5.1. ans.register — Register a Name

An agent sends a REQUEST with Method = "ans.register" to bind an agent:// name to its peer identity. Only Unicast and Anycast names may be registered; Channel names are derived from the URI syntax and MUST NOT be submitted to ans.register (see Section 7.4).¶

Request body

A Name Record as defined in Section 4. All MUST fields MUST be present.¶

Response body (Status = OK)

A JSON object with the following fields:¶

• "registered": boolean — true if the record was accepted.¶
• "name": string — the normalized name.¶
• "seq": integer — the accepted sequence number.¶
• "expires_at": string — the accepted expiration timestamp.¶

Error responses

• INVALID_REQUEST (6) — malformed record, invalid signature, or constraint violation (e.g., name syntax, field length).¶
• UNAUTHORIZED (5) — the sender is not the owner of an existing record with the same name.¶
• BUSY (8) — the receiver has reached its capacity for stored Name Records.¶

The receiver MUST perform the following validation before accepting a registration:¶

1. Verify the agent:// name conforms to the ABNF in Section 3.1.¶
2. Verify the Ed25519 signature per Section 4.2.¶
3. If a record with the same name already exists, verify that the request's owner_id matches the stored owner_id and that the request's seq is strictly greater than the stored seq.¶
4. If no record exists, set the owner_id to the sender's peer_id.¶
5. Verify that expires_at is in the future and that ttl is positive.¶

Registration MAY additionally require a deployment-specific anti-spam mechanism such as proof-of-work, token expenditure, or rate limiting. Such mechanisms are outside the scope of this specification.¶

5.2. ans.resolve — Resolve a Name

A caller sends a REQUEST with Method = "ans.resolve" to look up the Name Record(s) bound to an agent:// name.¶

Request body

A JSON object with the following fields:¶

• "name": string (MUST) — the full agent:// URI to resolve.¶

Response body (Status = OK)

A JSON object with a uniform envelope containing three fields:¶

• "mode": string (MUST) — one of "unicast", "anycast", or "channel".¶
• "records": array (MUST) — matching Name Records. For Unicast: at most one element. For Anycast: zero or more elements, ordered by seq descending. For Channel: empty array.¶
• "topic": string or null (MUST) — the GossipSub topic string for Channel mode; null for Unicast and Anycast.¶
• "source": string (MAY) — when present, indicates the resolution layer that produced the result. Values are drawn from: "local" (in-memory cache), "store" (persistent database), "dht" (Kademlia DHT), "peer" (peer-assisted RPC). Omitted if unknown.¶

Error responses

INVALID_REQUEST (6) if the name is malformed.¶

If the receiver does not have the requested record in its local store, it MAY attempt resolution via the DHT or peer-assisted query before returning an empty records array.¶

5.3. ans.unregister — Remove a Name

An agent sends a REQUEST with Method = "ans.unregister" to remove its Name Record.¶

Request body

A JSON object with the following fields:¶

• "name": string (MUST) — the agent:// name to unregister.¶
• "signature": string (MUST) — Ed25519 signature over the UTF-8 string "unregister:" concatenated with the normalized name.¶

Response body (Status = OK)

A JSON object: { "unregistered": true }.¶

Error responses

• UNAUTHORIZED (5) — the sender is not the owner.¶
• INVALID_REQUEST (6) — invalid signature or name not found.¶

The receiver MUST verify that the signature is valid and that the sender's peer_id matches the stored owner_id before removing the record. Upon successful unregistration, the receiver SHOULD propagate the removal via GossipSub (see Section 8.1).¶

5.4. ans.lookup — Tag-Based Name Lookup

A caller sends a REQUEST with Method = "ans.lookup" to find agents by skill tags. Unlike ADP's adp.discover, ans.lookup is a narrow-waist filter: it returns all matching records without scoring or ranking.¶

Request body

A JSON object with the following fields:¶

Table 4: ans.lookup Request Fields

Field	Type	Description
tags	string[]	Skill tags to match (at least one SHOULD be provided).
namespace	string	Optional namespace filter.
limit	integer	Maximum results. Default: 10.

Response body (Status = OK)

A JSON object with a "results" array. Each element contains:¶

• "record": the matching Name Record.¶
• "matched_tags": string[] — tags that contributed to the match.¶

Error responses

INVALID_REQUEST (6) if the query is malformed.¶

A Name Record matches if at least one of the query tags appears in the record's skills array (after normalization). Implementations SHOULD normalize tags to lowercase and apply alias resolution (e.g., "py" → "python") before matching.¶

When the total number of matching records exceeds the AIP maximum message size (65535 octets), implementations SHOULD truncate the result set to "limit" entries and return only complete records that fit within a single response datagram. Callers that need additional results MAY issue subsequent queries with an "offset" parameter (application-level pagination) or use an AITP STREAM exchange for large result sets, as discussed in AITP [I-D.song-anp-aitp].¶

5.5. Method Summary

6.1. Error Detail Envelope

When an ANS method returns an AITP error status, the response body SHOULD include the following JSON object:¶

{
  "code":   "ANS-1002",
  "title":  "invalid-signature",
  "detail": "Ed25519 signature verification failed for
              name 'agent://nlp/translator'.",
  "name":   "agent://nlp/translator"
}

Fields:¶

code

An ANS error code from Table 6. MUST be present.¶

title

A short, stable, machine-readable slug. MUST be present.¶

detail

A human-readable explanation. MAY be present.¶

name

The agent:// name that triggered the error, if applicable. MAY be present.¶

6.2. ANS Error Codes

AITP status codes provide the transport-level disposition (success, client error, server error). ANS error codes provide the protocol-specific reason. A receiver MUST set the AITP status code; it SHOULD include the ANS error detail body for non-OK responses.¶

7.1. Resolution Algorithm

When resolving an agent:// URI, implementations SHOULD attempt the following layers in order, returning the first successful result:¶

1. Layer 1 — Local Memory Cache. Look up the normalized name in the in-memory Name Table (e.g., sync.Map). If a non-expired record is found, return it.¶
2. Layer 2 — Persistent Store. Query the local persistent store (e.g., SQLite) for a non-expired record. If found, populate the L1 cache and return.¶
3. Layer 3 — DHT. Query the DHT at key "/clawnet-ans/{normalized-name}". If a valid, non-expired record is found, store it in L2 and L1 and return.¶
4. Layer 4 — Peer-Assisted Query. Send an ans.resolve request to connected peers in parallel. Accept the first valid response. Store in L2 and L1.¶

If all layers fail, the resolver returns a not-found result.¶

Implementations MAY skip layers or query multiple layers in parallel to reduce latency. The layer order above is RECOMMENDED for the common case.¶

7.2. Unicast Resolution

A Unicast URI (agent://[ns/]name/instance) resolves to exactly one Name Record by exact-matching the full path "{namespace}/{name}/{instance}" or "{name}/{instance}". If no exact match is found, the resolver returns not-found.¶

7.3. Anycast Resolution

An Anycast URI (agent://[ns/]name) resolves to all non-expired Name Records whose name field matches the service name, either by exact match or by prefix match (all records sharing the same namespace and service segments).¶

The resolver returns the full candidate set. Instance selection is the caller's responsibility; callers MAY use ADP's ranked discovery (adp.discover) or any other selection strategy.¶

7.4. Channel Resolution

Channel names are derived, not registered. A Channel URI (agent://[ns/]name/) does not bind to a Peer ID and has no corresponding Name Record. Instead, the resolver deterministically maps the channel name to a GossipSub topic string using the following rule:¶

topic = "/clawnet/channel/" + normalized-channel-path
        (strip trailing "/")

Example:
  agent://finance/market-updates/
  → /clawnet/channel/finance/market-updates

The resolver returns the topic string. The AIP module delivers datagrams to this topic via GossipSub pub/sub.¶

7.5. Cache Behavior

Resolved Name Records SHOULD be cached at both the memory layer (L1) and persistent layer (L2). The cache entry MUST expire no later than the Name Record's expires_at timestamp. Implementations SHOULD also re-resolve after the TTL period to obtain fresher records.¶

When a GossipSub announcement updates or removes a cached name (see Section 8.1), implementations MUST update or invalidate the L1 and L2 cache entries accordingly.¶

8.1. GossipSub Announcements

Name registrations and unregistrations are announced via the GossipSub topic "/clawnet/ans".¶

8.2. DHT Storage

Name Records are stored in the Kademlia DHT under the namespace "clawnet-ans". The DHT key for a Name Record is:¶

key = "/clawnet-ans/" + normalized-name

The DHT value is the UTF-8 JSON serialization of the Name Record. DHT put and get operations MUST validate the signature and sequence number using the same rules as GossipSub validation (Section 8.1.2).¶

DHT implementations SHOULD set a record expiration aligned with the Name Record's expires_at field. When a DHT get returns an expired record, the resolver MUST treat it as not found.¶

8.3. Peer-Assisted Resolution

When Layers 1-3 of the resolution algorithm fail, the resolver MAY send ans.resolve requests to currently connected peers in parallel. This is Layer 4 of the resolution stack.¶

Implementations SHOULD apply the following constraints to peer-assisted resolution:¶

• A timeout of 5 seconds per peer query.¶
• Accept the first valid response (first-wins strategy).¶
• Limit fan-out to at most 5 concurrent peer queries to avoid network amplification.¶
• Validate the returned Name Record using the same signature and seq checks as other layers.¶

9.1. Registration

A name is registered by sending an ans.register request to one or more peers or directory agents. Upon successful registration, the registrant SHOULD announce the Name Record via GossipSub and publish it to the DHT.¶

The initial registration sets owner_id = peer_id and seq = 1. This binding is immutable: subsequent updates MUST come from the same owner_id.¶

9.2. Freshness and TTL

The TTL field indicates how long a consumer should consider the record fresh after retrieval. The expires_at field provides the absolute expiration boundary.¶

Registrants SHOULD re-register (with incremented seq) before expires_at to maintain continuous name availability. Periodic re-broadcast via GossipSub (e.g., every 5 minutes) helps ensure propagation to newly joined peers.¶

9.3. Renewal

Renewal is a re-registration with the same name and owner_id, an incremented seq, and an updated expires_at. The ans.register method serves both initial registration and renewal — no separate method is required.¶

Deployment profiles MAY impose additional requirements for renewal (e.g., periodic payment, proof-of-work, activity checks). Such requirements are outside the scope of this specification.¶

9.4. Ownership and Transfer

Name ownership is established at first registration and is immutable. Only the Owner (identified by owner_id) may update or unregister a name.¶

Because owner_id is immutable while peer_id is mutable, an Owner MAY update a Name Record to point to a different serving peer_id (e.g., after key rotation or migration to a new host). The update MUST be signed by the key corresponding to the current owner_id and carry a strictly higher seq value. This mechanism allows names to persist across peer-identity rotations without re-registration.¶

ANS does not define a transfer protocol at the AITP layer. Deployment profiles MAY define transfer mechanisms (e.g., dual-signed transfer messages) as extensions. A transferred name results in a new registration with the new owner's peer_id, owner_id, and seq reset to 1.¶

9.5. Expiration and Release

A Name Record is expired when the current time is past its expires_at timestamp. Expired records:¶

• MUST NOT be returned by ans.resolve or ans.lookup.¶
• SHOULD be removed from persistent stores during periodic garbage collection.¶
• SHOULD be removed from the DHT (or allowed to expire via DHT TTL).¶

Once expired and removed, the name returns to the available pool and may be registered by any agent. Deployment profiles MAY impose a grace period between expiration and release.¶

10.1. Name Spoofing

An adversary may attempt to register a Name Record for a name owned by another agent. The owner_id immutability rule prevents this: once a name has an owner, only that owner's signed updates are accepted. Receivers MUST verify signatures and owner_id matching before accepting any registration or update.¶

10.2. Replay Attacks

An adversary may replay an old Name Record to revert the name to stale state (e.g., a peer_id that the owner has since rotated). The monotonic seq field prevents this: receivers MUST reject records with seq less than or equal to the locally stored value.¶

To limit seq-space exhaustion, implementations SHOULD reject seq values that exceed the locally stored seq by more than a deployment-defined threshold (e.g., 1000).¶

10.3. Name Squatting

An adversary may register many names to deny them to legitimate agents. This document does not prescribe a specific mitigation; deployment profiles SHOULD employ at least one of:¶

• Proof-of-work: require computational effort before accepting ans.register.¶
• Token expenditure: require payment (e.g., Shell burn) proportional to name length or scarcity.¶
• Rate limiting: limit the number of registrations per peer per time window.¶
• Activity requirements: expire names whose registrant has not been active for a deployment-defined period.¶

10.4. GossipSub Flooding

An adversary may flood the "/clawnet/ans" topic with invalid or high-rate messages. Implementations MUST validate every message before processing (see Section 8.1.2) and SHOULD apply per-peer message rate limiting. GossipSub mesh scoring and peer scoring (as defined in GossipSub v1.1) provide additional protection against flooding.¶

10.5. DHT Poisoning

An adversary may attempt to store malicious Name Records in the DHT. Implementations MUST verify signatures on DHT get results before accepting them. Implementations SHOULD verify that the record's seq is consistent with locally known state (if any) and SHOULD cross-validate DHT results against GossipSub-disseminated records when possible.¶

10.6. Name Enumeration

The ans.lookup method allows querying by tags, which may reveal the set of registered agents. Implementations that are concerned about enumeration MAY restrict ans.lookup to authenticated peers or limit result sizes.¶

10.7. Privacy

Name Records contain peer_id, skill tags, and description text, which reveal agent identity and capabilities. Agents that require privacy SHOULD use minimal skill tags and description text. Agents that require anonymity SHOULD NOT register names and should instead use direct peer-ID addressing.¶

11.1. URI Scheme

ANS relies on the "agent" URI scheme defined by AIP [I-D.song-anp-aip]. This document makes no independent URI scheme registration request; the agent:// scheme registration is the responsibility of the AIP specification.¶

11.2. ANS Error Codes

The ANS error codes defined in Table 6 are protocol- internal identifiers within the ANP suite and are not drawn from IANA-managed registries. Should a formal ANS error code registry be established by a future document, the codes in Table 6 are candidates for registration.¶

11.3. AITP Method Names

The AITP method names (ans.register, ans.resolve, ans.unregister, ans.lookup) are conventions within the ANP protocol suite and are not drawn from IANA-managed registries. Should a formal AITP method registry be established by a future document, these method names are candidates for registration.¶

12.1. ClawNet

Organization

ChatChatTech¶

URL

https://github.com/ChatChatTech/ClawNet¶

Description

Go implementation of the ANP suite. The name system module uses the historical internal name "LNS" in source code; this predates the ANS terminology but covers the same protocol scope. All protocol-facing identifiers use agent://.¶

Maturity

Alpha¶

Coverage

Spec sections implemented:¶

• Name Record (§4): all 12 core fields, Ed25519 signature, monotonic seq, immutable owner_id¶
• Resolution (§7): 4-layer stack (memory, SQLite, DHT, peer-assisted RPC with first-wins strategy)¶
• Dissemination (§8): GossipSub register/unregister with signature validation; DHT namespace with Ed25519 validation¶
• Lifecycle (§9): registration, renewal, expiration, proof-of-work anti-spam¶
• Lookup (§5.4): tag-based narrow-waist filter with alias normalization and standard tag vocabulary¶
• Full-text search via SQLite FTS5 (BM25) over name, namespace, skills, description¶

Under integration:¶

• AITP method binding (§5) — currently REST-only; AITP segment framing in progress¶
• Wire-level topic and DHT namespace migration from /clawnet/lns to /clawnet/ans¶
• Channel addressing mode (§7.4) + derived topic mapping¶
• Uniform resolve envelope (§5.2) — currently returns single best match for anycast¶
• extensions field (§4.5) — not yet surfaced in record struct¶
• Validation rule table (§4.6) — rules enforced ad hoc; consolidated validation pass pending¶

Language

Go¶

License

Open source¶

Contact

ink@chatchat.space¶

A.1. DNS-SD (RFC 6763)

An agent with a domain name may publish DNS SRV and TXT records for DNS-based Service Discovery ([RFC6763]):¶

; SRV record (RFC 2782)
_clawnet._tcp.acme.com. IN SRV 0 0 4001 agent1.acme.com.

; TXT record (RFC 6763 §6)
_clawnet._tcp.acme.com. IN TXT "peer=12D3KooW..."
                                "agent=agent://acme/main"
                                "skills=translation,nlp"

Resolvers that support DNS-SD may query these records to bootstrap ANP connectivity with enterprise agents.¶

A.2. Well-Known URI (RFC 8615)

An agent with an HTTPS domain may publish its Agent Card at a well-known URI:¶

GET https://acme.com/.well-known/agent-card.json
→ 200 OK
→ Content-Type: application/json
→ { Agent Card JSON (ADP) }

This enables web-based clients to discover ANP agents without participating in the P2P network.¶

A.3. Local Discovery (mDNS)

For LAN discovery, agents may publish mDNS ([RFC6762]) service records:¶

_clawnet._tcp.local. IN SRV 0 0 4001 agent1.local.
_clawnet._tcp.local. IN TXT "peer=12D3KooW..."
                             "skills=translation,nlp"