DEV Community: Salikh Osmanov

🔐 Admin Control in TON Stablecoins: What Every User Must Know

Salikh Osmanov — Sat, 14 Feb 2026 10:16:30 +0000

🧭 Introduction

One day I needed to choose a stablecoin for use in one of my startups.

Initially, I had only two options:

They are the most popular stablecoins on the TON blockchain.

To make a proper decision, I decided to explore their source codes.

I was surprised when I saw that admins of these contracts are able to perform operations that can potentially lead to loss of user funds and that go beyond standard fungible token functionality.

🛡️ Stablecoin Admin Permissions

I explored the following smart contracts in detail:

Both stablecoins are based on the stablecoin sample smart contract from the TON Foundation GitHub:

https://github.com/ton-blockchain/stablecoin-contract

In the README file of the repository, we can find the following text:

This project was created to allow users to exchange and buy assets in the TON DeFi ecosystem for a jetton (token or currency) that is not subject to volatile fluctuations.

To meet regulatory requirements, the issuer of the tokens must have additional control over the tokens.

Thus this jetton represents a standard TON jetton smart contract with additional functionality:

Admin of jetton can make transfers from user's jetton wallet.

Admin of jetton can burn user's jettons.

Admin of jetton can lock/unlock user's jetton wallet (set_status). Admin can make transfer and burn even if wallet locked.

Admin of jetton can change jetton-minter code and its full data.

I intentionally made the “To meet regulatory requirements” excerpt bold.

I think all stablecoins, in order to work normally without restrictions around the world, have to include the operations mentioned above.

But users have to be aware of that — they do not have full, exclusive control over their funds.

⚙️ Implementation Details

USDT contracts’ code is identical to the standard stablecoin contract.

USDe contracts’ code differs slightly in burn and mint mechanics, but in terms of regulatory features, they are the same.

If we look at the code, we will see the following operations that the admin can perform in a jetton wallet contract:

transfer
burn
set_status

Compared with the standard jetton contract, the standard stablecoin contract has an additional field named status.

So now every wallet smart contract has a status.

There are 4 statuses:

Status = 0 — No restrictions. The owner can transfer and receive funds. (Default status)
Status = 1 — User cannot send funds from the wallet.
Status = 2 — User cannot receive funds to the wallet.
Status = 3 — User cannot either send or receive funds.

The admin of the stablecoin can set any status for any wallet.

Even if a wallet is locked for sending funds, the admin of the jetton can still transfer.

But if a wallet is locked for receiving funds, no one can send funds to that wallet, including the admin.

🔥 Important Difference from Standard Jetton

In a stablecoin wallet, only the admin of the jetton can burn funds.

In the standard jetton contract, only the owner of the wallet can burn jettons.

This is a critical architectural difference.

🧾 Conclusion

I think it’s acceptable that an admin can perform some regulatory functions on a stablecoin user’s wallet.

But users must be aware of these mechanics.

Stablecoins on TON are not purely owner-controlled assets — they are controlled assets with administrative override.

Understanding this distinction is critical when choosing which stablecoin to trust and use.

How many addresses fit into a Cell?

Salikh Osmanov — Fri, 16 Jan 2026 18:15:40 +0000

Intro

While developing a smart contract, I needed to store several addresses in persistent storage. At first this looked trivial, but then a simple question came up: how many addresses can I actually fit into a single cell?

Since TON storage is measured in bits and cells, and both storage and message forwarding cost gas, answering this question precisely matters. To do that, we need to look at how addresses are defined and serialized at the TL-b level.

TL-b schemes

All address formats used in TON are defined in block.tlb. The relevant schemes are:

addr_none$00 = MsgAddressExt;

addr_extern$01 len:(## 9) external_address:(bits len)
= MsgAddressExt;

anycast_info$_ depth:(#<= 30) { depth >= 1 }
rewrite_pfx:(bits depth) = Anycast;

addr_std$10 anycast:(Maybe Anycast)
workchain_id:int8 address:bits256 = MsgAddressInt;

addr_var$11 anycast:(Maybe Anycast) addr_len:(## 9)
workchain_id:int32 address:(bits addr_len) = MsgAddressInt;

_ _:MsgAddressInt = MsgAddress;
_ _:MsgAddressExt = MsgAddress;

Address constructors

There are exactly four address constructors:

addr_none
addr_extern
addr_std
addr_var

Theoretical aspects: calculating address size

In this section we calculate exact bit sizes based strictly on the TL-B definitions.

`addr_none`

addr_none$00 = MsgAddressExt;

Constructor tag $00 → 2 bits

Exact size: 2 bits

`addr_extern`

addr_extern$01 len:(## 9) external_address:(bits len)

Components:

Constructor tag $01 → 2 bits
len:(## 9) → 9 bits
external_address:(bits len) → len bits, where len ∈ [0, 511]

Exact size formula:

2 + 9 + len = 11 + len bits

Minimum size: len = 0 → 11 bits

Maximum size: len = 511 → 522 bits

`addr_std`

addr_std$10 anycast:(Maybe Anycast) workchain_id:int8 address:bits256

Breakdown:

Constructor tag $10 → 2 bits
anycast:(Maybe Anycast)
- Presence flag → 1 bit
- If present:
  - depth:(#<=30) → 5 bits
  - rewrite_pfx:(bits depth) → depth bits, where depth ∈ [1, 30]
workchain_id:int8 → 8 bits
address:bits256 → 256 bits

Exact size formula:

2 + 1 + (anycast ? (5 + depth) : 0) + 8 + 256

Without anycast (presence bit = 0):

2 + 1 + 8 + 256 = 267 bits

With anycast, maximum depth = 30:

2 + 1 + (5 + 30) + 8 + 256 = 302 bits

`addr_var`

addr_var$11 anycast:(Maybe Anycast) addr_len:(## 9)
workchain_id:int32 address:(bits addr_len)

Components:

Constructor tag $11 → 2 bits
anycast:(Maybe Anycast)
- Presence flag → 1 bit
- If present:
- depth:(#<=30) → 5 bits
- rewrite_pfx:(bits depth) → depth bits
addr_len:(## 9) → 9 bits
workchain_id:int32 → 32 bits
address:(bits addr_len) → addr_len bits, where addr_len ∈ [0, 511]

Exact size formula:

2 + 1 + (anycast ? (5 + depth) : 0) + 9 + 32 + addr_len

Without anycast, maximum address length:

2 + 1 + 9 + 32 + 511 = 555 bits

With anycast, maximum depth = 30 and maximum address length:

2 + 1 + (5 + 30) + 9 + 32 + 511 = 590 bits

Practical assumptions (what really happens on mainnet)

Anycast is not used

Since TVM version 10, anycast addresses:

are not allowed as message destinations,
are not allowed in account addresses,
are no longer supported by address parsing and rewrite instructions.

In practice, this means the Maybe Anycast flag is always 0, and the Anycast payload is never present.

`addr_var` is not used

Currently active workchains (masterchain and basechain):

use addr_std,
use 256-bit account IDs,
use small workchain IDs.

addr_var exists for future extensions and is not used in real contracts today.

Practical address sizes

Internal address (`addr_std`, real usage)

2 (tag)
+ 1 (anycast flag)
+ 8 (workchain_id)
+ 256 (account_id)
= 267 bits

Exact size: 267 bits

This size is fixed.

External address (`addr_extern`, maximum)

2 (tag)
+ 9 (length)
+ 511 (payload)
= 522 bits

Summary

TON defines four address constructors: addr_none, addr_extern, addr_std, and addr_var.
Theoretical address sizes range from 2 bits to 590 bits.
On mainnet today:
- Anycast is unused.
- addr_var is unused.
- All internal addresses are addr_std.

As a result, the practical internal address size is fixed and exactly:

➡️ 267 bits

Knowing this exact value is essential when designing compact storage layouts, estimating gas costs, and deciding how many addresses can fit into a single cell.

3 Types of Authorization in TON Smart Contracts

Salikh Osmanov — Thu, 04 Dec 2025 20:48:10 +0000

Introduction

In smart contracts, we often need to allow certain actions only for specific actors.

A simple example is a wallet contract: we must authorize message senders to ensure only valid users can send funds.

So what options do we have?

In this article, I’d like to show three common ways to authorize messages in TON smart contracts.

1. Signature Verification

This mechanism is used for external messages.

Below is an example in FunC that checks a message signature.

It comes from the standard wallet-v3 contract:

https://github.com/ton-blockchain/ton/blob/d97fc197f07bb0070eeb3e6fcb8137a240ea5365/crypto/smartcont/wallet3-code.fc#L7

() recv_external(slice in_msg) impure {
  var signature = in_msg~load_bits(512);
  ;; some code
  var (stored_seqno, stored_subwallet, public_key) =
      (ds~load_uint(32), ds~load_uint(32), ds~load_uint(256));
  ;; 
  throw_unless(35, check_signature(slice_hash(in_msg), signature, public_key));
  accept_message();
  ;; other code
}

As we can see, the contract verifies the message’s signature using the public key stored in the contract’s data.

Why this cannot be used for internal messages

There are two main reasons:

Smart contracts must be deterministic.

Most cryptographic algorithms rely on randomness, which cannot be generated deterministically inside a smart contract.
Contract storage is public.

Therefore, private keys cannot be stored securely inside the contract.

Because of this, signature-based authorization only works for external messages.

2. Address Storage

This is the most widely used authorization method for internal messages.

We simply compare the sender’s address with the address stored in the contract’s storage.

Example from the standard NFT Collection contract:

https://github.com/ton-blockchain/nft-contract/blob/0b493104cd547d0fd52b7e6fd3c046fc365fe3d4/nft/nft-collection-editable.fc#L70

() recv_internal(cell in_msg_full, slice in_msg_body) impure {
    if (in_msg_body.slice_empty?()) {
        ;; ignore empty messages
        return ();
    }
    slice cs = in_msg_full.begin_parse();
    int flags = cs~load_uint(4);

    if (flags & 1) {
        ;; ignore all bounced messages
        return ();
    }

    slice sender_address = cs~load_msg_addr();

    int op = in_msg_body~load_uint(32);
    int query_id = in_msg_body~load_uint(64);

    var (owner_address, next_item_index, content, nft_item_code, royalty_params) = load_data();

    ;; some code

    throw_unless(401, equal_slices(sender_address, owner_address));

    ;; some code
}

The contract stores the owner address, and then throws if the sender does not match it.

This method allows storing multiple authorized addresses for different roles.

However, it is not ideal when we need to authorize many senders, such as in Jetton contracts.

3. Address Calculation

When a contract must authorize an arbitrary number of senders, we need a different approach.

A great example is the Jetton Wallet contract.

Whenever jettons are transferred, the receiver must verify whether the sender wallet truly belongs to the same Jetton Master.

Example from the standard Jetton Wallet:

https://github.com/ton-blockchain/jetton-contract/blob/d55f228edb0eb477cb4845d67e0dacc6489c6b57/contracts/jetton-wallet.fc#L83

() receive_jettons(slice in_msg_body, slice sender_address, int my_ton_balance, int msg_value)
    impure inline_ref {
    (int status, int balance, slice owner_address, slice jetton_master_address) = load_data();
    int query_id = in_msg_body~load_query_id();
    int jetton_amount = in_msg_body~load_coins();
    slice from_address = in_msg_body~load_msg_addr();
    slice response_address = in_msg_body~load_msg_addr();

    throw_unless(error::not_valid_wallet,
        equal_slices_bits(jetton_master_address, sender_address)
        |
        equal_slices_bits(
            calculate_user_jetton_wallet_address(
                from_address,
                jetton_master_address,
                my_code()
            ),
            sender_address
        )
    );

    ;; other code
}

Here, the contract calls

calculate_user_jetton_wallet_address(from_address, jetton_master_address, my_code())

and checks the result against the actual sender.

Note the use of my_code() — an instruction that returns the current contract code via the c7 register:

https://docs.ton.org/tvm/registers#c7-—-environment-information-and-global-variables

Important notes

You can also store another contract’s code in your storage to calculate addresses for external contracts.
Sometimes the sender must pass initialization parameters used during deployment. You must validate these parameters carefully.
If both contracts use the same known parameter (e.g., admin address), it is safer to read it from your own storage, not from the message.

Conclusion

I hope this article is helpful for newcomers to TON smart-contract development.

Choosing the right authorization strategy is an important part of designing a contract’s architecture.

Happy coding! 🚀

A Comprehensive Guide to Implicit Fields in TL-B

Salikh Osmanov — Thu, 09 Oct 2025 13:01:23 +0000

Introduction

In this article, we’ll dive deep into the concept of implicit fields in the TL-B language — a critical feature for understanding TON blockchain data structures.

When developing smart contracts on TON, TL-B schemas are used to define standardized cell layouts such as CommonMsgInfo, StateInit, and many others. Among all aspects of TL-B, implicit fields and their value-assignment rules are some of the trickiest to master.

Understanding implicit fields is essential for:

Correctly interpreting .tlb schemas
Implementing serialization and deserialization logic
Writing tools and parsers for TON data

In this article, we’ll explore:

What implicit fields are and how they are defined
Where and why they are used
The two main usage scenarios (parameterized types and derived values)
Constraints and the rules for constraint expressions
Best practices and naming conventions

Before you continue, it’s worth reviewing the official TL-B documentation:

Most examples in this article are drawn from the official TON TL-B schemas and documentation:

block.tlb — defines the structure of blocks and block headers
hashmap.tlb — defines hashmaps and their serialization in TL-B
boc.tlb — defines the Bag of Cells (BOC) container format

For deeper understanding of how these schemas are used in TON layouts, consult the official documentation:

Note: I’ll use TypeScript-style pseudocode to illustrate TL-B objects.

Understanding Implicit Fields in TL-B

According to the official TL-B documentation:

“Some fields may be implicit. These fields are defined within curly braces { }, indicating that they are not directly serialized. Instead, their values must be deduced from other data, usually the parameters of the type being serialized.”

Before diving deeper, let’s clarify a term used throughout this article — the resulting bitstring (or simply bitstring).

This is the binary string produced after serializing an object according to its TL-B definition. It represents the actual bits written into a cell and is used to reconstruct the object during deserialization.

For example:

const A = {
  x: 2,
  y: 3
};

and the corresponding TL-B combinator declaration:

constructor1$10 x:(## 4) y:(## 6) = A;

Serialization proceeds as follows:

The first two bits "10" represent the constructor tag.
Then we encode x = 2 using 4 bits: 0010.
Then we encode y = 3 using 6 bits: 000011.

The resulting bitstring is:

"10" + "0010" + "000011" → 100010000011

What Are Implicit Fields?

TL-B has two kinds of fields:

Explicit fields — values are represented in the resulting bitstring.
Implicit fields — values are not represented in the bitstring but are derived or passed as parameters.

Implicit fields make TL-B schemas more compact and expressive. They let you describe structural relationships and parameter dependencies without wasting bits on redundant data.

Defining Implicit Fields

Curly braces { } in TL-B can serve several purposes:

Defining implicit fields
Expressing constraints on values
Declaring computed or returned fields

The general syntax for an implicit field is:

{ field_name : field_type }

Allowed Field Types

Natural Numbers (#)

  { x:# }

Here, # represents a natural number (usually a 32-bit unsigned integer).

Type Parameters (Type)

  { X:Type }

Naming Conventions

Field Type	Naming Convention	Example
Natural number	lowercase	`{n:#}`
Type parameter	uppercase	`{X:Type}`

Constraints in TL-B

In TL-B, constraints are expressions enclosed in { } that specify conditions a value must satisfy.

They are not serialized — instead, they act as logical rules that implementations must enforce during serialization or deserialization.

Constraints are widely used in TON schemas to ensure consistency between related fields.

1. Boolean constraints

A simple comparison or logical assertion:

flags:(## 8) { flags <= 1 }

This means that the 8-bit field flags must not exceed 1.

Such constraints are checked during serialization or parsing, ensuring schema consistency.

2. Relational constraints

Constraints can express relationships between multiple fields:

seq_no:# vert_seq_no:# { vert_seq_no >= vert_seqno_incr }

Here, vert_seq_no must be greater than or equal to vert_seqno_incr.

No extra bits are stored — this condition just governs valid combinations of values.

3. Derived (computed) constraints

Constraints can also define the value of an implicit field, indicated by a tilde (~) operator:

{ prev_seq_no:# } { ~prev_seq_no + 1 = seq_no }

This means that prev_seq_no is implicitly defined by

prev_seq_no = seq_no − 1

(expressed as ~prev_seq_no + 1 = seq_no, since − is not allowed in TL-B).

It’s not read from the bitstring — instead, it’s derived from another value.

You can also use multiplication (*) to express relationships that would otherwise use division.

Since / is not permitted in TL-B, expressions such as “x = y / 2” must be rewritten using multiplication:

{ ~x * 2 = y }

This constraint means x = y / 2, but expressed through the only allowed operation *.

This pattern appears in TL-B when the number of elements, bits, or cells must be a multiple or divisor of another count.

If the tilde (~) operator still confuses you, I’ve written a detailed explanation of it and its usage in TL-B here: 👉 Negate Operator (~) in TL-B Explained

4. Fixed-value constraints

Sometimes, a constraint simply fixes a constant:

{ ~len = 8 }

This is equivalent to declaring that the implicit field len always equals 8.

Summary of Constraint Usage

Type	Purpose	Example
Boolean	Limit a value	`{ flags <= 1 }`
Relational	Relate two fields	`{ vert_seq_no >= vert_seqno_incr }`
Derived	Define one value from another	`{ ~prev_seq_no + 1 = seq_no }`
Fixed	Hard-coded constant	`{ ~len = 8 }`

Constraints are one of the most elegant features of TL-B — they make schemas self-validating, documenting both data layout and expected relationships.

Placement of Implicit Field Definitions

By convention, implicit field definitions — that is, parts like { prev_seq_no:# } which declare an implicit variable — are usually placed at the beginning of a combinator declaration.

These definitions introduce implicit parameters or values that may later be used by other fields or constraints in the same combinator.

However, this placement is a convention, not a strict requirement — they can appear anywhere within the definition as long as references remain valid.

In contrast, constraints (for example, { ~prev_seq_no + 1 = seq_no }) typically follow field definitions, since they describe logical relationships among already declared fields.

Example excerpt from block.tlb:

block_info#9bc7a987 version:uint32
  not_master:(## 1)
  after_merge:(## 1) before_split:(## 1)
  after_split:(## 1)
  want_split:Bool want_merge:Bool
  key_block:Bool vert_seqno_incr:(## 1)
  flags:(## 8) { flags <= 1 }
  seq_no:# vert_seq_no:# { vert_seq_no >= vert_seqno_incr }
  { prev_seq_no:# } { ~prev_seq_no + 1 = seq_no }
  shard:ShardIdent gen_utime:uint32
  start_lt:uint64 end_lt:uint64
  gen_validator_list_hash_short:uint32
  gen_catchain_seqno:uint32
  min_ref_mc_seqno:uint32
  prev_key_block_seqno:uint32
  gen_software:flags.0?GlobalVersion
  master_ref:not_master?^BlkMasterInfo
  prev_ref:^(BlkPrevInfo after_merge)
  prev_vert_ref:vert_seqno_incr?^(BlkPrevInfo 0)
  = BlockInfo;

Here, { prev_seq_no:# } and { ~prev_seq_no + 1 = seq_no } demonstrate implicit definition combined with a constraint.

Obtaining Values of Implicit Fields

Suppose we have:

_ {length:#} a:(## length) ...

Where does length come from?

Implicit fields get their values in two main ways:

Through type parameters — values are passed when instantiating a type.
Through constraints or derivation — values are computed or logically determined from other fields.

Example 1: Parameterized Implicit Field

Incorrect definition:

_ val:(## length) = IntVal length; // invalid

Here, length is not declared, so this schema is invalid.

Correct version:

_ {length:#} val:(## length) = IntVal length;

Now length is an implicit parameter — it’s passed in rather than serialized.

Example 2: Derived (Calculated) Implicit Field

We can define implicit fields whose values are derived from others using the tilde (~) operator.

For example:

_ {length:#} val:(## length) { ~length = 8 } = Int8BitVal;

Here { ~length = 8 } acts as a constraint, meaning “length must equal 8.”

Implementations can interpret this as a computed or fixed value.

Example 3: Returned Implicit Value

Sometimes a field’s value is returned by another type using the ~ notation:

_ {length:#} val:(## length) = IntVal length ~val;

This means that IntVal returns its val, making it accessible to the enclosing type.

We can then use this returned value:

_ {v:#} a:(IntVal 8 ~v) b:(## v) = A;

Here, v is an implicit field that obtains its value from IntVal 8 ~v, and that value determines the bit length of b.

Serialization and Deserialization

It’s important to distinguish between parameterized and derived implicit fields.

Parameterized fields must be known before serialization or deserialization, since their values define bit sizes or type choices.
Derived fields are computed during deserialization — they are not read from the bitstring but inferred from other data.

Example: Parameterized Field

_ {x:#} my_val:(## x) = A x;

If we serialize:

const A = { my_val: 5, x: 6 };

We must know x = 6 before serialization to encode the correct number of bits.

During deserialization, we also need x to know how many bits to read.

Resulting bitstring: 6 bits representing the binary form of 5 → 000101.

Example: Derived Field

_ {a:#} my_val:(## x) { ~x = a + 1 } = A;

Here, x is not provided externally.

Instead, during deserialization, after reading a, we can compute x = a + 1 and use it to read my_val.

Thus, calculated implicit fields are derived, not deserialized — their values are reconstructed logically.

Summary

Case	Source of Value	Serialization Behavior	Example
Explicit field	Directly stored in bitstring	Serialized	`a:(## 8)`
Implicit (parameterized)	Passed as type parameter	Not serialized	`{n:#} value:(## n)`
Implicit (derived)	Computed from other fields	Not serialized	`{ ~x = a + 1 }`
Constraint	Restriction or relation	Not serialized	`{ flags <= 1 }`
Returned value	Returned by nested type	Not serialized	`Type ~field`

Conclusion

Implicit fields and constraints are key features of TL-B that make TON schemas compact yet expressive.

They allow you to parameterize structures, enforce logical relationships, and define derived values — all without consuming extra bits in serialization.

When implementing parsers or code generators for TL-B, always remember:

Implicit ≠ serialized — their values come from parameters or computation.
Constraint expressions are limited: use + and * only, and express subtraction or division through equivalent additive or multiplicative forms.
Constraints { ~x = expr } and { condition } define logical relationships, not procedural code.
Placement is flexible, though usually at the beginning for clarity.

Mastering implicit fields and constraints will make your understanding of TON’s TL-B language much deeper and your tools more robust.

Negate Operator (`~`) in TL-B, Explained

Salikh Osmanov — Wed, 17 Sep 2025 14:29:45 +0000

Introduction

The negate operator (~, often called the “tilde”) is one of the trickiest parts of TL-B. It shows up all over TON schemas, and understanding it is essential for reading schemas, implementing serializers/deserializers, and building tooling.

Before diving in, it’s worth skimming:

And browsing real .tlb schemas in TON repositories:

Note: Examples below use TypeScript-style pseudo-objects for clarity.

Where `~` can appear—and what it does

~ appears in two places, with different roles:

Inside curly braces { … } on the left (fields) side of a combinator This is a constraint/equation context. You can:
- Define the value of an implicit field (not serialized) by equation.
- Constrain the value of an explicit field (serialized) by equation.

⚠️ { ~x = expr } does not “override” a field value.

It requires that the serialized value equals expr. If it doesn’t, validation fails.

On the right (type name) side after = … This is a return context. ~expr makes the constructor return an integer value that outer types can use as a parameter. Returned values don’t get serialized; they’re outputs from a type.

Using `~` in field/constraint equations

Constraint on an explicit field

_ val:(## 8) { ~val = 2 } = IntVal;

val is serialized as 8 bits.
The constraint requires val == 2.

This is equivalent to:

_ val:(## 8) { val = 2 } = IntVal;

For explicit fields, you can use constraints with or without ~. Both mean the same thing: the serialized value must satisfy the condition.

Defining an implicit field

Here’s a valid case with constant addition:

_ {limit:#} size:(## 8) { ~limit = size + 1 } = Sized;

limit is implicit.
It’s defined as one more than the serialized size.

Another valid case with constant multiplication:

_ {bits:#} bytes:(## 8) { ~bits = bytes * 8 } = ByteSized;

bits is implicit.
It’s always 8 × bytes.

And here’s the real hm_edge definition from hashmap.tlb showing variable + variable:

hm_edge#_ {n:#} {X:Type} {l:#} {m:#} 
  label:(HmLabel ~l n) { n = (~m) + l } 
  node:(HashmapNode m X) 
= Hashmap n X;

Explanation:

n, l, m are implicit parameters.
The label encodes a prefix of length l.
{ n = (~m) + l } is a constraint: the total key length n is equal to the remaining part size ~m plus the prefix length l.
The node encodes the subtree for the remaining m bits.
The type returns Hashmap n X.

This shows that variable + variable is legal in TL-B equations.

Allowed operators in these equations

Addition +
- constant + variable ✅
- variable + constant ✅
- variable + variable ✅ (as in n = (~m) + l)
Multiplication *
- constant × variable ✅
- variable × variable ❌ (not supported)
Equality = (to form the equation)

⚠️ Not allowed: subtraction (-), division (/), comparisons (<, <=, etc.)

Valid patterns

{ ~a = 2 }
{ ~a = b }
{ ~a = b + 1 }
{ ~a + 1 = b }     // equivalent to a = b - 1
{ ~a = 2 * b }
{ ~a * 2 = b }     // equivalent to a = b / 2
{ n = (~m) + l }   // variable + variable (as in hashmap.tlb)

Using with Type Parameters

First, let’s recall how parameters work for types.

How do variables work?

If we declare the following:

_ {size:#} a:(## size) = A size;

To serialize, we must provide the value of the size parameter. The object we want to serialize might look like this:

const A = {
    size: 8,
    a: 24
};

After serialization we get the following bitstring:

00011000

This is the binary representation of the value 24 (a field), written using 8 bits (as specified by the size parameter).

As we can see, the value of a parameter must be known before serializing an object.

The same is true when we want to deserialize.

Suppose we have the following bitstring:

0010000101

We must know how many bits to take in order to determine the value of the a field.

If the size parameter’s value is 3, then we take the first 3 bits (001) → a = 1.
If size is 4, then we take the first 4 bits (0010) → a = 2.

So, parameters of a type must be known for both serialization and deserialization.

Returning a value instead of passing a parameter

If we set a parameter with the negate operator (~) in front of it, then we don’t have to provide the value explicitly. Instead, the type will return a value that can be used as a parameter.

Example:

_ val:(## 8) = IntVal ~val;

Here, the constructor “returns” the value of the val field.

Example of usage

Suppose we have the following type declaration representing a cart item:

_ id:# price:(## 16) quantity:(## 8) = Item;

This is simple — we just have 3 properties. An object might look like:

const item1 = {
    id: 17,
    quantity: 2,
    price: 120
};

Now let’s define a cart type that can contain n items:

_ {n:#} items:(n * Item) = Cart n;

Here, n is implicit and sets the number of items. We pass the value through a parameter.

But suppose we want to serialize the number of items instead of passing n. That means we should use an explicit field rather than an implicit one:

_ n:# items:(n * Item) = Cart;

We can make the cart more advanced by introducing a separate type for metadata, e.g., storing the number of items (and potentially discounts, etc.):

_ items_count:# = CartMetaData;

But to connect it, we must return the value of items_count so it can be used in the Cart type:

_ id:# price:(## 16) quantity:(## 8) = Item;
_ items_count:# = CartMetaData ~items_count;
_ metadata:CartMetaData ~n items:(n * Item) = Cart;

Notice:

The n field in Cart is not implicit here, because its value is serialized in the bitstring.
CartMetaData returns items_count, which is then passed as n to the Cart.

An example object:

const my_cart = {
    metadata: {
        items_count: 2
    },
    items: [
        { id: 172, price: 100, quantity: 1 },
        { id: 23, price: 50, quantity: 4 }
    ]
};

⚠️ Reminder: all bits are stored in a Cell, and the size must not exceed 1023 bits. Larger objects must be split across cells.

Returning an expression

You can also return expressions, for example:

_ a:# b:# = TwoNat ~(a + b);
_ {sum:#} numbers:(TwoNat ~sum) = Example;

TwoNat encapsulates two numbers.
It also returns their sum, which can be used in another type.

Returning a constant

You can return constants as well:

_ a:# = A ~4;
_ {x:#} b:(A ~x) = B;

Here, A always returns 4. Therefore, the implicit variable x in B will always be 4.

Optional use

Unlike type parameters, returned values are optional. You may use them or simply ignore them.

_ val:# = A ~val;
_ a:A b:# = A_and_B;

Although A returns the value of its val field, A_and_B does not use it.

Even when parameters are present, returned values may still be omitted:

_ {length:#} val:(## length) = A ~val length;
_ a:(A 8) b:# = A_and_B;

Here:

8 is the parameter passed to A as its length.
A also returns val, but A_and_B doesn’t use it.

Recursive expression

Now let’s look at the case when the negate operator is used to recursively serialize an object or deserialize a bitstring.

The most common example is the unary type:

unary_zero$0 = Unary ~0;
unary_succ$1 {n:#} x:(Unary ~n) = Unary ~(n + 1);

This effectively means the following expansions:

unary_zero$0                       = Unary ~0;
unary_succ$1 {n:#} x:(Unary ~0)    = Unary ~1;
unary_succ$1 {n:#} x:(Unary ~1)    = Unary ~2;
unary_succ$1 {n:#} x:(Unary ~2)    = Unary ~3;
…
unary_succ$1 {n:#} x:(Unary ~n)    = Unary ~(n + 1);

In other words: each time we parse a unary_succ, we return one more than what we get after deserializing the next bit of the bitstring.

Using Unary in another type

Suppose we use Unary in the following type:

_ {l:#} len:(Unary ~l) = Example;

Let’s try to deserialize the bitstring 110 into an object of type Example.

We’ll build it step by step as a TypeScript object.

Step 1 — initialize

Example has no tag prefix, so we can start with an empty object:

const example = {
    len: { /* … */ },
    get l() {
        return this.len.n;
    }
};

Here:

len is of type Unary.
l is an implicit field, equal to the value returned by len.

Step 2 — first bit

The first bit of the bitstring is 1, so we use unary_succ. That gives us:

const example = {
    len: {
        x: { /* … */ },
        get n() {
            return this.x.n + 1;
        }
    },
    get l() {
        return this.len.n;
    }
};

Notice:

n is returned.
Its value is this.x.n + 1.

It would be more intuitive to write the schema as:

unary_succ$1 {n:#} x:(Unary ~(n-1)) = Unary ~n;

But two problems arise:

We can’t use calculations like (n-1) in field declarations.
The - operator is not supported in TL-B.

Step 3 — recurse

The remaining bitstring is 10.

The next bit is 1, so again we apply unary_succ:

const example = {
    len: {
        x: {
            x: { /* ... */ },
            get n() {
                return this.x.n + 1;
            }
        },
        get n() {
            return this.x.n + 1;
        }
    },
    get l() {
        return this.len.n;
    }
};

Step 4 — base case

The last bit is 0, which means we use unary_zero. That returns 0.

Final object:

const example = {
    len: {
        x: {
            x: { 
                n: 0
            },
            get n() {
                return this.x.n + 1;
            }
        },
        get n() {
            return this.x.n + 1;
        }
    },
    get l() {
        return this.len.n;
    }
};

Here n = 0 because unary_zero returns 0.

Result

If we run:

console.log(example.l);

We get 2, which means len:(Unary ~2).

Indeed, the bitstring 110 contains two 1 bits before the terminating 0.

Common pitfalls

{ ~val = 2 } vs { val = 2 } → ✅ both work on explicit fields.
{ ~val = 2 } checks, it doesn’t assign.
Addition: variable + variable ✅ (e.g. n = (~m) + l in hashmap.tlb).
Multiplication: only constant × variable ✅, variable × variable ❌.
No subtraction, division, or comparisons.
Returned values (~val) are optional.

Conclusion

The negate operator ~ has two roles:

In { … }, it defines implicit fields or enforces constraints.
On the right side of a type, it returns integers for outer contexts.

For explicit fields, constraints can be written with or without ~ — both are valid and equivalent.

For implicit fields, you must use ~ to define their values.

And as the hm_edge constructor in hashmap.tlb shows, variable + variable is fully supported in TL-B equations — while variable × variable remains unsupported.

Once you know these rules (and the limits of allowed operators), TL-B schemas with ~ become much clearer to read and implement.

Computing the actual size of a TON smart contract storage

Salikh Osmanov — Wed, 30 Jul 2025 20:02:13 +0000

Sometimes, it’s useful to know the exact size of the data stored by a smart contract. A contract must pay a storage fee, which depends on the size of the data stored.

In TON, data is stored in the c4 register of TVM as a Cell. Let’s briefly recall what a Cell is.

A Cell is a data structure that can contain up to 1023 bits and 4 references to other cells.
Read more: TON Documentation - Cell

The Cell is the fundamental building block of TVM.

How to Compute the Storage Size?

According to the official documentation, the FunC standard library provides the following functions to determine the size of a cell and a slice:

compute_data_size?
slice_compute_data_size?
compute_data_size
slice_compute_data_size

It’s essential to understand how the size is actually computed.

Let’s take a look at the description of the compute_data_size? function:

"Returns (x, y, z, -1) or (null, null, null, 0). It recursively calculates the number of unique cells x, data bits y, and cell references z in the directed acyclic graph (DAG) at cell c. This provides the total storage used by the DAG while recognizing identical cells. "

The key concepts here are:

Unique cells
Identical cell recognition

So, what does “unique cells” mean? And how does the function recognize identical cells?

Let’s explore this through research and practical tests.

Project description

To conduct this research, I created a project based on the Blueprint template. You can find the project here.

Note: I won’t include source code here to keep the article clean and focused on the results.

The project includes:

A smart contract for computing storage size
Sandbox tests
A script for running production tests

In the tests, there are only tests for the compute_data_size? and slice_compute_data_size? functions because the only difference between these and their strict versions (compute_data_size, slice_compute_data_size) is that the strict versions raise an exception if the number of unique cells in the cell structure exceeds the max_cells parameter passed to the functions.

Prerequisites

You need to have Node.js installed to run the project locally. For an IDE, Visual Studio Code is recommended, along with the FunC Language Support plugin by Whales Corp, which can be found here.

Smart contact description

The smart contract includes the following functionality:

Filling the storage with a custom Cell structure via an internal message with special opcode and custom cell data.
Computing storage size using compute_data_size? via the get_results_for_cell method.
Computing storage size using slice_compute_data_size? via the get_results_for_slice method.

The contract also computes the size of the input data during storage filling, verifying that computations on raw input data match those on stored internal data. This uses the ~dumb and ~strdump functions (debug primitives), and outputs can be seen when running Sandbox tests.

Test Cases & Observations

To understand how compute_data_size? and slice_compute_data_size? behave under different scenarios, a variety of test cases were designed using custom cell structures. These tests aim to explore how the computation distinguishes between unique and identical cells, how data and references affect uniqueness, and how the max_cells limit behaves. Each test case builds upon the previous one, gradually increasing in complexity and providing insights through both predictable and edge-case configurations.

An empty cell

First of all, let's compute the size of an empty cell — a cell with no data and no references.

const root = beginCell().endCell();

The functions return the following results:

uniqueCells: 1
dataBits: 0
references: 0
success: true

Nothing surprising. Let’s try to fill the cell with some data.

Not empty cell

In this case, we fill the cell with some data and get the results again.

const root = beginCell().storeStringTail("value 1").endCell();

Now the cell has 7 symbols of data, which is 56 bits in total (8 bits per symbol).

The function returns the following results:

uniqueCells: 1
dataBits: 56
references: 0
success: true

Again, the results are predictable. So how about references?

One reference

Now we add one more cell to see the results for two cells.

const cell_1 = beginCell().endCell();
const root = beginCell().storeRef(cell_1).endCell();

We have two cells with no data. The root cell refers to cell_1. cell_1 has no references.

This time we get the following results:

uniqueCells: 2
dataBits: 0
references: 1
success: true

No surprises here. There is one reference from root to cell_1, no data bits, and two cells total.

Let’s make our cell structure a bit more complicated.

No references / no value

In this case, we add a third cell which is identical to cell_1 (no data, no references) and observe how the functions work.

const cell_2 = beginCell().endCell();
const cell_1 = beginCell().endCell();
const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

We want to see how two identical cells (cell_1 and cell_2) are treated when computing the size of the cell structure.

Now we have the following results:

uniqueCells: 2
dataBits: 0
references: 2
success: true

The interesting part here is that we have only 2 unique cells. Therefore, we can make our first conclusion:

Cells with no data and no references are treated as one unique cell.

No references / the same value

But how about the data? What results do we get if we have no empty cells? First let’s try with the same data.

const cell_2 = beginCell().storeUint(0,1).endCell();
const cell_1 = beginCell().storeUint(0,1).endCell();
const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

cell_1 and cell_2 now contain the same 1-bit uint value 0.

After invoking functions, we get the results:

uniqueCells: 2
dataBits: 1
references: 2
success: true

We see that cell_1 and cell_2 are again treated as one unique cell. Due to that, data bits are 1 and unique cells are 2.

Our next conclusion is:

Cells with no references but with the same values are treated as one unique cell.

No references / different values

Logically, with different values, cells cannot be treated as identical. But programmers must verify hypotheses.

Let’s fill cell_1 and cell_2 with different values this time.

const cell_2 = beginCell().storeUint(1,1).endCell();
const cell_1 = beginCell().storeUint(0,1).endCell();
const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

cell_1 has value 0, and cell_2 has value 1.

After invoking functions, we get the results:

uniqueCells: 3
dataBits: 2
references: 2
success: true

This time, all cells are treated as unique.

We are done with no-reference cells. Let’s experiment with references.

References to the same cell

We complicate our cell structure by adding a fourth cell. We want to understand how two cells with no value (or the same values) and references to the same cell are treated.

const the_same_cell = beginCell().endCell();
const cell_2 = beginCell().storeRef(the_same_cell).endCell();
const cell_1 = beginCell().storeRef(the_same_cell).endCell();
const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

After running functions, we get:

uniqueCells: 3
dataBits: 0
references: 3
success: true

We see that cell_1 and cell_2 are treated as one unique cell. But there’s one more interesting thing: there are 3 references reported, although there are actually 4.

It’s interesting because references to identical cells are counted normally, but references from cells treated as one unique cell are counted only once.

We can conclude:

Cells with no value or the same values that refer to the same cell are treated as one unique cell.
References from cells treated as one unique cell are counted only once.

References to identical cells

With references to the same cell understood, how about references to identical cells? In this article, identical cells are synonymous with unique cells.

Let’s add one more cell to see how it works.

const cell_2_1 = beginCell().endCell();
const cell_1_1 = beginCell().endCell();
const cell_2 = beginCell().storeRef(cell_2_1).endCell();
const cell_1 = beginCell().storeRef(cell_1_1).endCell();
const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

Here, cell_1_1 and cell_2_1 are basically one unique cell (no data / no references).

The functions give the following results:

uniqueCells: 3
dataBits: 0
references: 3
success: true

We see that cell_1 and cell_2 are treated as unique cells. cell_1_1 and cell_2_1 are also unique cells. All references from identical cells are counted only once, so two actual references (from cell_1 to cell_1_1 and from cell_2 to cell_2_1) are counted as one reference.

Our next conclusion:

Cells with no data (or the same data) referring to identical cells are treated as one unique cell.

References to non-identical cells

To clarify that references to non-identical cells prevent treating our cells as unique, let’s check with code.

const cell_2_1 = beginCell().storeUint(1, 1).endCell();
const cell_1_1 = beginCell().storeUint(0, 1).endCell();
const cell_2 = beginCell().storeRef(cell_2_1).endCell();
const cell_1 = beginCell().storeRef(cell_1_1).endCell();

This time, cell_1_1 and cell_2_1 contain different values.

After invoking functions, we get:

uniqueCells: 5
dataBits: 2
references: 4
success: true

All 5 cells are different. Q.E.D.

Different references order

Now, we refer to identical cells, but the order of references is different. We use more than one reference per cell to check this, so our structure is more complex.

const bottom_cell_2 = beginCell().endCell();
const bottom_cell_1 = beginCell().storeUint(0,1).endCell();
const cell_2 = beginCell().storeRef(bottom_cell_2).storeRef(bottom_cell_1).endCell();
const cell_1 = beginCell().storeRef(bottom_cell_1).storeRef(bottom_cell_2).endCell();
const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

Both cell_1 and cell_2 refer to the same cells bottom_cell_1 and bottom_cell_2, but in different orders:

cell_1.ref1 --> bottom_cell_1
cell_1.ref2 --> bottom_cell_2

cell_2.ref1 --> bottom_cell_2
cell_2.ref2 --> bottom_cell_1

After invoking functions, we get:

uniqueCells: 5
dataBits: 1
references: 6
success: true

This leads to the conclusion:

If cells have the same data (or no data) and refer to the same cells, the order of references must be the same to treat them as one unique cell.

Identical structures except for the deepest level

Let’s check a scenario where two branches of our structure are absolutely identical at all intermediate levels, but differ in the very last referenced cell.

const cell_2_1_1 = beginCell().storeUint(3, 2).endCell();
const cell_1_1_1 = beginCell().storeUint(2, 2).endCell();

const cell_2_1 = beginCell().storeRef(cell_2_1_1).endCell();
const cell_1_1 = beginCell().storeRef(cell_1_1_1).endCell();

const cell_2 = beginCell().storeRef(cell_2_1).endCell();
const cell_1 = beginCell().storeRef(cell_1_1).endCell();

const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

Here, cell_1 and cell_2 refer to cells that have no value and exactly one reference each. But the deepest cells they point to — cell_1_1_1 and cell_2_1_1 — are different because they contain different values.

Results from compute_data_size?:

uniqueCells: 7
dataBits: 2
references: 6
success: true

Observation:
Even though the structures above the leaves are visually identical, the difference at the bottom means that all cells in both branches are treated as unique. This happens because uniqueness is checked recursively — if a referenced cell is different, its parent is automatically considered different, all the way up to the root.

Conclusion:
A difference at the deepest level propagates upward, making the entire branch unique in the computation.

Max cells limitation

As a final test, let’s look at the behavior when max_cells is limited to less than the actual number of cells.

const cell_2 = beginCell().storeUint(1,1).endCell();
const cell_1 = beginCell().storeUint(0,1).endCell();
const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

We have 3 unique cells. Let’s set max_cells parameter to 2 and see the results.

The functions return:

uniqueCells: null
dataBits: null
references: null
success: false

When the actual size of the cell structure exceeds max_cells, we get nulls.

But here we had 3 unique cells. How about 3 cells but only 2 unique ones?

Max cells limitation for actual / unique cells imbalance

We again have 3 cells but only 2 unique ones.

const cell_2 = beginCell().endCell();
const cell_1 = beginCell().endCell();
const root = beginCell().storeRef(cell_1).storeRef(cell_2).endCell();

The function invocation returns:

uniqueCells: 2
dataBits: 0
references: 2
success: true

This lets us conclude:

max_cells limits only the number of unique cells.

Production Tests

The project includes a script (testInProduction.ts) to run all tests on-chain.
Results in production match Sandbox results.

Possible Improvements

To reduce testing costs, modify the smart contract to return excess TON after storage is filled.

Final Conclusions

The functions (compute_data_size?, slice_compute_data_size?,compute_data_size,slice_compute_data_size) calculate:

Unique cells
Data bits
References

Cells are identical if:

They have the same data (or none)
Refer to identical cells
Reference order is the same

Additional rules and nuances:

References from identical cells are counted once
max_cells limits unique cells only
A difference in the deepest referenced cells propagates upward, making all parent cells along the branch unique, even if intermediate cells have the same data and structure

Afterword

The test cases explored in this article helped demystify the behavior of compute_data_size? and slice_compute_data_size? in the TON Virtual Machine. By analyzing different cell configurations, the results provided a clear understanding of how data size is calculated, how identical cells are treated, and how reference structures influence outcomes.

These insights are essential for developers aiming to optimize smart contract storage and cost in TON, ensuring both accuracy and efficiency in contract design.

DEV Community: Salikh Osmanov

🔐 Admin Control in TON Stablecoins: What Every User Must Know

🧭 Introduction

🛡️ Stablecoin Admin Permissions

⚙️ Implementation Details

🔥 Important Difference from Standard Jetton

🧾 Conclusion

How many addresses fit into a Cell?

Intro

TL-b schemes

Address constructors

Theoretical aspects: calculating address size

addr_none

addr_extern

addr_std

addr_var

Practical assumptions (what really happens on mainnet)

Anycast is not used

addr_var is not used

Practical address sizes

Internal address (addr_std, real usage)

External address (addr_extern, maximum)

Summary

3 Types of Authorization in TON Smart Contracts

Introduction

1. Signature Verification

Why this cannot be used for internal messages

2. Address Storage

3. Address Calculation

Important notes

Conclusion

A Comprehensive Guide to Implicit Fields in TL-B

Introduction

Understanding Implicit Fields in TL-B

What Are Implicit Fields?

Defining Implicit Fields

Allowed Field Types

Naming Conventions

Constraints in TL-B

1. Boolean constraints

2. Relational constraints

3. Derived (computed) constraints

4. Fixed-value constraints

Summary of Constraint Usage

Placement of Implicit Field Definitions

Obtaining Values of Implicit Fields

Example 1: Parameterized Implicit Field

Example 2: Derived (Calculated) Implicit Field

Example 3: Returned Implicit Value

Serialization and Deserialization

Example: Parameterized Field

Example: Derived Field

Summary

Conclusion

Negate Operator (`~`) in TL-B, Explained

Introduction

Where ~ can appear—and what it does

Using ~ in field/constraint equations

Constraint on an explicit field

Defining an implicit field

Allowed operators in these equations

Using with Type Parameters

How do variables work?

Returning a value instead of passing a parameter

Example of usage

Returning an expression

Returning a constant

Optional use

Recursive expression

Using Unary in another type

Step 1 — initialize

Step 2 — first bit

Step 3 — recurse

Step 4 — base case

Result

Common pitfalls

Conclusion

Computing the actual size of a TON smart contract storage

How to Compute the Storage Size?

Project description

`addr_none`

`addr_extern`

`addr_std`

`addr_var`

`addr_var` is not used

Internal address (`addr_std`, real usage)

External address (`addr_extern`, maximum)

Where `~` can appear—and what it does

Using `~` in field/constraint equations