mtcute/packages/tl/descriptions.yaml

# This file contains additional descriptions for TL objects,
# for example for objects/fields that don't have a description
# from Telegram documentation.
#
# By default, these descriptions are used as a fallback,
# but can also be used to overwrite original documentation.
#
# This file is licensed under MIT license.

# Big thanks to Durov team for not providing complete docs like this in the first place,
# and instead spreading the docs across dozens of pages without proper formatting or anything.

# Override TL objects' (classes/methods) description, or their arguments' descriptions.
# Type is defined by the first 2 symbols in key ("o_" for class/method, "u_" for union)
objects:
  o_mt_reqPq:
    desc: >
      Request for the first step of Authorization key derivation process.
      This method is deprecated, use {@link tl.mtproto.RawReqPqMultiRequest} instead.
      The difference is that when using this, only one server key is returned, while
      `req_pq_multi` will return multiple.      
    arguments:
      nonce: Randomly generated number (32-bit) that will be used in the later steps
  o_mt_reqPqMulti:
    desc: >
      Request for the first step of Authorization key derivation process.      
    arguments:
      nonce: Randomly generated number that will be used in the later steps
  o_mt_resPQ:
    desc: Response for the first step of Authorization key derivation process
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Random number generated by the server, used in the later steps
      pq: >
        Big endian representation of a natural number, which is a product
        of two different odd prime numbers. Normally, this value is `<= 2^63-1`.
        Client is expected to decompose this product to `p` and `q`.        
      serverPublicKeyFingerprints: |
        List of public RSA key fingerprints, which are computed as follows:
         - First, the modulus and the exponent are extracted from the key
         - Then, the following TL type is written: `rsa_public_key n:string e:string = RSAPublicKey`
           - This is a bare type, meaning there's no 4-byte type number before it
           - `n` is the modulus, `e` is the exponent, encoded as big-endian
         - Finally, SHA1 is computed, and its last 8 bytes are taken and parsed as LE long
           (i.e. `parse_int64_le(sha1(rsa_public_key).slice(-8))`)

        Client is expected to choose out of those keys any single one that it has
        embedded in itself and return one of them in the following request.        
  o_mt_reqDHParams:
    desc: Request for the second step of Authorization key derivation process.
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      p: Big endian encoded first factor. Note - `p < q`
      q: Big endian encoded second factor. Node - `p < q`
      publicKeyFingerprint: Fingerprint of the RSA key that the client has chosen
      encryptedData: |
        Encrypted payload, obtained as follows:
        - Let `newNonce` be a random 32-bit number
        - Let `data` be a serialization of either {@link tl.mtproto.RawP_q_inner_data}
          or {@link tl.mtproto.RawP_q_inner_data_temp} with the generated `newNonce`
        - `dataWithHash = concat(sha1(data), data, random_bytes(235 - data.length))`
        - `encryptedData = dataWithHash ^ key.exponent % key.modulus`, where `key` is the
          server public key which was chosen        
  o_mt_p_q_inner_data:
    desc: Inner data used for {@link tl.mtproto.RawReqDHParamsRequest}
    arguments:
      pq: Original product of `p` and `q` sent by the server
      p: Big endian encoded first factor. Note - `p < q`
      q: Big endian encoded second factor. Node - `p < q`
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      newNonce: New client nonce generated
  o_mt_p_q_inner_data_temp:
    desc: >
      Inner data used for {@link tl.mtproto.RawReqDHParamsRequest}.
      Unlike {@link tl.mtproto.RawP_q_inner_data}, this is used to generate
      a temporary key.      
    arguments:
      pq: Original product of `p` and `q` sent by the server
      p: Big endian encoded first factor. Note - `p < q`
      q: Big endian encoded second factor. Node - `p < q`
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      newNonce: New client nonce generated
      expiresIn: >
        Maximum number of seconds that this key will be valid for.
        The server might discard the key earlier.        
  o_mt_server_DH_params_fail:
    desc: PQ decomposition was incorrect, try again.
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
  o_mt_server_DH_params_ok:
    desc: PQ decomposition was correct, server-side variables for DH are returned
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      encryptedAnswer: |
        Encrypted DH parameters, obtained as follows:
         - Let `answer` be a serialization of {@link tl.mtproto.RawServer_DH_inner_data}
         - `hash1 = sha1(concat(newNonce, serverNonce))`
         - `hash2 = sha1(concat(serverNonce, newNonce))`
         - `hash3 = sha1(concat(newNonce, newNonce))`
         - `key = concat(hash1, hash2.slice(0, 12))`
         - `iv = concat(hash2.slice(12, 20), hash3, newNonce.slice(0, 4))`
         - `encryptedAnswer = aes256_ige_encrypt(answer, key, iv)        
  o_mt_server_DH_inner_data:
    desc: >
      Inner data that is returned in {@link tl.mtproto.RawServer_DH_params_ok},
      containing server-side variables for Diffie-Hellman exchange      
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      g: '`g` number (generator) used for Diffie-Hellman'
      dhPrime: '`p` prime number (modulus) used for Diffie-Hellman'
      gA: '`gA` number (`gA = g ^ A % p`, where `A` is server secret) used for Diffie-Hellman'
      serverTime: Server UNIX timestamp (in seconds)
  o_mt_setClientDHParams:
    desc: Request containing encrypted client-side variables for Diffie-Hellman exchange
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      encryptedData: |
        Encrypted DH parameters, obtained as follows:
         - Let `B` be a random 2048-bit (256 bytes) integer
         - `gB = g ^ B % dhPrime` (Diffie-Hellman)
         - Let `data` be a serialization of {@link tl.mtproto.RawClient_DH_inner_data}
         - `dataWithHash = concat(sha1(data), data, padding))`, where `padding` is
           0-15 random bytes, such that `dataWithHash.length` is divisible by 16
         - `encryptedData = aes256_ige_encrypt(dataWithHash, key, iv)`, where `key` and `iv`
           are the same as ones used in {@link tl.mtproto.RawServer_DH_params_ok}        
  o_mt_client_DH_inner_data:
    desc: >
      Inner data of {@link tl.mtproto.RawSetClientDHParamsRequest},
      containing client-side variables for Diffie-Hellman exchange      
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      retryId: >
        Retry ID. When requesting for the first time, `0`,
        then last `authKeyAuxHash` is used        
      gB: '`gB` number (`gB = g ^ B % p`, where `B` is client secret) used for Diffie-Hellman'
  с_mt_dh_gen_ok:
    desc: >
      DH exchange was successful, and auth key is `gA ^ b % dhPrime`,
      and `authKeyAuxHash = sha1(authKey).slice(0, 8)`      
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      newNonceHash1: >
        Nonce hash, computed as follows: `sha1(concat([newNonce, [0x01], authKeyAuxHash])`        
  o_mt_dh_gen_retry:
    desc: >
      DH exchange need to be retried. Current auth key is `gA ^ b % dhPrime`,
      and `authKeyAuxHash = sha1(authKey).slice(0, 8)`, but they will change.

      When this is received, you are expected to send
      another {@link tl.mtproto.RawSetClientDHParamsRequest}.      
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      newNonceHash2: >
        Nonce hash, computed as follows: `sha1(concat([newNonce, [0x02], authKeyAuxHash])`        
  o_mt_dh_gen_fail:
    desc: DH exchange failed. You should restart the entire authorization flow.
    arguments:
      nonce: Client nonce that was generated earlier
      serverNonce: Server nonce that was received earlier
      newNonceHash3: >
        Nonce hash, computed as follows: `sha1(concat([newNonce, [0x03], authKeyAuxHash])`        
  o_mt_rpc_result:
    desc: Result of an RPC call
    arguments:
      reqMsgId: Requesting message ID
      result: Result of the call
  o_mt_rpc_error:
    desc: >
      RPC call resulted in an error, information about that error.
      Error is still a result, and thus it is sent as a `result`
      of {@link tl.mtproto.RawRpc_result}      
    arguments:
      errorCode: Numeric error code (like 404)
      errorMessage: String error code
  с_mt_rpc_answer_unknown:
    description: Nothing is known about this RPC call
  o_mt_rpc_answer_dropped_running:
    desc: >
      Response was canceled while the RPC query was being processed
      (where the RPC query itself was still fully processed); in this case,
      the same rpc_answer_dropped_running is also returned in response to
      the original query, and both of these responses require
      an acknowledgment from the client.      
  o_mt_rpc_answer_dropped:
    desc: The RPC response was removed from the server’s outgoing queue
    arguments:
      msgId: Message ID of the RPC response
      seqNo: Seq NO of the RPC response
      bytes: Length in bytes of the RPC response
  o_mt_future_salt:
    desc: Information about a single future server salt
    arguments:
      validSince: UNIX time in seconds from when this salt will be used
      validUntil: UNIX time in seconds until which this salt will be used
      salt: The server salt itself
  o_mt_future_salts:
    desc: Information about future server salts
    arguments:
      reqMsgId: Requesting message ID
      now: Current server UNIX timestamp in seconds
      salts: List of future salts
  o_mt_pong:
    desc: Response to a {@link tl.mtproto.RawPingRequest}
    arguments:
      msgId: Message ID that contained `mt_ping`
      pingId: Ping ID that was sent in `mt_ping`
  o_mt_ping:
    desc: Ping a server to test connection
    arguments:
      pingId: Random ping ID
  o_mt_pingDelayDisconnect:
    desc: >
      Works like ping. In addition, after this is received,
      the server starts a timer which will close the current connection
      `disconnectDelay` seconds later unless it receives a new message
      of the same type which automatically resets all previous timers.

      If the client sends these pings once every 60 seconds, for example,
      it may set `disconnect_delay` equal to 75 seconds.      
    arguments:
      pingId: Random ping ID
      disconnectDelay: Disconnect delay in seconds
  o_mt_destroy_session:
    desc: >
      Used by the client to notify the server that it may forget the
      data from a different session belonging to the same user
      (i.e. with the same `authKeyId`).

      The result of this being applied to the current session is undefined.      
    arguments:
      sessionId: Old session ID
  o_mt_destroy_session_ok:
    desc: Session was succesfully destroyed
    arguments:
      sessionId: Old session ID
  o_mt_destroy_session_none:
    desc: Session was not destroyed because it does not exist
    arguments:
      sessionId: Old session ID
  o_mt_new_session_created:
    desc: >
      The server notifies the client that a new session (from the server’s standpoint)
      had to be created to handle a client message. If, after this, the server receives
      a message with an even smaller `msg_id` within the same session, a similar
      notification will be generated for this `msg_id` as well.
      No such notifications are generated for high msg_id values.

      This notification must be acknowledged by the client. It is necessary, for instance,
      for the client to understand that there is, in fact, a “gap” in the stream of notifications
      received from the server (the user may have failed to receive
      notifications during some period of time).

      Client should also resend all the messages that were sent before `firstMsgId`      
    arguments:
      firstMsgId: First message ID that is known by the server to be from this session.
      uniqueId: Random number generated by the server every time a session is (re-)created
      serverSalt: Current server salt
  o_mt_msg_container:
    desc: A simple container that carries several messages
    arguments:
      messages: List of messages in the container
  o_mt_message:
    desc: A message in the container
    arguments:
      msgId: Original message ID
      seqno: Original message seq No
      bytes: Length of the message
      body: Contents of the message
  o_mt_msg_copy:
    desc: A copy of a message
    arguments:
      origMessage: Original message
  o_mt_gzip_packed:
    desc: >
      An object, which was gzipped.

      At the present time, it is supported in the body
      of an RPC response (i.e., as result in `rpc_result`)
      and generated by the server for a limited number
      of high-level queries. In addition, in the future
      it may be used to transmit non-service messages
      (i. e. RPC queries) from client to server.      
    arguments:
      packedData: Gzipped contents of the message
  o_mt_msgs_ack:
    desc: >
      Receipt of virtually all messages (with the exception of some purely
      service ones as well as the plain-text messages used in the protocol
      for creating an authorization key) must be acknowledged.

      This requires the use of the this service message (not requiring an acknowledgment itself)

      A server usually acknowledges the receipt of a message
      from a client (normally, an RPC query) using an RPC response.
      If a response is a long time coming, a server may first send a
      receipt acknowledgment, and somewhat later, the RPC response itself.

      A client normally acknowledges the receipt of a message
      from a server (usually, an RPC response) by adding an acknowledgment
      to the next RPC query if it is not transmitted too late (if it is
      generated, say, 60-120 seconds following the receipt of a message
      from the server). However, if for a long period of time there is no
      reason to send messages to the server or if there is a large number of
      unacknowledged messages from the server (say, over 16),
      the client transmits a stand-alone acknowledgment.      
    arguments:
      msgIds: IDs of messages to be acknowledged. Maximum 8192 IDs.
  o_mt_bad_msg_notification:
    desc: Used by the server to notify client that the sent message was incorrect.
    arguments:
      badMsgId: ID of the "bad" message
      badMsgSeqno: Seq No of the "bad" message
      errorCode: |
        Error code. Known values:
         - `16`: Message ID was too small. Most likely, client time is wrong, it would be
           worthwhile to synchronize it using notification's message ID and re-send the
           original message with the "correct" message ID or wrap it in a container
           with a new message ID if the original message had waited too
           long on the client to be transmitted.
         - `17`: Message ID was too big. Similar to the previous case,
           the client time has to be synchronized, and the message re-sent
         - `18`: Incorrect two lower order msg_id bits. The server expects client
           message ID to be divisible by 4.
         - `19`: Container message ID is the same as the message ID of the previous message
         - `20`: Message is too old, and it cannot be verified whether the server
           has received a message with this ID or not
         - `32`: Message seq No was too small (the server has already received a message
           with a higher or same seq No)
         - `33`: Message seq No was too big (the server has already received a message
           with a lower or same seq No)
         - `34`: An even seq No expected (not content-relevant), but odd received
         - `35`: An odd seq No expected (content-relevant), but even received
         - `48`: Incorrect server salt was used. In practice, `mt_bad_server_salt` is used instead.
         - `64`: Incorrect container        
  o_mt_bad_server_salt:
    desc: Used by the server to notify client that the sent message was incorrect.
    arguments:
      badMsgId: ID of the "bad" message
      badMsgSeqno: Seq No of the "bad" message
      errorCode: Always `48`
      newServerSalt: New server salt to be used
  o_mt_msg_resend_req:
    desc: |
      Explicit Request to Re-Send Messages

      The remote party immediately responds by re-sending
      the requested messages, normally using the same connection
      that was used to transmit the query. If at least one message
      with requested ID does not exist or has already been forgotten,
      or has been sent by the requesting party (known from parity),
      `MsgsStateInfo` is returned for all messages requested as if the
      `MsgResendReq` query had been a `MsgsStateReq` query as well.      
    arguments:
      msgIds: IDs of the messages to be resent (up to 8192 IDs)
  o_mt_msg_resend_ans_req:
    desc: |
      Explicit Request to Re-Send Answers

      The remote party immediately responds by re-sending *answers*
      to the requested messages, normally using the same connection
      that was used to transmit the query. `MsgsStateInfo` is returned
      for all messages requested as if the `MsgResendReq` query had
      been a `MsgsStateReq` query as well.      
    arguments:
      msgIds: IDs of the messages answers to which should be resent (up to 8192 IDs)
  o_mt_msgs_state_req:
    desc: >
      Request for Message Status Information. If either party has
      not received information on the status of its outgoing
      messages for a while, it may explicitly request it from the other party      
    arguments:
      msgIds: IDs of the messages state of which should be sent (up to 8192 IDs)
  o_mt_msgs_state_info:
    desc: Informational Message regarding Status of Messages
    arguments:
      reqMsgId: Requesting message ID
      info: |
        Byte array containing exactly one byte for each message ID:
         - `1`: nothing is known about the message (ID is too small, the other party may have forgotten it)
         - `2`: message was not received (ID falls within the range of stored identifiers;
           however, the other party has certainly not received a message like that)
         - `3`: message not received (ID is too big; however, the other
           party has certainly not received it yet)
         - `4`: message received (note that this response is also at the same time a receipt acknowledgment)
         - `+8`: message already acknowledged
         - `+16`: message not requiring acknowledgment
         - `+32`: RPC query contained in message being processed or processing already complete
         - `+64`: content-related response to message already generated
         - `+128`: other party knows for a fact that message is already received        
  o_mt_msgs_all_info:
    desc: >
      Voluntary Communication of Status of Messages. Either party may
      voluntarily inform the other party of the status of the messages
      transmitted by the other party.      
    arguments:
      msgIds: Message IDs that the other party is being informed about
      info: Byte array in the same format as {@link tl.mtproto.RawMsgs_state_info}
  o_mt_msg_detailed_info:
    desc: |
      Extended Voluntary Communication of Status of One Message.

      Normally used by the server to respond to the receipt of
      a duplicate message ID, especially if a response to the
      message has already been generated and the response is large.
      If the response is small, the server may re-send the answer
      itself instead. This message can also be used as a notification
      instead of resending a large message.      
    arguments:
      msgId: Original message ID that this message is informing about
      answerMsgId: Message ID that was the response to that message
      bytes: Size of the answer message
      status: Always `0`, but this may change in the future
  o_mt_msg_new_detailed_info:
    desc: >
      Similar to {@link tl.mtproto.RawMsg_detailed_info}, but
      used to notify about messages that were created on the server
      not in response to an RPC query (e.g. updates) and were transmitted
      to the client some time ago, but not acknowledged      
    arguments:
      answerMsgId: ID of the message that was sent by the server
      bytes: Size of the answer message
      status: Always `0`, but this may change in the future
  o_mt_rpcDropAnswer:
    desc: >
      Cancellation of an RPC query.
      In certain situations, the client does not want to receive a
      response to an already transmitted RPC query, for example because
      the response turns out to be long and the client has decided to do
      without it because of insufficient link capacity. Simply interrupting
      the connection will not have any effect because the server would re-send
      the missing response at the first opportunity. Therefore, the client needs
      a way to cancel receipt of the RPC response message, actually acknowledging
      its receipt prior to it being in fact received, which will settle the server
      down and prevent it from re-sending the response. However, the client does
      not know the RPC response's message ID prior to receiving the response;
      the only thing it knows is the requesting message ID, i.e. the message ID
      of the relevant RPC query. Therefore, this special query is used      
    arguments:
      reqMsgId: ID of a message containing an RPC query to be cancelled


# Override arguments wherever they are, based on the filters
arguments:
  - name: gigagroup
    filters:
      - type: "true"
    desc: Is this a broadcast group?

# Replace any description, based on regex. Used to fix typos.
regex:
  - regex: \bchanel\b
    repl: channel
  - regex: \bgeoposition\b
    repl: geo position
  - regex: \bgeogroup\b
    repl: geo group
  - regex: \bunixdate\b|Unix timestamp
    repl: UNIX timestamp in seconds
  - regex: \bstickerset\b
    repl: stickerset
  - regex: \bonly "foursquare" needs\b
    repl: only "foursquare" and "gplaces" need
  # gender-neutral pronouns
  - regex: \bhis\b
    repl: their
  - regex: \bhim\b
    repl: them