feat: Implement core types and structures for audit trail functionality

Author: itsyaasir

audit-trail-rs/src/core/mod.rs

@@ -2,5 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 //! Core types and builders for audit trails.
-//!
-//! This module is intentionally minimal while the Move contract API is stabilized.
+
+pub mod types;
+
+pub use types::*;

audit-trail-rs/src/core/types/audit_trail.rs

@@ -0,0 +1,29 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use iota_interaction::types::base_types::IotaAddress;
+use iota_interaction::types::id::UID;
+use serde::{Deserialize, Serialize};
+
+use super::locking::LockingConfig;
+use super::metadata::ImmutableMetadata;
+use super::permission::Permission;
+use super::record::Record;
+use super::role_map::RoleMap;
+
+/// An audit trail stored on-chain.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct AuditTrail<D = super::record::RecordData> {
+    pub id: UID,
+    pub creator: IotaAddress,
+    pub created_at: u64,
+    pub sequence_number: u64,
+    pub records: Vec<Record<D>>,
+    pub locking_config: LockingConfig,
+    pub roles: RoleMap,
+    pub immutable_metadata: Option<ImmutableMetadata>,
+    pub updatable_metadata: Option<String>,
+    pub version: u64,
+    #[serde(skip)]
+    pub _phantom: std::marker::PhantomData<Permission>,
+}

audit-trail-rs/src/core/types/capability.rs

@@ -0,0 +1,17 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use iota_interaction::types::base_types::{IotaAddress, ObjectID};
+use iota_interaction::types::id::UID;
+use serde::{Deserialize, Serialize};
+
+/// Capability data returned by the Move capability module.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Capability {
+    pub id: UID,
+    pub security_vault_id: ObjectID,
+    pub role: String,
+    pub issued_to: Option<IotaAddress>,
+    pub valid_from: Option<u64>,
+    pub valid_until: Option<u64>,
+}

audit-trail-rs/src/core/types/event.rs

@@ -0,0 +1,68 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use iota_interaction::types::base_types::{IotaAddress, ObjectID};
+use serde::{Deserialize, Serialize};
+
+/// Generic wrapper for audit trail events.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Event<D> {
+    #[serde(flatten)]
+    pub data: D,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AuditTrailCreated {
+    pub trail_id: ObjectID,
+    pub creator: IotaAddress,
+    pub timestamp: u64,
+    pub has_initial_record: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AuditTrailDeleted {
+    pub trail_id: ObjectID,
+    pub timestamp: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RecordAdded {
+    pub trail_id: ObjectID,
+    pub sequence_number: u64,
+    pub added_by: IotaAddress,
+    pub timestamp: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RecordDeleted {
+    pub trail_id: ObjectID,
+    pub sequence_number: u64,
+    pub deleted_by: IotaAddress,
+    pub timestamp: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CapabilityIssued {
+    pub security_vault_id: ObjectID,
+    pub capability_id: ObjectID,
+    pub role: String,
+    pub issued_to: Option<IotaAddress>,
+    pub valid_from: Option<u64>,
+    pub valid_until: Option<u64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CapabilityDestroyed {
+    pub security_vault_id: ObjectID,
+    pub capability_id: ObjectID,
+    pub role: String,
+    pub issued_to: Option<IotaAddress>,
+    pub valid_from: Option<u64>,
+    pub valid_until: Option<u64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CapabilityRevoked {
+    pub security_vault_id: ObjectID,
+    pub capability_id: ObjectID,
+}

audit-trail-rs/src/core/types/locking.rs

@@ -0,0 +1,60 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+
+/// Defines a locking window (time or count based).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LockingWindow {
+    pub time_window_seconds: Option<u64>,
+    pub count_window: Option<u64>,
+}
+
+impl LockingWindow {
+    pub fn none() -> Self {
+        Self {
+            time_window_seconds: None,
+            count_window: None,
+        }
+    }
+
+    pub fn time_based(seconds: u64) -> Self {
+        Self {
+            time_window_seconds: Some(seconds),
+            count_window: None,
+        }
+    }
+
+    pub fn count_based(count: u64) -> Self {
+        Self {
+            time_window_seconds: None,
+            count_window: Some(count),
+        }
+    }
+}
+
+/// Locking configuration for the audit trail.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LockingConfig {
+    pub delete_record_lock: LockingWindow,
+}
+
+impl LockingConfig {
+    pub fn none() -> Self {
+        Self {
+            delete_record_lock: LockingWindow::none(),
+        }
+    }
+
+    pub fn time_based(seconds: u64) -> Self {
+        Self {
+            delete_record_lock: LockingWindow::time_based(seconds),
+        }
+    }
+
+    pub fn count_based(count: u64) -> Self {
+        Self {
+            delete_record_lock: LockingWindow::count_based(count),
+        }
+    }
+}

audit-trail-rs/src/core/types/metadata.rs

@@ -0,0 +1,11 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+
+/// Metadata set at trail creation and never updated.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ImmutableMetadata {
+    pub name: String,
+    pub description: Option<String>,
+}

audit-trail-rs/src/core/types/mod.rs

@@ -0,0 +1,24 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+//! Core data types for audit trails.
+
+pub mod audit_trail;
+pub mod capability;
+pub mod event;
+pub mod locking;
+pub mod metadata;
+pub mod permission;
+pub mod record;
+pub mod record_correction;
+pub mod role_map;
+
+pub use audit_trail::*;
+pub use capability::*;
+pub use event::*;
+pub use locking::*;
+pub use metadata::*;
+pub use permission::*;
+pub use record::*;
+pub use record_correction::*;
+pub use role_map::*;

audit-trail-rs/src/core/types/permission.rs

@@ -0,0 +1,82 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+
+/// Permission enum matching the Move permission module.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Hash)]
+pub enum Permission {
+    DeleteAuditTrail,
+    AddRecord,
+    DeleteRecord,
+    CorrectRecord,
+    UpdateLockingConfig,
+    UpdateLockingConfigForDeleteRecord,
+    UpdateLockingConfigForDeleteTrail,
+    AddRoles,
+    UpdateRoles,
+    DeleteRoles,
+    AddCapabilities,
+    RevokeCapabilities,
+    UpdateMetadata,
+    DeleteMetadata,
+}
+
+/// Convenience wrapper for permission sets.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PermissionSet {
+    pub permissions: Vec<Permission>,
+}
+
+impl PermissionSet {
+    pub fn empty() -> Self {
+        Self { permissions: vec![] }
+    }
+
+    pub fn from_vec(permissions: Vec<Permission>) -> Self {
+        Self { permissions }
+    }
+
+    pub fn admin_permissions() -> Self {
+        Self::from_vec(vec![
+            Permission::DeleteAuditTrail,
+            Permission::AddCapabilities,
+            Permission::RevokeCapabilities,
+            Permission::AddRoles,
+            Permission::UpdateRoles,
+            Permission::DeleteRoles,
+        ])
+    }
+
+    pub fn record_admin_permissions() -> Self {
+        Self::from_vec(vec![
+            Permission::AddRecord,
+            Permission::DeleteRecord,
+            Permission::CorrectRecord,
+        ])
+    }
+
+    pub fn locking_admin_permissions() -> Self {
+        Self::from_vec(vec![
+            Permission::UpdateLockingConfig,
+            Permission::UpdateLockingConfigForDeleteTrail,
+            Permission::UpdateLockingConfigForDeleteRecord,
+        ])
+    }
+
+    pub fn role_admin_permissions() -> Self {
+        Self::from_vec(vec![
+            Permission::AddRoles,
+            Permission::UpdateRoles,
+            Permission::DeleteRoles,
+        ])
+    }
+
+    pub fn cap_admin_permissions() -> Self {
+        Self::from_vec(vec![Permission::AddCapabilities, Permission::RevokeCapabilities])
+    }
+
+    pub fn metadata_admin_permissions() -> Self {
+        Self::from_vec(vec![Permission::UpdateMetadata, Permission::DeleteMetadata])
+    }
+}

audit-trail-rs/src/core/types/record.rs

@@ -0,0 +1,35 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use iota_interaction::types::base_types::IotaAddress;
+use serde::{Deserialize, Serialize};
+
+use super::record_correction::RecordCorrection;
+
+/// Supported record data types.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum RecordData {
+    Bytes(Vec<u8>),
+    Text(String),
+}
+
+impl RecordData {
+    pub fn bytes(data: impl Into<Vec<u8>>) -> Self {
+        Self::Bytes(data.into())
+    }
+
+    pub fn text(data: impl Into<String>) -> Self {
+        Self::Text(data.into())
+    }
+}
+
+/// A single record in the audit trail.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Record<D = RecordData> {
+    pub data: D,
+    pub metadata: Option<String>,
+    pub sequence_number: u64,
+    pub added_by: IotaAddress,
+    pub added_at: u64,
+    pub correction: RecordCorrection,
+}

audit-trail-rs/src/core/types/record_correction.rs

@@ -0,0 +1,35 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+
+/// Bidirectional correction tracking for audit records.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RecordCorrection {
+    pub replaces: Vec<u64>,
+    pub is_replaced_by: Option<u64>,
+}
+
+impl RecordCorrection {
+    pub fn new() -> Self {
+        Self {
+            replaces: Vec::new(),
+            is_replaced_by: None,
+        }
+    }
+
+    pub fn with_replaces(replaces: Vec<u64>) -> Self {
+        Self {
+            replaces,
+            is_replaced_by: None,
+        }
+    }
+
+    pub fn is_correction(&self) -> bool {
+        !self.replaces.is_empty()
+    }
+
+    pub fn is_replaced(&self) -> bool {
+        self.is_replaced_by.is_some()
+    }
+}