diff --git a/docs/app-directory/index.md b/docs/app-directory/index.md index d4f2864..36f4a5c 100644 --- a/docs/app-directory/index.md +++ b/docs/app-directory/index.md @@ -5,7 +5,7 @@ The App Directory showcases existing **Calimero applications** that you can depl ## Getting Started You can browse available apps directly from the **Calimero Application Registry**: -πŸ‘‰ [Calimero App Registry](https://github.com/calimero-network/apps) +πŸ‘‰ [Calimero App Registry](https://github.com/calimero-network/app-registry){:target="_blank"} To get started: @@ -17,9 +17,7 @@ More detailed guides and configuration examples will be added here soon. ## Featured Projects -- `Battleships` β€” Turn-based multiplayer with private boards and Merobox workflows. [Repo README](https://github.com/calimero-network/battleships#readme) -- `Shared Todo Backlog` β€” Collaborative backlog with CRDT sync patterns. [Repo README](https://github.com/calimero-network/shared-todo-backlog#readme) -- `Split Bills` β€” Expense sharing with delegation flows and settlement patterns. [Repo README](https://github.com/calimero-network/split-bills#readme) -- `KV Store` β€” Minimal read/write example ideal for first integrations. [Repo README](https://github.com/calimero-network/kv-store#readme) -- `Demo Blob App` β€” File-style payload handling plus frontend wiring. [Repo README](https://github.com/calimero-network/demo-blob-app#readme) -- `Calimero Curb Chat` β€” Rich messaging UI with cross-device workflows. [Repo README](https://github.com/calimero-network/calimero-curb-chat#readme) +- `Battleships` β€” Turn-based multiplayer with private boards and Merobox workflows. [Repo README](https://github.com/calimero-network/battleships#readme){:target="_blank"} +- `KV Store` β€” Minimal read/write example ideal for first integrations. [Repo README](https://github.com/calimero-network/kv-store#readme){:target="_blank"} +- `Demo Blob App` β€” File-style payload handling plus frontend wiring. [Repo README](https://github.com/calimero-network/demo-blob-app#readme){:target="_blank"} +- `Calimero Curb Chat` β€” Rich messaging UI with cross-device workflows. [Repo README](https://github.com/calimero-network/calimero-curb-chat#readme){:target="_blank"} diff --git a/docs/builder-directory/index.md b/docs/builder-directory/index.md index 12445c0..ea06989 100644 --- a/docs/builder-directory/index.md +++ b/docs/builder-directory/index.md @@ -8,11 +8,11 @@ Before we dive in, here are the tools we'll be using: ### Core Tools -- **`merod`** - The runtime that executes your Calimero applications. [Source code](https://github.com/calimero-network/core) +- **`merod`** - The runtime that executes your Calimero applications. [Source code](https://github.com/calimero-network/core){:target="_blank"} -- **`merobox`** - Docker orchestration tool that makes it trivial to spin up local Calimero nodes (`merod` instances). [Source code](https://github.com/calimero-network/merobox) +- **`merobox`** - Docker orchestration tool that makes it trivial to spin up local Calimero nodes (`merod` instances). [Source code](https://github.com/calimero-network/merobox){:target="_blank"} -- **`mero-devtools-js`** - JavaScript wrappers for Calimero tooling to keep your development workflow simple and consistent. [Source code](https://github.com/calimero-network/mero-devtools-js) +- **`mero-devtools-js`** - JavaScript wrappers for Calimero tooling to keep your development workflow simple and consistent. [Source code](https://github.com/calimero-network/mero-devtools-js){:target="_blank"} - **`@calimero-network/abi-codegen`** - Generates TypeScript clients from your Rust backend, keeping frontend/backend in sync. @@ -49,8 +49,6 @@ git clone https://github.com/calimero-network/battleships cd battleships pnpm install -# Or explore other examples (coming soon) -git clone https://github.com/calimero-network/awesome-apps ``` **Time:** Variable @@ -75,12 +73,12 @@ Keep this loop handy; the walkthrough below explains each step in detail and sho ## The AI-Assisted Path (Walkthrough) -This walkthrough uses **Cursor** (an AI-powered IDE) to build a complete Calimero application. We'll use the [Battleships game](https://github.com/calimero-network/battleships) as our example to show you exactly what happens at each step. +This walkthrough uses **Cursor** (an AI-powered IDE) to build a complete Calimero application. We'll use the [Battleships game](https://github.com/calimero-network/battleships){:target="_blank"} as our example to show you exactly what happens at each step. ### Prerequisites -1. **Install Cursor** - [Download here](https://cursor.sh) -2. **Install Docker** - [Download here](https://www.docker.com/products/docker-desktop) (required for `merobox`) +1. **Install Cursor** - [Download here](https://cursor.sh){:target="_blank"} +2. **Install Docker** - [Download here](https://www.docker.com/products/docker-desktop){:target="_blank"} (required for `merobox`) 3. **Have an idea** - Know what you want to build (or follow along with Battleships) 4. **Basic familiarity** - Know JavaScript/TypeScript and have seen Rust (don't need to be an expert) @@ -89,7 +87,7 @@ This walkthrough uses **Cursor** (an AI-powered IDE) to build a complete Calimer The key to AI-assisted development is giving the AI the right context. We've created a specialized prompt that teaches the AI about Calimero development patterns. **Access the prompt:** -[Calimero Bootstrap Prompt](https://gist.github.com/antonpaisov/270d609b43798a926f1755e4036319f5) +[Calimero Bootstrap Prompt](https://gist.github.com/antonpaisov/270d609b43798a926f1755e4036319f5){:target="_blank"} **In Cursor:** @@ -149,14 +147,14 @@ battleships/ **Why this structure:** -- `logic/` contains your Rust business logic compiled to WASM +- `logic/` contains your Rust or TypeScript business logic compiled to WASM - `app/` is your React frontend that calls into the WASM - `workflows/` your local merobox configuration and workflow - `scripts/` automates building, deploying, and testing #### Phase 2: Domain Modeling (Rust Backend) -The AI starts by modeling your domain in Rust. For Battleships, this means: +The AI starts by modeling your domain in Rust or TypeScript. For Battleships, this means: **2.1 Core Types** (`board.rs`, `ships.rs`) @@ -936,7 +934,7 @@ Now that it works, dig into what was created: **πŸ” Things to notice:** - **Type safety everywhere** - Rust types flow to TypeScript -- **Clear separation** - Logic in Rust, UI in React, network in YAML +- **Clear separation** - Logic in Rust/TypeScript, UI in React, network in YAML - **No boilerplate** - `#[calimero::state]` and `#[calimero::logic]` do the heavy lifting - **Event-driven** - State changes emit events, frontend reacts @@ -990,7 +988,7 @@ By following this walkthrough (or just reading it), you now understand: ### Do I need to be a Rust expert? -No. The AI generates idiomatic Rust, and you can mostly work in JavaScript. But basic Rust familiarity helps - consider the [Rust Book](https://doc.rust-lang.org/book/) for fundamentals. +No. The AI generates idiomatic Rust, and you can mostly work in JavaScript. But basic Rust familiarity helps - consider the [Rust Book](https://doc.rust-lang.org/book/){:target="_blank"} for fundamentals. ### Can I use a different frontend framework? @@ -1021,7 +1019,7 @@ mod tests { ### Can I see the full Battleships code? -Yes! [github.com/calimero-network/battleships](https://github.com/calimero-network/battleships) +Yes! [github.com/calimero-network/battleships](https://github.com/calimero-network/battleships){:target="_blank"} ### Is this production-ready? diff --git a/docs/builder-directory/js-sdk-guide.md b/docs/builder-directory/js-sdk-guide.md index 7083647..058e0d1 100644 --- a/docs/builder-directory/js-sdk-guide.md +++ b/docs/builder-directory/js-sdk-guide.md @@ -8,8 +8,8 @@ Build Calimero services using **TypeScript/JavaScript**. The JavaScript SDK comp The JavaScript SDK (`calimero-sdk-js`) consists of two main packages: -- **`@calimero/sdk`** - Decorators, CRDT collections, event system, and environment bindings -- **`@calimero/cli`** - Build toolchain (Rollup β†’ QuickJS β†’ WASM) +- **`@calimero-network/calimero-sdk-js`** - Decorators, CRDT collections, event system, and environment bindings +- **`@calimero-network/calimero-cli-js`** - Build toolchain (Rollup β†’ QuickJS β†’ WASM) **Key features:** - Write services in TypeScript/JavaScript instead of Rust @@ -69,16 +69,21 @@ flowchart LR ### Installation ```bash -pnpm add @calimero/sdk -pnpm add -D @calimero/cli typescript +pnpm add @calimero-network/calimero-sdk-js +pnpm add -D @calimero-network/calimero-cli-js typescript ``` +**NPM Resources:** + +- [calimero-sdk-js](https://www.npmjs.com/package/@calimero-network/calimero-sdk-js){:target="_blank"} +- [calimero-cli-js](https://www.npmjs.com/package/@calimero-network/calimero-cli-js){:target="_blank"} + ### Minimal Service ```typescript -import { State, Logic, Init, View } from '@calimero/sdk'; -import { Counter } from '@calimero/sdk/collections'; -import * as env from '@calimero/sdk/env'; +import { State, Logic, Init, View } from '@calimero-network/calimero-sdk-js'; +import { Counter } from '@calimero-network/calimero-sdk-js/collections'; +import * as env from '@calimero-network/calimero-sdk-js/env'; @State export class CounterApp { @@ -135,8 +140,8 @@ meroctl --node node1 call \ Marks a class as application state: ```typescript -import { State } from '@calimero/sdk'; -import { UnorderedMap, Counter } from '@calimero/sdk/collections'; +import { State } from '@calimero-network/calimero-sdk-js'; +import { UnorderedMap, Counter } from '@calimero-network/calimero-sdk-js/collections'; @State export class MyApp { @@ -155,7 +160,7 @@ export class MyApp { Marks a class as application logic (methods): ```typescript -import { Logic, Init } from '@calimero/sdk'; +import { Logic, Init } from '@calimero-network/calimero-sdk-js'; @Logic(MyApp) export class MyAppLogic extends MyApp { @@ -213,7 +218,7 @@ export class MyAppLogic extends MyApp { Marks event classes: ```typescript -import { Event } from '@calimero/sdk'; +import { Event } from '@calimero-network/calimero-sdk-js'; @Event export class ItemAdded { @@ -253,7 +258,7 @@ The JavaScript SDK provides the same CRDT collections as the Rust SDK: Key-value storage with Last-Write-Wins conflict resolution: ```typescript -import { UnorderedMap } from '@calimero/sdk/collections'; +import { UnorderedMap } from '@calimero-network/calimero-sdk-js/collections'; const map = new UnorderedMap(); @@ -283,7 +288,7 @@ const size = map.entries().length; Ordered list maintaining insertion order: ```typescript -import { Vector } from '@calimero/sdk/collections'; +import { Vector } from '@calimero-network/calimero-sdk-js/collections'; const vec = new Vector(); @@ -306,7 +311,7 @@ const len = vec.len(); // number Distributed counter with automatic summation: ```typescript -import { Counter } from '@calimero/sdk/collections'; +import { Counter } from '@calimero-network/calimero-sdk-js/collections'; const counter = new Counter(); @@ -327,7 +332,7 @@ counter.decrementBy(2); Last-Write-Wins register for single values: ```typescript -import { LwwRegister } from '@calimero/sdk/collections'; +import { LwwRegister } from '@calimero-network/calimero-sdk-js/collections'; const register = new LwwRegister(); @@ -346,7 +351,7 @@ const timestamp = register.timestamp(); // bigint Set with union-based merging: ```typescript -import { UnorderedSet } from '@calimero/sdk/collections'; +import { UnorderedSet } from '@calimero-network/calimero-sdk-js/collections'; const set = new UnorderedSet(); @@ -409,7 +414,7 @@ if (metrics) { Emit events for real-time updates: ```typescript -import { Event, emit, emitWithHandler } from '@calimero/sdk'; +import { Event, emit, emitWithHandler } from '@calimero-network/calimero-sdk-js'; // Define event @Event @@ -454,7 +459,7 @@ export class MyAppLogic extends MyApp { For node-local data (secrets, caches, per-node counters): ```typescript -import { createPrivateEntry } from '@calimero/sdk'; +import { createPrivateEntry } from '@calimero-network/calimero-sdk-js'; // Create private entry const secrets = createPrivateEntry<{ token: string }>('private:secrets'); @@ -488,8 +493,8 @@ cd my-calimero-service pnpm init # Install dependencies -pnpm add @calimero/sdk -pnpm add -D @calimero/cli typescript @types/node +pnpm add @calimero-network/calimero-sdk-js +pnpm add -D @calimero-network/calimero-cli-js typescript @types/node # Create TypeScript config cat > tsconfig.json << EOF @@ -542,8 +547,8 @@ The CLI automatically handles: ### Pattern 1: Simple Key-Value Store ```typescript -import { State, Logic, Init, View } from '@calimero/sdk'; -import { UnorderedMap, LwwRegister } from '@calimero/sdk/collections'; +import { State, Logic, Init, View } from '@calimero-network/calimero-sdk-js'; +import { UnorderedMap, LwwRegister } from '@calimero-network/calimero-sdk-js/collections'; @State export class KvStore { @@ -582,8 +587,8 @@ export class KvStoreLogic extends KvStore { ### Pattern 2: Metrics with Counters ```typescript -import { State, Logic, Init, View } from '@calimero/sdk'; -import { UnorderedMap, Counter } from '@calimero/sdk/collections'; +import { State, Logic, Init, View } from '@calimero-network/calimero-sdk-js'; +import { UnorderedMap, Counter } from '@calimero-network/calimero-sdk-js/collections'; @State export class Metrics { @@ -618,9 +623,9 @@ export class MetricsLogic extends Metrics { ### Pattern 3: Event-Driven Updates ```typescript -import { State, Logic, Init, Event, emitWithHandler } from '@calimero/sdk'; -import { UnorderedMap, Counter } from '@calimero/sdk/collections'; -import * as env from '@calimero/sdk/env'; +import { State, Logic, Init, Event, emitWithHandler } from '@calimero-network/calimero-sdk-js'; +import { UnorderedMap, Counter } from '@calimero-network/calimero-sdk-js/collections'; +import * as env from '@calimero-network/calimero-sdk-js/env'; @Event export class ItemAdded { @@ -842,12 +847,12 @@ merobox bootstrap run workflows/counter-js.yml --log-level=trace For detailed JavaScript SDK documentation: -- **Repository**: [`calimero-network/calimero-sdk-js`](https://github.com/calimero-network/calimero-sdk-js) - Full source code -- **Getting Started**: [`docs/getting-started.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/getting-started.md) - Step-by-step guide -- **Architecture**: [`docs/architecture.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/architecture.md) - Build pipeline and runtime -- **Collections**: [`docs/collections.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/collections.md) - CRDT usage guide -- **Events**: [`docs/events.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/events.md) - Event patterns and handlers -- **Troubleshooting**: [`docs/troubleshooting.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/troubleshooting.md) - Common issues +- **Repository**: [`calimero-network/calimero-sdk-js`](https://github.com/calimero-network/calimero-sdk-js){:target="_blank"} - Full source code +- **Getting Started**: [`docs/getting-started.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/getting-started.md){:target="_blank"} - Step-by-step guide +- **Architecture**: [`docs/architecture.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/architecture.md){:target="_blank"} - Build pipeline and runtime +- **Collections**: [`docs/collections.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/collections.md){:target="_blank"} - CRDT usage guide +- **Events**: [`docs/events.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/events.md){:target="_blank"} - Event patterns and handlers +- **Troubleshooting**: [`docs/troubleshooting.md`](https://github.com/calimero-network/calimero-sdk-js/blob/master/docs/troubleshooting.md){:target="_blank"} - Common issues ## Related Topics diff --git a/docs/builder-directory/sdk-guide.md b/docs/builder-directory/sdk-guide.md index 5515268..99b033b 100644 --- a/docs/builder-directory/sdk-guide.md +++ b/docs/builder-directory/sdk-guide.md @@ -412,9 +412,9 @@ calimero-abi extract \ For detailed SDK documentation: -- **Application SDK**: [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) - Complete API reference -- **Storage Collections**: [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md) - CRDT types and semantics -- **Examples**: [`core/apps`](https://github.com/calimero-network/core/tree/master/apps) - Working application examples +- **Application SDK**: [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md){:target="_blank"} - Complete API reference +- **Storage Collections**: [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md){:target="_blank"} - CRDT types and semantics +- **Examples**: [`core/apps`](https://github.com/calimero-network/core/tree/master/apps){:target="_blank"} - Working application examples ## Related Topics diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index c781663..fdafac3 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -4,7 +4,7 @@ Calimero **applications** are WASM (WebAssembly) modules that run inside the Cal ## Application Model -Applications are compiled from Rust (or other supported languages) to WebAssembly and executed in a sandboxed environment. They use the Calimero SDK to: +Applications are compiled from Rust or TypeScript to WebAssembly and executed in a sandboxed environment. They use the Calimero SDK to: - Define **state** using CRDT collections - Implement **logic** that mutates state @@ -13,7 +13,7 @@ Applications are compiled from Rust (or other supported languages) to WebAssembl ## Quick Start -See [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) for complete SDK documentation. +See [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md){:target="_blank"} for complete SDK documentation. **Minimal example:** @@ -65,7 +65,7 @@ flowchart LR ## CRDT State Management -Applications use CRDT collections for conflict-free state. See [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md) for complete CRDT documentation. +Applications use CRDT collections for conflict-free state. See [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md){:target="_blank"} for complete CRDT documentation. **Available collections:** - `Counter` - Distributed counters (sum) @@ -87,7 +87,7 @@ Applications emit events for real-time updates. Events propagate to all peers au 3. Handlers execute on peer nodes 4. Handlers can update state or trigger side effects -See [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) for event examples. +See [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md){:target="_blank"} for event examples. ## Private Storage @@ -100,7 +100,7 @@ let secrets = private_storage::entry::("my-secrets"); secrets.write(|s| { s.token = "rotated".to_string(); }); ``` -See [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) for private storage details. +See [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md){:target="_blank"} for private storage details. ## Views vs Mutations @@ -133,35 +133,35 @@ WASM execution is bounded: - **Execution time**: Metered with gas-like system - **Register limits**: Number and size of storage registers -See [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md) for detailed limits. +See [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md){:target="_blank"} for detailed limits. ## ABI Generation Applications export an ABI (Application Binary Interface) that clients use: -1. **Build WASM**: Compile Rust code to WASM +1. **Build WASM**: Compile Rust or TypeScript code to WASM 2. **Generate ABI**: Extract method signatures, types, events 3. **Client bindings**: Generate TypeScript/Python clients from ABI 4. **Type safety**: Full type information for client calls Tools: - **`calimero-abi`**: Rust tool for ABI generation -- **`@calimero/abi-codegen`**: TypeScript client generator +- **`@calimero-network/abi-codegen`**: TypeScript client generator ## Example Applications -- **kv-store**: Simple key-value store ([`core/apps/kv-store`](https://github.com/calimero-network/core/tree/master/apps/kv-store)) -- **blobs**: File/blob sharing ([`core/apps/blobs`](https://github.com/calimero-network/core/tree/master/apps/blobs)) -- **battleships**: Multiplayer game ([`battleships`](https://github.com/calimero-network/battleships)) +- **kv-store**: Simple key-value store ([`core/apps/kv-store`](https://github.com/calimero-network/core/tree/master/apps/kv-store){:target="_blank"}) +- **blobs**: File/blob sharing ([`core/apps/blobs`](https://github.com/calimero-network/core/tree/master/apps/blobs){:target="_blank"}) +- **battleships**: Multiplayer game ([`battleships`](https://github.com/calimero-network/battleships){:target="_blank"}) ## Deep Dives For detailed application development: -- **SDK Documentation**: [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) - API reference and examples -- **Storage Collections**: [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md) - CRDT types and merge semantics -- **Runtime**: [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md) - WASM execution engine -- **Integration Guide**: [`core/crates/node/readme/integration-guide.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/integration-guide.md) - Building applications +- **SDK Documentation**: [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md){:target="_blank"} - API reference and examples +- **Storage Collections**: [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md){:target="_blank"} - CRDT types and merge semantics +- **Runtime**: [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md){:target="_blank"} - WASM execution engine +- **Integration Guide**: [`core/crates/node/readme/integration-guide.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/integration-guide.md){:target="_blank"} - Building applications ## Related Topics diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index 787ef06..1de68ba 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -38,7 +38,7 @@ flowchart LR style PEER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` -See [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md) for execution details. +See [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md){:target="_blank"} for execution details. ## Synchronization Flow @@ -97,7 +97,7 @@ flowchart LR - **Gossipsub**: Fast (~100-200ms), reliable in good network conditions - **Periodic sync**: Ensures eventual consistency even with packet loss, partitions, or downtime -See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) for sync configuration details. +See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md){:target="_blank"} for sync configuration details. ## DAG-Based Causal Ordering @@ -144,39 +144,39 @@ flowchart LR | Component | Purpose | Repository | | --- | --- | --- | -| **SDK** | `#[app::state]`, `#[app::logic]`, CRDT collections, events | [`core/crates/sdk`](https://github.com/calimero-network/core/blob/master/crates/sdk) | -| **Runtime** | WASM execution (Wasmer), sandboxing | [`core/crates/runtime`](https://github.com/calimero-network/core/blob/master/crates/runtime) | -| **Storage** | CRDT collections, merge semantics | [`core/crates/storage`](https://github.com/calimero-network/core/blob/master/crates/storage) | -| **DAG** | Causal delta tracking, dependency resolution | [`core/crates/dag`](https://github.com/calimero-network/core/blob/master/crates/dag) | -| **Node** | NodeManager orchestrates sync, events, blobs | [`core/crates/node`](https://github.com/calimero-network/core/blob/master/crates/node) | -| **Network** | libp2p P2P (Gossipsub, streams, DHT) | [`core/crates/network`](https://github.com/calimero-network/core/blob/master/crates/network) | -| **Server** | JSON-RPC API, WebSocket/SSE | [`core/crates/server`](https://github.com/calimero-network/core/blob/master/crates/server) | -| **merod** | Node binary (coordinator/peer) | [`core/crates/merod`](https://github.com/calimero-network/core/blob/master/crates/merod) | -| **meroctl** | CLI for node operations | [`core/crates/meroctl`](https://github.com/calimero-network/core/blob/master/crates/meroctl) | - -See [`core/README.md`](https://github.com/calimero-network/core#readme) for complete architecture. +| **SDK** | `#[app::state]`, `#[app::logic]`, CRDT collections, events | [`core/crates/sdk`](https://github.com/calimero-network/core/blob/master/crates/sdk){:target="_blank"} | +| **Runtime** | WASM execution (Wasmer), sandboxing | [`core/crates/runtime`](https://github.com/calimero-network/core/blob/master/crates/runtime){:target="_blank"} | +| **Storage** | CRDT collections, merge semantics | [`core/crates/storage`](https://github.com/calimero-network/core/blob/master/crates/storage){:target="_blank"} | +| **DAG** | Causal delta tracking, dependency resolution | [`core/crates/dag`](https://github.com/calimero-network/core/blob/master/crates/dag){:target="_blank"} | +| **Node** | NodeManager orchestrates sync, events, blobs | [`core/crates/node`](https://github.com/calimero-network/core/blob/master/crates/node){:target="_blank"} | +| **Network** | libp2p P2P (Gossipsub, streams, DHT) | [`core/crates/network`](https://github.com/calimero-network/core/blob/master/crates/network){:target="_blank"} | +| **Server** | JSON-RPC API, WebSocket/SSE | [`core/crates/server`](https://github.com/calimero-network/core/blob/master/crates/server){:target="_blank"} | +| **merod** | Node binary (coordinator/peer) | [`core/crates/merod`](https://github.com/calimero-network/core/blob/master/crates/merod){:target="_blank"} | +| **meroctl** | CLI for node operations | [`core/crates/meroctl`](https://github.com/calimero-network/core/blob/master/crates/meroctl){:target="_blank"} | + +See [`core/README.md`](https://github.com/calimero-network/core#readme){:target="_blank"} for complete architecture. ## Component Details For detailed information on each component, see their README files: -- **SDK**: [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) - Macros, CRDTs, events -- **Runtime**: [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md) - WASM execution, sandboxing -- **Storage**: [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md) - CRDT collections, merging -- **DAG**: [`core/crates/dag/README.md`](https://github.com/calimero-network/core/blob/master/crates/dag/README.md) - Causal ordering, dependency resolution -- **Node**: [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) - NodeManager, sync, events -- **Network**: [`core/crates/network/README.md`](https://github.com/calimero-network/core/blob/master/crates/network/README.md) - libp2p, Gossipsub, P2P -- **Server**: [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) - JSON-RPC, WebSocket, SSE +- **SDK**: [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md){:target="_blank"} - Macros, CRDTs, events +- **Runtime**: [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md){:target="_blank"} - WASM execution, sandboxing +- **Storage**: [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md){:target="_blank"} - CRDT collections, merging +- **DAG**: [`core/crates/dag/README.md`](https://github.com/calimero-network/core/blob/master/crates/dag/README.md){:target="_blank"} - Causal ordering, dependency resolution +- **Node**: [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md){:target="_blank"} - NodeManager, sync, events +- **Network**: [`core/crates/network/README.md`](https://github.com/calimero-network/core/blob/master/crates/network/README.md){:target="_blank"} - libp2p, Gossipsub, P2P +- **Server**: [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md){:target="_blank"} - JSON-RPC, WebSocket, SSE ## Deep Dives For detailed architecture information: -- **DAG Logic**: [`core/crates/dag/README.md`](https://github.com/calimero-network/core/blob/master/crates/dag/README.md) - Causal ordering algorithms -- **Node Architecture**: [`core/crates/node/readme/architecture.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/architecture.md) - Complete system design -- **Sync Protocol**: [`core/crates/node/readme/sync-protocol.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/sync-protocol.md) - Delta propagation details -- **Storage**: [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md) - CRDT types and merge semantics -- **Network**: [`core/crates/network/README.md`](https://github.com/calimero-network/core/blob/master/crates/network/README.md) - P2P protocols and configuration +- **DAG Logic**: [`core/crates/dag/README.md`](https://github.com/calimero-network/core/blob/master/crates/dag/README.md){:target="_blank"} - Causal ordering algorithms +- **Node Architecture**: [`core/crates/node/readme/architecture.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/architecture.md){:target="_blank"} - Complete system design +- **Sync Protocol**: [`core/crates/node/readme/sync-protocol.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/sync-protocol.md){:target="_blank"} - Delta propagation details +- **Storage**: [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md){:target="_blank"} - CRDT types and merge semantics +- **Network**: [`core/crates/network/README.md`](https://github.com/calimero-network/core/blob/master/crates/network/README.md){:target="_blank"} - P2P protocols and configuration --- diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index 0b879ad..c7e36b5 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -31,7 +31,7 @@ flowchart LR ### 1. Creation -A context is created when an application is installed. See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md) for CLI details. +A context is created when an application is installed. See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md){:target="_blank"} for CLI details. **What happens:** - Application WASM is installed on the node @@ -103,7 +103,7 @@ flowchart LR - **Private Storage**: Node-local data that never leaves the executing node - **Complete Isolation**: Context A cannot access Context B's state -See [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md) for CRDT implementation details. +See [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md){:target="_blank"} for CRDT implementation details. ## Multi-Chain Integration @@ -138,7 +138,7 @@ meroctl call --context-id --method add_item --args '{"key": "hello" - Use `subscribe` method with `context_id` and `event_type` - See [API Reference](../reference/index.md) for details -See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md) for complete CLI documentation. +See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md){:target="_blank"} for complete CLI documentation. ## Context Management @@ -165,9 +165,9 @@ Revoking access removes the member but preserves state history. For detailed context documentation: -- **Context Management**: [`core/crates/context/README.md`](https://github.com/calimero-network/core/blob/master/crates/context/README.md) - Lifecycle and operations +- **Context Management**: [`core/crates/context/README.md`](https://github.com/calimero-network/core/blob/master/crates/context/README.md){:target="_blank"} - Lifecycle and operations - **Identity & Permissions**: [Identity](identity.md) - Cryptographic identities and access control -- **Merobox Workflows**: [`merobox` README](https://github.com/calimero-network/merobox#readme) - Automated context creation and management +- **Merobox Workflows**: [`merobox` README](https://github.com/calimero-network/merobox#readme){:target="_blank"} - Automated context creation and management ## Related Topics diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index 314812f..e9ddd97 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -29,7 +29,7 @@ flowchart LR A **root key** is the master identity for a user or node. It's typically: -- Generated from a blockchain wallet (NEAR, Ethereum, etc.) +- Generated from a NEAR wallet - Used for high-level operations (creating contexts, managing memberships) - Stored securely (hardware wallet, keychain, etc.) @@ -54,7 +54,7 @@ Generate identities with `meroctl`: meroctl identity create --node node1 ``` -See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md) for CLI details. +See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md){:target="_blank"} for CLI details. ## Blockchain Wallet Integration @@ -63,9 +63,7 @@ Calimero supports wallet-based authentication: | Protocol | Identity Source | | --- | --- | | **NEAR** | NEAR account ID + signature | -| **Ethereum** | Ethereum address + signature | -| **ICP** | ICP principal + signature | -| **Stellar** | Stellar account + signature | + **Flow:** 1. User connects wallet @@ -73,13 +71,13 @@ Calimero supports wallet-based authentication: 3. Calimero verifies signature 4. JWT token issued -See [`calimero-client-js/README.md`](https://github.com/calimero-network/calimero-client-js#readme) for client authentication examples. +See [`calimero-client-js/README.md`](https://github.com/calimero-network/calimero-client-js#readme){:target="_blank"} for client authentication examples. ## Authentication Flows For wallet authentication examples, see: -- **JavaScript**: [`calimero-client-js/README.md`](https://github.com/calimero-network/calimero-client-js#readme) - Client-side auth flows -- **Python**: [`calimero-client-py/README.md`](https://github.com/calimero-network/calimero-client-py#readme) - Python client auth +- **JavaScript**: [`calimero-client-js/README.md`](https://github.com/calimero-network/calimero-client-js#readme){:target="_blank"} - Client-side auth flows +- **Python**: [`calimero-client-py/README.md`](https://github.com/calimero-network/calimero-client-py#readme){:target="_blank"} - Python client auth ## JWT Tokens @@ -92,7 +90,7 @@ After authentication, Calimero issues JWT tokens containing: **Usage:** - Include in API requests: `Authorization: Bearer ` - Tokens expire and can be refreshed -- See [`core/crates/auth/README.md`](https://github.com/calimero-network/core/blob/master/crates/auth/README.md) for details +- See [`core/crates/auth/README.md`](https://github.com/calimero-network/core/blob/master/crates/auth/README.md){:target="_blank"} for details ## Key Management @@ -106,7 +104,7 @@ After authentication, Calimero issues JWT tokens containing: meroctl context revoke --context-id --member-id ``` -See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md) for key management commands. +See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md){:target="_blank"} for key management commands. **What happens:** - Key is removed from context membership @@ -131,9 +129,6 @@ import { ClientLogin } from '@calimero-network/calimero-client'; **Supported wallets:** - NEAR Wallet -- MetaMask (Ethereum) -- WalletConnect -- Internet Identity (ICP) ### Python Client @@ -144,7 +139,7 @@ from calimero_client_py import create_connection, AuthMode connection = create_connection( base_url="https://node.calimero.network", auth_mode=AuthMode.WALLET, - wallet_type="near" # or "ethereum", "icp" + wallet_type="near" ) ``` @@ -160,8 +155,8 @@ connection = create_connection( For detailed identity documentation: -- **Identity Contracts**: [`contracts` README](https://github.com/calimero-network/contracts#readme) - Smart contract implementations -- **Auth Service**: [`core/crates/auth/README.md`](https://github.com/calimero-network/core/blob/master/crates/auth/README.md) - Authentication service +- **Identity Contracts**: [`contracts` README](https://github.com/calimero-network/contracts#readme){:target="_blank"} - Smart contract implementations +- **Auth Service**: [`core/crates/auth/README.md`](https://github.com/calimero-network/core/blob/master/crates/auth/README.md){:target="_blank"} - Authentication service - **Client SDKs**: [Tools & APIs](../tools-apis/index.md) - Wallet integration guides ## Related Topics diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md index 8dd492a..56a5227 100644 --- a/docs/core-concepts/index.md +++ b/docs/core-concepts/index.md @@ -29,7 +29,7 @@ Understanding Calimero's core concepts is essential for building and operating a - **Root Keys**: Master identities (typically from blockchain wallets) - **Client Keys**: Derived keys for specific contexts -- **Authentication**: Wallet-based authentication (NEAR, Ethereum, ICP, etc.) +- **Authentication**: Wallet-based authentication (NEAR) **Key concepts:** - Hierarchical key management diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md index 82507c2..74e32a4 100644 --- a/docs/core-concepts/nodes.md +++ b/docs/core-concepts/nodes.md @@ -52,7 +52,7 @@ flowchart LR - **NodeManagers**: BlobManager (content storage), SyncManager (periodic sync) - **NodeState**: Blob cache, delta stores per context -See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) for detailed architecture. +See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md){:target="_blank"} for detailed architecture. ## Synchronization @@ -77,7 +77,7 @@ Content-addressed blob storage: - P2P distribution via streams - Periodic garbage collection -See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) for blob management details. +See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md){:target="_blank"} for blob management details. ## Admin Surfaces @@ -96,7 +96,7 @@ See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob - Node administration, context management, identity operations - JWT token authentication -See [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) for API details. +See [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md){:target="_blank"} for API details. ## Monitoring & Debugging @@ -120,10 +120,10 @@ Nodes can be configured via: For detailed node documentation: -- **Node Architecture**: [`core/crates/node/readme/architecture.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/architecture.md) - Complete system design -- **Sync Configuration**: [`core/crates/node/readme/sync-configuration.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/sync-configuration.md) - Tuning parameters -- **Event Handling**: [`core/crates/node/readme/event-handling.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/event-handling.md) - Event flow and handlers -- **Troubleshooting**: [`core/crates/node/readme/troubleshooting.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/troubleshooting.md) - Common issues +- **Node Architecture**: [`core/crates/node/readme/architecture.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/architecture.md){:target="_blank"} - Complete system design +- **Sync Configuration**: [`core/crates/node/readme/sync-configuration.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/sync-configuration.md){:target="_blank"} - Tuning parameters +- **Event Handling**: [`core/crates/node/readme/event-handling.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/event-handling.md){:target="_blank"} - Event flow and handlers +- **Troubleshooting**: [`core/crates/node/readme/troubleshooting.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/troubleshooting.md){:target="_blank"} - Common issues ## Related Topics diff --git a/docs/examples/core-apps-examples.md b/docs/examples/core-apps-examples.md index 69becdb..2ccb504 100644 --- a/docs/examples/core-apps-examples.md +++ b/docs/examples/core-apps-examples.md @@ -17,7 +17,7 @@ The `core/apps` directory contains reference implementations demonstrating vario ## kv-store -**Location**: [`core/apps/kv-store`](https://github.com/calimero-network/core/tree/master/apps/kv-store) +**Location**: [`core/apps/kv-store`](https://github.com/calimero-network/core/tree/master/apps/kv-store){:target="_blank"} **What it does:** Simple key-value store demonstrating basic CRDT operations and event emission. @@ -73,7 +73,7 @@ meroctl --node node1 call \ ## kv-store-with-handlers -**Location**: [`core/apps/kv-store-with-handlers`](https://github.com/calimero-network/core/tree/master/apps/kv-store-with-handlers) +**Location**: [`core/apps/kv-store-with-handlers`](https://github.com/calimero-network/core/tree/master/apps/kv-store-with-handlers){:target="_blank"} **What it does:** KV store with event handlers demonstrating real-time event processing. @@ -91,7 +91,7 @@ KV store with event handlers demonstrating real-time event processing. ## blobs -**Location**: [`core/apps/blobs`](https://github.com/calimero-network/core/tree/master/apps/blobs) +**Location**: [`core/apps/blobs`](https://github.com/calimero-network/core/tree/master/apps/blobs){:target="_blank"} **What it does:** Demonstrates blob storage and distribution across the network. @@ -135,7 +135,7 @@ meroctl --node node1 call \ ## collaborative-editor -**Location**: [`core/apps/collaborative-editor`](https://github.com/calimero-network/core/tree/master/apps/collaborative-editor) +**Location**: [`core/apps/collaborative-editor`](https://github.com/calimero-network/core/tree/master/apps/collaborative-editor){:target="_blank"} **What it does:** Real-time collaborative text editor using RGA (Replicated Growable Array) CRDT. @@ -184,7 +184,7 @@ meroctl --node node1 call \ ## private-data -**Location**: [`core/apps/private-data`](https://github.com/calimero-network/core/tree/master/apps/private-data) +**Location**: [`core/apps/private-data`](https://github.com/calimero-network/core/tree/master/apps/private-data){:target="_blank"} **What it does:** Demonstrates private storage for node-local secrets and data. @@ -201,7 +201,7 @@ Demonstrates private storage for node-local secrets and data. - Private cache management **Example usage:** -See workflow in [`workflows/example.yml`](https://github.com/calimero-network/core/blob/master/apps/private-data/workflows/example.yml) +See workflow in [`workflows/example.yml`](https://github.com/calimero-network/core/blob/master/apps/private-data/workflows/example.yml){:target="_blank"} **Learn from this example:** - Private storage API usage @@ -210,7 +210,7 @@ See workflow in [`workflows/example.yml`](https://github.com/calimero-network/co ## team-metrics -**Location**: [`core/apps/team-metrics-macro`](https://github.com/calimero-network/core/tree/master/apps/team-metrics-macro) and [`core/apps/team-metrics-custom`](https://github.com/calimero-network/core/tree/master/apps/team-metrics-custom) +**Location**: [`core/apps/team-metrics-macro`](https://github.com/calimero-network/core/tree/master/apps/team-metrics-macro){:target="_blank"} and [`core/apps/team-metrics-custom`](https://github.com/calimero-network/core/tree/master/apps/team-metrics-custom){:target="_blank"} **What it does:** Demonstrates nested CRDT structures for team metrics tracking. @@ -234,7 +234,7 @@ Demonstrates nested CRDT structures for team metrics tracking. ## xcall-example -**Location**: [`core/apps/xcall-example`](https://github.com/calimero-network/core/tree/master/apps/xcall-example) +**Location**: [`core/apps/xcall-example`](https://github.com/calimero-network/core/tree/master/apps/xcall-example){:target="_blank"} **What it does:** Demonstrates cross-context calls (xcall) for inter-context communication. @@ -339,8 +339,8 @@ meroctl --node calimero-node-1 call \ For detailed example documentation: -- **kv-store**: [`core/apps/kv-store/README.md`](https://github.com/calimero-network/core/blob/master/apps/kv-store/README.md) -- **collaborative-editor**: [`core/apps/collaborative-editor/README.md`](https://github.com/calimero-network/core/blob/master/apps/collaborative-editor/README.md) -- **blobs**: [`core/apps/blobs/README.md`](https://github.com/calimero-network/core/blob/master/apps/blobs/README.md) -- **xcall-example**: [`core/apps/xcall-example/README.md`](https://github.com/calimero-network/core/blob/master/apps/xcall-example/README.md) +- **kv-store**: [`core/apps/kv-store/README.md`](https://github.com/calimero-network/core/blob/master/apps/kv-store/README.md){:target="_blank"} +- **collaborative-editor**: [`core/apps/collaborative-editor/README.md`](https://github.com/calimero-network/core/blob/master/apps/collaborative-editor/README.md){:target="_blank"} +- **blobs**: [`core/apps/blobs/README.md`](https://github.com/calimero-network/core/blob/master/apps/blobs/README.md){:target="_blank"} +- **xcall-example**: [`core/apps/xcall-example/README.md`](https://github.com/calimero-network/core/blob/master/apps/xcall-example/README.md){:target="_blank"} diff --git a/docs/examples/index.md b/docs/examples/index.md index 6ae56ef..bfe4c4e 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -6,7 +6,7 @@ Learn Calimero by exploring working examples. All examples include source code, **[Core Apps Examples](core-apps-examples.md)** β€” Reference implementations from `core/apps` demonstrating SDK patterns and CRDT usage. -These examples live in [`calimero-network/core/apps`](https://github.com/calimero-network/core/tree/master/apps): +These examples live in [`calimero-network/core/apps`](https://github.com/calimero-network/core/tree/master/apps){:target="_blank"}: - **kv-store** - Basic CRDT operations, key-value storage - **blobs** - File/blob management with content addressing @@ -26,8 +26,7 @@ meroctl --node node1 app install --path build/kv_store.wasm For complete applications, see: -- **Battleships** - Multiplayer game - [`battleships`](https://github.com/calimero-network/battleships) repository -- **Shared Todo** - Collaborative task list - [`shared-todo-backlog`](https://github.com/calimero-network/shared-todo-backlog) repository +- **Battleships** - Multiplayer game - [`battleships`](https://github.com/calimero-network/battleships){:target="_blank"} repository - **KV Store** - Template app - Created via `npx create-mero-app` ## By Complexity diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 784d606..9bb2659 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -17,10 +17,14 @@ Choose your path based on what you want to do: ### Prerequisites **Required:** -- **Docker** 20.10+ (for running nodes) -- **Python** 3.8+ (for merobox) -- **Node.js** 18+ (for client SDKs and building JavaScript apps) -- **Rust toolchain** (for building Rust applications) + +- **[Docker](https://www.docker.com/){:target="_blank"}** 20.10+ (for running nodes) + +- **[Python](https://www.python.org/){:target="_blank"}** 3.8+ (for merobox) + +- **[Node.js](https://nodejs.org/en){:target="_blank"}** 18+ (for client SDKs and building JavaScript apps) + +- **[Rust toolchain](https://rust-lang.org/tools/install/){:target="_blank"}** (for building Rust applications) **Optional:** - `merod` and `meroctl` (if building from source) @@ -58,13 +62,19 @@ rustc --version ```bash # Install Calimero JavaScript SDK -npm install @calimero/sdk @calimero/cli +npm install @calimero-network/calimero-cli-js @calimero-network/calimero-sdk-js # Or with pnpm -pnpm add @calimero/sdk @calimero/cli +pnpm add @calimero-network/calimero-cli-js @calimero-network/calimero-sdk-js ``` -See [`merobox/README.md`](https://github.com/calimero-network/merobox#readme) for complete installation options. +NPM resources: + +- [calimero-sdk-js](https://www.npmjs.com/package/@calimero-network/calimero-sdk-js){:target="_blank"} + +- [calimero-cli-js](https://www.npmjs.com/package/@calimero-network/calimero-cli-js){:target="_blank"} + +See [`merobox/README.md`](https://github.com/calimero-network/merobox#readme){:target="_blank"} for complete installation options. ## Step 2: Run a Local Network @@ -223,7 +233,7 @@ See [Contexts](../core-concepts/contexts.md) for context management details. ### Core Examples -Examples in [`core/apps`](https://github.com/calimero-network/core/tree/master/apps): +Examples in [`core/apps`](https://github.com/calimero-network/core/tree/master/apps){:target="_blank"}: - **kv-store** - Simple key-value store (great for learning basics) - **blobs** - File/blob sharing with content addressing @@ -273,10 +283,10 @@ See [Examples](../examples/index.md) for complete list. A: For local development, yes. Use `merobox` to run nodes locally. For production, you can use hosted nodes or run your own. **Q: Which language should I use?** -A: Applications can be written in Rust (compiled to WASM) or JavaScript/TypeScript (using `@calimero/sdk`). Clients can use JavaScript/TypeScript or Python. +A: Applications can be written in Rust (compiled to WASM) or JavaScript/TypeScript (using `@calimero-network/calimero-sdk-js`). Clients can use JavaScript/TypeScript or Python. **Q: How do I handle authentication?** -A: Calimero supports wallet-based authentication (NEAR, Ethereum, ICP). See [Identity](../core-concepts/identity.md) and [Client SDKs](../tools-apis/client-sdks.md). +A: Calimero supports NEAR wallet-based authentication. See [Identity](../core-concepts/identity.md) and [Client SDKs](../tools-apis/client-sdks.md). **Q: Can I use this offline?** A: Yes! Calimero is offline-first. Apps work offline and sync when online. diff --git a/docs/index.md b/docs/index.md index dbfe6aa..c1556c1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,26 +2,26 @@ ## Why Calimero Exists -The Internet was designed to be **peer-to-peer**. From its origins in **DARPA’s research on packet switching** β€” a response to the fragility of circuit-switched networks like telephony β€” the Internet’s architecture has always favored decentralization. Protocols such as **TCP/IP** and **SMTP** embody this spirit: open, resilient, and without a central authority. Calimero builds upon that same idea. +The Internet was designed to be **peer-to-peer**. From its origins in **DARPA’s [research](https://en.wikipedia.org/wiki/ARPANET){:target="_blank"} on packet switching** β€” a response to the fragility of circuit-switched networks like telephony β€” the Internet’s architecture has always favored decentralization. Protocols such as **[TCP/IP](https://en.wikipedia.org/wiki/Internet_protocol_suite){:target="_blank"}** and **[SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol){:target="_blank"}** embody this spirit: open, resilient, and without a central authority. Calimero builds upon that same idea. -- **Calimero is not a blockchain.** +- **Calimero is not a [blockchain](https://en.wikipedia.org/wiki/Blockchain){:target="_blank"}.** - **Calimero is an application layer** built on top of the network β€” a place for collaboration, computation, and coordination between peers. -- Where a blockchain would rely on **consensus**, Calimero uses **CRDTs (Conflict-free Replicated Data Types)** for distributed consistency without global agreement. +- Where a blockchain would rely on **consensus**, Calimero uses **[CRDTs](https://crdt.tech/){:target="_blank"} (Conflict-free Replicated Data Types)** for distributed consistency without global agreement. Calimero is the layer you reach for when you *don’t* need the guarantees (or costs) of consensus β€” when local autonomy and asynchronous coordination are enough. ## Build Self-Sovereign Applications with CRDT-Powered P2P Sync -Calimero Network is a framework for distributed, peer-to-peer applications with automatic conflict-free data synchronization, user-owned data, and verifiable off-chain computing. +Calimero is a framework for distributed, peer-to-peer applications with automatic conflict-free data synchronization, user-owned data, and verifiable off-chain computing. | Attribute | What it means | | --- | --- | | Local-first by default | Your data stays on your node; you control replication | -| DAG-based CRDT sync | Conflict resolution without coordination, resilient offline | +| [DAG-based](https://en.wikipedia.org/wiki/Directed_acyclic_graph){:target="_blank"} CRDT sync | Conflict resolution without coordination, resilient offline | | Event-driven architecture | Real-time updates emitted across participating nodes | | Encrypted P2P channels | End-to-end secure sharing between context members | -| WASM runtime | Build applications in Rust, ship deterministic WebAssembly | -| Multi-chain integrations | Connect NEAR, ICP, Ethereum, Stellar, ZKSync for attestations | +| [WASM](https://en.wikipedia.org/wiki/WebAssembly){:target="_blank"} runtime | Build applications in Rust or TypeScript, ship deterministic WebAssembly | +| Multi-chain integrations | Connect [NEAR](https://www.near.org/){:target="_blank"}, [Internet Computer (ICP)](https://internetcomputer.org/){:target="_blank"}, [Ethereum](https://ethereum.org/){:target="_blank"}, and [Stellar](https://stellar.org/){:target="_blank"} for attestations | Calimero is a privacy-focused application layer for peer-to-peer collaboration. This site stays concise on purpose: each section orients you in a few minutes, then links directly to the canonical GitHub READMEs for full architecture and workflows. @@ -30,7 +30,7 @@ Calimero is a privacy-focused application layer for peer-to-peer collaboration. | Start here | What you get | | --- | --- | | [Launch a local network](builder-directory/index.md#minimal-dev-loop) | Bootstrap `merod` + Merobox and observe a context end-to-end. | -| [Build from a template](builder-directory/index.md#choose-your-starting-point) | Scaffold a Rust + React app with `create-mero-app`. | +| [Build from a template](builder-directory/index.md#choose-your-starting-point) | Scaffold a Rust or TypeScript + React app with `create-mero-app`. | | [Explore a reference app](app-directory/index.md#featured-projects) | Learn from maintained examples such as Battleships or Shared Todo. | | [Understand the architecture](intro/index.md#core-architecture-snapshot) | See how contexts, nodes, state sync, and identity fit together. | @@ -47,6 +47,6 @@ Calimero is a privacy-focused application layer for peer-to-peer collaboration. ## Highlights - **Contexts as private networks** β€” CRDT-backed state and scoped storage so teams can collaborate without global consensus. -- **Hierarchical identities** β€” Root keys delegate client keys per device, integrating with NEAR, Ethereum, Starknet, and ICP wallets. -- **Modular runtime** β€” `merod` orchestrates networking (libp2p), storage, and WASM apps with JSON-RPC/WebSocket surfaces. -- **Repository-first docs** β€” Detailed flows live in project READMEs such as [`calimero-network/core`](https://github.com/calimero-network/core#readme) and [`calimero-network/merobox`](https://github.com/calimero-network/merobox#readme). \ No newline at end of file +- **Hierarchical identities** β€” Root keys delegate client keys per device, integrating with NEAR wallets. +- **Modular runtime** β€” `merod` orchestrates networking ([libp2p](https://libp2p.io/){:target="_blank"}), storage, and WASM apps with JSON-RPC/WebSocket surfaces. +- **Repository-first docs** β€” Detailed flows live in project READMEs such as [`calimero-network/core`](https://github.com/calimero-network/core#readme){:target="_blank"} and [`calimero-network/merobox`](https://github.com/calimero-network/merobox#readme){:target="_blank"}. \ No newline at end of file diff --git a/docs/intro/index.md b/docs/intro/index.md index 5ae231e..097531f 100644 --- a/docs/intro/index.md +++ b/docs/intro/index.md @@ -2,9 +2,9 @@ ## What is Calimero? -**Calimero Core** is the runtime for building peer-to-peer applications with automatic conflict-free synchronization. It enables offline-first, distributed apps that sync when online, without central servers. +**Calimero** is a peer-to-peer framework for building self-sovereign, local-first applications with automatic, conflict-free synchronization. It enables developers to create distributed apps where users own their data, operate offline, and sync with peers when connectivity is availableβ€”without relying on centralized servers. -Calimero is an application layer built on top of the network β€” a place for collaboration, computation, and coordination between peers. Where a blockchain would rely on **consensus**, Calimero uses **CRDTs (Conflict-free Replicated Data Types)** for distributed consistency without global agreement. +At the application layer, Calimero provides a shared environment for collaboration, computation, and coordination between peers. Instead of relying on **global consensus** like blockchains do, it achieves distributed consistency through **CRDTs (Conflict-free Replicated Data Types)**β€”allowing independent nodes to converge on the same state without coordination, leaders, or ordering guarantees. ## Core Value Proposition @@ -13,8 +13,8 @@ Calimero is an application layer built on top of the network β€” a place for col | **CRDT-based Sync** | Automatic conflict resolution without coordination | | **Offline-first** | Works without connectivity, syncs when online | | **Event-driven** | Real-time notifications across nodes | -| **WASM Runtime** | Write apps in Rust, run in sandboxed environment | -| **Multi-chain** | Integrates with NEAR, ICP, Ethereum, Stellar, zkSync | +| **WASM Runtime** | Write apps in Rust or TypeScript, run in sandboxed environment | +| **Multi-chain** | Integrates with NEAR, ICP, Ethereum, Stellar | ## Key Design Principles @@ -27,11 +27,11 @@ Calimero is an application layer built on top of the network β€” a place for col Calimero combines several powerful technologies to deliver a unique distributed computing platform: -- βœ… **Automatic conflict resolution** via CRDTs β€” no manual merge code needed. Write natural code with nested data structures; the storage layer handles synchronization automatically. -- βœ… **Causal ordering** via DAG β€” handles out-of-order network delivery gracefully. Deltas can arrive in any order; the system buffers and applies them in correct causal sequence. -- βœ… **Dual sync strategy** β€” fast broadcast (~100-200ms) + reliable catch-up. Gossipsub provides real-time propagation, while periodic P2P sync ensures eventual consistency even after network issues. -- βœ… **Event-driven architecture** β€” real-time updates without polling. Applications emit events that automatically propagate to all peers and trigger handlers. -- βœ… **Local-first** β€” data owned by users, no central authority required. Your data lives on your devices; you control access and sharing. +- **Automatic conflict resolution** via CRDTs β€” no manual merge code needed. Write natural code with nested data structures; the storage layer handles synchronization automatically. +- **Causal ordering** via DAG β€” handles out-of-order network delivery gracefully. Deltas can arrive in any order; the system buffers and applies them in correct causal sequence. +- **Dual sync strategy** β€” fast broadcast (~100-200ms) + reliable catch-up. [Gossipsub](https://docs.rs/gossipsub/latest/gossipsub/){:target="_blank"} provides real-time propagation, while periodic P2P sync ensures eventual consistency even after network issues. +- **Event-driven architecture** β€” real-time updates without polling. Applications emit events that automatically propagate to all peers and trigger handlers. +- **Local-first** β€” data owned by users, no central authority required. Your data lives on your devices; you control access and sharing. ## Use Cases @@ -42,7 +42,7 @@ Calimero enables a wide range of decentralized applications: | **Collaborative Editing** | Real-time document collaboration without servers. Multiple users edit simultaneously; conflicts resolve automatically via CRDTs. | | **Decentralized Social** | User-controlled social networks. Each user runs their own node; data ownership and privacy by default. | | **P2P Gaming** | Multiplayer games with automatic state sync. Game state synchronizes across players even with network interruptions. | -| **IoT Networks** | Decentralized device coordination. Devices coordinate without central servers; works offline and syncs when online. | +| **[IoT Networks](https://en.wikipedia.org/wiki/Internet_of_things){:target="_blank"}** | Decentralized device coordination. Devices coordinate without central servers; works offline and syncs when online. | | **Supply Chain** | Transparent, multi-party tracking. All participants maintain their own copy; automatic conflict resolution handles concurrent updates. | | **Healthcare** | Private, patient-controlled medical records. Patients own their data; selective sharing with healthcare providers via encrypted contexts. | @@ -59,10 +59,10 @@ See [Example Applications](../examples/index.md) for working implementations. | If you are… | Start here | | --- | --- | -| **Building apps** | [Getting Started](../getting-started/index.md) β†’ [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) | -| **Running nodes** | [Run a Local Network](../operator-track/run-a-local-network.md) β†’ [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) | -| **Understanding sync** | [Architecture Overview](../core-concepts/architecture.md) β†’ [`core/crates/dag/README.md`](https://github.com/calimero-network/core/blob/master/crates/dag/README.md) | -| **Debugging issues** | [Monitor & Debug](../operator-track/monitor-and-debug.md) β†’ [`core/crates/node/readme/troubleshooting.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/troubleshooting.md) | +| **Building apps** | [Getting Started](../getting-started/index.md) β†’ [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md){:target="_blank"} | +| **Running nodes** | [Run a Local Network](../operator-track/run-a-local-network.md) β†’ [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md){:target="_blank"} | +| **Understanding sync** | [Architecture Overview](../core-concepts/architecture.md) β†’ [`core/crates/dag/README.md`](https://github.com/calimero-network/core/blob/master/crates/dag/README.md){:target="_blank"} | +| **Debugging issues** | [Monitor & Debug](../operator-track/monitor-and-debug.md) β†’ [`core/crates/node/readme/troubleshooting.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/troubleshooting.md){:target="_blank"} | ## Core Architecture Layers @@ -73,7 +73,7 @@ Calimero's architecture consists of four main layers: - CRDT collections: `UnorderedMap`, `Vector`, `Counter`, `LwwRegister` - Event emission for real-time updates -**Documentation**: [Applications](../core-concepts/applications.md) β†’ [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) +**Documentation**: [Applications](../core-concepts/applications.md) β†’ [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md){:target="_blank"} ### 2. Node Layer - Orchestrates synchronization and execution @@ -81,23 +81,23 @@ Calimero's architecture consists of four main layers: - Event handler execution across the network - Blob distribution for file sharing -**Documentation**: [Nodes](../core-concepts/nodes.md) β†’ [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) +**Documentation**: [Nodes](../core-concepts/nodes.md) β†’ [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md){:target="_blank"} ### 3. Storage Layer - CRDT storage with automatic merging - DAG (Directed Acyclic Graph) for causal ordering - Handles out-of-order delivery with dependency resolution -- Merkle trees for efficient state comparison +- [Merkle trees](https://en.wikipedia.org/wiki/Merkle_tree){:target="_blank"} for efficient state comparison -**Documentation**: [Architecture Overview](../core-concepts/architecture.md) β†’ [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md) +**Documentation**: [Architecture Overview](../core-concepts/architecture.md) β†’ [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md){:target="_blank"} ### 4. Network Layer - libp2p-based P2P (Gossipsub, reliable streams, DHT discovery) -- JSON-RPC server for client interaction -- WebSocket/SSE for real-time subscriptions +- [JSON-RPC](https://www.jsonrpc.org/){:target="_blank"} server for client interaction +- [WebSocket](https://en.wikipedia.org/wiki/WebSocket){:target="_blank"}/[SSE](https://en.wikipedia.org/wiki/Server-sent_events){:target="_blank"} for real-time subscriptions - Authentication and authorization -**Documentation**: [Reference](../reference/index.md) β†’ [`core/crates/network/README.md`](https://github.com/calimero-network/core/blob/master/crates/network/README.md) +**Documentation**: [Reference](../reference/index.md) β†’ [`core/crates/network/README.md`](https://github.com/calimero-network/core/blob/master/crates/network/README.md){:target="_blank"} ## How It Works (Transaction Flow) @@ -147,14 +147,14 @@ For detailed component explanations, see [Architecture Overview](../core-concept ## Next Steps -- πŸ“– **New to Calimero?** β†’ [Getting Started](../getting-started/index.md) -- πŸ—οΈ **Ready to build?** β†’ [Builder Directory](../builder-directory/index.md) -- πŸŽ“ **Want to learn?** β†’ [Core Concepts](../core-concepts/index.md) -- βš™οΈ **Need to operate?** β†’ [Operator Track](../operator-track/index.md) +- **New to Calimero?** β†’ [Getting Started](../getting-started/index.md) +- **Ready to build?** β†’ [Builder Directory](../builder-directory/index.md) +- **Want to learn?** β†’ [Core Concepts](../core-concepts/index.md) +- **Need to operate?** β†’ [Operator Track](../operator-track/index.md) --- -**Built with ❀️ by the Calimero Network team** +**Built by the Calimero Network team** -For questions, reach out on [Discord](https://discord.gg/wZRC73DVpU) or [GitHub Issues](https://github.com/calimero-network/core/issues). +For questions, reach out on [Discord](https://discord.gg/wZRC73DVpU){:target="_blank"}, [GitHub Issues](https://github.com/calimero-network/core/issues){:target="_blank"}, or email [support@calimero.network](mailto:support@calimero.network){:target="_blank"}. diff --git a/docs/javascripts/sidebar.js b/docs/javascripts/sidebar.js index 1552e10..af9e705 100644 --- a/docs/javascripts/sidebar.js +++ b/docs/javascripts/sidebar.js @@ -1,5 +1,8 @@ document$.subscribe(() => { const hideIfSingle = (selector) => { + // Only hide sidebars on desktop (min-width: 76.25rem = 1220px) + if (window.innerWidth < 1220) return; + const sidebar = document.querySelector(selector); if (!sidebar) return; @@ -19,4 +22,17 @@ document$.subscribe(() => { hideIfSingle('.md-sidebar--primary'); hideIfSingle('.md-sidebar--secondary'); + + // Make repository link and social links open in new tab + const repoLink = document.querySelector('.md-source'); + if (repoLink) { + repoLink.setAttribute('target', '_blank'); + repoLink.setAttribute('rel', 'noopener noreferrer'); + } + + // Also apply to social links in footer + document.querySelectorAll('.md-footer__link, .md-social__link').forEach(link => { + link.setAttribute('target', '_blank'); + link.setAttribute('rel', 'noopener noreferrer'); + }); }); diff --git a/docs/operator-track/index.md b/docs/operator-track/index.md index 92d6e88..81ab932 100644 --- a/docs/operator-track/index.md +++ b/docs/operator-track/index.md @@ -6,12 +6,12 @@ Guidance for running and managing Calimero nodes in production. | Task | Guide | Repository Docs | | --- | --- | --- | -| **Local Development** | [Run a Local Network](run-a-local-network.md) | [`merobox/README.md`](https://github.com/calimero-network/merobox#readme) | -| **Monitoring** | [Monitor & Debug](monitor-and-debug.md) | [`core/crates/node/readme/troubleshooting.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/troubleshooting.md) | +| **Local Development** | [Run a Local Network](run-a-local-network.md) | [`merobox/README.md`](https://github.com/calimero-network/merobox#readme){:target="_blank"} | +| **Monitoring** | [Monitor & Debug](monitor-and-debug.md) | [`core/crates/node/readme/troubleshooting.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/troubleshooting.md){:target="_blank"} | ## Running Nodes -For complete node documentation, see [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md). +For complete node documentation, see [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md){:target="_blank"}. **Quick start:** ```bash diff --git a/docs/operator-track/monitor-and-debug.md b/docs/operator-track/monitor-and-debug.md index 2c13e22..de94efe 100644 --- a/docs/operator-track/monitor-and-debug.md +++ b/docs/operator-track/monitor-and-debug.md @@ -53,7 +53,7 @@ docker logs calimero-node-1 --follow ## Troubleshooting -See [`core/crates/node/readme/troubleshooting.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/troubleshooting.md) for: +See [`core/crates/node/readme/troubleshooting.md`](https://github.com/calimero-network/core/blob/master/crates/node/readme/troubleshooting.md){:target="_blank"} for: - Common issues and solutions - Performance tuning - Network problems @@ -65,4 +65,4 @@ Nodes expose metrics at: - **Admin API**: `http://localhost:2528/admin-api/metrics` - **Prometheus**: Configure in node settings -See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) for monitoring configuration. +See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md){:target="_blank"} for monitoring configuration. diff --git a/docs/operator-track/run-a-local-network.md b/docs/operator-track/run-a-local-network.md index ed5a8c2..45e3b26 100644 --- a/docs/operator-track/run-a-local-network.md +++ b/docs/operator-track/run-a-local-network.md @@ -4,7 +4,7 @@ Quick guide to running Calimero nodes locally for development and testing. ## Using Merobox (Recommended) -Merobox is the easiest way to run local networks. See [`merobox/README.md`](https://github.com/calimero-network/merobox#readme) for complete documentation. +Merobox is the easiest way to run local networks. See [`merobox/README.md`](https://github.com/calimero-network/merobox#readme){:target="_blank"} for complete documentation. **Quick start:** ```bash diff --git a/docs/privacy-verifiability-security/index.md b/docs/privacy-verifiability-security/index.md index b29adff..61fc892 100644 --- a/docs/privacy-verifiability-security/index.md +++ b/docs/privacy-verifiability-security/index.md @@ -34,7 +34,7 @@ Calimero is a component of a broader **privacy-oriented architecture** β€” modul ## Hardening Checklist -1. Anchor critical context membership changes to your chosen L1 (NEAR, Ethereum, Starknet, ICP). +1. Anchor critical context membership changes to NEAR. 2. Enable event payload hashing when emitting sensitive data; share full payloads via authenticated channels only. 3. Rotate client keys on a cadence and revoke stale devices at the root key level. 4. Run periodic Merkle checkpoint comparisons across nodes to detect divergence early. @@ -44,10 +44,10 @@ Calimero is a component of a broader **privacy-oriented architecture** β€” modul | Topic | Reference | Why it matters | | --- | --- | --- | -| Runtime architecture & security model | [`calimero-network/core` – Architecture](https://github.com/calimero-network/core#architecture) | Details on `merod`, networking layers, and verification primitives | -| Identity delegation & permissions | [`calimero-network/contracts` – Identity module](https://github.com/calimero-network/contracts/blob/main/README.mdx#identity-module) | How root/client keys, invites, and revocations are enforced | -| Context lifecycle & admin API | [`calimero-network/merobox` – Workflows](https://github.com/calimero-network/merobox#workflows) | Managing contexts, capturing Application IDs, production rollouts | -| Authentication adapters & wallet flows | [`calimero-network/core/apps/auth`](https://github.com/calimero-network/core/tree/main/apps/auth#readme) | Challenge/response flows for NEAR, Ethereum, Starknet, ICP | -| Advanced cryptography experiments | [`calimero-network/experiments/mpc-signer`](https://github.com/calimero-network/experiments/tree/main/mpc-signer#readme) | Threshold signing, multi-party custody, and ZK experiments | +| Runtime architecture & security model | [`calimero-network/core` – Architecture](https://github.com/calimero-network/core#architecture){:target="_blank"} | Details on `merod`, networking layers, and verification primitives | +| Identity delegation & permissions | [`calimero-network/contracts` – Identity module](https://github.com/calimero-network/contracts/blob/main/README.mdx#identity-module){:target="_blank"} | How root/client keys, invites, and revocations are enforced | +| Context lifecycle & admin API | [`calimero-network/merobox` – Workflows](https://github.com/calimero-network/merobox#workflows){:target="_blank"} | Managing contexts, capturing Application IDs, production rollouts | +| Authentication adapters & wallet flows | [`calimero-network/core/apps/auth`](https://github.com/calimero-network/core/tree/main/apps/auth#readme){:target="_blank"} | Challenge/response flows for NEAR | +| Advanced cryptography experiments | [`calimero-network/experiments/mpc-signer`](https://github.com/calimero-network/experiments/tree/main/mpc-signer#readme){:target="_blank"} | Threshold signing, multi-party custody, and ZK experiments | _This page stays high-level. For full setup steps, audit procedures, and API details, follow the linked READMEs._ diff --git a/docs/reference/index.md b/docs/reference/index.md index b14877a..2f68ed9 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -32,15 +32,15 @@ Most endpoints require JWT authentication. See [Identity](../core-concepts/ident For complete API documentation, including all methods, request/response formats, and error codes: -**β†’ [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md)** +**β†’ [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md){:target="_blank"}** ## Client SDKs For easier client development, use the official SDKs: -- **JavaScript/TypeScript**: [`@calimero/client`](https://github.com/calimero-network/calimero-client-js) - See [Client SDKs](../tools-apis/client-sdks.md) -- **Python**: [`calimero-client-py`](https://github.com/calimero-network/calimero-client-py) - See [Client SDKs](../tools-apis/client-sdks.md) -- **Rust**: [`core/crates/client`](https://github.com/calimero-network/core/blob/master/crates/client/README.md) +- **JavaScript/TypeScript**: [`@calimero/client`](https://github.com/calimero-network/calimero-client-js){:target="_blank"} - See [Client SDKs](../tools-apis/client-sdks.md) +- **Python**: [`calimero-client-py`](https://github.com/calimero-network/calimero-client-py){:target="_blank"} - See [Client SDKs](../tools-apis/client-sdks.md) +- **Rust**: [`core/crates/client`](https://github.com/calimero-network/core/blob/master/crates/client/README.md){:target="_blank"} ## CLI Reference diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 9ed3e04..41389c4 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -142,6 +142,33 @@ [data-md-color-scheme="slate"] .md-header { border-bottom: 1px solid rgba(255, 255, 255, 0.06); + background-color: var(--calimero-neutral-900); +} + +/* LIGHT MODE: Mobile drawer styling */ +[data-md-color-scheme="default"] .md-nav--primary .md-nav__title { + background-color: #FFFFFF; + color: #FFF !important; +} + +[data-md-color-scheme="default"] .md-nav--primary { + background-color: #FFFFFF; +} + +/* DARK MODE: Make text and icons white */ +[data-md-color-scheme="slate"] .md-nav__title { + color: #FFFFFF !important; + background-color: #111111 !important; +} + +[data-md-color-scheme="slate"] .md-source, +[data-md-color-scheme="slate"] .md-source__icon, +[data-md-color-scheme="slate"] .md-source__repository { + color: #FFFFFF !important; +} + +[data-md-color-scheme="slate"] .md-source svg { + fill: #FFFFFF; } [data-md-color-scheme="slate"] .md-tabs { @@ -227,23 +254,30 @@ blockquote { color: var(--calimero-green-500); } -/* Light mode: use black logo and proper header colors */ +/* Light mode: use BLACK logo */ [data-md-color-scheme="default"] .md-header__button.md-logo img, [data-md-color-scheme="default"] .md-logo img { content: url("../assets/img/logo-black.svg"); } +/* Light mode MOBILE: use WHITE logo for mobile drawer */ +@media screen and (max-width: 1219px) { + [data-md-color-scheme="default"] .md-nav--primary .md-nav__title[for="__drawer"] .md-logo img { + content: url("../assets/img/logo-white.svg"); + } +} + [data-md-color-scheme="default"] .md-header { - background-color: var(--md-default-bg-color); - color: var(--md-default-fg-color); - box-shadow: none; - border-bottom: 1px solid var(--md-default-fg-color--lightest); + background: linear-gradient(90deg, rgba(255, 255, 255, 0.95), rgba(240, 246, 222, 0.85)); + border-bottom: 1px solid rgba(31, 31, 31, 0.08); + box-shadow: 0 4px 12px rgba(19, 18, 21, 0.05); } -/* Dark mode: use white logo and proper header colors */ +/* Dark mode: use BLACK logo (swapped) */ [data-md-color-scheme="slate"] .md-header__button.md-logo img, [data-md-color-scheme="slate"] .md-logo img { - content: url("../assets/img/logo-white.svg"); + content: url("../assets/img/logo-black.svg"); + filter: invert(1) brightness(1.2); } [data-md-color-scheme="slate"] .md-header { @@ -314,4 +348,15 @@ blockquote { display: none !important; } +/* Hide repository stats (stars/forks count) */ +.md-source__facts { + display: none; +} + +/* Hide "Made with Material for MkDocs" footer text but keep social links */ +.md-copyright { + opacity: 0; + pointer-events: none; +} + diff --git a/docs/tools-apis/client-sdks.md b/docs/tools-apis/client-sdks.md index 2b98a2e..8793080 100644 --- a/docs/tools-apis/client-sdks.md +++ b/docs/tools-apis/client-sdks.md @@ -246,8 +246,8 @@ match client.list_contexts().await { ### Related Documentation -- **Repository**: [`calimero-network/core/crates/client`](https://github.com/calimero-network/core/tree/master/crates/client) -- **Source code**: [`core/crates/client/src`](https://github.com/calimero-network/core/tree/master/crates/client/src) +- **Repository**: [`calimero-network/core/crates/client`](https://github.com/calimero-network/core/tree/master/crates/client){:target="_blank"} +- **Source code**: [`core/crates/client/src`](https://github.com/calimero-network/core/tree/master/crates/client/src){:target="_blank"} ## Python Client SDK @@ -424,9 +424,9 @@ python example_usage.py ### Related Documentation -- **Repository**: [`calimero-network/calimero-client-py`](https://github.com/calimero-network/calimero-client-py) -- **PyPI Package**: [`calimero-client-py`](https://pypi.org/project/calimero-client-py/) -- **README**: [`calimero-client-py/README.md`](https://github.com/calimero-network/calimero-client-py/blob/master/README.md) +- **Repository**: [`calimero-network/calimero-client-py`](https://github.com/calimero-network/calimero-client-py){:target="_blank"} +- **PyPI Package**: [`calimero-client-py`](https://pypi.org/project/calimero-client-py/){:target="_blank"} +- **README**: [`calimero-client-py/README.md`](https://github.com/calimero-network/calimero-client-py/blob/master/README.md){:target="_blank"} ## JavaScript Client SDK @@ -513,7 +513,7 @@ function App() { The JavaScript client has **full authentication support** including: - **JWT token management** - Automatic token storage and refresh -- **Wallet-based authentication** - Support for NEAR, Ethereum, and other wallets +- **Wallet-based authentication** - Support for NEAR wallet - **React components** - Pre-built UI components (`ClientLogin`, `SetupModal`) - **Manual token handling** - Direct token management APIs @@ -721,9 +721,9 @@ try { ### Related Documentation -- **Repository**: [`calimero-network/calimero-client-js`](https://github.com/calimero-network/calimero-client-js) -- **NPM Package**: [`@calimero-network/calimero-client`](https://www.npmjs.com/package/@calimero-network/calimero-client) -- **README**: [`calimero-client-js/README.md`](https://github.com/calimero-network/calimero-client-js/blob/master/README.md) +- **Repository**: [`calimero-network/calimero-client-js`](https://github.com/calimero-network/calimero-client-js){:target="_blank"} +- **NPM Package**: [`@calimero-network/calimero-client`](https://www.npmjs.com/package/@calimero-network/calimero-client){:target="_blank"} +- **README**: [`calimero-client-js/README.md`](https://github.com/calimero-network/calimero-client-js/blob/master/README.md){:target="_blank"} ## Comparison diff --git a/docs/tools-apis/developer-tools.md b/docs/tools-apis/developer-tools.md index 19911c8..fba97c9 100644 --- a/docs/tools-apis/developer-tools.md +++ b/docs/tools-apis/developer-tools.md @@ -216,9 +216,9 @@ def test_my_app(calimero_cluster): ### Related Documentation -- **Repository**: [`calimero-network/merobox`](https://github.com/calimero-network/merobox) -- **PyPI Package**: [`merobox`](https://pypi.org/project/merobox/) -- **README**: [`merobox/README.md`](https://github.com/calimero-network/merobox/blob/master/README.md) +- **Repository**: [`calimero-network/merobox`](https://github.com/calimero-network/merobox){:target="_blank"} +- **PyPI Package**: [`merobox`](https://pypi.org/project/merobox/){:target="_blank"} +- **README**: [`merobox/README.md`](https://github.com/calimero-network/merobox/blob/master/README.md){:target="_blank"} ## ABI Codegen @@ -413,9 +413,9 @@ Add to your `package.json`: ### Related Documentation -- **Repository**: [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js) -- **NPM Package**: [`@calimero-network/abi-codegen`](https://www.npmjs.com/package/@calimero-network/abi-codegen) -- **README**: [`mero-devtools-js/README.md`](https://github.com/calimero-network/mero-devtools-js/blob/master/README.md) +- **Repository**: [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js){:target="_blank"} +- **NPM Package**: [`@calimero-network/abi-codegen`](https://www.npmjs.com/package/@calimero-network/abi-codegen){:target="_blank"} +- **README**: [`mero-devtools-js/README.md`](https://github.com/calimero-network/mero-devtools-js/blob/master/README.md){:target="_blank"} ## create-mero-app @@ -461,7 +461,7 @@ pnpm dev ### What Gets Generated -The tool clones the [`calimero-network/kv-store`](https://github.com/calimero-network/kv-store) repository and copies: +The tool clones the [`calimero-network/kv-store`](https://github.com/calimero-network/kv-store){:target="_blank"} repository and copies: - **Rust Application** (`logic/`) - WASM application with CRDT state - **React Frontend** (`app/`) - React application with TypeScript @@ -504,7 +504,7 @@ After scaffolding, customize your app: ### Next Steps -1. **Build the WASM** - Compile Rust to WASM: `cd logic && ./build.sh` +1. **Build the WASM** - Compile Rust or TypeScript to WASM: `cd logic && ./build.sh` 2. **Generate TypeScript Client** - Use ABI codegen to generate client types 3. **Start Local Network** - Use Merobox to start local nodes: `merobox bootstrap run workflows/local-network.yml` 4. **Run Frontend** - Start the React app: `cd app && pnpm dev` @@ -519,10 +519,10 @@ After scaffolding, customize your app: ### Related Documentation -- **Repository**: [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js) -- **NPM Package**: [`create-mero-app`](https://www.npmjs.com/package/create-mero-app) -- **README**: [`mero-devtools-js/create-mero-app/README.md`](https://github.com/calimero-network/mero-devtools-js/blob/master/create-mero-app/README.md) -- **kv-store Example**: [`calimero-network/kv-store`](https://github.com/calimero-network/kv-store) +- **Repository**: [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js){:target="_blank"} +- **NPM Package**: [`create-mero-app`](https://www.npmjs.com/package/create-mero-app){:target="_blank"} +- **README**: [`mero-devtools-js/create-mero-app/README.md`](https://github.com/calimero-network/mero-devtools-js/blob/master/create-mero-app/README.md){:target="_blank"} +- **kv-store Example**: [`calimero-network/kv-store`](https://github.com/calimero-network/kv-store){:target="_blank"} ## Complete Development Workflow diff --git a/docs/tools-apis/index.md b/docs/tools-apis/index.md index dc499d7..6b81df9 100644 --- a/docs/tools-apis/index.md +++ b/docs/tools-apis/index.md @@ -9,9 +9,9 @@ Use this directory as a jumping-off point; it shows you **what exists** and **wh | Tool | Reference | Notes | | --- | --- | --- | -| `merod` | [`calimero-network/core`](https://github.com/calimero-network/core#readme) | Node runtime orchestrating WASM apps, storage, networking, RPC. | -| `meroctl` | [CLI Reference](meroctl-cli.md) | Command-line surface for context lifecycle, deployment, diagnostics. See also [`core/crates/meroctl`](https://github.com/calimero-network/core/tree/master/crates/meroctl) for source code. | -| Admin Dashboard | [`calimero-network/admin-dashboard`](https://github.com/calimero-network/admin-dashboard#readme) | Web UI for member management, metrics, alerts. | +| `merod` | [`calimero-network/core`](https://github.com/calimero-network/core#readme){:target="_blank"} | Node runtime orchestrating WASM apps, storage, networking, RPC. | +| `meroctl` | [CLI Reference](meroctl-cli.md) | Command-line surface for context lifecycle, deployment, diagnostics. See also [`core/crates/meroctl`](https://github.com/calimero-network/core/tree/master/crates/meroctl){:target="_blank"} for source code. | +| Admin Dashboard | [`calimero-network/admin-dashboard`](https://github.com/calimero-network/admin-dashboard#readme){:target="_blank"} | Web UI for member management, metrics, alerts. | ## Developer Tooling @@ -21,11 +21,10 @@ Use this directory as a jumping-off point; it shows you **what exists** and **wh | Tool | Reference | Notes | | --- | --- | --- | | Developer Tools | [Developer Tools Guide](developer-tools.md) | Comprehensive guide to Merobox (local networks), ABI Codegen (TypeScript generation), and create-mero-app (boilerplate scaffolding). | -| Merobox | [`calimero-network/merobox`](https://github.com/calimero-network/merobox#readme) | Docker workflows for local multi-node networks, testing, and workflow orchestration. | -| ABI Codegen | [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js#readme) | Generate TypeScript clients from Rust application ABIs. | -| create-mero-app | [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js#readme) | Scaffold new Calimero apps from kv-store boilerplate. | -| Design System | [`calimero-network/design-system`](https://github.com/calimero-network/design-system#readme) | Shared UI components and tokens. | -| Plugins | [`calimero-network/plugins`](https://github.com/calimero-network/plugins#readme) | Automation hooks and extension samples. | +| Merobox | [`calimero-network/merobox`](https://github.com/calimero-network/merobox#readme){:target="_blank"} | Docker workflows for local multi-node networks, testing, and workflow orchestration. | +| ABI Codegen | [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js#readme){:target="_blank"} | Generate TypeScript clients from Rust application ABIs. | +| create-mero-app | [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js#readme){:target="_blank"} | Scaffold new Calimero apps from kv-store boilerplate. | +| Design System | [`calimero-network/design-system`](https://github.com/calimero-network/design-system#readme){:target="_blank"} | Shared UI components and tokens. | ## SDKs & Clients @@ -35,17 +34,17 @@ Use this directory as a jumping-off point; it shows you **what exists** and **wh | SDK | Reference | Notes | | --- | --- | --- | | Client SDKs | [Client SDKs Guide](client-sdks.md) | Comprehensive guide to Rust, Python, and JavaScript client SDKs for interacting with Calimero nodes. | -| JavaScript Client | [`calimero-network/calimero-client-js`](https://github.com/calimero-network/calimero-client-js#readme) | Browser/Node bindings, event streaming, auth helpers. βœ… Full authentication support. | -| Python Client | [`calimero-network/calimero-client-py`](https://github.com/calimero-network/calimero-client-py#readme) | Python bindings, ABI tooling, automation recipes. ⚠️ Authentication support planned. | -| Rust Client | [`calimero-network/core/crates/client`](https://github.com/calimero-network/core/tree/master/crates/client) | Rust client SDK for CLI tools and sidecar services. ⚠️ Authentication support planned. | -| Rust SDK | [`calimero-network/core/crates/sdk`](https://github.com/calimero-network/core/tree/master/crates/sdk) | App macros, storage primitives, state helpers. For building Calimero applications. | +| JavaScript Client | [`calimero-network/calimero-client-js`](https://github.com/calimero-network/calimero-client-js#readme){:target="_blank"} | Browser/Node bindings, event streaming, auth helpers. βœ… Full authentication support. | +| Python Client | [`calimero-network/calimero-client-py`](https://github.com/calimero-network/calimero-client-py#readme){:target="_blank"} | Python bindings, ABI tooling, automation recipes. ⚠️ Authentication support planned. | +| Rust Client | [`calimero-network/core/crates/client`](https://github.com/calimero-network/core/tree/master/crates/client){:target="_blank"} | Rust client SDK for CLI tools and sidecar services. ⚠️ Authentication support planned. | +| Rust SDK | [`calimero-network/core/crates/sdk`](https://github.com/calimero-network/core/tree/master/crates/sdk){:target="_blank"} | App macros, storage primitives, state helpers. For building Calimero applications. | ## Automation & Workflows | Resource | Reference | Notes | | --- | --- | --- | -| Merobox Workflows | [`workflows/` in example repos](https://github.com/calimero-network/battleships/tree/main/workflows) | Reusable network topologies for local + CI. | -| Docs & CI scripts | [`calimero-network/docs`](https://github.com/calimero-network/docs#readme) | MkDocs site, link policies, CI glue. | +| Merobox Workflows | [`workflows/` in example repos](https://github.com/calimero-network/battleships/tree/main/workflows){:target="_blank"} | Reusable network topologies for local + CI. | +| Docs & CI scripts | [`calimero-network/docs`](https://github.com/calimero-network/docs#readme){:target="_blank"} | MkDocs site, link policies, CI glue. | !!! tip Pick a tool, follow its README end-to-end, then link back into MKDocs when you need a refresher. These pages stay minimal by design. diff --git a/docs/tools-apis/meroctl-cli.md b/docs/tools-apis/meroctl-cli.md index c6471aa..48a7cfc 100644 --- a/docs/tools-apis/meroctl-cli.md +++ b/docs/tools-apis/meroctl-cli.md @@ -311,7 +311,7 @@ meroctl --node node1 context ls For detailed CLI documentation: -- **Source Code**: [`core/crates/meroctl`](https://github.com/calimero-network/core/tree/master/crates/meroctl) - Full implementation +- **Source Code**: [`core/crates/meroctl`](https://github.com/calimero-network/core/tree/master/crates/meroctl){:target="_blank"} - Full implementation - **Examples**: See `EXAMPLES` constants in source files for more usage patterns ## Related Topics diff --git a/mkdocs.yml b/mkdocs.yml index 99d2f03..789c394 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,7 +4,7 @@ site_description: Lightweight documentation for the Calimero network and develop site_url: https://docs.calimero.network # Repository -repo_url: https://github.com/calimero-network/docs +repo_url: https://github.com/calimero-network edit_uri: "" # Theme Configuration @@ -147,9 +147,9 @@ nav: extra: social: - icon: fontawesome/brands/github - link: https://github.com/calimero-network/docs - - icon: fontawesome/brands/twitter - link: https://twitter.com/CalimeroNetwork + link: https://github.com/calimero-network + - icon: fontawesome/brands/x-twitter + link: https://x.com/CalimeroNetwork - icon: fontawesome/solid/globe link: https://calimero.network