fix: align docs, wire admin tests, and remove unused soroban-token-sdk

CONTRIBUTING.md

@@ -18,7 +18,7 @@ It is responsible for:
 - **Payment splitting** — distribute a single payment across multiple recipients
 - **Dispute resolution** — allow a third-party resolver to adjudicate contested payments
 
-The contract source files have been cleared. You, as a contributor, will be building these modules from scratch by picking up open GitHub Issues.
+Core token primitives, escrow, and freeze modules are implemented and tested. Some modules (recurring payments, splitter, dispute) exist as draft files in `src/` but are not yet wired into the compiled crate. Contributors pick up open GitHub Issues to finish, extend, or expose these modules.
 
 ---
 
@@ -50,14 +50,26 @@ cd veritix-contract/veritixpay/contract/token
 
 ## Project Structure
 
-The repository is currently in a clean-slate state. Only `lib.rs` exists in `src/` — everything else will be built by contributors picking up issues.
-
 ```
 veritixpay/
 ├── contract/
 │   └── token/
 │       ├── src/
-│       │   └── lib.rs          # Entry point — start here
+│       │   ├── lib.rs              # Crate entry point — module declarations
+│       │   ├── contract.rs         # Public Soroban interface (VeritixToken)
+│       │   ├── admin.rs            # Admin storage and rotation
+│       │   ├── allowance.rs        # Spending approvals
+│       │   ├── balance.rs          # Ledger balance helpers
+│       │   ├── escrow.rs           # Escrow logic (compiled)
+│       │   ├── freeze.rs           # Account freeze/unfreeze (compiled)
+│       │   ├── metadata.rs         # Token metadata
+│       │   ├── storage_types.rs    # Shared DataKey enum and structs
+│       │   ├── test.rs             # Compiled unit tests
+│       │   ├── escrow_test.rs      # Escrow-specific tests (compiled)
+│       │   ├── admin_test.rs       # Admin rotation tests (compiled)
+│       │   ├── recurring.rs        # Draft — not yet declared in lib.rs
+│       │   ├── splitter.rs         # Draft — not yet declared in lib.rs
+│       │   └── dispute.rs          # Draft — not yet declared in lib.rs
 │       ├── Cargo.toml
 │       └── Makefile
 ├── Cargo.toml
@@ -66,7 +78,7 @@ veritixpay/
 └── README.md
 ```
 
-Each module (escrow, splitter, dispute, etc.) will live as its own `.rs` file inside `src/` and be declared in `lib.rs`. You will be building these out one issue at a time.
+Each compiled module is declared in `lib.rs` with `pub mod module_name;`. Draft files exist on disk but are **not** declared in `lib.rs` and are therefore not compiled or tested until a contributor wires them in.
 
 ---
 
@@ -147,6 +159,8 @@ Run only your tests:
 cargo test your_feature
 ```
 
+> **Compiled vs. dormant test files:** Only test modules declared in `lib.rs` under `#[cfg(test)]` are compiled and run by `cargo test`. A test file that exists in `src/` but is not declared in `lib.rs` is silently ignored by the compiler. When adding a new `*_test.rs` file, always add the corresponding `#[cfg(test)] mod your_test;` line to `lib.rs`.
+
 ---
 
 ## Storage Conventions

README.md

@@ -17,7 +17,7 @@ The contract handles **token transfers**, **escrow for ticket purchases**, **rec
 
 Escrowed funds are held temporarily on the contract's own ledger balance. When an escrow is created, tokens move from the depositor into the contract address, stay there while the escrow is unresolved, and move back out only on release or refund. This means the contract address can hold a real token balance during escrow flows without increasing total supply.
 
-This project is currently being built in the open. The contract source files have been cleared and contributors can claim open GitHub Issues to build individual modules from scratch. If you want to contribute to a real Soroban project, this is a great place to start — see the [Contributing](#contributing) section below.
+This project is actively being built in the open. Core token primitives, escrow logic, recurring payments, splitting, and dispute resolution are implemented and tested. Some draft modules exist in `src/` but are not yet wired into the crate. Contributors can claim open GitHub Issues to extend and improve existing modules. See the [Contributing](#contributing) section below.
 
 ---
 
@@ -30,20 +30,23 @@ This project is currently being built in the open. The contract source files hav
 
 ---
 
-## Contract Modules (Planned)
+## Contract Modules
 
-These modules will be built by contributors picking up open issues. The entry point is `src/lib.rs`.
+The entry point is `veritixpay/contract/token/src/lib.rs`. Modules compiled into the crate are listed below.
 
 | Module | File | Status | Description |
 |--------|------|--------|-------------|
-| Token Core | `contract.rs` | 🔜 Open | Mint, burn, transfer, approve |
-| Escrow | `escrow.rs` | 🔜 Open | Create, release, and refund escrow holds |
-| Recurring Payments | `recurring.rs` | 🔜 Open | Set up and execute recurring charges |
-| Payment Splitter | `splitter.rs` | 🔜 Open | Split a payment between multiple parties |
-| Dispute Resolution | `dispute.rs` | 🔜 Open | Open and resolve payment disputes |
-| Admin | `admin.rs` | 🔜 Open | Admin address controls |
-| Storage Types | `storage_types.rs` | 🔜 Open | Shared `DataKey` enum and struct definitions |
-| Tests | `test.rs` | 🔜 Open | Unit test suite |
+| Token Core | `contract.rs` | Compiled | Mint, burn, transfer, approve, clawback, freeze |
+| Admin | `admin.rs` | Compiled | Admin address controls and rotation |
+| Allowance | `allowance.rs` | Compiled | Third-party spending approvals |
+| Balance | `balance.rs` | Compiled | Ledger balance reads/writes |
+| Escrow | `escrow.rs` | Compiled | Create, release, and refund escrow holds |
+| Freeze | `freeze.rs` | Compiled | Regulatory account blocking |
+| Metadata | `metadata.rs` | Compiled | Token name, symbol, decimals |
+| Storage Types | `storage_types.rs` | Compiled | Shared `DataKey` enum and struct definitions |
+| Recurring Payments | `recurring.rs` | Draft | Set up and execute recurring charges (not yet exposed in `contract.rs`) |
+| Payment Splitter | `splitter.rs` | Draft | Split a payment between multiple parties (not yet exposed in `contract.rs`) |
+| Dispute Resolution | `dispute.rs` | Draft | Open and resolve payment disputes (not yet exposed in `contract.rs`) |
 
 ---
 
@@ -70,24 +73,35 @@ stellar --version
 git clone https://github.com/Lead-Studios/veritix-contract.git
 cd veritix-contract/veritixpay/contract/token
 
-make build    # compile to WASM
+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`.
+
 ---
 
 ## Project Structure
 
-The repository is in a clean-slate state. Only `lib.rs` exists in `src/` — contributors will build out the modules by picking up issues.
-
 ```
 veritixpay/
 ├── contract/
 │   └── token/
 │       ├── src/
-│       │   └── lib.rs          # Entry point — start here
+│       │   ├── lib.rs              # Crate entry point — module declarations
+│       │   ├── contract.rs         # Public Soroban interface (VeritixToken)
+│       │   ├── admin.rs            # Admin storage and rotation
+│       │   ├── allowance.rs        # Spending approvals
+│       │   ├── balance.rs          # Ledger balance helpers
+│       │   ├── escrow.rs           # Escrow logic
+│       │   ├── freeze.rs           # Account freeze/unfreeze
+│       │   ├── metadata.rs         # Token metadata
+│       │   ├── storage_types.rs    # Shared DataKey enum and structs
+│       │   ├── test.rs             # Compiled unit tests
+│       │   ├── escrow_test.rs      # Escrow-specific tests
+│       │   └── admin_test.rs       # Admin rotation tests
 │       ├── Cargo.toml
 │       └── Makefile
 ├── Cargo.toml

veritixpay/Cargo.toml

@@ -7,7 +7,6 @@ members = [
 
 [workspace.dependencies]
 soroban-sdk = "20.5.0"
-soroban-token-sdk = "20.5.0"
 
 [profile.release]
 opt-level = "z"

veritixpay/README.md

@@ -65,7 +65,9 @@ Security is enforced natively using the Soroban SDK. Every state-changing functi
 2. Create your logic file (e.g., `new_feature.rs`) and implement the core functions.
 3. Expose the necessary interface methods in `contract.rs`.
 4. Register the module by adding `pub mod new_feature;` to `lib.rs`.
-5. Create a corresponding `new_feature_test.rs` file to ensure 100% test coverage.
+5. Create a corresponding `new_feature_test.rs` file and add `#[cfg(test)] mod new_feature_test;` to `lib.rs` so it is compiled by `cargo test`.
+
+> **Note:** A test file in `src/` that is not declared in `lib.rs` is silently ignored. Always wire both the module and its test file through `lib.rs`.
 
 ## Links
 * [Back to Root README](../README.md)

veritixpay/contract/token/Cargo.toml

@@ -10,7 +10,6 @@ doctest = false
 
 [dependencies]
 soroban-sdk = { workspace = true }
-soroban-token-sdk = { workspace = true }
 
 [dev-dependencies]
 soroban-sdk = { workspace = true, features = ["testutils"] }

veritixpay/contract/token/src/admin_test.rs

@@ -1,30 +1,34 @@
-#[test]
-fn test_transfer_admin() {
-    let e = Env::default();
-    let admin = Address::generate(&e);
-    let new_admin = Address::generate(&e);
-
-    // Initialize with first admin
-    write_admin(&e, &admin);
-
-    // Perform transfer (requires admin's mock auth in test environment)
-    e.mock_all_auths();
-    transfer_admin(&e, new_admin.clone());
-
-    assert_eq!(read_admin(&e), new_admin);
-}
-
-#[test]
-#[should_panic]
-fn test_transfer_admin_unauthorized_panics() {
-    let e = Env::default();
-    let admin = Address::generate(&e);
-    let hacker = Address::generate(&e);
-    let new_admin = Address::generate(&e);
-
-    write_admin(&e, &admin);
-
-    // This should panic because hacker is calling it, not the current admin
-    e.set_auths(&[]); // Ensure no mock auths bypass the check
-    transfer_admin(&e, new_admin);
+#[cfg(test)]
+mod admin_test {
+    use soroban_sdk::{testutils::Address as _, Address, Env};
+
+    use crate::admin::{read_admin, transfer_admin, write_admin};
+
+    #[test]
+    fn test_transfer_admin() {
+        let e = Env::default();
+        let admin = Address::generate(&e);
+        let new_admin = Address::generate(&e);
+
+        write_admin(&e, &admin);
+
+        e.mock_all_auths();
+        transfer_admin(&e, new_admin.clone());
+
+        assert_eq!(read_admin(&e), new_admin);
+    }
+
+    #[test]
+    #[should_panic]
+    fn test_transfer_admin_unauthorized_panics() {
+        let e = Env::default();
+        let admin = Address::generate(&e);
+        let new_admin = Address::generate(&e);
+
+        write_admin(&e, &admin);
+
+        // No mock auths — transfer_admin requires the current admin to authorize
+        e.set_auths(&[]);
+        transfer_admin(&e, new_admin);
+    }
 }

veritixpay/contract/token/src/lib.rs

@@ -20,4 +20,7 @@ mod test;
 #[cfg(test)]
 mod escrow_test;
 
+#[cfg(test)]
+mod admin_test;
+
 pub use crate::contract::VeritixToken;