foundations/network/adnl-udp.mdx (1)

9-11: Prefer docs-owned routes for the DHT/RLDP links.

Lines 9-11 and 181-188 hardcode old-docs.ton.org for related protocol links. docs.json already owns redirects for those topics, so these should point to the site-local routes instead; that keeps users on docs.ton.org and avoids another content edit when DHT/RLDP are migrated.

🔗 Suggested link cleanup

- ADNL over UDP is the protocol used by TON nodes to communicate with each other. It serves as the foundation for higher-level protocols such as [DHT](https://old-docs.ton.org/v3/documentation/network/protocols/dht/overview) and [RLDP](https://old-docs.ton.org/v3/documentation/network/protocols/rldp).
+ ADNL over UDP is the protocol used by TON nodes to communicate with each other. It serves as the foundation for higher-level protocols such as [DHT](/v3/documentation/network/protocols/dht/overview) and [RLDP](/v3/documentation/network/protocols/rldp).

Apply the same replacement in the See also list.

Also applies to: 181-188

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@foundations/network/adnl-udp.mdx` around lines 9 - 11, Replace hardcoded
external links to "https://old-docs.ton.org/..." with the site-local routes
defined in docs.json for the DHT and RLDP pages in the ADNL over UDP doc: update
the two inline links that currently point to the DHT and RLDP old-docs URLs (the
ones used in the paragraph contrasting ADNL over UDP and ADNL over TCP) and the
same two entries in the "See also" list to use the local route paths (e.g., the
canonical /foundations/... or /network/... routes managed by docs.json) so the
links remain on docs.ton.org and follow existing redirects.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

foundations/network/adnl-tcp.mdx (1)

57-57: Prefer internal TL docs link for consistency and longevity.

Line 57 points to core.telegram.org. Consider linking to your internal TL docs page so navigation stays in-repo and less sensitive to external URL drift.

Suggested fix

-After this exchange the connection is established. Data is serialized using [TL (Type Language)](https://core.telegram.org/mtproto/TL).
+After this exchange the connection is established. Data is serialized using [TL (Type Language)](/languages/tl/overview).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@foundations/network/adnl-tcp.mdx` at line 57, Replace the external
core.telegram.org link used in the sentence "Data is serialized using [TL (Type
Language)](https://core.telegram.org/mtproto/TL)" with the project's internal TL
documentation page to ensure link stability; update the Markdown link target
while keeping the link text "TL (Type Language)" unchanged so references to TL
remain consistent across the repo (edit the adnl-tcp.mdx line containing that
link).

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

foundations/network/adnl.mdx (2)

1-133: ⚠️ Potential issue | 🟠 Major

Address the missing overlays and forks content.

Issue #1035 explicitly requests coverage of public/private overlays and ADNL forks, but this documentation does not address those concepts. As flagged in a previous review, readers following the migration from old-docs will find this gap.

Consider adding a dedicated section (e.g., "## Overlays and ADNL forks") that:

• Defines public vs. private overlays
• Explains when and how ADNL forks occur
• Describes their impact on peer discovery and neighbor tables
• Links to any additional migrated content or references the original specification

This section could be placed after "Neighbor tables" (line 40) or before "See also" (line 128).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@foundations/network/adnl.mdx` around lines 1 - 133, Add a new section titled
"## Overlays and ADNL forks" (insert after the "Neighbor tables" paragraph or
before "See also") that defines public vs private overlays, explains triggers
and mechanics of ADNL forks, and describes effects on peer discovery and
neighbor table maintenance (stale entries, divergence, rejoin/merge procedures);
include guidance on when overlays are used (e.g., isolation, testnets, private
clusters), how forks are detected/reconciled, and link or reference the
original/migrated specification and related ADNL docs for further reading.
Ensure the new section uses the same tone and formatting as other sections and
references ADNL concepts already in the document (e.g., neighbor table, address,
handshake, datagram) so readers can correlate impacts.

---

67-68: ⚠️ Potential issue | 🟡 Minor

Clarify byte-range notation to match the TCP page.

The [0..16] and [16..32] notation is ambiguous—readers cannot tell whether the end index is inclusive or exclusive. The TCP documentation (adnl-tcp.mdx lines 204-205) uses Python-style slice notation [0:16] which clearly indicates exclusive end indices.

For consistency and clarity, please use the same notation here:

📐 Suggested notation fix

- key = secret[0..16] || hash[16..32] // 16 bytes each
- nonce = hash[0..4] || secret[20..32] // 4 + 12 bytes
+ key = secret[0:16] || hash[16:32] // 16 bytes each (exclusive end)
+ nonce = hash[0:4] || secret[20:32] // 4 + 12 bytes (exclusive end)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@foundations/network/adnl.mdx` around lines 67 - 68, The slice ranges used for
computing key and nonce (key = secret[0..16] || hash[16..32], nonce = hash[0..4]
|| secret[20..32]) use ambiguous `[0..16]`/`[16..32]` notation; update these to
Python-style exclusive-end slices (e.g., `secret[0:16]`, `hash[16:32]`,
`hash[0:4]`, `secret[20:32]`) so readers clearly understand the byte ranges for
key, nonce, secret, and hash and match the TCP page convention.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

foundations/network/adnl.mdx (2)

67-69: ⚠️ Potential issue | 🟡 Minor

Clarify whether byte ranges are half-open.

0..16 / 16..32 is ambiguous in docs prose. Please make endpoint semantics explicit (or use half-open notation directly) and include resulting lengths inline.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@foundations/network/adnl.mdx` around lines 67 - 69, Clarify the byte-range
semantics for the key and nonce construction by stating explicitly that ranges
are half-open (start inclusive, end exclusive) or by switching to explicit
half‐open notation; update the lines using key, nonce, secret and hash to show
e.g. secret[0:16] and hash[16:32] and annotate each slice with its resulting
length (16 bytes, 12 bytes, etc.) so readers know the exact byte counts used for
key (16 bytes) and nonce (4+12 = 16 bytes).

---

122-127: ⚠️ Potential issue | 🟠 Major

Add a dedicated section for overlays and ADNL forks (objective gap).

The page still does not define public/private overlays or explain ADNL fork behavior, which is part of issue #1035 scope.

Suggested section outline

+## Overlays and ADNL forks
+
+Public overlays are discoverable/shared network scopes; private overlays restrict membership and discovery.
+
+An ADNL fork occurs when neighbor/discovery views diverge, producing temporary partitioned routing neighborhoods until peer exchange converges.
+
+Document expected effects on peer discovery / neighbor tables and link to detailed follow-up pages.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@foundations/network/adnl.mdx` around lines 122 - 127, Add a new dedicated
subsection in foundations/network/adnl.mdx (near the "P2P protocol (ADNL over
UDP)" section) that defines public and private overlays, describes how overlays
map to namespaces/addresses and how peers discover overlay-specific public keys,
and explains ADNL fork behavior (how forks create divergent overlays, how
channel keys and encryption are scoped per-overlay, how discovery and message
routing respond to forks, and recommendations for conflict
resolution/resynchronization). Reference the existing discussion of channel
creation and key derivation in the UDP section (e.g., the create channel flow
and "keys are derived from the client's private key and the peer's public key")
and tie it to overlay-specific key selection and fork scenarios; mention issue
`#1035` so reviewers can track scope. Ensure the new text uses clear definitions
for "public overlay" and "private overlay" and includes expected operational
behavior during forks (discovery, channel acceptance, and key mismatches).

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes