feat(foundations): normalized hash

docs.json

@@ -663,6 +663,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

@@ -16,26 +16,19 @@ The process of seeking a transaction associated with an `external-in` message is
 
 ### Message normalization
 
-Normalization is a standardization process that converts different external-in message representations into a consistent format. This needs to be done because the structure of external-in messages allows the same message to be constructed in different forms, which results in different possible hashes for the same external message.
+Message lookup uses normalized hash because different serializers can produce different raw hashes for external-in messages. To avoid mismatches, clients and providers calculate a canonical lookup key defined by [TEP-467](https://github.com/ton-blockchain/TEPs/blob/master/text/0467-normalized-message-hash.md). Most TON [RPC providers](/ecosystem/api/overview) support lookup by this key.
 
-To address this, the ecosystem defines a standard that ensures consistent hash calculation. The normalization rules are specified in detail in the [TEP-467 proposal](https://github.com/ton-blockchain/TEPs/pull/467). Message lookup by its normalized hash is already implemented in most TON [RPC providers](/ecosystem/api/overview).
-
-**How normalization works:**
-
-The normalized hash is computed by applying the following standardization rules to an external-in message:
-
-1. **Source Address (`src`)**: set to `addr_none$00`
-1. **Import Fee (`import_fee`)**: set to `0`
-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
 /**
  * Generates a normalized hash of an "external-in" message for comparison.
  *
- * This function ensures consistent hashing of external-in messages by following [TEP-467](https://github.com/ton-blockchain/TEPs/blob/8b3beda2d8611c90ec02a18bec946f5e33a80091/text/0467-normalized-message-hash.md):
+ * This function ensures consistent hashing of external-in messages by following [TEP-467](https://github.com/ton-blockchain/TEPs/blob/master/text/0467-normalized-message-hash.md):
  *
  * @param {Message} message - The message to be normalized and hashed. Must be of type `"external-in"`.
  * @returns {Buffer} The hash of the normalized message.
@@ -264,6 +257,6 @@ if (tx) {
 
 ## See also
 
-- [TEP-467: Normalized Message Hash](https://github.com/ton-blockchain/TEPs/blob/8b3beda2d8611c90ec02a18bec946f5e33a80091/text/0467-normalized-message-hash.md)
+- [TEP-467: Normalized Message Hash](https://github.com/ton-blockchain/TEPs/blob/master/text/0467-normalized-message-hash.md)
 - [Messages and transactions](/foundations/messages/ordinary-tx)
 - [TON Connect: Sending messages](/ecosystem/ton-connect/overview)

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 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,90 @@
+---
+title: "Normalized message hash"
+sidebarTitle: "Normalized hash"
+---
+
+import { Aside } from "/snippets/aside.jsx";
+
+The normalized message hash is a canonical identifier used to look up [external-in](/foundations/messages/external-in) messages across APIs and SDKs. It is computed from a standardized external-in representation so different serializers produce the same lookup key.
+
+<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, clients and providers can serialize external-in messages with structural differences that lead to different raw hashes for the same lookup intent. This affects fields and layout choices used in hashing, such as `src`, `import_fee`, `init`, and whether the body is embedded or referenced.
+
+Providers usually do not rewrite message content. The mismatch appears because systems may hash slightly different structural representations. For example, `init` is meaningful in message semantics, but normalization sets it to `nothing$0` when building a canonical lookup form.
+
+Apply normalization rules only to compute a lookup key. This process builds a canonical external-in representation for hashing and does not mutate an already sent message.
+
+## 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`.
+1. **Import Fee (`import_fee`)**: Set to `0`.
+1. **InitState (`init`)**: Set to `nothing$0`.
+1. **Body (`body:(Either X ^X)`)**: Always store as a reference (`^X`). The content of the body itself is included without modification.
+
+After constructing the canonical external-in message cell, compute its standard [cell hash](/foundations/serialization/cells).
+
+### Low-level construction example
+
+The following TypeScript example builds the canonical external-in cell used for normalized hash calculation. 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 buildNormalizedExtInMessage(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 = buildNormalizedExtInMessage(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.
+
+### What to use for global uniqueness
+
+Use normalized hash as a lookup correlation key before confirmation. After a transaction is found, use the transaction identifier for global uniqueness, such as account address + transaction LT (or transaction hash, when available in your integration).
+
+<Aside type="tip">
+  Read more about external message tracking from the TonAPI side in [TonAPI docs](https://docs.tonconsole.com/academy/transaction-tracking).
+</Aside>