feat: vault upgrade lifecycle events

[gaiabio12-design]

Summary

• New module `contracts/vault/src/upgrade.rs`: defines `UpgradeStartedData { new_wasm_hash, previous_version }` and `UpgradeCompletedData { new_wasm_hash }` as `#[contracttype]` structs.
• `upgrade_started` event emitted before `env.deployer().update_current_contract_wasm()` — carries the intended hash plus `previous_version: Option<BytesN<32>>` (None on first upgrade, the previous hash on subsequent ones). Lets indexers detect failed upgrades: no matching `upgrade_completed` = swap didn't complete.
• `upgrade_completed` event emitted after the WASM swap succeeds — confirms the deployment took effect.
• `upgraded` event retained for backward compatibility with indexers already parsing it.
• `events.rs`: two new symbol constructors (`event_upgrade_started`, `event_upgrade_completed`) with byte-identity snapshot tests.
• `EVENT_SCHEMA.md`: documents all three events with full topic/data tables, JSON examples, and indexer guidance including the `upgrade_started -> upgrade_completed -> upgraded` ordering guarantee.

Test plan

• `upgrade_emits_all_three_lifecycle_events` — all three events present after a single upgrade call
• `upgrade_started_precedes_upgrade_completed` — ordering: started < completed < upgraded
• `upgrade_started_topic_includes_caller` — topic 1 is the admin address
• `upgrade_completed_topic_includes_caller` — topic 1 is the admin address
• `upgrade_started_data_first_upgrade_has_no_previous_version` — `previous_version` is None on first upgrade
• `upgrade_started_data_second_upgrade_has_previous_version` — second upgrade carries first hash as `previous_version`
• `upgrade_completed_data_contains_new_hash` — data payload matches the installed hash
• Snapshot tests for `event_upgrade_started` and `event_upgrade_completed` byte identity
• All pre-existing upgrade tests still pass (no regressions)

Closes #528

[gaiabio12-design]

CI failures are pre-existing on main, not introduced by this PR.

The compile errors (__broadcast defined multiple times, duplicate definitions with name 'broadcast') originate from two pub fn broadcast implementations already present in contracts/vault/src/lib.rs lines 1471 and 1628 — both existed before this branch was cut. This same failure appears on the main branch run immediately before our PR was opened: run IDs 28292295694 (CI), 28292295699 (Test Coverage), 28292295713 (WASM Size Budget).

Our change (upgrade.rs + lifecycle events) compiles and is orthogonal to the broadcast duplication bug.

[greatest0fallt1me]

This PR is being closed as invalid.

To raise a PR, please first comment on the issue you want to work on and wait to be assigned. Once you're assigned to the issue, open a fresh PR (linking it with Closes #N) — or reopen this one.

This keeps the contributor workflow predictable for everyone working on the GrantFox campaign. Thanks!

[gaiabio12-design]

CI status — pre-existing failures vs. our changes

After four commits on this branch I want to be transparent about what's failing and why.

What this PR fixed (were already broken on main)

Error	Location	Status
error[E0428]: __broadcast defined multiple times	vault/src/lib.rs	✅ Fixed in 2fa20fe
cannot find type Severity / String / AdminBroadcast	settlement/src/lib.rs	✅ Fixed in 028e46e
cannot find value MAX_MESSAGE_LEN	settlement/src/lib.rs	✅ Fixed in 028e46e
cannot find attribute contracterror	vault/src/lib.rs	✅ Fixed in 028e46e
contracterror import out of alphabetical order	vault/src/lib.rs:31	✅ Fixed in aaa4af3

Remaining failures — all pre-existing on main (CI run 28292295694 / 28292295713)

Error	Job	Pre-existing on main?
Val: TryFromVal<Env, u16> — deduct(max_fee_bps: u16) in vault	WASM Build	✅ Yes (run 28292295713)
Box not found in this scope — proptest + #![no_std] nightly	Test (Nightly)	✅ Yes
cargo fmt --check diffs in vault, settlement, revenue_pool	Test (Stable)	✅ Yes (run 28292295694)

The u16 WASM error was introduced by PR #519 (max_fee_bps: u16 slippage feature) which merged before us; soroban_sdk v22 doesn't implement TryFromVal for u16. Fixing it would require changing u16 → u32 or a wrapper type in deduct — that's outside the scope of this issue but worth tracking separately.

Happy to address anything in scope. Let me know if you'd like a fix for the u16 type as well.