> ## Documentation Index
> Fetch the complete documentation index at: https://whalescorp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet Management (creation, import, seed phrase)

# What is a wallet in Tonhub

A wallet in the application is a combination of three interconnected elements:

* **Secret cryptographic keys** — a unique pair of mathematically linked keys (private and public) that are generated from your seed phrase. The private key is used to digitally sign all outgoing transactions and never leaves your device. The public key allows other network participants to verify the authenticity of your transactions
* **Address in TON and Solana blockchains** — this is your unique identifier in the network, which looks like a string of characters (for example, EQD...). It works like a bank account number: other users send coins to this address, and you use it to receive funds. The address is mathematically derived from your public key
* **Local data on the phone** — information that is stored only on your device: application settings (language, display currency, security level), cached history of all your transactions, contacts and saved addresses for convenient transfers. This data does not affect the wallet itself, but makes working with it more convenient

<Info>
  The main point: your funds are stored in the blockchain, not in the application. The application is a way to manage these funds using your secret phrase (seed / recovery phrase).
</Info>

# Creating a New Wallet

Creating a wallet technically means generating [cryptographic keys](https://en.wikipedia.org/wiki/Cryptographic_key) and an address, not opening a bank account.

## Creation Algorithm

1. **Entropy Generation** — the application on the device creates a cryptographically strong [random number](https://en.wikipedia.org/wiki/Random_number_generation) of sufficient length. This number serves as the foundation for all subsequent cryptographic operations and is practically impossible to brute force or guess.
2. **Mnemonic Phrase Formation** — based on the generated entropy, a [seed phrase](https://en.wikipedia.org/wiki/Mnemonic_phrase) consisting of 24 words is created on the device. This phrase allows complete recovery of the original secret key.
3. **Cryptographic Key Generation** — from the original secret, the following are computed:
   1. **Private Key** — a secret key that provides the right to sign transactions and manage funds
   2. **Public Key** — an open key used for verifying [digital signatures](https://en.wikipedia.org/wiki/Digital_signature). In [Solana](https://solana.com), the wallet address = public key, simply written in the convenient [Base58](https://en.wikipedia.org/wiki/Base58) format (a long string without special characters).
4. **Wallet Address Calculation (for TON)** — based on the public key, a unique wallet address is generated by applying a [cryptographic hash function](https://en.wikipedia.org/wiki/Cryptographic_hash_function).

## Wallet Activation

An active wallet is one that already works in the blockchain. It has a balance or transaction history, and it can send transfers if it has enough [TON](https://ton.org) to pay fees.\
In the [TON network](https://ton.org), every wallet is a [smart contract](https://en.wikipedia.org/wiki/Smart_contract). For a wallet to become active, you need to:

* Deploy the contract on the network
* Configure it correctly
* Have enough TON for fees

Therefore, sometimes this situation occurs: money has already arrived at the address and you can see the balance, but you can't send a transfer yet. This happens when there isn't enough TON for the fee or the contract hasn't been initialized yet.\
For a regular user address in [Solana](https://solana.com), "active" means:

* The address has transaction history in the blockchain,
* There is [SOL](https://solana.com/sol) on the balance to pay fees for sending transfers.

# Token Accounts and Token Storage

In [TON](https://ton.org), the main coin and tokens are stored in one contract, providing direct access to them. [Solana's](https://solana.com) architecture is different.\
In the Solana network, each [SPL token](https://spl.solana.com) is stored in a separate specialized account, not on the general wallet address. For each "wallet + token" pair, a standard account is created — [Associated Token Account (ATA)](https://spl.solana.com/associated-token-account), which contains the balance of a specific token.\
**Creating token-account**\
When first interacting with a new token (for example, when receiving [USDC](https://www.centre.io/usdc)), your address lacks the corresponding ATA. Before executing the operation, the system must create such an account in the blockchain — this requires a separate transaction with a fee in SOL.\
**Automation in Tonhub**\
Tonhub automatically creates the necessary token-accounts during first operations with a token. The user doesn't need to perform additional actions — a "Create ATA" line appears in the transaction details, indicating the technical creation of an account in the network.

# Where the Private Key is Stored in Tonhub

The private key is stored exclusively on the user's device in encrypted form. The private key and seed phrase are not transmitted to Tonhub servers and are not saved in cloud storage by default.\
Keys and wallet data in the application are stored exclusively in encrypted state:

* Encryption is performed by the application's internal key, which is placed in the operating system's secure storage:
  * iOS — [Keychain](https://developer.apple.com/documentation/security/keychain_services) (via Secure Store)
  * Android — [Android Keystore](https://developer.android.com/training/articles/keystore)
* Access is tied to PIN code or biometric authentication and a specific device

## Access to Encrypted Key

1. Requires device unlock (PIN code, password, [Face ID](https://support.apple.com/en-us/HT208109), [Touch ID](https://support.apple.com/en-us/HT201371) and other authentication methods)
2. On some devices, the "only on this device" option is activated, excluding the possibility of transferring data from storage to another device

## Security Justification of This Approach

1. No centralized point of vulnerability. Tonhub does not have access to the user's private key and cannot lose it from its server, since the key is not transmitted to the company's servers.
2. Protection at the operating system and hardware level. [Keychain](https://developer.apple.com/documentation/security/keychain_services) and [Keystore](https://developer.android.com/training/articles/keystore) are designed with the following principles:
   1. Isolation from other applications — third-party applications cannot access secret data
   2. Binding to a specific device and unlock method
   3. Even if application files are compromised, obtaining the private key is practically impossible:
      1. Data is in encrypted state
      2. Decryption requires a key from secure storage, access to which is impossible without physical access to the device and its unlock

The main risk factor remains the human factor: in case of seed phrase compromise (written on paper, saved as a photo, etc.), cryptographic protection on the device becomes ineffective.

# Importing an Existing Wallet

## Importing TON Wallet

1. From the secret, using the algorithm and [TON](https://ton.org) parameters fixed in the application, an [ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) key is formed.
2. From the key, the wallet smart contract address is calculated (wallet type/version, workchain, etc.). This address will be used for incoming/outgoing TON and tokens.
3. Verification/synchronization with the TON network. Request to the blockchain by address:
   1. Is there already a balance/transactions
   2. Is the wallet (contract) activated and can it send
   3. If operations have already occurred at the address, history is pulled

## Importing Solana Wallet

1. After entering the same (or separate) secret using the [Solana](https://solana.com) scheme, an [ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) key is formed.
2. From the public key, an address string is formed.
3. Request to the Solana network. The application queries the [RPC node](https://docs.solana.com/developing/clients/jsonrpc-api) (server that is connected to the blockchain and responds to application requests):
   1. Main balance in SOL
   2. Associated token accounts (SPL tokens)
   3. Transaction history

# Can You Use Seed Phrase from Tonhub in Other Applications

[Derivation path](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) represents the algorithm by which a wallet generates a specific private key and address from one seed phrase.

* [TON](https://ton.org) wallet and token balance will display correctly if the target application supports the TON network, since the wallet format and derivation path in most applications correspond to Tonhub standards.
* [Solana](https://solana.com) balance will display only if the application uses identical rules for generating Solana keys from the seed phrase. Compatibility is not guaranteed, as different wallets may use different derivation paths.

# **Creating Multiple Wallets**

Tonhub supports creating an unlimited number of wallets. Users can always import or create a new wallet. When creating/importing a wallet (`WalletSecurePasscodeComponent`), the new address is simply added to the end of the `state.addresses` list without quantity limitation. Only a duplicate of an already added address cannot be added.

# How to Store Seed Phrase

**Main rule:**[Seed phrase](https://en.wikipedia.org/wiki/Mnemonic_phrase) is the only key to your money. Whoever owns the phrase owns the wallet. No phrase — no access.

## How to Store Safely

**Write on paper:**

* Completely, without abbreviations
* Clearly, legibly, with word or line numbers
* Don't photograph the paper

**Make several copies:**

* 2–3 copies in different safe places (home, safe, bank deposit box, etc.)
* Copies should be physically separated (so fire/theft in one place doesn't destroy everything)

**Store where:**

* there is no free access by strangers
* there is no high probability of loss/disposal (for example, not on the table, not in a "daily" notebook)
* you yourself will guaranteed remember where this place is after years

## How to Verify the Phrase is Written Correctly

**After writing:**

* Twice re-enter the phrase from the sheet into the application/wallet (in recovery mode) **as a test**:
  * On a separate device or in a secure environment
  * Make sure the wallet opens with your written copy

**Compare:**

* Number of words
* Order
* Correct spelling (especially similar words)

**Good practice:**

* Sign the sheet (but not with the phrase), for example: "Tonhub, main wallet, date"

## What to Do if You Suspect a Leak

1. Consider the current phrase compromised
2. In Tonhub:
   1. Create a new wallet with a new seed phrase
   2. Write it down correctly and verify it
3. Transfer all funds from the "suspicious" wallet to the new one:
   1. [TON](https://ton.org), tokens, [Solana](https://solana.com) assets (if any)
4. After transfer:
   1. stop using the old seed phrase entirely
   2. destroy all its copies (paper and digital)

## What to Do if You Lost Your Seed Phrase

**Honest answer:**\
**If:**

* Tonhub with this wallet is no longer on the device
* and there is no copy of the seed phrase (paper lost, photos deleted, you don't remember the words)

**Then:**

* recovering access to funds is impossible:
  * Not through Tonhub support
  * Not through developers
  * Not through blockchain

The blockchain doesn't know "who you are" — it only knows the mathematical key. Without the seed phrase, this key cannot be recovered.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.