@calimero-network/agent-skills 0.3.0 → 0.4.0

package/skills/calimero-rust-sdk/SKILL.md

@@ -5,11 +5,15 @@ You are helping a developer build a **Calimero WASM application** in Rust using
 ## What you need to know immediately
 
 - Apps compile to WASM and run inside the `merod` node runtime
-- All persistent state **must** use Calimero CRDT collections — never `std::collections`
-- The `#[app]` macro goes on the **`impl` block**, not the struct
-- All `pub` methods on the `#[app]` impl are callable via JSON-RPC from clients
-- Events are emitted with `app::emit!()` and pushed to all context members
-- Private storage is per-member and isolated; shared state syncs across all members
+- `#[app::state]` goes on the **struct**, `#[app::logic]` goes on the **impl block**
+- All CRDT collections are from `calimero_storage::collections::*` — NOT `calimero_sdk::state::*`
+- Most collection operations return `Result<>` — always use `?`
+- `app::Result<T>` is the correct return type for public methods (not `Result<T, String>`)
+- Use `app::bail!(err)` to early-return errors
+- Use `app::log!()` not `env::log!()` or `println!()`
+- Events are declared with `#[app::event]` on an enum and declared on state with
+  `emits = for<'a> Event<'a>`
+- Private storage uses `#[app::private]` struct + `StructName::private_load_or_default()?`
 - There is no `main()` — the SDK provides the entry point
 
 ## Cargo.toml setup
@@ -19,38 +23,81 @@ You are helping a developer build a **Calimero WASM application** in Rust using
 crate-type = ["cdylib"]
 
 [dependencies]
-calimero-sdk = "0.x"
+calimero-sdk     = "0.10"
+calimero-storage = "0.10"
+
+[build-dependencies]
+calimero-wasm-abi = "0.10"
+serde_json        = "1"
+
+[profile.app-release]
+inherits         = "release"
+codegen-units    = 1
+opt-level        = "z"
+lto              = true
+debug            = false
+strip            = "symbols"
+panic            = "abort"
+overflow-checks  = true
 ```
 
-## Minimal app skeleton
+For the build script, add `build.rs`:
+
+```rust
+fn main() {
+    calimero_wasm_abi::export().unwrap();
+}
+```
+
+## Minimal app skeleton (KV store)
 
 ```rust
 use calimero_sdk::app;
 use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
-use calimero_sdk::state::UnorderedMap;
-
-#[derive(Default, BorshDeserialize, BorshSerialize)]
-pub struct AppState {
-    items: UnorderedMap<String, String>,
+use calimero_sdk::serde::Serialize;
+use calimero_storage::collections::{LwwRegister, UnorderedMap};
+
+#[app::state(emits = for<'a> Event<'a>)]
+#[derive(Debug, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
+pub struct KvStore {
+    items: UnorderedMap<String, LwwRegister<String>>,
 }
 
-#[app::state]
-impl AppState {}
+#[app::event]
+pub enum Event<'a> {
+    Inserted { key: &'a str, value: &'a str },
+    Updated  { key: &'a str, value: &'a str },
+    Removed  { key: &'a str },
+}
 
 #[app::logic]
-impl AppState {
+impl KvStore {
     #[app::init]
-    pub fn init() -> AppState {
-        AppState::default()
+    pub fn init() -> KvStore {
+        KvStore {
+            items: UnorderedMap::new(),
+        }
     }
 
-    pub fn set(&mut self, key: String, value: String) -> Result<(), String> {
-        self.items.insert(key, value);
+    pub fn set(&mut self, key: String, value: String) -> app::Result<()> {
+        app::log!("set {:?} = {:?}", key, value);
+        if self.items.contains(&key)? {
+            app::emit!(Event::Updated { key: &key, value: &value });
+        } else {
+            app::emit!(Event::Inserted { key: &key, value: &value });
+        }
+        self.items.insert(key, value.into())?;
         Ok(())
     }
 
-    pub fn get(&self, key: String) -> Option<String> {
-        self.items.get(&key).cloned()
+    pub fn get(&self, key: &str) -> app::Result<Option<String>> {
+        Ok(self.items.get(key)?.map(|v| v.get().clone()))
+    }
+
+    pub fn remove(&mut self, key: &str) -> app::Result<Option<String>> {
+        app::emit!(Event::Removed { key });
+        Ok(self.items.remove(key)?.map(|v| v.get().clone()))
     }
 }
 ```
@@ -61,51 +108,114 @@ impl AppState {
 # Add WASM target (one-time)
 rustup target add wasm32-unknown-unknown
 
-# Build
-cargo build --target wasm32-unknown-unknown --release
+# Build with the app-release profile
+cargo build --target wasm32-unknown-unknown --profile app-release
 
-# Output: target/wasm32-unknown-unknown/release/<crate_name>.wasm
+# Output: target/wasm32-unknown-unknown/app-release/<crate_name>.wasm
 ```
 
 ## Installing and running on a node (dev workflow)
 
 ```bash
+# (Assumes: meroctl node add node1 ... && meroctl node use node1 already done)
+
 # 1. Install app from WASM file
-meroctl --node-url http://localhost:2428 app install \
-  --path target/wasm32-unknown-unknown/release/myapp.wasm
-# Returns: app-id
+meroctl app install \
+  --path target/wasm32-unknown-unknown/app-release/myapp.wasm
+# Returns: application-id
 
-# 2. Create a context (instance of the app)
-meroctl --node-url http://localhost:2428 context create --app-id <app-id>
+# 2. Create a context (instance of the app — init() is called)
+meroctl context create --application-id <application-id>
 # Returns: context-id
 
-# 3. Call a method
-meroctl --node-url http://localhost:2428 call <context-id> set \
-  --args '{"key":"hello","value":"world"}'
+# 3. Call a mutation
+meroctl call <context-id> set --args '{"key":"hello","value":"world"}'
+
+# 4. Call a view (read-only)
+meroctl call <context-id> get --args '{"key":"hello"}' --view
 
-# 4. Call a view
-meroctl --node-url http://localhost:2428 call <context-id> get \
-  --args '{"key":"hello"}' --view
+# Dev mode: auto-reinstall when WASM changes
+meroctl context create --watch target/wasm32-unknown-unknown/app-release/myapp.wasm
 ```
 
+For `merod` setup and full `meroctl` reference, see `calimero-merod` and `calimero-meroctl` skills.
+
 ## Key rules
 
-- State struct **must** derive `Default`, `BorshDeserialize`, `BorshSerialize`
-- Never use `HashMap`, `Vec`, `BTreeMap` directly for state — use CRDT collections
-- No blocking I/O, no threads, no `async` in app logic
-- Use `calimero_sdk::env::log!()` not `println!`
+- State struct derives `BorshDeserialize, BorshSerialize` — **not** `Default`
+- Add `#[borsh(crate = "calimero_sdk::borsh")]` to all borsh types
+- Add `#[serde(crate = "calimero_sdk::serde")]` to all serde types
+- Never use `HashMap`, `Vec`, `BTreeMap` directly for **persisted shared state** — use CRDT
+  collections
+- `Vec<T>` and `Option<T>` are fine for local / return types — just not for fields that need CRDT
+  sync
 - Mutations use `&mut self`, views use `&self`
+- Return `app::Result<T>` for all public methods; use `?` on collection ops
+- Use `app::bail!(err)` to return errors early (like `return Err(err.into())`)
+
+## Cross-context calls (xcall)
+
+```rust
+use calimero_sdk::env;
+use calimero_sdk::serde_json;
+
+// Call a method on another context
+let ctx_bytes: [u8; 32] = /* context id bytes */;
+let params = serde_json::json!({ "match_id": id, "winner": w });
+let params_bytes = serde_json::to_vec(&params).unwrap();
+env::xcall(&ctx_bytes, "on_match_finished", &params_bytes);
+```
 
-## Logging
+## Environment functions
 
 ```rust
 use calimero_sdk::env;
 
-// Inside any app method:
-env::log!("Processing key: {}", key);
+env::executor_id()                                // [u8; 32] — caller's public key bytes
+env::context_id()                                 // [u8; 32] — current context ID
+env::time_now()                                   // u64 — current time in milliseconds
+
+env::random_bytes(buf: &mut [u8])                 // fill buf with random bytes
+
+env::ed25519_verify(sig: &[u8; 64], pub_key: &[u8; 32], msg: &[u8]) -> bool
+
+// Blob streaming API
+let fd = env::blob_create();                      // start writing a new blob
+env::blob_write(fd, data: &[u8]) -> u64;          // write bytes
+let blob_id: [u8; 32] = env::blob_close(fd);     // finalize, returns content-addressed ID
+
+let fd = env::blob_open(blob_id: &[u8; 32]);      // open blob for reading (returns 0 if not found)
+env::blob_read(fd, buffer: &mut [u8]) -> u64;     // read bytes (returns 0 at EOF)
+env::blob_close(fd);                              // close read handle
+
+// Make a blob discoverable to all context members
+env::blob_announce_to_context(blob_id: &[u8; 32], context_id: &[u8; 32]) -> bool;
+
+// Cross-context call
+env::xcall(context_id: &[u8; 32], method: &str, params: &[u8]);
 ```
 
+## Additional features
+
+- **UserStorage** — per-member isolated storage (not synced to others): see
+  `references/user-and-frozen-storage.md`
+- **FrozenStorage** — immutable content-addressed entries: see
+  `references/user-and-frozen-storage.md`
+- **Event handlers** — named callbacks triggered when an event is emitted on any peer: see
+  `references/event-handlers.md`
+- **Migrations** — `#[app::migrate]` for upgrading state schema: see `references/migrations.md`
+- **Blob API** — streaming binary storage from app logic: see `references/blob-api.md`
+- **Nested CRDTs** — `#[derive(Mergeable)]` for custom structs used as map values: see
+  `references/nested-crdts.md`
+
+## Related skills
+
+- **`calimero-core`** — runtime concepts (context/app model, JSON-RPC protocol, WebSocket events,
+  CRDT type taxonomy)
+- **`calimero-meroctl`** — full `meroctl` CLI reference for deploying and testing the app
+- **`calimero-merod`** — `merod` daemon setup and health checks
+
 ## References
 
-See `references/` for CRDT collections, events, private storage, and examples.
-See `rules/` for hard constraints the compiler won't catch.
+See `references/` for CRDT collections, events, private storage, and examples. See `rules/` for hard
+constraints the compiler won't catch.

package/skills/calimero-rust-sdk/references/blob-api.md

@@ -0,0 +1,119 @@
+# Blob API
+
+Blobs are binary objects stored outside the CRDT state — large files, images, documents. The app
+stores a blob **ID** (32-byte hash) in state; the binary data lives in blob storage.
+
+Two separate steps: **upload the binary** (client-side, before calling the app method), then **store
+the metadata + announce** (inside the app method).
+
+---
+
+## Streaming write (create a blob from inside the app)
+
+```rust
+use calimero_sdk::env;
+
+// Write arbitrary bytes to a new blob
+let fd = env::blob_create();
+env::blob_write(fd, b"Hello, World!");
+env::blob_write(fd, b" More data...");
+let blob_id: [u8; 32] = env::blob_close(fd);  // finalize; returns content-addressed ID
+
+// Announce to context so other nodes can discover and download it
+let ctx = env::context_id();
+env::blob_announce_to_context(&blob_id, &ctx);
+```
+
+## Streaming read (read a blob from inside the app)
+
+```rust
+let fd = env::blob_open(&blob_id);  // returns 0 if blob not found
+if fd == 0 {
+    app::bail!(/* not found error */);
+}
+
+let mut buf = [0u8; 4096];
+let mut all_bytes = Vec::new();
+loop {
+    let n = env::blob_read(fd, &mut buf);
+    if n == 0 { break; }
+    all_bytes.extend_from_slice(&buf[..n as usize]);
+}
+env::blob_close(fd);
+```
+
+---
+
+## Typical pattern: client uploads, app stores metadata
+
+Most apps let the **client** upload binary data via `blobClient.uploadBlob()` (which returns a blob
+ID), then call an app method that stores the metadata and announces the blob:
+
+```rust
+use calimero_sdk::{app, env};
+use calimero_storage::collections::UnorderedMap;
+
+#[app::state]
+pub struct FileStore {
+    files: UnorderedMap<String, [u8; 32]>,  // name → blob_id
+}
+
+#[app::logic]
+impl FileStore {
+    /// Called after client uploads the blob and gets back blob_id_bytes
+    pub fn store_file(
+        &mut self,
+        name: String,
+        blob_id: [u8; 32],
+    ) -> app::Result<()> {
+        // Announce so all context peers can discover and download it
+        let ctx = env::context_id();
+        env::blob_announce_to_context(&blob_id, &ctx);
+
+        self.files.insert(name, blob_id)?;
+        Ok(())
+    }
+
+    pub fn get_blob_id(&self, name: &str) -> app::Result<Option<[u8; 32]>> {
+        Ok(self.files.get(name)?)
+    }
+}
+```
+
+---
+
+## env functions summary
+
+| Function                                    | Signature                        | Notes                                                                |
+| ------------------------------------------- | -------------------------------- | -------------------------------------------------------------------- |
+| `blob_create()`                             | `() -> u64`                      | Returns write fd                                                     |
+| `blob_write(fd, data)`                      | `(u64, &[u8]) -> u64`            | Returns bytes written                                                |
+| `blob_close(fd)`                            | `(u64) -> [u8; 32]`              | Finalizes; returns blob ID                                           |
+| `blob_open(id)`                             | `(&[u8; 32]) -> u64`             | Returns read fd, 0 if missing                                        |
+| `blob_read(fd, buf)`                        | `(u64, &mut [u8]) -> u64`        | Returns bytes read, 0 at EOF                                         |
+| `blob_announce_to_context(blob_id, ctx_id)` | `(&[u8; 32], &[u8; 32]) -> bool` | Makes blob discoverable to peers; context must match current context |
+
+---
+
+## Encoding blob IDs for JSON
+
+Blob IDs are `[u8; 32]`. For JSON-friendly responses, encode as hex or base58:
+
+```rust
+// hex (add hex = "0.4" to Cargo.toml)
+let hex_id: String = hex::encode(&blob_id);
+let blob_id: [u8; 32] = hex::decode(&hex_str).unwrap().try_into().unwrap();
+
+// base58 (add bs58 to Cargo.toml)
+let b58_id: String = bs58::encode(&blob_id).into_string();
+```
+
+---
+
+## Cargo.toml additions
+
+```toml
+[dependencies]
+hex  = "0.4"   # for hex encoding
+bs58 = "0.5"   # for base58 encoding (optional)
+```

package/skills/calimero-rust-sdk/references/event-handlers.md

@@ -0,0 +1,122 @@
+# Event Handlers
+
+Event handlers are app methods that run **automatically on every peer** when an event is emitted
+with a named handler. The emitting peer runs the handler immediately; all other peers run it when
+they receive the event during sync.
+
+This lets you trigger side effects (CRDT updates, counters, bookkeeping) that happen consistently on
+every node without requiring explicit RPC calls.
+
+---
+
+## Syntax
+
+Pass a string method name as the second element of a tuple in `app::emit!`:
+
+```rust
+// Without handler (normal event, subscribers only):
+app::emit!(Event::Updated { key: &key, value: &value });
+
+// With handler (also calls self.update_handler(key, value) on every peer):
+app::emit!((Event::Updated { key: &key, value: &value }, "update_handler"));
+```
+
+The handler method must exist on the same `#[app::logic]` impl with matching arguments.
+
+---
+
+## Full example
+
+```rust
+use calimero_sdk::app;
+use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+use calimero_storage::collections::{Counter, LwwRegister, UnorderedMap};
+
+#[app::state(emits = for<'a> Event<'a>)]
+#[derive(Debug, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
+pub struct AppState {
+    items:           UnorderedMap<String, LwwRegister<String>>,
+    handler_counter: Counter,
+}
+
+#[app::event]
+pub enum Event<'a> {
+    Inserted { key: &'a str, value: &'a str },
+    Updated  { key: &'a str, value: &'a str },
+    Removed  { key: &'a str },
+}
+
+#[app::logic]
+impl AppState {
+    #[app::init]
+    pub fn init() -> AppState {
+        AppState {
+            items:           UnorderedMap::new(),
+            handler_counter: Counter::new(),
+        }
+    }
+
+    pub fn set(&mut self, key: String, value: String) -> app::Result<()> {
+        if self.items.contains(&key)? {
+            app::emit!((Event::Updated { key: &key, value: &value }, "update_handler"));
+        } else {
+            app::emit!((Event::Inserted { key: &key, value: &value }, "insert_handler"));
+        }
+        self.items.insert(key, value.into())?;
+        Ok(())
+    }
+
+    pub fn remove(&mut self, key: &str) -> app::Result<Option<String>> {
+        app::emit!((Event::Removed { key }, "remove_handler"));
+        Ok(self.items.remove(key)?.map(|v| v.get().clone()))
+    }
+
+    // --- Handlers (called automatically on every peer when event fires) ---
+
+    pub fn insert_handler(&mut self, key: &str, value: &str) -> app::Result<()> {
+        app::log!("insert_handler: key={}, value={}", key, value);
+        self.handler_counter.increment()?;
+        Ok(())
+    }
+
+    pub fn update_handler(&mut self, key: &str, value: &str) -> app::Result<()> {
+        app::log!("update_handler: key={}, value={}", key, value);
+        self.handler_counter.increment()?;
+        Ok(())
+    }
+
+    pub fn remove_handler(&mut self, key: &str) -> app::Result<()> {
+        app::log!("remove_handler: key={}", key);
+        self.handler_counter.increment()?;
+        Ok(())
+    }
+
+    pub fn get_handler_count(&self) -> app::Result<u64> {
+        Ok(self.handler_counter.value()?)
+    }
+}
+```
+
+---
+
+## Handler constraints
+
+Handlers must be:
+
+- **Commutative** — order of execution should not matter
+- **Idempotent** — safe to replay (sync may re-deliver events during catch-up)
+- **Pure w.r.t. CRDT state** — only mutate CRDT fields; avoid logic that depends on exact ordering
+
+Handlers receive the same arguments as the event variant fields. The method signature must match
+exactly.
+
+---
+
+## When to use handlers vs regular methods
+
+| Use handler when                                         | Use regular method when                      |
+| -------------------------------------------------------- | -------------------------------------------- |
+| You want something to happen on every node automatically | You want a node to call something explicitly |
+| Maintaining derived CRDT counters / aggregates           | One-off mutations triggered by one actor     |
+| Bookkeeping that must stay consistent across peers       | Operations that require authorization checks |

package/skills/calimero-rust-sdk/references/events.md

@@ -1,6 +1,7 @@
 # Events
 
-Events are emitted from app logic and pushed in real-time to all context members subscribed via WebSocket.
+Events are emitted from app logic and pushed in real-time to all context members subscribed via
+WebSocket.
 
 ## Define an event type
 

package/skills/calimero-rust-sdk/references/examples.md

@@ -2,42 +2,58 @@
 
 ## KV Store (simplest app)
 
-Source: https://github.com/calimero-network/kv-store
+Source: <https://github.com/calimero-network/kv-store>
 
 ```rust
 use calimero_sdk::app;
 use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
-use calimero_sdk::state::UnorderedMap;
+use calimero_sdk::serde::Serialize;
+use calimero_storage::collections::{LwwRegister, UnorderedMap};
 
-#[derive(Default, BorshDeserialize, BorshSerialize)]
+#[app::state(emits = for<'a> Event<'a>)]
+#[derive(Debug, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
 pub struct KvStore {
-    entries: UnorderedMap<String, String>,
+    items: UnorderedMap<String, LwwRegister<String>>,
 }
 
-#[app::state]
-impl KvStore {}
+#[app::event]
+pub enum Event<'a> {
+    Inserted { key: &'a str, value: &'a str },
+    Updated  { key: &'a str, value: &'a str },
+    Removed  { key: &'a str },
+}
 
 #[app::logic]
 impl KvStore {
     #[app::init]
     pub fn init() -> KvStore {
-        KvStore::default()
+        KvStore { items: UnorderedMap::new() }
     }
 
-    pub fn set(&mut self, key: String, value: String) {
-        self.entries.insert(key, value);
+    pub fn set(&mut self, key: String, value: String) -> app::Result<()> {
+        if self.items.contains(&key)? {
+            app::emit!(Event::Updated { key: &key, value: &value });
+        } else {
+            app::emit!(Event::Inserted { key: &key, value: &value });
+        }
+        self.items.insert(key, value.into())?;
+        Ok(())
     }
 
-    pub fn get(&self, key: String) -> Option<String> {
-        self.entries.get(&key).cloned()
+    pub fn get(&self, key: &str) -> app::Result<Option<String>> {
+        Ok(self.items.get(key)?.map(|v| v.get().clone()))
     }
 
-    pub fn entries(&self) -> Vec<(String, String)> {
-        self.entries.iter().map(|(k, v)| (k.clone(), v.clone())).collect()
+    pub fn remove(&mut self, key: &str) -> app::Result<Option<String>> {
+        app::emit!(Event::Removed { key });
+        Ok(self.items.remove(key)?.map(|v| v.get().clone()))
     }
 
-    pub fn remove(&mut self, key: String) -> bool {
-        self.entries.remove(&key).is_some()
+    pub fn entries(&self) -> app::Result<Vec<(String, String)>> {
+        Ok(self.items.entries()?
+            .map(|(k, v)| (k, v.get().clone()))
+            .collect())
     }
 }
 ```
@@ -45,26 +61,62 @@ impl KvStore {
 ## Calling from a client (JSON-RPC)
 
 Mutations (state changes):
+
 ```json
-{
-  "method": "set",
-  "args": { "key": "hello", "value": "world" }
-}
+{ "method": "set", "args": { "key": "hello", "value": "world" } }
 ```
 
 Views (read-only):
+
 ```json
-{
-  "method": "get",
-  "args": { "key": "hello" }
-}
+{ "method": "get",  "args": { "key": "hello" } }
+{ "method": "entries", "args": {} }
+```
+
+## Lobby + Game pattern (battleships)
+
+Two separate WASM crates — a Lobby context and a Game context. The Game context calls back into the
+Lobby via `env::xcall()` when a match ends.
+
+```rust
+// In game crate — notify lobby when match finishes
+let params = calimero_sdk::serde_json::json!({
+    "match_id": mid,
+    "winner": winner_key,
+    "loser": loser_key,
+});
+let params_bytes = calimero_sdk::serde_json::to_vec(&params).unwrap();
+calimero_sdk::env::xcall(&lobby_ctx_bytes, "on_match_finished", &params_bytes);
 ```
 
-## Other reference apps in core/apps
+## Error handling pattern
+
+```rust
+use thiserror::Error;
+use calimero_sdk::serde::Serialize;
+
+#[derive(Debug, Error, Serialize)]
+#[serde(crate = "calimero_sdk::serde")]
+#[serde(tag = "kind", content = "data")]
+pub enum AppError {
+    #[error("not found: {0}")]
+    NotFound(String),
+    #[error("forbidden: {0}")]
+    Forbidden(&'static str),
+}
+
+// In a method:
+pub fn get_item(&self, key: &str) -> app::Result<String> {
+    let Some(v) = self.items.get(key)? else {
+        app::bail!(AppError::NotFound(key.to_string()));
+    };
+    Ok(v.get().clone())
+}
+```
 
-- `collaborative-editor` — concurrent text editing with CRDT merge
-- `private-data` — mixing shared and private storage patterns
-- `team-metrics` — structured data with multiple CRDT collections
-- `blobs` — binary payload handling
+## Other reference apps
 
-Source: https://github.com/calimero-network/core/tree/master/apps
+- `battleships` — multi-context game, private storage, xcall, event handlers
+- `calimero-scaffolding-e2e-application` — exercises all CRDT types, blob API, user storage
+- `curb` — chat app, event-driven UI updates
+- Source: <https://github.com/calimero-network/>