kisstron/README

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)
* Offline mode for send/freeze/unfreeze transactions
* 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.

-- Offline operations --

The send trx, send usdt, send usdc, fre trx and unf trx subcommands support the
-o flag that, after the "Success:" line, outputs a JSON of a signed transaction.
You can copy or otherwise transfer this output to a different machine running
kisstron and broadcast it to the network with bro trx subcommand:

./kisstron.py bro trx [netopts]

You can then paste the transaction JSON into the input field, press Enter and,
unless -nc flag is passed too, confirm sending the transaction by entering yes.
The transaction will be broadcast and processed as usual.

Keep in mind that Tron transactions expire very quickly, so you have a limited
time window between signing and publishing them.

== FAQ ==

- Can I trust this wallet?

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.

You can also use offline mode to split signing and sending transactions, as
shown in this document.

- 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.