initial upload

README

@@ -0,0 +1,196 @@
+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.