DOCSEARCHbyAlgolia
Submit Docs

tons Documentation

website·Indexed 29 days ago

https://tonfactory.github.io/tons-docs/

An open-source cross-platform wallet application and command-line interface for the TON blockchain. Features include support for TON DNS, Multisig v2 wallets, Jetton standards, and Tonconnect v2 protocol, alongside tools for smart-contract deployment using tonsdk.

Tokens
5K
Snippets
36
Records
45
Agent score
75%

What's inside tons

  1. Overview of tons wallet application

    tons is an Open Source cross-platform wallet application and command-line interface used to maintain any type of wallet on the TON network. It is compatible with Windows, Mac, and Linux, and can be deployed on both desktops and servers.

  2. Overview of Keystore encryption types

    The tons tool uses keystores—encrypted files—to store wallet private keys. There are two primary types:

    1. Password: Encrypts only sensitive data; public data remains plain text.
    2. YubiKey: Encrypts all data (including public info) using AES and relies on a hardware device for the private key.

  3. Understand Global and Local Whitelists

    The whitelist is a file used to store user contacts, reducing the risk of transferring assets to the wrong address. There are two types:

    • Global whitelist: Contacts are stored in a whitelist.json file and are accessible from any keystore.
    • Local whitelist: Contacts are stored within a specific keystore file and are only accessible when using that keystore.

  4. Understand the tons filesystem architecture

    tons uses a specific filesystem architecture to manage its data. The application maintains a .tons directory with the following structure:

    • config.yaml: Configuration settings
    • whitelist.json: Whitelisted contacts
    • keystores/: A directory containing individual .keystore files.
    .tons
├── config.yaml
├── whitelist.json
├── keystores
│   ├── *.keystore

  5. Integrate tons CLI with toncli for wallet deployment

    To use a tons wallet with toncli, you must create a wallet matching toncli's expected parameters (version v3r2, subwallet-id 0, workchain 0) and manually replace the toncli wallet files in its configuration directory.
    # 1. Create the compatible wallet
$ tons wallet create toncli-deployer -v v3r2 -w 0 -id 0 --save-to-whitelist toncli-deployer

# 2. Export the wallet to the toncli build directory
# (Replace /path/to/toncli/wallet/build with the actual path from appdirs.user_config_dir("toncli"))
$ tons wallet to-addr-pk toncli-deployer '/Users/username/Library/Application Support/toncli/wallet/build'

# 3. Replace existing toncli wallet files
$ cd '/Users/username/Library/Application Support/toncli/wallet/build'
$ mv contract.pk backup_old.pk && mv contract.addr backup_old.addr
$ mv toncli-deployer.pk contract.pk && mv toncli-deployer.addr contract.addr

  6. Add a contact to the tons whitelist

    Add a TON address to the whitelist and assign it a friendly name (alias) to simplify transfers and management.
    tons whitelist add myBestFriend EQAqJuYmOYI_0C23atgYhQOcL4IHznWbCwUY0u4KOU3yRVEm

  7. Create and configure a tons keystore

    Create a new encrypted keystore to manage your keys and then set it as the active keystore for the current session using the tons.keystore_name configuration key.
    # Create a new keystore
tons keystore new myFirstKeystore --password MY_SECRET

# Set it as the current active keystore
tons config tons.keystore_name myFirstKeystore

  8. Choose a tons user interface

    tons provides three different interfaces depending on the user's needs:

    1. tons-gui: A graphical user interface (GUI) for convenient asset management.
    2. tons-interactive: A terminal-based interactive menu for controlling assets.
    3. tons: A batch-mode CLI for writing automatic scripts and executing direct commands.

  9. Deploy smart contracts using internal messages with tons CLI

    Use the tons dev send-internal command to deploy a smart contract by sending an internal message from a specified wallet. This requires a Python script that defines a function receiving a WalletContract and returning a tuple of (address_string, state_init_cell, optional_cell).
    # CLI Command
$ tons dev send-internal ./scripts/deploy.py deploy_through_internal MY_WALLET_NAME 0.1 --wait
    # ./scripts/deploy.py
from typing import Optional
from tonsdk.contract.wallet import WalletContract
from tonsdk.boc import Cell
from tonsdk.contract.token.ft import JettonMinter

def deploy_through_internal(wallet: WalletContract) -> (str, Optional[Cell], Optional[Cell]):
    minter = JettonMinter(admin_address=wallet.address,
                          jetton_content_uri="URL",
                          jetton_wallet_code_hex='CODE')

    return minter.address.to_string(), minter.create_state_init()["state_init"], None

  10. Import a TON wallet from mnemonics

    Import an existing wallet using its mnemonic phrase and version (e.g., v4r2). Use the --save-to-whitelist flag to give the wallet a friendly name for easier reference in subsequent commands.
    # Import wallet and save to whitelist as 'myPocketMoney'
tons wallet import-from-mnemonics pocketMoney v4r2 0 "YOUR MNEMONIC WORDS HERE" --save-to-whitelist myPocketMoney

# Verify the import by listing wallets
tons wallet list

  11. Deploy smart contracts using external messages with tons CLI

    Use the tons dev send-external command to create and send an external message to the TON blockchain. The associated Python script function must receive no arguments and return a tuple containing the contract address string and the message Cell.
    # CLI Command
$ tons dev send-external ./scripts/deploy.py deploy_through_external --wait
    # ./scripts/deploy.py
from tonsdk.contract.wallet import WalletContract, WalletVersionEnum, Wallets
from tonsdk.boc import Cell

def deploy_through_external() -> (str, Cell):
    wallet_workchain = 0
    wallet_version = WalletVersionEnum.v3r2
    wallet_mnemonics = "YOUR 24 ... WORDS".split(" ")

    _mnemonics, _pub_k, _priv_k, wallet = Wallets.from_mnemonics(
        wallet_mnemonics, wallet_version, wallet_workchain)
    return wallet.address.to_string(), wallet.create_init_external_message()["message"]

  12. Configure YubiKey for keystore use

    To use a YubiKey device with yubikey-type keystores, you must first set up the device. This can be done via the tons-interactive interface (Config > YubiKey) or manually using the ykman tool. When generating a private key manually, you must use slot 0x87, pin-policy ONCE, and key type RSA2048.
    # Generate a private key in the required slot using ykman
ykman piv keys generate 0x87 - -m ${YOUR_MANAGEMENT_KEY} -P ${YOUR_PIN} --pin-policy ONCE --touch-policy ALWAYS -a RSA2048