Basic notifications (smart contract - user)

This specification is designed to make it easier to notify users of any events on the part of TON smart contracts. I have prepared message structures and recommendations for various services. This specification will be useful for wallets, blockchain explorers and other services that display messages from the blockchain to the user.

Spec

It is supposed that the smart contract to notify the user, can send an internal message to the smart contract of the user's wallet. The message must be formed according to a specific structure (see TL-B sheme below).

// -------- FROM block.tlb --------
nothing$0 {X:Type} = Maybe X;
just$1 {X:Type} value:X = Maybe X;

left$0 {X:Type} {Y:Type} value:X = Either X Y;
right$1 {X:Type} {Y:Type} value:Y = Either X Y;
// --------------------------------

// ----- notification TL-B scheme -----
just#_ {n:#} text:bits next:^(ContinueComment ~n) = ContinueComment ~(n + 1);
cons#_ len:(## 8) text:(bits (len * 8)) 
    next:(Maybe ^ContinueComment) = StartComment;

rop:uint32 data:Any = MsgBody;

notification#3f5476ca comment:StartComment
    real_body:(Either MsgBody ^MsgBody) = Request;
// ------------------------------------

comment and real_body are mandatory. We must tell the user in English text(utf-8 encoding) about an event in comment, and also have the ability to pass additional information to real_body, which can be read by a third-party service. If you don't have specific information for real_body you must specify rop in it, but you don't have to attach data.

rop correspond to the purpose of op from the "Smart contract guidelines"

These notifications may carry 0 or more TON coins with them.

If you are a developer of a wallet or any other service that displays TON
blockchain messages to users and decide to follow this specification, you must:

Identify the message as an incoming notification
Correctly read the message according to the TL-B sheme
Display data from comment to the user in utf-8
Display at least rop from real_body
If possible, read data from real_body

Additional information

Notification op code (notification#0x3f5476ca) calculated with:

import binascii

result = hex(binascii.crc32(bytes("notification", "utf-8")) & 0x7fffffff)
print(result)  # 0x3f5476ca

The use of & 0x7fffffff conditioned by paragraph 5 "Internal messages"
of the "Smart contract guidelines" section of the documentation

Fighting spam

As you may have already guessed, these notifications can be used to send spam.
To avoid this, I offer a few recommendations for services/wallets:

Use a trusted registry of smart contracts that will not send spam.
For example you can check a smart contract by its hash of source code.
You can give the user the option of automatically grouping the notification
or adding the address/(smart contract by its source code hash) to a blacklist.

ton-blockchain / TIPs