@calimero-network/agent-skills 0.2.0 → 0.4.0

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/>

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

@@ -0,0 +1,123 @@
+# State Schema Migrations
+
+When you need to change the shape of your app's state (add a field, rename a field, change a type),
+use `#[app::migrate]` to write a migration function that converts the old Borsh bytes to the new
+state struct.
+
+The migration runs **once** when the upgraded WASM is installed on a context that has existing
+state. New contexts (no prior state) call `#[app::init]` as normal.
+
+---
+
+## How it works
+
+1. Define the OLD state struct with `BorshDeserialize` only (for reading old bytes)
+2. Define the NEW state struct (your updated `#[app::state]`)
+3. Write a `#[app::migrate]` function that reads the old bytes and returns the new struct
+4. Install the new WASM — the node calls the migrate function on the existing context
+
+---
+
+## Example: adding a field
+
+```rust
+use calimero_sdk::app;
+use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+use calimero_sdk::state::read_raw;
+use calimero_storage::collections::{LwwRegister, UnorderedMap};
+
+// --- V1 (old schema, for deserialization only) ---
+#[derive(BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
+struct AppStateV1 {
+    items: UnorderedMap<String, LwwRegister<String>>,
+    counter: LwwRegister<u64>,
+}
+
+// --- V2 (new schema, adds a `notes` field) ---
+#[app::state(emits = for<'a> Event<'a>)]
+#[derive(Debug, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
+pub struct AppStateV2 {
+    items:   UnorderedMap<String, LwwRegister<String>>,
+    counter: LwwRegister<u64>,
+    notes:   LwwRegister<String>,      // new field
+}
+
+#[app::event]
+pub enum Event<'a> {
+    Migrated { from: &'a str, to: &'a str },
+}
+
+// --- Migration function ---
+#[app::migrate]
+pub fn migrate_v1_to_v2() -> AppStateV2 {
+    let old_bytes = read_raw().unwrap_or_else(|| {
+        panic!("Migration error: no existing state found");
+    });
+
+    let old: AppStateV1 = BorshDeserialize::deserialize(&mut &old_bytes[..])
+        .unwrap_or_else(|e| panic!("Migration error: deserialization failed: {:?}", e));
+
+    app::emit!(Event::Migrated { from: "1.0.0", to: "2.0.0" });
+
+    AppStateV2 {
+        items:   old.items,
+        counter: old.counter,
+        notes:   LwwRegister::new("added in v2".to_owned()),
+    }
+}
+
+// --- App logic (same as before, plus new notes methods) ---
+#[app::logic]
+impl AppStateV2 {
+    #[app::init]
+    pub fn init() -> AppStateV2 {
+        AppStateV2 {
+            items:   UnorderedMap::new(),
+            counter: LwwRegister::new(0),
+            notes:   LwwRegister::new(String::new()),
+        }
+    }
+
+    pub fn set_notes(&mut self, notes: String) -> app::Result<()> {
+        self.notes.set(notes);
+        Ok(())
+    }
+}
+```
+
+---
+
+## `read_raw()`
+
+```rust
+use calimero_sdk::state::read_raw;
+
+let bytes: Option<Vec<u8>> = read_raw();
+```
+
+Returns the raw Borsh-encoded bytes of the current state, or `None` if no state exists (fresh
+context). Always `unwrap` with a clear panic message — a missing state during migration is a
+programmer error.
+
+---
+
+## Migration scenarios
+
+| Change         | How to handle                                      |
+| -------------- | -------------------------------------------------- |
+| Add a field    | New field with default value in migrate fn         |
+| Remove a field | Simply don't include it in new struct              |
+| Rename a field | Map old field name to new field name               |
+| Change a type  | Deserialize old, convert value, assign to new type |
+
+---
+
+## Rules
+
+- The migration function must return the **exact** new state type decorated with `#[app::state]`
+- The old struct needs only `BorshDeserialize` — do NOT put `#[app::state]` on it
+- Keep old struct definitions in the source file (or a `migrations` module) as long as the migration
+  exists
+- Do NOT call `read_raw()` outside of `#[app::migrate]` — it's only valid in that context

package/skills/calimero-rust-sdk/references/nested-crdts.md

@@ -0,0 +1,113 @@
+# Nested CRDTs and Mergeable
+
+When you use a custom struct as a value in `UnorderedMap<K, V>` or `UserStorage<T>`, that struct
+must implement `Mergeable` so the CRDT engine knows how to resolve concurrent writes.
+
+Two ways: derive macro (easiest) or manual impl.
+
+---
+
+## Option 1: `#[derive(Mergeable)]` (recommended when all fields are CRDTs)
+
+Add `calimero-storage-macros` to your dependencies:
+
+```toml
+[dependencies]
+calimero-sdk             = "0.10"
+calimero-storage         = "0.10"
+calimero-storage-macros  = "0.10"
+```
+
+```rust
+use calimero_sdk::app;
+use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+use calimero_storage::collections::{Counter, UnorderedMap};
+use calimero_storage_macros::Mergeable;
+
+/// All fields are CRDTs — derive macro just calls merge() on each field
+#[derive(Debug, Mergeable, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
+pub struct TeamStats {
+    pub wins:   Counter,
+    pub losses: Counter,
+    pub draws:  Counter,
+}
+
+#[app::state(emits = MetricsEvent)]
+#[derive(Debug, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
+pub struct AppState {
+    teams: UnorderedMap<String, TeamStats>,
+}
+
+#[app::logic]
+impl AppState {
+    pub fn record_win(&mut self, team: String) -> app::Result<u64> {
+        let mut stats = self.teams.get(&team)?.unwrap_or_else(|| TeamStats {
+            wins:   Counter::new(),
+            losses: Counter::new(),
+            draws:  Counter::new(),
+        });
+        stats.wins.increment()?;
+        let total = stats.wins.value()?;
+        self.teams.insert(team, stats)?;
+        Ok(total)
+    }
+}
+```
+
+Use `#[derive(Mergeable)]` whenever all fields are CRDT types (`Counter`, `UnorderedMap`,
+`LwwRegister`, `Vector`, etc.).
+
+---
+
+## Option 2: Manual `Mergeable` impl (when fields aren't all CRDTs)
+
+```rust
+use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+use calimero_storage::collections::{
+    crdt_meta::MergeError, LwwRegister, Mergeable, UnorderedMap,
+};
+
+#[derive(Debug, BorshSerialize, BorshDeserialize, Default)]
+#[borsh(crate = "calimero_sdk::borsh")]
+pub struct UserProfile {
+    pub name:  LwwRegister<String>,
+    pub score: LwwRegister<u64>,
+    pub tags:  UnorderedMap<String, LwwRegister<bool>>,
+}
+
+impl Mergeable for UserProfile {
+    fn merge(&mut self, other: &Self) -> Result<(), MergeError> {
+        self.name.merge(&other.name)?;
+        self.score.merge(&other.score)?;
+        self.tags.merge(&other.tags)?;
+        Ok(())
+    }
+}
+```
+
+For structs with non-CRDT primitive fields (e.g. `u64` timestamps), pick a merge strategy explicitly
+— typically last-write-wins based on a timestamp field:
+
+```rust
+impl Mergeable for FileRecord {
+    fn merge(&mut self, other: &Self) -> Result<(), MergeError> {
+        // LWW: take the version with the later timestamp
+        if other.uploaded_at > self.uploaded_at {
+            *self = other.clone();
+        }
+        Ok(())
+    }
+}
+```
+
+---
+
+## Rules
+
+- Custom value types in `UnorderedMap<K, V>` **must** implement `Mergeable`
+- Custom types in `UserStorage<T>` **must** implement `Mergeable + Default`
+- `#[derive(Mergeable)]` works only when every field already implements `Mergeable`
+- All nested CRDT fields must still be initialized with `::new()` — there is no blanket `Default`
+  (exception: when `Default` is derived manually for use with `UserStorage`)

package/skills/calimero-rust-sdk/references/private-storage.md

@@ -2,55 +2,97 @@
 
 Calimero apps have two storage scopes:
 
-| Scope | Who can read | Synced across members? |
-| --- | --- | --- |
-| Shared state (CRDT) | All context members | Yes — automatic |
-| Private storage | Only the local member | No |
+| Scope               | Who can read               | Synced across members? |
+| ------------------- | -------------------------- | ---------------------- |
+| Shared state (CRDT) | All context members        | Yes — automatic        |
+| Private storage     | Only the local node/member | No                     |
 
-## Using private storage
+## Declaring private storage
+
+Use `#[app::private]` on a separate struct. Private storage is **never broadcast** to other nodes.
 
 ```rust
-use calimero_sdk::env;
+use calimero_sdk::app;
+use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+use calimero_storage::collections::UnorderedMap;
 
-// Write private data
-env::private_storage_write(b"my_key", b"my_value");
+#[derive(BorshSerialize, BorshDeserialize, Debug)]
+#[borsh(crate = "calimero_sdk::borsh")]
+#[app::private]
+pub struct PrivateData {
+    secrets: UnorderedMap<String, String>,
+}
 
-// Read private data
-let value = env::private_storage_read(b"my_key");
-// returns Option<Vec<u8>>
+impl Default for PrivateData {
+    fn default() -> Self {
+        Self {
+            secrets: UnorderedMap::new(),
+        }
+    }
+}
+```
+
+## Reading and writing private storage
+
+```rust
+#[app::logic]
+impl AppState {
+    pub fn set_secret(&mut self, key: String, value: String) -> app::Result<()> {
+        // Load (or create default) private storage
+        let mut priv_data = PrivateData::private_load_or_default()?;
+        // Get a mutable guard
+        let mut priv_mut = priv_data.as_mut();
+
+        priv_mut.secrets.insert(key, value)?;
+        Ok(())
+    }
+
+    pub fn get_secret(&self, key: &str) -> app::Result<Option<String>> {
+        let priv_data = PrivateData::private_load_or_default()?;
+        Ok(priv_data.secrets.get(key)?.cloned())
+    }
+}
+```
+
+## Real example from battleships — private board storage
+
+```rust
+#[derive(BorshSerialize, BorshDeserialize, Debug)]
+#[borsh(crate = "calimero_sdk::borsh")]
+#[app::private]
+pub struct PrivateBoards {
+    boards: UnorderedMap<String, PlayerBoard>,
+}
+
+impl Default for PrivateBoards {
+    fn default() -> Self {
+        Self { boards: UnorderedMap::new() }
+    }
+}
+
+// Usage inside a method:
+let mut priv_boards = PrivateBoards::private_load_or_default()?;
+let mut priv_mut = priv_boards.as_mut();
+let mut pb = priv_mut.boards.get(&key)?.unwrap_or(PlayerBoard::new());
+pb.place_ships(ships)?;
+priv_mut.boards.insert(key, pb)?;
 ```
 
 ## When to use private storage
 
 - Secrets, credentials, or keys that should not leave the local node
-- Per-member preferences or settings
+- Per-member preferences or game state (e.g. hidden ship positions in battleships)
 - Draft data not yet ready to share with the context
 - Caching computed values locally
 
 ## When NOT to use private storage
 
-- Anything that must be visible to other context members — use CRDT state instead
+- Anything that must be visible to other context members — use CRDT shared state instead
 - Authoritative application state — always use shared CRDT collections for that
 
-## Serializing structured data to private storage
-
-```rust
-use calimero_sdk::borsh::{self, BorshSerialize, BorshDeserialize};
-use calimero_sdk::env;
-
-#[derive(BorshSerialize, BorshDeserialize)]
-struct MyPrivateData {
-    token: String,
-    created_at: u64,
-}
+## Key points
 
-// Write
-let data = MyPrivateData { token: "secret".into(), created_at: 1234567890 };
-let bytes = borsh::to_vec(&data).unwrap();
-env::private_storage_write(b"my_data", &bytes);
-
-// Read
-if let Some(bytes) = env::private_storage_read(b"my_data") {
-    let data: MyPrivateData = borsh::from_slice(&bytes).unwrap();
-}
-```
+- `PrivateData::private_load_or_default()?` — loads or creates fresh instance
+- `priv_data.as_mut()` — returns a mutable guard; changes are persisted when the guard is dropped
+- Private storage uses `UnorderedMap` from `calimero_storage::collections`, same as shared state
+- Multiple `#[app::private]` structs can coexist in the same app