feat: Implement audit trail metadata update and migration operations

- Added `update_metadata` function in `metadata.rs` to allow updating metadata for an audit trail.
- Introduced `migrate` function in `migrate.rs` for migrating audit trails.
- Created `mod.rs` to organize audit trail operations, including create, locking, metadata, migrate, and records.
- Implemented record management functions in `records.rs` for adding, deleting, and retrieving records.
- Developed `CreateTrail` and `AddRecord` transaction types to facilitate trail creation and record addition.
- Enhanced `Data` type in `record.rs` to support both bytes and text, with serialization and deserialization logic.
- Updated various core types and error handling to reflect new functionalities.
- Added end-to-end tests for creating trails and managing records.

Author: itsyaasir

audit-trail-move/scripts/publish_package.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Copyright 2020-2026 IOTA Stiftung
+# SPDX-License-Identifier: Apache-2.0
+
+script_dir=$(cd "$(dirname $0)" && pwd)
+package_dir=$script_dir/..
+
+RESPONSE=$(iota client publish --with-unpublished-dependencies --silence-warnings --json --gas-budget 500000000 $package_dir)
+{ # try
+    PACKAGE_ID=$(echo $RESPONSE | jq --raw-output '.objectChanges[] | select(.type | contains("published")) | .packageId')
+} || { # catch
+    echo $RESPONSE
+}
+
+export IOTA_AUDIT_TRAIL_PKG_ID=$PACKAGE_ID
+echo "${IOTA_AUDIT_TRAIL_PKG_ID}"

audit-trail-move/sources/record.move

@@ -13,9 +13,9 @@ use std::string::String;
 /// A single record in the audit trail
 public struct Record<D: store + copy> has store {
     /// Arbitrary data stored on-chain
-    stored_data: D,
+    data: D,
     /// Optional metadata for this specific record
-    record_metadata: Option<String>,
+    metadata: Option<String>,
     /// Position in the trail (0-indexed, never reused)
     sequence_number: u64,
     /// Who added this record
@@ -30,16 +30,16 @@ public struct Record<D: store + copy> has store {
 
 /// Create a new record
 public(package) fun new<D: store + copy>(
-    stored_data: D,
-    record_metadata: Option<String>,
+    data: D,
+    metadata: Option<String>,
     sequence_number: u64,
     added_by: address,
     added_at: u64,
     correction: RecordCorrection,
 ): Record<D> {
     Record {
-        stored_data,
-        record_metadata,
+        data,
+        metadata,
         sequence_number,
         added_by,
         added_at,
@@ -51,12 +51,12 @@ public(package) fun new<D: store + copy>(
 
 /// Get the stored data from a record
 public fun data<D: store + copy>(record: &Record<D>): &D {
-    &record.stored_data
+    &record.data
 }
 
 /// Get the record metadata
 public fun metadata<D: store + copy>(record: &Record<D>): &Option<String> {
-    &record.record_metadata
+    &record.metadata
 }
 
 /// Get the record sequence number
@@ -82,8 +82,8 @@ public fun correction<D: store + copy>(record: &Record<D>): &RecordCorrection {
 /// Destroy a record
 public(package) fun destroy<D: store + copy + drop>(record: Record<D>) {
     let Record {
-        stored_data: _,
-        record_metadata: _,
+        data: _,
+        metadata: _,
         sequence_number: _,
         added_by: _,
         added_at: _,

audit-trail-rs/src/client/full_client.rs

@@ -1,36 +1,125 @@
-// Copyright 2020-2025 IOTA Stiftung
+// Copyright 2020-2026 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
-//! A minimal full client wrapper for audit trail interactions.
+//! A full client wrapper for audit trail interactions.
 //!
-//! This is a scaffold that will be extended with transaction-building capabilities
-//! once the Move contract API is finalized.
+//! This client includes signing capabilities for executing transactions.
 
 use std::ops::Deref;
 
 use crate::client::read_only::AuditTrailClientReadOnly;
+use crate::core::builder::AuditTrailBuilder;
+use crate::core::handler::{AuditTrailFull, AuditTrailHandle, AuditTrailReadOnly};
+use crate::error::Error;
+use iota_interaction::types::base_types::ObjectID;
+use iota_interaction::types::transaction::ProgrammableTransaction;
+use iota_interaction::{IotaKeySignature, OptionalSync};
+use iota_sdk::types::crypto::PublicKey;
+use product_common::core_client::{CoreClient, CoreClientReadOnly};
+use product_common::network_name::NetworkName;
+use secret_storage::Signer;
+use serde::de::DeserializeOwned;
 
-/// A full client that wraps the read-only client and will host write operations.
+/// A full client that wraps the read-only client and hosts write operations.
 #[derive(Clone)]
-pub struct AuditTrailClient {
+pub struct AuditTrailClient<S> {
     read_client: AuditTrailClientReadOnly,
+    public_key: PublicKey,
+    signer: S,
 }
 
-impl Deref for AuditTrailClient {
+impl<S> Deref for AuditTrailClient<S> {
     type Target = AuditTrailClientReadOnly;
     fn deref(&self) -> &Self::Target {
         &self.read_client
     }
 }
 
-impl AuditTrailClient {
-    /// Creates a new full client from an existing read-only client.
-    pub fn new(read_client: AuditTrailClientReadOnly) -> Self {
-        Self { read_client }
+impl<S> AuditTrailClient<S>
+where
+    S: Signer<IotaKeySignature>,
+{
+    pub async fn new(client: AuditTrailClientReadOnly, signer: S) -> Result<Self, Error> {
+        let public_key = signer
+            .public_key()
+            .await
+            .map_err(|e| Error::InvalidKey(e.to_string()))?;
+
+        Ok(Self {
+            public_key,
+            read_client: client,
+            signer,
+        })
     }
+}
 
-    /// Returns a reference to the underlying read-only client.
-    pub const fn read_only(&self) -> &AuditTrailClientReadOnly {
+impl<S> AuditTrailClient<S> {
+    pub fn read_only(&self) -> &AuditTrailClientReadOnly {
         &self.read_client
     }
+
+    pub fn trail<'a>(&'a self, trail_id: ObjectID) -> AuditTrailHandle<'a, Self> {
+        AuditTrailHandle::new(self, trail_id)
+    }
+
+    /// Creates a builder for an audit trail.
+    pub fn create_trail(&self) -> AuditTrailBuilder {
+        AuditTrailBuilder::new()
+    }
+
+    pub async fn migrate(&self, _trail_id: ObjectID, _cap_id: ObjectID) -> Result<(), Error> {
+        Err(Error::NotImplemented("AuditTrailClient::migrate"))
+    }
+
+    pub async fn delete_trail(&self, _trail_id: ObjectID, _cap_id: ObjectID) -> Result<(), Error> {
+        Err(Error::NotImplemented("AuditTrailClient::delete_trail"))
+    }
+}
+
+#[async_trait::async_trait]
+impl<S> CoreClientReadOnly for AuditTrailClient<S> {
+    fn package_id(&self) -> ObjectID {
+        self.read_client.package_id()
+    }
+
+    fn network_name(&self) -> &NetworkName {
+        self.read_client.network()
+    }
+
+    fn client_adapter(&self) -> &crate::iota_interaction_adapter::IotaClientAdapter {
+        self.read_client.iota_client()
+    }
+}
+
+#[async_trait::async_trait]
+impl<S> CoreClient<S> for AuditTrailClient<S>
+where
+    S: Signer<IotaKeySignature> + OptionalSync,
+{
+    fn signer(&self) -> &S {
+        &self.signer
+    }
+
+    fn sender_address(&self) -> iota_interaction::types::base_types::IotaAddress {
+        iota_interaction::types::base_types::IotaAddress::from(&self.public_key)
+    }
+
+    fn sender_public_key(&self) -> &iota_interaction::types::crypto::PublicKey {
+        &self.public_key
+    }
 }
+
+#[async_trait::async_trait]
+impl<S> AuditTrailReadOnly for AuditTrailClient<S>
+where
+    S: Signer<IotaKeySignature> + OptionalSync,
+{
+    async fn execute_read_only_transaction<T: DeserializeOwned>(
+        &self,
+        tx: ProgrammableTransaction,
+    ) -> Result<T, Error> {
+        self.read_client.execute_read_only_transaction(tx).await
+    }
+}
+
+impl<S> AuditTrailFull for AuditTrailClient<S> where S: Signer<IotaKeySignature> + OptionalSync {}

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

@@ -1,11 +1,7 @@
-// Copyright 2020-2025 IOTA Stiftung
+// Copyright 2020-2026 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
 //! Client implementations for interacting with audit trails on the IOTA blockchain.
-//!
-//! This module provides two client types:
-//! - [`read_only`]: Read-only access to audit trail data
-//! - [`full_client`]: Full read-write access with transaction capabilities
 
 use iota_interaction::IotaClientTrait;
 use product_common::network_name::NetworkName;

audit-trail-rs/src/client/read_only.rs

@@ -1,22 +1,24 @@
-// Copyright 2020-2025 IOTA Stiftung
+// Copyright 2020-2026 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
 //! A read-only client for interacting with IOTA Audit Trail module objects.
-//!
-//! This client provides minimal setup to resolve the audit trail package ID
-//! and basic access to the underlying IOTA client adapter.
 
 use std::ops::Deref;
 
 #[cfg(not(target_arch = "wasm32"))]
 use iota_interaction::IotaClient;
-use iota_interaction::types::base_types::ObjectID;
+use iota_interaction::IotaClientTrait;
+use iota_interaction::types::base_types::{IotaAddress, ObjectID};
+use iota_interaction::types::transaction::{ProgrammableTransaction, TransactionKind};
 #[cfg(target_arch = "wasm32")]
 use iota_interaction_ts::bindings::WasmIotaClient;
+use product_common::core_client::CoreClientReadOnly;
 use product_common::network_name::NetworkName;
 use product_common::package_registry::Env;
+use serde::de::DeserializeOwned;
 
 use super::network_id;
+use crate::core::handler::{AuditTrailHandle, AuditTrailReadOnly};
 use crate::error::Error;
 use crate::iota_interaction_adapter::IotaClientAdapter;
 use crate::package;
@@ -62,6 +64,11 @@ impl AuditTrailClientReadOnly {
         &self.iota_client
     }
 
+    /// Returns a typed handle bound to a trail id.
+    pub fn trail<'a>(&'a self, trail_id: ObjectID) -> AuditTrailHandle<'a, Self> {
+        AuditTrailHandle::new(self, trail_id)
+    }
+
     /// Attempts to create a new [`AuditTrailClientReadOnly`] from a given IOTA client.
     ///
     /// This resolves the package ID from the internal registry based on the network.
@@ -126,3 +133,48 @@ impl AuditTrailClientReadOnly {
         Self::new_internal(client, network).await
     }
 }
+
+#[async_trait::async_trait]
+impl CoreClientReadOnly for AuditTrailClientReadOnly {
+    fn package_id(&self) -> ObjectID {
+        self.audit_trail_pkg_id
+    }
+
+    fn network_name(&self) -> &NetworkName {
+        &self.network
+    }
+
+    fn client_adapter(&self) -> &IotaClientAdapter {
+        &self.iota_client
+    }
+}
+
+#[async_trait::async_trait]
+impl AuditTrailReadOnly for AuditTrailClientReadOnly {
+    async fn execute_read_only_transaction<T: DeserializeOwned>(
+        &self,
+        tx: ProgrammableTransaction,
+    ) -> Result<T, Error> {
+        let inspection_result = self
+            .iota_client
+            .read_api()
+            .dev_inspect_transaction_block(IotaAddress::ZERO, TransactionKind::programmable(tx), None, None, None)
+            .await
+            .map_err(|err| Error::UnexpectedApiResponse(format!("Failed to inspect transaction block: {err}")))?;
+
+        let execution_results = inspection_result
+            .results
+            .ok_or_else(|| Error::UnexpectedApiResponse("DevInspectResults missing 'results' field".to_string()))?;
+
+        let (return_value_bytes, _) = execution_results
+            .first()
+            .ok_or_else(|| Error::UnexpectedApiResponse("Execution results list is empty".to_string()))?
+            .return_values
+            .first()
+            .ok_or_else(|| Error::InvalidArgument("should have at least one return value".to_string()))?;
+
+        let deserialized_output = bcs::from_bytes::<T>(return_value_bytes)?;
+
+        Ok(deserialized_output)
+    }
+}

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

@@ -0,0 +1,72 @@
+// Copyright 2020-2026 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+//! Audit trail builder for creation transactions.
+
+use product_common::transaction::transaction_builder::TransactionBuilder;
+
+use super::transactions::CreateTrail;
+use super::types::{Data, ImmutableMetadata, LockingConfig};
+use crate::error::Error;
+
+/// Builder for creating an audit trail.
+#[derive(Debug, Clone)]
+pub struct AuditTrailBuilder {
+    pub initial_data: Option<Data>,
+    pub initial_record_metadata: Option<String>,
+    pub locking_config: LockingConfig,
+    pub trail_metadata: Option<ImmutableMetadata>,
+    pub updatable_metadata: Option<String>,
+}
+
+impl AuditTrailBuilder {
+    /// Creates a new builder.
+    pub fn new() -> Self {
+        Self {
+            initial_data: None,
+            initial_record_metadata: None,
+            locking_config: LockingConfig::none(),
+            trail_metadata: None,
+            updatable_metadata: None,
+        }
+    }
+
+    /// Sets the initial record data and optional record metadata.
+    pub fn with_initial_record(mut self, data: Data, metadata: Option<String>) -> Self {
+        self.initial_data = Some(data);
+        self.initial_record_metadata = metadata;
+        self
+    }
+
+    /// Sets the locking configuration for the trail.
+    pub fn with_locking_config(mut self, config: LockingConfig) -> Self {
+        self.locking_config = config;
+        self
+    }
+
+    /// Sets immutable metadata for the trail.
+    pub fn with_trail_metadata(mut self, metadata: ImmutableMetadata) -> Self {
+        self.trail_metadata = Some(metadata);
+        self
+    }
+
+    /// Sets immutable metadata by parts.
+    pub fn with_trail_metadata_parts(mut self, name: impl Into<String>, description: Option<String>) -> Self {
+        self.trail_metadata = Some(ImmutableMetadata {
+            name: name.into(),
+            description,
+        });
+        self
+    }
+
+    /// Sets updatable metadata for the trail.
+    pub fn with_updatable_metadata(mut self, metadata: impl Into<String>) -> Self {
+        self.updatable_metadata = Some(metadata.into());
+        self
+    }
+
+    /// Finalizes the builder and creates a transaction builder.
+    pub fn finish(self) -> Result<TransactionBuilder<CreateTrail>, Error> {
+        Ok(TransactionBuilder::new(CreateTrail::new(self)))
+    }
+}