Tracking TON Transactions: From Message to Trace

Alright — let’s break down how the hell you’re supposed to track a transaction in TON. If you’ve ever used Ethereum or Bitcoin, you might think: “Yeah, I just grab the hash of the transaction and I’m good.”
Well, surprise: TON doesn’t work that way. Not even close.

If you don’t clearly get what an account, transaction, message, trace, cell, or cell-hash is — or what the wallet actually signs — buckle up and read the glossary.

Glossary (quick refresher)▼

Account – Basic unit of information storage in the blockchain; a record in the workchain state containing metadata, balance, and possibly code and data.
Messages – Data packets exchanged between accounts (internal) or between accounts and entities outside the blockchain (external-in or external-out).
Transactions – Atomic changes to an account’s state. Typically (excluding system transactions), they're reactions to incoming messages. The exact validator processing time can't be predetermined, thus neither the timestamp nor hash can be known in advance.
(Transactions can shoot out internal messages, which go to other accounts, triggering more transactions, and so on – it’s like digital dominoes.)
Trace – It’s a tree. Nodes = transactions. Edges = messages. The root? Usually a response to an external-in.
Want examples? Go check tonviewer.com (opens in a new tab) – some are simple (opens in a new tab), others branch out beautifully (opens in a new tab), and some are just degenerate one-offs (opens in a new tab).
Example of trace in TON blockchain Cell – The atomic unit in TON. Up to 1023 bits and up to 4 refs to other cells. Everything lives in cells – accounts, messages, transactions, even blocks. And each cell has its own hash. That hash is how you track stuff.
Hash – Anytime you see "hash" here, it means the hash of the cell. Don't try to hash the raw bytes like a savage. It won’t work.

Simple Example

You send your buddy 5 TON using Tonkeeper.
Behind the scenes, your wallet puts together an instruction for your account contract, which then runs something like this:

Make sure the instruction isn't too old (check the TTL).
Check that the sequence number (seqno) is one higher than the last one.
Verify the signature against the public key stored in the account.
Take the draft of the outgoing internal message (the 5 TON transfer) from the external message body, fill in the actual sender info, and send it out.

This whole thing – the instruction and signature – goes into the body of the external-in message. But here’s the weird part: the message headers (like the recipient address) aren’t signed at all. They just specify which account should receive the message, and off it goes to the blockchain.

In decoded form, it looks something like this: Example decoded external message Once it lands, two transactions and two messages are recorded on-chain. The external-in message from the wallet triggers the sender’s transaction, which emits an internal message. That internal message reaches the recipient and triggers their transaction.

What Has a Unique ID and What Doesn’t?

Account – It’s globally unique. Workchain + 256-bit address. Easy.
Transaction – Unique per account and lt. So AccountID + lt = unique. And that’s in the body, so the hash is globally unique too.
Messages (internal + external-out) – Even in the same transaction, they'll have different lt. That plus source account = unique hash.
(Tiny exception: some weird old system messages might break this. Don’t worry about it unless you’re working at the protocol level.)
External-in – This one's a bit tricky. A single external-in message can end up creating multiple transactions – for example, if the wallet didn't set the +2 flag and the account doesn't have enough funds. In such cases, the message will keep being retried until the TTL expires or the account runs out of money. So by default, external-in messages are not globally unique.
BUT – if you’re using a standard wallet contract (like v3r1–v5r1) and sets the correct flags (which most popular wallets do), then the message body + sender address combination becomes unique. That means the message hash is globally unique and can be used as an ID right after signing – even before the blockchain sees it.
Trace – Usually tracked by the root transaction hash. Explorers like tonviewer.com (opens in a new tab) will let you find a trace from any globally unique message or transaction hash.

The TL;DR

Only one identifier exists before the validator touches anything: the hash of the external-in message.
But there are a few things you need to understand and account for:

The wallet contract that sends the transaction must behave correctly.
This only works for wallets that support seqno and ttl – older or non-standard contracts won't do.
Only the message body is signed – the rest (headers like destination) is not. So relayers or other middleware might change those parts before the message gets into the blockchain, changing the final hash. That’s why normalization is needed.
You can’t query a message by its hash using a light server – they don’t index that. You’ll need a full blockchain index (like tonapi.io, toncenter.com, or dton.io), or some duct-tape hacks.

How External-in Normalization Works

Because relayers can modify parts of a message before it hits the chain, we normalize the message to get a stable, predictable hash. Here's how it works:

Extract the original message from the cell.
Keep only two things: the destination address and the message body.
Repack the message with the body stored as a reference – this guarantees a consistent structure.
Store it in a new, empty cell and compute the hash.

TypeScript

function normalizeHash(message: Message): Buffer {
    if (message.info.type !== 'external-in') {
        return message.body.hash();
    }
 
    const cell = beginCell()
        .storeUint(2, 2)    // external-in
        .storeUint(0, 2)    // addr_none
        .storeAddress(message.info.dest)
        .storeUint(0, 4)    // import_fee = 0
        .storeBit(false)    // no StateInit
        .storeBit(true)     // store body as reference
        .storeRef(message.body)
        .endCell();
 
    return cell.hash();
}
 
// Original code: https://github.com/tonkeeper/tonapi-js/blob/4786b2e6bd42c8a3b116e6d234dde7c16cb8426b/examples/track-transaction.ts#L15

For a more detailed, step-by-step example of tracking a transaction using normalized hashes, check out the Cookbook.

If You’re Building a dApp

When the user sends a message through TonConnect, you receive a BOC (Bag of Cells) — an encoded copy of the sent message. Normalize it, calculate the hash, and boom – you can show an explorer link right away or track what happens next.

This BOC contains everything you need to get the exact same normalized hash, even before the message appears on-chain. See how to decode and handle BOC strings in the Cookbook.

If You’re Building Something Else

You should probably go read the full article: original here [ru] (opens in a new tab). It’s got all the gritty, boring details we skipped here.

TonAPI Embed Sign data