chore: unify Proof of Inclusion examples and streamline build process

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

@@ -202,19 +202,14 @@ jobs:
 
       - name: Run Rust examples
         # run examples only on ubuntu for now
-        if: matrix.os == 'ubuntu-24.04'
-        run: |
-          cargo metadata --format-version 1 --manifest-path ./examples/Cargo.toml | \
-          jq -r '.packages[] | select(.name == "examples") | .targets[].name' | \
-          awk '$1 ~ /[0-9].*/' | \
-          parallel -k -j 4 --retries 3 --joblog report.log ./target/release/examples/{}
-          cat report.log
-
-      - name: Run Proof of Inclusion Rust examples
         if: matrix.os == 'ubuntu-24.04'
         run: |
           export IOTA_GENESIS_PATH="$HOME/.iota/iota_config/genesis.blob"
-          ./examples/poi/run.sh
+          cargo metadata --format-version 1 --no-deps --manifest-path ./examples/Cargo.toml | \
+          jq -r '.packages[] | select(.name == "examples") | .targets[] |
+            select(.kind | index("example")) | .name' | \
+          parallel -k -j 1 --retries 3 --joblog report.log ./target/release/examples/{}
+          cat report.log
 
       - name: Archive server logs
         if: ${{ env.IOTA_SERVER_LOGFILE }}

Cargo.toml

@@ -8,7 +8,7 @@ rust-version = "1.85"
 
 [workspace]
 resolver = "2"
-members = ["audit-trail-rs", "examples", "examples/poi", "notarization-rs", "poi-rs"]
+members = ["audit-trail-rs", "examples", "notarization-rs", "poi-rs"]
 exclude = [
   "bindings/wasm/notarization_wasm",
   "bindings/wasm/audit_trail_wasm",

examples/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2024"
 publish = false
 
 [lib]
-path = "notarization/utils.rs"
+path = "utils.rs"
 
 [[example]]
 name = "01_create_locked_notarization"
@@ -108,14 +108,52 @@ path = "audit-trail/real-world/02_clinical_trial.rs"
 name = "03_digital_product_passport"
 path = "audit-trail/real-world/03_digital_product_passport.rs"
 
+[[example]]
+name = "01_transaction_proof"
+path = "poi/01_transaction_proof.rs"
+
+[[example]]
+name = "02_multi_target_proof"
+path = "poi/02_multi_target_proof.rs"
+
+[[example]]
+name = "03_reuse_verifier"
+path = "poi/03_reuse_verifier.rs"
+
+[[example]]
+name = "04_object_proof"
+path = "poi/04_object_proof.rs"
+
+[[example]]
+name = "05_event_proof"
+path = "poi/05_event_proof.rs"
+
+[[example]]
+name = "advanced_01_committee_cache"
+path = "poi/advanced/01_committee_cache.rs"
+
+[[example]]
+name = "advanced_02_trusted_node"
+path = "poi/advanced/02_trusted_node.rs"
+
 [dependencies]
 anyhow.workspace = true
+async-trait.workspace = true
 audit_trails = { path = "../audit-trail-rs" }
+bcs.workspace = true
 chrono.workspace = true
+iota-config = { git = "https://github.com/iotaledger/iota.git", tag = "v1.29.0" }
+iota-grpc-client.workspace = true
 iota-sdk.workspace = true
 iota-sdk-types.workspace = true
+iota-types.workspace = true
+iota_interaction = { workspace = true, features = ["keytool"] }
 notarization = { path = "../notarization-rs" }
+poi-rs = { path = "../poi-rs" }
 product_common = { workspace = true, features = ["core-client", "test-utils", "transaction"] }
+reqwest.workspace = true
+serde.workspace = true
 serde_json.workspace = true
 sha2.workspace = true
+tempfile.workspace = true
 tokio.workspace = true

examples/audit-trail/run.sh

@@ -30,6 +30,7 @@ examples=(
     "09_tagged_records"
     "10_capability_constraints"
     "11_manage_record_tags"
+    "12_correct_records"
     "01_customs_clearance"
     "02_clinical_trial"
     "03_digital_product_passport"

examples/poi/01_transaction_proof.rs

@@ -17,7 +17,7 @@
 //! different security roles: the endpoint supplies evidence, while the genesis blob establishes trust.
 
 use anyhow::{Context, Result, ensure};
-use poi_examples::prepare_poi_example;
+use examples::prepare_poi_example;
 use poi_rs::{CommitteeResolution, Proof};
 
 /// Demonstrates how to:

examples/poi/02_multi_target_proof.rs

@@ -12,7 +12,7 @@
 //! the selected transaction; the builder rejects targets from another transaction.
 
 use anyhow::{Context, Result, ensure};
-use poi_examples::prepare_poi_example;
+use examples::prepare_poi_example;
 use poi_rs::CommitteeResolution;
 
 /// Demonstrates how to:

examples/poi/03_reuse_verifier.rs

@@ -13,7 +13,7 @@
 //! authenticated while verifying the first proof.
 
 use anyhow::{Context, Result};
-use poi_examples::prepare_poi_example;
+use examples::prepare_poi_example;
 use poi_rs::CommitteeResolution;
 
 /// Demonstrates how to:

examples/poi/04_object_proof.rs

@@ -14,7 +14,7 @@
 //! blob, independently of the node that supplied the proof evidence.
 
 use anyhow::{Context, Result, ensure};
-use poi_examples::prepare_poi_example;
+use examples::prepare_poi_example;
 use poi_rs::CommitteeResolution;
 
 /// Demonstrates how to:

examples/poi/05_event_proof.rs

@@ -15,7 +15,7 @@
 //! blob, independently of the node that supplied the proof evidence.
 
 use anyhow::{Context, Result, ensure};
-use poi_examples::prepare_poi_example;
+use examples::prepare_poi_example;
 use poi_rs::CommitteeResolution;
 
 /// Demonstrates how to:

examples/poi/README.md

@@ -2,6 +2,9 @@
 
 ## Introduction
 
+These examples are targets in the shared [`examples`](../Cargo.toml) Cargo package, alongside
+the Single Notarization and Audit Trails examples.
+
 These Rust examples create fresh ledger activity and use it to construct and verify portable IOTA Proof of Inclusion
 proofs. Each example reads the active IOTA CLI environment and wallet, creates a locked `Notarization` object, and uses
 the resulting transaction, object, or event as its proof target.
@@ -64,14 +67,14 @@ verifier's trust boundary.
 Run an example from the repository root:
 
 ```bash
-cargo run --release -p poi-examples --example 01_transaction_proof
+cargo run --release -p examples --example 01_transaction_proof
 ```
 
 For localnet genesis-anchored examples, provide the genesis blob created by that local network:
 
 ```bash
 export IOTA_GENESIS_PATH=/path/to/localnet/genesis.blob
-cargo run --release -p poi-examples --example 01_transaction_proof
+cargo run --release -p examples --example 01_transaction_proof
 ```
 
 The focused runner executes every example:

examples/poi/advanced/01_committee_cache.rs

@@ -15,8 +15,8 @@
 use std::time::Instant;
 
 use anyhow::{Context, Result};
+use examples::prepare_poi_example;
 use file_committee_cache::FileCommitteeCache;
-use poi_examples::prepare_poi_example;
 use poi_rs::CommitteeResolution;
 
 /// Demonstrates how to:

examples/poi/advanced/02_trusted_node.rs

@@ -11,7 +11,7 @@
 //! must be operated by a party the verifier trusts.
 
 use anyhow::{Context, Result};
-use poi_examples::prepare_poi_example;
+use examples::prepare_poi_example;
 use poi_rs::CommitteeResolution;
 
 /// Demonstrates trusted-node committee resolution against a trusted endpoint.

examples/poi/run.sh

@@ -13,13 +13,13 @@ echo "Genesis-anchored examples run in separate processes and may repeat the com
 echo "On mainnet, all eight transactions consume paid gas from the active wallet."
 echo ""
 
-cargo run --release -p poi-examples --example 01_transaction_proof
-cargo run --release -p poi-examples --example 02_multi_target_proof
-cargo run --release -p poi-examples --example 03_reuse_verifier
-cargo run --release -p poi-examples --example 04_object_proof
-cargo run --release -p poi-examples --example 05_event_proof
-cargo run --release -p poi-examples --example advanced_01_committee_cache
-cargo run --release -p poi-examples --example advanced_02_trusted_node
+cargo run --release -p examples --example 01_transaction_proof
+cargo run --release -p examples --example 02_multi_target_proof
+cargo run --release -p examples --example 03_reuse_verifier
+cargo run --release -p examples --example 04_object_proof
+cargo run --release -p examples --example 05_event_proof
+cargo run --release -p examples --example advanced_01_committee_cache
+cargo run --release -p examples --example advanced_02_trusted_node
 
 echo ""
 echo "All Proof of Inclusion examples completed successfully!"

examples/poi/utils.rs

@@ -26,7 +26,7 @@ const GRPC_URL_ENV: &str = "NETWORK_GRPC_URL";
 const GENESIS_PATH_ENV: &str = "IOTA_GENESIS_PATH";
 const PUBLISH_SCRIPT_FILE: &str = concat!(
     env!("CARGO_MANIFEST_DIR"),
-    "/../../notarization-move/scripts/publish_package.sh"
+    "/../notarization-move/scripts/publish_package.sh"
 );
 
 /// Clients and network metadata shared by the Rust Proof of Inclusion examples.
@@ -174,7 +174,7 @@ pub async fn prepare_poi_example() -> Result<PoiContext> {
         );
     }
 
-    let package_cache_directory = concat!(env!("CARGO_MANIFEST_DIR"), "/../../target/poi-examples");
+    let package_cache_directory = concat!(env!("CARGO_MANIFEST_DIR"), "/../target/poi-examples");
     fs::create_dir_all(package_cache_directory).context("failed to create the package cache directory")?;
     let package_cache_file = format!("{package_cache_directory}/notarization-package-{chain_identifier}.txt");
     let cached_package_id = get_cached_id(&chain_identifier, Some(&package_cache_file))

examples/run.sh

@@ -1,22 +1,20 @@
 #!/bin/bash
 
+set -e
+
 # Script to run all examples contained in this directory
 # Usage: ./run.sh
 # Make sure to set the following environment variables:
 # - IOTA_NOTARIZATION_PKG_ID: The package ID of the notarization module
 # - IOTA_AUDIT_TRAIL_PKG_ID: The package ID of the audit trail module
 # - IOTA_TF_COMPONENTS_PKG_ID: The package ID of the tf components module
+# - IOTA_GENESIS_PATH: The trusted genesis blob for PoI on local or custom networks
+# PoI uses the active IOTA CLI environment and wallet; see examples/poi/README.md.
 
 ./examples/audit-trail/run.sh
 printf "\n================================\n"
 printf "================================\n\n"
 
-# At the moment the `examples` folder contains all single notarization (SN) examples.
-# After a `notarization` folder has been introduced to contain the SN examples,
-# uncomment the following line, update the paths in Cargo.toml and move the bash code below that line into `./examples/notarization/run.sh`.
-
-# ./examples/notarization/run.sh
-
 # Script to run all notarization examples
 # Usage: ./run.sh
 # Make sure to set IOTA_NOTARIZATION_PKG_ID environment variable
@@ -57,3 +55,5 @@ done
 
 echo ""
 echo "All Notarization examples completed successfully!"
+
+./examples/poi/run.sh

examples/utils.rs

@@ -0,0 +1,13 @@
+// Copyright 2020-2026 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+#[path = "notarization/utils.rs"]
+mod notarization;
+#[path = "poi/utils.rs"]
+mod poi;
+
+pub use notarization::{
+    get_funded_audit_trail_client, get_funded_notarization_client, get_notarization_read_only_client,
+    issue_tagged_record_role,
+};
+pub use poi::{NotarizationTargets, PoiContext, prepare_poi_example};