How a browser non-custodial wallet works
Gram Wallet generates your 24-word phrase in the browser and never sends it anywhere. The phrase is encrypted with your password using PBKDF2-SHA256 at 600,000 iterations and AES-GCM-256 through the browser’s WebCrypto, and the result is kept in this browser’s local storage. The password itself is not stored.
When you send, the message is signed locally; only the signed bytes go to a TON node. Broadcast is not confirmation: the wallet waits for the network to accept the message before reporting success.
The limits are those of any browser: code running in the page, extensions, or someone at your unlocked device can reach an unlocked key. The code has had no external security audit.
What this covers
- Covers Gram Wallet inside Tongram: key creation, storage, unlocking, signing and broadcast.
- Assumes a recent Chrome, Safari, Firefox or Edge, or the Telegram in-app browser; WebCrypto is required.
- Does not cover hardware wallets or other TON wallets; Tongram does not integrate them.
Steps in Tongram
- Open Wallet and create a new wallet. The 24 words are produced locally; write them down before continuing, they are the only way to restore.
- Set a password. It derives the encryption key on your device and is not written anywhere; forgetting it means restoring from the phrase.
- Optionally choose "stay unlocked until this tab closes". The decrypted phrase then sits in that tab’s session storage and disappears when the tab closes.
- Send something. The review screen shows network, recipient, and for tokens the contract and decimals; the outcome box shows the emulated result. Signing happens when you confirm.
- Watch the stages: signed, broadcast, confirmed. If the network has not accepted the message within a minute, the wallet says the result is unknown and gives you the identifier to check, rather than inviting a resend.
What you see and where it comes from
- Keys and addresses are derived locally with the TON crypto libraries; the wallet contract is v5r1 by default, v4r2 for imported wallets that need it.
- The encrypted vault, account list and contacts live in local storage; nothing of this is transmitted.
- Balances and history are read from Toncenter; token and collectible trust flags and the pre-signature emulation come from tonapi.
- The signed external message is delivered to a Toncenter endpoint; the wallet then polls the contract’s seqno to learn whether it was accepted.
Freshness and limits
- Encryption at rest does not protect an unlocked key from malicious code in the same page or from an extension with page access.
- Clearing site data deletes the vault. Without the 24 words, or an encrypted backup, the wallet is gone.
- A message accepted by a node can still fail on chain. The wallet reports what it can observe and says "unknown" when it cannot.
- No external audit has been performed. You are choosing to trust code you can inspect, not code someone has reviewed for you.
- Confirm the address bar reads tongram.net before unlocking; a lookalike domain can show the same screens.
Common mistakes
- Treating the password as the backup. It only unlocks this browser’s copy; the phrase is the backup.
- Leaving "stay unlocked" on a shared or public machine. Anyone at the tab can sign until it closes.
- Sending again after a slow broadcast. Check the identifier the wallet gives you first; a second send can go through twice.
- Restoring the phrase into a page reached from a link in a message. Type the domain yourself.