Update docs/WALLET_TOOLS.md

docs/WALLET_TOOLS.md

@@ -2,6 +2,11 @@
 
 Contractless wallet tools create wallets, restore wallets, export private-key image backups, register wallet addresses with the network, and sign or verify messages.
 
+This page also covers balance lookup helpers:
+
+- `lookup_local_balance`
+- `lookup_remote_balance`
+
 On Windows, add `.exe` to each command name.
 
 When a tool asks for a wallet path, image path, private-key path, or output directory, press `<Tab>` to search and auto-complete files and folders.
@@ -218,6 +223,63 @@ false
 
 This command expects the address itself, not a path to a file containing the address.
 
+## create_vanity_tx
+
+Creates and signs a vanity address registration transaction for the selected wallet.
+
+A vanity address is a human-readable alias that maps back to the wallet's real short address. The vanity name is not a separate wallet and does not create a new private key. It is a registered address alias owned by the wallet that signs the transaction.
+
+Usage:
+
+```text
+create_vanity_tx <vanity_name> <txfee>
+```
+
+Interactive prompts:
+
+```text
+Enter the vanity name to register (letters only, up to 20 characters):
+Please enter the vanity registration fee: (e.g. 1.0, minimum fee 5.00000000):
+Please enter the path to your wallet file:
+What is your wallet decryption key?
+```
+
+Vanity name rules:
+
+- 1 to 20 characters
+- letters only
+- no numbers
+- no punctuation
+- no spaces
+
+The tool automatically lowercases the vanity address and appends the correct wallet/network suffix. For example, entering:
+
+```text
+BruceBates
+```
+
+may create a vanity address like:
+
+```text
+brucebates.cltc
+```
+
+The transaction fee is entered as a decimal amount. The minimum vanity registration fee is:
+
+```text
+5.00000000
+```
+
+The tool saves the signed transaction JSON into:
+
+```text
+./transactions/<transaction_hash>.json
+```
+
+Creating the file does not register the vanity address by itself. Broadcast the saved transaction with `broadcast_transaction`.
+
+After the transaction confirms, tools that support address resolution can use the vanity address as an alias for the wallet's real short address.
+
 ## sign_message
 
 Signs a plain-text message with the selected wallet.
@@ -281,3 +343,84 @@ invalid signature
 
 This command expects the wallet address and signature directly, not paths to files containing them. The tool uses the selected wallet to authenticate the network lookup needed to retrieve the public key for the address being checked.
 
+## lookup_local_balance
+
+Reads a local balance file from disk and prints the stored balance as a decimal value.
+
+This is a low-level local inspection tool. It does not ask a node for current wallet state, does not include mempool changes, and does not prove that the value is the current network balance. It simply decodes the first 8 bytes of a local balance file as a little-endian `u64`.
+
+Usage:
+
+```text
+lookup_local_balance <path/to/file.bal>
+```
+
+Interactive prompt:
+
+```text
+Please enter the path to the balance file:
+```
+
+When entering the path interactively, press `<Tab>` to search and auto-complete files and folders.
+
+Expected output:
+
+```json
+{
+  "balance": "123.45678900"
+}
+```
+
+Use this mainly for debugging or manually inspecting local balance-sheet files.
+
+## lookup_remote_balance
+
+Asks a configured node for all known asset balances for one wallet address.
+
+Unlike `lookup_local_balance`, this is a network lookup. It contacts a peer, authenticates with the selected wallet, resolves short/long/vanity address input, and returns balances for the requested address.
+
+Usage:
+
+```text
+lookup_remote_balance <address_file>
+```
+
+Interactive prompts:
+
+```text
+Please enter the path to the file containing the wallet address:
+Please enter the path to your wallet file:
+What is your wallet decryption key?
+```
+
+The address file may contain either:
+
+- a plain wallet address
+- a wallet JSON file containing `short_address` or `vanity_address`
+
+When entering file paths interactively, press `<Tab>` to search and auto-complete files and folders.
+
+Expected output:
+
+```json
+{
+  "balances": [
+    {
+      "asset": "CLTC",
+      "nft_series": 0,
+      "balance": "100.00000000"
+    },
+    {
+      "asset": "testcoin",
+      "nft_series": 0,
+      "balance": "25.00000000"
+    }
+  ]
+}
+```
+
+`asset` is the base coin, token, or NFT asset name.
+
+`nft_series` is `0` for normal base-coin/token balances and 1-of-1 NFTs. For numbered NFT collections, it identifies the numbered item.
+
+`balance` is displayed with 8 decimal places.