feat: standardize token event schemas and add Makefile preflight target

CONTRIBUTING.md

@@ -37,6 +37,8 @@ rustc --version
 stellar --version
 ```
 
+**First-time setup:** Run `make preflight` from the `veritixpay/contract/token/` directory to verify all required tools are installed. This will give you fast, actionable feedback if anything is missing.
+
 ---
 
 ## Getting the Code
@@ -113,6 +115,7 @@ If you have an idea not covered by an existing issue, open one first and describ
 All commands run from inside `veritixpay/contract/token/`:
 
 ```bash
+make preflight  # verify all required tools are installed
 make build    # compile the contract to WASM
 make test     # run the full test suite
 make fmt      # format all Rust code with rustfmt

README.md

@@ -73,13 +73,14 @@ stellar --version
 git clone https://github.com/Lead-Studios/veritix-contract.git
 cd veritix-contract/veritixpay/contract/token
 
+make preflight  # verify all required tools are installed
 make build    # compile to WASM (requires stellar CLI)
 make test     # run tests
 make fmt      # format code
 make clean    # remove build artifacts
 ```
 
-> **Note:** `make build` uses `stellar contract build` under the hood. Install the Stellar CLI with `cargo install stellar-cli`.
+> **Note:** Run `make preflight` first to verify your setup. It checks for stellar CLI, Rust, and the wasm32-unknown-unknown target.
 
 ---
 

veritixpay/contract/token/Makefile

@@ -2,6 +2,17 @@ default: build
 
 all: test
 
+# Check for required tools and Rust targets
+preflight:
+	@echo "Checking prerequisites..."
+	@which stellar > /dev/null 2>&1 || (echo "❌ stellar CLI not found. Install with: cargo install stellar-cli" && exit 1)
+	@echo "✓ stellar CLI found"
+	@rustup target list --installed | grep -q wasm32-unknown-unknown || (echo "❌ wasm32-unknown-unknown target not installed. Install with: rustup target add wasm32-unknown-unknown" && exit 1)
+	@echo "✓ wasm32-unknown-unknown target installed"
+	@which cargo > /dev/null 2>&1 || (echo "❌ cargo not found. Install Rust from: https://rustup.rs" && exit 1)
+	@echo "✓ cargo found"
+	@echo "✅ All prerequisites met!"
+
 test: build
 	cargo test
 

veritixpay/contract/token/src/contract.rs

@@ -61,7 +61,7 @@ impl VeritixToken {
 
         // Emit transparency event
         e.events()
-            .publish((symbol_short!("clawback"), from), amount);
+            .publish((symbol_short!("clawback"), admin, from), amount);
     }
 
     // --- Freeze controls ---
@@ -86,7 +86,7 @@ impl VeritixToken {
         require_positive_amount(amount);
         receive_balance(&e, to.clone(), amount);
         increase_supply(&e, amount);
-        e.events().publish((symbol_short!("mint"), to), amount);
+        e.events().publish((symbol_short!("mint"), admin, to), amount);
     }
 
     /// Caller burns their own tokens.
@@ -108,7 +108,7 @@ impl VeritixToken {
         spend_allowance(&e, from.clone(), spender.clone(), amount);
         spend_balance(&e, from.clone(), amount);
         decrease_supply(&e, amount);
-        e.events().publish((symbol_short!("burn"), from), amount);
+        e.events().publish((symbol_short!("burn"), spender, from), amount);
     }
 
     // --- Transfers & allowance ---

veritixpay/contract/token/src/dispute.rs

@@ -1,7 +1,7 @@
 use crate::balance::{receive_balance, spend_balance};
 use crate::escrow::get_escrow;
 use crate::storage_types::{increment_counter, write_persistent_record, DataKey};
-use soroban_sdk::{contracttype, Address, Env, Symbol};
+use soroban_sdk::{contracttype, symbol_short, Address, Env, Symbol};
 
 #[contracttype]
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -53,8 +53,8 @@ pub fn open_dispute(
     e.storage().persistent().set(&DataKey::Dispute(count), &record);
 
     e.events().publish(
-        (Symbol::new(e, "dispute"), Symbol::new(e, "opened"), escrow_id),
-        claimant,
+        (symbol_short!("dispute_opened"), escrow_id, claimant.clone()),
+        (),
     );
 
     count
@@ -75,17 +75,17 @@ fn settle_escrow_by_outcome(e: &Env, escrow_id: u32, release_to_beneficiary: boo
         spend_balance(e, e.current_contract_address(), escrow.amount);
         receive_balance(e, escrow.beneficiary.clone(), escrow.amount);
         e.events().publish(
-            (Symbol::new(e, "escrow"), Symbol::new(e, "released"), escrow_id),
-            escrow.beneficiary,
+            (symbol_short!("escrow_released"), escrow_id, escrow.beneficiary.clone()),
+            escrow.amount,
         );
     } else {
         escrow.refunded = true;
         write_persistent_record(e, &DataKey::Escrow(escrow_id), &escrow);
         spend_balance(e, e.current_contract_address(), escrow.amount);
         receive_balance(e, escrow.depositor.clone(), escrow.amount);
         e.events().publish(
-            (Symbol::new(e, "escrow"), Symbol::new(e, "refunded"), escrow_id),
-            escrow.depositor,
+            (symbol_short!("escrow_refunded"), escrow_id, escrow.depositor.clone()),
+            escrow.amount,
         );
     }
 }
@@ -125,7 +125,7 @@ pub fn resolve_dispute(
     e.storage().persistent().set(&DataKey::Dispute(dispute_id), &dispute);
 
     e.events().publish(
-        (Symbol::new(e, "dispute"), Symbol::new(e, "resolved"), dispute_id),
+        (symbol_short!("dispute_resolved"), dispute_id, resolver),
         release_to_beneficiary,
     );
 }

veritixpay/contract/token/src/escrow.rs

@@ -3,7 +3,7 @@ use crate::storage_types::{
     increment_counter, read_persistent_record, write_persistent_record, DataKey,
 };
 use crate::validation::require_positive_amount;
-use soroban_sdk::{contracttype, Address, Env, Symbol};
+use soroban_sdk::{contracttype, symbol_short, Address, Env, Symbol};
 
 #[contracttype]
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -44,12 +44,8 @@ pub fn create_escrow(e: &Env, depositor: Address, beneficiary: Address, amount:
 
     // Optional observability event
     e.events().publish(
-        (
-            Symbol::new(e, "escrow"),
-            Symbol::new(e, "created"),
-            depositor,
-        ),
-        (beneficiary, amount),
+        (symbol_short!("escrow_created"), depositor.clone(), beneficiary.clone()),
+        amount,
     );
 
     count
@@ -86,12 +82,8 @@ pub fn try_release_escrow(e: &Env, caller: Address, escrow_id: u32) -> Result<()
 
     // Event for observability
     e.events().publish(
-        (
-            Symbol::new(e, "escrow"),
-            Symbol::new(e, "released"),
-            escrow_id,
-        ),
-        escrow.beneficiary,
+        (symbol_short!("escrow_released"), escrow_id, escrow.beneficiary.clone()),
+        escrow.amount,
     );
 
     Ok(())
@@ -128,12 +120,8 @@ pub fn try_refund_escrow(e: &Env, caller: Address, escrow_id: u32) -> Result<(),
 
     // Event for observability
     e.events().publish(
-        (
-            Symbol::new(e, "escrow"),
-            Symbol::new(e, "refunded"),
-            escrow_id,
-        ),
-        escrow.depositor,
+        (symbol_short!("escrow_refunded"), escrow_id, escrow.depositor.clone()),
+        escrow.amount,
     );
 
     Ok(())