WIP: Audit Trails#161
Open
itsyaasir wants to merge 299 commits into
Open
Conversation
itsyaasir
commented
Jan 5, 2026
fix: creation of roles & make the sequence and record number clear
…update related assertions
- Updated compiler version to 1.15.0. - Added a new module `record_correction` for managing correction relationships between audit records. - Integrated `RecordCorrection` into the `Record` struct to track corrections. - Updated relevant functions to utilize the new correction tracking feature.
…rade feat: add version specifier for package upgrades
feat: setup correction records
Audit Trail `RoleMap` & `Capability` integration and the Notarization integration for `TimeLock` has been migrated to use `TfComponents` as the following move modules have been moved from the Notarization repository to the new `TfComponents` package in `product_core` : * audit_trail::role_map * audit_trail::capability * notarization::timelock More details can be found in the product-core PR: iotaledger/product-core#89 The Rust and WASM bindings for `TimeLock` are still located in the `notarization` repository. These will be moved to `product-core` during future AT development. Additionally, the Move type `TimeLock` which is now used from `product-core` package `TsComponents` offers new additionally variants `UnlockAtMs` and `Infinite`. The Rust and WASM bindings have been extended accordingly.
- 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.
…error handling - Introduced `from_iota_client` method for creating an `AuditTrailClient` without signing capabilities. - Added `NoSigner` marker type and `FromIotaClientError` for improved error handling during client creation. - Updated `AuditTrailClient` to manage public keys and signers more effectively. - Enhanced `AuditTrailClientReadOnly` with a new method for custom package ID handling.
… initialization - Replaced the custom `new` method in `AuditTrailBuilder` with the `Default` trait for simpler instantiation. - Added `Default` implementation to `LockingWindow` and `LockingConfig` structs for consistent default behavior. - Refactored tests to remove unused environment variable handling and directly use `Data::text` for record creation.
- Moved `AuditTrailHandle`, `AuditTrailFull`, and `AuditTrailReadOnly` traits to a new `trail` module for better organization. - Introduced new modules for capabilities, creation, locking, metadata, records, and roles to enhance modularity. - Updated import paths across the codebase to reflect the new module structure. - Removed deprecated `handler` and `transactions` modules to streamline the codebase. - Enhanced `TrailRecords` and `TrailCapabilities` with new functionalities for managing audit trail records and capabilities.
- Updated import for `CreateTrail` to reflect its new location in the `create` module. - Added a new `trail.rs` module containing traits and structures for managing audit trails, including `AuditTrailReadOnly`, `AuditTrailFull`, and `AuditTrailHandle`. - Enhanced organization of audit trail components for improved modularity and maintainability.
…ures for improved clarity and performance
) - Rewrite of the `delete_records_batch()` and `is_record_locked()` functions to only evaluate against the existing records once when the transaction begins (has been evaluated for each deleted record before) - `window_count_based(0)` is now forbidden in favor of using `window_none()` instead to prevent silently misconfigured trails. - Client-relevant asserts in Move `locking` module are validated in the AT Rust libraries public surface now The Move locking module has two client-relevant asserts, now being also validated in the Rust crate: 1. ECountWindowMustBePositive — window_count_based(0) is rejected. 2. EUntilDestroyedNotSupportedForDeleteTrail — TimeLock::UntilDestroyed cannot be used as the trail-level delete lock (but it is valid for write_lock). The tf_components::timelock module also asserts EPastTimestamp on unlock_at/unlock_at_ms when the timestamp is in the past. This is not mirrored in the Rust crate because it depends on the on-chain clock at execution time, so a client-side check would either be redundant (if the user picks a far-future timestamp) or wrong (if the transaction is built well before submission and a borderline timestamp lapses). --------- Co-authored-by: Yasir <yasir@shariff.dev>
Fix audit-trail Move security audit findings
…otarization (#257) Aligns the documentation across the three implementation layers — Move smart contracts, Rust client crates, and WASM/TypeScript bindings — for both **Audit Trail** and **Notarization**. The goals are * users can live with the docs in the language they use - no need to traverse from TS do Rust or Move * every public Move entity, its Rust counterpart, and its WASM/TS counterpart describe the same behaviour with the same vocabulary, so a reader can move between layers without re-deriving the contract semantics. No behavioural changes — documentation, style guides, and tooling only. See DOC-SKILL-EXAMPLES.md for examples and explanations how to use the SKILL based doc alignment process. Additionally, the README files and the source-docs of public exposed entities for Move, Rust and WASM/TS packages in the repository have been checked against a new [Naming Conventions guideline](https://github.com/iotaledger/notarization/blob/77413f9cf3f6142f78a302b9b95dabb1b6f0bce1/CLAUDE.md#naming-conventions) and edited accordingly. ## What's in the PR **Style guides (new, top-level)** - `MOVE-DOC-STYLEGUIDE.md` — authoritative rules for Move doc comments (audience, block ordering, capability gating, abort/event conventions). - `bindings/wasm/DOC-STYLEGUIDE.md` — equivalent rules for wasm-bindgen-generated TSDoc/JSDoc (TS-visible names, `{@link}` syntax, allowed tags, etc.). - No Rust style guide ATM - Audit Trail and Notarization follow different styles. Discussion needed which path to follow. - `Naming Conventions` section in the root `CLAUDE.md` file which can be seen as the source of truth regarding wording, terminology, prose and capitalization rules. **Per-product `CLAUDE.md` guides** - `audit-trail-move/CLAUDE.md`, `notarization-move/CLAUDE.md` — reference the Move styleguide and pin product-specific terminology (e.g. the "Notarization Methods" rules). - `bindings/wasm/audit_trail_wasm/CLAUDE.md`, `bindings/wasm/notarization_wasm/CLAUDE.md` — same for the TS side. **API mapping files (new)** - `audit-trail-move/api_mapping.toml`, `notarization-move/api_mapping.toml` — map every public Move function/struct/enum to its Rust and WASM/TS counterparts. Used as index when syncing docs across layers to reduce token consumption resp. compare docs of the specific languages more efficiently. **Product-agnostic skills (new, under `.claude/skills/`)** - `init-api-mapping` — bootstraps an `api_mapping.toml` for a new product. - `update-api-mapping` — reconciles the mapping against a git revision (added/removed entities). - `sync-product-docs` — syncs Move/Rust/WASM doc comments using the mapping. - `naming-convention` — Audit README files and public-entity docs for compliance with the `Naming Conventions` **Doc comment rewrites** - `audit-trail-move/sources/*.move`, `notarization-move/sources/*.move` — full rewrite under the new style guide, including consistent abort and event sections. - `audit-trail-rs/src/**`, `notarization-rs/src/**` — Rust docs updated to mirror the Move semantics (per-method bullet lists where behaviour differs, accurate lock semantics, `TimeLock::Infinite` destruction rule, etc.). - `bindings/wasm/audit_trail_wasm/src/**`, `bindings/wasm/notarization_wasm/src/**` — TSDoc rewritten to TS-visible names with `{@link}` references, matching the Move/Rust semantics from the mapping.
# Conflicts: # Cargo.toml # bindings/wasm/notarization_wasm/Cargo.toml
…rmat Cargo.toml files for consistency
The docs of all `permission_set` constructor functions (Move, Rust, WASM) now explicitly list the contained permissions and can now be used as source of truth everywhere else. Several docs contained hard coded permission lists that duplicated the source-of-truth. Three of them were already outdated (i.e. admin_permissions()) and there is a risk that these lists get outdated. Now the `permission_set` constructor functions are referenced in all other docs (single source of truth - at least in the specific programming language).
Product name `Audit Trail` has changed to `Audit Trails`. In this context Following changes are included: * `Naming Conventions` section in the `CLAUDE.md` file has been changed accordingly * README files and source docs of public exposed entities for Move, Rust and WASM/TS have been checked and edited according to the new `Naming Conventions` * Audit Trails Move package: * The name of the package has been renamed to `IotaAuditTrails` * The alias of the package address has been renamed to `audit_trails` allowing Move users to import AT Move types with `use audit_trails:: ...` * The npmjs package "@iota/audit-trail" has been renamed to "@iota/audit-trails" * The Rust crate `audit_trail` has been renamed to `audit_trails` - folder names are kept as-is. This allow Rust users to import the crate using `use audit_trails::...` instead of `use audit_trail::....` Additional minor changes: * The `Permission::Migrate`has been added to the `admin_permissions()` set in the AT Rust package * The `audit/trail_wasm/docs` folder has been deleted because it's auto generated and contained in `.gitignore` * Use qualified type names for events and errors originating from TfComponents used in `audit-trail-move/sources/audit_trail.move` Files, folders, crates, modules (Rust, Move) etc. still strictly follow the "only singular form in names rule". Only renaming the crate and the npmjs package allows users to have proper imports in TS and Rust but doesn't cause too much efforts.
…ependency in Move.toml
…d to use markdown-lists
… /update-api-mapping skills
…rmission-set constructors and events during future development
…tation Add audit trail event emissions for updates
…arization-move refactor: remove TfComponents from `notarization-move`
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description of change
Links to any relevant issues
Type of change
How the change has been tested
Change checklist