feat(admin): add verify_admin_handover() helper with typed error

[morelucks]

Summary

Implements issue #1587. Adds AdminStorage::verify_admin_handover(env, proposed) — a pure, read-only pre-flight guard that returns a typed OperationNotAllowed error when the proposed new admin address is identical to the current admin.

Motivation

Previously, callers had no clean way to detect a same-address handover before committing the full transfer_admin call. The only feedback was an ambiguous OperationNotAllowed that is also returned for other failure modes (uninitialized, transfer locked). This forced:

• Frontend / off-chain clients to implement their own equality check.
• Downstream contracts to attempt the transfer and handle a generic error.
• Support to diagnose failures from opaque error codes.

verify_admin_handover provides one well-named entry point that makes the identity violation explicit and documentable.

Changes

quicklendx-contracts/src/admin.rs

New public function added to the second impl AdminStorage block:

pub fn verify_admin_handover(env: &Env, proposed: &Address) -> Result<(), QuickLendXError>

Condition	Return
Admin not initialized	Err(OperationNotAllowed)
proposed == current admin	Err(OperationNotAllowed)
proposed != current admin	Ok(())

The function is read-only: no storage writes, no auth calls, no events emitted.

quicklendx-contracts/src/test_admin_handover.rs (new)

9 deterministic tests covering:

• proposed == current → error
• proposed != current → ok
• called before init → error
• multiple unrelated addresses → all pass
• idempotent: no state mutated (admin, lock, pending all unchanged)
• transfer_admin self-transfer still rejected (no existing guard removed)
• transfer_admin with valid candidate still succeeds (no regression)
• two-step self-target still rejected
• full two-step flow with valid candidate still works

quicklendx-contracts/src/lib.rs

Registered mod test_admin_handover with plain #[cfg(test)] — always-on, runs on every CI matrix entry.

docs/contracts/admin.md

New section documents the helper: purpose, signature, behaviour table, properties (read-only, idempotent, composable), usage example, and a note clarifying the helper is additive and does not remove existing guards.

Backwards compatibility

Fully backwards-compatible. The helper is additive. All existing transfer paths retain their own guards unchanged.

Testing

# New tests only (once pre-existing compile errors are resolved)
cargo test -p quicklendx-contracts test_admin_handover

# Full suite
cargo test -p quicklendx-contracts

# Lint
cargo clippy --workspace --all-targets -- -D warnings

# WASM verification
cargo build --target wasm32-unknown-unknown --release

Note: The codebase currently has 22 pre-existing compile errors in unrelated files (verification.rs, types.rs, lib.rs:3289, test_invoice_search_ranking.rs). None are introduced by this PR; they affect the full test suite and need a separate fix.

Closes #1587

[drips-wave]

@morelucks Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Baskarayelu]

add verify_admin_handover() helper with typed error — nice work, merging 👍