PoC: modularize executor and simplify Wasm I/O with permissionless and permissioned scenarios

Cargo.toml

@@ -4,11 +4,18 @@ version = "0.1.0"
 edition = "2024"
 
 [workspace]
+resolver = "3"
 members = [
     "host",
-    "wasm_instruction",
-    "authorizer"
-, "common"]
+    "guest/instruction",
+    "guest/authorizer",
+]
 
 [workspace.dependencies]
-wasmtime = "33.0"
+derive_more = { version = "2.0", features = ["full"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+wasmtime = { version = "33.0", features = ["component-model"] }
+wasmtime-wasi = "33.0"
+# wasmtime = "33.0"
+wit-bindgen = "0.42" 

README.md

@@ -0,0 +1,87 @@
+# Executor Modularization & WasmInstruction I/O Simplification PoC
+
+This proof-of-concept explores splitting Hyperledger Iroha’s _Executor_ into modular pieces and slimming down _WasmInstruction_ I/O. The inspiration comes from:
+
+- <https://github.com/hyperledger-iroha/iroha/issues/5357>
+- <https://github.com/hyperledger-iroha/iroha/issues/5358> (see state-transition diagram)
+
+These occupy a key position within tracking issue [#5356](https://github.com/hyperledger-iroha/iroha/issues/5356):
+
+![big_picture_in_5356.png](big_picture_in_5356.png)
+
+## Objective
+
+Can we cleanly separate instruction execution into three roles?
+
+1. _WasmInstruction_: collects read/write intents without directly mutating state
+2. _Authorizer_: evaluates intents against permission rules (approve or reject)
+3. _Host runtime_: initiates the instruction flow, batches intents for the authorizer, and applies them to state
+
+Success means smaller, testable components, fewer FFI round-trips, and clearer extension points.
+
+## Repository Structure
+
+```text
+.
+├── guest/
+│   ├── authorizer/          — Wasm component that enforces permissions
+│   └── instruction/         — Wasm component that submits read/write intents
+├── host/                    — Rust runtime and tests
+├── wit/                     — Shared WIT interfaces
+└── README.md
+```
+
+## Building & Testing
+
+### Prerequisites
+
+```bash
+rustup target add wasm32-wasip2
+```
+
+```bash
+cargo add wit-bindgen
+```
+
+### Guest components
+
+```bash
+cargo build --target wasm32-wasip2 --manifest-path guest/instruction/Cargo.toml
+```
+
+```bash
+cargo build --target wasm32-wasip2 --manifest-path guest/authorizer/Cargo.toml
+```
+
+### Host tests
+
+```bash
+cargo test --package host --lib
+```
+
+```bash
+cargo test --package host --lib -- tests::instruction_flows --exact --show-output
+```
+
+Compare the test steps to the #5358 state-transition diagram for clarity.
+
+## Developer Notes
+
+### Host vs. guest, imports vs. exports
+
+- `wasmtime::component::bindgen!` is used on the _host_ side to implement _import_ functions.
+- `wit_bindgen::generate!` is used on the _guest_ side to implement _export_ functions.
+
+### [Component model](https://component-model.bytecodealliance.org/introduction.html) trade-offs
+
+- Removes all `unsafe` blocks around FFI calls, making future development and maintenance easier:
+  > By expressing higher-level semantics than integers and floats, it becomes possible to statically analyse and reason about a component's behaviour - to enforce and guarantee properties just by looking at the surface of the component.
+- Wasm _components_ typically produce larger binaries than classic _modules_—keep that in mind.
+
+### Future developer experience
+
+- Consider `guest/instruction/src/lib.rs` as a reference implementation of smart contracts and trigger executables. It’s intentionally verbose now; later we can introduce syntax sugars.
+
+---
+
+_This PoC is experimental and exists solely to test the feasibility of the referenced Iroha issues._

authorizer/Cargo.toml → guest/authorizer/Cargo.toml

@@ -7,3 +7,4 @@ edition.workspace = true
 crate-type = ["cdylib"]
 
 [dependencies]
+wit-bindgen = { workspace = true}

guest/authorizer/src/lib.rs

@@ -0,0 +1,91 @@
+use poc::wit::types::*;
+
+wit_bindgen::generate!({
+    world: "universe",
+    path: "../../wit",
+});
+
+struct Authorizer;
+
+/// Default implementation for permission validation.
+impl Guest for Authorizer {
+    fn read_request(_args: String) -> ReadSet {
+        unimplemented!("boilerplate");
+    }
+
+    fn read_approval(signals: ReadSet, receptors: AllowSet) -> bool {
+        let mut signals = signals;
+        signals.inner.retain(|signal| {
+            let approved = receptors.inner.iter().any(|receptor| {
+                let captures = receptor.key.captures(&signal.key);
+                let NodeValueAllow::AccountAsset(AccountAssetA { bit_mask }) = receptor.value;
+                let passes = 0b0000_0001 & !bit_mask == 0;
+                captures && passes
+            });
+
+            !approved
+        });
+
+        signals.inner.is_empty()
+    }
+
+    fn write_request(_view: ViewSet, _args: String) -> WriteSet {
+        unimplemented!("boilerplate");
+    }
+
+    fn write_approval(signals: EventSet, receptors: AllowSet) -> bool {
+        let mut signals = signals;
+        signals.inner.retain(|signal| {
+            let NodeValueEvent::AccountAsset(AccountAssetE { status_bit }) = signal.value;
+            let receptors = receptors
+                .inner
+                .iter()
+                .filter(|receptor| receptor.key.captures(&signal.key));
+            let Some(bit_mask_union) = receptors
+                .map(|entry| {
+                    let NodeValueAllow::AccountAsset(AccountAssetA { bit_mask }) = entry.value;
+                    bit_mask
+                })
+                .reduce(|acc, bit| acc | bit)
+            else {
+                return false;
+            };
+
+            let approved = status_bit & !bit_mask_union == 0;
+            !approved
+        });
+
+        signals.inner.is_empty()
+    }
+}
+
+export!(Authorizer);
+
+// TODO: move common types to separate crate from host
+pub trait Capture<T> {
+    fn captures(&self, candidate: &T) -> bool;
+}
+
+impl Capture<NodeKey> for FuzzyNodeKey {
+    fn captures(&self, key: &NodeKey) -> bool {
+        let (
+            FuzzyNodeKey::AccountAsset(FuzzyCompositeKey { e0: z0, e1: z1 }),
+            NodeKey::AccountAsset(CompositeKey { e0, e1 }),
+        ) = (self, key);
+        z0.as_ref().is_none_or(|z0| z0 == e0) && z1.as_ref().is_none_or(|z1| z1 == e1)
+    }
+}
+
+impl Capture<FuzzyNodeKey> for FuzzyNodeKey {
+    fn captures(&self, candidate: &FuzzyNodeKey) -> bool {
+        let (
+            FuzzyNodeKey::AccountAsset(FuzzyCompositeKey { e0: z0, e1: z1 }),
+            FuzzyNodeKey::AccountAsset(FuzzyCompositeKey { e0, e1 }),
+        ) = (self, candidate);
+        z0.as_ref()
+            .is_none_or(|z0| e0.as_ref().is_some_and(|e0| z0 == e0))
+            && z1
+                .as_ref()
+                .is_none_or(|z1| e1.as_ref().is_some_and(|e1| z1 == e1))
+    }
+}

guest/instruction/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "instruction"
+version.workspace = true
+edition.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+wit-bindgen = { workspace = true}

guest/instruction/src/lib.rs

@@ -0,0 +1,81 @@
+use poc::wit::types::*;
+use serde::Deserialize;
+
+wit_bindgen::generate!({
+    world: "universe",
+    path: "../../wit",
+});
+
+struct SupplyAll;
+
+#[derive(Debug, Deserialize)]
+struct Args {
+    // Name of the asset to supply
+    asset: String,
+    // Account balances below this threshold will be supplied
+    threshold: u32,
+    // Amount to supply to accounts
+    supply_amount: u32,
+    // The supplier account
+    supplier: String,
+}
+
+impl Guest for SupplyAll {
+    fn read_request(args: String) -> ReadSet {
+        let args: Args = serde_json::from_str(&args).expect("wrong args");
+
+        let inner = vec![ReadEntry {
+            key: FuzzyNodeKey::AccountAsset(FuzzyCompositeKey {
+                e0: None,
+                e1: Some(args.asset.to_string()),
+            }),
+            value: NodeValueRead::AccountAsset,
+        }];
+
+        ReadSet { inner }
+    }
+
+    fn read_approval(_signals: ReadSet, _receptors: AllowSet) -> bool {
+        unimplemented!("boilerplate");
+    }
+
+    fn write_request(view: ViewSet, args: String) -> WriteSet {
+        let args: Args = serde_json::from_str(&args).expect("wrong args");
+
+        let inner = view
+            .inner
+            .into_iter()
+            .filter_map(|entry| {
+                let NodeValueView::AccountAsset(value) = entry.value;
+                (value.balance < args.threshold).then(|| {
+                    vec![
+                        WriteEntry {
+                            key: entry.key,
+                            value: NodeValueWrite::AccountAsset(AccountAssetW::Receive(
+                                args.supply_amount,
+                            )),
+                        },
+                        WriteEntry {
+                            key: NodeKey::AccountAsset(CompositeKey {
+                                e0: args.supplier.clone(),
+                                e1: args.asset.clone(),
+                            }),
+                            value: NodeValueWrite::AccountAsset(AccountAssetW::Send(
+                                args.supply_amount,
+                            )),
+                        },
+                    ]
+                })
+            })
+            .flatten()
+            .collect();
+
+        WriteSet { inner }
+    }
+
+    fn write_approval(_signals: EventSet, _receptors: AllowSet) -> bool {
+        unimplemented!("boilerplate");
+    }
+}
+
+export!(SupplyAll);

host/Cargo.toml

@@ -4,3 +4,8 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+derive_more = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+wasmtime = { workspace = true }
+wasmtime-wasi = { workspace = true }