@calimero-network/agent-skills 0.3.0 → 0.4.0

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

package/skills/calimero-rust-sdk/references/state-collections.md

@@ -1,39 +1,120 @@
 # CRDT State Collections
 
-Calimero provides conflict-free replicated data types for application state. These are the only correct way to store persistent, shared state.
+Calimero provides conflict-free replicated data types for application state. All collections are
+imported from `calimero_storage::collections`.
+
+> **Critical:** Do NOT use `calimero_sdk::state::*` — that path no longer exists. The correct import
+> is `calimero_storage::collections::*`.
 
 ## Available Collections
 
-| Type | Use for | std equivalent |
-| --- | --- | --- |
-| `calimero_sdk::state::Map<K, V>` | Key-value mapping | `HashMap<K, V>` |
-| `calimero_sdk::state::Set<T>` | Unique values | `HashSet<T>` |
-| `calimero_sdk::state::Vector<T>` | Ordered list | `Vec<T>` |
-| `calimero_sdk::state::UnorderedMap<K, V>` | Unordered map | `HashMap<K, V>` |
+| Type                      | Use for                                 | Notes                                              |
+| ------------------------- | --------------------------------------- | -------------------------------------------------- |
+| `UnorderedMap<K, V>`      | Key-value mapping                       | Most collection ops return `Result<>` — use `?`    |
+| `UnorderedSet<T>`         | Unique value set                        |                                                    |
+| `Vector<T>`               | Ordered list (append-only)              |                                                    |
+| `LwwRegister<T>`          | Single last-write-wins value            | Wrap map values: `UnorderedMap<K, LwwRegister<V>>` |
+| `Counter`                 | Grow-only counter (GCounter by default) | `.increment()`, `.value()`                         |
+| `Counter<true>`           | PN-Counter (supports decrement)         | Same API + `.decrement()`                          |
+| `FrozenStorage<T>`        | Immutable content-addressed entries     |                                                    |
+| `UserStorage<T>`          | Per-member isolated storage             | Not synced to other members                        |
+| `ReplicatedGrowableArray` | CRDT text / ordered sequence            | Collaborative editing                              |
+
+## Import
+
+```rust
+use calimero_storage::collections::{
+    Counter, FrozenStorage, LwwRegister, ReplicatedGrowableArray,
+    UnorderedMap, UnorderedSet, UserStorage, Vector,
+};
+```
 
 ## Usage
 
 ```rust
-use calimero_sdk::state::{Map, Vector};
+use calimero_sdk::app;
+use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+use calimero_storage::collections::{LwwRegister, UnorderedMap, Vector, Counter};
 
-#[derive(Default, BorshDeserialize, BorshSerialize)]
+#[app::state]
+#[derive(Debug, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
 pub struct AppState {
-    items: Map<String, String>,
-    log: Vector<String>,
+    // Map values wrapped in LwwRegister for CRDT merge
+    items:   UnorderedMap<String, LwwRegister<String>>,
+    log:     Vector<String>,
+    counter: Counter,
 }
 
 #[app::logic]
 impl AppState {
-    pub fn set(&mut self, key: String, value: String) {
-        self.items.insert(key, value);
+    pub fn set(&mut self, key: String, value: String) -> app::Result<()> {
+        self.items.insert(key, value.into())?;
+        Ok(())
+    }
+
+    pub fn get(&self, key: &str) -> app::Result<Option<String>> {
+        Ok(self.items.get(key)?.map(|v| v.get().clone()))
     }
 
-    pub fn get(&self, key: &str) -> Option<&String> {
-        self.items.get(key)
+    pub fn append(&mut self, entry: String) -> app::Result<()> {
+        self.log.push(entry)?;
+        Ok(())
     }
 
-    pub fn append(&mut self, entry: String) {
-        self.log.push(entry);
+    pub fn increment(&mut self) -> app::Result<()> {
+        self.counter.increment()?;
+        Ok(())
+    }
+}
+```
+
+## UnorderedMap patterns
+
+```rust
+// Insert
+self.items.insert(key, value.into())?;
+
+// Get (returns Option<LwwRegister<V>>)
+let val = self.items.get(&key)?.map(|v| v.get().clone());
+
+// Contains
+let exists = self.items.contains(&key)?;
+
+// Remove
+let old = self.items.remove(&key)?;
+
+// All entries
+let all: Vec<(K, V)> = self.items.entries()?.collect();
+
+// In-place mutation via guard
+if let Some(mut guard) = self.items.get_mut(&key)? {
+    guard.set(new_value);
+}
+
+// Entry API (like HashMap::entry)
+use calimero_storage::collections::unordered_map::Entry;
+let entry = self.items.entry(key)?;
+let val = entry.or_insert(LwwRegister::new(default_value))?;
+
+// Length
+let n = self.items.len()?;
+
+// Clear
+self.items.clear()?;
+```
+
+## Constructor
+
+Collections must be initialized with `::new()` — there is no Default impl:
+
+```rust
+#[app::init]
+pub fn init() -> AppState {
+    AppState {
+        items:   UnorderedMap::new(),
+        log:     Vector::new(),
+        counter: Counter::new(),
     }
 }
 ```
@@ -41,10 +122,14 @@ impl AppState {
 ## Keys and values must implement
 
 - `BorshSerialize + BorshDeserialize`
-- `Clone` (for most operations)
+- Values in UnorderedMap are typically wrapped in `LwwRegister<V>` — this handles conflict
+  resolution automatically
 
 ## Important
 
-CRDT collections handle concurrent writes from different context members automatically —
-you never need to manually resolve conflicts. Writes from different members are merged
-deterministically using the DAG-based sync engine.
+CRDT collections handle concurrent writes from different context members automatically — you never
+need to manually resolve conflicts. Writes from different members are merged deterministically using
+the DAG-based sync engine.
+
+Collection operations are **fallible** — always propagate errors with `?`. Panicking inside a WASM
+method aborts the execution and rolls back state.

package/skills/calimero-rust-sdk/references/user-and-frozen-storage.md

@@ -0,0 +1,169 @@
+# UserStorage and FrozenStorage
+
+Two specialised CRDT collection types for per-member and immutable data.
+
+---
+
+## UserStorage\<T\>
+
+Stores a separate value of type `T` per context member (keyed by public key). Each member can only
+read/write their own value via the current executor identity. Reading another member's value
+requires explicitly passing their public key.
+
+`T` must implement `BorshSerialize + BorshDeserialize + Mergeable + Default`.
+
+### Simple example (single value per user)
+
+```rust
+use calimero_storage::collections::{LwwRegister, UserStorage};
+
+#[app::state]
+pub struct AppState {
+    // Each member stores their own string value
+    user_names: UserStorage<LwwRegister<String>>,
+}
+
+#[app::logic]
+impl AppState {
+    // Write the current executor's value
+    pub fn set_my_name(&mut self, name: String) -> app::Result<()> {
+        self.user_names.insert(name.into())?;
+        Ok(())
+    }
+
+    // Read the current executor's value
+    pub fn get_my_name(&self) -> app::Result<Option<String>> {
+        Ok(self.user_names.get()?.map(|v| v.get().clone()))
+    }
+
+    // Read a specific user's value
+    pub fn get_name_for(&self, user_key: calimero_sdk::PublicKey) -> app::Result<Option<String>> {
+        Ok(self.user_names.get_for_user(&user_key)?.map(|v| v.get().clone()))
+    }
+}
+```
+
+### Nested example (map per user)
+
+When `T` is a collection, it must implement `Mergeable` manually (or via `#[derive(Mergeable)]`):
+
+```rust
+use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+use calimero_storage::collections::{LwwRegister, Mergeable, UnorderedMap, UserStorage};
+
+#[derive(Debug, BorshSerialize, BorshDeserialize, Default)]
+#[borsh(crate = "calimero_sdk::borsh")]
+struct UserKvMap {
+    map: UnorderedMap<String, LwwRegister<String>>,
+}
+
+impl Mergeable for UserKvMap {
+    fn merge(&mut self, other: &Self)
+        -> Result<(), calimero_storage::collections::crdt_meta::MergeError>
+    {
+        self.map.merge(&other.map)
+    }
+}
+
+#[app::state]
+pub struct AppState {
+    user_data: UserStorage<UserKvMap>,
+}
+
+#[app::logic]
+impl AppState {
+    pub fn set_user_kv(&mut self, key: String, value: String) -> app::Result<()> {
+        // get-modify-put pattern
+        let mut data = self.user_data.get()?.unwrap_or_default();
+        data.map.insert(key, value.into())?;
+        self.user_data.insert(data)?;
+        Ok(())
+    }
+
+    pub fn get_user_kv(&self, key: &str) -> app::Result<Option<String>> {
+        let data = self.user_data.get()?;
+        match data {
+            Some(d) => Ok(d.map.get(key)?.map(|v| v.get().clone())),
+            None => Ok(None),
+        }
+    }
+}
+```
+
+### Key methods
+
+| Method                           | Description                      |
+| -------------------------------- | -------------------------------- |
+| `insert(value: T)?`              | Store value for current executor |
+| `get()?`                         | Get value for current executor   |
+| `get_for_user(key: &PublicKey)?` | Get value for a specific user    |
+
+---
+
+## FrozenStorage\<T\>
+
+Content-addressed, **immutable** storage. Values are keyed by their SHA-256 hash. Once inserted, a
+value can never be modified or deleted. All members share the same frozen entries (unlike
+`UserStorage`).
+
+`T` must implement `BorshSerialize + BorshDeserialize + Into<FrozenValue<T>>`. Typically `T` is
+`String` or a `Vec<u8>`.
+
+```rust
+use calimero_storage::collections::FrozenStorage;
+
+#[app::state]
+pub struct AppState {
+    frozen: FrozenStorage<String>,
+}
+
+#[app::logic]
+impl AppState {
+    /// Insert a value — returns its 32-byte SHA-256 hash
+    pub fn add_frozen(&mut self, value: String) -> app::Result<[u8; 32]> {
+        let hash = self.frozen.insert(value.into())?;
+        Ok(hash)
+    }
+
+    /// Retrieve by hash
+    pub fn get_frozen(&self, hash: [u8; 32]) -> app::Result<Option<String>> {
+        Ok(self.frozen.get(&hash)?.map(|v| v.clone()))
+    }
+}
+```
+
+### Typical usage pattern
+
+Since hashes are `[u8; 32]`, encode them as hex or base58 strings for JSON:
+
+```rust
+use hex;
+
+pub fn add_frozen(&mut self, value: String) -> app::Result<String> {
+    let hash = self.frozen.insert(value.into())?;
+    Ok(hex::encode(hash))  // return as hex string for JSON clients
+}
+
+pub fn get_frozen(&self, hash_hex: String) -> app::Result<Option<String>> {
+    let mut hash = [0u8; 32];
+    hex::decode_to_slice(&hash_hex, &mut hash)
+        .map_err(|_| /* your error type */)?;
+    Ok(self.frozen.get(&hash)?.map(|v| v.clone()))
+}
+```
+
+### Frozen storage key methods
+
+| Method                     | Description                          |
+| -------------------------- | ------------------------------------ |
+| `insert(value: T.into())?` | Store value, returns `[u8; 32]` hash |
+| `get(&hash)?`              | Retrieve value by hash               |
+
+---
+
+## Cargo.toml — add hex for hash encoding
+
+```toml
+[dependencies]
+hex = "0.4"
+```