feat: event type filtering, batch notifications, audit logging

- Add NotificationCategory and NotificationPriority as trailing topics
  on all emitted events so off-chain consumers can filter by type
- Add batch_schedule_notifications: create up to 50 notifications in a
  single transaction with all-or-nothing validation and a summary event
- Add AuditRecord type and append-only on-chain audit log tracking the
  full notification lifecycle (created, delivery attempt, delivery
  failed, acknowledged, cancelled, expired)
- Add query endpoints: get_audit_log and get_notification_audit
- Add explicit audit write helpers: record_delivery_attempt,
  record_delivery_failure, record_acknowledgment
- Add BatchTooLarge error variant
- Add AuditAction enum and AuditRecordAppended, BatchNotificationsCreated
  events
- Add 179-test suite: payload_validation_test, batch_notification_test,
  audit_log_test (all passing)

Author: ScriptedBro

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

@@ -1,10 +1,13 @@
 use crate::base::errors::Error;
 use crate::base::events::{
-    AdminTransferred, AuthorizationFailure, AutoshareCreated, AutoshareUpdated, ContractPaused,
-    ContractUnpaused, GroupActivated, GroupDeactivated, NotificationCategory, NotificationExpired,
-    NotificationPriority, NotificationScheduled, ScheduledNotificationCancelled, Withdrawal,
+    AdminTransferred, AuditAction, AuditRecordAppended, AuthorizationFailure, AutoshareCreated,
+    AutoshareUpdated, BatchNotificationsCreated, ContractPaused, ContractUnpaused, GroupActivated,
+    GroupDeactivated, NotificationCategory, NotificationExpired, NotificationPriority,
+    NotificationScheduled, ScheduledNotificationCancelled, Withdrawal,
+};
+use crate::base::types::{
+    AuditRecord, AutoShareDetails, GroupMember, PaymentHistory, ScheduledNotification,
 };
-use crate::base::types::{AutoShareDetails, GroupMember, PaymentHistory, ScheduledNotification};
 use soroban_sdk::{contracttype, token, Address, BytesN, Env, String, Vec};
 
 /// Maximum allowed length for AutoShare group names.
@@ -24,6 +27,10 @@ pub enum DataKey {
     GroupMembers(BytesN<32>),
     IsPaused,
     ScheduledNotification(BytesN<32>),
+    /// Monotonically increasing counter for audit record sequence numbers.
+    AuditSeq,
+    /// All audit records stored in a single Vec for full-scan queries.
+    AuditLog,
 }
 
 pub fn create_autoshare(
@@ -899,6 +906,13 @@ pub fn schedule_notification(
     };
     env.storage().persistent().set(&key, &notification);
 
+    append_audit_record(
+        &env,
+        notification_id.clone(),
+        AuditAction::Created,
+        creator.clone(),
+    );
+
     NotificationScheduled {
         creator,
         category: NotificationCategory::Notification,
@@ -944,6 +958,13 @@ pub fn expire_notification(env: Env, notification_id: BytesN<32>) -> Result<(),
 
     env.storage().persistent().remove(&key);
 
+    append_audit_record(
+        &env,
+        notification_id.clone(),
+        AuditAction::Expired,
+        env.current_contract_address(),
+    );
+
     NotificationExpired {
         notification_id,
         category: NotificationCategory::Notification,
@@ -984,6 +1005,13 @@ pub fn cancel_notification(
             .remove(&DataKey::ScheduledNotification(notification_id.clone()));
     }
 
+    append_audit_record(
+        &env,
+        notification_id.clone(),
+        AuditAction::Cancelled,
+        caller.clone(),
+    );
+
     ScheduledNotificationCancelled {
         caller,
         category: NotificationCategory::Notification,
@@ -994,3 +1022,252 @@ pub fn cancel_notification(
 
     Ok(())
 }
+
+// ============================================================================
+// Batch Notification Creation
+// ============================================================================
+
+/// Maximum number of notifications that can be created in a single batch call.
+const MAX_BATCH_SIZE: u32 = 50;
+
+/// Creates multiple scheduled notifications in a single transaction.
+///
+/// Each `ids[i]` is paired with `ttl_seconds[i]`. Both slices must have the same
+/// length and must not be empty. The length must not exceed [`MAX_BATCH_SIZE`].
+/// The same validation applied by [`schedule_notification`] is applied to each
+/// entry; if any entry fails the entire call is rejected.
+///
+/// A [`NotificationScheduled`] event is emitted for every created notification,
+/// followed by a single [`BatchNotificationsCreated`] summary event carrying the
+/// full list of ids and the count.
+pub fn batch_schedule_notifications(
+    env: Env,
+    ids: Vec<BytesN<32>>,
+    creator: Address,
+    ttl_seconds: Vec<u64>,
+) -> Result<(), Error> {
+    creator.require_auth();
+
+    if get_paused_status(&env) {
+        return Err(Error::ContractPaused);
+    }
+
+    let count = ids.len();
+
+    // Must have at least one notification.
+    if count == 0 {
+        return Err(Error::InvalidInput);
+    }
+
+    // Lengths must match.
+    if count != ttl_seconds.len() {
+        return Err(Error::InvalidInput);
+    }
+
+    // Enforce maximum batch size.
+    if count > MAX_BATCH_SIZE {
+        return Err(Error::BatchTooLarge);
+    }
+
+    let created_at = env.ledger().timestamp();
+
+    // Validate all entries before persisting any (all-or-nothing semantics).
+    // Also track ids seen within this batch to catch intra-batch duplicates.
+    let mut seen_in_batch: Vec<BytesN<32>> = Vec::new(&env);
+    for i in 0..count {
+        let ttl = ttl_seconds.get(i).unwrap();
+        if ttl == 0 {
+            return Err(Error::InvalidExpirationDuration);
+        }
+        let id = ids.get(i).unwrap();
+
+        // Check for intra-batch duplicates.
+        for seen in seen_in_batch.iter() {
+            if seen == id {
+                return Err(Error::AlreadyExists);
+            }
+        }
+        seen_in_batch.push_back(id.clone());
+
+        let key = DataKey::ScheduledNotification(id.clone());
+        if env.storage().persistent().has(&key) {
+            return Err(Error::AlreadyExists);
+        }
+        // Validate ttl doesn't overflow.
+        created_at
+            .checked_add(ttl)
+            .ok_or(Error::InvalidExpirationDuration)?;
+    }
+
+    // Persist and emit per-notification events.
+    for i in 0..count {
+        let ttl = ttl_seconds.get(i).unwrap();
+        let id = ids.get(i).unwrap();
+        let expires_at = created_at + ttl;
+
+        let notification = ScheduledNotification {
+            id: id.clone(),
+            creator: creator.clone(),
+            created_at,
+            expires_at,
+        };
+        let key = DataKey::ScheduledNotification(id.clone());
+        env.storage().persistent().set(&key, &notification);
+
+        append_audit_record(&env, id.clone(), AuditAction::Created, creator.clone());
+
+        NotificationScheduled {
+            creator: creator.clone(),
+            category: NotificationCategory::Notification,
+            priority: NOTIFICATION_PRIORITY,
+            notification_id: id.clone(),
+        }
+        .publish(&env);
+    }
+
+    // Summary event.
+    BatchNotificationsCreated {
+        creator: creator.clone(),
+        category: NotificationCategory::Notification,
+        priority: NOTIFICATION_PRIORITY,
+        count,
+        ids,
+    }
+    .publish(&env);
+
+    Ok(())
+}
+
+// ============================================================================
+// Audit Logging
+// ============================================================================
+
+/// Appends an immutable [`AuditRecord`] to the on-chain audit log and emits an
+/// [`AuditRecordAppended`] event. The sequence number is auto-incremented.
+fn append_audit_record(
+    env: &Env,
+    notification_id: BytesN<32>,
+    action: AuditAction,
+    actor: Address,
+) {
+    // Increment sequence counter.
+    let seq_key = DataKey::AuditSeq;
+    let seq: u64 = env
+        .storage()
+        .instance()
+        .get(&seq_key)
+        .unwrap_or(0u64)
+        + 1;
+    env.storage().instance().set(&seq_key, &seq);
+
+    let timestamp = env.ledger().timestamp();
+
+    let record = AuditRecord {
+        seq,
+        notification_id: notification_id.clone(),
+        action,
+        actor: actor.clone(),
+        timestamp,
+    };
+
+    // Append to the full log (used for full-scan / range queries).
+    let log_key = DataKey::AuditLog;
+    let mut log: Vec<AuditRecord> = env
+        .storage()
+        .persistent()
+        .get(&log_key)
+        .unwrap_or(Vec::new(env));
+    log.push_back(record);
+    env.storage().persistent().set(&log_key, &log);
+
+    AuditRecordAppended {
+        notification_id,
+        action,
+        category: NotificationCategory::Notification,
+        seq,
+        actor,
+        timestamp,
+    }
+    .publish(env);
+}
+
+/// Returns all audit records in creation order.
+///
+/// Records are immutable and append-only; this list can only grow over time.
+pub fn get_audit_log(env: Env) -> Vec<AuditRecord> {
+    env.storage()
+        .persistent()
+        .get(&DataKey::AuditLog)
+        .unwrap_or(Vec::new(&env))
+}
+
+/// Returns all audit records for a specific notification identifier.
+pub fn get_audit_records_for_notification(
+    env: Env,
+    notification_id: BytesN<32>,
+) -> Vec<AuditRecord> {
+    let log: Vec<AuditRecord> = env
+        .storage()
+        .persistent()
+        .get(&DataKey::AuditLog)
+        .unwrap_or(Vec::new(&env));
+
+    let mut result: Vec<AuditRecord> = Vec::new(&env);
+    for record in log.iter() {
+        if record.notification_id == notification_id {
+            result.push_back(record);
+        }
+    }
+    result
+}
+
+/// Records a delivery attempt for a notification in the audit log.
+///
+/// This is a permissionless write so any authorised service (an off-chain
+/// relay, a keeper) can record that it attempted delivery.
+pub fn record_delivery_attempt(
+    env: Env,
+    notification_id: BytesN<32>,
+    actor: Address,
+) -> Result<(), Error> {
+    actor.require_auth();
+
+    if get_paused_status(&env) {
+        return Err(Error::ContractPaused);
+    }
+
+    append_audit_record(&env, notification_id, AuditAction::DeliveryAttempt, actor);
+    Ok(())
+}
+
+/// Records a delivery failure for a notification in the audit log.
+pub fn record_delivery_failure(
+    env: Env,
+    notification_id: BytesN<32>,
+    actor: Address,
+) -> Result<(), Error> {
+    actor.require_auth();
+
+    if get_paused_status(&env) {
+        return Err(Error::ContractPaused);
+    }
+
+    append_audit_record(&env, notification_id, AuditAction::DeliveryFailed, actor);
+    Ok(())
+}
+
+/// Records that the recipient acknowledged a notification.
+pub fn record_acknowledgment(
+    env: Env,
+    notification_id: BytesN<32>,
+    actor: Address,
+) -> Result<(), Error> {
+    actor.require_auth();
+
+    if get_paused_status(&env) {
+        return Err(Error::ContractPaused);
+    }
+
+    append_audit_record(&env, notification_id, AuditAction::Acknowledged, actor);
+    Ok(())
+}

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

@@ -56,4 +56,6 @@ pub enum Error {
     /// Triggered when attempting to expire a notification whose lifetime has not
     /// yet elapsed.
     NotificationNotExpired = 25,
+    /// Triggered when a batch operation exceeds the maximum allowed size.
+    BatchTooLarge = 26,
 }

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

@@ -1,4 +1,4 @@
-use soroban_sdk::{contractevent, contracttype, Address, BytesN, String};
+use soroban_sdk::{contractevent, contracttype, Address, BytesN, String, Vec};
 
 /// High-level notification category attached to every emitted event.
 ///
@@ -217,3 +217,62 @@ pub struct NotificationExpired {
     pub priority: NotificationPriority,
     pub expires_at: u64,
 }
+
+// ============================================================================
+// Audit Logging
+// ============================================================================
+
+/// Discriminator for each stage in the notification lifecycle that the audit
+/// log tracks.  Values are fixed-width integers so they serialise compactly on
+/// chain and can be matched exactly by off-chain indexers.
+#[contracttype]
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum AuditAction {
+    /// A notification was created (scheduled on-chain).
+    Created = 0,
+    /// A delivery attempt was made for a notification.
+    DeliveryAttempt = 1,
+    /// A delivery attempt failed.
+    DeliveryFailed = 2,
+    /// The recipient acknowledged the notification.
+    Acknowledged = 3,
+    /// The notification was cancelled before expiry.
+    Cancelled = 4,
+    /// The notification expired naturally.
+    Expired = 5,
+}
+
+/// Emitted when a new audit record is appended to the on-chain log.
+///
+/// Off-chain indexers should key off `(notification_id, action)` to track the
+/// full lifecycle of each notification.
+#[contractevent]
+#[derive(Clone)]
+pub struct AuditRecordAppended {
+    #[topic]
+    pub notification_id: BytesN<32>,
+    #[topic]
+    pub action: AuditAction,
+    #[topic]
+    pub category: NotificationCategory,
+    pub seq: u64,
+    pub actor: Address,
+    pub timestamp: u64,
+}
+
+/// Emitted when a batch of notifications is created in a single transaction.
+///
+/// Each per-notification event is still emitted individually; this summary
+/// event additionally carries the count so consumers can verify completeness.
+#[contractevent]
+#[derive(Clone)]
+pub struct BatchNotificationsCreated {
+    #[topic]
+    pub creator: Address,
+    #[topic]
+    pub category: NotificationCategory,
+    #[topic]
+    pub priority: NotificationPriority,
+    pub count: u32,
+    pub ids: Vec<BytesN<32>>,
+}