Smart Contracts und Mini Apps mit TON entwickeln

Seit dem 21. Januar 2025 erlauben die Telegram-Bedingungen für Bot-Entwickler einer Mini App Blockchain-Funktionen nur dann, wenn sie zum Erstellen und Verteilen von Vermögenswerten ausschließlich das NetzwerkTONnutzt und sich nur mit Wallets verbindet, die über TON Connect angebunden sind, so TelegramsBlockchain-Richtlinien. Eine Mini App ist eine Webanwendung, die sich ohne separate Installation direkt in Telegram öffnet und vom Messenger-Client die Daten des Nutzers erhält, der sie aufruft. Wer sie entwickelt, arbeitet gleichzeitig mit drei Systemen: der Weboberfläche in Telegram, einem eigenen Server und denSmart Contractsvon TON, die über Nachrichten statt über synchrone Aufrufe miteinander kommunizieren.

Diese Aufteilung bestimmt, wo was geprüft wird. Eine Zahlung in einer TON-Mini-App ist verlässlich, wenn der Server die Telegram-Sitzung validiert, diese Sitzung mit derWalletverknüpft, die signiert, und der Smart Contract nur Benachrichtigungen akzeptiert, die von seiner eigenen Jetton-Wallet stammen. Keine der drei Prüfungen ersetzt die anderen, und die dritte hat eine Besonderheit, die das Design des Smart Contracts verändert: Die Benachrichtigung über eine Jetton-Zahlung ist nicht bounceable, sodass ein Smart Contract, der sie ablehnt, die Token nicht zurückgibt. Das Beispiel eines Shops, der in einem Jetton kassiert, zeigt weiter unten die Folgen.

Was Telegram verlangt und mit welchen Tools im November 2026 entwickelt wird

Die Telegram-Richtlinien setzten zwei Fristen: den 1. Februar 2025 für die Einhaltung der Klauseln zur Wallet-Anbindung und den 21. Februar 2025 für die Migration von Mini Apps, die auf anderen Netzwerken liefen, zu TON. Seitdem ist es nicht erlaubt, aus einer Mini App heraus Token oder NFT anderer Netzwerke auszugeben oder zu verteilen, und andere Protokolle zur Wallet-Anbindung sind nur zulässig, um Vermögenswerte über eine Bridge zu TON zu bringen. Bots ohne Mini App fallen nicht unter diese Regeln. Eine zweite Vorgabe betrifft das Geschäftsmodell: Telegram verlangt, dassdigitale Waren und Dienstleistungenwegen der Bedingungen von App Store und Google Play ausschließlich in Telegram Stars bezahlt werden, während beim Verkauf physischer Waren oder Dienstleistungen andere Währungen und Anbieter zulässig sind. Eine Zahlung in TON oder in einem Jetton passt daher zum Verkauf physischer Waren, nicht zu digitalen Inhalten innerhalb der App.

Auch Sprache und Tools haben sich verändert. Die TON-Dokumentation stelltTolkals empfohlene Sprache für Smart Contracts vor, eine Weiterentwicklung von FunC, das nun zusammen mit Fift unter den Legacy-Sprachen geführt wird. IhrÄnderungsprotokollliegt in Version 1.5 vor, und der Compiler für JavaScript (@ton/tolk-js) veröffentlichte diese Version am 15. Oktober 2026. Zum Kompilieren, Testen und Deployen empfiehlt dieEntwicklerdokumentationActon (Version 1.2.1veröffentlichteam 5. Oktober 2026) und führt Blueprint als Legacy-Umgebung mit Support für bestehende Projekte weiter; die Web-IDE unter ide.ton.org wurde eingestellt. Die Versionen werden ab dem ersten Commit im Repository festgeschrieben, weil sich das Verhalten des Compilers von Version zu Version ändert: Version 1.2 etwa machte address zu einem Typ ausschließlich für interne Adressen und ergänzte Informationen zu zurückgeleiteten (bounced) Nachrichten.

Drei Identitäten, die der Server verknüpfen muss

Wenn ein Nutzer die Mini App öffnet, übergibt Telegram der Seite zwei Versionen seiner Daten. initDataUnsafe ist ein bereits geparstes Objekt, das dieMini-Apps-Dokumentationals nicht vertrauenswürdig einstuft; initData ist der ursprüngliche String, den der Server verifizieren kann. Die Verifizierung erfolgt per HMAC-SHA-256: Der geheime Schlüssel ist der HMAC des Bot-Tokens mit dem String „WebAppData“ als Schlüssel, und die mit diesem Schlüssel berechnete Signatur aller empfangenen Felder, alphabetisch sortiert im Format Schlüssel=Wert, muss mit dem Feld hash übereinstimmen. Über das Feld auth_date lassen sich zudem veraltete Sitzungen ablehnen. Ein Dritter, der das Bot-Token nicht kennt, kann seit der Bot API 8.0 vom November 2024 stattdessen die Ed25519-Signatur des Feldes signature mit dem öffentlichen Schlüssel prüfen, den Telegram veröffentlicht.

Diese Validierung belegt, wer der Telegram-Nutzer ist, nicht aber, welche Wallet er kontrolliert. Auch das Verbinden einer Wallet über TON Connect belegt das gegenüber dem Server nicht, denn dieser erhält vom Browser nur eine Adresse. Um beide Identitäten zu verknüpfen, bietet TON Connectton_proof: Der Server erzeugt für jeden Anmeldeversuch einen unvorhersehbaren Wert, und die Wallet signiert ihn zusammen mit der Domain der Anwendung und einem Zeitstempel. Der Server rekonstruiert die Nachricht, prüft, ob die Domain seine eigene ist, ob der Zeitstempel in einem kurzen Zeitfenster liegt (die Dokumentation schlägt bis zu zehn Minuten vor) und ob der Wert noch nicht verwendet wurde, und verifiziert die Signatur mit dem öffentlichen Schlüssel, den er aus dem walletStateInit der Wallet gewinnt. Erst nach beiden Prüfungen kann er festhalten, dass ein bestimmter Telegram-Nutzer mit einer bestimmten Wallet agiert.

Die dritte Identität ist die, die der Smart Contract sieht: die Adresse, von der jede Nachricht stammt. Der Smart Contract weiß nichts von Telegram oder von der Sitzung auf dem Server; er entscheidet anhand des Absenders, des beigefügten Werts und des Nachrichteninhalts. Deshalb muss die Kennung, die eine Zahlung einer Bestellung zuordnet, in der Nachricht selbst mitgeschickt werden, und deshalb hängt die Sicherheit einer Jetton-Zahlung davon ab, welchen Absender der Smart Contract akzeptiert.

Wie eine Jetton-Zahlung zum Smart Contract gelangt

Ein Jetton ist ein fungibler Token auf TON, definiert durch den Standard TEP-74, und funktioniert nicht wie ein ERC-20. Kein Smart Contract speichert alle Salden: Jeder Inhaber hat seine eigene Jetton-Wallet, einen Smart Contract mit seinem Saldo dieses Jettons, dessen Adresse der Master-Contract des Tokens aus der Adresse des Inhabers berechnen kann. Laut demLeitfaden für Jetton-Zahlungensendet der Käufer zum Bezahlen keine Nachricht an den Verkäufer, sondern an seine eigene Jetton-Wallet: einen transfer mit dem Betrag, dem Empfänger, einer Adresse für die Rückgabe des überschüssigen TON und zwei Feldern, auf die es hier ankommt, forward_ton_amount und forward_payload. Seine Jetton-Wallet zieht den Betrag vom Saldo ab und sendet einen internal_transfer an die Jetton-Wallet des Empfängers, die ihn gutschreibt.

Der Empfänger erfährt davon nur, wenn er eine dritte Nachricht erhält. DerStandard TEP-74legt fest, dass die Jetton-Wallet des Empfängers ihrem Eigentümer eine transfer_notification (Operationscode 0x7362d09c) mit dem Betrag, dem ursprünglichen Absender und dem forward_payload sendet, wenn forward_ton_amount größer als null ist, und dass diese Benachrichtigung nicht gesendet werden darf, wenn der Wert null ist. Das überschüssige TON geht in einer excesses-Nachricht an die angegebene Adresse zurück. In derReferenz-Jetton-Walletwird die Benachrichtigung zudem als nicht bounceable Nachricht gesendet, weil der Empfänger ein Konto ohne deployten Smart Contract sein könnte: Schlägt die Verarbeitung im empfangenden Smart Contract fehl, geht nichts an die Jetton-Wallet zurück, und die Token bleiben im Saldo des Empfängers.

Hypothetisches Beispiel: ein Telegram-Shop, der in einem Jetton kassiert

Als hypothetisches Beispiel dient eine Modemarke, die einen Shop als Mini App eröffnet und ihre Bestellungen, also physische Kleidungsstücke, in einem Dollar-Jetton abrechnet. Der Server validiert initData in jeder Sitzung, verknüpft die Wallet jedes Kunden per ton_proof und legt eine Bestellung mit einer Kennung an. Beim Bezahlen fordert die Mini App die Wallet des Kunden über TON Connect auf, einen transfer an seine eigene Jetton-Wallet zu signieren, mit dem Smart Contract des Shops als Empfänger, der Bestellkennung im forward_payload und einem TON-Betrag in forward_ton_amount, damit die Benachrichtigung ankommt. Der Smart Contract des Shops empfängt die transfer_notification, liest die Kennung und markiert die Bestellung als bezahlt; der Server verfolgt diese Nachrichten, um den Versand vorzubereiten.

Die erste Version des Smart Contracts akzeptiert jede transfer_notification mit gültiger Kennung. Jeder kann eine Nachricht mit diesem Operationscode senden, und der Zahlungsleitfaden warnt, dass jeder gefälschte Jetton-Wallets mit beliebigen Salden deployen kann: Ein Angreifer, der eine Wallet deployt, die den Dollar-Jetton imitiert, kann dem Shop eine Zahlung melden, die nie stattgefunden hat, und sich das Kleidungsstück liefern lassen. Die Korrektur besteht darin, den Absender jeder Benachrichtigung mit der Jetton-Wallet abzugleichen, die dem Smart Contract des Shops beim Master des akzeptierten Jettons zugeordnet ist. Diese Adresse ist beim Deployment nicht bekannt, weil sie von der Adresse des Smart Contracts selbst abhängt. DieDokumentation zur On-Chain-Verarbeitung von Jettonsschlägt drei Wege vor: sie beim Master mit der Nachricht ProvideWalletAddress aus dem Standard TEP-89 anzufragen und die Antwort zu speichern, sie nach einer Berechnung off-chain per Admin-Nachricht festzulegen oder sie im Smart Contract zu berechnen, indem die Methode get_wallet_address des Masters mit der Instruktion RUNVM emuliert wird.

Der zweite Fehler zeigt sich in der Oberfläche. Baut die Mini App den transfer mit forward_ton_amount gleich null, wechselt der Jetton den Besitzer, doch der Smart Contract erhält keine Benachrichtigung: Der Kunde sieht die Zahlung in seiner Wallet als abgeschlossen, während die Bestellung offen bleibt. Der Zahlungsleitfaden fordert Dienste auf, ein forward_ton_amount größer als null zu setzen, und der Server braucht zusätzlich einen Abgleich für Zahlungen, die ohne Benachrichtigung eingehen, etwa solche, die der Kunde außerhalb der Mini App direkt aus seiner Wallet sendet. Dazu liest er die Transaktionen der Jetton-Wallet des Shops aus.

Der dritte ergibt sich aus dem Lagerbestand. Ist ein Kleidungsstück zwischen Anlage der Bestellung und Zahlung ausverkauft, liegt es nahe, dass der Smart Contract die Benachrichtigung ablehnt. Da die Benachrichtigung nicht bounceable ist, gibt diese Ablehnung nichts zurück: Die Token liegen bereits in der Jetton-Wallet des Shops, und die Zahlung bleibt unverbucht. Der Smart Contract muss eine echte Benachrichtigung daher immer annehmen, die Zahlung verbuchen, auch wenn er die Bestellung nicht erfüllen kann, und eine Rückerstattung anbieten. Dazu sendet er an seine Jetton-Wallet einen transfer zurück an den ursprünglichen Käufer, dessen Adresse in der Benachrichtigung selbst enthalten ist. Dasselbe gilt für eine unbekannte oder doppelte Bestellkennung: Die Zahlung wird verbucht und erstattet, nicht abgelehnt.

Was vor dem Deployment im Mainnet getestet wird

Die Tests eines solchen Projekts umfassen den Smart Contract, der mit dem Test-Runner von Acton geprüft wird (in einem Legacy-Projekt mit der Blueprint-Sandbox), und den gesamten Ablauf im TON-Testnet. Aus dem Beispiel ergeben sich diese Mindestprüfungen:

• Eine Benachrichtigung von einer gefälschten Jetton-Wallet, die der Smart Contract ignoriert, ohne den Status einer Bestellung zu ändern.
• Eine Zahlung mit forward_ton_amount gleich null, die der Server über den Abgleich erkennt.
• Eine Zahlung für eine ausverkaufte Bestellung, eine mit unbekannter und eine mit doppelter Kennung, jeweils mit Rückerstattung.
• Eine Sitzung mit manipuliertem initData oder veraltetem auth_date sowie ein ton_proof mit wiederverwendetem Wert oder fremder Domain.
• Eine Zahlung, die der Kunde signiert und vor der Bestätigung abbricht, um zu prüfen, was er beim erneuten Öffnen der Mini App sieht.

Zu jedem Test ist das erwartete Ergebnis festgehalten, und die Testreihe wird wiederholt, wenn sich die Version von Tolk oder Acton ändert und wenn der Shop einen neuen Jetton akzeptiert, weil die Jetton-Wallet, die der Smart Contract erkennen muss, für jeden Master eine andere ist.

In einer TON-Mini-App sorgt Telegram für die Distribution, die verlässliche Zahlung hängt von Smart Contract und Server ab

Die Integration mit Telegram bietet etwas, das ein anderes Netzwerk innerhalb dieser App nicht bieten kann: Der Nutzer öffnet den Shop aus einem Chat, identifiziert sich ohne Registrierung und verbindet eine Wallet, ohne Telegram zu verlassen. Dieser Vorteil ist an zwei Voraussetzungen geknüpft. Er hängt von den Nutzungsbedingungen von Telegram ab, die 2025 den Mini Apps anderer Netzwerke einen Monat für die Migration zu TON ließen und sich erneut ändern können; das Projekt geht also eine Plattformabhängigkeit ein, vergleichbar mit der einer mobilen App von ihrem App Store. Und eine App in Telegram anzubieten garantiert keine Nutzer: Die Distribution bleibt Aufgabe des Produkts.

Technisch zwingt TON dazu, jede Zahlung als Folge von Nachrichten zwischen getrennt ausgeführten Smart Contracts zu denken. Ein Team, das von EVM kommt, wo eine Überweisung und ihre Wirkung in derselben Transaktion stattfinden, muss diese Umstellung verinnerlichen, bevor es die erste Zeile schreibt. Das Beispiel zeigt es: Die drei Fehler liegen nicht in der Syntax von Tolk, sondern im Modell, denn sie bestehen darin, einen Absender ungeprüft zu akzeptieren, zu vergessen, dass die Benachrichtigung optional ist, und anzunehmen, dass eine Ablehnung die Mittel zurückgibt. Der Steckbrief zuTONfasst das Netzwerk und seine Standards zusammen, derLeitfaden zu Entwicklungsunternehmen für TONvergleicht Anbieter, und bei Metlabs entwickeln wirSmart Contractsund Mini Apps, die diesen gesamten Ablauf abdecken, vom Smart Contract bis zum Server.