Introducing a new way to review your PRs.

Read the announcement

ayugram / ayugramdesktop

Desktop Telegram client with good customization and Ghost mode.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / mtproto-networking

MTProto networking

Overview

The MTProto networking stack is centered on MTP::Instance in Telegram/…/mtp_instance.h and Telegram/…/mtp_instance.cpp. Callers send TL requests through Instance::send() / sendSerialized() or through the convenience builders in Telegram/…/sender.h; Telegram/SourceFiles/mtproto/mtproto_concurrent_sender.* wraps the same Instance API for callers that need callbacks delivered through a supplied runner instead of directly on the main thread.

A request is assigned a process-wide request id by details::GetNextRequestId() in Telegram/…/mtp_instance.cpp, serialized by Telegram/SourceFiles/mtproto/details/mtproto_serialized_request.*, registered in Instance::Private request/callback maps, and routed to a details::Session for the requested shifted DC id. Shifted DC helpers in Telegram/…/facade.h distinguish main, config, logout, upload, download, updater, group-call, destroy-key, and temporary DC sessions without changing the bare server DC id. Instance::Private::getSession() starts sessions lazily; main DC traffic uses the main session thread, upload/download shifts use a file-session thread pool, and other shifted sessions share an “other” thread.

Telegram/…/session.h and Telegram/…/session.cpp split the public session object from SessionPrivate, which lives on the session thread. SessionData is the thread-safe bridge: it owns the toSend map, haveSent map, received response queue, current SessionOptions, and methods that queue work back to the main-thread Session. Session::sendPrepared() places a serialized request in toSend and schedules SessionPrivate::tryToSend(). Responses are pushed by SessionPrivate into haveReceivedMessages; Session::tryToReceive() later dispatches RPC results to Instance::processCallback() and updates to Instance::processUpdate() only for the main session.

Telegram/…/session_private.cpp implements connection choice, MTProto message packing, encryption, retry, ack, resend, and response parsing. connectToServer() snapshots SessionOptions, acquires/loads an auth key, and creates one or more candidate AbstractConnections from DC options. It tries allowed IPv4/IPv6 and TCP/HTTP variants in parallel, prioritizes IPv6/TCP/secret endpoints, waits briefly for a better candidate, then promotes the best connected candidate. tryToSend() builds service messages (ping, msgs_ack, msg_resend_req, msgs_state_req, http_wait, key-bind requests) and user requests, optionally wraps requests in invokeWithLayer(initConnection(...)), batches multiple messages into a container, tracks sent containers, and hands the encrypted packet to the active connection. handleReceived() verifies auth key id, decrypts with AES-IGE, validates the message key, server session, padding, time, and salt, then handleOneReceived() handles gzip, containers, acks, bad salt/time, state replies, RPC results, new-session notifications, pongs, and updates. Bad server time/salt updates base::unixtime, resends affected messages, or resets the MTProto session depending on the server notification.

Auth keys are represented by Telegram/SourceFiles/mtproto/mtproto_auth_key.*. AuthKey stores the 2048-bit key material, computes the lower-64-bit key id from SHA1, derives AES keys/IVs for old and current MTProto, and records generated/temporary creation and expiry times. Per-DC state lives in details::Dcenter (Telegram/SourceFiles/mtproto/details/mtproto_dcenter.*): one persistent key plus separate regular/media temporary keys guarded by a read-write lock and atomic creation flags. SessionPrivate::tryAcquireKeyCreation() creates a BoundKeyCreator (Telegram/SourceFiles/mtproto/details/mtproto_bound_key_creator.*) when no suitable temporary key exists. The unbound handshake is performed by DcKeyCreator (Telegram/SourceFiles/mtproto/details/mtproto_dc_key_creator.*) over the selected connection using req_pq/DH exchange and RSA keys from DcOptions; regular temporary keys are then bound to the persistent key by DcKeyBinder before Dcenter::releaseKeyCreationOnDone() publishes them. CDN temporary keys are stored after CDN RSA configuration is available and do not bind through a persistent key.

Datacenter and config state is owned by MTP::Config and MTP::DcOptions in Telegram/SourceFiles/mtproto/mtproto_config.* and Telegram/SourceFiles/mtproto/mtproto_dc_options.*. DcOptions starts with built-in production/test IPv4 and IPv6 endpoints and RSA public keys, can deserialize stored endpoints and CDN public keys, applies server config.dc_options, emits changed() by bare DC id, and exposes lookup(dcId, DcType, throughProxy) as a two-dimensional matrix of address family and protocol variants. Lookup filters CDN, media-only, invalid secrets, HTTP-ineligible (tcpo_only or secret) endpoints, and proxy-static endpoints. Config::apply() updates MTProto-wide limits and calls dcOptions().setFromList() when help.getConfig returns non-empty DC options.

Telegram/SourceFiles/mtproto/config_loader.* refreshes config. It sends help.getConfig first to the main DC, then rotates through MTP::configDcId(dc) sessions on an 8s timer. When no proxy is enabled and this is not a key-destroyer instance, it also starts SpecialConfigRequest (Telegram/SourceFiles/mtproto/special_config_request.*) to fetch a simple encrypted endpoint list from DNS-over-HTTPS / Firebase-like endpoints under ConfigFields::txtDomainString; each special endpoint is installed as a temporary DC option, queried for help.getConfig, and used only to update DC options. The same SpecialConfigRequest type is used by Instance::syncHttpUnixtime() to read an HTTP Date header when a connection asks for time synchronization.

The connection abstraction is details::AbstractConnection in Telegram/SourceFiles/mtproto/connection_abstract.*. AbstractConnection::Create() chooses TcpConnection for TCP variants and HttpConnection for HTTP variants, then wraps the result in ResolvingConnection when a SOCKS5/MTProto proxy host should be custom-resolved. Every connection first sends a fake non-secure req_pq and accepts a matching resPQ as a transport health check before SessionPrivate sends encrypted MTProto packets.

TCP transport is implemented by Telegram/SourceFiles/mtproto/connection_tcp.*. It supports plain abridged transport, 16-byte obfuscated transport, and padded/intermediate-like secrets (0xDD or 0xEE prefixes) through the nested Protocol classes. It builds the 64-byte obfuscation start prefix, derives send/receive AES-CTR keys, writes the protocol id and protocol DC id, and then frames encrypted packets according to the selected protocol. The socket layer is selected by AbstractSocket::Create() in Telegram/SourceFiles/mtproto/details/mtproto_abstract_socket.*: ordinary TcpSocket (Telegram/SourceFiles/mtproto/details/mtproto_tcp_socket.*) for direct/Qt-proxied TCP, or TlsSocket (Telegram/SourceFiles/mtproto/details/mtproto_tls_socket.*) for 0xEE TLS-style secrets. File/media sessions ask sockets for larger send/receive buffers via the protocolForFiles flag.

HTTP transport is implemented by Telegram/SourceFiles/mtproto/connection_http.*. It always posts to http://<dc-address>:80/api, uses Qt’s QNetworkAccessManager with ToNetworkProxy(proxy), and treats the HTTP body as raw MTProto transport bytes. Once connected, it reports usingHttpWait(), so SessionPrivate::tryToSend() injects http_wait service messages and sends a new wait when needHttpWait() sees no outstanding HTTP requests.

Proxy data and conversion live in Telegram/SourceFiles/mtproto/mtproto_proxy_data.*. ProxyData::Type covers none, SOCKS5, HTTP, MTProto, and Web. SOCKS5/HTTP are passed to Qt through ToNetworkProxy(). MTProto and Web proxies return QNetworkProxy::NoProxy; TCP connects to the proxy host/port and uses secretFromMtprotoPassword() as the TCP obfuscation secret. Domain-name SOCKS5/MTProto proxies can be custom-resolved by ResolvingConnection, which uses Instance::resolveProxyDomain() and DomainResolver (Telegram/SourceFiles/mtproto/details/mtproto_domain_resolver.*) to query DNS-over-HTTPS, stores the ordered resolved IPs in ProxyData, and promotes a successful IP to the front through Instance::setGoodProxyDomain().

Proxy checking and rotation are separate from request sessions. Telegram/SourceFiles/mtproto/proxy_check.* creates lightweight AbstractConnections against the main DC to measure ping for a candidate proxy; it skips Web proxies and checks both IPv4 and IPv6 endpoint variants when allowed. Telegram/SourceFiles/core/proxy_rotation_manager.* watches proxy settings and account connection state. When proxy rotation is enabled, multiple proxies exist, and no production account is connected, it probes non-Web proxies in preferred order, records availability, and switches to the first newly available proxy after the configured rotation timeout.

Web proxy support has two layers. ProxyData validates Web proxy hostnames and optional base paths, stores the base path in the otherwise unused user field, fixes the port to 443, rejects TLS-style 0xEE secrets, computes the bridge HMAC capability, and builds the public HTTPS bridge URL. Telegram/SourceFiles/mtproto/details/mtproto_web_proxy_socket.* implements an AbstractSocket backed by WebProxy::Transport streams; TcpConnection selects this socket when ProxyData::Type::Web is active, so the rest of MTProto still sees a TCP-like encrypted stream to an MTProto proxy.

Telegram/SourceFiles/mtproto/web_proxy/web_proxy_transport.* is the Web proxy relay. Transport::Activate() creates a dedicated thread, configures a singleton transport for the active Web proxy, attempts a hidden WebviewCarrier, and exposes state changes for UI. If hidden WebView is unavailable or fails repeatedly, Transport::OpenBrowser() mints a short-lived local token and opens a 127.0.0.1 page served by a local QTcpServer. The browser authenticates over a local WebSocket with that token, receives bridge control data containing WebProxyBridgeUrl(proxy), loads the remote proxy page in a sandboxed iframe, and relays binary frames between Telegram Desktop and the remote page. The frame protocol in Telegram/SourceFiles/mtproto/web_proxy/web_proxy_frame.* supports control frames (Hello, Welcome, AuthChallenge, AuthResponse, Ping, Pong, Bye) and per-stream Open, Data, Window, and Close; the transport enforces per-stream and global pending byte/item limits, flow-control windows, local-only clients, CSP on the helper page, WebSocket origin/host checks, and write-progress timeouts. Telegram/SourceFiles/mtproto/web_proxy/web_proxy_webview.* provides the hidden WebView carrier with strict source/navigation validation, heartbeat/handshake/write timers, a restricted-origin WebView, and a native bridge script that base64-encodes frames into window.external.invoke() messages.

Coupling

  • If request routing or shifted DC semantics change in Telegram/…/facade.h, audit Instance::Private::getThreadForDc(), DcOptions::dcType(), and SessionPrivate::getProtocolDcId() in Telegram/…/mtp_instance.cpp, Telegram/…/mtproto_dc_options.cpp, and Telegram/…/session_private.cpp; upload/download/media/CDN sessions depend on the shift to choose threads, protocol DC sign, and temporary key type.
  • If SessionOptions fields are added in Telegram/…/session.h, update Session::refreshOptions() and the equality gate in SessionData::notifyConnectionInited() in Telegram/…/session.cpp; otherwise a connection may be marked initialized using stale options and skip a needed initConnection retry.
  • If DcOptions::Endpoint flags or secret validation change in Telegram/SourceFiles/mtproto/mtproto_dc_options.*, also update TcpConnection::Protocol::Create() and AbstractSocket::Create() in Telegram/…/connection_tcp.cpp and Telegram/…/mtproto_abstract_socket.cpp; the same secret bytes decide endpoint eligibility, TCP framing, and TLS-style socket selection.
  • If proxy type behavior changes in Telegram/SourceFiles/mtproto/mtproto_proxy_data.*, verify Session::refreshOptions(), AbstractConnection::Create(), TcpConnection::connectToServer(), HttpConnection, ResolvingConnection, proxy_check.*, and core/proxy_rotation_manager.*; each proxy type controls which transport is allowed, whether Qt proxying is used, whether custom DNS resolution applies, and whether rotation probes can run.
  • If Web proxy link encoding or base-path support changes in Telegram/SourceFiles/mtproto/mtproto_proxy_data.*, keep WebProxyBridgeUrl(), WebProxyBridgePath(), WebviewCarrier::validSource(), the helper page CSP/iframe target in Telegram/…/web_proxy_transport.cpp, and hidden WebView navigation in Telegram/…/web_proxy_webview.cpp in sync; the host/path/capability triple is validated on both local and remote sides.
  • If the Web proxy frame format changes in Telegram/SourceFiles/mtproto/web_proxy/web_proxy_frame.*, update both Transport::Private::processRelayFrame() / sendFrame() and WebviewCarrier handling in Telegram/…/web_proxy_transport.cpp and Telegram/…/web_proxy_webview.cpp; the local browser/WebView carriers forward raw serialized frames and protocol drift is treated as a fatal proxy error.
  • If config loading changes in Telegram/SourceFiles/mtproto/config_loader.* or Telegram/SourceFiles/mtproto/special_config_request.*, verify DcOptions::constructAddOne() and temporary DC id helpers in Telegram/…/facade.h; special endpoints are written into temporary DC ids and queried through normal MTProto sessions, not through a separate transport path.
  • If auth key lifetime or binding logic changes in Telegram/SourceFiles/mtproto/details/mtproto_dcenter.*, Telegram/SourceFiles/mtproto/details/mtproto_bound_key_creator.*, or Telegram/…/session_private.cpp, verify persistent-key writeback in Instance::Private::dcPersistentKeyChanged() and temporary-key notifications in Session::watchDcKeyChanges(); sessions update encryption keys reactively and restart when the key id changes.

Risks

  • Telegram/…/session.cpp marks SessionData::notifyConnectionInited() with #TODO race while comparing current options with stored options before setting the DC connection initialized. If proxy/language options change while a response arrives, the DC may be marked initialized for the wrong init parameters and later requests may omit the required invokeWithLayer(initConnection(...)) wrapper.
  • Telegram/…/web_proxy_transport.cpp explicitly warns that QAbstractSocket::disconnectFromHost() can synchronously erase _clients entries while WebSocket messages are processed. If processWebSocket() is refactored to keep references across message handling again, a close frame or protocol error can invalidate the flat-map reference and cause use-after-erase behavior.
  • Telegram/…/mtproto_proxy_data.h stores a Web proxy base path in ProxyData::user to avoid changing the serialized proxy format. If generic proxy UI or persistence code starts treating user as credentials for Web proxies, Web bridge URLs and capability checks can silently target the wrong path or reject valid Web proxy entries.
  • Telegram/…/session_private.cpp binds temporary keys to the persistent key that existed when creation started, and Dcenter::releaseKeyCreationOnDone() in Telegram/…/mtproto_dcenter.cpp rejects the temporary key if the persistent key changed. If persistent-key replacement code bypasses the normal dcPersistentKeyChanged() path, in-flight temporary key creation can loop through destroy/restart without a usable session key.
  • Telegram/…/web_proxy_transport.cpp and Telegram/…/web_proxy_webview.cpp enforce many independent pending-byte, pending-item, frame-size, window, and timer limits. Raising one limit without the paired limits can make the local WebSocket/WebView carrier accept more data than the other side will drain, which turns a slow Web proxy into stream failure or full transport failure.