Normalized message hash

The normalized message hash is a consistent and reliable identifier for external-in messages. It remains constant regardless of variations in the src, import_fee, and init fields, which can change without affecting the validity of the message. This hash is particularly useful for tracking transactions.

For the canonical specification, refer to TEP-467: Normalized Message Hash.

Why normalization is needed

In TON, an external-in message can be constructed and packed in different ways that are all logically identical. Fields such as the source address (src), the import_fee, and the state initialization (init) can vary depending on the sender’s implementation or the API provider processing the message.

Because these non-essential fields are included when computing the standard cell hash, functionally identical messages can produce different message hashes. This variability complicates reliable transaction tracking and deduplication, as highlighted in the TON Console transaction tracking guide.

By applying normalization rules before calculating the hash, the variable fields are removed or zeroed out, ensuring that the same logical message always produces the exact same hash.

Calculate the normalized hash

The normalized hash is computed by standardizing the ext_in_msg_info$10 fields before serializing the message. This approach is independent of any specific SDK and can be implemented in any language.

According to TEP-467, apply the following rules:

1. Source Address (src): Set to addr_none$00.
2. Import Fee (import_fee): Set to 0.
3. InitState (init): Set to nothing$0.
4. Body (body:(Either X ^X)): Always store as a reference (^X). The content of the body itself is included without modification.

After constructing the cell with these standardized values, calculate its standard cell hash (the SHA-256 of the root cell).

Low-level construction example

The following TypeScript example demonstrates the raw cell construction. This logic illustrates the underlying TL-B serialization and can be adapted to any programming language or SDK.

import { beginCell, Cell, Address } from "@ton/core";

function normalizeExternalMessage(destAddress: Address, bodyCell: Cell): Cell {
  return beginCell()
    .storeUint(0b10, 2)         // external-in message prefix
    .storeUint(0b00, 2)         // src: addr_none$00
    .storeAddress(destAddress)  // dest: MsgAddressInt
    .storeCoins(0)              // import_fee: 0
    .storeBit(false)            // init: nothing$0
    .storeBit(true)             // body: stored as a reference (^X)
    .storeRef(bodyCell)         // The actual body cell
    .endCell();
}

// Compute the standard cell hash
const normalizedExtMessage = normalizeExternalMessage(destAddress, bodyCell);
const normalizedHash = normalizedExtMessage.hash().toString("hex");

Tools and SDK support

Many tools and libraries in the TON ecosystem support the normalized message hash either natively or through API integration.

Tool	Support	Details
ton/ton (@ton/ton)	Yes	Use storeMessage(..., { forceRef: true }) and custom logic to clear fields. See Message lookup for an example.
TonCenter	Yes	API methods such as sendBocReturnHash return the normalized hash; transaction lookups support it.
TonAPI	Yes	Transaction tracking and API lookups natively use the normalized hash.
ton-blockchain/ton	Yes	Supported at the node level (ton-blockchain/ton#1557).

For a practical guide on searching for transactions using TON Connect and the normalized hash, see the Message lookup guide.

Uniqueness constraints

The normalized message hash is not a globally unique identifier across the entire blockchain. It is possible for custom smart contracts to process identical external messages that produce the same normalized hash, resulting in multiple distinct transaction chains.

However, the normalized message hash serves as a unique identifier for a specific transaction trace when the following conditions are met:

• The message is sent to a wallet contract.
• The message includes an instruction to send an internal message with the IGNORE_ERRORS=+2 flag (this is standard behavior for TON Connect and for wallets starting from v5).
• The wallet contract is never deleted.

For dApps interacting with user wallets via TON Connect, or for exchanges controlling their outbound external messages, it is safe to reference traces using the normalized hash. This applies even before the transactions are finalized.