[Observability] Standardize Event Schema with Versioning, Correlation IDs, and Full Names

[KarenZita01]

Description

The contract's event system emits events for significant state changes (DustColl, Routed, YeldFail, GasBufIn, GasBufTp, GasBufWd, GDepLock, GDepSlshed, DebtSettl, ClwbkStr, ClwbkRec, FeeSet, VaultSet, ThreshSet), but there is no standardized event schema, no event versioning, and no backward compatibility guarantees. Events use symbol_short with truncated 4-character names that are cryptic for off-chain consumers. The security_analysis.rs (6.9KB) identifies some risks but is a standalone analysis file with no integration to the actual contract code.

Event-specific gaps:

• Event names are truncated to 4 characters (symbol_short!), making them unreadable
• No EventVersion field to allow schema evolution
• Events lack correlation IDs (can't link related events across multiple operations)
• security_analysis.rs findings are not tracked as issues or test cases
• No event filtering or indexing support for off-chain observers
• Same event structure used for both admin and user operations (no distinction)

Technical Context & Impact

• Affected Components/Files: contracts/utility_contracts/src/lib.rs (all env.events().publish() calls), contracts/utility_contracts/src/security_analysis.rs
• Impact: Observability, Off-Chain Integration, Auditing

Step-by-Step Implementation Guide

1. Define event schema convention: Create docs/event_schema.md with EventName(domain_action), required fields, and versioning
2. Implement EventBuilder helper: Create src/event_helper.rs with EventBuilder::new(domain: &str, action: &str) that constructs proper event names (>4 chars using full symbols)
3. Add event versioning: Include version: u32 in every event struct, starting at EVENT_VERSION_V1 = 1
4. Add correlation IDs: Add optional correlation_id: Option<BytesN<32>> to events, passed through from operation entry points
5. Differentiate event types: Use EventType::{Admin, User, System} enum tag in each event
6. Convert security analysis to tests: Move findings from security_analysis.rs into tests/security_test_cases.rs as executable test scenarios
7. Add event index hints: Include indexed_fields: Vec<Symbol> hint for Soroban event indexing

Verification & Testing Steps

1. Write integration test that captures all published events and validates them against schema
2. Verify event names are descriptive (not truncated to 4 chars)
3. Test event versioning: parse v1 events, verify version field is present and correct
4. Test correlation ID propagation: call multi-step operation and verify all events share correlation ID
5. Run full test suite: cargo test --package utility_contracts
6. Deploy to testnet and verify events appear correctly in Stellar Expert or similar block explorer