diff --git a/.github/banner_audit_trails.png b/.github/banner_audit_trails.png new file mode 100644 index 0000000..fac8906 Binary files /dev/null and b/.github/banner_audit_trails.png differ diff --git a/README.md b/README.md index b4593d6..68e4992 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@

Introduction ◈ Where To Start ◈ - Toolkits ◈ + Suite Components ◈ Documentation & Resources ◈ Bindings ◈ Contributing @@ -18,18 +18,20 @@ --- -# IOTA Notarization And Audit Trail +# IOTA Notarization Suite ## Introduction -This repository contains two complementary IOTA ledger toolkits for verifiable on-chain data workflows: +This repository contains the IOTA Notarization Suite, a set of IOTA ledger tools for verifiable on-chain data workflows. -- **IOTA Notarization** - Best when you want a proof object for arbitrary data, documents, hashes, or latest-state notarization flows. -- **IOTA Audit Trail** - Best when you want shared audit records with sequential entries, role-based access control, locking, and tagging. +The suite includes: -Each toolkit is available as: +- **Single Notarization** + Use this for individual locked or dynamic notarizations of arbitrary data, documents, hashes, or latest-state records. +- **Audit Trails** + Use this for structured record histories with sequential entries, role-based access control, locking, and tagging. + +Each suite component is available as: - a **Move package** for the on-chain contracts - a **Rust SDK** for typed client access and transaction builders @@ -37,68 +39,68 @@ Each toolkit is available as: ## Where To Start -### I want to notarize data +### I want a single notarized record -Use **IOTA Notarization** when your main need is proving the existence, integrity, or latest state of data on-chain. +Use **Single Notarization** when your main need is proving the existence, integrity, or latest state of one notarized object on-chain. -- [Notarization Rust SDK](./notarization-rs) -- [Notarization Move Package](./notarization-move) -- [Notarization Wasm SDK](./bindings/wasm/notarization_wasm) -- [Notarization examples](./bindings/wasm/notarization_wasm/examples/README.md) +- [Single Notarization Rust SDK](./notarization-rs) +- [Single Notarization Move Package](./notarization-move) +- [Single Notarization Wasm SDK](./bindings/wasm/notarization_wasm) +- [Single Notarization examples](./bindings/wasm/notarization_wasm/examples/README.md) -### I want audit records +### I want an audit trail -Use **IOTA Audit Trail** when you need shared audit records with permissions, capabilities, tagging, and write or delete controls. +Use **Audit Trails** when you need a structured record history with permissions, capabilities, tagging, and write or delete controls. -- [Audit Trail Rust SDK](./audit-trail-rs) -- [Audit Trail Move Package](./audit-trail-move) -- [Audit Trail Wasm SDK](./bindings/wasm/audit_trail_wasm) -- [Audit Trail examples](./bindings/wasm/audit_trail_wasm/examples/README.md) +- [Audit Trails Rust SDK](./audit-trail-rs) +- [Audit Trails Move Package](./audit-trail-move) +- [Audit Trails Wasm SDK](./bindings/wasm/audit_trail_wasm) +- [Audit Trails examples](./bindings/wasm/audit_trail_wasm/examples/README.md) ### I want the on-chain contracts -- [Notarization Move](./notarization-move) -- [Audit Trail Move](./audit-trail-move) +- [Single Notarization Move](./notarization-move) +- [Audit Trails Move](./audit-trail-move) ### I want application SDKs -- [Notarization Rust](./notarization-rs) -- [Audit Trail Rust](./audit-trail-rs) -- [Notarization Wasm](./bindings/wasm/notarization_wasm) -- [Audit Trail Wasm](./bindings/wasm/audit_trail_wasm) +- [Single Notarization Rust](./notarization-rs) +- [Audit Trails Rust](./audit-trail-rs) +- [Single Notarization Wasm](./bindings/wasm/notarization_wasm) +- [Audit Trails Wasm](./bindings/wasm/audit_trail_wasm) -## Toolkits +## Suite Components -| Toolkit | Best for | Move Package | Rust SDK | Wasm SDK | -| ------------ | ------------------------------------------------------------------------ | ------------------------------------------ | -------------------------------------- | -------------------------------------------------------- | -| Notarization | Proof objects for documents, hashes, and updatable notarized state | [`notarization-move`](./notarization-move) | [`notarization-rs`](./notarization-rs) | [`notarization_wasm`](./bindings/wasm/notarization_wasm) | -| Audit Trail | Shared sequential records with roles, capabilities, tagging, and locking | [`audit-trail-move`](./audit-trail-move) | [`audit-trail-rs`](./audit-trail-rs) | [`audit_trail_wasm`](./bindings/wasm/audit_trail_wasm) | +| Component | Best for | Move Package | Rust SDK | Wasm SDK | +| -------------------- | ------------------------------------------------------------------------ | ------------------------------------------ | -------------------------------------- | -------------------------------------------------------- | +| Single Notarization | Individual locked or dynamic notarizations for documents, hashes, and state | [`notarization-move`](./notarization-move) | [`notarization-rs`](./notarization-rs) | [`notarization_wasm`](./bindings/wasm/notarization_wasm) | +| Audit Trails | Shared sequential records with roles, capabilities, tagging, and locking | [`audit-trail-move`](./audit-trail-move) | [`audit-trail-rs`](./audit-trail-rs) | [`audit_trail_wasm`](./bindings/wasm/audit_trail_wasm) | ### Which one should I use? -| Need | Best fit | -| ------------------------------------------------------------------------- | ------------ | -| Immutable or updatable proof object for arbitrary data | Notarization | -| Simple proof-of-existence or latest-state notarization flow | Notarization | -| Shared sequential records with roles, capabilities, and record tag policy | Audit Trail | -| Team or system audit log with governance and operational controls | Audit Trail | +| Need | Best fit | +| ------------------------------------------------------------------------- | -------------------- | +| Locked proof object for arbitrary data | Single Notarization | +| Dynamic latest-state notarization flow | Single Notarization | +| Shared sequential records with roles, capabilities, and record tag policy | Audit Trails | +| Team or system audit log with governance and operational controls | Audit Trails | ## Documentation And Resources -### IOTA Notarization +### Single Notarization -- [Notarization Rust SDK README](./notarization-rs/README.md) -- [Notarization Move Package README](./notarization-move/README.md) -- [Notarization Wasm README](./bindings/wasm/notarization_wasm/README.md) -- [Notarization examples](./bindings/wasm/notarization_wasm/examples/README.md) +- [Single Notarization Rust SDK README](./notarization-rs/README.md) +- [Single Notarization Move Package README](./notarization-move/README.md) +- [Single Notarization Wasm README](./bindings/wasm/notarization_wasm/README.md) +- [Single Notarization examples](./bindings/wasm/notarization_wasm/examples/README.md) - [IOTA Notarization Docs Portal](https://docs.iota.org/developer/iota-notarization) -### IOTA Audit Trail +### Audit Trails -- [Audit Trail Rust SDK README](./audit-trail-rs/README.md) -- [Audit Trail Move Package README](./audit-trail-move/README.md) -- [Audit Trail Wasm README](./bindings/wasm/audit_trail_wasm/README.md) -- [Audit Trail examples](./bindings/wasm/audit_trail_wasm/examples/README.md) +- [Audit Trails Rust SDK README](./audit-trail-rs/README.md) +- [Audit Trails Move Package README](./audit-trail-move/README.md) +- [Audit Trails Wasm README](./bindings/wasm/audit_trail_wasm/README.md) +- [Audit Trails examples](./bindings/wasm/audit_trail_wasm/examples/README.md) ### Shared @@ -108,12 +110,12 @@ Use **IOTA Audit Trail** when you need shared audit records with permissions, ca [Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface) bindings available in this repository: -- [Web Assembly for IOTA Notarization](./bindings/wasm/notarization_wasm) -- [Web Assembly for IOTA Audit Trail](./bindings/wasm/audit_trail_wasm) +- [Web Assembly for Single Notarization](./bindings/wasm/notarization_wasm) +- [Web Assembly for Audit Trails](./bindings/wasm/audit_trail_wasm) ## Contributing -We would love to have you help us with the development of IOTA Notarization and Audit Trail. Each and every contribution is greatly valued. +We would love to have you help us with the development of the IOTA Notarization Suite. 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/). diff --git a/audit-trail-rs/README.md b/audit-trail-rs/README.md index f02ca75..112b069 100644 --- a/audit-trail-rs/README.md +++ b/audit-trail-rs/README.md @@ -1,46 +1,251 @@ -![banner](https://github.com/iotaledger/notarization/raw/HEAD/.github/banner_notarization.png) +# IOTA Audit Trails Rust SDK -

- StackExchange - Discord - Apache 2.0 license -

+## Introduction -

- Introduction ◈ - Documentation & Resources ◈ - Bindings ◈ - Contributing -

+The Audit Trails Rust SDK is the Rust client for structured record histories in the IOTA Notarization Suite. ---- +The SDK provides an `AuditTrailBuilder` that creates audit trail objects on the IOTA ledger and an `AuditTrailHandle` +that interacts with existing trails. The handle maps to one on-chain audit trail and provides typed APIs for records, +access control, locking, tags, metadata, migration, and deletion. -# IOTA Audit Trail Rust SDK +Use Audit Trails when you need a governed record history with sequential entries, role-based permissions, capabilities, +locking, and tagging. Use Single Notarization when you need one locked or dynamic notarized object for arbitrary data, +documents, hashes, or latest-state records. -## Introduction +You can find the full IOTA Notarization Suite documentation [here](https://docs.iota.org/developer/iota-notarization). + +## Process Flows + +The following workflows demonstrate how `AuditTrailBuilder` and `AuditTrailHandle` instances create, update, govern, and +delete audit trail objects on the ledger. + +### Creating an Audit Trail + +An _Audit Trail_ is created on the ledger using the `AuditTrailClient::create_trail()` function. To create an _Audit +Trail_, specify the following initial arguments with the `AuditTrailBuilder` setter functions. The terms used here are +defined in the [glossary below](#glossary). + +- Optional `Initial Record` that becomes sequence number `0` +- Optional `Immutable Metadata` +- Optional `Updatable Metadata` +- Optional `Locking Config` +- Optional `Record Tag Registry` +- Optional initial admin address + +After an _Audit Trail_ has been created, the creator receives an Admin capability object. This capability authorizes +administrative operations such as defining roles, issuing capabilities, updating locks, managing tags, and deleting the +trail. + +#### Creating a new Audit Trail on the Ledger + +The following sequence diagram explains the interaction between the involved technical components and the `Admin` when an +_Audit Trail_ is created on the ledger: + +```mermaid +sequenceDiagram + actor Admin + participant Lib as Rust-Library + participant Move as Move-SC + participant Net as Iota-Network + Admin ->>+ Lib: fn AuditTrailClientReadOnly::new(iota_client) + Lib ->>- Admin: AuditTrailClientReadOnly + Admin ->>+ Lib: fn AuditTrailClient::new(read_only_client, signer) + Lib ->>- Admin: AuditTrailClient + Admin ->>+ Lib: fn AuditTrailClient::create_trail() + Lib ->>- Admin: AuditTrailBuilder + Admin ->> Lib: fn AuditTrailBuilder::with_trail_metadata(metadata) + Admin ->> Lib: fn AuditTrailBuilder::with_updatable_metadata(metadata) + Admin ->> Lib: fn AuditTrailBuilder::with_initial_record(record) + Admin ->>+ Lib: fn AuditTrailBuilder::finish() + Lib ->>- Admin: TransactionBuilder + Admin ->>+ Lib: fn TransactionBuilder::build_and_execute() + Note right of Admin: Alternatively fn execute_with_gas_station()
can be used to execute via Gas Station + Note right of Admin: Alternatively fn build()
can be used to only return the TransactionData and signatures + Lib ->>+ Move: main::create() + Move ->> Net: transfer::transfer(trail, sender) + Move ->> Net: transfer::transfer(admin_capability, admin) + Move ->>- Lib: TX Response + Lib ->>- Admin: TrailCreated + IotaTransactionBlockResponse +``` + +### Adding And Reading Records + +Records are managed through the trail-scoped record API returned by `AuditTrailHandle::records()`. A record append uses +`TrailRecords::add()`, while read paths use `TrailRecords::get()`, `TrailRecords::record_count()`, `TrailRecords::list()`, +or `TrailRecords::list_page()`. + +To add a record, the sender must hold a capability whose role allows record writes. Tagged records must use a tag already +defined in the trail's tag registry, and the sender's role must allow that tag. + +#### Appending a Record to an Existing Audit Trail + +The following sequence diagram shows the component interaction when a `Record Admin` appends a new record: + +```mermaid +sequenceDiagram + actor RecordAdmin + participant Lib as Rust-Library + participant Move as Move-SC + participant Net as Iota-Network + RecordAdmin ->>+ Lib: fn AuditTrailClient::trail(trail_id) + Lib ->>- RecordAdmin: AuditTrailHandle + RecordAdmin ->>+ Lib: fn AuditTrailHandle::records() + Lib ->>- RecordAdmin: TrailRecords + RecordAdmin ->>+ Lib: fn TrailRecords::add(data, metadata, tag) + Lib ->>- RecordAdmin: TransactionBuilder + RecordAdmin ->>+ Lib: fn TransactionBuilder::build_and_execute() + Lib ->>+ Move: main::add_record() + Move ->> Move: validate capability, lock state, and tag policy + Move ->> Net: append record at next sequence number + Move ->> Net: event::emit(RecordAdded) + Move ->>- Lib: TX Response + Lib ->>- RecordAdmin: RecordAdded + IotaTransactionBlockResponse +``` + +#### Reading Records from an Existing Audit Trail + +The following sequence diagram explains the component interaction for `Verifiers` or other parties fetching trail +records: + +```mermaid +sequenceDiagram + actor Verifier + participant Lib as Rust-Library + participant Net as Iota-Network + Verifier ->>+ Lib: fn AuditTrailClientReadOnly::trail(trail_id) + Lib ->>- Verifier: AuditTrailHandle + Verifier ->>+ Lib: fn AuditTrailHandle::records() + Lib ->>- Verifier: TrailRecords + Verifier ->>+ Lib: fn TrailRecords::get(sequence_number) + Lib -->> Net: RPC Calls + Net -->> Lib: Record Data + Lib ->>- Verifier: Record +``` + +### Managing Access + +Access control is managed through the trail-scoped access API returned by `AuditTrailHandle::access()`. Roles define +which permissions are allowed, and capability objects delegate those roles to users or services. + +The built-in Admin role is initialized when the trail is created. Additional roles can be created with +`TrailAccess::for_role(name).create(...)`, updated with `update_permissions(...)`, and delegated with +`issue_capability(...)`. Issued capabilities can also be revoked, destroyed, or constrained by address and validity +window. + +#### Defining a Role and Issuing a Capability + +The following sequence diagram shows the component interaction when an `Admin` defines a role and issues a capability: + +```mermaid +sequenceDiagram + actor Admin + participant Lib as Rust-Library + participant Move as Move-SC + participant Net as Iota-Network + Admin ->>+ Lib: fn AuditTrailClient::trail(trail_id) + Lib ->>- Admin: AuditTrailHandle + Admin ->>+ Lib: fn AuditTrailHandle::access() + Lib ->>- Admin: TrailAccess + Admin ->>+ Lib: fn TrailAccess::for_role("RecordAdmin") + Lib ->>- Admin: RoleHandle + Admin ->>+ Lib: fn RoleHandle::create(permissions, role_tags) + Lib ->>- Admin: TransactionBuilder + Admin ->>+ Lib: fn TransactionBuilder::build_and_execute() + Lib ->>+ Move: main::create_role() + Move ->> Net: event::emit(RoleCreated) + Move ->>- Lib: TX Response + Admin ->>+ Lib: fn RoleHandle::issue_capability(options) + Lib ->>- Admin: TransactionBuilder + Admin ->>+ Lib: fn TransactionBuilder::build_and_execute() + Lib ->>+ Move: main::new_capability() + Move ->> Net: transfer::transfer(capability, issued_to) + Move ->> Net: event::emit(CapabilityIssued) + Move ->>- Lib: TX Response + Lib ->>- Admin: CapabilityIssued + IotaTransactionBlockResponse +``` + +### Locking And Deletion + +Locking is managed through the trail-scoped locking API returned by `AuditTrailHandle::locking()`. The lock configuration +controls three independent behaviors: + +- when records can be deleted +- when the entire trail can be deleted +- when new records can be written + +An audit trail can be deleted only after its records are removed and the delete-trail lock allows deletion. Records can +be deleted individually with `TrailRecords::delete()` or in batches with `TrailRecords::delete_records_batch()`. + +#### Updating Locking Rules + +The following sequence diagram shows the component interaction when a `Locking Admin` updates the write lock: + +```mermaid +sequenceDiagram + actor LockingAdmin + participant Lib as Rust-Library + participant Move as Move-SC + participant Net as Iota-Network + LockingAdmin ->>+ Lib: fn AuditTrailClient::trail(trail_id) + Lib ->>- LockingAdmin: AuditTrailHandle + LockingAdmin ->>+ Lib: fn AuditTrailHandle::locking() + Lib ->>- LockingAdmin: TrailLocking + LockingAdmin ->>+ Lib: fn TrailLocking::update_write_lock(lock) + Lib ->>- LockingAdmin: TransactionBuilder + LockingAdmin ->>+ Lib: fn TransactionBuilder::build_and_execute() + Lib ->>+ Move: main::update_write_lock() + Move ->> Move: validate capability and requested lock + Move ->> Net: update trail locking config + Move ->>- Lib: TX Response + Lib ->>- LockingAdmin: () + IotaTransactionBlockResponse +``` + +#### Deleting an Audit Trail -`audit_trail` is the Rust SDK for reading and writing audit trails on the IOTA ledger. +The lifecycle of an _Audit Trail_ deletion can be described as: -An audit trail is a shared on-chain object that stores a sequential series of records together with: +- Delete all unlocked records with `TrailRecords::delete()` or `TrailRecords::delete_records_batch()` +- Wait until the `Delete Trail Lock` allows trail deletion, if a lock is configured +- Delete the trail object with `AuditTrailHandle::delete_audit_trail()` -- 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 trail deletion process does not remove records automatically. The trail must be empty before +`delete_audit_trail()` can succeed. -The crate provides: +## Glossary -- 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 +- `Audit Trail`: A shared on-chain object that stores ordered records, metadata, locking configuration, tag registry, + roles, and capability state. +- `Record`: A single trail entry stored at a sequence number. Records contain `Data`, optional record metadata, an + optional tag, and creation information. +- `Initial Record`: An optional record created together with the trail. When present, it is stored at sequence number + `0`. +- `Sequence Number`: The numeric position of a record inside a trail. Sequence numbers are used to fetch, delete, and + reason about records. +- `Admin Capability`: The capability object created at trail creation time. It authorizes administrative operations for + the trail. +- `Role`: A named permission set stored inside the trail. Roles define which operations a capability holder may perform. +- `Permission Set`: A collection of permissions such as adding records, deleting records, updating locks, managing tags, + managing metadata, or managing capabilities. +- `Capability`: An owned object that grants one role for one audit trail. Capabilities can optionally be restricted to an + address or a validity window. +- `Record Tag Registry`: The trail-owned list of tags that records may use. Tagged writes must reference a registered + tag. +- `Role Tags`: Optional role-scoped tag restrictions. They narrow which tagged records a role may operate on. +- `Locking Config`: The active locking rules for record deletion, trail deletion, and record writes. +- `Delete Record Window`: A locking rule that controls when individual records can be deleted. +- `Delete Trail Lock`: A time lock that controls when the entire trail can be deleted. +- `Write Lock`: A time lock that controls when new records can be added. +- `Immutable Metadata`: Optional metadata stored at creation time and never updated after the trail is created. +- `Updatable Metadata`: Optional metadata stored on the trail that can be replaced or cleared after creation. +- `Trail Handle`: The typed Rust handle returned by `AuditTrailClient::trail(trail_id)`. It scopes record, access, + locking, tag, metadata, migration, and deletion operations to one audit trail. ## 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. +- [Audit Trails 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. +- [Audit Trails Wasm SDK](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm): JavaScript and TypeScript bindings for browser and Node.js integrations. +- [Audit Trails 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 Notarization Suite. 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. @@ -52,7 +257,7 @@ This README is also used as the crate-level rustdoc entry point, while the sourc ## Contributing -We would love to have you help us with the development of IOTA Audit Trail. Each and every contribution is greatly valued. +We would love to have you help us with the development of the IOTA Notarization Suite. 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/). diff --git a/notarization-rs/README.md b/notarization-rs/README.md index 75be16b..a208d19 100644 --- a/notarization-rs/README.md +++ b/notarization-rs/README.md @@ -1,21 +1,27 @@ -# IOTA Notarization +# IOTA Single Notarization -The Notarization Rust library provides a `NotarizationBuilder` that can be used to create Notarization objects on -the IOTA ledger or to use an already existing Notarization object. The NotarizationBuilder returns a Notarization struct -instance, which is mapped to the Notarization object on the ledger and can be used to interact with the object. +The Single Notarization Rust SDK is the Rust client for individual locked and dynamic notarizations in the IOTA +Notarization Suite. -You can find the full IOTA Notarization documentation [here](https://docs.iota.org/developer/iota-notarization). +The SDK provides a `NotarizationBuilder` that creates notarization objects on the IOTA ledger or connects to existing +notarization objects. The builder returns a `Notarization` struct instance that maps to the on-chain object and provides +typed methods for interacting with it. + +Use Single Notarization when you need one notarized object for arbitrary data, documents, hashes, or latest-state +records. Use Audit Trails when you need a structured record history with roles, capabilities, locking, and tagging. + +You can find the full IOTA Notarization Suite documentation [here](https://docs.iota.org/developer/iota-notarization). ## Process Flows -The following workflows demonstrate how NotarizationBuilder and Notarization instances can be used to create, update and -destroy Notarization objects on the ledger. +The following workflows demonstrate how `NotarizationBuilder` and `Notarization` instances create, update, and destroy +single notarization objects on the ledger. ### Dynamic Notarizations A _Dynamic Notarization_ is created on the ledger using the `NotarizationBuilder::create_dynamic()` function. -To create a _Dynamic Notarization_, the following initial arguments need to be specified using the NotarizationBuilder -setter functions (The used terms can be found in the [glossary below](#glossary)): +To create a _Dynamic Notarization_, specify the following initial arguments with the `NotarizationBuilder` setter +functions. The terms used here are defined in the [glossary below](#glossary). - Initial State consisting of `Stored Data` and `State Metadata` that will be used to define the first version of the Notarization state. @@ -23,8 +29,8 @@ setter functions (The used terms can be found in the [glossary below](#glossary) - Optional `Updatable Metadata` (**Dynamic**: always updatable; **Locked**: immutable) - An optional boolean indicator if the Notarization shall be transferable -After a **dynamic** Notarization has been created, it can be updated using the `Notarization::update_state()` function and can be -destroyed using `Notarization::destroy()`. +After a **dynamic** Notarization has been created, it can be updated using the `Notarization::update_state()` function +and destroyed using `Notarization::destroy()`. **Locked** notarizations are immutable after creation. #### Creating a new Dynamic Notarization on the Ledger @@ -60,7 +66,7 @@ sequenceDiagram Lib ->>- Prover: OnChainNotarization + IotaTransactionBlockResponse ``` -#### Fetching state data from a Notarization already existing on the ledger +#### Fetching state data from an existing Notarization on the ledger The following sequence diagram explains the component interaction for `Verifiers` (or other parties) fetching the `Latest State`: @@ -79,7 +85,7 @@ sequenceDiagram Lib ->>- Verifier: State ``` -#### Updating state data of a Notarization already existing on the ledger +#### Updating state data of an existing Notarization on the ledger The following sequence diagram shows the component interaction in case a `Prover` wants to update the `Latest State` of a Notarization: @@ -111,17 +117,18 @@ sequenceDiagram ### Locked Notarizations -In general _Locked Notarizations_ are handled similar to _Dynamic Notarizations_. A `NotarizationBuilder` for _Locked Notarization_ is created -using the `NotarizationClient::create_locked_notarization()` function. The resulting `NotarizationBuilder` can be used to -create the _Locked Notarization_ on the ledger using the `NotarizationBuilder::finish()` function. +In general, _Locked Notarizations_ are handled similarly to _Dynamic Notarizations_. A `NotarizationBuilder` for a +_Locked Notarization_ is created using the `NotarizationClient::create_locked_notarization()` function. The resulting +`NotarizationBuilder` can be used to create the _Locked Notarization_ on the ledger using the +`NotarizationBuilder::finish()` function. -To create a _Locked Notarization_ the following arguments need to be specified using the `NotarizationBuilder` setter +To create a _Locked Notarization_, specify the following arguments with the `NotarizationBuilder` setter functions: - all arguments needed to create a _Dynamic Notarization_ - Optional Delete Timelock -After the _Locked Notarization_ has been created - by design - the `Latest State` can not bee updated anymore. +After the _Locked Notarization_ has been created, the `Latest State` cannot be updated by design. The lifecycle of a _Locked Notarization_ can be described as: @@ -129,7 +136,7 @@ The lifecycle of a _Locked Notarization_ can be described as: - If a `Delete Timelock` has been used, wait at least until the time-lock has expired - Destroy the Notarization object -As the `Latest State` of a _Locked Notarization_ can not be updated the lifecycle doesn’t include any update processes. +As the `Latest State` of a _Locked Notarization_ cannot be updated, the lifecycle does not include any update processes. ## Glossary @@ -139,12 +146,12 @@ As the `Latest State` of a _Locked Notarization_ can not be updated the lifecycl data; each update completely overwrites the previous stored data. - `Ledger Object`: A single, updatable on-chain object that holds the `Latest State` of the notarized data. It is identified by a unique ObjectId and is modified through update transactions. -- `Transfer Timelock`k: An optional time-locking period during which the `Ledger Object` can not be transfered. -- `Delete Timelock`: An optional time-locking period during which the Ledger Object can not be deleted. +- `Transfer Timelock`: An optional time-locking period during which the `Ledger Object` cannot be transferred. +- `Delete Timelock`: An optional time-locking period during which the `Ledger Object` cannot be deleted. - `State Metadata`: An optional text describing the `Stored Data`. For example, if document hashes of succeeding revisions of a document are stored as `Stored Data`, State Metadata can be used to describe the revision specifier of the document. -- `Latest State`: The most recent version of the `Stored Data` (and optionally theState Metadata) within the +- `Latest State`: The most recent version of the `Stored Data` (and optionally the `State Metadata`) within the `Ledger Object`. In _Dynamic Notarization_, only this latest state is visible on-chain, as previous states are overwritten. As the `Stored Data` and optionally the `State Metadata` together build the `Latest State` they can only be updated together in one function call. @@ -159,16 +166,16 @@ As the `Latest State` of a _Locked Notarization_ can not be updated the lifecycl immutability. - `Immutable Description`: An arbitrary informational String that can be used for example to describe the purpose of the created _Dynamic Notarization_ object, how often it will be updated or other legally important or useful information. - The `Immutable Description` is specified by the `Prover` at creation time and can not be updated after the Notarization - abject has been created. + The `Immutable Description` is specified by the `Prover` at creation time and cannot be updated after the Notarization + object has been created. - `Creation Timestamp`: Indicates when the `Ledger Object` was initially created. - `Immutable Metadata`: Consists of the `Immutable Description` and `Creation Timestamp`. - `Updatable Metadata`: An arbitrary informational String that can be updated at any time by the `Prover` independently - from the `Latest State` (dynamic notarizations only; locked notarizations are immutable). Can be used to provide additional useful information that are subject to change from time to - time. + from the `Latest State` (dynamic notarizations only; locked notarizations are immutable). Can be used to provide + additional useful information that is subject to change from time to time. - `State Version Count`: Numerical value incremented with each update of the `Latest State`. -- `Last State Change Time`: Indicates when the `Latest State` has been updated the last time. +- `Last State Change Time`: Indicates when the `Latest State` was last updated. - `Calculated Metadata`: Consists of the `State Version Count` and `Last State Change Time` -- `Notarized Record`: Some information owned by the `Prover` that describe and include notarized data, so that these data +- `Notarized Record`: Some information owned by the `Prover` that describes and includes notarized data, so that this data can be verified by a `Verifier`. In the context of the _Dynamic Notarization_ method, the latest version of subsequent versions of a `Notarized Record` is the `Latest State`.