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.

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:

1. The wallet contract that sends the transaction must behave correctly.
2. This only works for wallets that support seqno and ttl – older or non-standard contracts won't do.
3. 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.
4. 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).

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:

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

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.

Library Usage Examples

package main
 
import (
  "fmt"
  "github.com/tonkeeper/tongo/boc"
  "github.com/tonkeeper/tongo/tlb"
  "os"
)
 
func main() {
  var bocString = "te6cckECBgEAAPYAAeWIAW7m9GMNMJnjJLq86chyLJWpEZh3KHlgHyzaMJzYP4z8A5tLO3P////rPqB8UAAA..."
  cell, err := boc.DeserializeSinglRootBase64(bocString)
 
  if err != nil {
    os.Exit(1)
  }
 
  var msg tlb.Message
  err = tlb.Unmarshal(cell, &msg)
  if err != nil {
    os.Exit(1)
  }
 
  hash := msg.Hash(true)
  fmt.Println( hash.Hex())
}

Tracking a Transaction by Normalized Hash

A normalized hash can be resolved only by full blockchain indexers (such as tonapi, toncenter, or dton). Lite servers and archive nodes do not understand it.

Key REST Endpoints

These are the main endpoints that accept a normalized message hash and allow you to determine whether the operation was accepted on-chain, as well as retrieve related data such as the transaction, execution trace, or event.

For the purposes of this guide we will focus on getTrace, because it captures the status of the entire transaction chain and therefore lets us determine whether the operation succeeded.

Polling Strategy

Polling interval: 1s → 2s → 4s → 8s → … (exponential backoff)

1. If the external message includes an expire_time field — use it as a hard cutoff. Once the current time exceeds expire_time, the message will never be accepted by the network. Stop polling and mark the attempt as failed.
2. If the message has no expire_time, use a custom upper limit (e.g. 60–120 seconds) depending on your UX needs.

Trace Lifecycle States

Tip: cache {trace_id, expiresAt} locally. If the trace is still Not found or Pending after expiresAt, mark the operation as failed and prompt the user to retry.

Example of isFinalized function

A trace is finalized when:

• it is not emulated
• it contains no outgoing internal messages
• all child traces are finalized as well

function isFinalized(trace): Boolean {
    if (trace.emulated) {
        return false;
    }
    for (const msg of trace.out_msgs) {
        if (msg.msg_type === "int_msg") {
            return false;
        }
    }
    for (const child of trace.children) {
        if (!isFinalized(child)) {
            return false;
        }
    }
    return true;
}

Minimal Integration Flow

1. After signing — compute the normalized hash from the BOC the wallet returns.
2. Start polling traces/{hash} with the back‑off scheme above.
3. When “pending” appears — present the explorer link or custom “Pending” badge.
4. When finalized — parse the trace:
   • All transactions success → show confirmation.
   • Any error → show failure reason (bounce, low balance, etc.).
5. Stop once success or definitive failure is recorded.

This keeps the user informed from the moment a message leaves the wallet until the entire domino chain of transactions is settled on‑chain.

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.