feat(foundations): normalized hash

docs.json

@@ -592,6 +592,7 @@
               "foundations/messages/overview",
               "foundations/messages/internal",
               "foundations/messages/external-in",
+              "foundations/messages/normalized-hash",
               "foundations/messages/external-out",
               "foundations/messages/deploy",
               "foundations/messages/modes",

ecosystem/ton-connect/message-lookup.mdx

@@ -29,6 +29,10 @@ The normalized hash is computed by applying the following standardization rules
 1. **InitState (`init`)**: set to an empty value
 1. **Body**: always stored as a reference
 
+<Aside type="tip">
+  For more details on the standardization process, language-agnostic implementations, and uniqueness constraints, see the [Normalized message hash](/foundations/messages/normalized-hash) documentation.
+</Aside>
+
 ## Transaction lookup using external message from TON Connect
 
 ```ts

foundations/messages/external-in.mdx

@@ -42,3 +42,5 @@ Incoming external messages are sent to the contract from outside the blockchain,
 ## Multiple delivery
 
 When an incoming external message is sent to the blockchain, validators share them with each other, and might accidentally (or intentionally) deliver it several times. As it's usually preferred to process a unique incoming external message only once, some measures need to be taken to ensure duplicate messages are not accepted. Some of these techniques can be found in [wallet](/standard/wallets/comparison) contracts.
+
+For reliable off-chain transaction tracking, the ecosystem relies on the [normalized message hash](/foundations/messages/normalized-hash) standard.

foundations/messages/normalized-hash.mdx

@@ -0,0 +1,87 @@
+---
+title: "Normalized message hash"
+sidebarTitle: "Normalized hash"
+---
+
+import { Aside } from "/snippets/aside.jsx";
+
+The normalized message hash is a consistent and reliable identifier for [external-in](/foundations/messages/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.
+
+<Aside type="note">
+  For the canonical specification, refer to [TEP-467: Normalized Message Hash](https://github.com/ton-blockchain/TEPs/blob/master/text/0467-normalized-message-hash.md).
+</Aside>
+
+## 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](https://docs.tonconsole.com/academy/transaction-tracking).
+
+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](/foundations/serialization/cells) (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.
+
+```typescript
+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](/ecosystem/ton-connect/message-lookup) for an example. |
+| **TonCenter** | Yes | API methods such as `sendBocReturnHash` return the normalized hash; transaction lookups support it. |
+| **TonAPI** | Yes | [Transaction tracking](https://docs.tonconsole.com/tonapi/cookbook/transaction-tracking) and API lookups natively use the normalized hash. |
+| **ton-blockchain/ton** | Yes | Supported at the node level ([ton-blockchain/ton#1557](https://github.com/ton-blockchain/ton/pull/1557)). |
+
+<Aside type="tip">
+  For a practical guide on searching for transactions using TON Connect and the normalized hash, see the [Message lookup](/ecosystem/ton-connect/message-lookup) guide.
+</Aside>
+
+## 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](/standard/wallets/comparison).
+- The message includes an instruction to send an internal message with the `IGNORE_ERRORS=+2` flag (this is standard behavior for [TON Connect](/ecosystem/ton-connect/overview) and for wallets starting from v5).
+- The wallet contract is never deleted.
+
+<Aside type="note">
+  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.
+</Aside>
+