TON Storage Fees, Part 1: Understanding the Mechanism

Introduction

If you develop smart contracts on the TON blockchain—or plan to do so—you should understand the storage fee mechanism because it affects much more than just the cost of storing data.

Storage fees influence transaction execution, account status transitions, contract balances, and even the values visible inside the Compute phase. At first glance, storage fees may seem like a minor detail, but they can have important side effects that affect smart contract logic.

For example:

• msg_value visible inside TVM may differ from the original incoming message value;
• storage debt may survive across multiple transactions;
• account status can change from ACTIVE to FROZEN or DELETED;
• balance available during Compute phase may differ from what you expect.

Understanding how storage fees are calculated and collected will help you avoid subtle bugs and write more reliable smart contracts.

This article reflects the behavior of the current TVM implementation and was verified against the TON source code. Future protocol changes may affect implementation details.

If you are interested primarily in practical implications and development tips, see this:

➡ TON Storage Fees, Part 2: Important Notes and Practical Tips.

What Is the Storage Fee?

Storage fee is the fee paid for keeping a smart contract account on the blockchain.

Even if a contract stores no user data, the blockchain still stores:

• contract code;
• account metadata;
• balance information;
• account status information.

As a result, every deployed contract consumes blockchain storage and must periodically pay storage fees.

In this article, the terms contract and account are used interchangeably because every deployed smart contract corresponds to a blockchain account.

Storage fees depend on:

• the number of stored cells;
• the number of stored bits;
• the duration since the previous payment;
• network configuration parameters.

The larger the account state and the longer it remains unpaid, the larger the accumulated storage debt becomes.

Transaction Phases Refresher

A transaction may consist of:

1. Storage Phase
2. Credit Phase
3. Compute Phase
4. Action Phase
5. Bounce Phase

The Storage Phase is responsible for calculating and collecting storage fees.

The Credit Phase credits incoming value to the account balance.

The Compute Phase executes TVM code.

The order of Storage and Credit phases is particularly important for understanding storage fee collection.

Bounceable and Non-Bounceable Messages

TON supports two types of internal messages:

• bounceable;
• non-bounceable.

For bounceable messages:

Storage Phase
      ↓
Credit Phase
      ↓
Compute Phase

For non-bounceable messages:

Credit Phase
      ↓
Storage Phase
      ↓
Compute Phase

This difference is one of the most important concepts in the entire storage fee mechanism.

How the Storage Fee Mechanism Works

The algorithm and flowchart presented below are simplified versions of the actual implementation used by TVM. The real implementation contains additional branches, special cases, and optimizations that are not essential for understanding the storage fee mechanism. The goal of this article is to explain the core concepts and the effects of storage fee collection while keeping the explanation approachable. For the exact implementation, refer to transaction.cpp in the TON source code.

At a high level, the Storage Phase performs the following tasks:

1. Calculate storage fee accumulated since the previous payment.
2. Add previously unpaid storage debt.
3. Determine how much can be collected from the available balance.
4. Store any remaining debt as due_payment.
5. Check whether the account should remain active, become frozen, or be deleted.

Storage Fee Formula

Conceptually, storage fee depends on:

• elapsed time;
• number of stored cells;
• number of stored bits;
• storage prices.

Simplified:

Storage Fee = Time × Storage Size × Price

More precisely:

fee =
ceil(
    duration_seconds *
    (
        stored_cells * cell_price +
        stored_bits * bit_price
    )
    / 2^16
)

The important takeaway is simple:

Larger account state + longer unpaid period = larger storage debt.

Storage Fee Collection Algorithm

The simplified algorithm can be described as follows:

1. Determine the balance available at the beginning of the transaction.
2. If the incoming message is non-bounceable, credit its value first.
3. Calculate elapsed time since last_paid.
4. Calculate the new storage fee.
5. Add any existing due_payment.
6. Compare the total debt with the available balance.
7. Collect as much as possible.
8. Store the unpaid remainder as due_payment.
9. If the debt exceeds freeze thresholds, freeze the account.
10. If the debt exceeds deletion thresholds and the account is already not active, delete it.
11. If the incoming message is bounceable, credit its value after the Storage Phase.

Simplified Storage Fee Flowchart

The flowchart below is a simplified representation of the storage fee collection process. It focuses on ordinary accounts and omits several implementation-specific branches present in the TVM source code.

➡️ Open the Storage Fee Flowchart

The flowchart intentionally omits several implementation-specific branches present in transaction.cpp. Its purpose is to demonstrate the main storage fee collection flow and the behaviors most relevant to smart contract developers.

Key Variables After Storage Phase

The Storage Phase produces several values that affect subsequent phases:

• balance_before_compute
• msg_value_before_compute
• due_payment
• storage_phase.status_change

These values may differ from the original account balance and incoming message value.

Understanding them is important because they directly affect contract execution inside the Compute Phase.

Frozen and Deleted Accounts

TON defines several account states:

• ACTIVE
• FROZEN
• DELETED

When storage debt grows beyond certain thresholds and the account cannot pay it, the account may become frozen.

A frozen account no longer stores the full contract state. Instead, it stores a compact representation containing hashes of the original code and data together with account metadata.

As a result, frozen accounts consume dramatically less storage than active accounts.

Under normal circumstances:

ACTIVE
   ↓
FROZEN
   ↓
DELETED

An active account is not deleted immediately. It first becomes frozen and only later can be deleted if debt conditions are met.

Continue Reading

This article explained how storage fees are calculated and collected.

In Part 2 we will focus on practical implications, common pitfalls, and development techniques, including:

• why msg_value is not always equal to the original incoming message value;
• why my_balance - msg_value can be dangerous;
• why storage fees are collected only during transactions;
• how due_payment behaves;
• how to reserve funds correctly using my_storage_due().

Related Article

TON Storage Fees, Part 2: Important Notes and Practical Tips

Useful Links

• Simplified Storage Fee Flowchart
  https://raw.githubusercontent.com/a08778/ton-fee-lab/9f3d24abe6c4d2d56ac9506c2efbc69f563e5d1b/simplified_storage_fee_flowchart.svg

• TON transaction processing source code
  https://github.com/ton-blockchain/ton/blob/master/crypto/block/transaction.cpp

• TON blockchain configuration parameters
  https://tonviewer.com/config

• Storage fee research and tests
  https://github.com/a08778/ton-fee-lab

• TON documentation: account statuses
  https://docs.ton.org/blockchain-basics/primitives/status#status-variety

• TON documentation: transaction phases
  https://docs.ton.org/blockchain-basics/primitives/phases#storage-phase

• TON documentation: bounceable messages
  https://docs.ton.org/blockchain-basics/primitives/messages/internal#bounces