kisstron: KISS-friendly Tron CLI wallet --------------------------------------- This is a simple, no-nonsense Tron cryptocurrency wallet written in Python 3 on top of the open-source tronpy library. The kisstron project aims to enable CLI users to easily use Tron cryptocurrency, including stablecoins like USDT or USDC, without all the hassle of "native" (Java-based) Tron's wallet-cli or similar third-party projects. == Features == * Support for mainnet Tron as well as Nile and Shasta testnets * Small codebase size that can be easily audited * Full BIP-39 support for mnemonic wallet generation and import (English only) * Account info display: TRX/USDT/USDC balances, frozen assets, remaining energy and bandwidth * Sending TRX/USDT/USDC on all supported networks * Freezing (for energy) and unfreezing TRX on all supported networks * Ability to connect to custom nodes or TronGrid API (with your own API key) * No filesystem interaction (that's a feature, not a bug: see the FAQ section) * Full scriptability: send/freeze/unfreeze transactions require manual approval but it actually can be turned off with a special commandline parameter for the kisstron wallet to be used in various automation tasks * The kisstron.py file can be used as a library itself for different projects == Dependency setup == First, install Python 3, pip and the required dependencies (from this dir): pip install -r requirements.txt In some distributions, you may need to run pip3 instead of pip. Also, your distribution might not contain the required development packages. For instance, in Alpine Linux, you might have to run the following command first (as root): apk add python3-dev libtool autoconf automake musl-dev libffi-dev Optionally, make the kisstron.py file executable: chmod +x kisstron.py After everything is set up, you should be able to run the help screen: ./kisstron.py -h == Usage == Now, let's cover typical kisstron wallet usage scenarios. -- Generate a new wallet -- ./kisstron.py new trx [-pp "passphrase"] [-wc word_count] [-dp derivation_path] This will generate a new Tron wallet and display all its information. You must then store this information in a secure place. If -pp option is specified, your custom passphrase will be used to encrypt the mnemonic phrase. If -wc option is specified, you can set to generate 15, 18, 21 or 24 words of mnemonic instead of 12. If -dp option is specified, you can set a non-standard BIP-39 derivation path. It is generally NOT recommended to ever use this option unless you are an expert. -- Import an existing wallet from a mnemonic -- ./kisstron.py import trx [-pp "passphrase"] [-dp derivation_path] This will ask you to enter your BIP-39 mnemonic and import your Tron wallet by recovering and displaying all information about it. You must then store this information in a secure place. If -pp option is specified, your custom passphrase will be used to decrypt the mnemonic phrase. The -dp option is the same as for the "new trx" subcommand, so the same precautions apply. Note that entering a wrong passphrase won't generate an error: kisstron will just restore a different wallet from the same mnemonic, so be careful. -- Network options -- For any of the further operations in this section, the following options can be added and are quite important: * -net selects the network: mainnet (default), nile, shasta * -node allows to specify custom Tron node URL (must be HTTP URL, not RPC) * -tgkey allows to specify custom TronGrid API key (overrides -node) These options will be marked as [netopts] in the further reference. Note that -tgkey is only relevant for mainnet and has no effect on testnets. -- Displaying account information -- Display account information based on any Tron address: ./kisstron.py info trx -addr tron_address [netopts] Display your account information based on your private key (in hex): ./kisstron.py info trx -pk private_key [netopts] Either of these commands will display the following information: * Tron address (in Base58check format) * Balances in TRX, USDT and USDC * Frozen TRX assets (if any) * Remaining bandwidth amount * Remaining energy amount If you supply both -pk and -addr to "info trx" subcommand, -pk will take precedence. -- Sending funds -- Send TRX: ./kisstron.py send trx -addr dest_addr -amt amount -pk private_key [netopts] Send USDT: ./kisstron.py send usdt -addr dest_addr -amt amount -pk private_key [netopts] Send USDC: ./kisstron.py send usdc -addr dest_addr -amt amount -pk private_key [netopts] Any of these commands will ask you for confirmation by entering "yes" and pressing Enter to send the transaction. If you don't want to do this or use the send subcommands in some kind of automation, append -nc flag to them. The amount is entered in floating point TRX/USDT/USDC values respectively, not in minimal units. When transfering USDT/USDC, you may get error messages related to lack of energy to conduct the transaction. Please refer to the next section of TRX freezing to get energy. -- Freezing and unfreezing TRX funds -- Freeze TRX for energy: ./kisstron.py fre trx -amt amount -pk private_key [netopts] Unfreeze TRX: ./kisstron.py unf trx -amt amount -pk private_key [netopts] Any of these commands will ask you for confirmation by entering "yes" and pressing Enter to send the transaction. If you don't want to do this or use the subcommands in some kind of automation, append -nc flag to them. Again, the amount of TRX is entered as a floating point value. Keep in mind that it takes up to 72 hours to unfreeze your TRX assets. == FAQ == - Can I trust it? The author trusts it. In fact, kisstron was created because of lack of decent FOSS Tron wallets for Linux/BSD desktop operating systems. However, it cannot be considered production-ready as it hasn't undergone rigorous testing and independent audit. The kisstron codebase is small and well-commented though, so you can trust it exactly to the same extent as you trust the underlying tronpy library and its dependencies. You can study tronpy source code here: https://github.com/andelf/tronpy - Why are TRC-20 tokens hardcoded? To simplify the logic and avoid any user mistakes when manually pasting token contract addresses. If you need to add custom token support, you can always modify the KT_TRC20_TOKENS dictionary in the source code directly. - Why doesn't kisstron do anything to keep private keys and passphrases secure? Because it only cares about interacting with Tron network and creating or restoring your wallets. For key/password management, there are dedicated tools like pass (https://www.passwordstore.org/) that do their job extremely well. For example, instead of -pk private_key, you could write -pk $(pass kt/pkey) or something like that if you stored your wallet key under kt/pkey path in pass. This way, your keys can stay secure without adding any filesystem interaction to kisstron itself, reducing the overall attack surface. - Does kisstron use any remote API to sign transactions? No. The underlying tronpy library signs all transactions offline, so the private key never leaves your machine. It uses libsecp256k1 via coincurve library binding for transaction signing. Ability to implement offline mode (transactions are created and signed on one kisstron instance without Internet connectivity, then broadcast from another) in the future versions is being studied. - Why doesn't kisstron support TRC-10, multisig, witnesses, history etc? Support for some of these things may come in the future. But kisstron was created as a minimum viable wallet to operate on TRX and select stablecoins. It adheres to the KISS principle ("keep it simple, stupid"), hence the name. == Credits == Created by Luxferre in 2024, released into public domain with no warranties. Made in Ukraine.