feat(contract): add notification category metadata to events

Off-chain consumers could not selectively subscribe to specific
notification categories because every event looked the same beyond its
name. This adds a NotificationCategory (Group / Admin / Financial)
published as a trailing, indexed topic on every emitted event so
listeners and indexers can filter by category without decoding payloads.

- Introduce NotificationCategory enum in base::events.
- Attach the category as the last topic of every contract event.
- Keep the change backward compatible: the event name remains the first
  topic and all pre-existing topics/data keep their positions; the new
  category topic is simply appended and ignored by existing listeners.
- Add tests covering each category and a subscriber that filters by type.

Author: shaaibu7

contract/contracts/hello-world/src/autoshare_logic.rs

@@ -1,7 +1,7 @@
 use crate::base::errors::Error;
 use crate::base::events::{
     AdminTransferred, AutoshareCreated, AutoshareUpdated, ContractPaused, ContractUnpaused,
-    GroupActivated, GroupDeactivated, Withdrawal,
+    GroupActivated, GroupDeactivated, NotificationCategory, Withdrawal,
 };
 use crate::base::types::{AutoShareDetails, GroupMember, PaymentHistory};
 use soroban_sdk::{contracttype, token, Address, BytesN, Env, String, Vec};
@@ -108,6 +108,7 @@ pub fn create_autoshare(
 
     AutoshareCreated {
         creator: creator.clone(),
+        category: NotificationCategory::Group,
         id: id.clone(),
     }
     .publish(&env);
@@ -275,6 +276,7 @@ pub fn transfer_admin(env: Env, current_admin: Address, new_admin: Address) -> R
     env.storage().persistent().set(&DataKey::Admin, &new_admin);
     AdminTransferred {
         old_admin: current_admin,
+        category: NotificationCategory::Admin,
         new_admin,
     }
     .publish(&env);
@@ -297,7 +299,10 @@ pub fn pause(env: Env, admin: Address) -> Result<(), Error> {
     }
 
     env.storage().persistent().set(&pause_key, &true);
-    ContractPaused {}.publish(&env);
+    ContractPaused {
+        category: NotificationCategory::Admin,
+    }
+    .publish(&env);
     Ok(())
 }
 
@@ -313,7 +318,10 @@ pub fn unpause(env: Env, admin: Address) -> Result<(), Error> {
     }
 
     env.storage().persistent().set(&pause_key, &false);
-    ContractUnpaused {}.publish(&env);
+    ContractUnpaused {
+        category: NotificationCategory::Admin,
+    }
+    .publish(&env);
     Ok(())
 }
 
@@ -646,8 +654,9 @@ pub fn update_members(
     env.storage().persistent().set(&members_key, &new_members);
 
     AutoshareUpdated {
-        id: id.clone(),
         updater: caller,
+        category: NotificationCategory::Group,
+        id: id.clone(),
     }
     .publish(&env);
     Ok(())
@@ -680,8 +689,9 @@ pub fn deactivate_group(env: Env, id: BytesN<32>, caller: Address) -> Result<(),
     env.storage().persistent().set(&key, &details);
 
     GroupDeactivated {
-        id: id.clone(),
         creator: caller,
+        category: NotificationCategory::Group,
+        id: id.clone(),
     }
     .publish(&env);
     Ok(())
@@ -714,8 +724,9 @@ pub fn activate_group(env: Env, id: BytesN<32>, caller: Address) -> Result<(), E
     env.storage().persistent().set(&key, &details);
 
     GroupActivated {
-        id: id.clone(),
         creator: caller,
+        category: NotificationCategory::Group,
+        id: id.clone(),
     }
     .publish(&env);
     Ok(())
@@ -761,8 +772,9 @@ pub fn withdraw(
 
     Withdrawal {
         token,
-        amount,
         recipient,
+        category: NotificationCategory::Financial,
+        amount,
     }
     .publish(&env);
     Ok(())

contract/contracts/hello-world/src/base/events.rs

@@ -1,30 +1,65 @@
-use soroban_sdk::{contractevent, Address, BytesN};
+use soroban_sdk::{contractevent, contracttype, Address, BytesN};
+
+/// High-level notification category attached to every emitted event.
+///
+/// Off-chain consumers (listeners, indexers, dashboards) often only care about a
+/// subset of the events the contract emits. Each event carries its category as a
+/// trailing, indexed event topic so consumers can subscribe to — or filter out —
+/// whole categories without having to decode the event payload first.
+///
+/// # Backward compatibility
+///
+/// The category is published as the *last* topic of every event, after the event
+/// name and any pre-existing topics. Existing listeners that read the event name
+/// (the first topic) and the previously defined topics/data are unaffected: the
+/// extra trailing topic is simply ignored by consumers that don't look for it.
+#[contracttype]
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum NotificationCategory {
+    /// Lifecycle changes to AutoShare groups: created, updated, activated,
+    /// deactivated.
+    Group = 0,
+    /// Administrative / system actions: pause, unpause, admin transfer.
+    Admin = 1,
+    /// Movement of funds: withdrawals.
+    Financial = 2,
+}
 
 /// Emitted when a new AutoShare group is created.
 #[contractevent(data_format = "single-value")]
 #[derive(Clone)]
 pub struct AutoshareCreated {
     #[topic]
     pub creator: Address,
+    #[topic]
+    pub category: NotificationCategory,
     pub id: BytesN<32>,
 }
 
 /// Emitted when the contract is paused by the admin.
 #[contractevent]
 #[derive(Clone)]
-pub struct ContractPaused {}
+pub struct ContractPaused {
+    #[topic]
+    pub category: NotificationCategory,
+}
 
 /// Emitted when the contract is unpaused by the admin.
 #[contractevent]
 #[derive(Clone)]
-pub struct ContractUnpaused {}
+pub struct ContractUnpaused {
+    #[topic]
+    pub category: NotificationCategory,
+}
 
 /// Emitted when an AutoShare group's member list is updated.
 #[contractevent(data_format = "single-value")]
 #[derive(Clone)]
 pub struct AutoshareUpdated {
     #[topic]
     pub updater: Address,
+    #[topic]
+    pub category: NotificationCategory,
     pub id: BytesN<32>,
 }
 
@@ -34,6 +69,8 @@ pub struct AutoshareUpdated {
 pub struct GroupDeactivated {
     #[topic]
     pub creator: Address,
+    #[topic]
+    pub category: NotificationCategory,
     pub id: BytesN<32>,
 }
 
@@ -43,6 +80,8 @@ pub struct GroupDeactivated {
 pub struct GroupActivated {
     #[topic]
     pub creator: Address,
+    #[topic]
+    pub category: NotificationCategory,
     pub id: BytesN<32>,
 }
 
@@ -52,6 +91,8 @@ pub struct GroupActivated {
 pub struct AdminTransferred {
     #[topic]
     pub old_admin: Address,
+    #[topic]
+    pub category: NotificationCategory,
     pub new_admin: Address,
 }
 
@@ -63,5 +104,7 @@ pub struct Withdrawal {
     pub token: Address,
     #[topic]
     pub recipient: Address,
+    #[topic]
+    pub category: NotificationCategory,
     pub amount: i128,
 }

contract/contracts/hello-world/src/lib.rs

@@ -256,4 +256,7 @@ mod tests {
 
     #[path = "../tests/test_utils_test.rs"]
     mod test_utils_test;
+
+    #[path = "../tests/notification_test.rs"]
+    mod notification_test;
 }