# MTProto Client Behavior Matrix

> Version-pinned Telegram client connection behavior notes for proxy compatibility debugging.

- Skill: `sleep3r/mtproto-client-behavior-matrix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sleep3r/mtproto-client-behavior-matrix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sleep3r/mtproto-client-behavior-matrix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: sleep3r (https://skillmd.com/u/sleep3r)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sleep3r/mtproto-client-behavior-matrix

---


# MTProto Client Behavior Matrix

Use this skill when behavior differs by client platform (iOS/Android/Desktop) or when tuning relay/handshake timeouts.

## Evidence Policy

- Do not publish behavior claims without evidence.
- Accept only:
  - reproducible local captures/logs, or
  - direct client source links pinned to a tag and commit.
- Mark each claim as `source-backed` or `field-capture`.

## iOS (Telegram iOS)

Version snapshot:

- Repo/tag: `TelegramMessenger/Telegram-iOS` `build-26855`
- Commit: `b16d9acdffa9b3f88db68e26b77a3713e87a92e3`

Source-backed behavior:

- TCP connect timeout: `12s`
  - https://github.com/TelegramMessenger/Telegram-iOS/blob/b16d9acdffa9b3f88db68e26b77a3713e87a92e3/submodules/MtProtoKit/Sources/MTTcpConnection.m#L980
- Response watchdog base: `MTMinTcpResponseTimeout = 12.0`
  - https://github.com/TelegramMessenger/Telegram-iOS/blob/b16d9acdffa9b3f88db68e26b77a3713e87a92e3/submodules/MtProtoKit/Sources/MTTcpConnection.m#L576
- Response timeout includes payload-dependent term and resets on partial reads
  - https://github.com/TelegramMessenger/Telegram-iOS/blob/b16d9acdffa9b3f88db68e26b77a3713e87a92e3/submodules/MtProtoKit/Sources/MTTcpConnection.m#L1339
  - https://github.com/TelegramMessenger/Telegram-iOS/blob/b16d9acdffa9b3f88db68e26b77a3713e87a92e3/submodules/MtProtoKit/Sources/MTTcpConnection.m#L1398
- Transport-level watchdog: `20s`
  - https://github.com/TelegramMessenger/Telegram-iOS/blob/b16d9acdffa9b3f88db68e26b77a3713e87a92e3/submodules/MtProtoKit/Sources/MTTcpTransport.m#L312
- Reconnect backoff steps (`1s`, then `4s`, then `8s`)
  - https://github.com/TelegramMessenger/Telegram-iOS/blob/b16d9acdffa9b3f88db68e26b77a3713e87a92e3/submodules/MtProtoKit/Sources/MTTcpConnectionBehaviour.m#L66

Field-capture behavior (proxy-side observations):

- Pre-warms multiple idle sockets.
- Can split 64-byte obfuscation handshake across TLS records.
- May delay first payload after `ServerHello`.

Proxy implications:

- Assemble handshake bytes until full 64-byte payload is complete.
- Keep generous handshake stage timeout; tighten only after relay is active.
- Do not treat short idle prewarmed sockets as protocol failure.

## Android (Telegram Android)

Version snapshot:

- Repo/ref: `DrKLO/Telegram` `master` (snapshot: `12.6.4 (6666)`)
- Commit: `009e97356f966bb81eceba113d210230bf383122`

Source-backed behavior:

- Enables `TCP_NODELAY`, switches socket to `O_NONBLOCK`, uses `connect(..., EINPROGRESS)` with edge-triggered epoll.
  - https://github.com/DrKLO/Telegram/blob/009e97356f966bb81eceba113d210230bf383122/TMessagesProj/jni/tgnet/ConnectionSocket.cpp#L618
- Connect path chooses address family/static flags and sets per-type logical timeouts (`Proxy=5s`, `Generic=8/12s`, `Upload=25/40s`, `Push=20/30s`).
  - https://github.com/DrKLO/Telegram/blob/009e97356f966bb81eceba113d210230bf383122/TMessagesProj/jni/tgnet/Connection.cpp#L276
  - https://github.com/DrKLO/Telegram/blob/009e97356f966bb81eceba113d210230bf383122/TMessagesProj/jni/tgnet/Connection.cpp#L368
- Timeout model is logical/internal (`setTimeout` / `checkTimeout`).
  - https://github.com/DrKLO/Telegram/blob/009e97356f966bb81eceba113d210230bf383122/TMessagesProj/jni/tgnet/ConnectionSocket.cpp#L1105
  - https://github.com/DrKLO/Telegram/blob/009e97356f966bb81eceba113d210230bf383122/TMessagesProj/jni/tgnet/ConnectionSocket.cpp#L1115
- Explicit connection-type split (`Generic`, `Download`, `Upload`, `Push`, `Temp`, `Proxy`) and multiple parallel slots.
  - https://github.com/DrKLO/Telegram/blob/009e97356f966bb81eceba113d210230bf383122/TMessagesProj/jni/tgnet/Defines.h#L68
  - https://github.com/DrKLO/Telegram/blob/009e97356f966bb81eceba113d210230bf383122/TMessagesProj/jni/tgnet/Defines.h#L26

Proxy implications:

- Expect several concurrent connection attempts from one device/session.
- Treat connect churn as normal; optimize for quick accept + cheap close path.

## Desktop (Windows/Linux/macOS via Telegram Desktop)

Version snapshot:

- Repo/tag: `telegramdesktop/tdesktop` `v6.7.2`
- Commit: `085c4ba65d1f8aa13abf0fd7fc8489f094552542`

Source-backed behavior:

- Builds multiple test connections and chooses by priority.
  - https://github.com/telegramdesktop/tdesktop/blob/085c4ba65d1f8aa13abf0fd7fc8489f094552542/Telegram/SourceFiles/mtproto/session_private.cpp#L1010
- Wait-for-connected starts at `1000ms` and grows on failures.
  - https://github.com/telegramdesktop/tdesktop/blob/085c4ba65d1f8aa13abf0fd7fc8489f094552542/Telegram/SourceFiles/mtproto/session_private.cpp#L34
  - https://github.com/telegramdesktop/tdesktop/blob/085c4ba65d1f8aa13abf0fd7fc8489f094552542/Telegram/SourceFiles/mtproto/session_private.cpp#L1236
- TCP/HTTP transport full-connect timeout: `8s`.
  - https://github.com/telegramdesktop/tdesktop/blob/085c4ba65d1f8aa13abf0fd7fc8489f094552542/Telegram/SourceFiles/mtproto/connection_tcp.cpp#L21
  - https://github.com/telegramdesktop/tdesktop/blob/085c4ba65d1f8aa13abf0fd7fc8489f094552542/Telegram/SourceFiles/mtproto/connection_http.cpp#L18
- Resolver path uses per-IP timeout `4000ms` and scales by resolved IP count.
  - https://github.com/telegramdesktop/tdesktop/blob/085c4ba65d1f8aa13abf0fd7fc8489f094552542/Telegram/SourceFiles/mtproto/connection_resolving.cpp#L16
- After first success, may wait `2000ms` for a better candidate.
  - https://github.com/telegramdesktop/tdesktop/blob/085c4ba65d1f8aa13abf0fd7fc8489f094552542/Telegram/SourceFiles/mtproto/session_private.cpp#L33

Linux/macOS note:

- In reviewed MTProto sources, timeout/retry logic is shared with Windows path (no observed OS-specific branching there).
- Validate package/channel specifics separately (Snap/DEB/Flatpak/macOS build IDs) before asserting behavioral deltas.

Proxy implications:

- Expect candidate racing and early cancellation patterns.
- Keep reconnect path cheap and non-blocking.
- Do not overfit timeout policy to a single desktop platform.

## Practical Use Checklist

- If one platform fails and others pass, first compare known timeout model for that client.
- Verify whether failures happen pre-handshake, in 64-byte obfuscation phase, or after relay starts.
- Inspect whether client behavior is expected parallel racing vs actual proxy regression.
- Update this skill only with pinned sources or reproducible captures.