Crate Architecture

layer is a workspace of focused, single-responsibility crates. Understanding the stack helps when you need to go below the high-level API.

Dependency graph

Your App
  └── layer-client          ← high-level Client, UpdateStream, InputMessage
        ├── layer-mtproto   ← MTProto session, DH, message framing
        │     └── layer-crypto  ← AES-IGE, RSA, SHA, factorize
        └── layer-tl-types  ← all generated types + LAYER constant
              ├── layer-tl-gen    (build-time code generator)
              └── layer-tl-parser (build-time TL schema parser)

layer-client

The high-level async Telegram client. Import this in your application.

What it provides

• Client — the main handle with all high-level methods
• Config — connection configuration
• Update enum — typed update events
• InputMessage — fluent message builder
• parsers::parse_markdown — Markdown → entities
• UpdateStream — async iterator
• Dialog, DialogIter, MessageIter — dialog/history access
• Participant, ParticipantStatus — member info
• UploadedFile, DownloadIter — media
• TypingGuard — auto-cancels chat action on drop
• SessionBackend trait + BinaryFileBackend, InMemoryBackend, SqliteBackend
• Socks5Config — proxy configuration
• Error types: InvocationError, RpcError, SignInError, LoginToken, PasswordToken
• Retry traits: RetryPolicy, AutoSleep, NoRetries, RetryContext

layer-tl-types

All generated Telegram API types. Auto-regenerated at cargo build from tl/api.tl.

What it provides

• LAYER: i32 — the current layer number (223)
• types::* — 1,200+ concrete structs (types::Message, types::User, etc.)
• enums::* — 400+ boxed type enums (enums::Message, enums::Peer, etc.)
• functions::* — 500+ RPC function structs implementing RemoteCall
• Serializable / Deserializable traits
• Cursor — zero-copy deserializer
• RemoteCall — marker trait for RPC functions
• Optional: name_for_id(u32) -> Option<&'static str>

Key type conventions

Most Telegram API fields use enums::* types because the wire format is polymorphic.

layer-mtproto

The MTProto session layer. Handles the low-level mechanics of talking to Telegram.

What it provides

• EncryptedSession — manages auth key, salt, session ID, message IDs
• authentication::* — complete 3-step DH key exchange
• Message framing: serialization, padding, encryption, HMAC
• msg_container unpacking (batched responses)
• gzip decompression of gzip_packed responses
• Transport abstraction (abridged, intermediate, obfuscated)

DH handshake steps

1. PQ factorization — req_pq_multi → server sends resPQ
2. Server DH params — req_DH_params with encrypted key → server_DH_params_ok
3. Client DH finish — set_client_DH_params → dh_gen_ok

After step 3, both sides hold the same auth key derived from the shared DH secret.

layer-crypto

Cryptographic primitives. Pure Rust, #![deny(unsafe_code)].

layer-tl-parser

TL schema parser. Converts .tl text into structured Definition values.

Parsed AST types

• Definition — a single TL line (constructor or function)
• Category — Types or Functions
• Parameter — a named field with type
• ParameterType — flags, conditionals, generic, basic
• Flag — flags.N?type conditional fields

Used exclusively by build.rs in layer-tl-types. You never import it directly.

layer-tl-gen

Rust code generator. Takes the parsed AST and emits valid Rust source files.

Output files (written to $OUT_DIR)

Each type automatically gets:

• impl Serializable — binary TL encoding
• impl Deserializable — binary TL decoding
• impl Identifiable — const CONSTRUCTOR_ID: u32
• Optional: impl Debug, impl From, impl TryFrom, impl Serialize/Deserialize