From 970cd56ba58fb037bac0a1586d55b22d6dece4c5 Mon Sep 17 00:00:00 2001 From: Luxferre Date: Sat, 19 Sep 2026 18:26:25 +0300 Subject: [PATCH] go port --- README | 214 ------------------------------------------------------ README.md | 100 +++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 214 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 05c5e76..0000000 --- a/README +++ /dev/null @@ -1,214 +0,0 @@ -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) -* -fee allows to set custom transaction fee limit (in TRX, 100 by default) if - operating on the mainnet (relevant for send, fre and unf subcommands) - -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..d13f9c0 --- /dev/null +++ b/README.md @@ -0,0 +1,100 @@ +# kisstron (Go) + +A KISS-oriented TRON CLI wallet, ported from Python to Go with **zero third-party +dependencies** (Go standard library only). It doubles as an importable library. + +## Install + +```sh +go install code.luxferre.top/luxferre/kisstron@latest +``` + +This builds the `kisstron` CLI into `$(go env GOPATH)/bin`. + +## CLI usage + +The command-line interface is identical to the original Python `kisstron.py`: + +```sh +kisstron new trx +kisstron import trx +kisstron info trx -addr +kisstron info trx -pk -net nile +kisstron send trx -addr -amt 10 -pk +kisstron send usdt -addr -amt 5 -pk -nc +kisstron fre trx -amt 100 -pk +kisstron unf trx -amt 100 -pk +kisstron send trx -addr -amt 10 -pk -o # offline: emit signed JSON +kisstron bro trx # broadcast JSON from stdin +``` + +Options: `-net/--network`, `-node/--tron-node`, `-tgkey/--trongrid-api-key`, +`-fee/--fee-limit`, `-addr/--address`, `-amt/--amount`, `-pk/--private-key`, +`-o/--offline`, `-pp/--passphrase`, `-wc/--words-count`, `-dp/--derivation-path`, +`-nc/--no-confirm`. See `kisstron -h` for details. + +## Library usage + +All packages live at the module root and can be imported directly: + +| Package | Purpose | +| --- | --- | +| `code.luxferre.top/luxferre/kisstron/tron` | Keys, addresses, TRON client, transactions, TRC20, wallet helpers | +| `code.luxferre.top/luxferre/kisstron/keccak` | Legacy Keccak-256 | +| `code.luxferre.top/luxferre/kisstron/base58` | Base58 / base58check | +| `code.luxferre.top/luxferre/kisstron/secp256k1` | secp256k1 curve + recoverable ECDSA | +| `code.luxferre.top/luxferre/kisstron/bip39` | BIP-39 mnemonics and seed derivation | +| `code.luxferre.top/luxferre/kisstron/bip32` | BIP-32 CKDpriv derivation | +| `code.luxferre.top/luxferre/kisstron/ops` | High-level wallet operations | +| `code.luxferre.top/luxferre/kisstron/cli` | Result formatting and confirmation | + +Example: restore a wallet and convert an address. + +```go +package main + +import ( + "fmt" + + "code.luxferre.top/luxferre/kisstron/tron" +) + +func main() { + key, err := tron.DeriveFromMnemonic("cloth print knife public box ... rose lounge", "", "") + if err != nil { + panic(err) + } + fmt.Println(key.Pub.ToBase58CheckAddress()) + + addr, _ := tron.ToHexAddress(key.Pub.ToBase58CheckAddress()) + fmt.Println(addr) +} +``` + +Example: query the chain and send TRX. + +```go +client := tron.NewClient("nile", tron.DefaultEndpoint("nile"), tron.FeeLimitTestnet, "") +info, err := client.GetAccount("TTynhnM88m4C9Wohm2zT6oiYbV7hC8qUJm") +if err != nil { + panic(err) +} +fmt.Println(info["balance"]) + +key, _ := tron.PrivateKeyFromHex("") +builder, _ := client.Transfer(key.Pub.ToBase58CheckAddress(), "", 1_000_000) +tx, _ := builder.Build() +_ = tx.Sign(key) +receipt, _ := tx.Broadcast() +fmt.Println(receipt["txid"]) +``` + +## Notes + +- **Zero dependencies**: `go.mod` has no `require` block and there is no `go.sum`. + Every cryptographic primitive is implemented on the Go standard library. +- Source uses 2-space indentation (do not run `gofmt`, which would convert it to tabs). +- The original Python implementation is retained as `kisstron.py` for reference. +- The Go port reproduces the original output byte-for-byte, including a latent + bandwidth calculation quirk in the Python original (documented in `ops/ops.go`). +- Created by Luxferre, released into the public domain with no warranties. \ No newline at end of file