diamond Mini-Apps

Integrating Telegram Mini-Apps: Decentralized Wallet Binding, BOC Payload Signing & Replay Protection

verified_user TGWAY Web3 Research Staff • calendar_today Published Sep 11, 2026 • visibility 1,860 Views

[TonConnect 2.0 WebApp Handshake & Session Cryptography] Integrating Telegram Mini-Apps: Decentralized Wallet Binding, BOC Payload Signing & Replay Protection

Telegram Mini-Apps (TMAs) have established themselves as the premier frontend environment for Web3 consumer applications, enabling hundreds of millions of users to interact with decentralized finance, gaming, and social protocols without leaving their messaging client. However, bridging sandboxed web views with external non-custodial crypto wallets requires a trustless, cryptographically hardened communication channel. TonConnect 2.0 satisfies this requirement by providing an end-to-end encrypted session standard operating over Curve25519 ECDH key exchanges and AES-CBC symmetric ciphers. DApps authenticate via strict cryptographic manifests, negotiate bridge sessions over HTTP Server-Sent Events (SSE), and dispatch serialized Bag of Cells (BOC) transaction requests with microsecond precision. This technical guide examines TonConnect 2.0 session handshakes, manifest verification standards, BOC payload signing, and anti-replay protection.

1 verified

Manifest Verification

Wallets validate domain origin via an immutable tonconnect-manifest.json hosted on the DApp's root domain, defeating phishing spoofing.

2 vpn_key

Curve25519 E2EE Bridge

All communication between the Mini-App and the wallet daemon is encrypted with shared secrets derived via ephemeral elliptic-curve Diffie-Hellman.

3 lock_clock

Replay Protection Nonce

Transaction payloads incorporate monotonic sequence numbers (subwallet_id / seqno) and valid-until expiration epochs.

4 security

Zero Key Exposure

Private seed phrases never enter WebApp memory; signing executes exclusively inside the secure enclave of the external wallet app.

1. Implementation Workflow: Integrating TonConnect 2.0 into Telegram Mini-Apps

Deploy the Cryptographic Manifest Specification

Create and host tonconnect-manifest.json at the root of your HTTPS domain. Specify your application name, icon URL, and legal privacy URLs. Non-custodial wallets fetch and verify this file prior to showing the authentication approval modal.

Initialize TonConnect UI Client SDK

Import @tonconnect/ui into your React or TypeScript frontend. Initialize the TonConnectUI instance passing your verified manifest URL. The SDK handles bridge polling, deep linking, and wallet selection modals automatically.

Assemble and Serialize the BOC Payload

When initiating smart contract interactions, construct the transaction message cell with opcodes, target addresses, and forward amounts. Serialize the structure into a base64-encoded Bag of Cells (BOC) and dispatch via tonConnectUI.sendTransaction().

Verify On-Chain Transaction Hash

The wallet signs the BOC and returns a signed BOC string containing the external message. Query a TON API indexer (e.g. TonCenter or TonAPI) using the message hash to confirm blockchain finality before fulfilling DApp digital goods.

2. Interactive Simulator: TonConnect 2.0 Handshake & BOC Signing Engine

account_balance_wallet

TonConnect 2.0 Protocol Handshake Console

Curve25519 E2EE Bridge & BOC Serialization Engine

WALLET DISCONNECTED

SELECT TARGET WALLET

TRANSACTION OPERATION

BRIDGE SESSION PAYLOAD INSPECTOR E2EE Bridge: Idle

        {

          "validUntil": 1789064120,

          "messages": [{ "address": "EQB_k9...942", "amount": "5000000000", "payload": "te6cckEBAQEAKgAAU... [BOC Base64]" }]

        }

        [System] TonConnect 2.0 SDK ready. Awaiting manifest verification handshake.
      

Session Encryption

None

Manifest Status

Unchecked

Replay Nonce

Signed Hash

None

3. Technical Comparison: TonConnect 2.0 vs. WalletConnect v2 vs. Injected Providers

Protocol Attribute	TonConnect 2.0	WalletConnect v2 (EVM)
Telegram Sandbox Optimization	Native deep-linking within Telegram TMA web view container	Prone to pop-up blocking and broken modal redirects inside iframes
Cryptographic Payload Format	Bag of Cells (BOC) serialized binary trees with TVM opcodes	JSON-RPC 2.0 hexadecimal encoded ABI calls
Session Relay Bridge	Lightweight HTTP SSE bridge with client-side key derivation	Centralized Relay servers with project ID cloud rate limits
Phishing Defense	Mandatory strict manifest domain matching required for connection	Optional metadata validation without strict DNS-bound manifests

4. Architectural Overview: E2EE Handshake & Payload Dispatch

TonConnect 2.0 WebApp Architecture Infographic

Figure 9: Cryptographic sequence diagram showing Curve25519 session derivation and serialized BOC message signing.

5. Frequently Asked Questions (FAQ)

Can a Telegram Mini-App execute transactions silently without user approval?

Never. TonConnect 2.0 enforces non-custodial boundaries. The Mini-App can only dispatch unsigned BOC proposals. The user's external wallet app intercepts the request, displays exact parameters and gas costs, and requires biometric or passcode authorization.

What happens if the tonconnect-manifest.json file is unreachable?

If the manifest returns an HTTP 404, invalid SSL certificate, or unparseable JSON, TonConnect compliant wallets immediately reject the connection attempt and show an unverified DApp warning to protect the user from malicious spoofs.

Does TonConnect support multiple concurrent transaction messages?

Yes. TonConnect 2.0 supports bundling up to 4 distinct messages inside a single transaction envelope, allowing multi-action operations such as approving a Jetton allowance and executing a swap in one atomic signature.