⚡ layer

A modular, production-grade async Rust implementation of the Telegram MTProto protocol.

Written from the ground up to understand Telegram's internals at the lowest level.

🧩 What is layer?

layer is a hand-crafted, bottom-up async Rust implementation of the Telegram MTProto protocol — built not to reinvent the wheel, but to understand it.

The core protocol pieces — the .tl schema parser, the AES-IGE cipher, the Diffie-Hellman key exchange, the MTProto session, the async update stream — are all written from scratch. The async runtime and a handful of well-known utilities (tokio, flate2, getrandom) are borrowed from the ecosystem, because that's just good engineering. The architecture draws inspiration from the excellent grammers library.

The goal was never "yet another Telegram SDK." It was: what happens if you sit down and build every piece yourself, and actually understand why it works?

🎓 Personal use & learning project — layer was built as a personal exploration: learning by building. The goal is to deeply understand Telegram's protocol by implementing every layer from scratch, not to ship a polished production SDK. Feel free to explore, learn from it, or hack on it!

⚠️ Pre-production (0.x.x) — This library is still in early development. APIs will change without notice. Not production-ready — use at your own risk!

💬 Community

	Link
📢 Channel (updates & releases)	@layer_rs
💬 Chat (questions & discussion)	@layer_chat

🏗️ Crate Overview

Crate	Description
`layer-tl-parser`	Parses `.tl` schema text into an AST
`layer-tl-gen`	Generates Rust code from the AST at build time
`layer-tl-types`	All Layer 224 constructors, functions and enums
`layer-crypto`	AES-IGE, RSA, SHA, DH key derivation
`layer-mtproto`	MTProto session, DH exchange, message framing
`layer-client`	High-level async client — auth, bots, updates, 2FA, media
`layer-app`	Interactive demo binary (not published)
`layer-connect`	Raw DH connection demo (not published)

layer/
├── layer-tl-parser/   ── Parses .tl schema text → AST
├── layer-tl-gen/      ── AST → Rust source (build-time)
├── layer-tl-types/    ── Auto-generated types, functions & enums (Layer 224)
├── layer-crypto/      ── AES-IGE, RSA, SHA, auth key derivation
├── layer-mtproto/     ── MTProto session, DH, framing, transport
├── layer-client/      ── High-level async Client API
├── layer-connect/     ── Demo: raw DH + getConfig
└── layer-app/         ── Demo: interactive login + update stream

🆕 What's New in v0.4.0

TL Schema — Layer 223 → 224

Updated api.tl from Layer 223 to Layer 224 (2,329 definitions, up from 2,295)
All generated types, functions and enums in layer-tl-types reflect Layer 224

MTProto Core Fixes

bad_msg auto-resend — messages rejected by the server are automatically re-queued
seq_no correction for error codes 32/33
Outgoing MsgsAck handling with periodic flush
Message container batching for lower round-trip overhead
gzip_packed support for large outgoing requests
future_salts prefetch and rotation before expiry
time_offset correction applied to all outgoing msg_id values
msg_resend_req handling from a sent-body cache

Connection / Session

Sent message body tracking for resend
pending_ack batching system
new_session_created / DestroySession lifecycle handling
New disconnect() method for graceful teardown

Update Engine

pts / seq / qts tracking with gap detection
Per-channel getChannelDifference loop
Update deadline detection triggers getDifference on stale sequences
PossibleGapBuffer for out-of-order update recovery

New Client APIs

send_reaction() — send a message reaction
set_admin_rights() — promote a user with AdminRightsBuilder
set_banned_rights() — restrict a user with BanRights
iter_participants() — lazy async iterator over all members
get_profile_photos() — fetch a user's profile photo list
get_permissions() — retrieve effective permissions of a user
edit_inline_message() — edit a message sent via inline mode

Search

SearchBuilder — fluent per-peer message search with date filters and limits
GlobalSearchBuilder — search across all dialogs

Updates & Keyboard

IncomingMessage: new markdown_text(), html_text(), and extended accessors
CallbackQuery: typed helpers for game_short_name, chat_instance, data
InlineSend::edit_message() support
Keyboard: added request_phone, request_geo, request_poll, request_quiz, game, buy, copy_text button constructors
Typing: topic typing via optional top_msg_id in send_chat_action

🚀 Quick Start

Add to your Cargo.toml:

[dependencies]
layer-client = "0.4.0"
tokio = { version = "1", features = ["full"] }

👤 User Account

use layer_client::{Client, Config, SignInError};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (client, _shutdown) = Client::connect(Config {
        session_path: "my.session".into(),
        api_id:       12345,          // https://my.telegram.org
        api_hash:     "abc123".into(),
        ..Default::default()
    }).await?;

    if !client.is_authorized().await? {
        let token = client.request_login_code("+1234567890").await?;
        let code  = "12345"; // read from stdin

        match client.sign_in(&token, code).await {
            Ok(name) => println!("Welcome, {name}!"),
            Err(SignInError::PasswordRequired(t)) => {
                client.check_password(*t, "my_2fa_password").await?;
            }
            Err(e) => return Err(e.into()),
        }
        client.save_session().await?;
    }

    client.send_message("me", "Hello from layer! 👋").await?;
    Ok(())
}

🤖 Bot

use layer_client::{Client, Config, update::Update};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (client, _shutdown) = Client::connect(Config {
        session_path: "bot.session".into(),
        api_id:       12345,
        api_hash:     "abc123".into(),
        ..Default::default()
    }).await?;

    client.bot_sign_in("1234567890:ABCdef...").await?;
    client.save_session().await?;

    let mut updates = client.stream_updates();
    while let Some(update) = updates.next().await {
        match update {
            Update::NewMessage(msg) if !msg.outgoing() => {
                if let Some(peer) = msg.peer_id() {
                    client.send_message_to_peer(
                        peer.clone(),
                        &format!("Echo: {}", msg.text().unwrap_or("")),
                    ).await?;
                }
            }
            Update::CallbackQuery(cb) => {
                client.answer_callback_query(cb.query_id, Some("Done!"), false).await?;
            }
            _ => {}
        }
    }
    Ok(())
}

✅ What Is Supported

🔐 Cryptography

AES-IGE encryption / decryption (MTProto 2.0)
RSA encryption with Telegram's public keys
SHA-1 and SHA-256 hashing
Auth key derivation from DH nonce material
PQ factorization (Pollard's rho)
Diffie-Hellman shared secret computation

📡 MTProto

Full 3-step DH key exchange handshake
MTProto 2.0 encrypted sessions
Proper message framing (salt, session_id, msg_id, seq_no)
msg_container (multi-message) unpacking
gzip-packed response decompression
Server salt tracking, pong, bad_server_salt handling
bad_msg_notification handling
Reconnect with exponential backoff + ±20% jitter
Network hint channel (signal_network_restored()) to skip backoff immediately

🚂 Transports

Abridged — default, single-byte length prefix (lowest overhead)
Intermediate — 4-byte LE length prefix, better proxy compat
Obfuscated2 — XOR stream cipher over Abridged, bypasses DPI / MTProxy

📦 TL Type System

Full .tl schema parser
Build-time Rust code generation
All Layer 224 constructors — 2,329 definitions
Serializable / Deserializable traits for all types
RemoteCall trait for all RPC functions
Optional: Debug, serde, name_for_id(u32)

👤 Auth

Phone code login (request_login_code → sign_in)
2FA SRP password (check_password)
Bot token login (bot_sign_in)
Sign out (sign_out)
DC migration — PHONE_MIGRATE_*, USER_MIGRATE_*, NETWORK_MIGRATE_*
FLOOD_WAIT auto-retry with configurable policy (RetryPolicy trait)
Configurable I/O error retry treated as a flood-equivalent delay

💬 Messaging

Send text message by username/peer (send_message, send_message_to_peer)
Send with full options — reply_to, silent, schedule, no_webpage, entities, markup via InputMessage builder
Send to Saved Messages (send_to_self)
Edit message (edit_message)
Edit inline bot message (edit_inline_message)
Forward messages (forward_messages)
Delete messages (delete_messages)
Get messages by ID (get_messages_by_id)
Get / delete scheduled messages
Pin / unpin message, unpin all messages
Get pinned message
Send chat action / typing indicator (send_chat_action)
TypingGuard — RAII wrapper, keeps typing alive on an interval, auto-cancels on drop
Send reactions (send_reaction)
Mark as read, clear mentions

📎 Media

Upload file from bytes — sequential (upload_file) and concurrent parallel-parts (upload_file_concurrent)
Upload from async AsyncRead stream (upload_stream)
Send file as document or photo (send_file)
Send multiple media in one album (send_multi_media)
Download media to file (download_media_to_file)
Chunked streaming download (DownloadIter)
Photo, Document, Sticker ergonomic wrappers with accessors
Downloadable trait for generic media location handling

⌨️ Keyboards & Reply Markup

InlineKeyboard row builder
Button types: callback, url, url_auth, switch_inline, switch_elsewhere, webview, simple_webview, request_phone, request_geo, request_poll, request_quiz, game, buy, copy_text
Reply keyboard (standard keyboard) builder
Answer callback query, answer inline query

📋 Text Parsing

Markdown parser → (plain_text, Vec<MessageEntity>)
HTML parser → (plain_text, Vec<MessageEntity>) (feature html)
spec-compliant html5ever tokenizer replacing parse_html (feature html5ever)
HTML generator (generate_html) always available, hand-rolled

👥 Participants & Chat Management

Get participants, kick, ban with BanRights builder, promote with AdminRightsBuilder
Get profile photos
Search peer members
Join chat / accept invite link
Delete dialog

🔍 Search

Search messages in a peer (SearchBuilder)
Global search across all chats (GlobalSearchBuilder)

📜 Dialogs & Iteration

List dialogs (get_dialogs)
Lazy dialog iterator (iter_dialogs)
Lazy message iterator per peer (iter_messages)

🔗 Peer Resolution

Resolve username → peer (resolve_username)
Resolve peer string (username, phone, "me") → InputPeer (resolve_peer)
Access-hash cache, restored from session across restarts

💾 Session Persistence

Binary file session (BinaryFileBackend) — default
In-memory session (InMemoryBackend) — testing / ephemeral bots
SQLite session (SqliteBackend) — feature sqlite
SessionBackend trait — plug in any custom backend
Catch-up mode (Config::catch_up) — replay missed updates via getDifference on reconnect

🌐 Networking

SOCKS5 proxy (Config::socks5, optional username/password auth)
Multi-DC pool — auth keys stored per DC, connections created on demand
invoke_on_dc — send a request to a specific DC
Raw escape hatch: client.invoke::<R>() for any Layer 224 method not yet wrapped

🔔 Updates

Typed update stream (stream_updates())
Update::NewMessage / MessageEdited / MessageDeleted
Update::CallbackQuery / InlineQuery / InlineSend
Update::Raw — unmapped TL update passthrough
PTS / QTS / seq / date gap detection and fill via getDifference
Per-channel PTS tracking

🛑 Shutdown

ShutdownToken returned from Client::connect — call .cancel() to begin graceful shutdown
client.disconnect() — disconnect without token

❌ What Is NOT Supported

These are high level gaps, not planned omissions, just not built yet. Use client.invoke::<R>() with raw TL types as a workaround for any of these.

Feature	Notes
Secret chats (E2E)	MTProto layer-2 secret chats not implemented
Voice / video calls	No call signalling or media transport
Payments	`SentCode::PaymentRequired` returns an error; payment flow not implemented
Group / channel creation	`createChat`, `createChannel` not wrapped
Channel admin tooling	No channel creation, migration, linking, or statistics — admin/ban rights are supported via `set_admin_rights` / `set_banned_rights`
Sticker set management	No `getStickerSet`, `uploadStickerFile`, etc.
Account settings	No profile update, privacy settings, notification preferences
Contact management	No `importContacts`, `deleteContacts`
Poll / quiz creation	No `InputMediaPoll` wrapper
Live location	Not wrapped
Bot menu / command registration	`setMyCommands`, `setBotInfo` not wrapped
IPv6	Config flag exists (`allow_ipv6: false`) but not tested
MTProxy with proxy secret	Obfuscated2 transport works; MTProxy secret mode untested

🔧 Feature Flags

`layer-tl-types`

Feature	Default	Description
`tl-api`	✅	High-level Telegram API schema
`tl-mtproto`	❌	Low-level MTProto schema
`impl-debug`	✅	`#[derive(Debug)]` on generated types
`impl-from-type`	✅	`From<types::T> for enums::E`
`impl-from-enum`	✅	`TryFrom<enums::E> for types::T`
`name-for-id`	❌	`name_for_id(u32) -> Option<&'static str>`
`impl-serde`	❌	`serde::Serialize` / `Deserialize`

`layer-client`

Feature	Default	Description
`html`	❌	Built-in hand-rolled HTML parser (`parse_html`, `generate_html`)
`html5ever`	❌	spec-compliant html5ever tokenizer replaces `parse_html`
`sqlite`	❌	SQLite session backend (`SqliteBackend`)

📐 Updating to a New TL Layer

# 1. Replace the schema
cp new-api.tl layer-tl-types/tl/api.tl

# 2. Build — types regenerate automatically
cargo build

🧪 Tests

cargo test --workspace

📄 License

Licensed under either of, at your option:

MIT License — see LICENSE-MIT
Apache License, Version 2.0 — see LICENSE-APACHE

👤 Author

Ankit Chaubey

Built with curiosity, caffeine, and a lot of Rust compiler errors. 🦀


🐙 GitHub	github.com/ankit-chaubey
🌐 Website	ankitchaubey.in
📬 Email	ankitchaubey.dev@gmail.com
📦 Project	github.com/ankit-chaubey/layer
📢 Channel	@layer_rs
💬 Chat	@layer_chat

🙏 Acknowledgements

Lonami for grammers. Portions of this project include code derived from the grammers project, which is dual-licensed under the MIT or Apache-2.0 licenses. The architecture, design decisions, SRP math, and session handling are deeply inspired by grammers. It's a fantastic library and an even better learning resource. Thank you for making it open source! 🎉
Telegram for the detailed MTProto specification.
The Rust async ecosystem — tokio, getrandom, flate2, and friends.
🤖 AI tools used for clearer documentation and better comments across the repo (2026 is a good year to use AI).
Even regrets 😁 after making these docs through AI. iykyk. Too lazy to revert and type again, so it stays as is!

⚠️ Telegram Terms of Service

As with any third-party Telegram library, please ensure that your usage complies with Telegram's Terms of Service. Misuse or abuse of the Telegram API may result in temporary limitations or permanent bans of Telegram accounts.

layer.. because sometimes you have to build it yourself to truly understand it.

layer 0.4.0