feat(vault-contract): add view functions, events, and ROI

apps/smart-contracts/contracts/vault-contract/src/events.rs

@@ -0,0 +1,44 @@
+use soroban_sdk::{contracttype, Address, Env};
+
+/// Event emitted when a beneficiary successfully claims their ROI.
+/// This enables indexers and explorers to track claim activity.
+#[contracttype]
+#[derive(Clone, Debug)]
+pub struct ClaimEvent {
+    /// The address that claimed the ROI
+    pub beneficiary: Address,
+    /// Amount of participation tokens redeemed
+    pub tokens_redeemed: i128,
+    /// Amount of USDC received (including ROI)
+    pub usdc_received: i128,
+    /// The ROI percentage at the time of claim
+    pub roi_percentage: i128,
+}
+
+/// Event emitted when the vault availability is changed by admin.
+#[contracttype]
+#[derive(Clone, Debug)]
+pub struct AvailabilityChangedEvent {
+    /// The admin who made the change
+    pub admin: Address,
+    /// The new enabled status
+    pub enabled: bool,
+}
+
+/// Helper functions for publishing events
+pub mod events {
+    use super::*;
+    use soroban_sdk::symbol_short;
+
+    /// Publishes a ClaimEvent to the blockchain event log.
+    pub fn emit_claim(env: &Env, event: ClaimEvent) {
+        env.events()
+            .publish((symbol_short!("claim"),), event);
+    }
+
+    /// Publishes an AvailabilityChangedEvent to the blockchain event log.
+    pub fn emit_availability_changed(env: &Env, event: AvailabilityChangedEvent) {
+        env.events()
+            .publish((symbol_short!("avail"),), event);
+    }
+}

apps/smart-contracts/contracts/vault-contract/src/lib.rs

@@ -1,10 +1,14 @@
 #![no_std]
 
 mod error;
+mod events;
+mod storage_types;
 mod vault;
 
 pub use crate::error::ContractError;
-pub use crate::vault::VaultContract;
+pub use crate::events::{AvailabilityChangedEvent, ClaimEvent};
+pub use crate::storage_types::DataKey;
+pub use crate::vault::{ClaimPreview, VaultContract, VaultOverview};
 
 #[cfg(test)]
-mod test;
+mod test;

apps/smart-contracts/contracts/vault-contract/src/storage_types.rs

@@ -0,0 +1,20 @@
+use soroban_sdk::contracttype;
+
+/// Typed storage keys for the vault contract.
+/// Using an enum instead of raw strings improves type safety and readability.
+#[derive(Clone)]
+#[contracttype]
+pub enum DataKey {
+    /// The admin address that can enable/disable the vault
+    Admin,
+    /// Whether claiming is currently enabled
+    Enabled,
+    /// The ROI percentage (e.g., 5 means 5% return)
+    RoiPercentage,
+    /// The participation token contract address
+    TokenAddress,
+    /// The USDC stablecoin contract address
+    UsdcAddress,
+    /// Total tokens that have been redeemed through the vault
+    TotalTokensRedeemed,
+}