update readme

README.md

@@ -2,38 +2,45 @@
 
 ![marine version on crates.io](https://img.shields.io/crates/v/marine?color=green&style=flat-square)
 
-Marine is a modern general purpose Wasm runtime based on the [Component model](https://github.com/WebAssembly/component-model), it runs multi-module Wasm applications with interface-types and shared-nothing linking scheme. This execution model suits well for different scenarios, especially for applications based on the [entity component system](https://en.wikipedia.org/wiki/Entity_component_system) (ECS) pattern or architecture based on plugins.
+Marine is a modern general purpose Wasm runtime based on the [component model](https://github.com/WebAssembly/component-model) capable of running multi-module Wasm applications, aka services, with [interface-types](https://github.com/WebAssembly/interface-types) and a [shared-nothing linking](https://training.linuxfoundation.org/blog/how-and-why-to-link-webassembly-modules/) scheme. This execution model is well suited for a variety of scenarios and especially applicable to implementations following the [entity component system](https://en.wikipedia.org/wiki/Entity_component_system) (ECS) pattern or plugin-based architectures.
 
-Fluence [nodes](https://github.com/fluencelabs/fluence) use Marine to execute Wasm services composed by compiled [Aqua](https://github.com/fluencelabs/aqua).
+Fluence peers, such as Fluence [Rust node](https://github.com/fluencelabs/fluence), include Marine to execute the hosted Wasm services composed with [Aqua](https://github.com/fluencelabs/aqua).
 
 ## Motivational example
 
-The most archetypal example to meet the power of Marine is a multi-module Wasm application. Let's consider [this](./examples/motivational-example) one consists of two modules: 
+To illustrate the capabilities of Marine, let's have a look at a multi-module Wasm service as implemented in [this](./examples/motivational-example) example.
+
+`cd` into the `examples/motivational-example` directory and have a look at the  `shrek/src/main.rs` file: 
+
 ```rust
+// examples/motivational-example/shrek/src/main.rs
 use marine_rs_sdk::marine;
 
 fn main() {}
 
 #[marine]
 pub fn greeting(name: &str) -> Vec<String> {
-    let donkey_greeting = donkey::greeting(name);
-    let shrek_greeting = format!("Shrek: hi, {}", name);
+    let donkey_greeting = donkey::greeting(name);         // 1
+    let shrek_greeting = format!("Shrek: hi, {}", name);  // 2
     
-    vec![shrek_greeting, donkey_greeting]
+    vec![shrek_greeting, donkey_greeting]                 
 }
 
-mod donkey {
+mod donkey {                                               // 3
     use super::*;
 
     #[marine]
-    #[link(wasm_import_module = "donkey")]
+    #[link(wasm_import_module = "donkey")]                 // 4
     extern "C" {
         pub fn greeting(name: &str) -> String;
     }
 }
 ```
 
+In this Marine (Wasm) module (and namespace) `shrek`, we declare a function `greeting` that creates a `donkey_greeting` (1) from the `donkey` module's (3)`greeting` function, which itself is dependent on importing the `donkey` **Wasm module** with Rust's FFI [`link`](https://doc.rust-lang.org/nomicon/ffi.html) (4) from `examples/motivational-example/donkey/src/main.rs` (see below).
+
 ```rust
+// examples/motivational-example/donkey/src/main.rs
 use marine_rs_sdk::marine;
 
 fn main() {}
@@ -44,13 +51,27 @@ pub fn greeting(name: &str) -> String {
 }
 ```
 
+In summary, our example is comprised of two independent Wasm modules, `shrek` and `donkey`, and illustrates how to link one module into another one, i.e., use the `donkey` module in the `shrek` module. Please note that the `shrek` module is called a *facade* module following the [facade pattern]((https://en.wikipedia.org/wiki/Facade_pattern)) and there can only be one *facade* module per service. 
+
+
+Make sure you have the Marine tools [installed](https://doc.fluence.dev/docs/tutorials_tutorials/recipes_setting_up#marine-tools)) and compile the `donkey` and `shrek`, respectively, which we can do with the `build.sh` script:
 
-Compile these modules (you'll need Marine tools to be installed, here is the installation [guide](https://doc.fluence.dev/docs/tutorials_tutorials/recipes_setting_up#marine-tools)) and run them with Marine REPL:
 ```bash
-$ > ./build.sh
-  ...
-$ > mrepl Config.toml
-  ...
+./build.sh
+```
+
+which creates two independent Wasm modules that are placed in the `artifact` directory:
+
+```bash
+ls artifacts
+donkey.wasm    shrek.wasm
+```
+
+Now that we have our modules, we can explore them with the Marine REPL. Note that we use the  `Config.toml` file to help out the REPL by providing the module location and names. Once we got the REPL up and running, we can interact with both modules and, as expected, the `shrek` module is successfully able to access the `donkey` module's exposed functions.
+
+```bash
+marine mrepl Config.toml
+...
 1> interfaces
 Loaded modules interface:
 
@@ -59,13 +80,19 @@ shrek:
 donkey:
   fn greeting(name: string) -> string
 
-2> call shrek greeting "Feona"
-result: Array([String("Shrek: hi, Feona"), String("Donkey: hi, Feona")])
- elapsed time: 903.949µs
+2> call donkey greeting "no link module"
+result: String("Donkey: hi, no link module")
+ elapsed time: 42.985µs
 
-3> q
+3> call donkey greeting "facade with link module"
+result: String("Donkey: hi, facade with link module")
+ elapsed time: 39.25µs
+
+4> q
 ```
 
+Looks like everything is in order and the modules are ready for [deployment to the network](https://doc.fluence.dev/docs/quick-start/2.-hosted-services#deploying-a-wasm-module-to-the-network) and [composition with Aqua](https://doc.fluence.dev/docs/quick-start/4.-service-composition-and-reuse-with-aqua).
+
 ## Repository structure
 
 - **[REPL](./tools/repl)** - REPL intended to test Marine Wasm modules