TON Architecture: How It Works

Under normal conditions, a single shard handles all transactions for the workchain.

When a shard becomes overloaded, it automatically splits into two shards. Accounts starting with "0" go to one shard, accounts starting with "1" go to the other.

Each new shard can split again if needed. The process is recursive — the network can keep splitting until every account has its own shard if necessary.

When shards are underutilized, they merge back together. The network dynamically adjusts to actual demand.

Go: open a terminal in a folder you can write to, e.g. cd ~/Desktop (Windows: cd %USERPROFILE%\Desktop).

Do: save this as shard.py and run python3 shard.py. The rule is the whole design in one line: an account’s shard is decided by the leading bits of its address.

import hashlib

def shard_of(account_hash: bytes, depth: int) -> str:
    """TON assigns an account to a shard by the FIRST bits of its address."""
    bits = "".join(f"{b:08b}" for b in account_hash[:2])
    return bits[:depth] if depth else "(one shard)"

account = hashlib.sha256(b"finkatana practice account").digest()
print("account starts:", account.hex()[:8], "=",
      "".join(f"{b:08b}" for b in account[:2]))
for depth in (0, 1, 2, 3, 4):
    print(f"  split into {2**depth:>2} shard(s): this account lives in shard {shard_of(account, depth)}")

You should see: one account’s home becoming more specific as the chain splits:

account starts: 39f25911 = 0011100111110010
  split into  1 shard(s): this account lives in shard (one shard)
  split into  2 shard(s): this account lives in shard 0
  split into  4 shard(s): this account lives in shard 00
  split into  8 shard(s): this account lives in shard 001
  split into 16 shard(s): this account lives in shard 0011

Notice what this buys: when a shard splits, nothing moves. Each account’s new home is just one bit longer than its old one, so a split is a pure bookkeeping change and anybody can work out where an account lives from its address alone, with no lookup and no directory.

If not: if every line shows the same shard, the slice bits[:depth] is being ignored — check that depth is the loop variable and not a fixed number.

Go: same folder. A sharding scheme that piles everyone into one shard has achieved nothing.

Do: save this as spread.py and run it. It places a hundred thousand accounts and measures the gap between the busiest and quietest shard.

import hashlib
from collections import Counter

def shard_of(account_hash, depth):
    return "".join(f"{b:08b}" for b in account_hash[:2])[:depth]

for depth in (2, 4):
    counts = Counter(shard_of(hashlib.sha256(f"user-{i}".encode()).digest(), depth)
                     for i in range(100_000))
    smallest, largest = min(counts.values()), max(counts.values())
    print(f"{2**depth:>2} shards: {len(counts)} in use, "
          f"smallest {smallest:,}, largest {largest:,}, "
          f"imbalance {largest / smallest - 1:.1%}")

You should see: an almost perfectly even split:

 4 shards: 4 in use, smallest 24,758, largest 25,350, imbalance 2.4%
16 shards: 16 in use, smallest 6,143, largest 6,371, imbalance 3.7%

The evenness is not luck — it is what a cryptographic hash is for. Because addresses are hashes, their leading bits are effectively random, so accounts fall into shards uniformly without anybody organising it. This is the property that makes “split when busy” a workable rule.

If not: if the imbalance is very large, the accounts are not being hashed — feeding sequential numbers straight in, without sha256, produces exactly the clustering this design avoids. That is worth doing once, to see it.

Go: same folder. Everything has a price, and here it is.

Do: save this as crossing.py and run it. It picks twenty thousand random sender-receiver pairs and asks how often the two are in different shards.

import hashlib, random

def shard_of(account_hash, depth):
    return "".join(f"{b:08b}" for b in account_hash[:2])[:depth]

random.seed(11)
users = [hashlib.sha256(f"user-{i}".encode()).digest() for i in range(1000)]

for depth in (1, 2, 4, 8):
    cross = sum(shard_of(random.choice(users), depth) != shard_of(random.choice(users), depth)
                for _ in range(20_000))
    print(f"{2**depth:>3} shards: {cross / 20_000:.1%} of transfers cross a shard boundary "
          f"(theory {1 - 1 / 2**depth:.1%})")

You should see: the measurement landing on the theory:

  2 shards: 50.3% of transfers cross a shard boundary (theory 50.0%)
  4 shards: 75.1% of transfers cross a shard boundary (theory 75.0%)
 16 shards: 93.6% of transfers cross a shard boundary (theory 93.8%)
256 shards: 99.5% of transfers cross a shard boundary (theory 99.6%)

Past a handful of shards, essentially every transfer is cross-shard. That is why TON is built around asynchronous messages rather than the single instant transaction people expect: your transfer leaves one shard as a message and is delivered into another. It is a deliberate trade — unlimited capacity in exchange for transfers that complete in steps rather than at once, which is also why a TON transfer can be accepted on one side before it has landed on the other.

If not: if the measured figures sit far from the theory, the two random.choice calls are being replaced by one value — sender and receiver must be drawn separately.

Go: same folder. Sixteen chains running independently are sixteen opinions. Something has to make them one history.

Do: save this as master.py and run it.

import hashlib

def block_hash(shard, height):
    return hashlib.sha256(f"{shard}:{height}".encode()).hexdigest()

shards = [f"{i:04b}" for i in range(16)]
tips = {s: block_hash(s, 900_000) for s in shards}

masterchain_block = hashlib.sha256("".join(tips[s] for s in shards).encode()).hexdigest()
print(f"shards being tracked : {len(shards)}")
print(f"masterchain block    : {masterchain_block[:32]}...")

tips["0110"] = block_hash("0110", 900_001)          # one shard produces a new block
rebuilt = hashlib.sha256("".join(tips[s] for s in shards).encode()).hexdigest()
print(f"after ONE shard moves: {rebuilt[:32]}...")
print("the masterchain block changed:", masterchain_block != rebuilt)

You should see: a single number standing for the state of all sixteen chains:

shards being tracked : 16
masterchain block    : bebd90e52bbadc0ef4be46fe5c85d3cb...
after ONE shard moves: 1246ba94ac8e69c5ccca1bab9faa1948...
the masterchain block changed: True

That is the masterchain’s job in one line of code: it records the latest block of every shard, so one hash pins the entire network’s state. It is also why finality on TON means “referenced by a masterchain block” rather than “my shard says so”, and why the masterchain deliberately stays small and expensive — every validator must follow it, whatever else they follow.

If not: if the last line prints False, the tips dictionary was rebuilt from scratch after the update, so the change was thrown away — only the one shard’s entry should be replaced.

Go: same folder, using what steps 2 to 4 produced.

Do: read the three results together and answer, for yourself, where an attacker would aim. Then confirm your reasoning by re-running crossing.py with depth values of 6 and 10 added to the list.

python3 crossing.py

You should see: the crossing rate climbing towards 100% and never coming back down. That is the finding: as TON scales, nearly all activity becomes cross-shard, so the security of the whole network rests on the message-passing machinery and on the masterchain that orders it — not on any single shard being honest.

Two practical consequences follow, and they are why this page exists. A validator set spread thin across many shards must be reshuffled unpredictably, or an attacker could aim at one small shard’s validators instead of the whole network. And as a user, “the transaction succeeded” on the sending side is not the same as “it arrived” — for anything that matters, confirm the destination account actually received it.

If not: if adding those depths makes no difference to the output, the for depth in (...) tuple was edited in a copy of the file rather than the one you are running — check with ls which file you saved.