Merge pull request #44 from iotaledger/feat/add-examples

feat: add e2e tests and examples

Author: itsyaasir

.github/workflows/build-and-test-move.yml

@@ -1,4 +1,4 @@
-name: Build and Test
+name: Build and Test Move
 
 on:
   pull_request:
@@ -37,7 +37,7 @@ jobs:
       - run: |
           # this run step does nothing, but is needed to get the job output
 
-  build-and-test:
+  build-and-test-move:
     runs-on: ${{ matrix.os }}
     needs: check-for-run-condition
     if: ${{ needs.check-for-run-condition.outputs.should-run == 'true' && github.event_name != 'workflow_dispatch' }}

Cargo.toml

@@ -8,7 +8,7 @@ rust-version = "1.65"
 
 [workspace]
 resolver = "2"
-members = ["notarization-rs"]
+members = ["notarization-rs", "examples"]
 
 [workspace.dependencies]
 anyhow = "1.0"

examples/01_create_locked_notarization.rs

@@ -0,0 +1,57 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use anyhow::Result;
+use examples::get_funded_client;
+use notarization::core::state::State;
+use notarization::core::timelock::TimeLock;
+use notarization::core::NotarizationMethod;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    println!("Creating a locked notarization example");
+
+    // Create a notarization client
+    let notarization_client = get_funded_client().await?;
+
+    // Calculate unlock time (24 hours from now)
+    let now_ts = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs();
+    let unlock_at = now_ts + 86400; // 24 hours
+
+    println!("Creating locked notarization with delete lock until: {}", unlock_at);
+
+    // Create a locked notarization with state and delete lock
+    let locked_notarization = notarization_client
+        .create_locked_notarization()
+        .with_state(State::from_string(
+            "Important document content".to_string(),
+            Some("Document metadata".to_string()),
+        ))
+        .with_immutable_description("Critical legal document".to_string())
+        .with_updateable_metadata("Initial document metadata".to_string())
+        .with_delete_at(TimeLock::UnlockAt(unlock_at as u32))
+        .finish()?
+        .build_and_execute(&notarization_client)
+        .await?
+        .output;
+
+    println!("✅ Locked notarization created successfully!");
+    println!("Notarization ID: {:?}", locked_notarization.id);
+    println!("Method: {:?}", locked_notarization.method);
+    println!("Description: {:?}", locked_notarization.immutable_metadata.description);
+    println!("Updateable metadata: {:?}", locked_notarization.updateable_metadata);
+    println!("State version count: {}", locked_notarization.state_version_count);
+
+    // Verify the notarization method is locked
+    assert_eq!(locked_notarization.method, NotarizationMethod::Locked);
+
+    // Check if it has locking metadata
+    assert!(locked_notarization.immutable_metadata.locking.is_some());
+
+    println!("🔒 The notarization is locked and cannot be updated or transferred until destroyed");
+    println!("🗑️ The notarization can only be destroyed after the delete lock expires");
+
+    Ok(())
+}

examples/02_create_dynamic_notarization.rs

@@ -0,0 +1,74 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use anyhow::Result;
+use examples::get_funded_client;
+use notarization::core::state::State;
+use notarization::core::timelock::TimeLock;
+use notarization::core::NotarizationMethod;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    println!("Creating a dynamic notarization example");
+
+    // Create a notarization client
+    let notarization_client = get_funded_client().await?;
+
+    println!("Creating a simple dynamic notarization without locks...");
+
+    // Create a simple dynamic notarization
+    let simple_notarization = notarization_client
+        .create_dynamic_notarization()
+        .with_state(State::from_string(
+            "Live document content".to_string(),
+            Some("Version 1.0".to_string()),
+        ))
+        .with_immutable_description("Dynamic document".to_string())
+        .with_updateable_metadata("Initial metadata".to_string())
+        .finish()
+        .build_and_execute(&notarization_client)
+        .await?
+        .output;
+
+    println!("✅ Simple dynamic notarization created!");
+    println!("ID: {:?}", simple_notarization.id);
+
+    // Calculate unlock time for transfer lock example
+    let now_ts = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs();
+    let unlock_at = now_ts + 3600; // 1 hour
+
+    println!("\nCreating a dynamic notarization with transfer lock...");
+
+    // Create a dynamic notarization with transfer lock
+    let locked_transfer_notarization = notarization_client
+        .create_dynamic_notarization()
+        .with_state(State::from_string("Transfer-locked content".to_string(), None))
+        .with_immutable_description("Transfer-locked document".to_string())
+        .with_transfer_lock(TimeLock::UnlockAt(unlock_at as u32))
+        .finish()
+        .build_and_execute(&notarization_client)
+        .await?
+        .output;
+
+    println!("✅ Transfer-locked dynamic notarization created!");
+    println!("ID: {:?}", locked_transfer_notarization.id);
+
+    // Verify both are dynamic notarizations
+    assert_eq!(simple_notarization.method, NotarizationMethod::Dynamic);
+    assert_eq!(locked_transfer_notarization.method, NotarizationMethod::Dynamic);
+
+    // Check transfer lock status
+    let is_transfer_locked = notarization_client
+        .is_transfer_locked(*locked_transfer_notarization.id.object_id())
+        .await?;
+
+    println!("\n📊 Notarization Status:");
+    println!("Simple notarization - Method: {:?}", simple_notarization.method);
+    println!("Transfer-locked notarization - Transfer locked: {}", is_transfer_locked);
+    println!("\n🔄 Dynamic notarizations can be updated and transferred (unless transfer-locked)");
+    println!("📝 State and metadata can be modified over time");
+
+    Ok(())
+}

examples/03_update_dynamic_notarization.rs

@@ -0,0 +1,70 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use anyhow::Result;
+use examples::get_funded_client;
+use notarization::core::state::State;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    println!("Demonstrating update on dynamic notarization");
+
+    let notarization_client = get_funded_client().await?;
+
+    println!("Creating a dynamic notarization...");
+
+    // Create a dynamic notarization
+    let dynamic_notarization_id = notarization_client
+        .create_dynamic_notarization()
+        .with_state(State::from_string(
+            "Original content".to_string(),
+            Some("Original metadata".to_string()),
+        ))
+        .with_immutable_description("Dynamic document for update test".to_string())
+        .with_updateable_metadata("Initial updateable metadata".to_string())
+        .finish()
+        .build_and_execute(&notarization_client)
+        .await?
+        .output
+        .id;
+
+    println!("✅ Dynamic notarization created with ID: {:?}", dynamic_notarization_id);
+
+    let current_state = notarization_client.state(*dynamic_notarization_id.object_id()).await?;
+    println!("Initial state: {}", current_state.data.as_text()?);
+    println!("Initial state metadata: {:?}", current_state.metadata);
+
+    println!("\n🔄 Updating state on dynamic notarization...");
+    let new_state = State::from_string("Updated content".to_string(), Some("New metadata".to_string()));
+
+    let state_update_result = notarization_client
+        .update_state(new_state, *dynamic_notarization_id.object_id())
+        .build_and_execute(&notarization_client)
+        .await;
+
+    match state_update_result {
+        Ok(_) => println!("✅ State update succeeded"),
+        Err(e) => println!("❌ State update failed - {}", e),
+    }
+
+    println!("\n📝 Updating metadata on dynamic notarization...");
+    let new_metadata = Some("Updated metadata".to_string());
+
+    let metadata_update_result = notarization_client
+        .update_metadata(new_metadata, *dynamic_notarization_id.object_id())
+        .build_and_execute(&notarization_client)
+        .await;
+
+    match metadata_update_result {
+        Ok(_) => println!("✅ Metadata update succeeded"),
+        Err(e) => println!("❌ Metadata update failed - {}", e),
+    }
+
+    let current_state = notarization_client.state(*dynamic_notarization_id.object_id()).await?;
+    println!("Updated state: {}", current_state.data.as_text()?);
+    println!("Updated state metadata: {:?}", current_state.metadata);
+
+    println!("\n🔒 Dynamic notarizations are mutable - state and metadata can be changed");
+
+    Ok(())
+}

examples/04_destroy_notarization.rs

@@ -0,0 +1,166 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use anyhow::Result;
+use examples::get_funded_client;
+use notarization::core::state::State;
+use notarization::core::timelock::TimeLock;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    println!("Demonstrating notarization destruction scenarios");
+
+    // Create a notarization client
+    let notarization_client = get_funded_client().await?;
+
+    // Scenario 1: Destroy an unlocked dynamic notarization (should succeed)
+    println!("📝 Scenario 1: Creating and destroying an unlocked dynamic notarization...");
+
+    let unlocked_dynamic_id = notarization_client
+        .create_dynamic_notarization()
+        .with_state(State::from_string("Unlocked content".to_string(), None))
+        .with_immutable_description("Unlocked dynamic document".to_string())
+        .finish()
+        .build_and_execute(&notarization_client)
+        .await?
+        .output
+        .id;
+
+    println!("✅ Created unlocked dynamic notarization: {:?}", unlocked_dynamic_id);
+
+    // Check if destroy is allowed
+    let is_destroy_allowed = notarization_client
+        .is_destroy_allowed(*unlocked_dynamic_id.object_id())
+        .await?;
+
+    println!("🔍 Destroy allowed: {}", is_destroy_allowed);
+
+    // Destroy the unlocked notarization
+    let destroy_result = notarization_client
+        .destroy(*unlocked_dynamic_id.object_id())
+        .build_and_execute(&notarization_client)
+        .await;
+
+    match destroy_result {
+        Ok(_) => println!("✅ Successfully destroyed unlocked dynamic notarization"),
+        Err(e) => println!("❌ Failed to destroy: {}", e),
+    }
+
+    // Scenario 2: Try to destroy a transfer-locked dynamic notarization (should fail)
+    println!("\n📝 Scenario 2: Creating a transfer-locked dynamic notarization...");
+
+    let now_ts = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs();
+    let unlock_at = now_ts + 86400; // 24 hours
+
+    let transfer_locked_id = notarization_client
+        .create_dynamic_notarization()
+        .with_state(State::from_string("Transfer-locked content".to_string(), None))
+        .with_immutable_description("Transfer-locked document".to_string())
+        .with_transfer_lock(TimeLock::UnlockAt(unlock_at as u32))
+        .finish()
+        .build_and_execute(&notarization_client)
+        .await?
+        .output
+        .id;
+
+    println!(
+        "✅ Created transfer-locked dynamic notarization: {:?}",
+        transfer_locked_id
+    );
+
+    let is_destroy_allowed = notarization_client
+        .is_destroy_allowed(*transfer_locked_id.object_id())
+        .await?;
+
+    println!("🔍 Destroy allowed: {}", is_destroy_allowed);
+
+    // Try to destroy the transfer-locked notarization
+    let destroy_result = notarization_client
+        .destroy(*transfer_locked_id.object_id())
+        .build_and_execute(&notarization_client)
+        .await;
+
+    match destroy_result {
+        Ok(_) => println!("❌ Unexpected: Destruction succeeded (should have failed)"),
+        Err(e) => println!("✅ Expected: Destruction failed - {}", e),
+    }
+
+    // Scenario 3: Create and try to destroy a time-locked locked notarization (should fail)
+    println!("\n📝 Scenario 3: Creating a time-locked locked notarization...");
+
+    let delete_locked_id = notarization_client
+        .create_locked_notarization()
+        .with_state(State::from_string("Delete-locked content".to_string(), None))
+        .with_immutable_description("Delete-locked document".to_string())
+        .with_delete_at(TimeLock::UnlockAt(unlock_at as u32))
+        .finish()?
+        .build_and_execute(&notarization_client)
+        .await?
+        .output
+        .id;
+
+    println!("✅ Created delete-locked locked notarization: {:?}", delete_locked_id);
+
+    let is_destroy_allowed = notarization_client
+        .is_destroy_allowed(*delete_locked_id.object_id())
+        .await?;
+
+    println!("🔍 Destroy allowed: {}", is_destroy_allowed);
+
+    // Try to destroy the delete-locked notarization
+    let destroy_result = notarization_client
+        .destroy(*delete_locked_id.object_id())
+        .build_and_execute(&notarization_client)
+        .await;
+
+    match destroy_result {
+        Ok(_) => println!("❌ Unexpected: Destruction succeeded (should have failed)"),
+        Err(e) => println!("✅ Expected: Destruction failed - {}", e),
+    }
+
+    // Scenario 4: Create and destroy a locked notarization with no delete lock (should succeed)
+    println!("\n📝 Scenario 4: Creating a locked notarization with no delete lock...");
+
+    let no_delete_lock_id = notarization_client
+        .create_locked_notarization()
+        .with_state(State::from_string("No delete lock content".to_string(), None))
+        .with_immutable_description("No delete lock document".to_string())
+        .with_delete_at(TimeLock::None)
+        .finish()?
+        .build_and_execute(&notarization_client)
+        .await?
+        .output
+        .id;
+
+    println!(
+        "✅ Created locked notarization with no delete lock: {:?}",
+        no_delete_lock_id
+    );
+
+    let is_destroy_allowed = notarization_client
+        .is_destroy_allowed(*no_delete_lock_id.object_id())
+        .await?;
+
+    println!("🔍 Destroy allowed: {}", is_destroy_allowed);
+
+    // Destroy the notarization with no delete lock
+    let destroy_result = notarization_client
+        .destroy(*no_delete_lock_id.object_id())
+        .build_and_execute(&notarization_client)
+        .await;
+
+    match destroy_result {
+        Ok(_) => println!("✅ Successfully destroyed locked notarization with no delete lock"),
+        Err(e) => println!("❌ Failed to destroy: {}", e),
+    }
+
+    println!("\n📋 Summary:");
+    println!("🔓 Unlocked notarizations can be destroyed immediately");
+    println!("🔒 Transfer-locked dynamic notarizations cannot be destroyed");
+    println!("⏰ Time-locked locked notarizations cannot be destroyed before lock expires");
+    println!("🆓 Locked notarizations with TimeLock::None can be destroyed");
+
+    Ok(())
+}