README (8680B)
1 kisstron: KISS-friendly Tron CLI wallet 2 --------------------------------------- 3 This is a simple, no-nonsense Tron cryptocurrency wallet written in Python 3 4 on top of the open-source tronpy library. The kisstron project aims to enable 5 CLI users to easily use Tron cryptocurrency, including stablecoins like USDT 6 or USDC, without all the hassle of "native" (Java-based) Tron's wallet-cli or 7 similar third-party projects. 8 9 == Features == 10 11 * Support for mainnet Tron as well as Nile and Shasta testnets 12 * Small codebase size that can be easily audited 13 * Full BIP-39 support for mnemonic wallet generation and import (English only) 14 * Account info display: TRX/USDT/USDC balances, frozen assets, remaining 15 energy and bandwidth 16 * Sending TRX/USDT/USDC on all supported networks 17 * Freezing (for energy) and unfreezing TRX on all supported networks 18 * Ability to connect to custom nodes or TronGrid API (with your own API key) 19 * Offline mode for send/freeze/unfreeze transactions 20 * No filesystem interaction (that's a feature, not a bug: see the FAQ section) 21 * Full scriptability: send/freeze/unfreeze transactions require manual approval 22 but it actually can be turned off with a special commandline parameter for the 23 kisstron wallet to be used in various automation tasks 24 * The kisstron.py file can be used as a library itself for different projects 25 26 == Dependency setup == 27 28 First, install Python 3, pip and the required dependencies (from this dir): 29 30 pip install -r requirements.txt 31 32 In some distributions, you may need to run pip3 instead of pip. Also, your 33 distribution might not contain the required development packages. For instance, 34 in Alpine Linux, you might have to run the following command first (as root): 35 36 apk add python3-dev libtool autoconf automake musl-dev libffi-dev 37 38 Optionally, make the kisstron.py file executable: 39 40 chmod +x kisstron.py 41 42 After everything is set up, you should be able to run the help screen: 43 44 ./kisstron.py -h 45 46 == Usage == 47 48 Now, let's cover typical kisstron wallet usage scenarios. 49 50 -- Generate a new wallet -- 51 52 ./kisstron.py new trx [-pp "passphrase"] [-wc word_count] [-dp derivation_path] 53 54 This will generate a new Tron wallet and display all its information. You must 55 then store this information in a secure place. 56 If -pp option is specified, your custom passphrase will be used to encrypt the 57 mnemonic phrase. If -wc option is specified, you can set to generate 15, 18, 21 58 or 24 words of mnemonic instead of 12. If -dp option is specified, you can set 59 a non-standard BIP-39 derivation path. It is generally NOT recommended to ever 60 use this option unless you are an expert. 61 62 -- Import an existing wallet from a mnemonic -- 63 64 ./kisstron.py import trx [-pp "passphrase"] [-dp derivation_path] 65 66 This will ask you to enter your BIP-39 mnemonic and import your Tron wallet by 67 recovering and displaying all information about it. You must then store this 68 information in a secure place. 69 If -pp option is specified, your custom passphrase will be used to decrypt the 70 mnemonic phrase. The -dp option is the same as for the "new trx" subcommand, so 71 the same precautions apply. 72 Note that entering a wrong passphrase won't generate an error: kisstron will 73 just restore a different wallet from the same mnemonic, so be careful. 74 75 -- Network options -- 76 77 For any of the further operations in this section, the following options can 78 be added and are quite important: 79 80 * -net selects the network: mainnet (default), nile, shasta 81 * -node allows to specify custom Tron node URL (must be HTTP URL, not RPC) 82 * -tgkey allows to specify custom TronGrid API key (overrides -node) 83 * -fee allows to set custom transaction fee limit (in TRX, 100 by default) if 84 operating on the mainnet (relevant for send, fre and unf subcommands) 85 86 These options will be marked as [netopts] in the further reference. 87 88 Note that -tgkey is only relevant for mainnet and has no effect on testnets. 89 90 -- Displaying account information -- 91 92 Display account information based on any Tron address: 93 94 ./kisstron.py info trx -addr tron_address [netopts] 95 96 Display your account information based on your private key (in hex): 97 98 ./kisstron.py info trx -pk private_key [netopts] 99 100 Either of these commands will display the following information: 101 102 * Tron address (in Base58check format) 103 * Balances in TRX, USDT and USDC 104 * Frozen TRX assets (if any) 105 * Remaining bandwidth amount 106 * Remaining energy amount 107 108 If you supply both -pk and -addr to "info trx" subcommand, -pk will take 109 precedence. 110 111 -- Sending funds -- 112 113 Send TRX: 114 115 ./kisstron.py send trx -addr dest_addr -amt amount -pk private_key [netopts] 116 117 Send USDT: 118 119 ./kisstron.py send usdt -addr dest_addr -amt amount -pk private_key [netopts] 120 121 Send USDC: 122 123 ./kisstron.py send usdc -addr dest_addr -amt amount -pk private_key [netopts] 124 125 Any of these commands will ask you for confirmation by entering "yes" and 126 pressing Enter to send the transaction. If you don't want to do this or use 127 the send subcommands in some kind of automation, append -nc flag to them. 128 The amount is entered in floating point TRX/USDT/USDC values respectively, 129 not in minimal units. 130 When transfering USDT/USDC, you may get error messages related to lack of 131 energy to conduct the transaction. Please refer to the next section of TRX 132 freezing to get energy. 133 134 -- Freezing and unfreezing TRX funds -- 135 136 Freeze TRX for energy: 137 138 ./kisstron.py fre trx -amt amount -pk private_key [netopts] 139 140 Unfreeze TRX: 141 142 ./kisstron.py unf trx -amt amount -pk private_key [netopts] 143 144 Any of these commands will ask you for confirmation by entering "yes" and 145 pressing Enter to send the transaction. If you don't want to do this or use 146 the subcommands in some kind of automation, append -nc flag to them. 147 Again, the amount of TRX is entered as a floating point value. 148 149 Keep in mind that it takes up to 72 hours to unfreeze your TRX assets. 150 151 -- Offline operations -- 152 153 The send trx, send usdt, send usdc, fre trx and unf trx subcommands support the 154 -o flag that, after the "Success:" line, outputs a JSON of a signed transaction. 155 You can copy or otherwise transfer this output to a different machine running 156 kisstron and broadcast it to the network with bro trx subcommand: 157 158 ./kisstron.py bro trx [netopts] 159 160 You can then paste the transaction JSON into the input field, press Enter and, 161 unless -nc flag is passed too, confirm sending the transaction by entering yes. 162 The transaction will be broadcast and processed as usual. 163 164 Keep in mind that Tron transactions expire very quickly, so you have a limited 165 time window between signing and publishing them. 166 167 == FAQ == 168 169 - Can I trust this wallet? 170 171 The author trusts it. In fact, kisstron was created because of lack of decent 172 FOSS Tron wallets for Linux/BSD desktop operating systems. However, it cannot 173 be considered production-ready as it hasn't undergone rigorous testing and 174 independent audit. The kisstron codebase is small and well-commented though, 175 so you can trust it exactly to the same extent as you trust the underlying 176 tronpy library and its dependencies. 177 You can study tronpy source code here: https://github.com/andelf/tronpy 178 179 - Why are TRC-20 tokens hardcoded? 180 181 To simplify the logic and avoid any user mistakes when manually pasting token 182 contract addresses. If you need to add custom token support, you can always 183 modify the KT_TRC20_TOKENS dictionary in the source code directly. 184 185 - Why doesn't kisstron do anything to keep private keys and passphrases secure? 186 187 Because it only cares about interacting with Tron network and creating or 188 restoring your wallets. For key/password management, there are dedicated tools 189 like pass (https://www.passwordstore.org/) that do their job extremely well. 190 For example, instead of -pk private_key, you could write -pk $(pass kt/pkey) or 191 something like that if you stored your wallet key under kt/pkey path in pass. 192 This way, your keys can stay secure without adding any filesystem interaction 193 to kisstron itself, reducing the overall attack surface. 194 195 - Does kisstron use any remote API to sign transactions? 196 197 No. The underlying tronpy library signs all transactions offline, so the 198 private key never leaves your machine. It uses libsecp256k1 via coincurve 199 library binding for transaction signing. 200 201 You can also use offline mode to split signing and sending transactions, as 202 shown in this document. 203 204 - Why doesn't kisstron support TRC-10, multisig, witnesses, history etc? 205 206 Support for some of these things may come in the future. But kisstron was 207 created as a minimum viable wallet to operate on TRX and select stablecoins. It 208 adheres to the KISS principle ("keep it simple, stupid"), hence the name. 209 210 == Credits == 211 212 Created by Luxferre in 2024, released into public domain with no warranties. 213 214 Made in Ukraine.