Vadim Volodin

Posted on Jan 15

Integrating TON blockchain into Trust Wallet: a case study

#blockchain #opensource #software #cryptocurrency

I had TON cryptocurrency. I had Trust Wallet. But I couldn't use them together — TON simply wasn't supported.

I could have waited. Instead, I decided to build it myself.

A month later, TON was live in a wallet with 130 million users.

The Grant That Almost Fell Through

I noticed that TON Foundation was offering development grants. I applied. Almost immediately, they reached out — we hopped on a call and talked it through.

At the same time, I messaged a friend who worked at Trust Wallet. Together, we set up a group chat: Wallet Core developers, the TON team, my engineer friend, and me.

Then things got complicated.

Trust Wallet has two parts. Wallet Core is open-source and handles transaction signing. After discussing it in our chat, I realized we could contribute there. But there's a second part — app interaction (fetching balances, broadcasting transactions). That's closed-source. Only Trust Wallet's internal team can build it.

And that means: management approval, allocated engineering time, accountability. Trust Wallet can't just say "sure, we'll ship it next month."

TON Foundation had doubts:

What if Trust Wallet never adds it to the app? Why fund the grant?

Eventually, both teams met in the middle. TON approved the grant; Trust Wallet committed to prioritizing the integration. Win-win: a new blockchain and users for Trust Wallet, a new wallet and users for TON.

We started coding. My friend did most of the development — I reviewed and refined. We merged the PR in about a month.

How Trust Wallet Works Under the Hood

Trust Wallet runs on three platforms: Android, iOS, and a browser extension.

At its core is Wallet Core — an open-source library supporting over 130 blockchains. Written in C++ and Rust. It's not just used by Trust Wallet; other major wallets like Crypto.com rely on it too. The library handles:

Private key generation
Address creation and validation
Transaction signing
Smart contract interactions

This is where we added TON.

An Unexpected Bonus: Code from Everscale

Few people know the full story.

Originally, Durov launched TON, with TON Labs handling part of the development. After US sanctions, Durov stepped away — but TON Labs didn't. They continued building a fork called Free TON, which later became Everscale.

Then a new TON Foundation emerged, endorsed by Durov. It's now integrated into Telegram and has taken off. Everscale, meanwhile, has faded.

Here's the thing: TON Labs did a lot of impressive technical work. Everscale was already in Wallet Core. We extracted the shared code into a module called CommonTON.

That code now powers both Everscale and TON.

What Makes TON Different

Your Wallet Is a Smart Contract

In TON, a wallet isn't just an address — it's a full-fledged smart contract. Everscale uses the older V3 wallet; for TON, we implemented V4R2.

Transaction Structure

In order to create a transaction from wallet, you have to send a message to the wallet smart contract:

External Message (from user to their contract)
├── header: sender's contract address
├── stateInit: code and data (first transaction only)
└── 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

I won't go too deep here. You can read more about the V4 wallet in the docs — including the source code.

Cells and BOC — A Unique Data Model

All data in TON is represented as a tree of cells (Bag of Cells). Each cell holds up to 1023 bits of data and up to 4 references to other cells.

Here's how we create a cell with V4R2 wallet data:

Cell::Ref WalletV4R2::createDataCell() const {
    CellBuilder builder;

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

    return builder.intoCell();  // Total: 321 bits
}

To build a transaction, you assemble these cells correctly: recipient address, amount, comment — all packed into a BOC. Luckily, the BOC serializer was already implemented.

Address Formats

Everscale only has raw addresses:

0:4f6bbb5de550f01a5b73792ceca77d8c933ab396a1e300eb0ab5a5f49a430986

TON also supports a user-friendly format:

EQBPa7td5VDwGltzeSzsp32MkzqzlqHjAOsKtaX0mkMJhq_B

This is a base64 string that includes address type information and a checksum. The checksum helps catch typos in seed phrases.

Why Tonkeeper and Trust Wallet Are Incompatible

The Mnemonic Problem

Standards rule the blockchain world. Much of what originated in Bitcoin is still used today. BIP39 (Bitcoin Improvement Proposal) describes how to derive a private key from a seed phrase. The formula: seed = hash(mnemonic + salt).

By standard, salt = "mnemonic" + password.

In TON, salt = "TON default seed".

The result: the same seed phrase produces different keys in Tonkeeper vs. Trust Wallet. You cannot transfer a wallet between them.

This isn't unique to TON — the same issue exists with Waves, Qtum, and Polkadot (sr25519).

Checksum Validation

TON addresses include a checksum. If a user mistypes a word in their seed phrase and the checksum doesn't match, the wallet warns them immediately. This is another reason Tonkeeper and Trust Wallet wallets aren't interchangeable.

Beyond Wallet Core

In addition to the Wallet Core implementation, I provided Trust Wallet's team with code examples: how to fetch transaction data, query wallet state, and more. I also consulted on app integration questions related to TON. Also added blockchain info and the logo to the assets repository.

The Result

I connected with the TON and Trust Wallet teams. My friend and I built the integration. The code now runs in Trust Wallet across all platforms.

January 2023 — the PR was merged into Wallet Core.

Numbers:

130 million Trust Wallet users gained access to TON
Grant for blockchain integration: $4,250
Grant for adding Jettons: $4,000

Code:

TON in Wallet Core — main integration
Jettons (TON tokens) — added later

A few months later, I added Jettons, then moved on to other projects for TON and NEAR. But that's a story for another time.

Occasionally I share notes on development and more on Twitter

I would also like to say thank you to everyone who contributed:
Tao Xu, Sztergbaum Roman, optout, Sergei, Viacheslav from Trust Wallet team - for organisation and code review
Kirill from TON Foundation - for helping me manage all of that, Narek - for tech support from TON
Viacheslav - for implementing the main integration
Vladimir from Trust Wallet - for making it possible and for code review
And to everyone else, who contributed to this project

DEV Community