From 81765509247b29278e9f9eac237f6972fcf2a120 Mon Sep 17 00:00:00 2001
From: aigerimu <89766357+aigerimu@users.noreply.github.com>
Date: Fri, 19 Dec 2025 22:09:51 +0700
Subject: [PATCH] aliases

---
 languages/tolk/types/aliases.mdx | 39 ++++++++++++++------------------
 1 file changed, 17 insertions(+), 22 deletions(-)

diff --git a/languages/tolk/types/aliases.mdx b/languages/tolk/types/aliases.mdx
index ef8ef676a..2c0b69e0c 100644
--- a/languages/tolk/types/aliases.mdx
+++ b/languages/tolk/types/aliases.mdx
@@ -2,8 +2,7 @@
 title: "Type aliases"
 ---
 
-Tolk supports type aliases, similar to TypeScript and Rust.
-An alias creates a new name for an existing type and remains fully interchangeable with it.
+Tolk supports type aliases, similar to TypeScript and Rust. An alias creates a new name for an existing type and remains fully interchangeable with it.
 
 ```tolk
 type UserId = int32
@@ -14,14 +13,14 @@ fun calcHash(id: UserId): MaybeOwnerHash {
 }
 ```
 
-## Aliases are interchangeable with underlying types
+## Alias interchangeability
 
-`UserId` and `int32` from the above are fully equivalent:
+Aliases are interchangeable with underlying types. `UserId` and `int32` from the above example are fully equivalent:
 
-- `id + 1` is okay, will be `int`
-- `someF(id)` is okay if `someF` accepts `int32` or `int`
-- methods for `int32` can be called having `UserId` and vice versa (and for `int` also, because `int32` is assignable to `int`)
-- a union `UserId | int32` makes no sense, it is simply `int32`
+- `id + 1` is valid and produces `int`;
+- `someF(id)` is valid if `someF` accepts `int32` or `int`;
+- methods for `int32` can be called on `UserId` values and vice versa; and also for `int`, since `int32` is assignable to `int`;
+- a union `UserId | int32` is redundant and is equivalent to `int32`.
 
 ```tolk
 fun demo() {
@@ -34,7 +33,7 @@ fun demo() {
 }
 ```
 
-**To obtain a "strict alias"**, which defines a distinct type, use a struct with one field:
+To obtain a “strict alias”, which defines a distinct type, use a struct with one field:
 
 ```tolk
 struct UniqueId {
@@ -44,16 +43,16 @@ struct UniqueId {
 
 Such a struct has no overhead over `int32`, but it becomes a distinct type with its own methods and semantics.
 
-## Two equal aliases are considered different
+## Distinct alias types
 
-If two aliases share the same underlying type,
+Two aliases with the same underlying type are considered distinct. If two aliases share the same underlying type:
 
 ```tolk
 type AssetsDict = dict
 type BalanceDict = dict
 ```
 
-Then they are not assignable to each other. It allows them to have identical methods:
+Then, they are not assignable to each other. This allows them to define methods with identical names:
 
 ```tolk
 fun AssetsDict.validate(self) { /* ... */ }
@@ -66,23 +65,21 @@ fun demo(a: AssetsDict, b: BalanceDict) {
 }
 ```
 
-This reminds `intN` types: `int32` is assignable to `int` and back, `int64` also, but assigning `int32` to `int64` is something strange.
-Assignment can be done with explicit casting: `b as AssetsDict`, see [operator `as`](/languages/tolk/types/type-checks-and-casts).
+This behavior is similar to `intN` types: `int32` is assignable to `int`, and `int64` is assignable to `int`, but `int32` and `int64` are not assignable to each other. Assignment can be done with an explicit [cast](/languages/tolk/types/type-checks-and-casts). For example, `b as AssetsDict`.
 
-## Type aliases can be generic
+## Generic type aliases
+
+Type aliases can be [generic](/languages/tolk/types/generics).
 
 ```tolk
 type Wrapper<T> = Nothing | Container<T>
 ```
 
-Read about [generic structs and aliases](/languages/tolk/types/generics).
-
 ## Stack layout and serialization
 
-An alias is identical to its underlying type.
+A type alias is identical to its underlying type in [stack layout](/languages/tolk/types/overall-tvm-stack) and [serialization](/languages/tolk/types/overall-serialization).
 
-Serialization can be overloaded with custom serializers.
-This is useful in tricky cases where binary encoding cannot be expressed using existing types.
+Serialization behavior can be overloaded by defining custom serializers. This is useful when binary encoding cannot be expressed using existing types.
 
 ```tolk
 type MyString = slice
@@ -95,5 +92,3 @@ fun MyString.unpackFromSlice(mutate s: slice) {
     // custom logic
 }
 ```
-
-For details, follow [TVM representation](/languages/tolk/types/overall-tvm-stack) and [Serialization](/languages/tolk/types/overall-serialization).