docs: improve notarization and audit trail docs

Author: itsyaasir

README.md

@@ -9,48 +9,66 @@
 
 <p align="center">
   <a href="#introduction">Introduction</a> ◈
+  <a href="#packages">Packages</a> ◈
   <a href="#documentation-and-resources">Documentation & Resources</a> ◈
   <a href="#bindings">Bindings</a> ◈
   <a href="#contributing">Contributing</a>
 </p>
 
 ---
 
-# IOTA Notarization
+# IOTA Notarization And Audit Trail
 
 ## Introduction
 
-IOTA Notarization enables the creation of immutable, on-chain records for any arbitrary data. This is achieved by storing the data, or a hash of it, inside a dedicated Move object on the IOTA ledger. This process provides a verifiable, timestamped proof of the data's existence and integrity at a specific point in time.
+This repository contains two complementary IOTA ledger toolkits:
 
-IOTA Notarization is composed of two primary components:
+- **IOTA Notarization**
+  Creates verifiable on-chain proof objects for arbitrary data, including dynamic and locked notarization flows.
+- **IOTA Audit Trail**
+  Creates shared on-chain audit trails with sequential records, role-based access control, locking, and tagging.
 
-- **Notarization Move Package**: The on-chain smart contracts that define the behavior and structure of notarization objects.
-- **Notarization Library (Rust/Wasm)**: A client-side library that provides developers with convenient functions to create, manage, and verify `Notarization` objects on the network.
+Each toolkit is split into:
 
-## Documentation and Resources
+- a Move package that defines the on-chain object model and behavior
+- a Rust SDK that provides typed client access and transaction builders
+- wasm bindings for JavaScript and TypeScript integrations
 
-- [Notarization Documentation Pages](https://docs.iota.org/developer/iota-notarization): Supplementing documentation with context around notarization and simple examples on library usage.
-- API References:
-  - [Rust API Reference](https://iotaledger.github.io/notarization/notarization/index.html): Package documentation (cargo docs).
+## Packages
 
-<!--  - [Wasm API Reference](https://docs.iota.org/references/iota-notarization/wasm/api_ref): Wasm Package documentation. -->
+| Toolkit | Move Package | Rust SDK | Wasm SDK |
+| ------- | ------------ | -------- | -------- |
+| Notarization | [`notarization-move`](./notarization-move) | [`notarization-rs`](./notarization-rs) | [`bindings/wasm/notarization_wasm`](./bindings/wasm/notarization_wasm) |
+| Audit Trail | [`audit-trail-move`](./audit-trail-move) | [`audit-trail-rs`](./audit-trail-rs) | [`bindings/wasm/audit_trail_wasm`](./bindings/wasm/audit_trail_wasm) |
 
-- Examples:
-  - [Rust Examples](https://github.com/iotaledger/notarization/tree/main/examples/README.md): Practical code snippets to get you started with the library in Rust.
-  - [Wasm Examples](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/notarization_wasm/examples/README.md): Practical code snippets to get you started with the library in TypeScript/JavaScript.
+## Documentation And Resources
+
+- IOTA Notarization:
+  - [Notarization Rust SDK README](https://github.com/iotaledger/notarization/tree/main/notarization-rs/README.md)
+  - [Notarization Wasm README](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/notarization_wasm/README.md)
+  - [Notarization Examples](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/notarization_wasm/examples/README.md)
+  - [IOTA Notarization Docs Portal](https://docs.iota.org/developer/iota-notarization)
+- IOTA Audit Trail:
+  - [Audit Trail Rust SDK README](https://github.com/iotaledger/notarization/tree/main/audit-trail-rs/README.md)
+  - [Audit Trail Move Package README](https://github.com/iotaledger/notarization/tree/main/audit-trail-move/README.md)
+  - [Audit Trail Wasm README](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm/README.md)
+  - [Audit Trail Wasm Examples](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm/examples/README.md)
+- Shared:
+  - [Repository Examples](https://github.com/iotaledger/notarization/tree/main/examples/README.md)
 
 ## Bindings
 
-[Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface) Bindings of this [Rust](https://www.rust-lang.org/) library to other programming languages:
+[Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface) bindings in this repository:
 
-- [Web Assembly](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/notarization_wasm) (JavaScript/TypeScript)
+- [Web Assembly](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/notarization_wasm) for IOTA Notarization
+- [Web Assembly](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm) for IOTA Audit Trail
 
 ## Contributing
 
-We would love to have you help us with the development of IOTA Notarization. Each and every contribution is greatly valued!
+We would love to have you help us with the development of IOTA Notarization and Audit Trail. Each and every contribution is greatly valued.
 
 Please review the [contribution](https://docs.iota.org/developer/iota-notarization/contribute) sections in the [IOTA Docs Portal](https://docs.iota.org/developer/iota-notarization/).
 
-To contribute directly to the repository, simply fork the project, push your changes to your fork and create a pull request to get them included!
+To contribute directly to the repository, simply fork the project, push your changes to your fork and create a pull request to get them included.
 
-The best place to get involved in discussions about this library or to look for support at is the `#notarization` channel on the [IOTA Discord](https://discord.gg/iota-builders). You can also ask questions on our [Stack Exchange](https://iota.stackexchange.com/).
+The best place to get involved in discussions about these libraries or to look for support at is the `#notarization` channel on the [IOTA Discord](https://discord.gg/iota-builders). You can also ask questions on our [Stack Exchange](https://iota.stackexchange.com/).

audit-trail-move/README.md

@@ -0,0 +1,90 @@
+![banner](https://github.com/iotaledger/notarization/raw/HEAD/.github/banner_notarization.png)
+
+<p align="center">
+  <a href="https://iota.stackexchange.com/" style="text-decoration:none;"><img src="https://img.shields.io/badge/StackExchange-9cf.svg?logo=stackexchange" alt="StackExchange"></a>
+  <a href="https://discord.gg/iota-builders" style="text-decoration:none;"><img src="https://img.shields.io/badge/Discord-9cf.svg?logo=discord" alt="Discord"></a>
+  <a href="https://github.com/iotaledger/notarization/blob/develop/LICENSE" style="text-decoration:none;"><img src="https://img.shields.io/github/license/iotaledger/notarization.svg" alt="Apache 2.0 license"></a>
+</p>
+
+<p align="center">
+  <a href="#introduction">Introduction</a> ◈
+  <a href="#modules">Modules</a> ◈
+  <a href="#development-and-testing">Development & Testing</a> ◈
+  <a href="#related-libraries">Related Libraries</a> ◈
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+# IOTA Audit Trail Move Package
+
+## Introduction
+
+`audit-trail-move` is the on-chain Move package behind IOTA Audit Trail.
+
+It defines the shared `AuditTrail` object and the supporting types needed for:
+
+- sequential record storage
+- role-based access control through capabilities
+- trail-wide locking for writes and deletions
+- record tags and role tag restrictions
+- immutable and updatable trail metadata
+- emitted events for trail and record lifecycle changes
+
+The package depends on `TfComponents` for reusable capability, role-map, and timelock primitives.
+
+## Modules
+
+- `audit_trail::main`
+  Core shared object, events, trail lifecycle, record mutation, metadata updates, roles, and capabilities.
+- `audit_trail::record`
+  Record payloads, initial records, and correction metadata.
+- `audit_trail::locking`
+  Locking configuration and lock evaluation helpers.
+- `audit_trail::permission`
+  Permission constructors and admin permission presets.
+- `audit_trail::record_tags`
+  Tag registry and role tag helpers.
+
+## Development And Testing
+
+Build the Move package:
+
+```bash
+cd audit-trail-move
+iota move build
+```
+
+Run the Move test suite:
+
+```bash
+cd audit-trail-move
+iota move test
+```
+
+Publish locally:
+
+```bash
+cd audit-trail-move
+./scripts/publish_package.sh
+```
+
+The publish script prints `IOTA_AUDIT_TRAIL_PKG_ID` and, on `localnet`, also exports `IOTA_TF_COMPONENTS_PKG_ID`.
+
+The package history files [`Move.lock`](./Move.lock) and [`Move.history.json`](./Move.history.json) are used by the Rust SDK to resolve and track deployed package versions.
+
+## Related Libraries
+
+- [Rust SDK](https://github.com/iotaledger/notarization/tree/main/audit-trail-rs/README.md)
+- [Wasm SDK](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm/README.md)
+- [Repository Root](https://github.com/iotaledger/notarization/tree/main/README.md)
+
+## Contributing
+
+We would love to have you help us with the development of IOTA Audit Trail. Each and every contribution is greatly valued.
+
+Please review the [contribution](https://docs.iota.org/developer/iota-notarization/contribute) sections in the [IOTA Docs Portal](https://docs.iota.org/developer/iota-notarization/).
+
+To contribute directly to the repository, simply fork the project, push your changes to your fork and create a pull request to get them included.
+
+The best place to get involved in discussions about this package or to look for support at is the `#notarization` channel on the [IOTA Discord](https://discord.gg/iota-builders). You can also ask questions on our [Stack Exchange](https://iota.stackexchange.com/).

audit-trail-rs/README.md

@@ -1 +1,99 @@
-# IOTA Audit Trail (WIP)
+![banner](https://github.com/iotaledger/notarization/raw/HEAD/.github/banner_notarization.png)
+
+<p align="center">
+  <a href="https://iota.stackexchange.com/" style="text-decoration:none;"><img src="https://img.shields.io/badge/StackExchange-9cf.svg?logo=stackexchange" alt="StackExchange"></a>
+  <a href="https://discord.gg/iota-builders" style="text-decoration:none;"><img src="https://img.shields.io/badge/Discord-9cf.svg?logo=discord" alt="Discord"></a>
+  <a href="https://github.com/iotaledger/notarization/blob/develop/LICENSE" style="text-decoration:none;"><img src="https://img.shields.io/github/license/iotaledger/notarization.svg" alt="Apache 2.0 license"></a>
+</p>
+
+<p align="center">
+  <a href="#introduction">Introduction</a> ◈
+  <a href="#documentation-and-resources">Documentation & Resources</a> ◈
+  <a href="#feature-overview">Feature Overview</a> ◈
+  <a href="#bindings">Bindings</a> ◈
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+# IOTA Audit Trail Rust SDK
+
+## Introduction
+
+`audit_trail` is the Rust SDK for reading and writing audit trails on the IOTA ledger.
+
+An audit trail is a shared on-chain object that stores a sequential series of records together with:
+
+- role-based access control backed by capabilities
+- trail-level locking rules for writes and deletions
+- tag registries for record categorization
+- immutable creation metadata and optional updatable metadata
+
+The crate provides:
+
+- read-only and signing client wrappers for the on-chain audit-trail package
+- typed trail handles for records, locking, access control, and tags
+- serializable Rust representations of on-chain objects and emitted events
+- transaction builders that integrate with the shared `product_common` transaction flow
+
+## Documentation And Resources
+
+- [Audit Trail Move Package](https://github.com/iotaledger/notarization/tree/main/audit-trail-move): On-chain contract package that defines the shared object model, permissions, locking, and events.
+- [Wasm SDK](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm): JavaScript and TypeScript bindings for browser and Node.js integrations.
+- [Wasm Examples](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm/examples/README.md): Runnable audit-trail examples for JS and TS consumers.
+- [Repository Examples](https://github.com/iotaledger/notarization/tree/main/examples/README.md): End-to-end examples across the broader repository.
+
+This README is also used as the crate-level rustdoc entry point, while the source files provide detailed API documentation for all public types and methods.
+
+## Feature Overview
+
+The public API is organized around a small set of entry points:
+
+- [`AuditTrailClientReadOnly`] for package resolution, trail-scoped reads, and inspected transactions
+- [`AuditTrailClient`] for signed write flows
+- [`AuditTrailHandle`] for operations scoped to one trail object
+- [`AuditTrailBuilder`] for configuring trail creation
+- [`core::types`] for domain types such as [`Data`], [`Record`], [`LockingConfig`], and [`PermissionSet`]
+
+Typical flow:
+
+1. Construct an [`AuditTrailClientReadOnly`] or [`AuditTrailClient`].
+2. Resolve a trail with [`AuditTrailClientReadOnly::trail`] or [`AuditTrailClient::trail`].
+3. Read state with [`AuditTrailHandle::get`] or move into one of the trail subsystems:
+   - [`AuditTrailHandle::records`]
+   - [`AuditTrailHandle::locking`]
+   - [`AuditTrailHandle::access`]
+   - [`AuditTrailHandle::tags`]
+4. For writes, build a typed transaction from the client, trail handle, or subsystem handle and execute it through the surrounding transaction infrastructure.
+
+The crate deliberately separates transaction construction from submission so applications can keep signing, sponsorship, gas selection, and batching policy outside the SDK.
+
+Pure value types expose executable doctests where the behavior is self-contained and stable:
+
+```rust
+use audit_trail::core::types::{Data, InitialRecord};
+
+let record = InitialRecord::new(Data::text("hello"), Some("first write".to_string()), None);
+
+assert_eq!(record.data, Data::text("hello"));
+assert_eq!(record.metadata.as_deref(), Some("first write"));
+assert!(record.tag.is_none());
+```
+
+If you are integrating against a custom deployment, use [`PackageOverrides`] during client construction so the crate does not rely on the built-in package registry for that environment.
+
+## Bindings
+
+[Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface) bindings of this Rust SDK to other programming languages:
+
+- [Web Assembly](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm) (JavaScript/TypeScript)
+
+## Contributing
+
+We would love to have you help us with the development of IOTA Audit Trail. Each and every contribution is greatly valued.
+
+Please review the [contribution](https://docs.iota.org/developer/iota-notarization/contribute) sections in the [IOTA Docs Portal](https://docs.iota.org/developer/iota-notarization/).
+
+To contribute directly to the repository, simply fork the project, push your changes to your fork and create a pull request to get them included.
+
+The best place to get involved in discussions about this library or to look for support at is the `#notarization` channel on the [IOTA Discord](https://discord.gg/iota-builders). You can also ask questions on our [Stack Exchange](https://iota.stackexchange.com/).