refactor: improve tx waiting, fees, and compatibility (#101)

* *Improves tx waiting, fees, and compatibility

*Clarifies transaction lifecycle handling so sends can return on submission by default or wait for inclusion or finalization, with more accurate status reporting and safer post-submit behavior.

*Improves transfer safety by parsing decimal amounts exactly, estimating fees before send and batch operations, and checking balances against amount, tip, and fee needs to avoid misleading success paths.

*Tightens compatibility checks to require matching runtime and transaction versions, updates regeneration guidance and usage docs, and removes wallet debug output while rejecting duplicate developer wallet creation.

* *fmt

* fix: address Nikolaus PR review comments

* *fix cargo audit issue

* *Improves transfer validation and address handling

*Centralizes balance and fee checks so single and batch transfers report shortages more consistently and avoid duplicated overflow logic.

*Adds shared address-to-account conversion for transfer and recovery commands, reducing repeated parsing code and keeping wallet-name resolution consistent.

*Refactors transaction status watching into smaller helpers for clearer success and failure handling, and separates finalization from the generic wait flag.

* *fmt

Author: ethan-crypto

Cargo.lock

@@ -98,7 +98,6 @@ qp-wormhole-circuit-builder = { version = "2.0.1" }
 
 [dev-dependencies]
 tempfile = "3.8.1"
-serial_test = "3.1"
 qp-poseidon-core = "1.4.0"
 
 # Optimize build scripts and their dependencies in dev mode.

Cargo.toml

@@ -8,7 +8,7 @@ This document explains how to use `quantus-cli` as a library in your Rust applic
 [dependencies]
 quantus-cli = { path = "." }  # For local development
 # or
-quantus-cli = "0.1.0"  # When published to crates.io
+quantus-cli = "1.3.3"  # Replace with the latest published version on crates.io
 ```
 
 ## Basic Usage
@@ -158,7 +158,7 @@ async fn query_balance() -> Result<(), Box<dyn std::error::Error>> {
     let storage_addr = api::storage().system().account(subxt_account_id);
     let account_info = client.client().storage().at(None).fetch_or_default(&storage_addr).await?;
 
-    println!("Balance: {} DEV", account_info.data.free);
+    println!("Balance (raw units): {}", account_info.data.free);
 
     Ok(())
 }
@@ -169,8 +169,9 @@ async fn query_balance() -> Result<(), Box<dyn std::error::Error>> {
 ```rust
 use quantus_cli::{
     chain::client::QuantusClient,
+    cli::common::ExecutionMode,
+    transfer,
     wallet::WalletManager,
-    AccountId32,
 };
 
 async fn send_transaction() -> Result<(), Box<dyn std::error::Error>> {
@@ -181,38 +182,36 @@ async fn send_transaction() -> Result<(), Box<dyn std::error::Error>> {
     let wallet_data = wallet_manager.load_wallet("my_wallet", "password")?;
     let keypair = wallet_data.keypair;
 
-    // Parse recipient address
+    // Recipient address
     let to_address = "qzkeicNBtW2AG2E7USjDcLzAL8d9WxTZnV2cbtXoDzWxzpHC2";
-    let to_account_id = AccountId32::from_ss58check(to_address)?;
-    
-    // Create transfer call
-    use quantus_cli::chain::quantus_subxt::api;
-    use subxt::tx::TxClient;
-    
-    let to_account_bytes: [u8; 32] = *to_account_id.as_ref();
-    let to_subxt_account_id = subxt::utils::AccountId32::from(to_account_bytes);
-    
-    let transfer_call = api::tx().balances().transfer(
-        to_subxt_account_id.into(),
-        1000000000000, // 1 DEV
-    );
-    
-    // Submit transaction
-    let tx_hash = client
-        .client()
-        .tx()
-        .sign_and_submit_then_watch_default(&transfer_call, &keypair)
-        .await?
-        .wait_for_finalized_success()
-        .await?
-        .extrinsic_hash();
+
+    // Submit and wait for inclusion in a best block
+    let tx_hash = transfer(
+        &client,
+        &keypair,
+        to_address,
+        1_000_000_000_000, // raw units, e.g. 1 token on a 12-decimal chain
+        None,
+        ExecutionMode {
+            wait_for_transaction: true,
+            finalized: false,
+        },
+    )
+    .await?;
 
     println!("Transaction hash: {:?}", tx_hash);
 
     Ok(())
 }
 ```
 
+Passing `None` for the tip means no tip is attached. Use `Some(raw_tip)` only when you explicitly want one.
+
+`ExecutionMode` semantics:
+- `wait_for_transaction = false`: return after submission (`submitted`)
+- `wait_for_transaction = true`: return after best-block inclusion (`included`)
+- `finalized = true`: return after finalization (`finalized`); this implies waiting
+
 ### Service Architecture
 
 For web services or applications that need to manage multiple wallets:

LIBRARY_USAGE.md

@@ -367,22 +367,35 @@ quantus wallet export --name my_wallet --format mnemonic
 ### Sending Tokens
 
 ```bash
-# Simple transfer
+# Simple transfer (default: submit and return once the node accepts the extrinsic)
 quantus send --from crystal_alice --to <address> --amount 10.5
 
-# With tip for priority
+# Wait for inclusion in a best block
+quantus send --from crystal_alice --to <address> --amount 10.5 --wait-for-transaction
+
+# Wait for finalization (implies --wait-for-transaction)
+quantus send --from crystal_alice --to <address> --amount 10.5 --finalized-tx
+
+# Optional advanced: add a tip to prioritize the transaction
 quantus send --from crystal_alice --to <address> --amount 10 --tip 0.1
 
 # With manual nonce
 quantus send --from crystal_alice --to <address> --amount 10 --nonce 42
 ```
 
+Transaction status terms:
+- `submitted`: accepted by the node, but not yet known to be in a block
+- `included`: observed in a best block
+- `finalized`: observed in a finalized block
+
+`--amount` and `--tip` use exact decimal parsing based on the chain's configured decimals. Malformed values, negative values, over-precision, or values that would round to zero are rejected. `--tip` is optional and omitted by default.
+
 ---
 
 ### Batch Transfers
 
 ```bash
-# From a JSON file
+# From a JSON file (amounts are raw smallest-unit integers)
 quantus batch send --from crystal_alice --batch-file transfers.json
 
 # Generate identical test transfers
@@ -509,7 +522,7 @@ quantus call \
 | `quantus system --runtime` | Runtime version details |
 | `quantus metadata --pallet Balances` | Explore chain metadata |
 | `quantus version` | CLI version |
-| `quantus compatibility-check` | Check CLI/node compatibility |
+| `quantus compatibility-check` | Check CLI/node spec-version and transaction-version compatibility |
 
 ---
 
@@ -820,12 +833,14 @@ The project includes a script to regenerate SubXT types and metadata when the bl
 1. **Updates metadata**: Downloads the latest chain metadata to `src/quantus_metadata.scale`
 2. **Generates types**: Creates type-safe Rust code in `src/chain/quantus_subxt.rs`
 3. **Formats code**: Automatically formats the generated code with `cargo fmt`
+4. **Prompts compatibility update**: Reminds you to update the supported runtime/transaction pair in `src/config/mod.rs`
 
 **When to use:**
 - After updating the Quantus runtime
 - When new pallets are added to the chain
 - When existing pallet APIs change
 - To ensure CLI compatibility with the latest chain version
+- Before updating the `quantus compatibility-check` allowlist
 
 **Requirements:**
 - `subxt-cli` must be installed: `cargo install subxt-cli`
@@ -849,7 +864,14 @@ Using node URL: ws://127.0.0.1:9944
 Updating metadata file at src/quantus_metadata.scale...
 Generating SubXT types to src/chain/quantus_subxt.rs...
 Formatting generated code...
+Reminder: update src/config/mod.rs with the new compatible spec/transaction version pair.
 Done!
 ```
 
-This ensures the CLI always has the latest type definitions and can interact with new chain features.
+After regeneration, re-run:
+
+```bash
+quantus compatibility-check --node-url <node>
+```
+
+The checked-in compatibility gate now requires both the runtime `spec_version` and `transaction_version` to match a supported pair.

README.md

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -euo pipefail
 
 # Default node URL
 NODE_URL="ws://127.0.0.1:9944"
@@ -32,6 +33,8 @@ echo "Generating SubXT types to src/chain/quantus_subxt.rs..."
 subxt codegen --url "$NODE_URL" > src/chain/quantus_subxt.rs
 
 echo "Formatting generated code..."
+# Generated SubXT code may require nightly rustfmt.
 cargo +nightly fmt -- src/chain/quantus_subxt.rs
 
-echo "Done!"
+echo "Reminder: update src/config/mod.rs with the new compatible spec/transaction version pair."
+echo "Done!"