TDesu.Telegram.Protocol
0.14.3
dotnet add package TDesu.Telegram.Protocol --version 0.14.3
NuGet\Install-Package TDesu.Telegram.Protocol -Version 0.14.3
<PackageReference Include="TDesu.Telegram.Protocol" Version="0.14.3" />
<PackageVersion Include="TDesu.Telegram.Protocol" Version="0.14.3" />
<PackageReference Include="TDesu.Telegram.Protocol" />
paket add TDesu.Telegram.Protocol --version 0.14.3
#r "nuget: TDesu.Telegram.Protocol, 0.14.3"
#:package TDesu.Telegram.Protocol@0.14.3
#addin nuget:?package=TDesu.Telegram.Protocol&version=0.14.3
#tool nuget:?package=TDesu.Telegram.Protocol&version=0.14.3
TDesu.Telegram.MTProto
F# library and CLI tool for parsing Telegram TL (Type Language) schemas and generating F# code.
Projects
| Project | Description | Target |
|---|---|---|
| TDesu.Telegram.TL | TL schema parser (FParsec-based) | netstandard2.1 |
| TDesu.Telegram.TL.Generator | Code generator CLI tool (td-tl-gen) |
net10.0 |
| TDesu.Telegram.Transport | MTProto transports: TCP, obfuscated TCP, WebSocket, HTTP, MTProxy fake-TLS | net10.0 |
| TDesu.Telegram.Protocol | MTProto 2.0 core: auth key exchange, message framing, session, RPC, client | net10.0 |
0.1.0 (breaking) reshapes
td-tl-genfrom one project's internal helper into a generic dotnet tool. New required flags (--schema,--output,--namespace,--overrides,--target), no embedded "default" overrides, no hardcoded paths. SeeRELEASE_NOTES.mdfor the migration list.
Installation
Library (NuGet)
dotnet add package TDesu.Telegram.TL
Generator (dotnet tool)
dotnet tool install --global TDesu.Telegram.TL.Generator
Usage
Parser library
open TDesu.Telegram.TL
let schema = """
boolFalse#bc799737 = Bool;
boolTrue#997275b5 = Bool;
---functions---
auth.sendCode#a677244f phone_number:string api_id:int api_hash:string settings:CodeSettings = auth.SentCode;
"""
match AstFactory.parse schema with
| Ok result ->
printfn "%d constructors, %d functions" result.Constructors.Length result.Functions.Length
| Error err ->
eprintfn "Parse error: %s" err
C# API:
using TDesu.Telegram.TL;
var schema = TlParser.Parse(schemaText); // throws FormatException on error
foreach (var ctor in schema.GetConstructors())
Console.WriteLine($"{ctor.Id.Name} #{ctor.GetConstructorId():X08}");
MTProto client transports
The carrier is part of the connection target: every DataCenter carries a TransportKind, and
MtProtoClient builds the matching ITransport when it connects and again on every reconnect.
Raw TCP is the default; the others are obfuscated.
open TDesu.Transport
open TDesu.MTProto
let dc = DataCenters.production[1]
// Raw TCP (intermediate framing) — the default:
use client = new MtProtoClient(dc)
// Or connect the same data centre over another carrier:
use wsClient = new MtProtoClient(dc |> DataCenters.over (TransportKind.WebSocket None))
// `None` means Telegram's own gateway. A self-hosted data centre needs its URL, since a
// WebSocket cannot be derived from an address and port:
use selfHosted =
new MtProtoClient(dc |> DataCenters.over (TransportKind.WebSocket(Some(Uri "wss://mtproto.example/apiws"))))
// A `transportFactory` still overrides everything, for carriers this library has no kind for:
use custom = new MtProtoClient(dc, transportFactory = fun d -> new MyTransport(d) :> ITransport)
// A self-hosted data centre also has its own RSA key; `rsaKeys` is the set the handshake
// matches the server's fingerprints against (default: Telegram's production key). The response
// deadline is `responseTimeout` (default 30 s; `TimeSpan.Zero` leaves only the caller's token).
use local = new MtProtoClient(dc, rsaKeys = [ myServerKey ], responseTimeout = TimeSpan.FromMinutes 2.0)
TransportKind |
Transport | Carrier | Obfuscation | Notes |
|---|---|---|---|---|
Tcp |
TcpTransport |
TCP | none | default; intermediate framing |
TcpObfuscated framing |
TcpObfuscatedTransport |
TCP | obfuscation2 | abridged or intermediate; DPI-resistant |
WebSocket endpoint |
WsTransport |
WebSocket | obfuscation2 | for CDN / reverse-proxy environments; None = Telegram's gateway for dc.Id |
Http |
HttpTransport |
HTTP/1.1 | none | legacy carrier |
FakeTls(host, port, secret, domain) |
FakeTlsTransport |
TLS-camouflaged TCP | obfuscation2 | via an MTProxy (ee secret + fronting domain) |
Generator CLI
Every invocation needs a schema, an output directory, a target namespace, an overrides TOML, and at least one target. There is no embedded default config — supply your own.
td-tl-gen \
--schema cached/api.tl \
--output ./Generated \
--namespace MyApp.Serialization \
--overrides path/to/overrides.toml \
--target cid,types,writers,coverage,return-types
| Target | Output file | Notes |
|---|---|---|
cid |
GeneratedCid.g.fs |
Constructor ID literals — also needs --mtproto-schema and a // LAYER N directive in --schema |
types |
GeneratedTlRequests.g.fs |
Whitelist-filtered request types with Serialize/Deserialize |
writers |
GeneratedTlWriters.g.fs |
Standalone write{X} functions and Write* DUs |
coverage |
GeneratedCoverageValidator.g.fs |
Handler coverage validator |
return-types |
GeneratedReturnTypes.g.fs |
CID → return type lookup |
tests |
GeneratedRoundTripTests.g.fs |
Round-trip tests for whitelisted requests |
layer-aliases |
GeneratedLayerAliases.g.fs |
Cross-layer CID aliases — needs --layer-base-schema |
client-cids |
GeneratedClientCid.g.fs |
Flat literal CID table for clients |
csharp |
GeneratedTl.g.cs, or one file per class with --split-by-class |
C# models and codecs; optional historical schema support |
all |
(multi) | Equivalent to cid,types,writers,coverage,return-types |
Optional flags:
--version— print the tool's own version and exit--mtproto-schema <path>— required by thecidtarget--layer-base-schema <path>— required bylayer-aliases; enables archived-layout readers and writers forcsharp--tests-namespace <ns>— module name for theteststarget (default<namespace>.Tests.GeneratedRoundTripTests)--client-namespace <ns>— namespace forclient-cids(default<namespace>.Client.Api)
Schemas are not downloaded automatically — fetch them manually from
core.telegram.org/schema or your TL source. The cid target
reads the schema's own // LAYER N directive (GeneratedLayerCid.Layer/DefaultLayer) — a schema
with no layer directive cannot be advertised to the server, so cid fails rather than guessing.
The one exception is a run whose --schema and --mtproto-schema are the same mtproto.tl
(generating the service layer, which has no API layer): that emits GeneratedLayerCid without
Layer/DefaultLayer.
Override TOML
The TOML file controls which TL types/functions get generated and how layer-dependent
CIDs are resolved at runtime. See samples/ServerOverrides/server-overrides.toml
for a fully worked example. Sections:
[[layer_variants]]— CIDs that vary by negotiated protocol layer[[aliases]]— multiple known CIDs for one method (older client layers)[[extras]]— undocumented CIDs not in the public schema[whitelists]—types/writers/writer_layer_types/stub_types[[csharp_layer_mappings]]— semantic old/current class mappings for C# historical codecs
With --target csharp --layer-base-schema previous.tl, both schemas must declare
// LAYER N, and the current layer must be newer. Same-name declarations whose CIDs
changed get historical readers automatically. Explicit mappings also enable historical
writers, including fields moved into a nested action object:
[[csharp_layer_mappings]]
source = "OldUrlButton"
target = "InlineButton"
nested_field = "Type"
nested_constructor = "InlineButtonTypeUrl"
Names are generated C# class/property names. The archived schema supplies CIDs, flags,
wire types and field order; TOML contains no binary layouts. Readers recognise archived
CIDs even without a negotiated layer, so previously saved payloads remain readable.
Writers select the archived layout for non-native layers through the base layer.
Missing formerly-required fields and new byte-bearing fields that cannot be represented
are rejected rather than silently dropped. GeneratedLayerCompatibility exposes
CanWrite and TryUpgradeRequest for consumer gates and request routing.
The F# library APIs EmitCSharp.buildModule and buildFiles take the planned variants
as their final argument; pass [] when historical codecs are not needed.
Generator architecture
TL schema text
-> AstFactory.parse FParsec parser -> TlSchema AST
-> SchemaMapper.mapSchema TlSchema -> CodeModel IR
-> Emit*.fs CodeModel -> F# code
EmitTypes.fs Fantomas AST -> serialization types
EmitWriters.fs Fantomas AST -> writer functions
EmitTemplates.fs String templates -> CIDs, tests, etc.
Samples
| Sample | Description |
|---|---|
| CSharpParser | C# API: TlParser.Parse(), extension methods |
| FSharpParser | F# API: AstFactory.parse, pattern matching on AST |
| CustomOverrides | F# library API: load TOML overrides and generate from code |
| ServerOverrides | Real-world overrides TOML from a Telegram MTProto server (dual-layer support, undocumented RPCs, custom whitelists) |
| PingPongBot | End-to-end: TL parsing → serialization → real MTProto handshake with Telegram DC |
Building
dotnet build
dotnet test
License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.3)
- TDesu.FSharp (>= 2.1.1)
- TDesu.Telegram.Crypto (>= 0.5.1)
- TDesu.Telegram.Serialization (>= 0.4.2)
- TDesu.Telegram.TL (>= 0.14.3)
- TDesu.Telegram.Transport (>= 0.14.3)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.14.3 | 268 | 11/2/2026 |
| 0.14.2 | 207 | 10/25/2026 |
| 0.14.1 | 111 | 10/25/2026 |
| 0.14.0 | 113 | 10/5/2026 |
| 0.13.1 | 320 | 9/5/2026 |
| 0.13.0 | 290 | 9/5/2026 |
| 0.12.4 | 143 | 9/1/2026 |
| 0.12.3 | 134 | 9/1/2026 |
| 0.12.2 | 127 | 9/1/2026 |
| 0.12.1 | 127 | 8/31/2026 |
| 0.12.0 | 134 | 8/30/2026 |
| 0.12.0-alpha.4 | 139 | 8/9/2026 |
| 0.12.0-alpha.3 | 99 | 8/9/2026 |
| 0.12.0-alpha.2 | 108 | 8/8/2026 |
| 0.12.0-alpha.1 | 93 | 8/8/2026 |
| 0.11.0-alpha.6 | 86 | 8/4/2026 |
| 0.11.0-alpha.5 | 81 | 8/4/2026 |
| 0.11.0-alpha.4 | 92 | 8/4/2026 |
| 0.11.0-alpha.3 | 88 | 8/4/2026 |
| 0.11.0-alpha.2 | 85 | 8/4/2026 |