diff --git a/docs.json b/docs.json index d18fb48fc..54f540a40 100644 --- a/docs.json +++ b/docs.json @@ -651,6 +651,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", diff --git a/ecosystem/ton-connect/message-lookup.mdx b/ecosystem/ton-connect/message-lookup.mdx index 05849ac9d..2a6a22ffb 100644 --- a/ecosystem/ton-connect/message-lookup.mdx +++ b/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 + + ## Transaction lookup using external message from TON Connect ```ts diff --git a/foundations/messages/external-in.mdx b/foundations/messages/external-in.mdx index cf96c61f0..f3a3149a2 100644 --- a/foundations/messages/external-in.mdx +++ b/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. diff --git a/foundations/messages/normalized-hash.mdx b/foundations/messages/normalized-hash.mdx new file mode 100644 index 000000000..0aec046a8 --- /dev/null +++ b/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. + + + +## 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)). | + + + +## 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. + + +