Integrating TON blockchain into Trust Wallet: a case study

Source: Dev.to

The Journey

• Month 1: TON went live in a wallet with 130 million users.

• Grant: I saw that the TON Foundation was offering development grants, applied, and they contacted me almost immediately.

• Collaboration: I messaged a friend who works at Trust Wallet. Together we created a group chat with:

  1. Wallet Core developers
  2. The TON team
  3. My engineer friend
  4. Me

• Complication: Trust Wallet consists of two parts:

  1. Wallet Core – open‑source library that handles key generation, address validation, transaction signing, etc.
  2. App layer – closed‑source code that fetches balances, broadcasts transactions, and interacts with the UI.

  Only the internal Trust Wallet team can modify the app layer, which means management approval, allocated engineering time, and accountability.

• Foundation concerns: “What if Trust Wallet never adds it to the app? Why fund the grant?”

• Resolution: Both teams met in the middle.

  • TON approved the grant.
  • Trust Wallet committed to prioritising the integration.

  Result: a new blockchain for Trust Wallet users and a new wallet for TON users – a win‑win.

• Development: My friend did most of the coding; I reviewed and refined. The PR was merged in about a month.

Trust Wallet Platforms

At its core is Wallet Core, an open‑source C++/Rust library supporting 130+ blockchains. It’s used not only by Trust Wallet but also by other major wallets (e.g., Crypto.com). The library handles:

• Private‑key generation
• Address creation & validation
• Transaction signing
• Smart‑contract interactions

This is where we added TON.

Background on TON

• Original project: Launched by Pavel Durov; development was partially handled by TON Labs.
• Sanctions: After US sanctions, Durov stepped away, but TON Labs continued with a fork called Free TON, later renamed Everscale.
• Current state: A new TON Foundation (endorsed by Durov) revived the project, integrated it into Telegram, and it has taken off.

TON Labs contributed a lot of impressive technical work. Everscale was already present in Wallet Core; we extracted the shared code into a module called CommonTON, which now powers both Everscale and TON.

Wallet Model Differences

In TON a wallet is not just an address – it’s a full‑fledged smart contract. To create a transaction you send an external message to the wallet contract, which then forwards an internal message to the recipient.

External Message (user → wallet contract)
├─ header: sender’s contract address
├─ stateInit: code & data (only on first transaction)
└─ body
   ├─ signature: Ed25519 signature
   └─ signing_message
      ├─ wallet_id, expire_at, seqno
      └─ Internal Message (to recipient)
         ├─ header: "send Y nanotons to address Z"
         └─ body: transfer comment

Technical Details

Cell Structure (Bag‑of‑Cells)

All TON data is a tree of cells (max 1023 bits + up to 4 references). Below is the code we added for creating a V4R2 wallet data cell (C++‑style, compiled into Wallet Core).

// Create the data cell for a V4R2 wallet
Cell::Ref WalletV4R2::createDataCell() const {
    CellBuilder builder;

    builder.appendU32(0);                         // sequence_number
    builder.appendU32(walletId);                  // wallet_id
    builder.appendRaw(publicKey.bytes, 256);       // public key (256 bits)
    builder.appendBitZero();                      // "no plugins" flag

    // Total: 321 bits → fits into a single cell
    return builder.intoCell();
}

To build a transaction we assemble cells for:

• Recipient address
• Amount
• Optional comment

All are packed into a BOC (Bag‑of‑Cells) serializer that already existed in Wallet Core.

Address Formats

The TON format is a Base64 string that embeds address‑type information and a checksum to catch typos.

Seed‑Phrase & Key Derivation

• BIP‑39 defines:

  seed = hash(mnemonic + salt)

• Standard salt: "mnemonic" + password

• TON salt: "TON default seed"

Because the salt differs, the same mnemonic produces different private keys in Tonkeeper vs. Trust Wallet. Consequently, wallets are not interchangeable. The same issue appears in Waves, Qtum, and Polkadot (sr25519).

TON’s checksum in the address also warns users immediately if a seed‑phrase typo leads to an invalid address.

Contributions Beyond Code

• Provided Trust Wallet’s team with code examples for:
  • Fetching transaction data
  • Querying wallet state
• Consulted on app‑integration questions related to TON.
• Added blockchain metadata and the TON logo to the assets repository.

Outcomes

After the initial integration, I later added Jetton support (TON tokens) and moved on to other projects for TON and NEAR.

Occasionally I share notes on development and more on Twitter.

Acknowledgements

A huge thank‑you to everyone who contributed:

• Tao Xu
• Roman Sztergbaum
• optout
• Sergei (Trust Wallet team) – organization and code review
• Kirill (TON Foundation) – helped manage everything
• Narek – technical support from TON
• Vyacheslav – implemented the main integration
• Vladimir (Trust Wallet) – made it possible and performed code review
• And to everyone else who contributed to this project