From d8f2c14778db0ee87c59a02672d334309035ced2 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sat, 8 Nov 2025 07:37:28 +0100 Subject: [PATCH 01/22] landing --- docs/app-directory/index.md | 9 + docs/builder-directory/index.md | 15 +- docs/core-concepts/applications.md | 7 + docs/core-concepts/architecture.md | 7 + docs/core-concepts/contexts.md | 7 + docs/core-concepts/identity.md | 7 + docs/core-concepts/index.md | 39 +++ docs/core-concepts/nodes.md | 7 + docs/examples/additional-templates.md | 7 + docs/examples/battleships.md | 7 + docs/examples/index.md | 35 ++ docs/examples/shared-todo-backlog.md | 7 + docs/examples/split-bills.md | 7 + .../build-your-first-application.md | 7 + docs/getting-started/index.md | 32 ++ .../getting-started/installation-checklist.md | 6 + .../launch-your-first-context.md | 7 + .../getting-started/sample-app-walkthrough.md | 7 + docs/index.md | 54 ++- docs/intro/index.md | 14 - docs/javascripts/sidebar.js | 22 ++ docs/operator-track/index.md | 33 ++ docs/operator-track/join-existing-contexts.md | 7 + docs/operator-track/monitor-and-debug.md | 7 + .../production-deployment-notes.md | 7 + docs/operator-track/run-a-local-network.md | 7 + docs/privacy-verifiability-security/index.md | 38 ++ docs/reference/commitments-consistency.md | 7 + docs/reference/error-codes.md | 7 + docs/reference/http-methods.md | 7 + docs/reference/index.md | 42 +++ docs/reference/response-envelope.md | 7 + docs/reference/versioning-changelog.md | 7 + docs/reference/websocket-streams.md | 7 + docs/stylesheets/extra.css | 327 +++++++++++++----- docs/support/contact-channels.md | 7 + docs/support/contribution-guide.md | 7 + docs/support/faq.md | 7 + docs/support/index.md | 32 ++ docs/support/roadmap-feedback.md | 7 + docs/tools-apis/index.md | 105 ++---- mkdocs.yml | 55 ++- 42 files changed, 853 insertions(+), 187 deletions(-) create mode 100644 docs/core-concepts/applications.md create mode 100644 docs/core-concepts/architecture.md create mode 100644 docs/core-concepts/contexts.md create mode 100644 docs/core-concepts/identity.md create mode 100644 docs/core-concepts/index.md create mode 100644 docs/core-concepts/nodes.md create mode 100644 docs/examples/additional-templates.md create mode 100644 docs/examples/battleships.md create mode 100644 docs/examples/index.md create mode 100644 docs/examples/shared-todo-backlog.md create mode 100644 docs/examples/split-bills.md create mode 100644 docs/getting-started/build-your-first-application.md create mode 100644 docs/getting-started/index.md create mode 100644 docs/getting-started/installation-checklist.md create mode 100644 docs/getting-started/launch-your-first-context.md create mode 100644 docs/getting-started/sample-app-walkthrough.md delete mode 100644 docs/intro/index.md create mode 100644 docs/javascripts/sidebar.js create mode 100644 docs/operator-track/index.md create mode 100644 docs/operator-track/join-existing-contexts.md create mode 100644 docs/operator-track/monitor-and-debug.md create mode 100644 docs/operator-track/production-deployment-notes.md create mode 100644 docs/operator-track/run-a-local-network.md create mode 100644 docs/reference/commitments-consistency.md create mode 100644 docs/reference/error-codes.md create mode 100644 docs/reference/http-methods.md create mode 100644 docs/reference/index.md create mode 100644 docs/reference/response-envelope.md create mode 100644 docs/reference/versioning-changelog.md create mode 100644 docs/reference/websocket-streams.md create mode 100644 docs/support/contact-channels.md create mode 100644 docs/support/contribution-guide.md create mode 100644 docs/support/faq.md create mode 100644 docs/support/index.md create mode 100644 docs/support/roadmap-feedback.md diff --git a/docs/app-directory/index.md b/docs/app-directory/index.md index 969c11b..d4f2864 100644 --- a/docs/app-directory/index.md +++ b/docs/app-directory/index.md @@ -14,3 +14,12 @@ To get started: 3. Run it within your Calimero environment to test and customize. 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) diff --git a/docs/builder-directory/index.md b/docs/builder-directory/index.md index afb91c7..97ce5ea 100644 --- a/docs/builder-directory/index.md +++ b/docs/builder-directory/index.md @@ -18,7 +18,7 @@ Before we dive in, here are the tools we'll be using: Don't worry about installing these individually - the setup process will handle it. -## Two Paths to Get Started +## Choose Your Starting Point Choose your adventure: @@ -60,6 +60,19 @@ After setup, follow the README instructions to build and run the app. --- +## Minimal Dev Loop + +1. `pnpm install` — fetch dependencies for root and generated subdirectories. +2. `pnpm logic:build` — compile the Rust WASM and regenerate ABI clients. +3. `pnpm network:bootstrap` — start Merobox, deploy the WASM, capture the **Application ID**. +4. Update your frontend config with the Application ID and context ID. +5. `pnpm dev` — run React/Vite with hot reload alongside `logic:watch`. +6. Open two browser tabs, join the context, and iterate on gameplay or flows. + +Keep this loop handy; the walkthrough below explains each step in detail and shows where the commands live. + +--- + ## 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. diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md new file mode 100644 index 0000000..4eda35e --- /dev/null +++ b/docs/core-concepts/applications.md @@ -0,0 +1,7 @@ +# Applications + +_Stub page — describe the Calimero application model._ + +- TODO: Explain WASM runtime, deterministic execution, event system. +- TODO: Cover private storage (`#[app::private]`) and CRDT state. +- TODO: Link to SDK documentation for ABI generation and client bindings. diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md new file mode 100644 index 0000000..10e9d0d --- /dev/null +++ b/docs/core-concepts/architecture.md @@ -0,0 +1,7 @@ +# Architecture Overview + +_Stub page — tie together contexts, nodes, applications, identity._ + +- TODO: Add end-to-end sequence diagram showing request flow. +- TODO: Include repository map referencing core components. +- TODO: Summarize how CRDT sync and proofs work across nodes. diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md new file mode 100644 index 0000000..2acb657 --- /dev/null +++ b/docs/core-concepts/contexts.md @@ -0,0 +1,7 @@ +# Contexts + +_Stub page — explain context isolation and lifecycle._ + +- TODO: Add diagram showing shared state vs private storage. +- TODO: Describe invitation flow, membership, and revocation. +- TODO: Link to `core` and `merobox` READMEs when anchors are ready. diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md new file mode 100644 index 0000000..7a4437d --- /dev/null +++ b/docs/core-concepts/identity.md @@ -0,0 +1,7 @@ +# Identity + +_Stub page — cover root vs client keys and wallet adapters._ + +- TODO: Explain hierarchical key management and revocation. +- TODO: Summarize NEAR/Ethereum/Starknet/ICP authentication flows. +- TODO: Reference `contracts` README for identity module details. diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md new file mode 100644 index 0000000..f537396 --- /dev/null +++ b/docs/core-concepts/index.md @@ -0,0 +1,39 @@ +# Core Concepts + +> Placeholder overview — flesh out once concept briefs are ready. + +- [Contexts](contexts.md) +- [Identity](identity.md) +- [Applications](applications.md) +- [Nodes](nodes.md) +- [Architecture Overview](architecture.md) + +## Contexts + +- Describe isolation model, lifecycle, invitations. +- Plan to embed simplified diagram. +- Link to `core` and `merobox` READMEs once anchors exist. + +## Identity + +- Outline root vs client keys and wallet adapters. +- Mention authentication challenges. + +## Applications + +- Summarize WASM runtime, state management, private storage. +- Call out event-driven patterns and ABI generation. + +## Nodes + +- High-level view of `merod`, networking stack, storage layer. +- Reference admin surfaces (dashboard, node console). + +## Architecture Overview + +- Provide end-to-end sequence diagram. +- Include repo map callouts for deeper dives. + +--- + +_This is a structural stub. Populate each section with concise prose, diagrams, and README links later._ diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md new file mode 100644 index 0000000..6fc6582 --- /dev/null +++ b/docs/core-concepts/nodes.md @@ -0,0 +1,7 @@ +# Nodes + +_Stub page — outline the role of `merod` nodes._ + +- TODO: Detail networking stack (libp2p), storage, sync. +- TODO: Explain admin surfaces (JSON-RPC, WebSocket, Admin API). +- TODO: Reference `core` README sections for runtime architecture. diff --git a/docs/examples/additional-templates.md b/docs/examples/additional-templates.md new file mode 100644 index 0000000..07d8a68 --- /dev/null +++ b/docs/examples/additional-templates.md @@ -0,0 +1,7 @@ +# Additional Templates + +_Stub page — catalog other starter apps._ + +- TODO: List KV Store, Demo Blob App, Calimero Curb Chat with short summaries. +- TODO: Add status badges (Maintained/Experimental) when taxonomy is ready. +- TODO: Link to each repository README and workflows. diff --git a/docs/examples/battleships.md b/docs/examples/battleships.md new file mode 100644 index 0000000..13eba1a --- /dev/null +++ b/docs/examples/battleships.md @@ -0,0 +1,7 @@ +# Battleships + +_Stub page — focal example for multiplayer workflow._ + +- TODO: Summarize architecture (context, players, private storage). +- TODO: Include setup steps and dev loop overview. +- TODO: Link to repo README and diagrams. diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 0000000..9a25aa7 --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,35 @@ +# Examples + +> Placeholder directory — expand once example narratives are drafted. + +- [Battleships](battleships.md) +- [Shared Todo Backlog](shared-todo-backlog.md) +- [Split Bills](split-bills.md) +- [Additional Templates](additional-templates.md) + +## Overview + +- Explain tiers (starter, intermediate, advanced). +- Note dependencies before cloning. + +## Battleships + +- One-liner summary. +- TODO: link to README anchors and add diagram. + +## Shared Todo Backlog + +- Highlight CRDT patterns and UI workflow. + +## Split Bills + +- Summarize delegation and settlement flows. + +## Additional Templates + +- KV Store, Demo Blob App, Calimero Curb Chat. +- Plan to add link list with status badges. + +--- + +_This is a scaffold; replace bullet notes with final copy and links._ diff --git a/docs/examples/shared-todo-backlog.md b/docs/examples/shared-todo-backlog.md new file mode 100644 index 0000000..fe7e223 --- /dev/null +++ b/docs/examples/shared-todo-backlog.md @@ -0,0 +1,7 @@ +# Shared Todo Backlog + +_Stub page — collaborative CRDT example._ + +- TODO: Describe list synchronization and conflict resolution. +- TODO: Provide quickstart steps and UI highlights. +- TODO: Link to repo README and workflow assets. diff --git a/docs/examples/split-bills.md b/docs/examples/split-bills.md new file mode 100644 index 0000000..2690d42 --- /dev/null +++ b/docs/examples/split-bills.md @@ -0,0 +1,7 @@ +# Split Bills + +_Stub page — cover delegation and settlement flows._ + +- TODO: Summarize roles, ledger structure, and payment flow. +- TODO: List setup steps and configuration notes. +- TODO: Link to repository README and diagrams when ready. diff --git a/docs/getting-started/build-your-first-application.md b/docs/getting-started/build-your-first-application.md new file mode 100644 index 0000000..75ceda8 --- /dev/null +++ b/docs/getting-started/build-your-first-application.md @@ -0,0 +1,7 @@ +# Build Your First Application + +_Stub page — map the template scaffold and dev loop._ + +- TODO: Outline `npx create-mero-app` workflow and generated structure. +- TODO: Explain `pnpm logic:build` → ABI generation → frontend wiring. +- TODO: Link to `mero-devtools-js` README for deeper instructions. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 0000000..538a804 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,32 @@ +# Getting Started + +> Placeholder content — to be filled with detailed guidance. + +- [Installation Checklist](installation-checklist.md) +- [Launch Your First Context](launch-your-first-context.md) +- [Build Your First Application](build-your-first-application.md) +- [Sample App Walkthrough](sample-app-walkthrough.md) + +## Installation Checklist + +- Outline required tooling (Docker, `merod`, `meroctl`, `merobox`). +- Provide quick commands for macOS/Linux/Windows. + +## Launch Your First Context + +- Step-by-step summary of running a Merobox workflow. +- Note to embed diagram linking to `calimero-network/merobox` README. + +## Build Your First Application + +- Flow chart for template scaffold → logic build → ABI generation. +- Link to `mero-devtools-js` quickstart when published. + +## Sample App Walkthrough + +- Highlight Battleships as the reference path. +- Call out where to embed screenshots/diagram. + +--- + +_This page is a scaffold; fill each section with concise text and links when assets are ready._ diff --git a/docs/getting-started/installation-checklist.md b/docs/getting-started/installation-checklist.md new file mode 100644 index 0000000..4a7d71f --- /dev/null +++ b/docs/getting-started/installation-checklist.md @@ -0,0 +1,6 @@ +# Installation Checklist + +_Stub page — outline required tooling (Docker, `merod`, `meroctl`, `merobox`) and platform-specific setup steps here._ + +- TODO: Add quick install commands for macOS, Linux, Windows. +- TODO: Link to package references and Homebrew tap. diff --git a/docs/getting-started/launch-your-first-context.md b/docs/getting-started/launch-your-first-context.md new file mode 100644 index 0000000..baf9d33 --- /dev/null +++ b/docs/getting-started/launch-your-first-context.md @@ -0,0 +1,7 @@ +# Launch Your First Context + +_Stub page — detail the Merobox workflow for bootstrapping a local network._ + +- TODO: Provide step-by-step commands using `merobox` workflows. +- TODO: Include diagram depicting nodes, context, Application ID capture. +- TODO: Link back to `merobox` README for full instructions. diff --git a/docs/getting-started/sample-app-walkthrough.md b/docs/getting-started/sample-app-walkthrough.md new file mode 100644 index 0000000..3414c8d --- /dev/null +++ b/docs/getting-started/sample-app-walkthrough.md @@ -0,0 +1,7 @@ +# Sample App Walkthrough + +_Stub page — use Battleships as the reference implementation._ + +- TODO: Summarize gameplay flow and architecture diagram. +- TODO: Provide quick steps to clone, bootstrap, and iterate. +- TODO: Link to other examples once write-ups exist. diff --git a/docs/index.md b/docs/index.md index 85d54bf..dbfe6aa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,52 @@ # Calimero Documentation -Welcome to the Calimero documentation. +## Why Calimero Exists -This site provides an overview of the Calimero network — a decentralized application layer focused on privacy, modularity, and verifiability. +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. -Use the sections below to explore: +- **Calimero is not a blockchain.** +- **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. -- [Introduction](intro/index.md) — the philosophy and core ideas behind Calimero -- [App Directory](app-directory/index.md) — explore and deploy existing applications -- [Builder Directory](builder-directory/index.md) — learn how to build your own Calimero apps -- [Privacy, Verifiability & Security](privacy-verifiability-security/index.md) — understand how Calimero fits into the modular privacy stack +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. + +| 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 | +| 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 | + +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. + +## Quick Actions + +| 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`. | +| [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. | + +## Choose Your Path + +| If you are… | Go to… | Why | +| --- | --- | --- | +| New to Calimero | [Introduction](intro/index.md) | Philosophy, architecture snapshot, and repo map. | +| Shipping an application | [Builder Directory](builder-directory/index.md) | Toolchain checklist, dev loop, and SDK links. | +| Evaluating existing apps | [App Directory](app-directory/index.md) | Spot maintained demos with direct README links. | +| Securing deployments | [Privacy · Verifiability · Security](privacy-verifiability-security/index.md) | Isolation model, identity delegation, auditability patterns. | +| Looking for tooling | [Tools & APIs](tools-apis/index.md) | Runtime, admin, SDK, and automation catalog. | + +## 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 diff --git a/docs/intro/index.md b/docs/intro/index.md deleted file mode 100644 index 19411ef..0000000 --- a/docs/intro/index.md +++ /dev/null @@ -1,14 +0,0 @@ -# Introduction - -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. - -## What Calimero Is (and Isn’t) - -- **Calimero is not a blockchain.** -- **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. - -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. diff --git a/docs/javascripts/sidebar.js b/docs/javascripts/sidebar.js new file mode 100644 index 0000000..1552e10 --- /dev/null +++ b/docs/javascripts/sidebar.js @@ -0,0 +1,22 @@ +document$.subscribe(() => { + const hideIfSingle = (selector) => { + const sidebar = document.querySelector(selector); + if (!sidebar) return; + + const list = sidebar.querySelector('nav > ul.md-nav__list'); + if (!list) return; + + const links = Array.from(list.querySelectorAll('li.md-nav__item > a.md-nav__link')).filter( + (link) => link.offsetParent !== null + ); + + if (links.length <= 1) { + sidebar.classList.add('is-hidden-single'); + } else { + sidebar.classList.remove('is-hidden-single'); + } + }; + + hideIfSingle('.md-sidebar--primary'); + hideIfSingle('.md-sidebar--secondary'); +}); diff --git a/docs/operator-track/index.md b/docs/operator-track/index.md new file mode 100644 index 0000000..4ca11ae --- /dev/null +++ b/docs/operator-track/index.md @@ -0,0 +1,33 @@ +# Operator Track + +> Placeholder road map — fill with actionable guidance as operator docs mature. + +- [Run a Local Network](run-a-local-network.md) +- [Join Existing Contexts](join-existing-contexts.md) +- [Monitor & Debug](monitor-and-debug.md) +- [Production Deployment Notes](production-deployment-notes.md) + +## Run a Local Network + +- Document hardware prerequisites. +- Summarize `merobox` bootstrap steps. +- Link to monitoring endpoints. + +## Join Existing Contexts + +- Explain invite flow, acceptance, and key management. +- Reference admin API endpoints. + +## Monitor & Debug + +- Highlight Admin Dashboard, Node Console, logs, metrics. +- Plan to add screenshots and diagrams. + +## Production Deployment Notes + +- Capture backup strategy, upgrades, observability stack. +- Provide checklist for securing nodes in production. + +--- + +_Stub content: expand each section with concise instructions and canonical README links._ diff --git a/docs/operator-track/join-existing-contexts.md b/docs/operator-track/join-existing-contexts.md new file mode 100644 index 0000000..ae58935 --- /dev/null +++ b/docs/operator-track/join-existing-contexts.md @@ -0,0 +1,7 @@ +# Join Existing Contexts + +_Stub page — explain invitations and membership management._ + +- TODO: Document invite issuance, acceptance, and key rotation. +- TODO: Reference admin API endpoints for context membership. +- TODO: Add flow diagram showing invite lifecycle. diff --git a/docs/operator-track/monitor-and-debug.md b/docs/operator-track/monitor-and-debug.md new file mode 100644 index 0000000..f343576 --- /dev/null +++ b/docs/operator-track/monitor-and-debug.md @@ -0,0 +1,7 @@ +# Monitor & Debug + +_Stub page — outline observability tools and procedures._ + +- TODO: Highlight Admin Dashboard, Node Console, log streams. +- TODO: Describe common health checks and alert thresholds. +- TODO: Link to troubleshooting sections in repo READMEs. diff --git a/docs/operator-track/production-deployment-notes.md b/docs/operator-track/production-deployment-notes.md new file mode 100644 index 0000000..5e777de --- /dev/null +++ b/docs/operator-track/production-deployment-notes.md @@ -0,0 +1,7 @@ +# Production Deployment Notes + +_Stub page — provide guidance for running Calimero in production._ + +- TODO: Document backup strategy, node upgrades, rolling deployments. +- TODO: Summarize security hardening (firewalls, key rotation, monitoring). +- TODO: Link to infra-as-code examples or reference architectures. diff --git a/docs/operator-track/run-a-local-network.md b/docs/operator-track/run-a-local-network.md new file mode 100644 index 0000000..a8cae14 --- /dev/null +++ b/docs/operator-track/run-a-local-network.md @@ -0,0 +1,7 @@ +# Run a Local Network + +_Stub page — outline requirements and bootstrap steps._ + +- TODO: List hardware prerequisites and Docker requirements. +- TODO: Provide `merobox` workflow example with explanation. +- TODO: Link to monitoring commands and health checks. diff --git a/docs/privacy-verifiability-security/index.md b/docs/privacy-verifiability-security/index.md index 749a690..b29adff 100644 --- a/docs/privacy-verifiability-security/index.md +++ b/docs/privacy-verifiability-security/index.md @@ -13,3 +13,41 @@ In this modular stack: - Other tools like **zero-knowledge proofs (ZK)** can extend privacy guarantees. Calimero is a component of a broader **privacy-oriented architecture** — modular, composable, and adaptable to your needs. + +## Isolation Model at a Glance + +- **Contexts scope visibility** — each context has shared CRDT state plus per-member private storage (`#[app::private]`). +- **Hierarchical identities** — root keys issue client keys per device or integration; revocation cascades from the root. +- **Deterministic runtime** — WASM apps run inside `merod`, so every state transition is deterministic and replayable. +- **Selective disclosure** — events can reveal only hashed or redacted payloads while full data stays on the owner’s node. +- **Audit trail** — every method call is tied to the caller via `executor_id`, enabling tamper-evident logs. + +## Verification Pathways + +| Layer | What is verified | How | +| --- | --- | --- | +| Context membership | Who can read/write state | Anchored invites or role assignments persisted on-chain | +| State synchronization | CRDT merges, Merkle checkpoints | Nodes exchange proofs before accepting remote updates | +| Application integrity | WASM binaries, configuration | Hashes committed to L1, compared during deployment | +| User actions | Caller identity, authorization | Challenge/response over wallet connector + executor audit logs | +| Data access | Private vs shared storage | Storage namespaces tied to caller identity, enforced in runtime | + +## Hardening Checklist + +1. Anchor critical context membership changes to your chosen L1 (NEAR, Ethereum, Starknet, ICP). +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. +5. Configure node monitoring (Admin Dashboard, Node Console) to alert on failed syncs or unauthorized method calls. + +## Where to Deep Dive + +| 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 | + +_This page stays high-level. For full setup steps, audit procedures, and API details, follow the linked READMEs._ diff --git a/docs/reference/commitments-consistency.md b/docs/reference/commitments-consistency.md new file mode 100644 index 0000000..9722508 --- /dev/null +++ b/docs/reference/commitments-consistency.md @@ -0,0 +1,7 @@ +# Commitments & Consistency Levels + +_Stub page — define processed, confirmed, finalized semantics._ + +- TODO: Provide comparison table across commitment levels. +- TODO: Explain how checkpoints and proofs tie into each level. +- TODO: Link to runtime documentation for detailed guarantees. diff --git a/docs/reference/error-codes.md b/docs/reference/error-codes.md new file mode 100644 index 0000000..4a9415f --- /dev/null +++ b/docs/reference/error-codes.md @@ -0,0 +1,7 @@ +# Error Codes & Retries + +_Stub page — summarize canonical errors and retry guidance._ + +- TODO: List standard error codes with meanings. +- TODO: Recommend retry/backoff strategies per code category. +- TODO: Link to troubleshooting sections in tooling READMEs. diff --git a/docs/reference/http-methods.md b/docs/reference/http-methods.md new file mode 100644 index 0000000..f5beed9 --- /dev/null +++ b/docs/reference/http-methods.md @@ -0,0 +1,7 @@ +# HTTP Methods + +_Stub page — catalog Calimero HTTP endpoints._ + +- TODO: Group methods by domain (Contexts, Applications, Identity, Admin). +- TODO: Provide tables with method, parameters, response shape, notes. +- TODO: Link to auto-generated API specs once available. diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 0000000..4247b5f --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,42 @@ +# Reference + +> Placeholder index — populate with method tables and schemas later. + +- [Commitments & Consistency Levels](commitments-consistency.md) +- [Response Envelope](response-envelope.md) +- [HTTP Methods](http-methods.md) +- [WebSocket Streams](websocket-streams.md) +- [Error Codes & Retries](error-codes.md) +- [Versioning & Changelog](versioning-changelog.md) + +## Commitments & Consistency Levels + +- Define processed/confirmed/finalized semantics. +- Plan to include comparison table. + +## Response Envelope + +- Document standard JSON structure (`context`, `value`, `error`). +- Note to provide sample payloads. + +## HTTP Methods + +- Group endpoints by domain (Contexts, Applications, Identity, Admin). +- Prepare tables with method, params, responses. + +## WebSocket Streams + +- Outline subscription flow and message formats. +- Add example subscribe/unsubscribe sequences. + +## Error Codes & Retries + +- List canonical codes and recommended handling. + +## Versioning & Changelog + +- Describe release cadence and links to repo changelogs. + +--- + +_This section is a scaffold; flesh out with canonical data once API audits conclude._ diff --git a/docs/reference/response-envelope.md b/docs/reference/response-envelope.md new file mode 100644 index 0000000..7c1adb0 --- /dev/null +++ b/docs/reference/response-envelope.md @@ -0,0 +1,7 @@ +# Response Envelope + +_Stub page — document the standard Calimero API response structure._ + +- TODO: Show JSON schema with `context`, `value`, `error` fields. +- TODO: Include success and failure examples. +- TODO: Reference SDK sections for typed client handling. diff --git a/docs/reference/versioning-changelog.md b/docs/reference/versioning-changelog.md new file mode 100644 index 0000000..9a84275 --- /dev/null +++ b/docs/reference/versioning-changelog.md @@ -0,0 +1,7 @@ +# Versioning & Changelog + +_Stub page — outline release cadence and change tracking._ + +- TODO: Describe how versions are tagged across repos. +- TODO: Link to individual `CHANGELOG.md` files. +- TODO: Explain how future site changelog aggregates updates. diff --git a/docs/reference/websocket-streams.md b/docs/reference/websocket-streams.md new file mode 100644 index 0000000..7d3bd5d --- /dev/null +++ b/docs/reference/websocket-streams.md @@ -0,0 +1,7 @@ +# WebSocket Streams + +_Stub page — describe subscription and event streaming._ + +- TODO: Outline subscribe/unsubscribe flow and payload format. +- TODO: Provide sample messages and reconnection guidance. +- TODO: Reference client SDK sections handling real-time updates. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index db1cb65..9ed3e04 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,20 +1,230 @@ /* Custom Calimero Branding Styles */ /* ============================================ - CUSTOM COLORS + CUSTOM COLORS (Calimero Brand Palette) ============================================ */ :root { - --md-accent-fg-color: #A5FF11; + /* Neutrals */ + --calimero-neutral-900: #131215; + --calimero-neutral-800: #222222; + --calimero-neutral-700: #282828; + --calimero-neutral-600: #404040; + --calimero-neutral-500: #5C5C5C; + --calimero-neutral-400: #8E8E8E; + --calimero-neutral-300: #A0A0A0; + --calimero-neutral-200: #C8C8C8; + --calimero-neutral-100: #F3F3F3; + + /* Brand greens */ + --calimero-green-900: #2D381B; + --calimero-green-800: #8AA200; + --calimero-green-700: #73B30C; + --calimero-green-600: #A5FF11; + --calimero-green-500: #E0F97A; +} + +/* Light theme (default) */ +[data-md-color-scheme="default"] { + --md-default-bg-color: #F5F5F4; /* light neutral backdrop */ + --md-default-fg-color: #1F1F1F; + --md-primary-fg-color: var(--calimero-green-800); + --md-primary-bg-color: #FFFFFF; + --md-accent-fg-color: var(--calimero-green-700); + --md-accent-bg-color: rgba(115, 179, 12, 0.14); + --md-code-bg-color: #EFEFEF; + --md-code-fg-color: #222222; +} + +[data-md-color-scheme="default"] body, +[data-md-color-scheme="default"] .md-main, +[data-md-color-scheme="default"] .md-content, +[data-md-color-scheme="default"] .md-header, +[data-md-color-scheme="default"] .md-sidebar { + background-color: var(--md-default-bg-color); + color: var(--md-default-fg-color); +} + +[data-md-color-scheme="default"] .md-header { + 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); +} + +[data-md-color-scheme="default"] .md-tabs { + background: linear-gradient(90deg, rgba(240, 246, 222, 0.95), rgba(209, 238, 140, 0.65)); + color: var(--md-default-fg-color); +} + +[data-md-color-scheme="default"] .md-tabs__link { + color: var(--md-default-fg-color); + opacity: 0.8; +} + +[data-md-color-scheme="default"] .md-tabs__item--active .md-tabs__link, +[data-md-color-scheme="default"] .md-tabs__link:hover { + color: var(--calimero-green-800); + opacity: 1; +} + +[data-md-color-scheme="default"] .md-sidebar__scrollwrap { + background-color: #FFFFFF; + border-right: 1px solid rgba(31, 31, 31, 0.06); +} + +[data-md-color-scheme="default"] .md-nav__link--active { + color: #6B8611; +} + +[data-md-color-scheme="default"] .md-nav__title { + color: #4E5F17; +} + +[data-md-color-scheme="default"] .md-typeset a { + color: #58730A; +} + +[data-md-color-scheme="default"] .md-typeset a:hover { + color: #3E5207; +} + +[data-md-color-scheme="default"] .md-typeset h1, +[data-md-color-scheme="default"] .md-typeset h2, +[data-md-color-scheme="default"] .md-typeset h3 { + color: #202320; +} + +[data-md-color-scheme="default"] .md-typeset table:not([class]) th { + background-color: rgba(138, 162, 0, 0.22); + color: #222222; +} + +[data-md-color-scheme="default"] .md-typeset table:not([class]) tbody tr { + background-color: rgba(255, 255, 255, 0.9); +} + +[data-md-color-scheme="default"] .md-typeset table:not([class]) tbody tr:nth-child(2n) { + background-color: rgba(240, 240, 240, 0.9); +} + +[data-md-color-scheme="default"] .md-typeset .admonition, +[data-md-color-scheme="default"] .md-typeset details { + background-color: rgba(209, 238, 140, 0.25); + border-color: rgba(115, 179, 12, 0.6); +} + +[data-md-color-scheme="default"] blockquote { + border-left: 0.25rem solid rgba(115, 179, 12, 0.7); + background-color: rgba(255, 255, 255, 0.85); + color: #262626; +} + +[data-md-color-scheme="default"] .md-button--primary { + background: var(--calimero-green-700); + color: #111; +} + +[data-md-color-scheme="default"] .md-button--primary:hover { + background: var(--calimero-green-600); +} + +/* Dark theme (slate) */ +[data-md-color-scheme="slate"] { + --md-default-bg-color: var(--calimero-neutral-900); + --md-default-fg-color: #E5E5E5; + --md-primary-fg-color: var(--calimero-green-600); + --md-primary-bg-color: var(--calimero-neutral-900); + --md-accent-fg-color: var(--calimero-green-600); + --md-accent-bg-color: rgba(165, 255, 17, 0.1); + --md-code-bg-color: rgba(40, 40, 40, 0.85); + --md-code-fg-color: #E5E5E5; +} + +[data-md-color-scheme="slate"] .md-header { + border-bottom: 1px solid rgba(255, 255, 255, 0.06); +} + +[data-md-color-scheme="slate"] .md-tabs { + background: linear-gradient(90deg, rgba(45, 56, 27, 0.9), rgba(73, 140, 24, 0.6)); + color: var(--md-default-fg-color); +} + +[data-md-color-scheme="slate"] .md-tabs__link { + color: var(--md-default-fg-color); + opacity: 0.75; +} + +[data-md-color-scheme="slate"] .md-tabs__link:hover, +[data-md-color-scheme="slate"] .md-tabs__link--active { + color: var(--calimero-green-600); + opacity: 1; } /* Content body link colors */ .md-typeset a { - color: #8AA200; + color: var(--calimero-green-600); } .md-typeset a:hover { - color: #A5FF11; + color: var(--calimero-green-700); +} + +/* Card and blockquote styling */ +.md-typeset .admonition, +.md-typeset details { + background-color: rgba(45, 56, 27, 0.35); + border-color: var(--calimero-green-800); +} + +blockquote { + border-left: 0.25rem solid var(--calimero-green-700); + background-color: rgba(19, 18, 21, 0.6); +} + +/* Table styling */ +.md-typeset table:not([class]) th { + background-color: rgba(138, 162, 0, 0.15); + color: var(--md-default-fg-color); +} + +.md-typeset table:not([class]) tbody tr { + background-color: rgba(34, 34, 34, 0.5); +} + +.md-typeset table:not([class]) tbody tr:nth-child(2n) { + background-color: rgba(40, 40, 40, 0.6); +} + +/* Tabs navigation */ +.md-tabs { + background: linear-gradient(90deg, rgba(45, 56, 27, 0.9), rgba(73, 140, 24, 0.6)); + color: var(--md-default-fg-color); +} + +.md-tabs__link { + color: var(--md-default-fg-color); + opacity: 0.75; +} + +.md-tabs__link:hover, +.md-tabs__link--active { + color: var(--calimero-green-600); + opacity: 1; +} + +/* Buttons */ +.md-button--primary { + background: var(--calimero-green-700); + color: #0E0F0E; +} + +.md-button--primary:hover { + background: var(--calimero-green-600); +} + +/* Sidebar headings */ +.md-nav__title { + color: var(--calimero-green-500); } /* Light mode: use black logo and proper header colors */ @@ -68,105 +278,40 @@ LAYOUT IMPROVEMENTS ============================================ */ -/* Hide sidebars on desktop only (NOT on mobile - needed for hamburger menu) */ -@media screen and (min-width: 60em) { +/* Swap sidebars so main navigation appears on the left and page table of contents on the right */ +@media screen and (min-width: 76.25rem) { .md-sidebar--primary { - display: none !important; + order: 1; + border-right: 1px solid var(--md-default-fg-color--lightest); } - - .md-sidebar--secondary { - display: none !important; - } -} -/* Wider content area - no sidebars on desktop */ -.md-main__inner { - max-width: none; -} - -.md-content { - max-width: 1200px; - margin: 0 auto; -} - -/* Remove margins for sidebars on desktop */ -@media screen and (min-width: 60em) { - .md-content__inner { - margin-left: 0; - margin-right: 0; - } -} - -/* ============================================ - MOBILE OPTIMIZATIONS - ============================================ */ - -/* Mobile-specific padding to prevent text from touching edges */ -@media screen and (max-width: 59.99em) { - /* Main content padding */ - .md-content__inner { - padding-left: 1.5rem !important; - padding-right: 1.5rem !important; - } - - /* Typography padding */ - .md-typeset { - padding-left: 0 !important; - padding-right: 0 !important; - } - - /* Ensure proper padding for main grid */ - .md-main { - padding-left: 0; - padding-right: 0; - } - - /* Content container padding */ .md-content { - margin-left: 0; - margin-right: 0; - padding-left: 0; - padding-right: 0; - } - - /* Ensure the primary sidebar (navigation drawer) is visible and functional on mobile */ - .md-sidebar--primary { - display: block !important; - } - - /* Style the navigation drawer when it opens */ - .md-sidebar--primary .md-sidebar__scrollwrap { - background-color: var(--md-default-bg-color); + order: 2; } - - /* Ensure hamburger menu button is visible and clickable */ - .md-header__button.md-icon { - display: inline-block; - color: var(--md-default-fg-color); - } -} -/* Tabs navigation - adapt to light/dark mode */ -.md-tabs { - background-color: var(--md-default-bg-color) !important; - color: var(--md-default-fg-color); + .md-sidebar--secondary { + order: 3; + border-left: 1px solid var(--md-default-fg-color--lightest); + } } -.md-tabs__list { - background-color: var(--md-default-bg-color) !important; +/* Hide the secondary sidebar when there is only a single ToC entry */ +@media screen and (min-width: 76.25rem) { + .md-sidebar--secondary ul.md-nav__list > li:first-child:last-child { + display: none; + } } -.md-tabs__link { - color: var(--md-default-fg-color); - opacity: 0.7; +/* Hide the primary sidebar when there is only a single navigation entry */ +@media screen and (min-width: 76.25rem) { + .md-sidebar--primary nav > ul.md-nav__list:not(:has(> li.md-nav__item:nth-child(2))) { + display: none; + } } -.md-tabs__link:hover { - opacity: 1; +/* Utility class used by sidebar.js to hide sidebars with single items */ +.md-sidebar.is-hidden-single { + display: none !important; } -.md-tabs__link--active { - color: var(--md-primary-fg-color); - opacity: 1; -} diff --git a/docs/support/contact-channels.md b/docs/support/contact-channels.md new file mode 100644 index 0000000..b0c723a --- /dev/null +++ b/docs/support/contact-channels.md @@ -0,0 +1,7 @@ +# Contact Channels + +_Stub page — list official support avenues._ + +- TODO: Provide Discord invite, GitHub Issues, Discussions, and email. +- TODO: Set expectations for response times and SLAs. +- TODO: Include guidance on what info to include when requesting help. diff --git a/docs/support/contribution-guide.md b/docs/support/contribution-guide.md new file mode 100644 index 0000000..56e8c2c --- /dev/null +++ b/docs/support/contribution-guide.md @@ -0,0 +1,7 @@ +# Contribution Guide + +_Stub page — explain how to contribute to Calimero docs and repos._ + +- TODO: Outline pull request expectations and review checklist. +- TODO: Reference style guide, linting, and testing requirements. +- TODO: Provide link to contributor license agreement if applicable. diff --git a/docs/support/faq.md b/docs/support/faq.md new file mode 100644 index 0000000..25f6b84 --- /dev/null +++ b/docs/support/faq.md @@ -0,0 +1,7 @@ +# FAQ + +_Stub page — capture top troubleshooting questions._ + +- TODO: Add common setup, build, and deployment issues with quick fixes. +- TODO: Link to detailed README sections for deeper guidance. +- TODO: Reference support channels when escalation is needed. diff --git a/docs/support/index.md b/docs/support/index.md new file mode 100644 index 0000000..f9f4b72 --- /dev/null +++ b/docs/support/index.md @@ -0,0 +1,32 @@ +# Support & Community + +> Placeholder hub — fill in once support pathways are confirmed. + +- [FAQ](faq.md) +- [Contact Channels](contact-channels.md) +- [Contribution Guide](contribution-guide.md) +- [Roadmap & Feedback](roadmap-feedback.md) + +## FAQ + +- Capture top troubleshooting questions. +- Include quick fixes and pointers to READMEs. + +## Contact Channels + +- Discord, GitHub Issues, Discussions, email. +- Note response expectations. + +## Contribution Guide + +- Outline how to propose doc updates and code changes. +- Mention style guide and review checklists. + +## Roadmap & Feedback + +- Link to public roadmap or tracking board. +- Provide feedback form or discussion thread links. + +--- + +_Substitute bullets with finalized copy and links once stakeholders approve messaging._ diff --git a/docs/support/roadmap-feedback.md b/docs/support/roadmap-feedback.md new file mode 100644 index 0000000..3aab83c --- /dev/null +++ b/docs/support/roadmap-feedback.md @@ -0,0 +1,7 @@ +# Roadmap & Feedback + +_Stub page — connect users with planning and feedback loops._ + +- TODO: Link to public roadmap or planning board once defined. +- TODO: Provide form or discussion thread for feedback submissions. +- TODO: Summarize how feedback is triaged and prioritized. diff --git a/docs/tools-apis/index.md b/docs/tools-apis/index.md index e0c41c4..68c4b35 100644 --- a/docs/tools-apis/index.md +++ b/docs/tools-apis/index.md @@ -1,85 +1,52 @@ -# Tools and APIs +# Tools & APIs -A comprehensive overview of the core tools and APIs in the Calimero ecosystem. Each tool serves a specific purpose in building, deploying, and managing Calimero applications. +!!! info + Every entry below links to its canonical README. Follow those for installation flags, API surfaces, and deeper guides. ---- +Use this directory as a jumping-off point; it shows you **what exists** and **where to learn more** without duplicating repo docs. -## merod +## Runtime & Admin -**Calimero Node Daemon** +| Tool | Reference | Notes | +| --- | --- | --- | +| `merod` | [`calimero-network/core`](https://github.com/calimero-network/core#readme) | Node runtime orchestrating WASM apps, storage, networking, RPC. | +| `meroctl` | [`calimero-network/core` – CLI](https://github.com/calimero-network/core#cli) | Command-line surface for context lifecycle, deployment, diagnostics. | +| Admin Dashboard | [`calimero-network/admin-dashboard`](https://github.com/calimero-network/admin-dashboard#readme) | Web UI for member management, metrics, alerts. | -The core node implementation that powers the Calimero network. `merod` is the runtime daemon that manages peer-to-peer connections, application contexts, and CRDT-based state synchronization. +## Developer Tooling -**Key Features:** -- P2P networking and peer discovery -- Context management and isolation -- CRDT-based state replication -- WebAssembly application runtime -- Built-in RPC server +| Tool | Reference | Notes | +| --- | --- | --- | +| Merobox | [`calimero-network/merobox`](https://github.com/calimero-network/merobox#readme) | Docker workflows for local multi-node networks and Application ID capture. | +| Mero Devtools JS | [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js#readme) | Scaffolds, ABI generators, TypeScript helpers. | +| 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. | -👉 [View merod on GitHub](https://github.com/calimero-network/core) +## SDKs & Clients ---- +| SDK | Reference | Notes | +| --- | --- | --- | +| JavaScript Client | [`calimero-network/calimero-client-js`](https://github.com/calimero-network/calimero-client-js#readme) | Browser/Node bindings, event streaming, auth helpers. | +| Python Client | [`calimero-network/calimero-client-py`](https://github.com/calimero-network/calimero-client-py#readme) | Python bindings, ABI tooling, automation recipes. | +| Rust SDK | [`calimero-network/core/calimero-sdk-js`](https://github.com/calimero-network/core/tree/main/calimero-sdk-js#readme) | App macros, storage primitives, state helpers. | -## meroctl +## Automation & Workflows -**Calimero Command-Line Interface** +| 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. | +| Homebrew Tap | [`calimero-network/homebrew-tap`](https://github.com/calimero-network/homebrew-tap#readme) | Package distribution for CLI and runtime binaries. | -The primary CLI tool for interacting with Calimero nodes. Use `meroctl` to manage contexts, deploy applications, and configure your node. +## Advanced & Research -**Key Features:** -- Context creation and management -- Application deployment and updates -- Node configuration and monitoring -- Identity and key management -- RPC client for node communication +| Project | Reference | Notes | +| --- | --- | --- | +| MPC Signer | [`calimero-network/experiments/mpc-signer`](https://github.com/calimero-network/experiments/tree/main/mpc-signer#readme) | Threshold signing, custody experiments, ZK exploration. | +| Escrow | [`calimero-network/escrow`](https://github.com/calimero-network/escrow#readme) | Bridge contracts, marketplace patterns, L1 attestations. | -👉 [View meroctl on GitHub](https://github.com/calimero-network/core) - ---- - -## merobox - -**Calimero Development Environment** - -A containerized development environment that bundles everything you need to run a local Calimero network. Perfect for testing and development. - -**Key Features:** -- Pre-configured local node setup -- Hot-reload for rapid development -- Multi-node testing environment -- Isolated development contexts -- Docker-based deployment - -👉 [View merobox on GitHub](https://github.com/calimero-network/merobox) - ---- - -## mero-devtools-js - -**JavaScript/TypeScript Development Kit** - -A comprehensive JavaScript/TypeScript SDK for building Calimero applications. Includes client libraries, type definitions, and development utilities. - -**Key Features:** -- TypeScript-first API client -- CRDT state management utilities -- Context and identity management -- WebSocket and RPC communication -- React hooks and utilities - -👉 [View mero-devtools-js on GitHub](https://github.com/calimero-network/mero-devtools-js) - ---- - -## Getting Started - -1. **Install merod** to run a Calimero node -2. **Use meroctl** to manage your node and deploy applications -3. **Try merobox** for local development and testing -4. **Build with mero-devtools-js** to create JavaScript/TypeScript applications - -For detailed setup instructions, refer to each tool's README in its respective repository. +!!! 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/mkdocs.yml b/mkdocs.yml index df86cca..3eba0ed 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ # Site Information -site_name: "" +site_name: "Calimero Docs" site_description: Lightweight documentation for the Calimero network and developer stack site_url: https://docs.calimero.network @@ -49,8 +49,10 @@ theme: - navigation.tabs # Top-level sections in tabs - navigation.tabs.sticky # Keep tabs visible when scrolling - navigation.sections # Show sections in sidebar + - navigation.expand # Expand active section in sidebar - navigation.indexes # Allow section index pages - navigation.top # Back to top button + - toc.follow # Keep right-hand TOC in view - search.suggest # Search suggestions - search.highlight # Highlight search terms - content.code.copy # Copy button for code blocks @@ -64,6 +66,9 @@ plugins: extra_css: - stylesheets/extra.css +extra_javascript: + - javascripts/sidebar.js + # Popular MkDocs Plugins to consider: # - mkdocs-material (already using as theme) # - mkdocs-mermaid2-plugin: For diagrams and flowcharts @@ -77,11 +82,51 @@ extra_css: # Navigation structure nav: - Home: index.md - - Introduction: intro/index.md - - App Directory: app-directory/index.md - - Builder Directory: builder-directory/index.md + - Build: + - Getting Started: + - Overview: getting-started/index.md + - Installation Checklist: getting-started/installation-checklist.md + - Launch Your First Context: getting-started/launch-your-first-context.md + - Build Your First Application: getting-started/build-your-first-application.md + - Sample App Walkthrough: getting-started/sample-app-walkthrough.md + - Builder Directory: builder-directory/index.md + - Examples: + - Overview: examples/index.md + - Battleships: examples/battleships.md + - Shared Todo Backlog: examples/shared-todo-backlog.md + - Split Bills: examples/split-bills.md + - Additional Templates: examples/additional-templates.md + - Learn: + - Core Concepts: + - Overview: core-concepts/index.md + - Contexts: core-concepts/contexts.md + - Identity: core-concepts/identity.md + - Applications: core-concepts/applications.md + - Nodes: core-concepts/nodes.md + - Architecture Overview: core-concepts/architecture.md + - Privacy, Verifiability & Security: privacy-verifiability-security/index.md + - Operate: + - Operator Track: + - Overview: operator-track/index.md + - Run a Local Network: operator-track/run-a-local-network.md + - Join Existing Contexts: operator-track/join-existing-contexts.md + - Monitor & Debug: operator-track/monitor-and-debug.md + - Production Deployment Notes: operator-track/production-deployment-notes.md + - Reference: + - Overview: reference/index.md + - Commitments & Consistency: reference/commitments-consistency.md + - Response Envelope: reference/response-envelope.md + - HTTP Methods: reference/http-methods.md + - WebSocket Streams: reference/websocket-streams.md + - Error Codes & Retries: reference/error-codes.md + - Versioning & Changelog: reference/versioning-changelog.md - Tools & APIs: tools-apis/index.md - - Privacy, Verifiability & Security: privacy-verifiability-security/index.md + - Support: + - Overview: support/index.md + - FAQ: support/faq.md + - Contact Channels: support/contact-channels.md + - Contribution Guide: support/contribution-guide.md + - Roadmap & Feedback: support/roadmap-feedback.md # Extra configuration extra: From b882f0280ee9faacd32de4ec66b7edb1a83c57f0 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 06:12:03 -0300 Subject: [PATCH 02/22] docs: comprehensive documentation improvements - Enhanced intro page with use cases and detailed repository structure - Filled contexts stub with lifecycle, isolation model, and operations - Filled identity stub with hierarchical keys, auth flows, and wallet integration - Filled core concepts and getting started index pages - Enhanced architecture page with detailed component deep dive - Added documentation gap analysis for tracking improvements --- DOCUMENTATION_GAP_ANALYSIS.md | 78 +++++++ docs/core-concepts/applications.md | 245 ++++++++++++++++++++- docs/core-concepts/architecture.md | 340 ++++++++++++++++++++++++++++- docs/core-concepts/contexts.md | 219 ++++++++++++++++++- docs/core-concepts/identity.md | 253 ++++++++++++++++++++- docs/core-concepts/index.md | 134 ++++++++++-- docs/core-concepts/nodes.md | 175 ++++++++++++++- docs/getting-started/index.md | 143 ++++++++++-- docs/intro/index.md | 160 ++++++++++++++ 9 files changed, 1691 insertions(+), 56 deletions(-) create mode 100644 DOCUMENTATION_GAP_ANALYSIS.md create mode 100644 docs/intro/index.md diff --git a/DOCUMENTATION_GAP_ANALYSIS.md b/DOCUMENTATION_GAP_ANALYSIS.md new file mode 100644 index 0000000..10215db --- /dev/null +++ b/DOCUMENTATION_GAP_ANALYSIS.md @@ -0,0 +1,78 @@ +# Documentation Gap Analysis + +## Summary Comparison + +### ✅ Already Well Covered +1. **Four-layer architecture** - Covered in `intro/index.md` and `core-concepts/architecture.md` +2. **Transaction flow** - Detailed sequence diagram in `architecture.md` +3. **Dual sync strategy** - Explained in `architecture.md` and `nodes.md` +4. **DAG causal ordering** - Visualized in `architecture.md` +5. **Node types** - Coordinator/peer explained in `nodes.md` +6. **Performance characteristics** - Listed in `intro/index.md` +7. **Component map** - Table in `architecture.md` +8. **Applications overview** - Comprehensive in `applications.md` +9. **CRDT collections** - Detailed in `applications.md` +10. **Where to start** - Table in `intro/index.md` + +### ❌ Missing or Incomplete + +#### Critical Gaps (Stub Pages) +1. **`core-concepts/contexts.md`** - Currently just a stub with TODOs +2. **`core-concepts/identity.md`** - Stub with TODOs +3. **`core-concepts/index.md`** - Placeholder content +4. **`getting-started/index.md`** - Placeholder content + +#### Missing Information +1. **Use Cases** - No mention of collaborative editing, decentralized social, P2P gaming, IoT, supply chain, healthcare +2. **Detailed Component Breakdown** - Runtime, SDK, storage, DAG explanations could be more detailed with "what it does" and "why it matters" +3. **Project Structure** - The detailed `core/` directory structure with explanations of what each crate does +4. **What Makes It Unique** - The bullet points exist but could be more prominent and detailed +5. **Core Principles** - Mentioned but not emphasized enough +6. **Key Components Deep Dive** - Each major crate needs a "what/why/how" explanation + +#### Structural Issues +1. **Intro page** - Good but could better emphasize unique value props +2. **Architecture page** - Component map is good but could add "responsibility" column +3. **No "Core Repository Overview"** - Missing a dedicated page explaining the core repo structure + +## Proposed Improvements + +### 1. Enhance `intro/index.md` +- Add prominent "Use Cases" section +- Expand "What Makes Calimero Unique" with more detail +- Add "Core Repository Structure" subsection +- Make "Core Principles" more prominent + +### 2. Fill `core-concepts/contexts.md` +- Explain context isolation model +- Describe lifecycle (create, invite, join, revoke) +- Add diagram showing shared state vs private storage +- Link to merobox workflows + +### 3. Fill `core-concepts/identity.md` +- Explain root vs client keys +- Describe wallet adapters +- Cover authentication flows per chain +- Link to contracts repo + +### 4. Enhance `core-concepts/architecture.md` +- Add "Key Components Deep Dive" section with detailed explanations +- Expand component map with "Responsibility" column +- Add "Project Structure" section explaining core/ directory + +### 5. Create `core-concepts/core-repository.md` (NEW) +- Detailed breakdown of core/ directory structure +- Explanation of each major crate (what/why/how) +- Component relationships diagram +- Links to individual crate READMEs + +### 6. Fill `core-concepts/index.md` +- Replace placeholder with actual overview +- Brief summaries of each concept +- Navigation guidance + +### 7. Fill `getting-started/index.md` +- Replace placeholder with actual content +- Clear progression path +- Links to each getting started page + diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index 4eda35e..9377101 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -1,7 +1,244 @@ # Applications -_Stub page — describe the Calimero application model._ +Calimero **applications** are WASM (WebAssembly) modules that run inside the Calimero node runtime. They use the Calimero SDK to manage CRDT-backed state, emit events, and interact with the network. -- TODO: Explain WASM runtime, deterministic execution, event system. -- TODO: Cover private storage (`#[app::private]`) and CRDT state. -- TODO: Link to SDK documentation for ABI generation and client bindings. +## 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: + +- Define **state** using CRDT collections +- Implement **logic** that mutates state +- Emit **events** for real-time updates +- Access **private storage** for node-local data + +## Quick Start + +```rust +use calimero_sdk::app; +use calimero_storage::collections::UnorderedMap; + +#[app::state] +#[derive(BorshSerialize, BorshDeserialize)] +pub struct MyApp { + items: UnorderedMap, +} + +#[app::logic] +impl MyApp { + #[app::init] + pub fn init() -> MyApp { + MyApp { + items: UnorderedMap::new(), + } + } + + pub fn add_item(&mut self, key: String, value: String) -> app::Result<()> { + self.items.insert(key, value)?; + Ok(()) + } + + pub fn get_item(&self, key: &str) -> app::Result> { + self.items.get(key).map_err(Into::into) + } +} +``` + +Build and deploy: + +```bash +# Build WASM +./build.sh + +# Install on node +meroctl --node-name node1 app install \ + --path build/app.wasm \ + --context-id +``` + +## Architecture + +### WASM Execution Flow + +```mermaid +sequenceDiagram + participant Client as JSON-RPC Client + participant Node as Node Runtime + participant WASM as WASM Module + participant Storage as CRDT Storage + participant Network as P2P Network + + Client->>Node: call("add_item", args) + Node->>WASM: execute(method, args) + + rect rgb(220, 237, 255) + Note over WASM,Storage: Transaction Execution + WASM->>Storage: map.insert(key, value) + Storage->>Storage: Generate Action::Update + Storage->>Storage: Calculate Merkle hashes + Storage->>Storage: Collect in DELTA_CONTEXT + end + + WASM-->>Node: ExecutionOutcome {
root_hash, events, ...} + + Node->>Network: Broadcast StateDelta + Network->>Node: Propagate to peers + Node-->>Client: TransactionResult +``` + +### Execution Model + +1. **Deterministic execution**: WASM code runs deterministically for consistent results across nodes +2. **Sandboxing**: Isolated execution environment with resource limits +3. **State mutation**: CRDT operations generate actions that are collected in DELTA_CONTEXT +4. **Event emission**: Applications can emit events for real-time updates + +## CRDT State Management + +Applications use CRDT collections for conflict-free state: + +### Available Collections + +| Collection | Use Case | Merge Strategy | +| --- | --- | --- | +| **Counter** | Metrics, counters | Sum | +| **LwwRegister<T>** | Single values | Latest timestamp | +| **UnorderedMap<K,V>** | Key-value storage | Recursive per-entry | +| **Vector<T>** | Ordered lists | Element-wise | +| **UnorderedSet<T>** | Unique values | Union | +| **Option<T>** | Optional CRDTs | Recursive if Some | + +### Nested Structures + +CRDTs can be nested arbitrarily: + +```rust +#[app::state] +pub struct TeamMetrics { + // Map of team member → Map of metric → Counter + member_metrics: UnorderedMap>, +} +``` + +## Event System + +Applications can emit events for real-time updates: + +```rust +#[app::state(emits = ItemAdded)] +pub struct MyApp { + items: UnorderedMap, +} + +#[derive(BorshSerialize, BorshDeserialize)] +pub struct ItemAdded { + key: String, + value: String, +} + +#[app::logic] +impl MyApp { + pub fn add_item(&mut self, key: String, value: String) -> app::Result<()> { + self.items.insert(key.clone(), value.clone())?; + app::emit(ItemAdded { key, value })?; + Ok(()) + } +} +``` + +**Event lifecycle**: +1. Emitted during method execution +2. Included in delta broadcast to all peers +3. Event handlers execute on peer nodes (not author node) +4. Handlers can update UI or trigger side effects + +## Private Storage + +For node-local data (secrets, caches, per-node counters): + +```rust +use calimero_sdk::private_storage; + +pub fn use_private_storage() { + let secrets = private_storage::entry::("my-secrets"); + secrets.write(|s| { + s.token = "rotated-token".to_string(); + }); +} +``` + +**Key properties**: +- Not replicated across nodes +- Stored via `storage_read` / `storage_write` directly +- Never included in CRDT deltas +- Accessible only on the executing node + +## Views vs Mutations + +Mark read-only methods with `#[app::view]`: + +```rust +#[app::logic] +impl MyApp { + // Mutation - persists state changes + pub fn add_item(&mut self, key: String, value: String) -> app::Result<()> { + self.items.insert(key, value)?; + Ok(()) + } + + // View - read-only, skips persistence + #[app::view] + pub fn get_item(&self, key: &str) -> app::Result> { + self.items.get(key).map_err(Into::into) + } +} +``` + +**Benefits**: +- Views don't generate storage deltas +- Faster execution (no persistence overhead) +- Clear intent in API + +## Resource Limits + +WASM execution is bounded: + +- **Memory**: Configurable limits (default: ~128MB) +- **Stack size**: Bounded to prevent stack overflow +- **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. + +## ABI Generation + +Applications export an ABI (Application Binary Interface) that clients use: + +1. **Build WASM**: Compile Rust 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 + +## 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)) + +## 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 + +## Related Topics + +- [Build Your First Application](getting-started/build-your-first-application.md) - Step-by-step guide +- [Contexts](contexts.md) - Application instances +- [Architecture Overview](architecture.md) - How applications fit into the system diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index 10e9d0d..afefe1c 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -1,7 +1,339 @@ # Architecture Overview -_Stub page — tie together contexts, nodes, applications, identity._ +Calimero's architecture consists of four main layers that work together to enable distributed, peer-to-peer applications with automatic conflict-free synchronization. -- TODO: Add end-to-end sequence diagram showing request flow. -- TODO: Include repository map referencing core components. -- TODO: Summarize how CRDT sync and proofs work across nodes. +## Four-Layer Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ 1. Application Layer │ +│ - WASM apps using Calimero SDK │ +│ - CRDT collections (UnorderedMap, Vector, Counter) │ +│ - Event emission for real-time updates │ +└────────────────────────┬────────────────────────────────┘ + │ +┌────────────────────────┴────────────────────────────────┐ +│ 2. Node Layer │ +│ - Orchestrates synchronization & execution │ +│ - Dual sync paths: Gossipsub + Periodic P2P │ +│ - Event handler execution │ +│ - Blob distribution │ +└────────────────────────┬────────────────────────────────┘ + │ +┌────────────────────────┴────────────────────────────────┐ +│ 3. Storage Layer │ +│ - CRDT storage with automatic merging │ +│ - DAG for causal ordering │ +│ - Out-of-order delivery handling │ +│ - Merkle trees for state comparison │ +└────────────────────────┬────────────────────────────────┘ + │ +┌────────────────────────┴────────────────────────────────┐ +│ 4. Network Layer │ +│ - libp2p (Gossipsub, Streams, DHT) │ +│ - JSON-RPC server │ +│ - WebSocket/SSE subscriptions │ +│ - Authentication & authorization │ +└─────────────────────────────────────────────────────────┘ +``` + +## Transaction Flow + +Here's how a transaction flows through the system: + +```mermaid +sequenceDiagram + participant Client as JSON-RPC Client + participant Node as Node Runtime + participant WASM as WASM Module + participant Storage as CRDT Storage + participant DAG as DAG Store + participant Network as P2P Network + participant Peer as Peer Node + + Client->>Node: call("add_item", args) + Node->>WASM: execute(method, args) + + rect rgb(220, 237, 255) + Note over WASM,Storage: Transaction Execution + WASM->>Storage: map.insert(key, value) + Storage->>Storage: Generate Action::Update + Storage->>Storage: Calculate Merkle hashes + Storage->>Storage: Collect in DELTA_CONTEXT + end + + WASM-->>Node: ExecutionOutcome {
root_hash, events, ...} + + rect rgb(255, 237, 220) + Note over Node,Network: Delta Propagation + Node->>DAG: Create CausalDelta {
parents: dag_heads,
payload: actions} + Node->>Network: Broadcast StateDelta via Gossipsub + end + + Network->>Peer: Propagate to all peers (~100-200ms) + Peer->>Peer: Check if parents ready + alt Parents ready + Peer->>Peer: Apply delta immediately + Peer->>Peer: Execute event handlers + else Parents missing + Peer->>Peer: Buffer as pending + Note over Peer: Wait for parents via P2P sync + end + + Node-->>Client: TransactionResult +``` + +## Synchronization Flow + +Calimero uses a dual-path synchronization strategy: + +### Path 1: Gossipsub Broadcast (Primary) +- **Speed**: ~100-200ms latency +- **Reliability**: Excellent in good network conditions +- **Purpose**: Fast, real-time propagation of changes +- **How it works**: Delta broadcast to all peers in the Gossipsub mesh + +### Path 2: Periodic P2P Sync (Fallback) +- **Speed**: Every 10-30 seconds +- **Reliability**: Ensures eventual consistency +- **Purpose**: Catch-up after network issues, downtime, or packet loss +- **How it works**: Direct P2P stream exchange of missing deltas + +```mermaid +flowchart TB + subgraph "Path 1: Gossipsub Broadcast (Primary)" + G1[Transaction executed
on Node A] + G2[Create CausalDelta
parents: dag_heads] + G3[Broadcast via Gossipsub] + G4[All peers receive
within ~100ms] + G5{Parents ready?} + G6A[Apply immediately] + G6B[Buffer as pending] + G7[Execute event handlers] + + G1 --> G2 --> G3 --> G4 --> G5 + G5 -->|Yes| G6A --> G7 + G5 -->|No| G6B + end + + subgraph "Path 2: Periodic Sync (Fallback)" + P1[SyncManager timer
every 10-30s] + P2[Select random peer] + P3[Open P2P stream] + P4[Exchange DAG heads] + P5{Heads differ?} + P6[Request missing deltas] + P7[Apply missing deltas] + P8[Catch up complete] + + P1 --> P2 --> P3 --> P4 --> P5 + P5 -->|Yes| P6 --> P7 --> P8 + P5 -->|No| P8 + end + + G6B -.->|Eventually| P6 + + style G1 fill:#4DABF7,stroke:#333,stroke-width:3px,color:#000 + style G6A fill:#51CF66,stroke:#333,stroke-width:3px,color:#000 + style G6B fill:#FFB84D,stroke:#333,stroke-width:3px,color:#000 + style P1 fill:#FF6B6B,stroke:#333,stroke-width:3px,color:#000 + style P8 fill:#51CF66,stroke:#333,stroke-width:3px,color:#000 +``` + +**Why both paths?** +- **Gossipsub**: Fast (~100-200ms), reliable in good network conditions +- **Periodic sync**: Ensures eventual consistency even with packet loss, partitions, or downtime + +## DAG-Based Causal Ordering + +The DAG (Directed Acyclic Graph) ensures that deltas are applied in the correct causal order, even when received out-of-order: + +```mermaid +graph TB + subgraph "Concurrent Updates (Fork)" + F0[Delta 0
ROOT] + F1A[Delta 1A
parents: D0
Node A] + F1B[Delta 1B
parents: D0
Node B] + F2[Delta 2
parents: D1A, D1B
MERGE] + + F0 --> F1A + F0 --> F1B + F1A --> F2 + F1B --> F2 + end + + style F0 fill:#4DABF7,stroke:#333,stroke-width:3px,color:#000 + style F1A fill:#FF6B6B,stroke:#333,stroke-width:3px,color:#000 + style F1B fill:#FF6B6B,stroke:#333,stroke-width:3px,color:#000 + style F2 fill:#51CF66,stroke:#333,stroke-width:3px,color:#000 +``` + +**Key properties**: +- Deltas can arrive in any order +- System buffers deltas until their parent dependencies are ready +- Once parents are available, deltas are applied automatically in causal order +- Concurrent updates create forks that merge automatically + +## Component Map + +| Component | Purpose | Responsibility | Location | +| --- | --- | --- | --- | +| **Application SDK** | Macro system (`#[app::state]`, `#[app::logic]`), CRDT collections, event emission | Provides developer API for building WASM applications | `crates/sdk` | +| **Runtime** | WASM execution engine (Wasmer), sandboxing, resource limits | Executes WASM modules safely with bounded resources | `crates/runtime` | +| **Storage** | CRDT collections with merge semantics | Manages conflict-free data types and automatic merging | `crates/storage` | +| **DAG** | Pure DAG for causal delta tracking, dependency resolution | Ensures deltas are applied in correct causal order | `crates/dag` | +| **Node** | NodeManager orchestrates sync, events, blob sharing | Coordinates all node operations (sync, events, blobs) | `crates/node` | +| **Network** | libp2p integration for P2P communication | Handles P2P networking (Gossipsub, streams, DHT) | `crates/network` | +| **Server** | JSON-RPC API, WebSocket/SSE subscriptions, admin endpoints | Exposes APIs for clients and admin operations | `crates/server` | +| **Auth** | Authentication and identity management | Handles wallet-based auth and JWT token issuance | `crates/auth` | +| **Store** | Persistent storage backend (RocksDB) | Provides durable storage for contexts and state | `crates/store` | +| **Context** | Context (application instance) lifecycle management | Manages context creation, membership, and operations | `crates/context` | +| **merod** | Node binary (coordinator or peer) | Main executable for running Calimero nodes | `crates/merod` | +| **meroctl** | CLI for node operations, app installation, calls | Command-line interface for node management | `crates/meroctl` | + +## Key Components Deep Dive + +### Application SDK (`crates/sdk`) + +**What it does:** +- Provides macros (`#[app::state]`, `#[app::logic]`, `#[app::init]`) for defining application structure +- Exposes CRDT collections (UnorderedMap, Vector, Counter, etc.) for state management +- Handles event emission and collection +- Manages private storage for node-local data + +**Why it matters:** +- Simplifies application development with declarative macros +- Ensures correct CRDT usage patterns +- Abstracts away low-level storage details + +**Key concepts:** +- State structs define persisted data +- Logic structs implement methods +- Views vs mutations (read-only vs state-changing) +- Event emission for real-time updates + +### Runtime (`crates/runtime`) + +**What it does:** +- Executes WASM modules using Wasmer +- Enforces resource limits (memory, stack, execution time) +- Provides host functions (storage, logging, crypto, HTTP) +- Handles deterministic execution + +**Why it matters:** +- Sandboxes untrusted code safely +- Prevents resource exhaustion +- Enables consistent execution across nodes + +**Key concepts:** +- VMLogic: Central execution context +- Host functions: Bridge between WASM and host +- Resource metering: Gas-like system for execution limits + +### Storage (`crates/storage`) + +**What it does:** +- Implements CRDT collections (UnorderedMap, Vector, Counter, LwwRegister, etc.) +- Handles automatic merging of concurrent updates +- Manages Merkle trees for efficient state comparison +- Provides snapshot and delta generation + +**Why it matters:** +- Enables conflict-free synchronization +- Handles concurrent updates automatically +- Efficient state comparison for sync + +**Key concepts:** +- CRDT semantics: Each collection type has specific merge behavior +- Nested structures: CRDTs can be nested arbitrarily +- Action generation: State changes generate actions for delta propagation + +### DAG (`crates/dag`) + +**What it does:** +- Tracks causal relationships between deltas +- Buffers deltas until parent dependencies are ready +- Applies deltas in correct causal order +- Detects and handles forks + +**Why it matters:** +- Handles out-of-order network delivery +- Ensures consistent state across nodes +- Enables concurrent updates without conflicts + +**Key concepts:** +- CausalDelta: Delta with parent references +- DagStore: Manages delta graph +- Pending deltas: Buffered until parents arrive +- DAG heads: Current tips of the graph + +### Node (`crates/node`) + +**What it does:** +- Orchestrates all node operations (NodeManager) +- Manages delta propagation (Gossipsub + P2P sync) +- Executes event handlers on peer nodes +- Distributes blobs via content-addressed storage + +**Why it matters:** +- Central coordination point for all node activities +- Ensures reliable synchronization +- Enables real-time event handling + +**Key concepts:** +- NodeManager: Main orchestrator (Actix Actor) +- DeltaStore: Wraps DAG with WASM execution +- SyncManager: Coordinates periodic sync +- BlobManager: Manages blob cache and distribution + +### Network (`crates/network`) + +**What it does:** +- Integrates libp2p for P2P communication +- Manages Gossipsub mesh for broadcast +- Handles P2P streams for direct communication +- Provides DHT for peer discovery + +**Why it matters:** +- Enables decentralized communication +- Fast broadcast for real-time updates +- Reliable streams for catch-up sync + +**Key concepts:** +- Gossipsub: Pub/sub for delta broadcast +- P2P streams: Direct peer-to-peer communication +- DHT: Distributed hash table for peer discovery +- Noise encryption: Secure communication + +### Server (`crates/server`) + +**What it does:** +- Exposes JSON-RPC API for client interaction +- Provides WebSocket and SSE for real-time subscriptions +- Handles admin API endpoints +- Manages authentication and authorization + +**Why it matters:** +- Enables client applications to interact with nodes +- Provides real-time updates via subscriptions +- Allows administrative operations + +**Key concepts:** +- JSON-RPC: Standard RPC protocol +- WebSocket/SSE: Real-time event streaming +- Admin API: Node management operations +- Authentication: JWT-based access control + +## 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 + +--- + +**Next**: Learn about specific concepts: [Contexts](contexts.md) | [Identity](identity.md) | [Applications](applications.md) | [Nodes](nodes.md) diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index 2acb657..e5c5035 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -1,7 +1,218 @@ # Contexts -_Stub page — explain context isolation and lifecycle._ +A **context** is an isolated instance of an application running on the Calimero network. Each context has its own state, members, and access controls. Think of it as a "workspace" or "room" where a specific application instance operates. -- TODO: Add diagram showing shared state vs private storage. -- TODO: Describe invitation flow, membership, and revocation. -- TODO: Link to `core` and `merobox` READMEs when anchors are ready. +## What Are Contexts? + +Contexts provide: + +- **State Isolation**: Each context maintains its own CRDT-backed state, completely separate from other contexts +- **Member Management**: Invite-only access control with cryptographic identities +- **Multi-Chain Support**: Each context can be associated with a blockchain protocol (NEAR, Ethereum, ICP, etc.) +- **Lifecycle Management**: Create, invite members, join, and manage contexts independently + +## Context Lifecycle + +### 1. Creation + +A context is created when an application is installed and initialized: + +```bash +# Install application +meroctl app install --path app.wasm --context-id + +# Create context (happens automatically on first install) +# Or create explicitly: +meroctl context create --application-id --protocol near +``` + +**What happens:** +- Application WASM is installed on the node +- Initial context state is created (via `#[app::init]` method) +- Context creator becomes the first member +- Context ID is generated (unique identifier) + +### 2. Invitation Flow + +Context creators can invite other identities to join: + +```bash +# Generate identity for invitee +meroctl identity create --node-name node2 + +# Create invitation +meroctl context invite \ + --context-id \ + --grantee-id +``` + +**Invitation contains:** +- Context ID +- Grantee public key +- Permissions (read/write/execute) +- Expiration (optional) + +### 3. Joining a Context + +Invited members can join using the invitation: + +```bash +# Join context using invitation +meroctl context join \ + --context-id \ + --invitation +``` + +**What happens:** +- Invitation is validated +- Member is added to context membership +- Member receives current state snapshot +- Member can now call methods and receive updates + +### 4. Membership & Permissions + +Context members have different permission levels: + +- **Creator**: Full control, can invite/revoke members +- **Member**: Can call methods, read state, receive events +- **Read-only**: Can query state but cannot mutate + +## State Isolation Model + +Each context maintains completely isolated state: + +``` +┌─────────────────────────────────────────────────┐ +│ Context A │ +│ ┌──────────────────────────────────────────┐ │ +│ │ Shared CRDT State │ │ +│ │ - UnorderedMap │ │ +│ │ - Vector │ │ +│ │ - Counter │ │ +│ └──────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ Private Storage (per-node) │ │ +│ │ - Node-local secrets │ │ +│ │ - Cached data │ │ +│ └──────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────┐ +│ Context B (completely separate) │ +│ ┌──────────────────────────────────────────┐ │ +│ │ Shared CRDT State │ │ +│ │ - Different data, different members │ │ +│ └──────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────┘ +``` + +**Key points:** +- **Shared CRDT State**: Replicated across all member nodes, automatically synchronized +- **Private Storage**: Node-local data that never leaves the executing node +- **Complete Isolation**: Context A cannot access Context B's state + +## Multi-Chain Integration + +Contexts can be associated with blockchain protocols: + +| Protocol | Use Case | Identity Source | +| --- | --- | --- | +| **NEAR** | NEAR-based applications | NEAR account IDs | +| **Ethereum** | Ethereum dApps | Ethereum addresses | +| **ICP** | Internet Computer apps | ICP principals | +| **Stellar** | Stellar-based apps | Stellar accounts | + +Each protocol provides: +- **Identity verification**: Cryptographic proof of ownership +- **Cross-chain attestations**: Verifiable claims about on-chain state +- **Relayer integration**: Bridge between Calimero and blockchain + +## Context Operations + +### Querying State + +```bash +# Call a view method (read-only) +meroctl call \ + --context-id \ + --method get_item \ + --args '{"key": "hello"}' +``` + +### Mutating State + +```bash +# Call a mutation method +meroctl call \ + --context-id \ + --method add_item \ + --args '{"key": "hello", "value": "world"}' \ + --executor-public-key +``` + +### Subscribing to Events + +```bash +# Subscribe via WebSocket +wscat -c ws://localhost:2528/ws + +# Subscribe to context events +{ + "jsonrpc": "2.0", + "id": 1, + "method": "subscribe", + "params": { + "context_id": "", + "event_type": "ItemAdded" + } +} +``` + +## Context Management + +### Listing Contexts + +```bash +# List all contexts on a node +meroctl context list + +# Get context details +meroctl context get --context-id +``` + +### Revoking Access + +```bash +# Revoke a member's access +meroctl context revoke \ + --context-id \ + --member-id +``` + +**What happens:** +- Member is removed from context +- Member can no longer call methods +- Member stops receiving updates +- State remains intact (no data deletion) + +## Best Practices + +1. **One Context Per Use Case**: Create separate contexts for different purposes (e.g., one per team, one per project) +2. **Minimize Members**: Only invite necessary members to reduce sync overhead +3. **Use Private Storage**: Store secrets and node-local data in private storage, not CRDT state +4. **Context Naming**: Use descriptive context IDs or metadata for easier management + +## Deep Dives + +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 +- **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 + +## Related Topics + +- [Applications](applications.md) - What runs inside contexts +- [Identity](identity.md) - Who can access contexts +- [Nodes](nodes.md) - Where contexts run +- [Architecture Overview](architecture.md) - How contexts fit into the system diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index 7a4437d..18774f2 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -1,7 +1,252 @@ # Identity -_Stub page — cover root vs client keys and wallet adapters._ +Calimero uses **cryptographic identities** to manage access control and authentication across the network. Each participant has one or more identities that prove ownership and grant permissions. -- TODO: Explain hierarchical key management and revocation. -- TODO: Summarize NEAR/Ethereum/Starknet/ICP authentication flows. -- TODO: Reference `contracts` README for identity module details. +## Identity Model + +Calimero supports a hierarchical identity model: + +``` +Root Key (Master Identity) +├── Client Key 1 (for Context A) +├── Client Key 2 (for Context B) +└── Client Key 3 (for Context C) +``` + +### Root Keys + +A **root key** is the master identity for a user or node. It's typically: + +- Generated from a blockchain wallet (NEAR, Ethereum, etc.) +- Used for high-level operations (creating contexts, managing memberships) +- Stored securely (hardware wallet, keychain, etc.) + +### Client Keys + +**Client keys** are derived from root keys and used for: + +- Executing methods in specific contexts +- Signing transactions and deltas +- Proving membership in contexts + +**Benefits:** +- **Isolation**: Compromise of one client key doesn't affect others +- **Revocation**: Can revoke access per-context without changing root key +- **Privacy**: Different keys for different contexts + +## Identity Generation + +### Creating a New Identity + +```bash +# Generate a new identity on a node +meroctl identity create --node-name node1 + +# Output: +# Public Key: ed25519:abc123... +# Stored in: ~/.calimero/identities/node1/ +``` + +**What happens:** +- Ed25519 keypair is generated +- Private key is stored securely on the node +- Public key is returned for sharing + +### Using Blockchain Wallets + +Calimero integrates with blockchain wallets for identity: + +| Protocol | Wallet Integration | Identity Source | +| --- | --- | --- | +| **NEAR** | NEAR Wallet, Ledger | NEAR account ID + signature | +| **Ethereum** | MetaMask, WalletConnect | Ethereum address + signature | +| **ICP** | Internet Identity, Plug | ICP principal + signature | +| **Stellar** | Stellar Wallet | Stellar account + signature | + +**Authentication Flow:** +1. User connects wallet (e.g., MetaMask) +2. User signs a challenge message +3. Calimero verifies signature against blockchain +4. Identity is established and JWT token issued + +## Authentication Flows + +### NEAR Protocol + +```typescript +// Client-side authentication +import { connect, keyStores } from 'near-api-js'; + +const keyStore = new keyStores.BrowserLocalStorageKeyStore(); +const near = await connect({ + networkId: 'testnet', + keyStore, +}); + +// Sign challenge +const account = await near.account('user.near'); +const signature = await account.connection.signer.signMessage( + challenge, + account.accountId, + 'testnet' +); + +// Send to Calimero auth service +const jwt = await fetch('/auth/near', { + method: 'POST', + body: JSON.stringify({ accountId, signature, challenge }), +}); +``` + +### Ethereum + +```typescript +// Using ethers.js +import { ethers } from 'ethers'; + +const provider = new ethers.BrowserProvider(window.ethereum); +const signer = await provider.getSigner(); +const address = await signer.getAddress(); + +// Sign challenge +const signature = await signer.signMessage(challenge); + +// Send to Calimero auth service +const jwt = await fetch('/auth/ethereum', { + method: 'POST', + body: JSON.stringify({ address, signature, challenge }), +}); +``` + +### ICP (Internet Computer) + +```typescript +// Using @dfinity/agent +import { Actor, HttpAgent } from '@dfinity/agent'; + +const agent = new HttpAgent({ identity }); +const principal = await agent.getPrincipal(); + +// Sign challenge using Internet Identity +const signature = await agent.sign(challenge); + +// Send to Calimero auth service +const jwt = await fetch('/auth/icp', { + method: 'POST', + body: JSON.stringify({ principal, signature, challenge }), +}); +``` + +## JWT Tokens + +After authentication, Calimero issues **JWT (JSON Web Token)** tokens: + +```json +{ + "context_id": "context-123", + "executor_public_key": "ed25519:abc...", + "permissions": ["read", "write", "execute"], + "exp": 1234567890 +} +``` + +**Token usage:** +- Included in API requests: `Authorization: Bearer ` +- Proves identity and permissions +- Expires after configured time +- Refreshable via refresh token + +## Key Management + +### Hierarchical Key Management + +``` +Root Key (NEAR account: alice.near) +│ +├── Context A Client Key +│ ├── Can execute methods in Context A +│ └── Can read/write Context A state +│ +├── Context B Client Key +│ ├── Can execute methods in Context B +│ └── Can read/write Context B state +│ +└── Context C Client Key (revoked) + └── No longer has access +``` + +**Benefits:** +- **Granular Control**: Different keys for different contexts +- **Easy Revocation**: Revoke one key without affecting others +- **Audit Trail**: Track which key performed which action + +### Key Revocation + +```bash +# Revoke a client key's access to a context +meroctl context revoke \ + --context-id \ + --member-id +``` + +**What happens:** +- Key is removed from context membership +- Key can no longer sign transactions for that context +- Existing transactions remain valid (immutable history) +- Root key remains unaffected + +## Wallet Adapters + +Calimero provides wallet adapters for easy integration: + +### JavaScript Client + +```typescript +import { ClientLogin } from '@calimero-network/calimero-client'; + +// Automatically handles wallet connection and authentication + navigate('/dashboard')} +/> +``` + +**Supported wallets:** +- NEAR Wallet +- MetaMask (Ethereum) +- WalletConnect +- Internet Identity (ICP) + +### Python Client + +```python +from calimero_client_py import create_connection, AuthMode + +# Connect with wallet authentication +connection = create_connection( + base_url="https://node.calimero.network", + auth_mode=AuthMode.WALLET, + wallet_type="near" # or "ethereum", "icp" +) +``` + +## Best Practices + +1. **Use Client Keys**: Don't use root keys directly for context operations +2. **Rotate Keys**: Periodically rotate client keys for security +3. **Secure Storage**: Store private keys in secure keychains, never in code +4. **Multi-Sig Support**: Use multi-signature wallets for high-value contexts +5. **Key Backup**: Backup root keys securely (hardware wallet, paper backup) + +## Deep Dives + +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 +- **Client SDKs**: [Tools & APIs](../tools-apis/index.md) - Wallet integration guides + +## Related Topics + +- [Contexts](contexts.md) - Where identities are used +- [Applications](applications.md) - What identities can access +- [Architecture Overview](architecture.md) - How identity fits into the system diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md index f537396..23bd13e 100644 --- a/docs/core-concepts/index.md +++ b/docs/core-concepts/index.md @@ -1,39 +1,137 @@ # Core Concepts -> Placeholder overview — flesh out once concept briefs are ready. +Understanding Calimero's core concepts is essential for building and operating applications. This section covers the fundamental building blocks of the platform. -- [Contexts](contexts.md) -- [Identity](identity.md) -- [Applications](applications.md) -- [Nodes](nodes.md) -- [Architecture Overview](architecture.md) +## Overview + +Calimero consists of several interconnected concepts: + +- **[Contexts](contexts.md)** - Isolated application instances with their own state and members +- **[Identity](identity.md)** - Cryptographic identities for access control and authentication +- **[Applications](applications.md)** - WASM modules that run inside contexts +- **[Nodes](nodes.md)** - Runtime that orchestrates synchronization and execution +- **[Architecture Overview](architecture.md)** - How all components work together ## Contexts -- Describe isolation model, lifecycle, invitations. -- Plan to embed simplified diagram. -- Link to `core` and `merobox` READMEs once anchors exist. +**Contexts** are isolated instances of applications running on the Calimero network. Each context has: + +- **Isolated State**: Own CRDT-backed state, completely separate from other contexts +- **Member Management**: Invite-only access control with cryptographic identities +- **Lifecycle**: Create, invite, join, and manage independently + +**Key concepts:** +- State isolation model (shared CRDT state vs private storage) +- Invitation and membership flow +- Multi-chain integration (NEAR, Ethereum, ICP, etc.) + +[Learn more →](contexts.md) ## Identity -- Outline root vs client keys and wallet adapters. -- Mention authentication challenges. +**Identity** in Calimero uses cryptographic keys for access control: + +- **Root Keys**: Master identities (typically from blockchain wallets) +- **Client Keys**: Derived keys for specific contexts +- **Authentication**: Wallet-based authentication (NEAR, Ethereum, ICP, etc.) + +**Key concepts:** +- Hierarchical key management +- Wallet adapters and integration +- JWT tokens for API authentication + +[Learn more →](identity.md) ## Applications -- Summarize WASM runtime, state management, private storage. -- Call out event-driven patterns and ABI generation. +**Applications** are WASM modules that run inside contexts: + +- **WASM Runtime**: Sandboxed execution environment +- **CRDT State**: Conflict-free data types for automatic synchronization +- **Event System**: Real-time event emission and handling +- **Private Storage**: Node-local data that never leaves the node + +**Key concepts:** +- SDK macros (`#[app::state]`, `#[app::logic]`) +- CRDT collections (UnorderedMap, Vector, Counter, etc.) +- Views vs mutations +- ABI generation for client bindings + +[Learn more →](applications.md) ## Nodes -- High-level view of `merod`, networking stack, storage layer. -- Reference admin surfaces (dashboard, node console). +**Nodes** (`merod`) orchestrate synchronization and execution: + +- **Node Types**: Coordinator (first node) or Peer (joins network) +- **Synchronization**: Dual-path sync (Gossipsub + periodic P2P) +- **Event Handling**: Automatic event handler execution +- **Blob Distribution**: Content-addressed file sharing + +**Key concepts:** +- NodeManager architecture +- Delta propagation and application +- Admin surfaces (JSON-RPC, WebSocket, SSE) + +[Learn more →](nodes.md) ## Architecture Overview -- Provide end-to-end sequence diagram. -- Include repo map callouts for deeper dives. +The **Architecture Overview** explains how all components work together: + +- **Four-Layer Architecture**: Application, Node, Storage, Network layers +- **Transaction Flow**: How requests flow through the system +- **Synchronization Flow**: Dual-path sync strategy +- **DAG-Based Ordering**: Causal ordering for out-of-order delivery +- **Component Map**: Detailed breakdown of each crate + +[Learn more →](architecture.md) + +## How Concepts Relate + +``` +┌─────────────────────────────────────────────────┐ +│ Node (merod) │ +│ ┌──────────────────────────────────────────┐ │ +│ │ Context A │ │ +│ │ ┌────────────────────────────────────┐ │ │ +│ │ │ Application (WASM) │ │ │ +│ │ │ - CRDT State │ │ │ +│ │ │ - Events │ │ │ +│ │ └────────────────────────────────────┘ │ │ +│ │ ┌────────────────────────────────────┐ │ │ +│ │ │ Members (Identities) │ │ │ +│ │ │ - Root Key: alice.near │ │ │ +│ │ │ - Client Key: ed25519:abc... │ │ │ +│ │ └────────────────────────────────────┘ │ │ +│ └──────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ Context B (separate instance) │ │ +│ └──────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────┘ +``` + +## Learning Path + +**New to Calimero?** Start here: + +1. **[Architecture Overview](architecture.md)** - Understand the big picture +2. **[Applications](applications.md)** - Learn how to build apps +3. **[Contexts](contexts.md)** - Understand application instances +4. **[Identity](identity.md)** - Learn about access control +5. **[Nodes](nodes.md)** - Understand the runtime + +**Ready to build?** Check out: + +- [Getting Started](../getting-started/index.md) - Step-by-step guides +- [Builder Directory](../builder-directory/index.md) - Development resources +- [Examples](../examples/index.md) - Working applications + +**Need to operate?** See: + +- [Operator Track](../operator-track/index.md) - Running and managing nodes +- [Reference](../reference/index.md) - API documentation --- -_This is a structural stub. Populate each section with concise prose, diagrams, and README links later._ +**Next**: Start with [Architecture Overview](architecture.md) to understand how everything fits together. diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md index 6fc6582..e1aacec 100644 --- a/docs/core-concepts/nodes.md +++ b/docs/core-concepts/nodes.md @@ -1,7 +1,174 @@ # Nodes -_Stub page — outline the role of `merod` nodes._ +A **node** (`merod`) is the core runtime that orchestrates synchronization, event handling, and blob distribution across a distributed network of peers. It wraps the DAG with WASM execution, networking, and lifecycle management. -- TODO: Detail networking stack (libp2p), storage, sync. -- TODO: Explain admin surfaces (JSON-RPC, WebSocket, Admin API). -- TODO: Reference `core` README sections for runtime architecture. +## What Nodes Do + +**Core Responsibilities**: +1. **Delta Management**: Apply deltas to WASM state in correct causal order +2. **Network Coordination**: Gossipsub broadcasts + P2P sync streams +3. **Event Execution**: Trigger event handlers on receiving nodes +4. **Blob Distribution**: Content-addressed file sharing +5. **Resource Management**: Memory limits, cleanup, garbage collection + +## Node Types + +### Coordinator Node +- First node in a network +- Handles initial context creation and bootstrap +- Can serve as entry point for new peers + +```bash +merod --node-type coordinator +``` + +### Peer Node +- Joins existing network +- Connects to coordinator or other peers +- Participates in P2P mesh + +```bash +merod --node-type peer --swarm-addrs /ip4/127.0.0.1/tcp/2428 +``` + +## Node Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ NodeManager (Actix Actor) │ +│ - Orchestrates all components │ +│ - Periodic timers (cleanup, heartbeat) │ +└────────────────┬────────────────────────────────────┘ + │ + ┌───────────┴───────────┬─────────────┐ + │ │ │ +┌────▼────────┐ ┌────────▼──────┐ ┌──▼───────────┐ +│NodeClients │ │NodeManagers │ │NodeState │ +│ - Context │ │ - BlobManager │ │ - BlobCache │ +│ - Node │ │ - SyncManager │ │ - DeltaStores│ +└─────────────┘ └───────────────┘ └──────────────┘ +``` + +### NodeManager +Main orchestrator that manages: +- **Periodic timers**: + - Blob eviction (every 5 min) + - Delta cleanup (every 60 sec) + - Hash heartbeat (every 30 sec) +- **Context subscriptions**: Subscribe to all contexts on startup +- **Lifecycle management**: Start/stop, graceful shutdown + +### NodeClients +External service clients: +- **ContextClient**: Execute WASM methods, query DAG heads, get root hash +- **NodeClient**: Subscribe/unsubscribe to contexts, broadcast deltas, open P2P streams + +### NodeManagers +Service managers: +- **BlobManager**: Store blobs (content-addressed), retrieve by ID, garbage collection +- **SyncManager**: Trigger periodic sync, track last sync time per context, coordinate P2P streams + +### NodeState +Runtime state (mutable caches): +- **blob_cache**: LRU cache for frequently accessed blobs +- **delta_stores**: Per-context DAG stores + +## Synchronization + +Nodes use a **dual-path synchronization strategy**: + +### Path 1: Gossipsub Broadcast (Primary) +- **Latency**: ~100-200ms +- **Reliability**: Excellent in good network conditions +- **Purpose**: Fast, real-time propagation + +All peers receive deltas via Gossipsub mesh within ~100-200ms. + +### Path 2: Periodic P2P Sync (Fallback) +- **Frequency**: Every 10-30 seconds +- **Reliability**: Ensures eventual consistency +- **Purpose**: Catch-up after network issues or downtime + +Direct P2P stream exchange of missing deltas ensures no data loss. + +For detailed sync flow, see [Architecture Overview](architecture.md#synchronization-flow). + +## Event Handling + +When a delta is applied: + +1. **Author node**: Skips event handler (assumes local UI already updated) +2. **Peer nodes**: Execute event handlers automatically after delta application +3. **Event propagation**: Events are included in delta broadcast to all peers + +This ensures: +- Real-time updates across all nodes +- No duplicate event handling on author node +- Consistent event ordering via DAG causal ordering + +## Blob Distribution + +Nodes manage content-addressed blob storage: + +- **Storage**: Blobs stored by content hash (blob ID) +- **Caching**: LRU cache for frequently accessed blobs (evicts after 5 min, or when cache exceeds 100 blobs / 500 MB) +- **Distribution**: Peers request blobs from each other via P2P streams +- **Garbage collection**: Unused blobs evicted periodically + +## Admin Surfaces + +Nodes expose several interfaces: + +### JSON-RPC Server +- **Port**: 2528 (default) +- **Purpose**: Client interaction, method calls, queries +- **Endpoints**: `/jsonrpc` (RPC calls), `/jsonrpc/stream` (subscriptions) + +### WebSocket +- **Purpose**: Real-time subscriptions (deltas, events, state changes) +- **Endpoint**: `/ws` +- **Protocol**: JSON-RPC over WebSocket + +### Server-Sent Events (SSE) +- **Purpose**: Alternative to WebSocket for event streaming +- **Endpoint**: `/sse` +- **Use case**: Browser-friendly real-time updates + +### Admin API +- **Port**: 2528 (default) +- **Endpoint**: `/admin-api/` +- **Purpose**: Node administration, context management, identity operations +- **Authentication**: JWT tokens + +## Monitoring & Debugging + +Key metrics and logs: + +- **DAG stats**: Pending deltas, applied deltas, DAG heads per context +- **Network stats**: Peer count, Gossipsub mesh health, P2P stream activity +- **Performance**: Delta application latency, sync duration, memory usage +- **Events**: Event handler execution, errors, warnings + +See [Monitor & Debug](operator-track/monitor-and-debug.md) for detailed guidance. + +## Configuration + +Nodes can be configured via: +- **Command-line flags**: `--node-type`, `--swarm-addrs`, `--config` +- **Configuration file**: TOML file with network, storage, runtime settings +- **Environment variables**: Override specific settings + +## Deep Dives + +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 + +## Related Topics + +- [Run a Local Network](operator-track/run-a-local-network.md) - Getting started with nodes +- [Architecture Overview](architecture.md) - How nodes fit into the system +- [Contexts](contexts.md) - Application instances managed by nodes diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 538a804..1e2dcf1 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -1,32 +1,139 @@ # Getting Started -> Placeholder content — to be filled with detailed guidance. +Welcome to Calimero! This guide will help you get up and running quickly, whether you're building applications, running nodes, or just exploring the platform. -- [Installation Checklist](installation-checklist.md) -- [Launch Your First Context](launch-your-first-context.md) -- [Build Your First Application](build-your-first-application.md) -- [Sample App Walkthrough](sample-app-walkthrough.md) +## Quick Start Paths -## Installation Checklist +Choose your path based on what you want to do: -- Outline required tooling (Docker, `merod`, `meroctl`, `merobox`). -- Provide quick commands for macOS/Linux/Windows. +| Goal | Path | Time | +| --- | --- | --- | +| **Run a local network** | [Installation Checklist](installation-checklist.md) → [Launch Your First Context](launch-your-first-context.md) | 10 min | +| **Build an application** | [Installation Checklist](installation-checklist.md) → [Build Your First Application](build-your-first-application.md) | 30 min | +| **Explore examples** | [Sample App Walkthrough](sample-app-walkthrough.md) | 15 min | -## Launch Your First Context +## Step 1: Installation Checklist -- Step-by-step summary of running a Merobox workflow. -- Note to embed diagram linking to `calimero-network/merobox` README. +Before you begin, ensure you have the required tools installed: -## Build Your First Application +**Required:** +- Docker (for running nodes) +- Node.js 18+ (for client SDKs) +- Rust toolchain (for building applications) -- Flow chart for template scaffold → logic build → ABI generation. -- Link to `mero-devtools-js` quickstart when published. +**Optional but recommended:** +- `merobox` (Python CLI for local development) +- `merod` and `meroctl` (if building from source) -## Sample App Walkthrough +[View full checklist →](installation-checklist.md) -- Highlight Battleships as the reference path. -- Call out where to embed screenshots/diagram. +## Step 2: Launch Your First Context + +Once you have the tools installed, launch a local network and create your first context: + +**Using Merobox (recommended):** +```bash +# Install merobox +pipx install merobox + +# Start local network +merobox run --count 2 + +# Create context (via workflow or CLI) +meroctl context create --application-id +``` + +**Using Docker directly:** +```bash +# Start coordinator node +docker run calimero/merod --node-type coordinator + +# Start peer node +docker run calimero/merod --node-type peer --swarm-addrs /ip4/127.0.0.1/tcp/2428 +``` + +[Detailed guide →](launch-your-first-context.md) + +## Step 3: Build Your First Application + +Now that you have a network running, build a simple application: + +**Quick start:** +```bash +# Clone example +git clone https://github.com/calimero-network/core +cd core/apps/kv-store + +# Build WASM +./build.sh + +# Install on node +meroctl app install --path build/kv_store.wasm --context-id +``` + +**From scratch:** +1. Create new Rust project +2. Add Calimero SDK dependencies +3. Define state with `#[app::state]` +4. Implement logic with `#[app::logic]` +5. Build to WASM +6. Install on node + +[Detailed guide →](build-your-first-application.md) + +## Step 4: Explore Examples + +Learn from working examples: + +- **kv-store**: Simple key-value store - great for understanding basics +- **battleships**: Multiplayer game - demonstrates real-time sync +- **blobs**: File sharing - shows blob distribution + +[Walkthrough →](sample-app-walkthrough.md) + +## What's Next? + +After completing the getting started guide: + +### For Builders + +- **[Core Concepts](../core-concepts/index.md)** - Deep dive into architecture +- **[Builder Directory](../builder-directory/index.md)** - Development resources +- **[Examples](../examples/index.md)** - More example applications +- **[Tools & APIs](../tools-apis/index.md)** - SDKs and tooling + +### For Operators + +- **[Operator Track](../operator-track/index.md)** - Running and managing nodes +- **[Reference](../reference/index.md)** - API documentation +- **[Monitor & Debug](../operator-track/monitor-and-debug.md)** - Observability + +### For Everyone + +- **[Architecture Overview](../core-concepts/architecture.md)** - How it all works +- **[Privacy & Security](../privacy-verifiability-security/index.md)** - Security model +- **[Support](../support/index.md)** - Get help and contribute + +## Common Questions + +**Q: Do I need to run my own node?** +A: For local development, yes. For production, you can use hosted nodes or run your own. + +**Q: Which language should I use?** +A: Applications are written in Rust (compiled to WASM). 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). + +**Q: Can I use this offline?** +A: Yes! Calimero is offline-first. Apps work offline and sync when online. + +## Getting Help + +- **Discord**: [Join our community](https://discord.gg/wZRC73DVpU) +- **GitHub Issues**: [Report bugs or ask questions](https://github.com/calimero-network/core/issues) +- **Documentation**: Browse the docs for detailed guides --- -_This page is a scaffold; fill each section with concise text and links when assets are ready._ +**Ready to start?** Begin with the [Installation Checklist](installation-checklist.md)! diff --git a/docs/intro/index.md b/docs/intro/index.md new file mode 100644 index 0000000..6f67749 --- /dev/null +++ b/docs/intro/index.md @@ -0,0 +1,160 @@ +# Introduction to Calimero + +## 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 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. + +## Core Value Proposition + +| Feature | What it means | +| --- | --- | +| **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 | + +## Key Design Principles + +1. **Data Ownership** - Your data on your devices, you control access +2. **Privacy by Default** - End-to-end encryption +3. **Distributed by Design** - P2P architecture, no single point of failure +4. **Developer-Friendly** - Simple API with powerful CRDT primitives + +## What Makes Calimero Unique? + +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. + +## Use Cases + +Calimero enables a wide range of decentralized applications: + +| Use Case | Why Calimero? | +| --- | --- | +| **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. | +| **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. | + +See [Example Applications](../examples/index.md) for working implementations. + +## Performance Characteristics + +- **Latency**: 100-200ms delta propagation (Gossipsub) +- **Throughput**: 100-1000 deltas/sec per context +- **Memory**: ~10MB per context (1000 deltas) +- **Scalability**: Horizontal (more contexts = more throughput) + +## Where to Start + +| If you are… | Start here | +| --- | --- | +| **Building apps** | [Build Your First Application](getting-started/build-your-first-application.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) | + +## Core Architecture Layers + +Calimero's architecture consists of four main layers: + +### 1. Application Layer +- WASM apps using the Calimero SDK +- 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) + +### 2. Node Layer +- Orchestrates synchronization and execution +- Dual sync paths: Gossipsub (~100-200ms) + Periodic P2P (every 10-30s) +- 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) + +### 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 + +**Documentation**: [Architecture Overview](core-concepts/architecture.md) → [`core/crates/storage/README.md`](https://github.com/calimero-network/core/blob/master/crates/storage/README.md) + +### 4. Network Layer +- libp2p-based P2P (Gossipsub, reliable streams, DHT discovery) +- JSON-RPC server for client interaction +- WebSocket/SSE 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) + +## How It Works (Transaction Flow) + +1. **Client calls WASM method** via JSON-RPC +2. **WASM executes**, generates CRDT actions (inserts, increments, etc.) +3. **Actions committed** as DAG delta with causal parents +4. **Delta broadcast** via Gossipsub to all peers (~100-200ms) +5. **Peers receive delta**, check if parents are ready +6. **If ready**: apply immediately and execute event handlers +7. **If not ready**: buffer until parents arrive (DAG handles this automatically) +8. **Periodic P2P sync** ensures eventual consistency + +For detailed flow diagrams, see [Architecture Overview](core-concepts/architecture.md). + +## Core Repository Structure + +The Calimero Core repository (`calimero-network/core`) contains the runtime and all supporting infrastructure: + +``` +core/ +├── crates/ # Core Rust libraries (30+ crates) +│ ├── sdk/ # Application SDK - macros, CRDT collections, event emission +│ ├── runtime/ # WASM execution engine (Wasmer), sandboxing, resource limits +│ ├── storage/ # CRDT storage layer - collections with merge semantics +│ ├── dag/ # DAG logic (pure) - causal delta tracking, dependency resolution +│ ├── node/ # Node runtime - orchestrates sync, events, blob sharing +│ ├── network/ # P2P networking - libp2p integration (Gossipsub, streams, DHT) +│ ├── server/ # JSON-RPC server - API, WebSocket/SSE subscriptions, admin endpoints +│ ├── auth/ # Authentication - identity management, JWT tokens +│ ├── store/ # Persistent storage backend (RocksDB) +│ ├── context/ # Context lifecycle management (application instances) +│ ├── merod/ # Node binary (coordinator or peer) +│ └── meroctl/ # CLI tool - node operations, app installation, method calls +├── apps/ # Example applications +│ ├── kv-store/ # Simple key-value store +│ ├── blobs/ # Blob sharing example +│ └── ... # More examples +├── contracts/ # Cross-chain smart contracts +│ ├── near/ # NEAR Protocol contracts +│ ├── icp/ # Internet Computer Protocol canisters +│ ├── ethereum/ # Solidity contracts +│ └── stellar/ # Stellar contracts +└── e2e-tests/ # End-to-end test suite +``` + +For detailed component explanations, see [Architecture Overview](core-concepts/architecture.md#component-map). + +## 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) + +--- + +**Built with ❤️ 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). + From 6fc56d9990c0eb521b43de6cccbed1e2b24a5ee6 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 06:17:00 -0300 Subject: [PATCH 03/22] fix: correct broken links in intro/index.md - Fixed all relative links to use ../ prefix (file is in intro/ subdirectory) - Added #core-architecture-snapshot anchor to Core Repository Structure section - Added intro/index.md to nav configuration in mkdocs.yml This fixes the broken link warnings from mkdocs build --strict --- docs/intro/index.md | 30 +++++++++++++++--------------- mkdocs.yml | 1 + 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/intro/index.md b/docs/intro/index.md index 6f67749..ccb6e82 100644 --- a/docs/intro/index.md +++ b/docs/intro/index.md @@ -59,10 +59,10 @@ See [Example Applications](../examples/index.md) for working implementations. | If you are… | Start here | | --- | --- | -| **Building apps** | [Build Your First Application](getting-started/build-your-first-application.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** | [Build Your First Application](../getting-started/build-your-first-application.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) | ## 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) ### 2. Node Layer - Orchestrates synchronization and execution @@ -81,7 +81,7 @@ 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) ### 3. Storage Layer - CRDT storage with automatic merging @@ -89,7 +89,7 @@ Calimero's architecture consists of four main layers: - Handles out-of-order delivery with dependency resolution - Merkle trees 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) ### 4. Network Layer - libp2p-based P2P (Gossipsub, reliable streams, DHT discovery) @@ -97,7 +97,7 @@ Calimero's architecture consists of four main layers: - WebSocket/SSE 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) ## How It Works (Transaction Flow) @@ -110,9 +110,9 @@ Calimero's architecture consists of four main layers: 7. **If not ready**: buffer until parents arrive (DAG handles this automatically) 8. **Periodic P2P sync** ensures eventual consistency -For detailed flow diagrams, see [Architecture Overview](core-concepts/architecture.md). +For detailed flow diagrams, see [Architecture Overview](../core-concepts/architecture.md). -## Core Repository Structure +## Core Repository Structure {#core-architecture-snapshot} The Calimero Core repository (`calimero-network/core`) contains the runtime and all supporting infrastructure: @@ -143,14 +143,14 @@ core/ └── e2e-tests/ # End-to-end test suite ``` -For detailed component explanations, see [Architecture Overview](core-concepts/architecture.md#component-map). +For detailed component explanations, see [Architecture Overview](../core-concepts/architecture.md#component-map). ## 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) --- diff --git a/mkdocs.yml b/mkdocs.yml index 3eba0ed..571138b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,6 +82,7 @@ extra_javascript: # Navigation structure nav: - Home: index.md + - Introduction: intro/index.md - Build: - Getting Started: - Overview: getting-started/index.md From f09fdae6161d9d8d4b4a5df054638aa7a13fa8a0 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 06:27:22 -0300 Subject: [PATCH 04/22] docs: add comprehensive CLI, SDK, and core apps documentation - Add meroctl CLI reference guide with all commands and workflows - Add SDK guide for builders covering CRDT collections, patterns, and best practices - Add core apps examples guide showcasing reference implementations - Update navigation to include new guides - Link guides from builder directory and examples index This documents the CLI (meroctl), SDK (sdk + storage crates), and examples (core/apps) as requested. --- docs/builder-directory/index.md | 2 + docs/builder-directory/sdk-guide.md | 426 ++++++++++++++++++++++++++++ docs/examples/core-apps-examples.md | 346 ++++++++++++++++++++++ docs/examples/index.md | 34 ++- docs/tools-apis/index.md | 2 +- docs/tools-apis/meroctl-cli.md | 322 +++++++++++++++++++++ mkdocs.yml | 9 +- 7 files changed, 1131 insertions(+), 10 deletions(-) create mode 100644 docs/builder-directory/sdk-guide.md create mode 100644 docs/examples/core-apps-examples.md create mode 100644 docs/tools-apis/meroctl-cli.md diff --git a/docs/builder-directory/index.md b/docs/builder-directory/index.md index 97ce5ea..f50743d 100644 --- a/docs/builder-directory/index.md +++ b/docs/builder-directory/index.md @@ -971,6 +971,8 @@ By following this walkthrough (or just reading it), you now understand: ### Want to Go Deeper? +- **[SDK Guide](sdk-guide.md)** - Complete guide to building with the Calimero SDK +- **[Core Apps Examples](../examples/core-apps-examples.md)** - Reference implementations in `core/apps` - **[Introduction](../intro/index.md)** - Understand Calimero's core concepts and architecture - **[Privacy, Verifiability & Security](../privacy-verifiability-security/index.md)** - Learn about private contexts and data flow - **[App Directory](../app-directory/index.md)** - Discover what's already built on Calimero diff --git a/docs/builder-directory/sdk-guide.md b/docs/builder-directory/sdk-guide.md new file mode 100644 index 0000000..3703385 --- /dev/null +++ b/docs/builder-directory/sdk-guide.md @@ -0,0 +1,426 @@ +# Calimero SDK Guide for Builders + +The Calimero SDK (`core/crates/sdk` and `core/crates/storage`) provides everything you need to build distributed, peer-to-peer applications with automatic conflict-free synchronization. + +## Overview + +The SDK consists of two main components: + +- **Application SDK** (`core/crates/sdk`): Macros, event system, private storage, and runtime integration +- **Storage SDK** (`core/crates/storage`): CRDT collections with automatic merge semantics + +Together, they enable you to build applications with: +- Automatic conflict resolution via CRDTs +- Real-time event propagation +- Private node-local storage +- Type-safe state management + +## Core Concepts + +### State Definition + +Applications define **state** using the `#[app::state]` macro: + +```rust +use calimero_sdk::app; +use calimero_storage::collections::UnorderedMap; +use calimero_sdk::borsh::{BorshSerialize, BorshDeserialize}; + +#[app::state(emits = Event)] +#[derive(BorshSerialize, BorshDeserialize)] +#[borsh(crate = "calimero_sdk::borsh")] +pub struct MyApp { + // CRDT-backed state (automatically synchronized) + items: UnorderedMap, + + // Can nest CRDTs arbitrarily + nested: UnorderedMap>, +} +``` + +**Key points:** +- State is persisted and synchronized across nodes +- Must derive `BorshSerialize` and `BorshDeserialize` for persistence +- Use `#[app::state(emits = Event)]` to enable event emission + +### Logic Implementation + +Implement **logic** using the `#[app::logic]` macro: + +```rust +#[app::logic] +impl MyApp { + // Initialize state (called once on context creation) + #[app::init] + pub fn init() -> MyApp { + MyApp { + items: UnorderedMap::new(), + nested: UnorderedMap::new(), + } + } + + // Mutation method (changes state, generates delta) + pub fn add_item(&mut self, key: String, value: String) -> app::Result<()> { + self.items.insert(key, value)?; + Ok(()) + } + + // View method (read-only, no delta generated) + #[app::view] + pub fn get_item(&self, key: &str) -> app::Result> { + self.items.get(key)?.map(|v| v.get().clone()).ok_or_else(|| app::Error::NotFound) + } +} +``` + +**Key points:** +- `#[app::init]` marks the initialization function +- Mutation methods (`&mut self`) generate deltas and sync +- View methods (`#[app::view]`) are read-only and faster +- Use `app::Result` for error handling + +### CRDT Collections + +The SDK provides several CRDT collection types: + +#### UnorderedMap + +Key-value storage with automatic conflict resolution: + +```rust +use calimero_storage::collections::UnorderedMap; + +let mut map: UnorderedMap = UnorderedMap::new(); + +// Insert value (conflict-free) +map.insert("key".to_string(), "value".to_string())?; + +// Get value +let value = map.get("key")?; // Returns Option + +// Remove value +map.remove("key")?; + +// Check existence +if map.contains("key")? { + // ... +} + +// Iterate entries +for (key, value) in map.entries()? { + // ... +} +``` + +#### Vector + +Ordered list with element-wise merging: + +```rust +use calimero_storage::collections::Vector; + +let mut vec: Vector = Vector::new(); + +// Append element +vec.push("item".to_string())?; + +// Get element by index +let item = vec.get(0)?; // Returns Option + +// Insert at position +vec.insert(0, "first".to_string())?; + +// Remove element +vec.remove(0)?; +``` + +#### Counter + +Distributed counter with automatic summation: + +```rust +use calimero_storage::collections::Counter; + +let mut counter = Counter::new(); + +// Increment +counter.increment()?; + +// Decrement +counter.decrement()?; + +// Get value +let value = counter.value(); // Returns i64 +``` + +#### LwwRegister + +Last-Write-Wins register for single values: + +```rust +use calimero_storage::collections::LwwRegister; + +let mut register: LwwRegister = LwwRegister::new("initial".to_string()); + +// Set value (latest timestamp wins) +register.set("updated".to_string())?; + +// Get value +let value = register.get().clone(); +``` + +#### UnorderedSet + +Set with union-based merging: + +```rust +use calimero_storage::collections::UnorderedSet; + +let mut set: UnorderedSet = UnorderedSet::new(); + +// Insert element +set.insert("item".to_string())?; + +// Check membership +if set.contains("item")? { + // ... +} + +// Remove element +set.remove("item")?; +``` + +### Event System + +Applications can emit events for real-time updates: + +```rust +#[app::state(emits = Event)] +pub struct MyApp { + items: UnorderedMap, +} + +// Define event types +#[app::event] +pub enum Event<'a> { + ItemAdded { + key: &'a str, + value: &'a str, + }, + ItemRemoved { + key: &'a str, + }, +} + +#[app::logic] +impl MyApp { + pub fn add_item(&mut self, key: String, value: String) -> app::Result<()> { + self.items.insert(key.clone(), value.clone())?; + + // Emit event (propagated to all peers) + app::emit!(Event::ItemAdded { + key: &key, + value: &value, + }); + + Ok(()) + } +} +``` + +**Event lifecycle:** +1. Emitted during method execution +2. Included in delta broadcast +3. Handlers execute on peer nodes (not author node) +4. Handlers can update UI or trigger side effects + +### Private Storage + +For node-local data (secrets, caches, per-node counters): + +```rust +use calimero_sdk::private_storage; + +pub fn use_private_storage() { + // Create private entry + let secrets = private_storage::entry::("my-secrets"); + + // Read value + let current = secrets.get_or_init(|| Secrets::default()); + + // Modify value (never synced, stays on node) + secrets.write(|s| { + s.token = "rotated-token".to_string(); + }); +} +``` + +**Key properties:** +- Never replicated across nodes +- Stored via `storage_read` / `storage_write` directly +- Never included in CRDT deltas +- Only accessible on the executing node + +## Common Patterns + +### Pattern 1: Simple Key-Value Store + +```rust +#[app::state(emits = Event)] +pub struct KvStore { + items: UnorderedMap>, +} + +#[app::logic] +impl KvStore { + #[app::init] + pub fn init() -> KvStore { + KvStore { + items: UnorderedMap::new(), + } + } + + pub fn set(&mut self, key: String, value: String) -> app::Result<()> { + self.items.insert(key, value.into())?; + Ok(()) + } + + #[app::view] + pub fn get(&self, key: &str) -> app::Result> { + Ok(self.items.get(key)?.map(|v| v.get().clone())) + } +} +``` + +### Pattern 2: Counter with Metrics + +```rust +#[app::state] +pub struct Metrics { + page_views: UnorderedMap, +} + +#[app::logic] +impl Metrics { + #[app::init] + pub fn init() -> Metrics { + Metrics { + page_views: UnorderedMap::new(), + } + } + + pub fn track_page_view(&mut self, page: String) -> app::Result<()> { + if let Some(counter) = self.page_views.get(&page)? { + counter.increment()?; + } else { + let mut counter = Counter::new(); + counter.increment()?; + self.page_views.insert(page, counter)?; + } + Ok(()) + } + + #[app::view] + pub fn get_views(&self, page: &str) -> app::Result { + Ok(self.page_views.get(page)?.map(|c| c.value()).unwrap_or(0)) + } +} +``` + +### Pattern 3: Nested Structures + +```rust +#[app::state] +pub struct TeamMetrics { + // Map of team → Map of member → Counter + teams: UnorderedMap>, +} + +#[app::logic] +impl TeamMetrics { + pub fn increment_metric( + &mut self, + team: String, + member: String, + ) -> app::Result<()> { + let members = self.teams + .entry(team)? + .or_insert_with(|| UnorderedMap::new()); + + let counter = members + .entry(member)? + .or_insert_with(|| Counter::new()); + + counter.increment()?; + Ok(()) + } +} +``` + +## Building Applications + +### Project Setup + +```bash +# Create new Rust project +cargo new my-calimero-app +cd my-calimero-app + +# Add dependencies to Cargo.toml +[dependencies] +calimero-sdk = { path = "../../core/crates/sdk" } +calimero-storage = { path = "../../core/crates/storage" } +calimero-sdk-macros = { path = "../../core/crates/sdk/macros" } +borsh = { version = "1.0", features = ["derive"] } + +[lib] +crate-type = ["cdylib"] + +[dependencies.calimero-sdk] +features = ["macro"] +``` + +### Build to WASM + +```bash +# Add WASM target +rustup target add wasm32-unknown-unknown + +# Build WASM binary +cargo build --target wasm32-unknown-unknown --release + +# Output: target/wasm32-unknown-unknown/release/my_calimero_app.wasm +``` + +### Extract ABI + +```bash +# Extract ABI from WASM +calimero-abi extract \ + target/wasm32-unknown-unknown/release/my_calimero_app.wasm \ + -o abi.json +``` + +## Best Practices + +1. **Always use CRDTs**: Don't use regular Rust collections for synchronized state +2. **Mark views with `#[app::view]`**: Improve performance and intent clarity +3. **Handle errors properly**: Use `app::Result` and meaningful error types +4. **Use private storage for secrets**: Never put secrets in CRDT state +5. **Emit events for UI updates**: Enable real-time updates across nodes +6. **Test with multiple nodes**: Verify sync behavior in multi-node scenarios + +## Deep Dives + +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 + +## Related Topics + +- [Build Your First Application](../getting-started/build-your-first-application.md) - Step-by-step tutorial +- [Applications](../core-concepts/applications.md) - Application architecture overview +- [Core Apps Examples](./core-apps-examples.md) - Reference implementations + diff --git a/docs/examples/core-apps-examples.md b/docs/examples/core-apps-examples.md new file mode 100644 index 0000000..dab55dd --- /dev/null +++ b/docs/examples/core-apps-examples.md @@ -0,0 +1,346 @@ +# Core Apps Examples + +The `core/apps` directory contains reference implementations demonstrating various SDK patterns and use cases. These examples serve as learning resources and starting points for your own applications. + +## Overview + +| Example | What it demonstrates | Key SDK features | +| --- | --- | --- | +| **kv-store** | Basic CRDT usage | `UnorderedMap`, `LwwRegister`, events | +| **kv-store-init** | Initialization patterns | `#[app::init]`, state setup | +| **kv-store-with-handlers** | Event handling | Event emission and handlers | +| **blobs** | File/blob management | Blob storage and distribution | +| **collaborative-editor** | Text collaboration | `ReplicatedGrowableArray` (RGA) CRDT | +| **private-data** | Private storage | Node-local secrets and data | +| **team-metrics** | Nested CRDTs | Nested maps, counters, metrics | +| **xcall-example** | Cross-context calls | Inter-context communication | + +## kv-store + +**Location**: [`core/apps/kv-store`](https://github.com/calimero-network/core/tree/master/apps/kv-store) + +**What it does:** +Simple key-value store demonstrating basic CRDT operations and event emission. + +**Key features:** +- `UnorderedMap>` for key-value storage +- Event emission for insertions, updates, and removals +- View methods for read-only queries +- Error handling patterns + +**API methods:** +- `set(key: String, value: String)` - Store or update a value +- `get(key: &str) -> Option` - Retrieve a value +- `remove(key: &str) -> Option` - Remove a value +- `clear()` - Remove all entries +- `len() -> usize` - Get number of entries +- `entries() -> BTreeMap` - Get all entries + +**Example usage:** +```bash +# Build +cd core/apps/kv-store +./build.sh + +# Install +meroctl --node node1 app install \ + --path res/kv_store.wasm \ + --application-id kv-store + +# Create context +meroctl --node node1 context create \ + --application-id kv-store \ + --context-id kv-context + +# Set a value +meroctl --node node1 call \ + --context-id kv-context \ + --method set \ + --args '{"key": "hello", "value": "world"}' + +# Get a value +meroctl --node node1 call \ + --context-id kv-context \ + --method get \ + --args '{"key": "hello"}' +``` + +**Learn from this example:** +- Basic CRDT state definition +- Mutations vs views +- Event emission patterns +- Error handling with `app::Result` + +## kv-store-with-handlers + +**Location**: [`core/apps/kv-store-with-handlers`](https://github.com/calimero-network/core/tree/master/apps/kv-store-with-handlers) + +**What it does:** +KV store with event handlers demonstrating real-time event processing. + +**Key features:** +- Same KV operations as basic kv-store +- Event handlers that execute on peer nodes +- Event-driven UI updates +- Handler patterns and best practices + +**Learn from this example:** +- Event handler implementation +- Real-time event propagation +- UI update patterns + +## blobs + +**Location**: [`core/apps/blobs`](https://github.com/calimero-network/core/tree/master/apps/blobs) + +**What it does:** +Demonstrates blob storage and distribution across the network. + +**Key features:** +- Upload files to blob storage +- Content-addressed blob IDs +- Blob listing and retrieval +- Context-aware blob announcements +- Network distribution via P2P + +**API methods:** +- `upload_blob(blob_id: [u8; 32], size: u64)` - Register a blob +- `list_blobs() -> Vec<[u8; 32]>` - List all blobs +- `get_blob_info(blob_id: [u8; 32]) -> Option` - Get blob metadata + +**Example usage:** +```bash +# Upload a blob +meroctl --node node1 blob upload \ + --file ./document.pdf \ + --context-id blob-context + +# Register in application +meroctl --node node1 call \ + --context-id blob-context \ + --method upload_blob \ + --args '{"blob_id": "...", "size": 1024}' + +# List blobs +meroctl --node node1 call \ + --context-id blob-context \ + --method list_blobs +``` + +**Learn from this example:** +- Blob storage patterns +- Content-addressed file sharing +- Large file distribution +- P2P blob discovery + +## collaborative-editor + +**Location**: [`core/apps/collaborative-editor`](https://github.com/calimero-network/core/tree/master/apps/collaborative-editor) + +**What it does:** +Real-time collaborative text editor using RGA (Replicated Growable Array) CRDT. + +**Key features:** +- Character-level collaborative editing +- `ReplicatedGrowableArray` for conflict-free text operations +- Insert and delete operations at any position +- Edit counting with `Counter` CRDT +- Document metadata (title, statistics) + +**API methods:** +- `init() -> EditorState` - Initialize new document +- `set_title(title: String)` - Set document title +- `insert_text(position: usize, text: String)` - Insert text +- `delete_text(start: usize, end: usize)` - Delete text range +- `get_text() -> String` - Get full document text +- `get_title() -> String` - Get document title +- `get_edit_count() -> i64` - Get total edit count + +**Example usage:** +```bash +# Insert text at position 0 +meroctl --node node1 call \ + --context-id editor-context \ + --method insert_text \ + --args '{"position": 0, "text": "Hello"}' + +# Delete text from position 5 to 10 +meroctl --node node1 call \ + --context-id editor-context \ + --method delete_text \ + --args '{"start": 5, "end": 10}' + +# Get full text +meroctl --node node1 call \ + --context-id editor-context \ + --method get_text +``` + +**Learn from this example:** +- RGA CRDT for text editing +- Character-level conflict resolution +- Collaborative editing patterns +- Position-based operations + +## private-data + +**Location**: [`core/apps/private-data`](https://github.com/calimero-network/core/tree/master/apps/private-data) + +**What it does:** +Demonstrates private storage for node-local secrets and data. + +**Key features:** +- Private storage usage patterns +- Node-local data that never syncs +- Secrets management +- Per-node counters and caches + +**API methods:** +- Methods for storing/retrieving private data +- Per-node secret rotation +- 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) + +**Learn from this example:** +- Private storage API usage +- Secrets management patterns +- When to use private vs shared storage + +## 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) + +**What it does:** +Demonstrates nested CRDT structures for team metrics tracking. + +**Key features:** +- Nested `UnorderedMap` structures +- Map of team → Map of member → Counter +- Metrics aggregation patterns +- Complex CRDT hierarchies + +**API methods:** +- `increment_metric(team: String, member: String)` - Increment member metric +- `get_team_metrics(team: String) -> HashMap` - Get all team metrics +- `get_member_metric(team: String, member: String) -> i64` - Get specific metric + +**Learn from this example:** +- Nested CRDT patterns +- Multi-level data structures +- Metrics aggregation +- Complex state management + +## xcall-example + +**Location**: [`core/apps/xcall-example`](https://github.com/calimero-network/core/tree/master/apps/xcall-example) + +**What it does:** +Demonstrates cross-context calls (xcall) for inter-context communication. + +**Key features:** +- Cross-context method calls +- Context-to-context communication +- Ping-pong pattern demonstration +- Event emission from xcalls + +**API methods:** +- `ping(target_context: String)` - Send ping to another context +- `pong()` - Handle ping (increments counter) +- `get_counter() -> u64` - Get ping counter +- `reset_counter()` - Reset counter + +**Example usage:** +```bash +# Deploy to Context A and Context B + +# Send ping from Context A to Context B +meroctl --node node1 call \ + --context-id context-a \ + --method ping \ + --args '{"target_context": ""}' + +# Check counter on Context B +meroctl --node node1 call \ + --context-id context-b \ + --method get_counter +``` + +**Learn from this example:** +- Cross-context communication +- xcall patterns +- Inter-context coordination +- Multi-context applications + +## Running Examples + +### Using Merobox Workflows + +Most examples include Merobox workflow files for automated testing: + +```bash +# Run example workflow +cd core/apps/kv-store +merobox bootstrap run workflows/kv-store.yml + +# Or for other examples +cd core/apps/collaborative-editor +merobox bootstrap run workflows/collaborative-editor.yml +``` + +### Manual Testing + +```bash +# 1. Build the example +cd core/apps/kv-store +./build.sh + +# 2. Start nodes (via merobox) +merobox run --count 2 + +# 3. Install application +meroctl --node calimero-node-1 app install \ + --path res/kv_store.wasm \ + --application-id kv-store + +# 4. Create context +meroctl --node calimero-node-1 context create \ + --application-id kv-store \ + --context-id test-context + +# 5. Test methods +meroctl --node calimero-node-1 call \ + --context-id test-context \ + --method set \ + --args '{"key": "hello", "value": "world"}' +``` + +## Learning Path + +**Start here:** +1. **kv-store** - Understand basic CRDT operations +2. **kv-store-with-handlers** - Learn event handling +3. **collaborative-editor** - See advanced CRDT usage (RGA) + +**Then explore:** +- **blobs** - File sharing patterns +- **private-data** - Secrets management +- **team-metrics** - Complex nested structures +- **xcall-example** - Cross-context communication + +## Related Topics + +- [SDK Guide](../builder-directory/sdk-guide.md) - Complete SDK reference +- [Build Your First Application](../getting-started/build-your-first-application.md) - Step-by-step tutorial +- [Applications](../core-concepts/applications.md) - Application architecture + +## Deep Dives + +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) + diff --git a/docs/examples/index.md b/docs/examples/index.md index 9a25aa7..3845792 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -1,16 +1,36 @@ # Examples -> Placeholder directory — expand once example narratives are drafted. +Calimero examples range from simple starter apps to complex multi-context applications. Learn by exploring working code and adapting patterns to your own projects. -- [Battleships](battleships.md) -- [Shared Todo Backlog](shared-todo-backlog.md) -- [Split Bills](split-bills.md) -- [Additional Templates](additional-templates.md) +## Core Apps Examples + +**Start here**: [Core Apps Examples](core-apps-examples.md) — Reference implementations from `core/apps` that demonstrate SDK patterns and CRDT usage. + +These examples live in the [`calimero-network/core/apps`](https://github.com/calimero-network/core/tree/master/apps) directory and include: + +- **kv-store** - Basic CRDT operations +- **blobs** - File/blob management +- **collaborative-editor** - Text collaboration with RGA CRDT +- **private-data** - Private storage patterns +- **team-metrics** - Nested CRDT structures +- **xcall-example** - Cross-context communication + +Each example includes source code, README, and Merobox workflow files for easy testing. + +## Application Examples + +- [Battleships](battleships.md) - Multiplayer game demonstrating real-time sync +- [Shared Todo Backlog](shared-todo-backlog.md) - CRDT patterns and UI workflows +- [Split Bills](split-bills.md) - Delegation and settlement flows +- [Additional Templates](additional-templates.md) - More examples and templates ## Overview -- Explain tiers (starter, intermediate, advanced). -- Note dependencies before cloning. +Examples are organized by complexity: + +- **Starter**: Basic CRDT usage (kv-store, simple counters) +- **Intermediate**: Event handling, blob management, nested structures +- **Advanced**: Cross-context calls, complex state machines, multi-context apps ## Battleships diff --git a/docs/tools-apis/index.md b/docs/tools-apis/index.md index 68c4b35..613ee08 100644 --- a/docs/tools-apis/index.md +++ b/docs/tools-apis/index.md @@ -10,7 +10,7 @@ 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` | [`calimero-network/core` – CLI](https://github.com/calimero-network/core#cli) | Command-line surface for context lifecycle, deployment, diagnostics. | +| `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. | ## Developer Tooling diff --git a/docs/tools-apis/meroctl-cli.md b/docs/tools-apis/meroctl-cli.md new file mode 100644 index 0000000..c6471aa --- /dev/null +++ b/docs/tools-apis/meroctl-cli.md @@ -0,0 +1,322 @@ +# meroctl CLI Reference + +`meroctl` is the command-line interface for managing Calimero nodes, applications, contexts, and blobs. It provides a complete toolkit for development, deployment, and operations. + +## Installation + +```bash +# From source (requires Rust) +cargo install --path core/crates/meroctl + +# Or via package manager (when available) +# brew install calimero-tap/meroctl +``` + +## Configuration + +### Node Connection + +Connect to a node using one of these methods: + +```bash +# Using node alias (configured in ~/.calimero/config.toml) +meroctl --node node1 + +# Using direct API URL +meroctl --api http://localhost:2528 +``` + +### Environment Variables + +```bash +# Set default config directory +export CALIMERO_HOME=~/.calimero + +# Configure node aliases in ~/.calimero/config.toml +``` + +## Command Categories + +### Applications (`app`) + +Manage WASM applications on nodes: + +```bash +# List all applications +meroctl --node node1 app ls + +# Get application details +meroctl --node node1 app get + +# Install application from WASM file +meroctl --node node1 app install \ + --path ./my-app.wasm \ + --application-id \ + --context-id + +# Watch WASM file and auto-update contexts +meroctl --node node1 app watch --path ./my-app.wasm + +# Uninstall application +meroctl --node node1 app uninstall + +# List packages +meroctl --node node1 app list-packages + +# List versions of a package +meroctl --node node1 app list-versions com.example.myapp + +# Get latest version +meroctl --node node1 app get-latest-version com.example.myapp +``` + +### Contexts (`context`) + +Manage application contexts: + +```bash +# List all contexts +meroctl --node node1 context ls + +# Create new context +meroctl --node node1 context create \ + --application-id + +# Create context in dev mode (with watch) +meroctl --node node1 context create \ + --watch \ + --context-id + +# Get context details +meroctl --node node1 context get + +# Join a context via invitation +meroctl --node node1 context join \ + --context-id \ + --invitation + +# Join via open invitation +meroctl --node node1 context join-open \ + --context-id + +# Invite identity to context +meroctl --node node1 context invite \ + --context-id \ + --grantee-id + +# Create open invitation +meroctl --node node1 context invite-open \ + --context-id + +# Update context +meroctl --node node1 context update \ + --context-id \ + --metadata + +# Delete context +meroctl --node node1 context delete + +# Watch context for changes +meroctl --node node1 context watch + +# Sync context state +meroctl --node node1 context sync + +# Manage context aliases +meroctl --node node1 context alias set +meroctl --node node1 context alias get +meroctl --node node1 context use + +# Manage context identity/permissions +meroctl --node node1 context identity grant \ + --context-id \ + --grantee-id \ + --permission ManageApplication + +meroctl --node node1 context identity revoke \ + --context-id \ + --grantee-id +``` + +### Calling Methods (`call`) + +Execute application methods: + +```bash +# Call a mutation method +meroctl --node node1 call \ + --context-id \ + --method set \ + --args '{"key": "hello", "value": "world"}' \ + --executor-public-key + +# Call a view method (read-only) +meroctl --node node1 call \ + --context-id \ + --method get \ + --args '{"key": "hello"}' +``` + +### Blobs (`blob`) + +Manage content-addressed blobs: + +```bash +# List all blobs +meroctl --node node1 blob ls + +# Upload blob from file +meroctl --node node1 blob upload \ + --file /path/to/file \ + --context-id # Optional: announce to context + +# Download blob to file +meroctl --node node1 blob download \ + --blob-id \ + --output /path/to/output \ + --context-id # Optional: network discovery + +# Get blob information +meroctl --node node1 blob info --blob-id + +# Delete blob +meroctl --node node1 blob delete --blob-id +``` + +### Peers (`peers`) + +Manage peer connections: + +```bash +# List connected peers +meroctl --node node1 peers ls + +# Get peer information +meroctl --node node1 peers get +``` + +### Node (`node`) + +Node management operations: + +```bash +# Get node status +meroctl --node node1 node status + +# Get node information +meroctl --node node1 node info + +# Health check +meroctl --node node1 node health +``` + +## Output Formats + +```bash +# JSON output (default) +meroctl --node node1 context ls --output-format json + +# Table output +meroctl --node node1 context ls --output-format table + +# Plain text +meroctl --node node1 context ls --output-format plain +``` + +## Common Workflows + +### Development Workflow + +```bash +# 1. Start local node (via merobox or Docker) +merobox run --count 1 + +# 2. Install application +meroctl --node calimero-node-1 app install \ + --path ./build/my-app.wasm \ + --application-id my-app + +# 3. Create context +meroctl --node calimero-node-1 context create \ + --application-id my-app \ + --context-id my-context + +# 4. Watch for changes (auto-reload) +meroctl --node calimero-node-1 app watch my-app \ + --path ./build/my-app.wasm + +# 5. Call methods +meroctl --node calimero-node-1 call \ + --context-id my-context \ + --method my_method \ + --args '{"arg": "value"}' +``` + +### Multi-Node Workflow + +```bash +# Node 1: Create context +meroctl --node node1 context create --application-id my-app + +# Node 1: Invite Node 2 +meroctl --node node1 context invite \ + --context-id \ + --grantee-id + +# Node 2: Join context +meroctl --node node2 context join \ + --context-id \ + --invitation + +# Both nodes can now call methods and sync state +``` + +### Blob Sharing Workflow + +```bash +# Node 1: Upload blob and announce to context +meroctl --node node1 blob upload \ + --file ./document.pdf \ + --context-id + +# Output: blob_id: abc123... + +# Node 2: Download blob (discovered via context) +meroctl --node node2 blob download \ + --blob-id abc123... \ + --output ./downloaded.pdf \ + --context-id +``` + +## Troubleshooting + +### Connection Issues + +```bash +# Check node is running +meroctl --api http://localhost:2528 node health + +# Verify authentication +meroctl --node node1 context ls +``` + +### Common Errors + +- **"Node not found"**: Check node alias in `~/.calimero/config.toml` or use `--api` flag +- **"Context not found"**: Verify context ID with `context ls` +- **"Method not found"**: Check ABI with `app get ` +- **"Permission denied"**: Verify executor public key has access to context + +## Deep Dives + +For detailed CLI documentation: + +- **Source Code**: [`core/crates/meroctl`](https://github.com/calimero-network/core/tree/master/crates/meroctl) - Full implementation +- **Examples**: See `EXAMPLES` constants in source files for more usage patterns + +## Related Topics + +- [Applications](../core-concepts/applications.md) - Building applications that work with CLI +- [Contexts](../core-concepts/contexts.md) - Understanding context operations +- [Operator Track](../operator-track/index.md) - Running and managing nodes + diff --git a/mkdocs.yml b/mkdocs.yml index 571138b..5e37254 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,9 +90,12 @@ nav: - Launch Your First Context: getting-started/launch-your-first-context.md - Build Your First Application: getting-started/build-your-first-application.md - Sample App Walkthrough: getting-started/sample-app-walkthrough.md - - Builder Directory: builder-directory/index.md + - Builder Directory: + - Overview: builder-directory/index.md + - SDK Guide: builder-directory/sdk-guide.md - Examples: - Overview: examples/index.md + - Core Apps Examples: examples/core-apps-examples.md - Battleships: examples/battleships.md - Shared Todo Backlog: examples/shared-todo-backlog.md - Split Bills: examples/split-bills.md @@ -121,7 +124,9 @@ nav: - WebSocket Streams: reference/websocket-streams.md - Error Codes & Retries: reference/error-codes.md - Versioning & Changelog: reference/versioning-changelog.md - - Tools & APIs: tools-apis/index.md + - Tools & APIs: + - Overview: tools-apis/index.md + - meroctl CLI: tools-apis/meroctl-cli.md - Support: - Overview: support/index.md - FAQ: support/faq.md From 19cb9348f33918cf6ed09545c65041057312bf66 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 06:36:52 -0300 Subject: [PATCH 05/22] docs: Add comprehensive JavaScript SDK guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create detailed guide for building Calimero services with TypeScript/JavaScript - Cover architecture (TypeScript → Rollup → QuickJS → WASM), decorators, CRDTs, events - Include build pipeline, common patterns, best practices, and troubleshooting - Add navigation entry and link from Builder Directory overview --- docs/builder-directory/index.md | 3 +- docs/builder-directory/js-sdk-guide.md | 893 +++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 896 insertions(+), 1 deletion(-) create mode 100644 docs/builder-directory/js-sdk-guide.md diff --git a/docs/builder-directory/index.md b/docs/builder-directory/index.md index f50743d..3391ff1 100644 --- a/docs/builder-directory/index.md +++ b/docs/builder-directory/index.md @@ -971,7 +971,8 @@ By following this walkthrough (or just reading it), you now understand: ### Want to Go Deeper? -- **[SDK Guide](sdk-guide.md)** - Complete guide to building with the Calimero SDK +- **[SDK Guide](sdk-guide.md)** - Complete guide to building with the Calimero Rust SDK +- **[JavaScript SDK Guide](js-sdk-guide.md)** - Build Calimero services using TypeScript/JavaScript - **[Core Apps Examples](../examples/core-apps-examples.md)** - Reference implementations in `core/apps` - **[Introduction](../intro/index.md)** - Understand Calimero's core concepts and architecture - **[Privacy, Verifiability & Security](../privacy-verifiability-security/index.md)** - Learn about private contexts and data flow diff --git a/docs/builder-directory/js-sdk-guide.md b/docs/builder-directory/js-sdk-guide.md new file mode 100644 index 0000000..e44d0e7 --- /dev/null +++ b/docs/builder-directory/js-sdk-guide.md @@ -0,0 +1,893 @@ +# Calimero JavaScript SDK Guide + +Build Calimero services using **TypeScript/JavaScript**. The JavaScript SDK compiles your code to WebAssembly using QuickJS, enabling you to build distributed applications without writing Rust. + +> ⚠️ **Experimental:** The JavaScript SDK is still evolving. Expect breaking changes while we stabilize the toolchain. + +## Overview + +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) + +**Key features:** +- Write services in TypeScript/JavaScript instead of Rust +- Same CRDT collections as Rust SDK +- Automatic conflict resolution +- Event-driven architecture +- Private storage for node-local data + +## Architecture + +### Build Pipeline + +``` +TypeScript Source + ↓ + [TypeScript Compiler] + ↓ + JavaScript (ES6 modules) + ↓ + [Rollup] Bundle with dependencies + ↓ + JavaScript Bundle + ↓ + [QuickJS qjsc] Compile to C bytecode + ↓ + code.h (C header) + ↓ + [Extract Methods] Parse AST + ↓ + methods.h (C header) + ↓ + [Clang/WASI-SDK] Compile to WASM + ↓ + WASM Binary + ↓ + [wasi-stub + wasm-opt] Optimize + ↓ + Final Service (~500KB) +``` + +### Runtime Execution + +``` +┌─────────────────────────────────────────┐ +│ JavaScript Application │ +│ (Your code with decorators) │ +└──────────────┬──────────────────────────┘ + │ +┌──────────────┴──────────────────────────┐ +│ @calimero/sdk │ +│ - Decorators (@State, @Logic, etc.) │ +│ - CRDT Collections │ +│ - Event System │ +└──────────────┬──────────────────────────┘ + │ +┌──────────────┴──────────────────────────┐ +│ QuickJS Runtime (in WASM) │ +│ - JavaScript interpreter │ +│ - ~450KB overhead │ +└──────────────┬──────────────────────────┘ + │ +┌──────────────┴──────────────────────────┐ +│ Calimero Host Functions │ +│ (calimero-sys) │ +│ - storage_read/write │ +│ - emit/commit │ +│ - context_id/executor_id │ +└──────────────┬──────────────────────────┘ + │ +┌──────────────┴──────────────────────────┐ +│ Calimero Runtime (Wasmer) │ +│ - WASM execution │ +│ - P2P synchronization │ +│ - Storage (RocksDB) │ +└─────────────────────────────────────────┘ +``` + +**How it works:** +- Your TypeScript code runs inside QuickJS (a lightweight JavaScript engine) +- CRDT operations call host functions that interact with Rust storage +- State is serialized and synchronized across the network +- Events propagate to all peers automatically + +## Getting Started + +### Prerequisites + +- Node.js 18+ with WASI support +- `pnpm` ≥ 8 (or npm/yarn) +- Access to a Calimero node (`merod`) and CLI (`meroctl`) + +### Installation + +```bash +pnpm add @calimero/sdk +pnpm add -D @calimero/cli typescript +``` + +### Minimal Service + +```typescript +import { State, Logic, Init, View } from '@calimero/sdk'; +import { Counter } from '@calimero/sdk/collections'; +import * as env from '@calimero/sdk/env'; + +@State +export class CounterApp { + count: Counter = new Counter(); +} + +@Logic(CounterApp) +export class CounterLogic extends CounterApp { + @Init + static init(): CounterApp { + env.log('Initializing counter'); + return new CounterApp(); + } + + increment(): void { + env.log('Incrementing counter'); + this.count.increment(); + } + + @View() + getCount(): bigint { + return this.count.value(); + } +} +``` + +### Build & Deploy + +```bash +# Build WASM from TypeScript +npx calimero-sdk build src/index.ts -o build/service.wasm + +# Install on node +meroctl --node-name node1 app install \ + --path build/service.wasm \ + --context-id + +# Call methods +meroctl --node-name node1 call \ + --context-id \ + --method increment + +meroctl --node-name node1 call \ + --context-id \ + --method getCount +``` + +## Core Concepts + +### Decorators + +#### @State + +Marks a class as application state: + +```typescript +import { State } from '@calimero/sdk'; +import { UnorderedMap, Counter } from '@calimero/sdk/collections'; + +@State +export class MyApp { + items: UnorderedMap = new UnorderedMap(); + viewCount: Counter = new Counter(); +} +``` + +**Key points:** +- State is persisted and synchronized across nodes +- Initialize CRDT fields inline (runtime reuses persisted IDs) +- Don't use regular JavaScript objects for synchronized state + +#### @Logic + +Marks a class as application logic (methods): + +```typescript +import { Logic, Init } from '@calimero/sdk'; + +@Logic(MyApp) +export class MyAppLogic extends MyApp { + @Init + static init(): MyApp { + return new MyApp(); + } + + // Mutation method (changes state) + addItem(key: string, value: string): void { + this.items.set(key, value); + } + + // View method (read-only) + @View() + getItem(key: string): string | undefined { + return this.items.get(key); + } +} +``` + +**Key points:** +- Logic class extends State class +- `@Init` marks the initialization method (called once on context creation) +- Methods without `@View()` are mutations (generate deltas) +- Methods with `@View()` are read-only (no delta generated) + +#### @View() + +Marks read-only methods: + +```typescript +@Logic(MyApp) +export class MyAppLogic extends MyApp { + // Mutation - generates delta + setValue(value: string): void { + this.register.set(value); + } + + // View - read-only, no delta + @View() + getValue(): string { + return this.register.get(); + } +} +``` + +**Benefits:** +- Faster execution (no persistence overhead) +- No redundant storage deltas +- Clear intent in API + +#### @Event + +Marks event classes: + +```typescript +import { Event } from '@calimero/sdk'; + +@Event +export class ItemAdded { + constructor( + public key: string, + public value: string, + public timestamp: number + ) {} +} +``` + +#### @Init + +Marks the initialization method: + +```typescript +@Logic(MyApp) +export class MyAppLogic extends MyApp { + @Init + static init(): MyApp { + return new MyApp(); + } +} +``` + +**Requirements:** +- Must be static +- Must return an instance of State class +- Called once when context is created + +### CRDT Collections + +The JavaScript SDK provides the same CRDT collections as the Rust SDK: + +#### UnorderedMap + +Key-value storage with Last-Write-Wins conflict resolution: + +```typescript +import { UnorderedMap } from '@calimero/sdk/collections'; + +const map = new UnorderedMap(); + +// Set value +map.set('key', 'value'); + +// Get value +const value = map.get('key'); // 'value' | undefined + +// Check existence +const exists = map.has('key'); // boolean + +// Remove entry +map.remove('key'); + +// Iterate +const entries = map.entries(); // [['key1', 'value1'], ['key2', 'value2']] +const keys = map.keys(); // ['key1', 'key2'] +const values = map.values(); // ['value1', 'value2'] + +// Size +const size = map.entries().length; +``` + +#### Vector + +Ordered list maintaining insertion order: + +```typescript +import { Vector } from '@calimero/sdk/collections'; + +const vec = new Vector(); + +// Add element +vec.push('first'); +vec.push('second'); + +// Get element +const item = vec.get(0); // 'first' + +// Remove element +const last = vec.pop(); // 'second' + +// Length +const len = vec.len(); // number +``` + +#### Counter + +Distributed counter with automatic summation: + +```typescript +import { Counter } from '@calimero/sdk/collections'; + +const counter = new Counter(); + +// Increment +counter.increment(); +counter.incrementBy(5); + +// Get value +const total = counter.value(); // bigint + +// Decrement +counter.decrement(); +counter.decrementBy(2); +``` + +#### LwwRegister + +Last-Write-Wins register for single values: + +```typescript +import { LwwRegister } from '@calimero/sdk/collections'; + +const register = new LwwRegister(); + +// Set value +register.set('hello'); + +// Get value +const value = register.get(); // 'hello' | null + +// Get timestamp +const timestamp = register.timestamp(); // bigint +``` + +#### UnorderedSet + +Set with union-based merging: + +```typescript +import { UnorderedSet } from '@calimero/sdk/collections'; + +const set = new UnorderedSet(); + +// Add element +set.add('item'); // true on first insert + +// Check membership +const has = set.has('item'); // boolean + +// Remove element +set.delete('item'); + +// Get all values +const all = set.toArray(); // string[] + +// Size +const size = set.size(); // number +``` + +### Nested CRDTs + +CRDTs can be nested arbitrarily: + +```typescript +@State +export class TeamMetrics { + // Map of member → Map of metric → Counter + memberMetrics: UnorderedMap>; + + // Map of team → Set of members + teams: UnorderedMap>; + + // Vector of profiles (each with nested data) + profiles: Vector; + + constructor() { + this.memberMetrics = new UnorderedMap(); + this.teams = new UnorderedMap(); + this.profiles = new Vector(); + } +} +``` + +**Important:** When you get a nested CRDT, you receive a **handle** that retains the CRDT ID. Mutating the handle issues host calls without deserializing the entire structure. + +```typescript +// Get nested map handle (lightweight, ID retained) +const metrics = this.memberMetrics.get('alice'); + +if (metrics) { + // Mutate nested CRDT (incremental host call) + const counter = metrics.get('commits') ?? new Counter(); + counter.increment(); + metrics.set('commits', counter); +} +``` + +### Event System + +Emit events for real-time updates: + +```typescript +import { Event, emit, emitWithHandler } from '@calimero/sdk'; + +// Define event +@Event +export class ItemAdded { + constructor(public key: string, public value: string) {} +} + +@Logic(MyApp) +export class MyAppLogic extends MyApp { + addItem(key: string, value: string): void { + this.items.set(key, value); + + // Emit event without handler + emit(new ItemAdded(key, value)); + + // Or emit with handler (handler executes on receiving nodes) + emitWithHandler(new ItemAdded(key, value), 'onItemAdded'); + } + + // Event handler (runs on peer nodes, not author node) + onItemAdded(event: ItemAdded): void { + this.itemCount.increment(); + env.log(`Item added: ${event.key} = ${event.value}`); + } +} +``` + +**Event lifecycle:** +1. Emitted during method execution +2. Included in delta broadcast to all peers +3. Handlers execute on peer nodes (not author node) +4. Handlers can update state or trigger side effects + +**Handler requirements:** +- **Commutative**: Order-independent operations +- **Independent**: No shared mutable state between handlers +- **Idempotent**: Safe to retry +- **Pure**: No external side effects (only state updates) + +### Private Storage + +For node-local data (secrets, caches, per-node counters): + +```typescript +import { createPrivateEntry } from '@calimero/sdk'; + +// Create private entry +const secrets = createPrivateEntry<{ token: string }>('private:secrets'); + +// Get or initialize +const current = secrets.getOrInit(() => ({ token: '' })); + +// Modify (never synced across nodes) +secrets.modify( + (value) => { + value.token = 'rotated-token'; + }, + () => ({ token: '' }) // Initial value if not exists +); +``` + +**Key properties:** +- Never replicated across nodes +- Stored via `storage_read` / `storage_write` directly +- Never included in CRDT deltas +- Only accessible on the executing node + +## Build Pipeline + +### Development Setup + +```bash +# Create project +mkdir my-calimero-service +cd my-calimero-service +pnpm init + +# Install dependencies +pnpm add @calimero/sdk +pnpm add -D @calimero/cli typescript @types/node + +# Create TypeScript config +cat > tsconfig.json << EOF +{ + "compilerOptions": { + "target": "ES2020", + "module": "ESNext", + "lib": ["ES2020"], + "moduleResolution": "node", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true + }, + "include": ["src/**/*"] +} +EOF + +# Create source directory +mkdir src +``` + +### Build Process + +```bash +# Build WASM from TypeScript +npx calimero-sdk build src/index.ts -o build/service.wasm + +# With verbose output +npx calimero-sdk build src/index.ts -o build/service.wasm --verbose + +# Validate only (no build) +npx calimero-sdk validate src/index.ts +``` + +### Build Configuration + +The CLI automatically handles: +- TypeScript compilation +- Dependency bundling (Rollup) +- QuickJS bytecode generation +- WASM compilation (WASI-SDK) +- Optimization (wasm-opt) + +**Output:** +- `service.wasm` - Deployable WASM binary (~500KB with QuickJS overhead) + +## Common Patterns + +### Pattern 1: Simple Key-Value Store + +```typescript +import { State, Logic, Init, View } from '@calimero/sdk'; +import { UnorderedMap, LwwRegister } from '@calimero/sdk/collections'; + +@State +export class KvStore { + items: UnorderedMap>; + + constructor() { + this.items = new UnorderedMap(); + } +} + +@Logic(KvStore) +export class KvStoreLogic extends KvStore { + @Init + static init(): KvStore { + return new KvStore(); + } + + set(key: string, value: string): void { + const register = this.items.get(key) ?? new LwwRegister(); + register.set(value); + this.items.set(key, register); + } + + @View() + get(key: string): string | null { + const register = this.items.get(key); + return register ? register.get() : null; + } + + remove(key: string): void { + this.items.remove(key); + } +} +``` + +### Pattern 2: Metrics with Counters + +```typescript +import { State, Logic, Init, View } from '@calimero/sdk'; +import { UnorderedMap, Counter } from '@calimero/sdk/collections'; + +@State +export class Metrics { + pageViews: UnorderedMap; + + constructor() { + this.pageViews = new UnorderedMap(); + } +} + +@Logic(Metrics) +export class MetricsLogic extends Metrics { + @Init + static init(): Metrics { + return new Metrics(); + } + + trackPageView(page: string): void { + const counter = this.pageViews.get(page) ?? new Counter(); + counter.increment(); + this.pageViews.set(page, counter); + } + + @View() + getViews(page: string): bigint { + const counter = this.pageViews.get(page); + return counter ? counter.value() : 0n; + } +} +``` + +### 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'; + +@Event +export class ItemAdded { + constructor(public key: string, public value: string) {} +} + +@State +export class StoreWithEvents { + items: UnorderedMap; + eventCount: Counter; + + constructor() { + this.items = new UnorderedMap(); + this.eventCount = new Counter(); + } +} + +@Logic(StoreWithEvents) +export class StoreWithEventsLogic extends StoreWithEvents { + @Init + static init(): StoreWithEvents { + return new StoreWithEvents(); + } + + addItem(key: string, value: string): void { + this.items.set(key, value); + emitWithHandler(new ItemAdded(key, value), 'onItemAdded'); + } + + // Handler executes on peer nodes + onItemAdded(event: ItemAdded): void { + this.eventCount.increment(); + env.log(`Item added: ${event.key} = ${event.value}`); + } + + @View() + getEventCount(): bigint { + return this.eventCount.value(); + } +} +``` + +## Best Practices + +### 1. Initialize CRDTs Inline + +```typescript +// ✅ GOOD - Runtime reuses persisted IDs +@State +export class MyApp { + items: UnorderedMap = new UnorderedMap(); +} + +// ❌ BAD - Constructor runs every time +@State +export class MyApp { + items: UnorderedMap; + + constructor() { + this.items = new UnorderedMap(); // Not reused! + } +} +``` + +### 2. Use @View() for Read-Only Methods + +```typescript +// ✅ GOOD - No persistence overhead +@View() +getItem(key: string): string | undefined { + return this.items.get(key); +} + +// ❌ BAD - Generates unnecessary deltas +getItem(key: string): string | undefined { + return this.items.get(key); +} +``` + +### 3. Handle Nested CRDTs Correctly + +```typescript +// ✅ GOOD - Use handles, mutate incrementally +const metrics = this.memberMetrics.get('alice'); +if (metrics) { + const counter = metrics.get('commits') ?? new Counter(); + counter.increment(); + metrics.set('commits', counter); +} + +// ❌ BAD - Don't try to clone entire structure +const metrics = this.memberMetrics.get('alice'); +if (metrics) { + // Don't do this - it doesn't work + const cloned = { ...metrics }; // Wrong! +} +``` + +### 4. Make Event Handlers Safe + +```typescript +// ✅ GOOD - Commutative, independent, idempotent +onItemAdded(event: ItemAdded): void { + this.itemCount.increment(); // CRDT operations are safe +} + +// ❌ BAD - Not safe for parallel execution +onItemAdded(event: ItemAdded): void { + // Don't make external API calls! + fetch('/api/notify', { ... }); // Wrong! + + // Don't depend on execution order! + if (this.items.has(event.key)) { // Race condition! + // ... + } +} +``` + +### 5. Use Private Storage for Secrets + +```typescript +// ✅ GOOD - Secrets never leave the node +const secrets = createPrivateEntry<{ token: string }>('private:secrets'); + +// ❌ BAD - Don't put secrets in CRDT state +@State +export class MyApp { + apiToken: string = ''; // Never do this! +} +``` + +## Troubleshooting + +### Build Errors + +**Issue**: TypeScript compilation errors +```bash +# Check TypeScript version +pnpm list typescript + +# Use verbose flag for details +npx calimero-sdk build src/index.ts -o build/service.wasm --verbose +``` + +**Issue**: Missing dependencies +```bash +# Ensure all dependencies are installed +pnpm install + +# Check QuickJS and WASI-SDK are downloaded (CLI handles this) +``` + +### Runtime Errors + +**Issue**: Method not found +- Verify method is in `@Logic` class +- Check method name matches call +- Ensure method is public (not private) + +**Issue**: CRDT operations failing +- Verify CRDT is initialized inline +- Check you're using CRDT collections, not plain objects +- Ensure nested CRDTs are handled as handles + +**Issue**: Events not propagating +- Verify `@Event` decorator on event class +- Check event is emitted during method execution +- Ensure handlers are in `@Logic` class + +## Examples + +The `calimero-sdk-js` repository includes comprehensive examples: + +| Example | Demonstrates | Location | +| --- | --- | --- | +| **counter** | Basic Counter CRDT | `examples/counter` | +| **kv-store** | UnorderedMap + LwwRegister, events | `examples/kv-store` | +| **team-metrics** | Nested CRDTs, mergeable structs | `examples/team-metrics` | +| **private-data** | Private storage patterns | `examples/private-data` | +| **blobs** | Blob management | `examples/blobs` | +| **xcall** | Cross-context calls | `examples/xcall` | + +**Run an example:** +```bash +# Clone repository +git clone https://github.com/calimero-network/calimero-sdk-js +cd calimero-sdk-js + +# Run example workflow +cd examples/counter +merobox bootstrap run workflows/counter-js.yml --log-level=trace +``` + +## Comparison: JavaScript SDK vs Rust SDK + +| Feature | JavaScript SDK | Rust SDK | +| --- | --- | --- | +| **Language** | TypeScript/JavaScript | Rust | +| **Runtime** | QuickJS (in WASM) | Native WASM | +| **Build Size** | ~500KB (includes QuickJS) | ~100KB (optimized) | +| **Performance** | Slower (JS interpreter) | Faster (native code) | +| **Development** | Easier (familiar JS syntax) | More learning curve | +| **Type Safety** | TypeScript | Rust | +| **CRDT Collections** | Same API | Same API | + +**When to use JavaScript SDK:** +- Familiar with JavaScript/TypeScript +- Faster prototyping +- Less performance-critical applications +- Want to leverage existing JS libraries (via Rollup) + +**When to use Rust SDK:** +- Need maximum performance +- Already familiar with Rust +- Complex algorithms or computations +- Minimal binary size requirements + +## Deep Dives + +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 + +## Related Topics + +- [SDK Guide (Rust)](sdk-guide.md) - Building with Rust SDK +- [Applications](../core-concepts/applications.md) - Application architecture overview +- [Core Apps Examples](../examples/core-apps-examples.md) - Rust SDK examples +- [Build Your First Application](../getting-started/build-your-first-application.md) - Tutorial + diff --git a/mkdocs.yml b/mkdocs.yml index 5e37254..d538e7d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -93,6 +93,7 @@ nav: - Builder Directory: - Overview: builder-directory/index.md - SDK Guide: builder-directory/sdk-guide.md + - JavaScript SDK Guide: builder-directory/js-sdk-guide.md - Examples: - Overview: examples/index.md - Core Apps Examples: examples/core-apps-examples.md From 99df2cb3697ea53bb149122b09d7187c3ac7baf3 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 06:44:21 -0300 Subject: [PATCH 06/22] docs: Add comprehensive guide for all three client SDKs - Document Rust client SDK (core/crates/client) with trait-based design - Document Python client SDK (calimero-client-py) with PyO3 bindings - Document JavaScript client SDK (calimero-client-js) with full auth support - Note authentication status: Rust/Python not yet supported, JS has full support - Explain use cases: sidecar tools, developer tools, automation/CI - Include quick start examples, API usage patterns, error handling - Add comparison table and guidance for choosing the right SDK - Update Tools & APIs index with prominent link to new guide --- docs/tools-apis/client-sdks.md | 768 +++++++++++++++++++++++++++++++++ docs/tools-apis/index.md | 11 +- mkdocs.yml | 1 + 3 files changed, 777 insertions(+), 3 deletions(-) create mode 100644 docs/tools-apis/client-sdks.md diff --git a/docs/tools-apis/client-sdks.md b/docs/tools-apis/client-sdks.md new file mode 100644 index 0000000..2b98a2e --- /dev/null +++ b/docs/tools-apis/client-sdks.md @@ -0,0 +1,768 @@ +# Calimero Client SDKs + +Client SDKs for interacting with Calimero nodes programmatically. These SDKs provide programmatic access to Calimero's admin API, enabling you to build sidecar tools, developer utilities, monitoring scripts, and automation workflows. + +## Overview + +Calimero provides three client SDKs for different language ecosystems: + +| SDK | Language | Repository | Authentication Support | Primary Use Cases | +| --- | --- | --- | --- | --- | +| **Rust Client** | Rust | `core/crates/client` | ⚠️ Not yet supported | Sidecar tools, CLI utilities, developer tools | +| **Python Client** | Python | `calimero-client-py` | ⚠️ Not yet supported | Automation scripts, monitoring tools, developer tools | +| **JavaScript Client** | TypeScript/JavaScript | `calimero-client-js` | ✅ Full support | Web apps, browser extensions, Node.js tools | + +!!! warning "Authentication Status" + **Rust and Python clients do not currently support authentication.** Authentication support is planned for future releases. Current usage is intended for: + - **Sidecar tools** - Local services running alongside Calimero nodes + - **Developer tools** - Scripts and utilities for development/testing + - **Internal automation** - CI/CD pipelines and internal tooling + + **JavaScript client has full authentication support** including JWT token management, wallet-based authentication, and React components for user authentication flows. + +## Use Cases + +### Sidecar Tools + +Tools that run alongside Calimero nodes to provide additional functionality: + +- **Metrics collectors** - Export node metrics to Prometheus, DataDog, etc. +- **Log aggregators** - Process and forward node logs +- **Health checkers** - Monitor node health and alert on issues +- **Backup services** - Periodically backup node state +- **Monitoring dashboards** - Custom dashboards for node status + +### Developer Tools + +Utilities for development and testing: + +- **Test scripts** - Automated testing of Calimero applications +- **Deployment tools** - Scripts for deploying and managing applications +- **Debugging tools** - Utilities for inspecting node state +- **Development helpers** - Scaffolding and code generation tools + +### Automation & CI/CD + +Automated workflows for DevOps: + +- **CI pipelines** - Automated testing and deployment +- **Release automation** - Scripts for packaging and releasing +- **Health monitoring** - Automated health checks and alerts +- **Data migration** - Scripts for migrating data between nodes + +## Rust Client SDK + +The Rust client SDK (`core/crates/client`) provides a trait-based abstraction for interacting with Calimero nodes. It's designed for building command-line tools, sidecar services, and developer utilities. + +### Features + +- **Trait-based design** - Flexible authentication and storage backends +- **Async/await support** - Full async support with `tokio` +- **Comprehensive API** - Access to all Calimero admin endpoints +- **Error handling** - Robust error types and handling +- **Type safety** - Strongly typed with Rust's type system + +### Installation + +Add to your `Cargo.toml`: + +```toml +[dependencies] +calimero-client = { path = "../core/crates/client" } +# Or from crates.io (when published) +# calimero-client = "0.1.0" +``` + +### Quick Start + +```rust +use calimero_client::{create_connection, create_client, AuthMode, ConnectionInfo}; +use calimero_client::traits::{ClientAuthenticator, ClientStorage}; +use url::Url; + +#[tokio::main] +async fn main() -> eyre::Result<()> { + // Create connection + let api_url = Url::parse("http://localhost:2528")?; + let authenticator = CliAuthenticator::new(); + let storage = FileStorage::new(); + + let connection = ConnectionInfo::new( + api_url, + Some("node1".to_string()), + authenticator, + storage, + ); + + // Create client + let client = Client::new(connection)?; + + // List contexts + let contexts = client.list_contexts().await?; + println!("Found {} contexts", contexts.data.len()); + + // List applications + let apps = client.list_applications().await?; + println!("Found {} applications", apps.data.len()); + + Ok(()) +} +``` + +### Authentication + +!!! warning "Authentication Not Yet Supported" + The Rust client currently supports `AuthMode::None` only. Authentication support with JWT tokens is planned for a future release. + +```rust +use calimero_client::{AuthMode, ConnectionInfo}; + +// Currently only AuthMode::None is supported +let connection = ConnectionInfo::new( + api_url, + Some("node1".to_string()), + CliAuthenticator::new(), + FileStorage::new(), +); +``` + +### API Examples + +#### Context Management + +```rust +// List all contexts +let contexts = client.list_contexts().await?; + +// Get specific context +let context = client.get_context(&context_id).await?; + +// Create new context +let create_request = CreateContextRequest { + application_id: app_id, + protocol: "near".to_string(), + params: Some(json!({"network": "testnet"}).to_string()), +}; +let new_context = client.create_context(create_request).await?; + +// Delete context +client.delete_context(&context_id).await?; +``` + +#### Application Management + +```rust +// List applications +let apps = client.list_applications().await?; + +// Get application +let app = client.get_application(&app_id).await?; + +// Install development application +let install_request = InstallDevApplicationRequest { + path: "/path/to/app.wasm".to_string(), + metadata: None, +}; +client.install_dev_application(install_request).await?; + +// Uninstall application +client.uninstall_application(&app_id).await?; +``` + +#### Function Execution + +```rust +use calimero_client::client::Client; + +// Execute function via JSON-RPC +let result = client.execute_function( + &context_id, + "set_value", + r#"{"key": "test", "value": "hello"}"#, + &executor_public_key, +).await?; +``` + +#### Blob Management + +```rust +// Upload blob +let data = b"Hello, Calimero!".to_vec(); +let blob_info = client.upload_blob(data, Some(&context_id)).await?; + +// List blobs +let blobs = client.list_blobs().await?; + +// Get blob info +let info = client.get_blob_info(&blob_id).await?; + +// Delete blob +client.delete_blob(&blob_id).await?; +``` + +### Architecture + +The Rust client uses a trait-based design for flexibility: + +```rust +pub trait ClientAuthenticator { + async fn authenticate(&self, url: &Url) -> Result; + // ... +} + +pub trait ClientStorage { + async fn load_tokens(&self, node_name: &str) -> Result>; + async fn save_tokens(&self, node_name: &str, tokens: &JwtToken) -> Result<()>; + // ... +} + +pub struct Client +where + A: ClientAuthenticator, + S: ClientStorage, +{ + connection: ConnectionInfo, +} +``` + +This allows you to implement custom authenticators and storage backends for your specific use case. + +### Error Handling + +```rust +use calimero_client::errors::ClientError; + +match client.list_contexts().await { + Ok(response) => println!("Success: {:?}", response), + Err(ClientError::Network { message }) => { + eprintln!("Network error: {}", message); + } + Err(ClientError::Authentication { message }) => { + eprintln!("Auth error: {}", message); + } + Err(e) => eprintln!("Error: {:?}", e), +} +``` + +### 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) + +## Python Client SDK + +The Python client SDK (`calimero-client-py`) provides Python bindings built with PyO3 for high-performance integration with Calimero nodes. Perfect for automation scripts, monitoring tools, and developer utilities. + +### Features + +- **High performance** - Built with Rust and PyO3 for optimal performance +- **Comprehensive API** - Full access to Calimero Network functionality +- **Type safety** - Strongly typed Python bindings +- **Async support** - Built-in async/await support +- **Easy installation** - Simple `pip install` + +### Installation + +```bash +pip install calimero-client-py +``` + +### Quick Start + +```python +import asyncio +from calimero_client_py import create_connection, create_client, AuthMode + +async def main(): + # Create connection + connection = create_connection( + base_url="http://localhost:2528", + auth_mode=AuthMode.NONE # Authentication not yet supported + ) + + # Create client + client = create_client(connection) + + # List contexts + contexts = await client.list_contexts() + print(f"Found {len(contexts.data)} contexts") + + # List applications + apps = await client.list_applications() + print(f"Found {len(apps.data)} applications") + +if __name__ == "__main__": + asyncio.run(main()) +``` + +### Authentication + +!!! warning "Authentication Not Yet Supported" + The Python client currently supports `AuthMode.NONE` only. Authentication support with JWT tokens is planned for a future release. + +```python +from calimero_client_py import create_connection, AuthMode + +# Currently only AuthMode.NONE is supported +connection = create_connection( + base_url="http://localhost:2528", + auth_mode=AuthMode.NONE +) +``` + +### API Examples + +#### Context Management + +```python +# List all contexts +contexts = await client.list_contexts() + +# Get specific context +context = await client.get_context(context_id) + +# Create new context +context = await client.create_context( + application_id=app_id, + protocol="near", + params='{"network": "testnet"}' +) + +# Delete context +await client.delete_context(context_id) +``` + +#### Application Management + +```python +# List applications +apps = await client.list_applications() + +# Get application +app = await client.get_application(app_id) + +# Install development application +response = await client.install_dev_application( + path="/path/to/app.wasm", + metadata=None +) + +# Uninstall application +await client.uninstall_application(app_id) +``` + +#### Function Execution + +```python +# Execute function via JSON-RPC +result = await client.execute_function( + context_id=context_id, + method="set_value", + args='{"key": "test", "value": "hello"}', + executor_public_key=executor_public_key +) +``` + +#### Blob Management + +```python +# Upload blob +with open("file.dat", "rb") as f: + data = f.read() +blob_info = await client.upload_blob(data, context_id=context_id) + +# List blobs +blobs = await client.list_blobs() + +# Get blob info +info = await client.get_blob_info(blob_id) + +# Delete blob +await client.delete_blob(blob_id) +``` + +### Error Handling + +```python +from calimero_client_py import ClientError + +try: + contexts = await client.list_contexts() +except ClientError as e: + if e.error_type == "Network": + print(f"Network error: {e.message}") + elif e.error_type == "Authentication": + print(f"Auth error: {e.message}") + else: + print(f"Error: {e.message}") +``` + +### Development + +#### Building from Source + +```bash +# Install maturin +pip install maturin + +# Build the package +maturin build --release + +# Install in development mode +maturin develop +``` + +#### Running Tests + +```bash +# Test Python integration +python -m pytest tests/ + +# Test the environment +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) + +## JavaScript Client SDK + +The JavaScript client SDK (`calimero-client-js`) provides TypeScript/JavaScript bindings with full authentication support. Ideal for web applications, browser extensions, and Node.js tools. + +### Features + +- **Full authentication** - JWT token management, wallet-based auth, React components +- **Real-time updates** - WebSocket and SSE subscriptions +- **TypeScript support** - Full type definitions +- **React components** - Pre-built UI components for authentication +- **Browser & Node.js** - Works in both environments + +### Installation + +```bash +# npm +npm install @calimero-network/calimero-client + +# yarn +yarn add @calimero-network/calimero-client + +# pnpm +pnpm add @calimero-network/calimero-client +``` + +### Quick Start + +#### Basic Setup + +```typescript +import { + setAppEndpointKey, + setApplicationId, + JsonRpcClient, +} from '@calimero-network/calimero-client'; + +// Configure node URL and application ID +setAppEndpointKey('https://your-calimero-node-url.com'); +setApplicationId('your-application-id'); + +// Create RPC client +const rpcClient = new JsonRpcClient( + 'https://your-calimero-node-url.com', + '/jsonrpc' +); + +// Make a query +const response = await rpcClient.query({ + contextId: 'context-id', + method: 'get_value', + argsJson: { key: 'test' }, + executorPublicKey: 'public-key', +}); +``` + +#### Authentication Flow + +```typescript +import { ClientLogin, AccessTokenWrapper } from '@calimero-network/calimero-client'; + +// Use ClientLogin component for authentication +function LoginPage() { + const handleLoginSuccess = () => { + // Navigate to authenticated section + window.location.href = '/dashboard'; + }; + + return ; +} + +// Wrap your app with AccessTokenWrapper for automatic token management +function App() { + return ( + localStorage.getItem('node_url') || ''}> + + + ); +} +``` + +### Authentication + +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 +- **React components** - Pre-built UI components (`ClientLogin`, `SetupModal`) +- **Manual token handling** - Direct token management APIs + +#### Complete Authentication Flow + +```typescript +import { + SetupModal, + ClientLogin, + AccessTokenWrapper, +} from '@calimero-network/calimero-client'; + +// Step 1: Setup (configure node URL and application ID) +function SetupPage() { + const handleSetupComplete = () => { + navigate('/auth'); + }; + + return ; +} + +// Step 2: Authentication (user login) +function AuthPage() { + const handleLoginSuccess = () => { + navigate('/home'); + }; + + return ; +} + +// Step 3: App with automatic token management +function App() { + return ( + localStorage.getItem('node_url') || ''}> + + } /> + } /> + } /> + + + ); +} +``` + +#### Manual Token Usage + +```typescript +import { + setAccessToken, + getJWTObject, + JsonRpcClient, +} from '@calimero-network/calimero-client'; + +// Set your token +setAccessToken('your-jwt-token-here'); + +// Get contextId and executorPublicKey from the token +const jwt = getJWTObject(); +const contextId = jwt?.context_id; +const executorPublicKey = jwt?.executor_public_key; + +// Use the client +const rpcClient = new JsonRpcClient('your-api-url', '/jsonrpc'); +const response = await rpcClient.query({ + contextId, + method: 'your-method', + argsJson: { /* your args */ }, + executorPublicKey, +}); +``` + +### API Examples + +#### RPC Client + +```typescript +import { JsonRpcClient } from '@calimero-network/calimero-client'; + +const rpcClient = new JsonRpcClient( + process.env.NEXT_PUBLIC_API_URL, + '/jsonrpc' +); + +// Make a query (read-only) +const queryResponse = await rpcClient.query({ + contextId: 'context-id', + method: 'get_posts', + argsJson: { limit: 10 }, + executorPublicKey: 'public-key', +}); + +// Make a mutation (write operation) +const mutateResponse = await rpcClient.mutate({ + contextId: 'context-id', + method: 'create_post', + argsJson: { + title: 'My First Post', + text: 'This is my first post', + }, + executorPublicKey: 'public-key', +}); +``` + +#### WebSocket Subscriptions + +```typescript +import { WsSubscriptionsClient } from '@calimero-network/calimero-client'; + +const subscriptionsClient = new WsSubscriptionsClient( + process.env.NEXT_PUBLIC_API_URL, + '/ws' +); + +// Connect and subscribe +await subscriptionsClient.connect(); +subscriptionsClient.subscribe(['context-id']); + +// Handle incoming events +subscriptionsClient.addCallback((event) => { + console.log('Received event:', event); +}); + +// Clean up +subscriptionsClient.disconnect(); +``` + +#### SSE Subscriptions + +```typescript +import { SseSubscriptionsClient } from '@calimero-network/calimero-client'; + +const sseClient = new SseSubscriptionsClient( + process.env.NEXT_PUBLIC_API_URL, + '/sse' +); + +// Connect to SSE endpoint +await sseClient.connect(); +await sseClient.subscribe(['context-id']); + +// Handle incoming events +sseClient.addCallback((event) => { + console.log('Received SSE event:', event); +}); + +// Clean up +sseClient.disconnect(); +``` + +#### Admin API + +```typescript +import { apiClient } from '@calimero-network/calimero-client'; + +// List contexts +const contexts = await apiClient.node().getContexts(); + +// Create context +const newContext = await apiClient.node().createContext( + applicationId, + 'near' // protocol +); + +// List applications +const apps = await apiClient.node().getApplications(); + +// Get application +const app = await apiClient.node().getApplication(appId); +``` + +### Error Handling + +```typescript +try { + const response = await rpcClient.query(params); + if (response.error) { + // Handle RPC error + console.error('RPC Error:', response.error.message); + } else { + // Process successful response + console.log('Result:', response.result); + } +} catch (error) { + // Handle network or other errors + console.error('Request failed:', error); +} +``` + +### Best Practices + +1. **Token Management** + - Use `AccessTokenWrapper` for automatic token refresh + - Store sensitive information in environment variables + - Never expose tokens in client-side code + +2. **Connection Management** + - Always clean up WebSocket connections when done + - Use unique connection IDs for multiple connections + - Implement reconnection logic for production + +3. **Error Handling** + - Always check for errors in RPC responses + - Implement proper error boundaries in React + - Log errors appropriately for debugging + +### 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) + +## Comparison + +| Feature | Rust Client | Python Client | JavaScript Client | +| --- | --- | --- | --- | +| **Language** | Rust | Python | TypeScript/JavaScript | +| **Performance** | High (native) | High (Rust bindings) | Good (JavaScript) | +| **Authentication** | ⚠️ Not yet | ⚠️ Not yet | ✅ Full support | +| **Async Support** | ✅ Tokio | ✅ asyncio | ✅ Native | +| **Type Safety** | ✅ Rust types | ✅ Python types | ✅ TypeScript | +| **React Components** | ❌ | ❌ | ✅ | +| **WebSocket** | ✅ | ✅ | ✅ | +| **SSE** | ✅ | ✅ | ✅ | +| **Best For** | CLI tools, sidecars | Scripts, automation | Web apps, browsers | + +## Choosing the Right SDK + +**Choose Rust Client if:** +- Building command-line tools or sidecar services +- Need maximum performance +- Already using Rust in your stack +- Building developer utilities + +**Choose Python Client if:** +- Building automation scripts or monitoring tools +- Working with Python-based tooling +- Need quick prototyping +- Building CI/CD pipelines + +**Choose JavaScript Client if:** +- Building web applications or browser extensions +- Need authentication flows +- Want React components +- Building user-facing applications + +## Related Topics + +- [meroctl CLI](meroctl-cli.md) - Command-line interface for Calimero +- [Introduction](../intro/index.md) - Understanding Calimero's core concepts +- [Contexts](../core-concepts/contexts.md) - Working with contexts +- [Identity](../core-concepts/identity.md) - Authentication and identity management + diff --git a/docs/tools-apis/index.md b/docs/tools-apis/index.md index 613ee08..968ba0d 100644 --- a/docs/tools-apis/index.md +++ b/docs/tools-apis/index.md @@ -24,11 +24,16 @@ Use this directory as a jumping-off point; it shows you **what exists** and **wh ## SDKs & Clients +!!! tip "Client SDKs Guide" + For comprehensive documentation on all three client SDKs (Rust, Python, JavaScript), see the [Client SDKs Guide](client-sdks.md). + | SDK | Reference | Notes | | --- | --- | --- | -| JavaScript Client | [`calimero-network/calimero-client-js`](https://github.com/calimero-network/calimero-client-js#readme) | Browser/Node bindings, event streaming, auth helpers. | -| Python Client | [`calimero-network/calimero-client-py`](https://github.com/calimero-network/calimero-client-py#readme) | Python bindings, ABI tooling, automation recipes. | -| Rust SDK | [`calimero-network/core/calimero-sdk-js`](https://github.com/calimero-network/core/tree/main/calimero-sdk-js#readme) | App macros, storage primitives, state helpers. | +| 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. | ## Automation & Workflows diff --git a/mkdocs.yml b/mkdocs.yml index d538e7d..dcece55 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -128,6 +128,7 @@ nav: - Tools & APIs: - Overview: tools-apis/index.md - meroctl CLI: tools-apis/meroctl-cli.md + - Client SDKs: tools-apis/client-sdks.md - Support: - Overview: support/index.md - FAQ: support/faq.md From c2c342f80d494f03dfd786c9d51e1a9abd45ef80 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 06:50:44 -0300 Subject: [PATCH 07/22] docs: Add comprehensive guide for developer tools - Document Merobox for local multi-node networks and testing - Document ABI Codegen for generating TypeScript clients from Rust ABIs - Document create-mero-app for scaffolding new apps from kv-store boilerplate - Include quick start examples, workflow orchestration, testing support - Explain complete development workflow using all three tools together - Update Tools & APIs index with prominent link to new guide --- docs/tools-apis/developer-tools.md | 587 +++++++++++++++++++++++++++++ docs/tools-apis/index.md | 9 +- mkdocs.yml | 1 + 3 files changed, 595 insertions(+), 2 deletions(-) create mode 100644 docs/tools-apis/developer-tools.md diff --git a/docs/tools-apis/developer-tools.md b/docs/tools-apis/developer-tools.md new file mode 100644 index 0000000..19911c8 --- /dev/null +++ b/docs/tools-apis/developer-tools.md @@ -0,0 +1,587 @@ +# Calimero Developer Tools + +Developer tools for building, testing, and scaffolding Calimero applications locally. These tools streamline the development workflow from initial project setup to testing and deployment. + +## Overview + +| Tool | Purpose | Language | Installation | +| --- | --- | --- | --- | +| **Merobox** | Local multi-node networks, workflow orchestration, testing | Python | `pipx install merobox` or `brew install merobox` | +| **ABI Codegen** | Generate TypeScript clients from Rust application ABIs | TypeScript/Node.js | `npm install @calimero-network/abi-codegen` | +| **create-mero-app** | Scaffold new Calimero apps from kv-store boilerplate | TypeScript/Node.js | `npx create-mero-app@latest` | + +## Merobox + +Merobox is a Python CLI tool for managing Calimero nodes in Docker containers. It's essential for local development and testing, enabling you to spin up multi-node networks, execute complex workflows, and automate testing scenarios. + +### Features + +- **Node Management** - Start, stop, and monitor Calimero nodes in Docker +- **Multi-Node Networks** - Run multiple nodes locally for testing P2P synchronization +- **Workflow Orchestration** - Execute complex multi-step workflows with YAML files +- **Auth Service Integration** - Traefik proxy and authentication service with nip.io DNS +- **Context Management** - Create and manage blockchain contexts +- **Identity Management** - Generate and manage cryptographic identities +- **Function Calls** - Execute smart contract functions via JSON-RPC +- **Testing Support** - Python testing fixtures for integration tests + +### Installation + +**Option 1: Using pipx (recommended)** + +```bash +pipx install merobox +``` + +**Option 2: Using Homebrew** + +```bash +brew install merobox +``` + +**Option 3: From source** + +```bash +git clone https://github.com/calimero-network/merobox.git +cd merobox +pipx install -e . +``` + +### Quick Start + +#### Basic Node Management + +```bash +# Start a single Calimero node +merobox run --name my-node + +# Start multiple nodes +merobox run --count 2 + +# Start with custom ports +merobox run --name my-node --server-port 2428 --swarm-port 2528 + +# List running nodes +merobox list + +# Check node health +merobox health my-node + +# View node logs +merobox logs my-node --follow + +# Stop a node +merobox stop my-node + +# Remove all node data (destructive!) +merobox nuke my-node +``` + +#### Application Management + +```bash +# Install a WASM application on a node +merobox install my-node /path/to/app.wasm + +# Call a function on an installed application +merobox call my-node '{"arg": "value"}' +``` + +#### Identity & Context Management + +```bash +# Create a new identity +merobox identity create + +# Create a new context +merobox context create my-node + +# Join a node to a context +merobox join my-node +``` + +### Workflow Orchestration + +Merobox supports complex multi-step workflows defined in YAML files: + +```yaml +# workflow.yml +image: "ghcr.io/calimero-network/merod:edge" + +nodes: + count: 2 + prefix: "calimero-node" + +steps: + - name: "Create identities" + type: identity + identity: "alice" + + - name: "Create context" + type: context + application_id: "my-app" + protocol: "near" + params: '{"network": "testnet"}' + + - name: "Install application" + type: install + node: "calimero-node-1" + path: "./app.wasm" + + - name: "Execute function" + type: execute + node: "calimero-node-1" + context_id: "{{ steps.create_context.context_id }}" + method: "set_value" + args: '{"key": "test", "value": "hello"}' + executor_public_key: "{{ steps.create_identities.alice.public_key }}" +``` + +**Execute a workflow:** + +```bash +merobox bootstrap run workflow.yml +``` + +**Workflow steps:** +- `identity` - Create cryptographic identities +- `context` - Create blockchain contexts +- `install` - Install WASM applications +- `execute` - Execute function calls +- `join` - Join contexts +- `invite_open` - Create open invitations +- `join_open` - Join via open invitation +- `wait` - Wait for conditions +- `assert` - Assert expected results +- `repeat` - Repeat steps multiple times +- `script` - Execute shell scripts + +### Auth Service Integration + +Merobox can integrate with authentication services using Traefik proxy: + +```bash +# Start nodes with auth service +merobox run --auth-service --count 2 +``` + +This automatically: +- Starts Traefik proxy (`traefik:v2.10`) +- Starts auth service (`ghcr.io/calimero-network/calimero-auth:latest`) +- Creates Docker networks (`calimero_web`, `calimero_internal`) +- Configures nip.io DNS resolution +- Sets up forward authentication middleware + +**Access patterns:** +- Node 1 API: `http://calimero-node-1.127.0.0.1.nip.io/jsonrpc` (protected) +- Node 1 Dashboard: `http://calimero-node-1.127.0.0.1.nip.io/admin-dashboard` (public) +- Auth Service: `http://localhost/auth/` (authentication endpoints) + +### Testing Support + +Merobox provides Python testing fixtures for integration tests: + +```python +from merobox.testing import cluster + +# Context manager +with cluster(count=2, prefix="ci") as env: + node1 = env.nodes[0] + node2 = env.nodes[1] + + # Use nodes in your tests + response = await client.list_contexts(node1) + assert len(response.data) == 0 + +# Pytest fixture +import pytest +from merobox.testing import cluster_fixture + +@pytest.fixture(scope="session") +def calimero_cluster(cluster_fixture): + yield cluster_fixture(count=3, prefix="test") + +def test_my_app(calimero_cluster): + node = calimero_cluster.nodes[0] + # Run your tests +``` + +### Use Cases + +- **Local Development** - Spin up local nodes for development and testing +- **Integration Testing** - Multi-node test scenarios with automated workflows +- **CI/CD Pipelines** - Automated testing in CI environments +- **Demo Environments** - Quick setup for demonstrations +- **Network Simulation** - Test P2P synchronization with multiple nodes + +### 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) + +## ABI Codegen + +ABI Codegen (`@calimero-network/abi-codegen`) generates TypeScript client code and type definitions from Rust application ABI manifests. It parses WASM-ABI v1 manifest files and generates fully-typed TypeScript clients for interacting with your Calimero applications. + +### Features + +- **TypeScript Generation** - Fully-typed client classes and type definitions +- **WASM-ABI v1 Support** - Parses standard ABI manifest format +- **Method Generation** - Generates methods for all Rust functions +- **Event Types** - Generates TypeScript types for events +- **Error Types** - Generates error types for method errors +- **CLI & Programmatic** - Use as CLI tool or import programmatically + +### Installation + +```bash +npm install @calimero-network/abi-codegen +``` + +### Quick Start + +#### CLI Usage + +```bash +# Basic usage +npx calimero-abi-codegen -i abi.json -o src + +# With custom client name +npx calimero-abi-codegen -i abi.json -o src --client-name MyClient + +# Validate ABI manifest only (no code generation) +npx calimero-abi-codegen --validate -i abi.json + +# Derive client name from WASM file +npx calimero-abi-codegen -i abi.json -o src --name-from kv_store.wasm +``` + +#### CLI Options + +- `-i, --input ` - Input ABI JSON file (default: `abi.json`) +- `-o, --outDir ` - Output directory for generated files (default: `src`) +- `--client-name ` - Custom client class name (default: `Client`) +- `--name-from ` - Derive client name from file path (e.g., WASM file) +- `--import-path ` - Custom import path for CalimeroApp and Context (default: `@calimero-network/calimero-client`) +- `--validate` - Validate ABI manifest only (no code generation) +- `-h, --help` - Show help message + +### Programmatic Usage + +```typescript +import { loadAbiManifestFromFile } from '@calimero-network/abi-codegen/parse'; +import { generateTypes } from '@calimero-network/abi-codegen/generate/types'; +import { generateClient } from '@calimero-network/abi-codegen/generate/client'; + +// Load ABI manifest +const manifest = loadAbiManifestFromFile('./abi.json'); + +// Generate TypeScript types +const typesContent = generateTypes(manifest); + +// Generate client class +const clientContent = generateClient(manifest, 'MyClient'); + +// Write to files +await fs.writeFile('src/types.ts', typesContent); +await fs.writeFile('src/MyClient.ts', clientContent); +``` + +### Generated Files + +ABI Codegen generates two files: + +1. **types.ts** - TypeScript type definitions for all types, events, and errors +2. **{ClientName}.ts** - Client class with methods for all Rust functions + +#### Example Generated Client + +```typescript +import { CalimeroApp, Context } from '@calimero-network/calimero-client'; + +// Generated types +export interface SetValueArgs { + key: string; + value: string; +} + +export interface GetValueArgs { + key: string; +} + +export interface ItemAddedEvent { + key: string; + value: string; + timestamp: number; +} + +// Generated client +export class KvStoreClient { + constructor( + private app: CalimeroApp, + private context: Context + ) {} + + async setValue(args: SetValueArgs): Promise { + await this.app.mutate({ + contextId: this.context.id, + method: 'set_value', + argsJson: args, + executorPublicKey: this.context.executorPublicKey, + }); + } + + async getValue(args: GetValueArgs): Promise { + const response = await this.app.query({ + contextId: this.context.id, + method: 'get_value', + argsJson: args, + executorPublicKey: this.context.executorPublicKey, + }); + return response.result as string | null; + } +} +``` + +### ABI Manifest Format + +ABI manifests follow the WASM-ABI v1 specification: + +```json +{ + "version": "1", + "methods": [ + { + "name": "set_value", + "args": { + "key": "string", + "value": "string" + }, + "returns": null, + "errors": [] + }, + { + "name": "get_value", + "args": { + "key": "string" + }, + "returns": "string | null", + "errors": [] + } + ], + "events": [ + { + "name": "ItemAdded", + "payload": { + "key": "string", + "value": "string", + "timestamp": "number" + } + } + ], + "types": { + "SetValueArgs": { + "fields": { + "key": "string", + "value": "string" + } + } + } +} +``` + +### Integration with Build Process + +Add to your `package.json`: + +```json +{ + "scripts": { + "generate:client": "calimero-abi-codegen -i abi.json -o src/generated", + "build": "npm run generate:client && npm run build:app" + } +} +``` + +### Use Cases + +- **Type Safety** - End-to-end type safety from Rust to TypeScript +- **API Generation** - Automatic client generation from Rust applications +- **Developer Experience** - Auto-complete and type checking in IDEs +- **Documentation** - Types serve as documentation for your API + +### 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) + +## create-mero-app + +`create-mero-app` scaffolds new Calimero applications by cloning the `kv-store` example repository and copying its files (excluding Git artifacts). It provides a ready-to-use boilerplate for building new Calimero applications. + +### Features + +- **Quick Scaffolding** - Generate new apps in seconds +- **kv-store Boilerplate** - Based on the proven kv-store example +- **Clean Output** - Excludes Git artifacts and node_modules +- **Package Name Setup** - Automatically configures package.json name + +### Installation + +No installation required - use via `npx`: + +```bash +npx create-mero-app@latest my-app +``` + +### Quick Start + +```bash +# Create a new app +npx create-mero-app@latest my-kv-store + +# Navigate to the new app +cd my-kv-store + +# Install dependencies +pnpm install + +# Build the WASM application +cd logic +chmod +x ./build.sh +./build.sh + +# Start the frontend +cd ../app +pnpm build +pnpm dev +``` + +### What Gets Generated + +The tool clones the [`calimero-network/kv-store`](https://github.com/calimero-network/kv-store) repository and copies: + +- **Rust Application** (`logic/`) - WASM application with CRDT state +- **React Frontend** (`app/`) - React application with TypeScript +- **Build Scripts** - Build scripts for Rust and TypeScript +- **Configuration** - TypeScript config, package.json, etc. +- **Workflows** (`workflows/`) - Merobox workflows for local testing + +**Excluded:** +- `.git/` and `.github/` - Git artifacts +- `node_modules/` - Dependencies (installed via `pnpm install`) + +### Project Structure + +``` +my-kv-store/ +├── logic/ # Rust WASM application +│ ├── src/ +│ │ └── lib.rs # Main application logic +│ ├── Cargo.toml +│ └── build.sh # Build script +├── app/ # React frontend +│ ├── src/ +│ │ └── App.tsx # Main React component +│ ├── package.json +│ └── vite.config.ts +├── workflows/ # Merobox workflows +│ └── local-network.yml +├── package.json # Root package.json +└── README.md +``` + +### Customization + +After scaffolding, customize your app: + +1. **Update Application Logic** - Modify `logic/src/lib.rs` with your business logic +2. **Update Frontend** - Modify `app/src/App.tsx` with your UI +3. **Update Package Names** - Update `package.json` files with your project name +4. **Add Dependencies** - Install additional npm/Rust packages as needed + +### Next Steps + +1. **Build the WASM** - Compile Rust 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` +5. **Deploy** - Deploy your WASM to Calimero nodes and host your frontend + +### Use Cases + +- **Quick Prototyping** - Rapidly scaffold new application ideas +- **Learning** - Start with a working example to understand Calimero +- **Boilerplate** - Base template for new applications +- **Development** - Ready-to-use development environment + +### 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) + +## Complete Development Workflow + +A typical development workflow using all three tools: + +### 1. Scaffold New Application + +```bash +npx create-mero-app@latest my-app +cd my-app +pnpm install +``` + +### 2. Build and Test Locally + +```bash +# Build WASM application +cd logic +chmod +x ./build.sh +./build.sh + +# Generate TypeScript client from ABI +cd .. +npx calimero-abi-codegen -i abi.json -o app/src/generated + +# Start local network with Merobox +merobox bootstrap run workflows/local-network.yml +``` + +### 3. Develop and Iterate + +```bash +# Start frontend dev server +cd app +pnpm dev + +# Make changes to Rust logic, rebuild +cd ../logic +./build.sh + +# Regenerate TypeScript client +cd .. +npx calimero-abi-codegen -i abi.json -o app/src/generated +``` + +### 4. Test Workflow + +```bash +# Run Merobox workflow for testing +merobox bootstrap run workflows/test-workflow.yml + +# Or use Merobox in Python tests +python -m pytest tests/ +``` + +## Related Topics + +- [Client SDKs](client-sdks.md) - Client libraries for interacting with nodes +- [meroctl CLI](meroctl-cli.md) - Command-line interface for node management +- [SDK Guide](../builder-directory/sdk-guide.md) - Building Calimero applications +- [Core Apps Examples](../examples/core-apps-examples.md) - Reference implementations + diff --git a/docs/tools-apis/index.md b/docs/tools-apis/index.md index 968ba0d..8790f39 100644 --- a/docs/tools-apis/index.md +++ b/docs/tools-apis/index.md @@ -15,10 +15,15 @@ Use this directory as a jumping-off point; it shows you **what exists** and **wh ## Developer Tooling +!!! tip "Developer Tools Guide" + For comprehensive documentation on Merobox, ABI Codegen, and create-mero-app, see the [Developer Tools Guide](developer-tools.md). + | Tool | Reference | Notes | | --- | --- | --- | -| Merobox | [`calimero-network/merobox`](https://github.com/calimero-network/merobox#readme) | Docker workflows for local multi-node networks and Application ID capture. | -| Mero Devtools JS | [`calimero-network/mero-devtools-js`](https://github.com/calimero-network/mero-devtools-js#readme) | Scaffolds, ABI generators, TypeScript helpers. | +| 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. | diff --git a/mkdocs.yml b/mkdocs.yml index dcece55..97cd39f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -129,6 +129,7 @@ nav: - Overview: tools-apis/index.md - meroctl CLI: tools-apis/meroctl-cli.md - Client SDKs: tools-apis/client-sdks.md + - Developer Tools: tools-apis/developer-tools.md - Support: - Overview: support/index.md - FAQ: support/faq.md From 77003faa7caff60852ec0d49606361a6400a3c27 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 06:52:52 -0300 Subject: [PATCH 08/22] fix: Add Mermaid diagram support and convert ASCII diagrams - Add mkdocs-mermaid2-plugin to requirements.txt - Configure Mermaid plugin in mkdocs.yml with theme settings - Update markdown extensions to properly handle Mermaid code blocks - Convert ASCII box diagrams in js-sdk-guide.md to Mermaid diagrams: - Build pipeline: Converted to Mermaid flowchart - Runtime execution: Converted to Mermaid graph with subgraphs - Mermaid diagrams in architecture.md and applications.md will now render properly - ASCII tree structures remain as-is (they render correctly in markdown) --- docs/builder-directory/js-sdk-guide.md | 122 +++++++++++++------------ mkdocs.yml | 44 ++++++++- requirements.txt | 3 + 3 files changed, 109 insertions(+), 60 deletions(-) diff --git a/docs/builder-directory/js-sdk-guide.md b/docs/builder-directory/js-sdk-guide.md index e44d0e7..32e8a53 100644 --- a/docs/builder-directory/js-sdk-guide.md +++ b/docs/builder-directory/js-sdk-guide.md @@ -22,69 +22,73 @@ The JavaScript SDK (`calimero-sdk-js`) consists of two main packages: ### Build Pipeline -``` -TypeScript Source - ↓ - [TypeScript Compiler] - ↓ - JavaScript (ES6 modules) - ↓ - [Rollup] Bundle with dependencies - ↓ - JavaScript Bundle - ↓ - [QuickJS qjsc] Compile to C bytecode - ↓ - code.h (C header) - ↓ - [Extract Methods] Parse AST - ↓ - methods.h (C header) - ↓ - [Clang/WASI-SDK] Compile to WASM - ↓ - WASM Binary - ↓ - [wasi-stub + wasm-opt] Optimize - ↓ - Final Service (~500KB) +```mermaid +flowchart TD + TS[TypeScript Source] + TC[TypeScript Compiler] + JS[JavaScript ES6 modules] + ROLLUP[Rollup Bundle with dependencies] + BUNDLE[JavaScript Bundle] + QJSC[QuickJS qjsc Compile to C bytecode] + CODEH[code.h C header] + EXTRACT[Extract Methods Parse AST] + METHODS[methods.h C header] + CLANG[Clang/WASI-SDK Compile to WASM] + WASM[WASM Binary] + OPT[wasi-stub + wasm-opt Optimize] + FINAL[Final Service ~500KB] + + TS --> TC + TC --> JS + JS --> ROLLUP + ROLLUP --> BUNDLE + BUNDLE --> QJSC + QJSC --> CODEH + CODEH --> EXTRACT + EXTRACT --> METHODS + METHODS --> CLANG + CLANG --> WASM + WASM --> OPT + OPT --> FINAL + + style TS fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style FINAL fill:#c8e6c9,stroke:#388e3c,stroke-width:3px ``` ### Runtime Execution -``` -┌─────────────────────────────────────────┐ -│ JavaScript Application │ -│ (Your code with decorators) │ -└──────────────┬──────────────────────────┘ - │ -┌──────────────┴──────────────────────────┐ -│ @calimero/sdk │ -│ - Decorators (@State, @Logic, etc.) │ -│ - CRDT Collections │ -│ - Event System │ -└──────────────┬──────────────────────────┘ - │ -┌──────────────┴──────────────────────────┐ -│ QuickJS Runtime (in WASM) │ -│ - JavaScript interpreter │ -│ - ~450KB overhead │ -└──────────────┬──────────────────────────┘ - │ -┌──────────────┴──────────────────────────┐ -│ Calimero Host Functions │ -│ (calimero-sys) │ -│ - storage_read/write │ -│ - emit/commit │ -│ - context_id/executor_id │ -└──────────────┬──────────────────────────┘ - │ -┌──────────────┴──────────────────────────┐ -│ Calimero Runtime (Wasmer) │ -│ - WASM execution │ -│ - P2P synchronization │ -│ - Storage (RocksDB) │ -└─────────────────────────────────────────┘ +```mermaid +graph TB + subgraph "JavaScript Application" + JS[Your code with decorators] + end + + subgraph "@calimero/sdk" + SDK[Decorators, CRDT Collections, Event System] + end + + subgraph "QuickJS Runtime (in WASM)" + QJS[JavaScript interpreter
~450KB overhead] + end + + subgraph "Calimero Host Functions" + HOST[storage_read/write
emit/commit
context_id/executor_id] + end + + subgraph "Calimero Runtime (Wasmer)" + RUNTIME[WASM execution
P2P synchronization
Storage RocksDB] + end + + JS --> SDK + SDK --> QJS + QJS --> HOST + HOST --> RUNTIME + + style JS fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style SDK fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px + style QJS fill:#fff3e0,stroke:#e65100,stroke-width:2px + style HOST fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style RUNTIME fill:#fce4ec,stroke:#c2185b,stroke-width:2px ``` **How it works:** diff --git a/mkdocs.yml b/mkdocs.yml index 97cd39f..1028392 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,6 +61,44 @@ theme: # Plugins (install with: pip install ) plugins: - search # Built-in search functionality + - mermaid2: # Mermaid diagram support + arguments: + theme: "default" + themeVariables: + primaryColor: "#ffffff" + primaryTextColor: "#000000" + primaryBorderColor: "#000000" + lineColor: "#000000" + secondaryColor: "#f5f5f5" + tertiaryColor: "#e0e0e0" + background: "#ffffff" + mainBkg: "#ffffff" + secondBkg: "#f5f5f5" + textColor: "#000000" + noteBkgColor: "#fff9c4" + noteTextColor: "#000000" + noteBorderColor: "#ffd700" + actorBorder: "#000000" + actorBkg: "#ffffff" + actorTextColor: "#000000" + actorLineColor: "#000000" + signalColor: "#000000" + signalTextColor: "#000000" + labelBoxBkgColor: "#ffffff" + labelBoxBorderColor: "#000000" + labelTextColor: "#000000" + loopTextColor: "#000000" + activationBorderColor: "#000000" + activationBkgColor: "#f5f5f5" + sequenceNumberColor: "#000000" + sectionBkgColor: "#ffffff" + altBkgColor: "#f5f5f5" + clusterBkg: "#ffffff" + clusterBorder: "#000000" + defaultLinkColor: "#1976d2" + titleColor: "#000000" + edgeLabelBackground: "#ffffff" + labelBackground: "#ffffff" # Custom CSS for branding and logo switching extra_css: @@ -153,7 +191,11 @@ markdown_extensions: anchor_linenums: true - pymdownx.inlinehilite - pymdownx.snippets - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true - admonition diff --git a/requirements.txt b/requirements.txt index a2eea5e..7e90642 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,3 +4,6 @@ mkdocs-material>=9.5.0 # Markdown extensions pymdown-extensions>=10.0 + +# Mermaid diagrams +mkdocs-mermaid2-plugin>=1.0.0 From b802755a606950a326cb4a9a9d978da7fdea7730 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 06:54:58 -0300 Subject: [PATCH 09/22] fix: Correct broken internal links - Fix core-apps-examples.md link in builder-directory/sdk-guide.md - Fix getting-started link in core-concepts/applications.md - Fix operator-track links in core-concepts/nodes.md - All links now use correct relative paths --- docs/builder-directory/sdk-guide.md | 2 +- docs/core-concepts/applications.md | 2 +- docs/core-concepts/nodes.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/builder-directory/sdk-guide.md b/docs/builder-directory/sdk-guide.md index 3703385..a8de8bf 100644 --- a/docs/builder-directory/sdk-guide.md +++ b/docs/builder-directory/sdk-guide.md @@ -422,5 +422,5 @@ For detailed SDK documentation: - [Build Your First Application](../getting-started/build-your-first-application.md) - Step-by-step tutorial - [Applications](../core-concepts/applications.md) - Application architecture overview -- [Core Apps Examples](./core-apps-examples.md) - Reference implementations +- [Core Apps Examples](../examples/core-apps-examples.md) - Reference implementations diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index 9377101..44d66a6 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -239,6 +239,6 @@ For detailed application development: ## Related Topics -- [Build Your First Application](getting-started/build-your-first-application.md) - Step-by-step guide +- [Build Your First Application](../getting-started/build-your-first-application.md) - Step-by-step guide - [Contexts](contexts.md) - Application instances - [Architecture Overview](architecture.md) - How applications fit into the system diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md index e1aacec..55dc901 100644 --- a/docs/core-concepts/nodes.md +++ b/docs/core-concepts/nodes.md @@ -149,7 +149,7 @@ Key metrics and logs: - **Performance**: Delta application latency, sync duration, memory usage - **Events**: Event handler execution, errors, warnings -See [Monitor & Debug](operator-track/monitor-and-debug.md) for detailed guidance. +See [Monitor & Debug](../operator-track/monitor-and-debug.md) for detailed guidance. ## Configuration @@ -169,6 +169,6 @@ For detailed node documentation: ## Related Topics -- [Run a Local Network](operator-track/run-a-local-network.md) - Getting started with nodes +- [Run a Local Network](../operator-track/run-a-local-network.md) - Getting started with nodes - [Architecture Overview](architecture.md) - How nodes fit into the system - [Contexts](contexts.md) - Application instances managed by nodes From 5dfdbd5588d13fc0577050fd0ea35f7b8a995bfe Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:13:03 -0300 Subject: [PATCH 10/22] docs: Restructure navigation and add visual diagrams - Simplify navigation: remove Support section, consolidate structure - Add Mermaid diagrams to core concepts: - Core concepts relationship diagram - Context lifecycle state diagram - Context state isolation diagram - Update links to reference actual pages instead of placeholders - Clean up navigation structure for better human flow --- docs/core-concepts/contexts.md | 82 +++++++++++++++++++--------------- docs/core-concepts/index.md | 45 ++++++++++--------- docs/getting-started/index.md | 2 +- mkdocs.yml | 67 ++++++++------------------- 4 files changed, 90 insertions(+), 106 deletions(-) diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index e5c5035..00d12d5 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -13,18 +13,35 @@ Contexts provide: ## Context Lifecycle +```mermaid +stateDiagram-v2 + [*] --> Created: Install App + Created --> Invited: Invite Members + Invited --> Joined: Accept Invitation + Joined --> Active: Start Using + Active --> [*]: Delete Context + + note right of Created + - WASM installed + - State initialized + - Creator = first member + end note + + note right of Invited + - Invitation sent + - Permissions set + end note + + note right of Active + - Members can call methods + - State syncs across nodes + - Events propagate + end note +``` + ### 1. Creation -A context is created when an application is installed and initialized: - -```bash -# Install application -meroctl app install --path app.wasm --context-id - -# Create context (happens automatically on first install) -# Or create explicitly: -meroctl context create --application-id --protocol near -``` +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. **What happens:** - Application WASM is installed on the node @@ -79,31 +96,24 @@ Context members have different permission levels: ## State Isolation Model -Each context maintains completely isolated state: - -``` -┌─────────────────────────────────────────────────┐ -│ Context A │ -│ ┌──────────────────────────────────────────┐ │ -│ │ Shared CRDT State │ │ -│ │ - UnorderedMap │ │ -│ │ - Vector │ │ -│ │ - Counter │ │ -│ └──────────────────────────────────────────┘ │ -│ ┌──────────────────────────────────────────┐ │ -│ │ Private Storage (per-node) │ │ -│ │ - Node-local secrets │ │ -│ │ - Cached data │ │ -│ └──────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────┘ - -┌─────────────────────────────────────────────────┐ -│ Context B (completely separate) │ -│ ┌──────────────────────────────────────────┐ │ -│ │ Shared CRDT State │ │ -│ │ - Different data, different members │ │ -│ └──────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────┘ +```mermaid +graph TB + subgraph "Context A" + CRDT1[Shared CRDT State
UnorderedMap, Vector, Counter
Replicated across nodes] + PRIVATE1[Private Storage
Node-local secrets
Never synced] + end + + subgraph "Context B" + CRDT2[Shared CRDT State
Different data
Different members] + PRIVATE2[Private Storage
Node-local only] + end + + CRDT1 -.->|isolated| CRDT2 + + style CRDT1 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style CRDT2 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px + style PRIVATE1 fill:#fff3e0,stroke:#e65100,stroke-width:2px + style PRIVATE2 fill:#fff3e0,stroke:#e65100,stroke-width:2px ``` **Key points:** @@ -111,6 +121,8 @@ Each context maintains completely isolated state: - **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. + ## Multi-Chain Integration Contexts can be associated with blockchain protocols: diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md index 23bd13e..f974297 100644 --- a/docs/core-concepts/index.md +++ b/docs/core-concepts/index.md @@ -89,26 +89,26 @@ The **Architecture Overview** explains how all components work together: ## How Concepts Relate -``` -┌─────────────────────────────────────────────────┐ -│ Node (merod) │ -│ ┌──────────────────────────────────────────┐ │ -│ │ Context A │ │ -│ │ ┌────────────────────────────────────┐ │ │ -│ │ │ Application (WASM) │ │ │ -│ │ │ - CRDT State │ │ │ -│ │ │ - Events │ │ │ -│ │ └────────────────────────────────────┘ │ │ -│ │ ┌────────────────────────────────────┐ │ │ -│ │ │ Members (Identities) │ │ │ -│ │ │ - Root Key: alice.near │ │ │ -│ │ │ - Client Key: ed25519:abc... │ │ │ -│ │ └────────────────────────────────────┘ │ │ -│ └──────────────────────────────────────────┘ │ -│ ┌──────────────────────────────────────────┐ │ -│ │ Context B (separate instance) │ │ -│ └──────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────┘ +```mermaid +graph TB + subgraph "Node (merod)" + subgraph "Context A" + APP1[Application WASM
CRDT State + Events] + MEMBERS1[Members Identities
Root Key: alice.near
Client Key: ed25519...] + end + subgraph "Context B" + APP2[Application WASM
CRDT State + Events] + MEMBERS2[Members Identities
Root Key: bob.near
Client Key: ed25519...] + end + end + + APP1 -.->|isolated state| APP2 + MEMBERS1 -.->|separate access| MEMBERS2 + + style APP1 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style APP2 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px + style MEMBERS1 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px + style MEMBERS2 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px ``` ## Learning Path @@ -129,8 +129,9 @@ The **Architecture Overview** explains how all components work together: **Need to operate?** See: -- [Operator Track](../operator-track/index.md) - Running and managing nodes -- [Reference](../reference/index.md) - API documentation +- [Running Nodes](../operator-track/run-a-local-network.md) - Setup and deployment +- [Monitoring](../operator-track/monitor-and-debug.md) - Observability +- [API Reference](../reference/http-methods.md) - HTTP endpoints --- diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 1e2dcf1..8efd5ba 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -112,7 +112,7 @@ After completing the getting started guide: - **[Architecture Overview](../core-concepts/architecture.md)** - How it all works - **[Privacy & Security](../privacy-verifiability-security/index.md)** - Security model -- **[Support](../support/index.md)** - Get help and contribute +- **[GitHub Discussions](https://github.com/calimero-network/core/discussions)** - Get help and contribute ## Common Questions diff --git a/mkdocs.yml b/mkdocs.yml index 1028392..1fa3dca 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,60 +120,31 @@ extra_javascript: # Navigation structure nav: - Home: index.md - - Introduction: intro/index.md - - Build: - - Getting Started: - - Overview: getting-started/index.md - - Installation Checklist: getting-started/installation-checklist.md - - Launch Your First Context: getting-started/launch-your-first-context.md - - Build Your First Application: getting-started/build-your-first-application.md - - Sample App Walkthrough: getting-started/sample-app-walkthrough.md - - Builder Directory: - - Overview: builder-directory/index.md - - SDK Guide: builder-directory/sdk-guide.md - - JavaScript SDK Guide: builder-directory/js-sdk-guide.md - - Examples: - - Overview: examples/index.md - - Core Apps Examples: examples/core-apps-examples.md - - Battleships: examples/battleships.md - - Shared Todo Backlog: examples/shared-todo-backlog.md - - Split Bills: examples/split-bills.md - - Additional Templates: examples/additional-templates.md + - Quick Start: getting-started/index.md - Learn: - - Core Concepts: - - Overview: core-concepts/index.md - - Contexts: core-concepts/contexts.md - - Identity: core-concepts/identity.md - - Applications: core-concepts/applications.md - - Nodes: core-concepts/nodes.md - - Architecture Overview: core-concepts/architecture.md - - Privacy, Verifiability & Security: privacy-verifiability-security/index.md + - Core Concepts: core-concepts/index.md + - Architecture: core-concepts/architecture.md + - Applications: core-concepts/applications.md + - Contexts: core-concepts/contexts.md + - Identity: core-concepts/identity.md + - Nodes: core-concepts/nodes.md + - Build: + - Overview: builder-directory/index.md + - Rust SDK: builder-directory/sdk-guide.md + - JavaScript SDK: builder-directory/js-sdk-guide.md + - Examples: examples/index.md - Operate: - - Operator Track: - - Overview: operator-track/index.md - - Run a Local Network: operator-track/run-a-local-network.md - - Join Existing Contexts: operator-track/join-existing-contexts.md - - Monitor & Debug: operator-track/monitor-and-debug.md - - Production Deployment Notes: operator-track/production-deployment-notes.md - - Reference: - - Overview: reference/index.md - - Commitments & Consistency: reference/commitments-consistency.md - - Response Envelope: reference/response-envelope.md - - HTTP Methods: reference/http-methods.md - - WebSocket Streams: reference/websocket-streams.md - - Error Codes & Retries: reference/error-codes.md - - Versioning & Changelog: reference/versioning-changelog.md + - Running Nodes: operator-track/run-a-local-network.md + - Monitoring: operator-track/monitor-and-debug.md - Tools & APIs: - Overview: tools-apis/index.md - - meroctl CLI: tools-apis/meroctl-cli.md + - CLI (meroctl): tools-apis/meroctl-cli.md - Client SDKs: tools-apis/client-sdks.md - Developer Tools: tools-apis/developer-tools.md - - Support: - - Overview: support/index.md - - FAQ: support/faq.md - - Contact Channels: support/contact-channels.md - - Contribution Guide: support/contribution-guide.md - - Roadmap & Feedback: support/roadmap-feedback.md + - Reference: + - API Methods: reference/http-methods.md + - WebSocket: reference/websocket-streams.md + - Error Codes: reference/error-codes.md # Extra configuration extra: From 3484893d793db043e843a86b747892d5e4c90266 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:13:57 -0300 Subject: [PATCH 11/22] docs: Add visual diagrams and make content more concise - Add hierarchical identity model diagram - Make Applications page more concise with README references - Convert ASCII diagrams to Mermaid in core concepts - Add more visual diagrams throughout documentation --- docs/core-concepts/applications.md | 33 +++++++----------------------- docs/core-concepts/identity.md | 24 +++++++++++++++++----- 2 files changed, 26 insertions(+), 31 deletions(-) diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index 44d66a6..56e1a08 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -13,47 +13,28 @@ 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. + +**Minimal example:** + ```rust use calimero_sdk::app; use calimero_storage::collections::UnorderedMap; #[app::state] -#[derive(BorshSerialize, BorshDeserialize)] pub struct MyApp { items: UnorderedMap, } #[app::logic] impl MyApp { - #[app::init] - pub fn init() -> MyApp { - MyApp { - items: UnorderedMap::new(), - } - } - - pub fn add_item(&mut self, key: String, value: String) -> app::Result<()> { - self.items.insert(key, value)?; - Ok(()) - } - - pub fn get_item(&self, key: &str) -> app::Result> { - self.items.get(key).map_err(Into::into) + pub fn add_item(&mut self, key: String, value: String) { + self.items.insert(key, value); } } ``` -Build and deploy: - -```bash -# Build WASM -./build.sh - -# Install on node -meroctl --node-name node1 app install \ - --path build/app.wasm \ - --context-id -``` +Build and deploy with [`meroctl`](../tools-apis/meroctl-cli.md). See [SDK Guide](../builder-directory/sdk-guide.md) for details. ## Architecture diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index 18774f2..f7a6fec 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -6,11 +6,25 @@ Calimero uses **cryptographic identities** to manage access control and authenti Calimero supports a hierarchical identity model: -``` -Root Key (Master Identity) -├── Client Key 1 (for Context A) -├── Client Key 2 (for Context B) -└── Client Key 3 (for Context C) +```mermaid +graph TD + ROOT[Root Key
Master Identity
alice.near] + CLIENT1[Client Key 1
Context A
ed25519:abc...] + CLIENT2[Client Key 2
Context B
ed25519:def...] + CLIENT3[Client Key 3
Context C
ed25519:ghi...] + + ROOT -->|derives| CLIENT1 + ROOT -->|derives| CLIENT2 + ROOT -->|derives| CLIENT3 + + CLIENT1 -->|signs transactions| CTX1[Context A] + CLIENT2 -->|signs transactions| CTX2[Context B] + CLIENT3 -->|signs transactions| CTX3[Context C] + + style ROOT fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style CLIENT1 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px + style CLIENT2 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px + style CLIENT3 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px ``` ### Root Keys From cb76f153ec4dae8c25e87e8e4bd46db6e560dc43 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:19:18 -0300 Subject: [PATCH 12/22] fix: Update all Mermaid diagrams to use black/green color scheme - Update Mermaid theme to use black/green colors (#000000, #00ff00) - Convert all ASCII box diagrams to Mermaid with proper colors: - Four-layer architecture diagram - Node architecture diagram - All core concept diagrams updated with black/green theme - Ensure all diagrams have high contrast and visibility - Directory trees kept as ASCII (appropriate for file structures) --- docs/builder-directory/js-sdk-guide.md | 14 +++--- docs/core-concepts/architecture.md | 65 ++++++++++---------------- docs/core-concepts/contexts.md | 8 ++-- docs/core-concepts/identity.md | 11 +++-- docs/core-concepts/index.md | 8 ++-- docs/core-concepts/nodes.md | 29 ++++++------ mkdocs.yml | 18 +++---- 7 files changed, 71 insertions(+), 82 deletions(-) diff --git a/docs/builder-directory/js-sdk-guide.md b/docs/builder-directory/js-sdk-guide.md index 32e8a53..b0584eb 100644 --- a/docs/builder-directory/js-sdk-guide.md +++ b/docs/builder-directory/js-sdk-guide.md @@ -51,8 +51,8 @@ flowchart TD WASM --> OPT OPT --> FINAL - style TS fill:#e3f2fd,stroke:#1976d2,stroke-width:2px - style FINAL fill:#c8e6c9,stroke:#388e3c,stroke-width:3px + style TS fill:#ffffff,stroke:#000000,stroke-width:2px + style FINAL fill:#e5ffe5,stroke:#000000,stroke-width:3px ``` ### Runtime Execution @@ -84,11 +84,11 @@ graph TB QJS --> HOST HOST --> RUNTIME - style JS fill:#e3f2fd,stroke:#1976d2,stroke-width:2px - style SDK fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px - style QJS fill:#fff3e0,stroke:#e65100,stroke-width:2px - style HOST fill:#e8f5e9,stroke:#388e3c,stroke-width:2px - style RUNTIME fill:#fce4ec,stroke:#c2185b,stroke-width:2px + style JS fill:#ffffff,stroke:#000000,stroke-width:2px + style SDK fill:#e5ffe5,stroke:#000000,stroke-width:2px + style QJS fill:#ffffff,stroke:#00ff00,stroke-width:2px + style HOST fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style RUNTIME fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` **How it works:** diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index afefe1c..049a7e9 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -4,37 +4,22 @@ Calimero's architecture consists of four main layers that work together to enabl ## Four-Layer Architecture -``` -┌─────────────────────────────────────────────────────────┐ -│ 1. Application Layer │ -│ - WASM apps using Calimero SDK │ -│ - CRDT collections (UnorderedMap, Vector, Counter) │ -│ - Event emission for real-time updates │ -└────────────────────────┬────────────────────────────────┘ - │ -┌────────────────────────┴────────────────────────────────┐ -│ 2. Node Layer │ -│ - Orchestrates synchronization & execution │ -│ - Dual sync paths: Gossipsub + Periodic P2P │ -│ - Event handler execution │ -│ - Blob distribution │ -└────────────────────────┬────────────────────────────────┘ - │ -┌────────────────────────┴────────────────────────────────┐ -│ 3. Storage Layer │ -│ - CRDT storage with automatic merging │ -│ - DAG for causal ordering │ -│ - Out-of-order delivery handling │ -│ - Merkle trees for state comparison │ -└────────────────────────┬────────────────────────────────┘ - │ -┌────────────────────────┴────────────────────────────────┐ -│ 4. Network Layer │ -│ - libp2p (Gossipsub, Streams, DHT) │ -│ - JSON-RPC server │ -│ - WebSocket/SSE subscriptions │ -│ - Authentication & authorization │ -└─────────────────────────────────────────────────────────┘ +```mermaid +graph TB + APP[Application Layer
WASM apps + SDK
CRDT collections
Event emission] + NODE[Node Layer
Synchronization & execution
Dual sync paths
Event handlers
Blob distribution] + STORAGE[Storage Layer
CRDT storage
DAG causal ordering
Out-of-order handling
Merkle trees] + NETWORK[Network Layer
libp2p P2P
JSON-RPC server
WebSocket/SSE
Authentication] + + APP -->|executes| NODE + NODE -->|stores| STORAGE + STORAGE -->|syncs via| NETWORK + NETWORK -->|provides| NODE + + style APP fill:#e5ffe5,stroke:#000000,stroke-width:3px + style NODE fill:#ffffff,stroke:#00ff00,stroke-width:3px + style STORAGE fill:#e5ffe5,stroke:#000000,stroke-width:3px + style NETWORK fill:#ffffff,stroke:#00ff00,stroke-width:3px ``` ## Transaction Flow @@ -133,11 +118,11 @@ flowchart TB G6B -.->|Eventually| P6 - style G1 fill:#4DABF7,stroke:#333,stroke-width:3px,color:#000 - style G6A fill:#51CF66,stroke:#333,stroke-width:3px,color:#000 - style G6B fill:#FFB84D,stroke:#333,stroke-width:3px,color:#000 - style P1 fill:#FF6B6B,stroke:#333,stroke-width:3px,color:#000 - style P8 fill:#51CF66,stroke:#333,stroke-width:3px,color:#000 + style G1 fill:#ffffff,stroke:#000000,stroke-width:3px + style G6A fill:#e5ffe5,stroke:#00ff00,stroke-width:3px + style G6B fill:#ffffff,stroke:#00ff00,stroke-width:2px + style P1 fill:#ffffff,stroke:#000000,stroke-width:2px + style P8 fill:#e5ffe5,stroke:#00ff00,stroke-width:3px ``` **Why both paths?** @@ -162,10 +147,10 @@ graph TB F1B --> F2 end - style F0 fill:#4DABF7,stroke:#333,stroke-width:3px,color:#000 - style F1A fill:#FF6B6B,stroke:#333,stroke-width:3px,color:#000 - style F1B fill:#FF6B6B,stroke:#333,stroke-width:3px,color:#000 - style F2 fill:#51CF66,stroke:#333,stroke-width:3px,color:#000 + style F0 fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style F1A fill:#ffffff,stroke:#000000,stroke-width:2px + style F1B fill:#ffffff,stroke:#000000,stroke-width:2px + style F2 fill:#e5ffe5,stroke:#00ff00,stroke-width:3px ``` **Key properties**: diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index 00d12d5..7192e3e 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -110,10 +110,10 @@ graph TB CRDT1 -.->|isolated| CRDT2 - style CRDT1 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px - style CRDT2 fill:#e8f5e9,stroke:#388e3c,stroke-width:2px - style PRIVATE1 fill:#fff3e0,stroke:#e65100,stroke-width:2px - style PRIVATE2 fill:#fff3e0,stroke:#e65100,stroke-width:2px + style CRDT1 fill:#e5ffe5,stroke:#000000,stroke-width:3px + style CRDT2 fill:#e5ffe5,stroke:#000000,stroke-width:3px + style PRIVATE1 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style PRIVATE2 fill:#ffffff,stroke:#00ff00,stroke-width:2px ``` **Key points:** diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index f7a6fec..5b4e8dc 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -21,10 +21,13 @@ graph TD CLIENT2 -->|signs transactions| CTX2[Context B] CLIENT3 -->|signs transactions| CTX3[Context C] - style ROOT fill:#e3f2fd,stroke:#1976d2,stroke-width:3px - style CLIENT1 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px - style CLIENT2 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px - style CLIENT3 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px + style ROOT fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CLIENT1 fill:#e5ffe5,stroke:#000000,stroke-width:2px + style CLIENT2 fill:#e5ffe5,stroke:#000000,stroke-width:2px + style CLIENT3 fill:#e5ffe5,stroke:#000000,stroke-width:2px + style CTX1 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style CTX2 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style CTX3 fill:#ffffff,stroke:#00ff00,stroke-width:2px ``` ### Root Keys diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md index f974297..6c06284 100644 --- a/docs/core-concepts/index.md +++ b/docs/core-concepts/index.md @@ -105,10 +105,10 @@ graph TB APP1 -.->|isolated state| APP2 MEMBERS1 -.->|separate access| MEMBERS2 - style APP1 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px - style APP2 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px - style MEMBERS1 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px - style MEMBERS2 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px + style APP1 fill:#e5ffe5,stroke:#000000,stroke-width:3px + style APP2 fill:#e5ffe5,stroke:#000000,stroke-width:3px + style MEMBERS1 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style MEMBERS2 fill:#ffffff,stroke:#00ff00,stroke-width:2px ``` ## Learning Path diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md index 55dc901..a207e2b 100644 --- a/docs/core-concepts/nodes.md +++ b/docs/core-concepts/nodes.md @@ -33,20 +33,21 @@ merod --node-type peer --swarm-addrs /ip4/127.0.0.1/tcp/2428 ## Node Architecture -``` -┌─────────────────────────────────────────────────────────┐ -│ NodeManager (Actix Actor) │ -│ - Orchestrates all components │ -│ - Periodic timers (cleanup, heartbeat) │ -└────────────────┬────────────────────────────────────┘ - │ - ┌───────────┴───────────┬─────────────┐ - │ │ │ -┌────▼────────┐ ┌────────▼──────┐ ┌──▼───────────┐ -│NodeClients │ │NodeManagers │ │NodeState │ -│ - Context │ │ - BlobManager │ │ - BlobCache │ -│ - Node │ │ - SyncManager │ │ - DeltaStores│ -└─────────────┘ └───────────────┘ └──────────────┘ +```mermaid +graph TB + NODEMGR[NodeManager Actix Actor
Orchestrates all components
Periodic timers cleanup heartbeat] + CLIENTS[NodeClients
Context Node] + MANAGERS[NodeManagers
BlobManager SyncManager] + STATE[NodeState
BlobCache DeltaStores] + + NODEMGR -->|manages| CLIENTS + NODEMGR -->|manages| MANAGERS + NODEMGR -->|manages| STATE + + style NODEMGR fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CLIENTS fill:#e5ffe5,stroke:#000000,stroke-width:2px + style MANAGERS fill:#ffffff,stroke:#00ff00,stroke-width:2px + style STATE fill:#e5ffe5,stroke:#000000,stroke-width:2px ``` ### NodeManager diff --git a/mkdocs.yml b/mkdocs.yml index 1fa3dca..e74f114 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,21 +63,21 @@ plugins: - search # Built-in search functionality - mermaid2: # Mermaid diagram support arguments: - theme: "default" + theme: "base" themeVariables: primaryColor: "#ffffff" primaryTextColor: "#000000" primaryBorderColor: "#000000" lineColor: "#000000" - secondaryColor: "#f5f5f5" - tertiaryColor: "#e0e0e0" + secondaryColor: "#00ff00" + tertiaryColor: "#e5ffe5" background: "#ffffff" mainBkg: "#ffffff" - secondBkg: "#f5f5f5" + secondBkg: "#f0f0f0" textColor: "#000000" - noteBkgColor: "#fff9c4" + noteBkgColor: "#ffffcc" noteTextColor: "#000000" - noteBorderColor: "#ffd700" + noteBorderColor: "#000000" actorBorder: "#000000" actorBkg: "#ffffff" actorTextColor: "#000000" @@ -89,13 +89,13 @@ plugins: labelTextColor: "#000000" loopTextColor: "#000000" activationBorderColor: "#000000" - activationBkgColor: "#f5f5f5" + activationBkgColor: "#e5ffe5" sequenceNumberColor: "#000000" sectionBkgColor: "#ffffff" - altBkgColor: "#f5f5f5" + altBkgColor: "#f0f0f0" clusterBkg: "#ffffff" clusterBorder: "#000000" - defaultLinkColor: "#1976d2" + defaultLinkColor: "#00ff00" titleColor: "#000000" edgeLabelBackground: "#ffffff" labelBackground: "#ffffff" From 095a8d8710c162dbbaf3c2ddeb795686eff584e6 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:25:24 -0300 Subject: [PATCH 13/22] docs: Simplify diagrams and make pages more concise - Split complex sync flow diagram into two simpler diagrams - Split transaction flow into simple and detailed views - Make architecture page more concise with README references - Simplify applications, identity, contexts, and nodes pages - Clean up placeholder content in Operator Track and Reference - Fix broken anchor links - Add component relationship diagram to architecture page --- docs/core-concepts/applications.md | 100 ++---- docs/core-concepts/architecture.md | 345 +++++++-------------- docs/core-concepts/contexts.md | 61 +--- docs/core-concepts/identity.md | 167 +++------- docs/core-concepts/nodes.md | 104 ++----- docs/intro/index.md | 2 +- docs/operator-track/index.md | 46 +-- docs/operator-track/monitor-and-debug.md | 69 ++++- docs/operator-track/run-a-local-network.md | 54 +++- docs/reference/index.md | 49 +-- 10 files changed, 375 insertions(+), 622 deletions(-) diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index 56e1a08..b21f19e 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -75,104 +75,54 @@ sequenceDiagram ## CRDT State Management -Applications use CRDT collections for conflict-free state: +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. -### Available Collections +**Available collections:** +- `Counter` - Distributed counters (sum) +- `LwwRegister` - Last-write-wins registers +- `UnorderedMap` - Key-value maps +- `Vector` - Ordered lists +- `UnorderedSet` - Unique sets (union) +- `Option` - Optional CRDTs -| Collection | Use Case | Merge Strategy | -| --- | --- | --- | -| **Counter** | Metrics, counters | Sum | -| **LwwRegister<T>** | Single values | Latest timestamp | -| **UnorderedMap<K,V>** | Key-value storage | Recursive per-entry | -| **Vector<T>** | Ordered lists | Element-wise | -| **UnorderedSet<T>** | Unique values | Union | -| **Option<T>** | Optional CRDTs | Recursive if Some | - -### Nested Structures - -CRDTs can be nested arbitrarily: - -```rust -#[app::state] -pub struct TeamMetrics { - // Map of team member → Map of metric → Counter - member_metrics: UnorderedMap>, -} -``` +CRDTs can be nested arbitrarily for complex data structures. ## Event System -Applications can emit events for real-time updates: - -```rust -#[app::state(emits = ItemAdded)] -pub struct MyApp { - items: UnorderedMap, -} - -#[derive(BorshSerialize, BorshDeserialize)] -pub struct ItemAdded { - key: String, - value: String, -} - -#[app::logic] -impl MyApp { - pub fn add_item(&mut self, key: String, value: String) -> app::Result<()> { - self.items.insert(key.clone(), value.clone())?; - app::emit(ItemAdded { key, value })?; - Ok(()) - } -} -``` +Applications emit events for real-time updates. Events propagate to all peers automatically. -**Event lifecycle**: +**Event lifecycle:** 1. Emitted during method execution -2. Included in delta broadcast to all peers -3. Event handlers execute on peer nodes (not author node) -4. Handlers can update UI or trigger side effects +2. Broadcast to all peers via delta +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. ## Private Storage -For node-local data (secrets, caches, per-node counters): +For node-local data (secrets, caches) that never syncs across nodes: ```rust use calimero_sdk::private_storage; -pub fn use_private_storage() { - let secrets = private_storage::entry::("my-secrets"); - secrets.write(|s| { - s.token = "rotated-token".to_string(); - }); -} +let secrets = private_storage::entry::("my-secrets"); +secrets.write(|s| { s.token = "rotated".to_string(); }); ``` -**Key properties**: -- Not replicated across nodes -- Stored via `storage_read` / `storage_write` directly -- Never included in CRDT deltas -- Accessible only on the executing node +See [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.md) for private storage details. ## Views vs Mutations -Mark read-only methods with `#[app::view]`: +Mark read-only methods with `#[app::view]` to skip persistence: ```rust -#[app::logic] -impl MyApp { - // Mutation - persists state changes - pub fn add_item(&mut self, key: String, value: String) -> app::Result<()> { - self.items.insert(key, value)?; - Ok(()) - } - - // View - read-only, skips persistence - #[app::view] - pub fn get_item(&self, key: &str) -> app::Result> { - self.items.get(key).map_err(Into::into) - } +#[app::view] // Read-only, no delta generated +pub fn get_item(&self, key: &str) -> Option { + self.items.get(key) } ``` +``` **Benefits**: - Views don't generate storage deltas diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index 049a7e9..b438240 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -24,111 +24,90 @@ graph TB ## Transaction Flow -Here's how a transaction flows through the system: - +**Simple view:** ```mermaid sequenceDiagram - participant Client as JSON-RPC Client - participant Node as Node Runtime - participant WASM as WASM Module - participant Storage as CRDT Storage - participant DAG as DAG Store - participant Network as P2P Network - participant Peer as Peer Node - Client->>Node: call("add_item", args) - Node->>WASM: execute(method, args) - - rect rgb(220, 237, 255) - Note over WASM,Storage: Transaction Execution - WASM->>Storage: map.insert(key, value) - Storage->>Storage: Generate Action::Update - Storage->>Storage: Calculate Merkle hashes - Storage->>Storage: Collect in DELTA_CONTEXT - end - - WASM-->>Node: ExecutionOutcome {
root_hash, events, ...} + Node->>WASM: execute() + WASM->>Storage: CRDT operations + Storage->>Node: ExecutionOutcome + Node->>Network: Broadcast delta + Network->>Peer: Propagate (~100ms) + Node->>Client: Result - rect rgb(255, 237, 220) - Note over Node,Network: Delta Propagation - Node->>DAG: Create CausalDelta {
parents: dag_heads,
payload: actions} - Node->>Network: Broadcast StateDelta via Gossipsub - end - - Network->>Peer: Propagate to all peers (~100-200ms) - Peer->>Peer: Check if parents ready - alt Parents ready - Peer->>Peer: Apply delta immediately - Peer->>Peer: Execute event handlers - else Parents missing - Peer->>Peer: Buffer as pending - Note over Peer: Wait for parents via P2P sync - end + style Client fill:#ffffff,stroke:#000000 + style Node fill:#e5ffe5,stroke:#00ff00 + style WASM fill:#ffffff,stroke:#000000 +``` + +**Detailed execution:** +```mermaid +sequenceDiagram + WASM->>Storage: map.insert(key, value) + Storage->>Storage: Generate Action + Storage->>Storage: Calculate Merkle hash + Storage->>Storage: Collect in DELTA_CONTEXT + Storage->>Node: Return ExecutionOutcome + Node->>DAG: Create CausalDelta + Node->>Network: Broadcast via Gossipsub - Node-->>Client: TransactionResult + style WASM fill:#ffffff,stroke:#000000 + style Storage fill:#e5ffe5,stroke:#00ff00 + style Node fill:#ffffff,stroke:#00ff00 ``` +See [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md) for execution details. + ## Synchronization Flow Calimero uses a dual-path synchronization strategy: ### Path 1: Gossipsub Broadcast (Primary) -- **Speed**: ~100-200ms latency -- **Reliability**: Excellent in good network conditions -- **Purpose**: Fast, real-time propagation of changes -- **How it works**: Delta broadcast to all peers in the Gossipsub mesh -### Path 2: Periodic P2P Sync (Fallback) -- **Speed**: Every 10-30 seconds -- **Reliability**: Ensures eventual consistency -- **Purpose**: Catch-up after network issues, downtime, or packet loss -- **How it works**: Direct P2P stream exchange of missing deltas +Fast real-time propagation (~100-200ms): ```mermaid -flowchart TB - subgraph "Path 1: Gossipsub Broadcast (Primary)" - G1[Transaction executed
on Node A] - G2[Create CausalDelta
parents: dag_heads] - G3[Broadcast via Gossipsub] - G4[All peers receive
within ~100ms] - G5{Parents ready?} - G6A[Apply immediately] - G6B[Buffer as pending] - G7[Execute event handlers] - - G1 --> G2 --> G3 --> G4 --> G5 - G5 -->|Yes| G6A --> G7 - G5 -->|No| G6B - end +flowchart LR + A[Transaction
executed] --> B[Create
CausalDelta] + B --> C[Broadcast via
Gossipsub] + C --> D[All peers receive
~100-200ms] + D --> E{Parents
ready?} + E -->|Yes| F[Apply
immediately] + E -->|No| G[Buffer as
pending] + F --> H[Execute
event handlers] - subgraph "Path 2: Periodic Sync (Fallback)" - P1[SyncManager timer
every 10-30s] - P2[Select random peer] - P3[Open P2P stream] - P4[Exchange DAG heads] - P5{Heads differ?} - P6[Request missing deltas] - P7[Apply missing deltas] - P8[Catch up complete] - - P1 --> P2 --> P3 --> P4 --> P5 - P5 -->|Yes| P6 --> P7 --> P8 - P5 -->|No| P8 - end - - G6B -.->|Eventually| P6 + style A fill:#ffffff,stroke:#000000,stroke-width:2px + style F fill:#e5ffe5,stroke:#00ff00,stroke-width:3px + style H fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style G fill:#ffffff,stroke:#00ff00,stroke-width:2px +``` + +### Path 2: Periodic P2P Sync (Fallback) + +Catch-up every 10-30 seconds for eventual consistency: + +```mermaid +flowchart LR + T[SyncManager
timer] --> S[Select
random peer] + S --> O[Open P2P
stream] + O --> X[Exchange
DAG heads] + X --> D{Heads
differ?} + D -->|Yes| R[Request
missing deltas] + D -->|No| C[Up to date] + R --> A[Apply
deltas] + A --> C - style G1 fill:#ffffff,stroke:#000000,stroke-width:3px - style G6A fill:#e5ffe5,stroke:#00ff00,stroke-width:3px - style G6B fill:#ffffff,stroke:#00ff00,stroke-width:2px - style P1 fill:#ffffff,stroke:#000000,stroke-width:2px - style P8 fill:#e5ffe5,stroke:#00ff00,stroke-width:3px + style T fill:#ffffff,stroke:#000000,stroke-width:2px + style C fill:#e5ffe5,stroke:#00ff00,stroke-width:3px + style A fill:#e5ffe5,stroke:#00ff00,stroke-width:2px ``` **Why both paths?** - **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. + ## DAG-Based Causal Ordering The DAG (Directed Acyclic Graph) ensures that deltas are applied in the correct causal order, even when received out-of-order: @@ -159,155 +138,59 @@ graph TB - Once parents are available, deltas are applied automatically in causal order - Concurrent updates create forks that merge automatically -## Component Map - -| Component | Purpose | Responsibility | Location | -| --- | --- | --- | --- | -| **Application SDK** | Macro system (`#[app::state]`, `#[app::logic]`), CRDT collections, event emission | Provides developer API for building WASM applications | `crates/sdk` | -| **Runtime** | WASM execution engine (Wasmer), sandboxing, resource limits | Executes WASM modules safely with bounded resources | `crates/runtime` | -| **Storage** | CRDT collections with merge semantics | Manages conflict-free data types and automatic merging | `crates/storage` | -| **DAG** | Pure DAG for causal delta tracking, dependency resolution | Ensures deltas are applied in correct causal order | `crates/dag` | -| **Node** | NodeManager orchestrates sync, events, blob sharing | Coordinates all node operations (sync, events, blobs) | `crates/node` | -| **Network** | libp2p integration for P2P communication | Handles P2P networking (Gossipsub, streams, DHT) | `crates/network` | -| **Server** | JSON-RPC API, WebSocket/SSE subscriptions, admin endpoints | Exposes APIs for clients and admin operations | `crates/server` | -| **Auth** | Authentication and identity management | Handles wallet-based auth and JWT token issuance | `crates/auth` | -| **Store** | Persistent storage backend (RocksDB) | Provides durable storage for contexts and state | `crates/store` | -| **Context** | Context (application instance) lifecycle management | Manages context creation, membership, and operations | `crates/context` | -| **merod** | Node binary (coordinator or peer) | Main executable for running Calimero nodes | `crates/merod` | -| **meroctl** | CLI for node operations, app installation, calls | Command-line interface for node management | `crates/meroctl` | - -## Key Components Deep Dive - -### Application SDK (`crates/sdk`) - -**What it does:** -- Provides macros (`#[app::state]`, `#[app::logic]`, `#[app::init]`) for defining application structure -- Exposes CRDT collections (UnorderedMap, Vector, Counter, etc.) for state management -- Handles event emission and collection -- Manages private storage for node-local data - -**Why it matters:** -- Simplifies application development with declarative macros -- Ensures correct CRDT usage patterns -- Abstracts away low-level storage details - -**Key concepts:** -- State structs define persisted data -- Logic structs implement methods -- Views vs mutations (read-only vs state-changing) -- Event emission for real-time updates - -### Runtime (`crates/runtime`) - -**What it does:** -- Executes WASM modules using Wasmer -- Enforces resource limits (memory, stack, execution time) -- Provides host functions (storage, logging, crypto, HTTP) -- Handles deterministic execution - -**Why it matters:** -- Sandboxes untrusted code safely -- Prevents resource exhaustion -- Enables consistent execution across nodes - -**Key concepts:** -- VMLogic: Central execution context -- Host functions: Bridge between WASM and host -- Resource metering: Gas-like system for execution limits - -### Storage (`crates/storage`) - -**What it does:** -- Implements CRDT collections (UnorderedMap, Vector, Counter, LwwRegister, etc.) -- Handles automatic merging of concurrent updates -- Manages Merkle trees for efficient state comparison -- Provides snapshot and delta generation - -**Why it matters:** -- Enables conflict-free synchronization -- Handles concurrent updates automatically -- Efficient state comparison for sync - -**Key concepts:** -- CRDT semantics: Each collection type has specific merge behavior -- Nested structures: CRDTs can be nested arbitrarily -- Action generation: State changes generate actions for delta propagation - -### DAG (`crates/dag`) - -**What it does:** -- Tracks causal relationships between deltas -- Buffers deltas until parent dependencies are ready -- Applies deltas in correct causal order -- Detects and handles forks - -**Why it matters:** -- Handles out-of-order network delivery -- Ensures consistent state across nodes -- Enables concurrent updates without conflicts - -**Key concepts:** -- CausalDelta: Delta with parent references -- DagStore: Manages delta graph -- Pending deltas: Buffered until parents arrive -- DAG heads: Current tips of the graph - -### Node (`crates/node`) - -**What it does:** -- Orchestrates all node operations (NodeManager) -- Manages delta propagation (Gossipsub + P2P sync) -- Executes event handlers on peer nodes -- Distributes blobs via content-addressed storage - -**Why it matters:** -- Central coordination point for all node activities -- Ensures reliable synchronization -- Enables real-time event handling - -**Key concepts:** -- NodeManager: Main orchestrator (Actix Actor) -- DeltaStore: Wraps DAG with WASM execution -- SyncManager: Coordinates periodic sync -- BlobManager: Manages blob cache and distribution - -### Network (`crates/network`) - -**What it does:** -- Integrates libp2p for P2P communication -- Manages Gossipsub mesh for broadcast -- Handles P2P streams for direct communication -- Provides DHT for peer discovery - -**Why it matters:** -- Enables decentralized communication -- Fast broadcast for real-time updates -- Reliable streams for catch-up sync - -**Key concepts:** -- Gossipsub: Pub/sub for delta broadcast -- P2P streams: Direct peer-to-peer communication -- DHT: Distributed hash table for peer discovery -- Noise encryption: Secure communication - -### Server (`crates/server`) - -**What it does:** -- Exposes JSON-RPC API for client interaction -- Provides WebSocket and SSE for real-time subscriptions -- Handles admin API endpoints -- Manages authentication and authorization - -**Why it matters:** -- Enables client applications to interact with nodes -- Provides real-time updates via subscriptions -- Allows administrative operations - -**Key concepts:** -- JSON-RPC: Standard RPC protocol -- WebSocket/SSE: Real-time event streaming -- Admin API: Node management operations -- Authentication: JWT-based access control +## Key Components + +```mermaid +graph TB + SDK[SDK
crates/sdk] + RUNTIME[Runtime
crates/runtime] + STORAGE[Storage
crates/storage] + DAG[DAG
crates/dag] + NODE[Node
crates/node] + NETWORK[Network
crates/network] + SERVER[Server
crates/server] + + SDK -->|executes via| RUNTIME + RUNTIME -->|uses| STORAGE + STORAGE -->|tracks in| DAG + NODE -->|orchestrates| RUNTIME + NODE -->|syncs via| NETWORK + SERVER -->|exposes| NODE + + style SDK fill:#e5ffe5,stroke:#000000,stroke-width:2px + style RUNTIME fill:#ffffff,stroke:#00ff00,stroke-width:2px + style STORAGE fill:#e5ffe5,stroke:#000000,stroke-width:2px + style DAG fill:#ffffff,stroke:#00ff00,stroke-width:2px + style NODE fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style NETWORK fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style SERVER fill:#ffffff,stroke:#000000,stroke-width:2px +``` + +| 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. + +## 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 ## Deep Dives diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index 7192e3e..e0fdd0a 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -141,71 +141,36 @@ Each protocol provides: ## Context Operations -### Querying State - +**Query state:** ```bash -# Call a view method (read-only) -meroctl call \ - --context-id \ - --method get_item \ - --args '{"key": "hello"}' +meroctl call --context-id --method get_item --args '{"key": "hello"}' ``` -### Mutating State - +**Mutate state:** ```bash -# Call a mutation method -meroctl call \ - --context-id \ - --method add_item \ - --args '{"key": "hello", "value": "world"}' \ - --executor-public-key +meroctl call --context-id --method add_item --args '{"key": "hello", "value": "world"}' --executor-public-key ``` -### Subscribing to Events +**Subscribe to events:** +- WebSocket: Connect to `ws://localhost:2528/ws` +- Use `subscribe` method with `context_id` and `event_type` +- See [WebSocket Reference](../reference/websocket-streams.md) for details -```bash -# Subscribe via WebSocket -wscat -c ws://localhost:2528/ws - -# Subscribe to context events -{ - "jsonrpc": "2.0", - "id": 1, - "method": "subscribe", - "params": { - "context_id": "", - "event_type": "ItemAdded" - } -} -``` +See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md) for complete CLI documentation. ## Context Management -### Listing Contexts - +**List contexts:** ```bash -# List all contexts on a node meroctl context list - -# Get context details -meroctl context get --context-id ``` -### Revoking Access - +**Revoke access:** ```bash -# Revoke a member's access -meroctl context revoke \ - --context-id \ - --member-id +meroctl context revoke --context-id --member-id ``` -**What happens:** -- Member is removed from context -- Member can no longer call methods -- Member stops receiving updates -- State remains intact (no data deletion) +Revoking access removes the member but preserves state history. ## Best Practices diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index 5b4e8dc..958044f 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -53,159 +53,66 @@ A **root key** is the master identity for a user or node. It's typically: ## Identity Generation -### Creating a New Identity +Generate identities with `meroctl`: ```bash -# Generate a new identity on a node meroctl identity create --node-name node1 - -# Output: -# Public Key: ed25519:abc123... -# Stored in: ~/.calimero/identities/node1/ ``` -**What happens:** -- Ed25519 keypair is generated -- Private key is stored securely on the node -- Public key is returned for sharing - -### Using Blockchain Wallets - -Calimero integrates with blockchain wallets for identity: +See [`core/crates/meroctl/README.md`](https://github.com/calimero-network/core/blob/master/crates/meroctl/README.md) for CLI details. -| Protocol | Wallet Integration | Identity Source | -| --- | --- | --- | -| **NEAR** | NEAR Wallet, Ledger | NEAR account ID + signature | -| **Ethereum** | MetaMask, WalletConnect | Ethereum address + signature | -| **ICP** | Internet Identity, Plug | ICP principal + signature | -| **Stellar** | Stellar Wallet | Stellar account + signature | +## Blockchain Wallet Integration -**Authentication Flow:** -1. User connects wallet (e.g., MetaMask) -2. User signs a challenge message -3. Calimero verifies signature against blockchain -4. Identity is established and JWT token issued +Calimero supports wallet-based authentication: -## Authentication Flows - -### NEAR Protocol +| Protocol | Identity Source | +| --- | --- | +| **NEAR** | NEAR account ID + signature | +| **Ethereum** | Ethereum address + signature | +| **ICP** | ICP principal + signature | +| **Stellar** | Stellar account + signature | -```typescript -// Client-side authentication -import { connect, keyStores } from 'near-api-js'; - -const keyStore = new keyStores.BrowserLocalStorageKeyStore(); -const near = await connect({ - networkId: 'testnet', - keyStore, -}); - -// Sign challenge -const account = await near.account('user.near'); -const signature = await account.connection.signer.signMessage( - challenge, - account.accountId, - 'testnet' -); - -// Send to Calimero auth service -const jwt = await fetch('/auth/near', { - method: 'POST', - body: JSON.stringify({ accountId, signature, challenge }), -}); -``` - -### Ethereum - -```typescript -// Using ethers.js -import { ethers } from 'ethers'; - -const provider = new ethers.BrowserProvider(window.ethereum); -const signer = await provider.getSigner(); -const address = await signer.getAddress(); - -// Sign challenge -const signature = await signer.signMessage(challenge); - -// Send to Calimero auth service -const jwt = await fetch('/auth/ethereum', { - method: 'POST', - body: JSON.stringify({ address, signature, challenge }), -}); -``` +**Flow:** +1. User connects wallet +2. Signs challenge message +3. Calimero verifies signature +4. JWT token issued -### ICP (Internet Computer) +See [`calimero-client-js/README.md`](https://github.com/calimero-network/calimero-client-js#readme) for client authentication examples. -```typescript -// Using @dfinity/agent -import { Actor, HttpAgent } from '@dfinity/agent'; - -const agent = new HttpAgent({ identity }); -const principal = await agent.getPrincipal(); +## Authentication Flows -// Sign challenge using Internet Identity -const signature = await agent.sign(challenge); - -// Send to Calimero auth service -const jwt = await fetch('/auth/icp', { - method: 'POST', - body: JSON.stringify({ principal, signature, challenge }), -}); -``` +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 ## JWT Tokens -After authentication, Calimero issues **JWT (JSON Web Token)** tokens: - -```json -{ - "context_id": "context-123", - "executor_public_key": "ed25519:abc...", - "permissions": ["read", "write", "execute"], - "exp": 1234567890 -} -``` +After authentication, Calimero issues JWT tokens containing: +- `context_id` - Target context +- `executor_public_key` - Client key for execution +- `permissions` - Access permissions +- `exp` - Expiration timestamp -**Token usage:** -- Included in API requests: `Authorization: Bearer ` -- Proves identity and permissions -- Expires after configured time -- Refreshable via refresh token +**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 ## Key Management -### Hierarchical Key Management - -``` -Root Key (NEAR account: alice.near) -│ -├── Context A Client Key -│ ├── Can execute methods in Context A -│ └── Can read/write Context A state -│ -├── Context B Client Key -│ ├── Can execute methods in Context B -│ └── Can read/write Context B state -│ -└── Context C Client Key (revoked) - └── No longer has access -``` - -**Benefits:** -- **Granular Control**: Different keys for different contexts -- **Easy Revocation**: Revoke one key without affecting others -- **Audit Trail**: Track which key performed which action - -### Key Revocation +**Hierarchical structure:** +- Root keys delegate to client keys per context +- Each context has separate client keys +- Keys can be revoked independently +**Revoke access:** ```bash -# Revoke a client key's access to a context -meroctl context revoke \ - --context-id \ - --member-id +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. + **What happens:** - Key is removed from context membership - Key can no longer sign transactions for that context diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md index a207e2b..06e56c8 100644 --- a/docs/core-concepts/nodes.md +++ b/docs/core-concepts/nodes.md @@ -50,96 +50,58 @@ graph TB style STATE fill:#e5ffe5,stroke:#000000,stroke-width:2px ``` -### NodeManager -Main orchestrator that manages: -- **Periodic timers**: - - Blob eviction (every 5 min) - - Delta cleanup (every 60 sec) - - Hash heartbeat (every 30 sec) -- **Context subscriptions**: Subscribe to all contexts on startup -- **Lifecycle management**: Start/stop, graceful shutdown - -### NodeClients -External service clients: -- **ContextClient**: Execute WASM methods, query DAG heads, get root hash -- **NodeClient**: Subscribe/unsubscribe to contexts, broadcast deltas, open P2P streams - -### NodeManagers -Service managers: -- **BlobManager**: Store blobs (content-addressed), retrieve by ID, garbage collection -- **SyncManager**: Trigger periodic sync, track last sync time per context, coordinate P2P streams - -### NodeState -Runtime state (mutable caches): -- **blob_cache**: LRU cache for frequently accessed blobs -- **delta_stores**: Per-context DAG stores +### Components -## Synchronization - -Nodes use a **dual-path synchronization strategy**: - -### Path 1: Gossipsub Broadcast (Primary) -- **Latency**: ~100-200ms -- **Reliability**: Excellent in good network conditions -- **Purpose**: Fast, real-time propagation +- **NodeManager**: Orchestrates sync, events, lifecycle, periodic timers +- **NodeClients**: ContextClient (WASM execution), NodeClient (P2P operations) +- **NodeManagers**: BlobManager (content storage), SyncManager (periodic sync) +- **NodeState**: Blob cache, delta stores per context -All peers receive deltas via Gossipsub mesh within ~100-200ms. +See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) for detailed architecture. -### Path 2: Periodic P2P Sync (Fallback) -- **Frequency**: Every 10-30 seconds -- **Reliability**: Ensures eventual consistency -- **Purpose**: Catch-up after network issues or downtime +## Synchronization -Direct P2P stream exchange of missing deltas ensures no data loss. +Nodes use dual-path sync: +- **Gossipsub** (~100-200ms) - Fast real-time broadcast +- **Periodic P2P** (every 10-30s) - Catch-up and recovery -For detailed sync flow, see [Architecture Overview](architecture.md#synchronization-flow). +See [Architecture Overview](architecture.md#synchronization-flow) for sync flow diagrams. ## Event Handling -When a delta is applied: - -1. **Author node**: Skips event handler (assumes local UI already updated) -2. **Peer nodes**: Execute event handlers automatically after delta application -3. **Event propagation**: Events are included in delta broadcast to all peers - -This ensures: -- Real-time updates across all nodes -- No duplicate event handling on author node -- Consistent event ordering via DAG causal ordering +When deltas are applied: +1. Author node skips handlers (local UI already updated) +2. Peer nodes execute handlers automatically +3. Events propagate via DAG causal ordering ## Blob Distribution -Nodes manage content-addressed blob storage: +Content-addressed blob storage: +- Blobs stored by hash (blob ID) +- LRU cache with eviction (5 min or 100 blobs / 500 MB) +- P2P distribution via streams +- Periodic garbage collection -- **Storage**: Blobs stored by content hash (blob ID) -- **Caching**: LRU cache for frequently accessed blobs (evicts after 5 min, or when cache exceeds 100 blobs / 500 MB) -- **Distribution**: Peers request blobs from each other via P2P streams -- **Garbage collection**: Unused blobs evicted periodically +See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md) for blob management details. ## Admin Surfaces -Nodes expose several interfaces: +**JSON-RPC** (port 2528): +- `/jsonrpc` - RPC calls -### JSON-RPC Server -- **Port**: 2528 (default) -- **Purpose**: Client interaction, method calls, queries -- **Endpoints**: `/jsonrpc` (RPC calls), `/jsonrpc/stream` (subscriptions) +**WebSocket** (`/ws`): +- Real-time subscriptions (deltas, events, state changes) +- JSON-RPC over WebSocket -### WebSocket -- **Purpose**: Real-time subscriptions (deltas, events, state changes) -- **Endpoint**: `/ws` -- **Protocol**: JSON-RPC over WebSocket +**SSE** (`/sse`): +- Alternative to WebSocket for event streaming +- Browser-friendly real-time updates -### Server-Sent Events (SSE) -- **Purpose**: Alternative to WebSocket for event streaming -- **Endpoint**: `/sse` -- **Use case**: Browser-friendly real-time updates +**Admin API** (`/admin-api/`): +- Node administration, context management, identity operations +- JWT token authentication -### Admin API -- **Port**: 2528 (default) -- **Endpoint**: `/admin-api/` -- **Purpose**: Node administration, context management, identity operations -- **Authentication**: JWT tokens +See [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) for API details. ## Monitoring & Debugging diff --git a/docs/intro/index.md b/docs/intro/index.md index ccb6e82..461f276 100644 --- a/docs/intro/index.md +++ b/docs/intro/index.md @@ -143,7 +143,7 @@ core/ └── e2e-tests/ # End-to-end test suite ``` -For detailed component explanations, see [Architecture Overview](../core-concepts/architecture.md#component-map). +For detailed component explanations, see [Architecture Overview](../core-concepts/architecture.md#key-components). ## Next Steps diff --git a/docs/operator-track/index.md b/docs/operator-track/index.md index 4ca11ae..92d6e88 100644 --- a/docs/operator-track/index.md +++ b/docs/operator-track/index.md @@ -1,33 +1,35 @@ -# Operator Track +# Operating Calimero Nodes -> Placeholder road map — fill with actionable guidance as operator docs mature. +Guidance for running and managing Calimero nodes in production. -- [Run a Local Network](run-a-local-network.md) -- [Join Existing Contexts](join-existing-contexts.md) -- [Monitor & Debug](monitor-and-debug.md) -- [Production Deployment Notes](production-deployment-notes.md) +## Quick Links -## Run a Local Network +| 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) | -- Document hardware prerequisites. -- Summarize `merobox` bootstrap steps. -- Link to monitoring endpoints. +## Running Nodes -## Join Existing Contexts +For complete node documentation, see [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob/master/crates/node/README.md). -- Explain invite flow, acceptance, and key management. -- Reference admin API endpoints. +**Quick start:** +```bash +# Install merod +cargo install --path core/crates/merod -## Monitor & Debug +# Run coordinator +merod --node-type coordinator -- Highlight Admin Dashboard, Node Console, logs, metrics. -- Plan to add screenshots and diagrams. +# Run peer +merod --node-type peer --swarm-addrs /ip4/127.0.0.1/tcp/2428 +``` -## Production Deployment Notes +**Or use Merobox:** +```bash +merobox run --count 2 +``` -- Capture backup strategy, upgrades, observability stack. -- Provide checklist for securing nodes in production. +## Monitoring ---- - -_Stub content: expand each section with concise instructions and canonical README links._ +See [Monitor & Debug](monitor-and-debug.md) for observability and troubleshooting. diff --git a/docs/operator-track/monitor-and-debug.md b/docs/operator-track/monitor-and-debug.md index f343576..4b41c77 100644 --- a/docs/operator-track/monitor-and-debug.md +++ b/docs/operator-track/monitor-and-debug.md @@ -1,7 +1,68 @@ # Monitor & Debug -_Stub page — outline observability tools and procedures._ +Observability and troubleshooting for Calimero nodes. -- TODO: Highlight Admin Dashboard, Node Console, log streams. -- TODO: Describe common health checks and alert thresholds. -- TODO: Link to troubleshooting sections in repo READMEs. +## Quick Health Checks + +```bash +# Check node health +meroctl --node-name node1 health + +# View logs +merobox logs node1 --follow + +# List contexts +meroctl --node-name node1 context list +``` + +## Admin Dashboard + +Access the web UI at `http://localhost:2528/admin-dashboard` (or your node URL). + +**Features:** +- Context management +- Application installation +- Identity management +- Metrics and stats + +## Monitoring Endpoints + +```bash +# Health check +curl http://localhost:2528/admin-api/health + +# Get peers count +curl http://localhost:2528/admin-api/peers-count + +# List contexts +curl http://localhost:2528/admin-api/contexts +``` + +## Logs + +```bash +# View node logs +merobox logs node1 + +# Follow logs in real-time +merobox logs node1 --follow + +# Or with Docker directly +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: +- Common issues and solutions +- Performance tuning +- Network problems +- Storage issues + +## Metrics + +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. diff --git a/docs/operator-track/run-a-local-network.md b/docs/operator-track/run-a-local-network.md index a8cae14..113388e 100644 --- a/docs/operator-track/run-a-local-network.md +++ b/docs/operator-track/run-a-local-network.md @@ -1,7 +1,53 @@ # Run a Local Network -_Stub page — outline requirements and bootstrap steps._ +Quick guide to running Calimero nodes locally for development and testing. -- TODO: List hardware prerequisites and Docker requirements. -- TODO: Provide `merobox` workflow example with explanation. -- TODO: Link to monitoring commands and health checks. +## 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. + +**Quick start:** +```bash +# Install merobox +pipx install merobox + +# Start 2-node network +merobox run --count 2 + +# Check status +merobox list +merobox health +``` + +**With workflow:** +```bash +merobox bootstrap run workflow.yml +``` + +## Using merod Directly + +For more control, run nodes directly: + +```bash +# Install merod +cargo install --path core/crates/merod + +# Start coordinator +merobox run --name node1 + +# Start peer +merobox run --name node2 +``` + +See [`core/crates/merod/README.md`](https://github.com/calimero-network/core/blob/master/crates/merod/README.md) for node options. + +## Requirements + +- Docker 20.10+ (for Merobox) +- Rust toolchain (if building from source) +- Python 3.8+ (for Merobox) + +## Next Steps + +- [Monitor & Debug](monitor-and-debug.md) - Observability and troubleshooting +- [Developer Tools](../tools-apis/developer-tools.md) - Merobox, ABI codegen, scaffolding diff --git a/docs/reference/index.md b/docs/reference/index.md index 4247b5f..0269f80 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,42 +1,19 @@ -# Reference +# API Reference -> Placeholder index — populate with method tables and schemas later. +API documentation for Calimero nodes and clients. -- [Commitments & Consistency Levels](commitments-consistency.md) -- [Response Envelope](response-envelope.md) -- [HTTP Methods](http-methods.md) -- [WebSocket Streams](websocket-streams.md) -- [Error Codes & Retries](error-codes.md) -- [Versioning & Changelog](versioning-changelog.md) +## Core API -## Commitments & Consistency Levels +| Topic | Documentation | Repository | +| --- | --- | --- | +| **HTTP Methods** | [API Methods](http-methods.md) | [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) | +| **WebSocket** | [WebSocket Streams](websocket-streams.md) | [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) | +| **Error Codes** | [Error Codes](error-codes.md) | [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) | -- Define processed/confirmed/finalized semantics. -- Plan to include comparison table. +## Additional Reference -## Response Envelope +- **JSON-RPC**: Standard JSON-RPC 2.0 over HTTP +- **WebSocket/SSE**: Real-time event subscriptions +- **Admin API**: Node management endpoints -- Document standard JSON structure (`context`, `value`, `error`). -- Note to provide sample payloads. - -## HTTP Methods - -- Group endpoints by domain (Contexts, Applications, Identity, Admin). -- Prepare tables with method, params, responses. - -## WebSocket Streams - -- Outline subscription flow and message formats. -- Add example subscribe/unsubscribe sequences. - -## Error Codes & Retries - -- List canonical codes and recommended handling. - -## Versioning & Changelog - -- Describe release cadence and links to repo changelogs. - ---- - -_This section is a scaffold; flesh out with canonical data once API audits conclude._ +For complete API documentation, see [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md). From 1fb151624edce393763292522e107d7bd2f6689c Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:31:16 -0300 Subject: [PATCH 14/22] docs: Reorganize documentation structure and fix graphs - Consolidate getting-started into single comprehensive guide - Remove all stub pages with TODOs (reference, examples, operator-track) - Fix graph sizes - simplify complex diagrams - Fix graph colors - use proper black/green theme - Update navigation structure - Fix broken links --- docs/builder-directory/js-sdk-guide.md | 73 ++--- docs/builder-directory/sdk-guide.md | 2 +- docs/core-concepts/applications.md | 31 +- docs/core-concepts/architecture.md | 27 +- docs/core-concepts/contexts.md | 2 +- docs/examples/additional-templates.md | 7 - docs/examples/battleships.md | 7 - docs/examples/core-apps-examples.md | 2 +- docs/examples/index.md | 60 ++-- docs/examples/shared-todo-backlog.md | 7 - docs/examples/split-bills.md | 7 - .../build-your-first-application.md | 7 - docs/getting-started/index.md | 274 ++++++++++++++---- .../getting-started/installation-checklist.md | 6 - .../launch-your-first-context.md | 7 - .../getting-started/sample-app-walkthrough.md | 7 - docs/intro/index.md | 2 +- docs/operator-track/join-existing-contexts.md | 7 - .../production-deployment-notes.md | 7 - docs/reference/commitments-consistency.md | 7 - docs/reference/error-codes.md | 7 - docs/reference/http-methods.md | 7 - docs/reference/index.md | 58 +++- docs/reference/response-envelope.md | 7 - docs/reference/versioning-changelog.md | 7 - docs/reference/websocket-streams.md | 7 - mkdocs.yml | 4 +- 27 files changed, 327 insertions(+), 319 deletions(-) delete mode 100644 docs/examples/additional-templates.md delete mode 100644 docs/examples/battleships.md delete mode 100644 docs/examples/shared-todo-backlog.md delete mode 100644 docs/examples/split-bills.md delete mode 100644 docs/getting-started/build-your-first-application.md delete mode 100644 docs/getting-started/installation-checklist.md delete mode 100644 docs/getting-started/launch-your-first-context.md delete mode 100644 docs/getting-started/sample-app-walkthrough.md delete mode 100644 docs/operator-track/join-existing-contexts.md delete mode 100644 docs/operator-track/production-deployment-notes.md delete mode 100644 docs/reference/commitments-consistency.md delete mode 100644 docs/reference/error-codes.md delete mode 100644 docs/reference/http-methods.md delete mode 100644 docs/reference/response-envelope.md delete mode 100644 docs/reference/versioning-changelog.md delete mode 100644 docs/reference/websocket-streams.md diff --git a/docs/builder-directory/js-sdk-guide.md b/docs/builder-directory/js-sdk-guide.md index b0584eb..7d64dbc 100644 --- a/docs/builder-directory/js-sdk-guide.md +++ b/docs/builder-directory/js-sdk-guide.md @@ -23,70 +23,31 @@ The JavaScript SDK (`calimero-sdk-js`) consists of two main packages: ### Build Pipeline ```mermaid -flowchart TD - TS[TypeScript Source] - TC[TypeScript Compiler] - JS[JavaScript ES6 modules] - ROLLUP[Rollup Bundle with dependencies] - BUNDLE[JavaScript Bundle] - QJSC[QuickJS qjsc Compile to C bytecode] - CODEH[code.h C header] - EXTRACT[Extract Methods Parse AST] - METHODS[methods.h C header] - CLANG[Clang/WASI-SDK Compile to WASM] - WASM[WASM Binary] - OPT[wasi-stub + wasm-opt Optimize] - FINAL[Final Service ~500KB] - - TS --> TC - TC --> JS - JS --> ROLLUP - ROLLUP --> BUNDLE - BUNDLE --> QJSC - QJSC --> CODEH - CODEH --> EXTRACT - EXTRACT --> METHODS - METHODS --> CLANG - CLANG --> WASM - WASM --> OPT - OPT --> FINAL +flowchart LR + TS[TypeScript
Source] --> BUILD[Build
Bundle] + BUILD --> QJS[QuickJS
Compile] + QJS --> WASM[WASI-SDK
to WASM] + WASM --> OPT[Optimize
~500KB] style TS fill:#ffffff,stroke:#000000,stroke-width:2px - style FINAL fill:#e5ffe5,stroke:#000000,stroke-width:3px + style BUILD fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style QJS fill:#ffffff,stroke:#000000,stroke-width:2px + style WASM fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style OPT fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` ### Runtime Execution ```mermaid -graph TB - subgraph "JavaScript Application" - JS[Your code with decorators] - end - - subgraph "@calimero/sdk" - SDK[Decorators, CRDT Collections, Event System] - end - - subgraph "QuickJS Runtime (in WASM)" - QJS[JavaScript interpreter
~450KB overhead] - end - - subgraph "Calimero Host Functions" - HOST[storage_read/write
emit/commit
context_id/executor_id] - end - - subgraph "Calimero Runtime (Wasmer)" - RUNTIME[WASM execution
P2P synchronization
Storage RocksDB] - end - - JS --> SDK - SDK --> QJS - QJS --> HOST - HOST --> RUNTIME +flowchart LR + JS[JavaScript
Your code] --> SDK[SDK
Decorators] + SDK --> QJS[QuickJS
Runtime] + QJS --> HOST[Host
Functions] + HOST --> RUNTIME[Calimero
Runtime] style JS fill:#ffffff,stroke:#000000,stroke-width:2px - style SDK fill:#e5ffe5,stroke:#000000,stroke-width:2px - style QJS fill:#ffffff,stroke:#00ff00,stroke-width:2px + style SDK fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style QJS fill:#ffffff,stroke:#000000,stroke-width:2px style HOST fill:#e5ffe5,stroke:#00ff00,stroke-width:2px style RUNTIME fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` @@ -893,5 +854,5 @@ For detailed JavaScript SDK documentation: - [SDK Guide (Rust)](sdk-guide.md) - Building with Rust SDK - [Applications](../core-concepts/applications.md) - Application architecture overview - [Core Apps Examples](../examples/core-apps-examples.md) - Rust SDK examples -- [Build Your First Application](../getting-started/build-your-first-application.md) - Tutorial +- [Getting Started](../getting-started/index.md) - Complete getting started guide diff --git a/docs/builder-directory/sdk-guide.md b/docs/builder-directory/sdk-guide.md index a8de8bf..a9b4d21 100644 --- a/docs/builder-directory/sdk-guide.md +++ b/docs/builder-directory/sdk-guide.md @@ -420,7 +420,7 @@ For detailed SDK documentation: ## Related Topics -- [Build Your First Application](../getting-started/build-your-first-application.md) - Step-by-step tutorial +- [Getting Started](../getting-started/index.md) - Complete getting started guide - [Applications](../core-concepts/applications.md) - Application architecture overview - [Core Apps Examples](../examples/core-apps-examples.md) - Reference implementations diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index b21f19e..484b2dc 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -42,28 +42,17 @@ Build and deploy with [`meroctl`](../tools-apis/meroctl-cli.md). See [SDK Guide] ```mermaid sequenceDiagram - participant Client as JSON-RPC Client - participant Node as Node Runtime - participant WASM as WASM Module - participant Storage as CRDT Storage - participant Network as P2P Network - Client->>Node: call("add_item", args) - Node->>WASM: execute(method, args) - - rect rgb(220, 237, 255) - Note over WASM,Storage: Transaction Execution - WASM->>Storage: map.insert(key, value) - Storage->>Storage: Generate Action::Update - Storage->>Storage: Calculate Merkle hashes - Storage->>Storage: Collect in DELTA_CONTEXT - end - - WASM-->>Node: ExecutionOutcome {
root_hash, events, ...} + Node->>WASM: execute() + WASM->>Storage: CRDT operations + Storage->>Node: ExecutionOutcome + Node->>Network: Broadcast delta + Node->>Client: Result - Node->>Network: Broadcast StateDelta - Network->>Node: Propagate to peers - Node-->>Client: TransactionResult + style Client fill:#ffffff,stroke:#000000,stroke-width:2px + style Node fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style WASM fill:#ffffff,stroke:#000000,stroke-width:2px + style Storage fill:#e5ffe5,stroke:#00ff00,stroke-width:2px ``` ### Execution Model @@ -170,6 +159,6 @@ For detailed application development: ## Related Topics -- [Build Your First Application](../getting-started/build-your-first-application.md) - Step-by-step guide +- [Getting Started](../getting-started/index.md) - Complete getting started guide - [Contexts](contexts.md) - Application instances - [Architecture Overview](architecture.md) - How applications fit into the system diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index b438240..7dfd1b7 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -110,26 +110,19 @@ See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob ## DAG-Based Causal Ordering -The DAG (Directed Acyclic Graph) ensures that deltas are applied in the correct causal order, even when received out-of-order: +The DAG ensures deltas are applied in correct causal order, even when received out-of-order: ```mermaid -graph TB - subgraph "Concurrent Updates (Fork)" - F0[Delta 0
ROOT] - F1A[Delta 1A
parents: D0
Node A] - F1B[Delta 1B
parents: D0
Node B] - F2[Delta 2
parents: D1A, D1B
MERGE] - - F0 --> F1A - F0 --> F1B - F1A --> F2 - F1B --> F2 - end +graph LR + ROOT[Delta 0
ROOT] --> A[Delta 1A
Node A] + ROOT --> B[Delta 1B
Node B] + A --> MERGE[Delta 2
MERGE] + B --> MERGE - style F0 fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff - style F1A fill:#ffffff,stroke:#000000,stroke-width:2px - style F1B fill:#ffffff,stroke:#000000,stroke-width:2px - style F2 fill:#e5ffe5,stroke:#00ff00,stroke-width:3px + style ROOT fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style A fill:#ffffff,stroke:#000000,stroke-width:2px + style B fill:#ffffff,stroke:#000000,stroke-width:2px + style MERGE fill:#e5ffe5,stroke:#00ff00,stroke-width:3px ``` **Key properties**: diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index e0fdd0a..8d6220c 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -154,7 +154,7 @@ meroctl call --context-id --method add_item --args '{"key": "hello" **Subscribe to events:** - WebSocket: Connect to `ws://localhost:2528/ws` - Use `subscribe` method with `context_id` and `event_type` -- See [WebSocket Reference](../reference/websocket-streams.md) for details +- 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. diff --git a/docs/examples/additional-templates.md b/docs/examples/additional-templates.md deleted file mode 100644 index 07d8a68..0000000 --- a/docs/examples/additional-templates.md +++ /dev/null @@ -1,7 +0,0 @@ -# Additional Templates - -_Stub page — catalog other starter apps._ - -- TODO: List KV Store, Demo Blob App, Calimero Curb Chat with short summaries. -- TODO: Add status badges (Maintained/Experimental) when taxonomy is ready. -- TODO: Link to each repository README and workflows. diff --git a/docs/examples/battleships.md b/docs/examples/battleships.md deleted file mode 100644 index 13eba1a..0000000 --- a/docs/examples/battleships.md +++ /dev/null @@ -1,7 +0,0 @@ -# Battleships - -_Stub page — focal example for multiplayer workflow._ - -- TODO: Summarize architecture (context, players, private storage). -- TODO: Include setup steps and dev loop overview. -- TODO: Link to repo README and diagrams. diff --git a/docs/examples/core-apps-examples.md b/docs/examples/core-apps-examples.md index dab55dd..69becdb 100644 --- a/docs/examples/core-apps-examples.md +++ b/docs/examples/core-apps-examples.md @@ -332,7 +332,7 @@ meroctl --node calimero-node-1 call \ ## Related Topics - [SDK Guide](../builder-directory/sdk-guide.md) - Complete SDK reference -- [Build Your First Application](../getting-started/build-your-first-application.md) - Step-by-step tutorial +- [Build Your First Application](../getting-started/index.md) - Step-by-step tutorial - [Applications](../core-concepts/applications.md) - Application architecture ## Deep Dives diff --git a/docs/examples/index.md b/docs/examples/index.md index 3845792..8af2688 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -1,55 +1,49 @@ # Examples -Calimero examples range from simple starter apps to complex multi-context applications. Learn by exploring working code and adapting patterns to your own projects. +Learn Calimero by exploring working examples. All examples include source code, README files, and Merobox workflow configurations. ## Core Apps Examples -**Start here**: [Core Apps Examples](core-apps-examples.md) — Reference implementations from `core/apps` that demonstrate SDK patterns and CRDT usage. +**[Core Apps Examples](core-apps-examples.md)** — Reference implementations from `core/apps` demonstrating SDK patterns and CRDT usage. -These examples live in the [`calimero-network/core/apps`](https://github.com/calimero-network/core/tree/master/apps) directory and include: +These examples live in [`calimero-network/core/apps`](https://github.com/calimero-network/core/tree/master/apps): -- **kv-store** - Basic CRDT operations -- **blobs** - File/blob management +- **kv-store** - Basic CRDT operations, key-value storage +- **blobs** - File/blob management with content addressing - **collaborative-editor** - Text collaboration with RGA CRDT - **private-data** - Private storage patterns - **team-metrics** - Nested CRDT structures - **xcall-example** - Cross-context communication -Each example includes source code, README, and Merobox workflow files for easy testing. +**Quick start:** +```bash +cd core/apps/kv-store +./build.sh +meroctl --node-name node1 app install --path build/kv_store.wasm +``` ## Application Examples -- [Battleships](battleships.md) - Multiplayer game demonstrating real-time sync -- [Shared Todo Backlog](shared-todo-backlog.md) - CRDT patterns and UI workflows -- [Split Bills](split-bills.md) - Delegation and settlement flows -- [Additional Templates](additional-templates.md) - More examples and templates +For complete applications, see: -## Overview +- **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 +- **KV Store** - Template app - Created via `npx create-mero-app` -Examples are organized by complexity: +## By Complexity -- **Starter**: Basic CRDT usage (kv-store, simple counters) -- **Intermediate**: Event handling, blob management, nested structures -- **Advanced**: Cross-context calls, complex state machines, multi-context apps - -## Battleships - -- One-liner summary. -- TODO: link to README anchors and add diagram. - -## Shared Todo Backlog +Examples organized by difficulty: -- Highlight CRDT patterns and UI workflow. - -## Split Bills - -- Summarize delegation and settlement flows. - -## Additional Templates +- **Starter**: Basic CRDT usage (kv-store, counters) +- **Intermediate**: Event handling, blob management, nested structures +- **Advanced**: Cross-context calls, complex state machines -- KV Store, Demo Blob App, Calimero Curb Chat. -- Plan to add link list with status badges. +## Getting Started with Examples ---- +1. Clone or browse the repository +2. Read the README for setup instructions +3. Run `./build.sh` or `pnpm run logic:build` +4. Install on a local node using `meroctl` +5. Explore the code and adapt patterns to your app -_This is a scaffold; replace bullet notes with final copy and links._ +See [Getting Started](../getting-started/index.md) for installation and setup. diff --git a/docs/examples/shared-todo-backlog.md b/docs/examples/shared-todo-backlog.md deleted file mode 100644 index fe7e223..0000000 --- a/docs/examples/shared-todo-backlog.md +++ /dev/null @@ -1,7 +0,0 @@ -# Shared Todo Backlog - -_Stub page — collaborative CRDT example._ - -- TODO: Describe list synchronization and conflict resolution. -- TODO: Provide quickstart steps and UI highlights. -- TODO: Link to repo README and workflow assets. diff --git a/docs/examples/split-bills.md b/docs/examples/split-bills.md deleted file mode 100644 index 2690d42..0000000 --- a/docs/examples/split-bills.md +++ /dev/null @@ -1,7 +0,0 @@ -# Split Bills - -_Stub page — cover delegation and settlement flows._ - -- TODO: Summarize roles, ledger structure, and payment flow. -- TODO: List setup steps and configuration notes. -- TODO: Link to repository README and diagrams when ready. diff --git a/docs/getting-started/build-your-first-application.md b/docs/getting-started/build-your-first-application.md deleted file mode 100644 index 75ceda8..0000000 --- a/docs/getting-started/build-your-first-application.md +++ /dev/null @@ -1,7 +0,0 @@ -# Build Your First Application - -_Stub page — map the template scaffold and dev loop._ - -- TODO: Outline `npx create-mero-app` workflow and generated structure. -- TODO: Explain `pnpm logic:build` → ABI generation → frontend wiring. -- TODO: Link to `mero-devtools-js` README for deeper instructions. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 8efd5ba..79f5f83 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -8,59 +8,130 @@ Choose your path based on what you want to do: | Goal | Path | Time | | --- | --- | --- | -| **Run a local network** | [Installation Checklist](installation-checklist.md) → [Launch Your First Context](launch-your-first-context.md) | 10 min | -| **Build an application** | [Installation Checklist](installation-checklist.md) → [Build Your First Application](build-your-first-application.md) | 30 min | -| **Explore examples** | [Sample App Walkthrough](sample-app-walkthrough.md) | 15 min | +| **Run a local network** | Installation → Launch network | 10 min | +| **Build an application** | Installation → Create app → Deploy | 30 min | +| **Explore examples** | Installation → Run example | 15 min | -## Step 1: Installation Checklist +## Step 1: Installation -Before you begin, ensure you have the required tools installed: +### Prerequisites **Required:** -- Docker (for running nodes) -- Node.js 18+ (for client SDKs) -- Rust toolchain (for building applications) +- **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) -**Optional but recommended:** -- `merobox` (Python CLI for local development) +**Optional:** - `merod` and `meroctl` (if building from source) -[View full checklist →](installation-checklist.md) +### Install Merobox -## Step 2: Launch Your First Context +Merobox is the easiest way to run local Calimero networks: -Once you have the tools installed, launch a local network and create your first context: - -**Using Merobox (recommended):** ```bash -# Install merobox +# Using pipx (recommended) pipx install merobox -# Start local network +# Or on macOS with Homebrew +brew install calimero-network/tap/merobox + +# Verify installation +merobox --version +``` + +### Install Rust Toolchain (for building applications) + +```bash +# Install Rust +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# Add WASM target +rustup target add wasm32-unknown-unknown + +# Verify installation +cargo --version +rustc --version +``` + +### Install Node.js SDKs (for client development) + +```bash +# Install Calimero JavaScript SDK +npm install @calimero/sdk @calimero/cli + +# Or with pnpm +pnpm add @calimero/sdk @calimero/cli +``` + +See [`merobox/README.md`](https://github.com/calimero-network/merobox#readme) for complete installation options. + +## Step 2: Run a Local Network + +### Using Merobox (Recommended) + +```bash +# Start a 2-node network merobox run --count 2 -# Create context (via workflow or CLI) -meroctl context create --application-id +# Check status +merobox list + +# View logs +merobox logs node1 --follow +``` + +### Using Docker Directly + +```bash +# Start coordinator +docker run -p 2528:2528 ghcr.io/calimero-network/merod:edge \ + --node-type coordinator + +# Start peer (in another terminal) +docker run -p 2529:2528 ghcr.io/calimero-network/merod:edge \ + --node-type peer \ + --swarm-addrs /ip4/127.0.0.1/tcp/2428 ``` -**Using Docker directly:** +### Verify Network + ```bash -# Start coordinator node -docker run calimero/merod --node-type coordinator +# Check node health +meroctl --node-name node1 health -# Start peer node -docker run calimero/merod --node-type peer --swarm-addrs /ip4/127.0.0.1/tcp/2428 +# List contexts +meroctl --node-name node1 context list ``` -[Detailed guide →](launch-your-first-context.md) +See [Running Nodes](../operator-track/run-a-local-network.md) for detailed node management. ## Step 3: Build Your First Application -Now that you have a network running, build a simple application: +### Option A: Create from Template + +```bash +# Create a new application +npx create-mero-app my-first-app + +# Navigate to project +cd my-first-app + +# Install dependencies +pnpm install + +# Build Rust backend +pnpm run logic:build + +# This creates: +# - logic/build/my_first_app.wasm (WASM binary) +# - logic/build/my_first_app.abi.json (API definition) +``` + +### Option B: Build from Core Examples -**Quick start:** ```bash -# Clone example +# Clone core repository git clone https://github.com/calimero-network/core cd core/apps/kv-store @@ -68,62 +139,145 @@ cd core/apps/kv-store ./build.sh # Install on node -meroctl app install --path build/kv_store.wasm --context-id +meroctl --node-name node1 app install \ + --path build/kv_store.wasm ``` -**From scratch:** -1. Create new Rust project -2. Add Calimero SDK dependencies -3. Define state with `#[app::state]` -4. Implement logic with `#[app::logic]` -5. Build to WASM -6. Install on node +### Option C: Build from Scratch -[Detailed guide →](build-your-first-application.md) +**1. Create Rust project:** +```bash +cargo new --lib my-app +cd my-app +``` + +**2. Add dependencies to `Cargo.toml`:** +```toml +[dependencies] +calimero-sdk = { path = "../../crates/sdk" } +calimero-storage = { path = "../../crates/storage" } +``` + +**3. Write your application in `src/lib.rs`:** +```rust +use calimero_sdk::app; +use calimero_storage::collections::UnorderedMap; + +#[app::state] +pub struct MyApp { + items: UnorderedMap, +} + +#[app::logic] +impl MyApp { + pub fn add_item(&mut self, key: String, value: String) { + self.items.insert(key, value); + } + + #[app::view] + pub fn get_item(&self, key: &str) -> Option { + self.items.get(key) + } +} +``` + +**4. Build WASM:** +```bash +cargo build --target wasm32-unknown-unknown --release +``` -## Step 4: Explore Examples +**5. Install on node:** +```bash +meroctl --node-name node1 app install \ + --path target/wasm32-unknown-unknown/release/my_app.wasm +``` -Learn from working examples: +See [SDK Guide](../builder-directory/sdk-guide.md) or [JavaScript SDK Guide](../builder-directory/js-sdk-guide.md) for detailed development guides. -- **kv-store**: Simple key-value store - great for understanding basics -- **battleships**: Multiplayer game - demonstrates real-time sync -- **blobs**: File sharing - shows blob distribution +## Step 4: Create and Use a Context -[Walkthrough →](sample-app-walkthrough.md) +**Create a context:** +```bash +meroctl --node-name node1 context create \ + --application-id +``` -## What's Next? +**Call methods:** +```bash +# Call a mutation +meroctl --node-name node1 call \ + --context-id \ + --method add_item \ + --args '{"key": "hello", "value": "world"}' \ + --executor-public-key + +# Call a view +meroctl --node-name node1 call \ + --context-id \ + --method get_item \ + --args '{"key": "hello"}' +``` -After completing the getting started guide: +See [Contexts](../core-concepts/contexts.md) for context management details. + +## Step 5: Explore Examples + +### Core Examples + +Examples in [`core/apps`](https://github.com/calimero-network/core/tree/master/apps): + +- **kv-store** - Simple key-value store (great for learning basics) +- **blobs** - File/blob sharing with content addressing +- **collaborative-editor** - Text collaboration with RGA CRDT +- **private-data** - Private storage patterns +- **team-metrics** - Nested CRDT structures +- **xcall-example** - Cross-context communication + +**Run an example:** +```bash +cd core/apps/kv-store +./build.sh +meroctl --node-name node1 app install --path build/kv_store.wasm +``` + +### Application Examples + +- **Battleships** - Multiplayer game with real-time sync +- **Shared Todo** - Collaborative task list +- **KV Store** - Boilerplate template application + +See [Examples](../examples/index.md) for complete list. + +## What's Next? ### For Builders -- **[Core Concepts](../core-concepts/index.md)** - Deep dive into architecture -- **[Builder Directory](../builder-directory/index.md)** - Development resources -- **[Examples](../examples/index.md)** - More example applications -- **[Tools & APIs](../tools-apis/index.md)** - SDKs and tooling +- **[Core Concepts](../core-concepts/index.md)** - Deep dive into architecture, contexts, identity +- **[Rust SDK Guide](../builder-directory/sdk-guide.md)** - Complete Rust development guide +- **[JavaScript SDK Guide](../builder-directory/js-sdk-guide.md)** - JavaScript/TypeScript development +- **[Examples](../examples/core-apps-examples.md)** - Working example applications ### For Operators -- **[Operator Track](../operator-track/index.md)** - Running and managing nodes -- **[Reference](../reference/index.md)** - API documentation -- **[Monitor & Debug](../operator-track/monitor-and-debug.md)** - Observability +- **[Running Nodes](../operator-track/run-a-local-network.md)** - Node setup and management +- **[Monitoring](../operator-track/monitor-and-debug.md)** - Observability and troubleshooting +- **[meroctl CLI](../tools-apis/meroctl-cli.md)** - Command-line reference ### For Everyone -- **[Architecture Overview](../core-concepts/architecture.md)** - How it all works -- **[Privacy & Security](../privacy-verifiability-security/index.md)** - Security model -- **[GitHub Discussions](https://github.com/calimero-network/core/discussions)** - Get help and contribute +- **[Architecture Overview](../core-concepts/architecture.md)** - How Calimero works +- **[Tools & APIs](../tools-apis/index.md)** - SDKs, CLI, developer tools ## Common Questions **Q: Do I need to run my own node?** -A: For local development, yes. For production, you can use hosted nodes or run your own. +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 are written in Rust (compiled to WASM). Clients can use JavaScript/TypeScript or Python. +A: Applications can be written in Rust (compiled to WASM) or JavaScript/TypeScript (using `@calimero/sdk`). 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). +A: Calimero supports wallet-based authentication (NEAR, Ethereum, ICP). 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. @@ -133,7 +287,3 @@ A: Yes! Calimero is offline-first. Apps work offline and sync when online. - **Discord**: [Join our community](https://discord.gg/wZRC73DVpU) - **GitHub Issues**: [Report bugs or ask questions](https://github.com/calimero-network/core/issues) - **Documentation**: Browse the docs for detailed guides - ---- - -**Ready to start?** Begin with the [Installation Checklist](installation-checklist.md)! diff --git a/docs/getting-started/installation-checklist.md b/docs/getting-started/installation-checklist.md deleted file mode 100644 index 4a7d71f..0000000 --- a/docs/getting-started/installation-checklist.md +++ /dev/null @@ -1,6 +0,0 @@ -# Installation Checklist - -_Stub page — outline required tooling (Docker, `merod`, `meroctl`, `merobox`) and platform-specific setup steps here._ - -- TODO: Add quick install commands for macOS, Linux, Windows. -- TODO: Link to package references and Homebrew tap. diff --git a/docs/getting-started/launch-your-first-context.md b/docs/getting-started/launch-your-first-context.md deleted file mode 100644 index baf9d33..0000000 --- a/docs/getting-started/launch-your-first-context.md +++ /dev/null @@ -1,7 +0,0 @@ -# Launch Your First Context - -_Stub page — detail the Merobox workflow for bootstrapping a local network._ - -- TODO: Provide step-by-step commands using `merobox` workflows. -- TODO: Include diagram depicting nodes, context, Application ID capture. -- TODO: Link back to `merobox` README for full instructions. diff --git a/docs/getting-started/sample-app-walkthrough.md b/docs/getting-started/sample-app-walkthrough.md deleted file mode 100644 index 3414c8d..0000000 --- a/docs/getting-started/sample-app-walkthrough.md +++ /dev/null @@ -1,7 +0,0 @@ -# Sample App Walkthrough - -_Stub page — use Battleships as the reference implementation._ - -- TODO: Summarize gameplay flow and architecture diagram. -- TODO: Provide quick steps to clone, bootstrap, and iterate. -- TODO: Link to other examples once write-ups exist. diff --git a/docs/intro/index.md b/docs/intro/index.md index 461f276..5ae231e 100644 --- a/docs/intro/index.md +++ b/docs/intro/index.md @@ -59,7 +59,7 @@ See [Example Applications](../examples/index.md) for working implementations. | If you are… | Start here | | --- | --- | -| **Building apps** | [Build Your First Application](../getting-started/build-your-first-application.md) → [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/master/crates/sdk/README.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) | | **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) | diff --git a/docs/operator-track/join-existing-contexts.md b/docs/operator-track/join-existing-contexts.md deleted file mode 100644 index ae58935..0000000 --- a/docs/operator-track/join-existing-contexts.md +++ /dev/null @@ -1,7 +0,0 @@ -# Join Existing Contexts - -_Stub page — explain invitations and membership management._ - -- TODO: Document invite issuance, acceptance, and key rotation. -- TODO: Reference admin API endpoints for context membership. -- TODO: Add flow diagram showing invite lifecycle. diff --git a/docs/operator-track/production-deployment-notes.md b/docs/operator-track/production-deployment-notes.md deleted file mode 100644 index 5e777de..0000000 --- a/docs/operator-track/production-deployment-notes.md +++ /dev/null @@ -1,7 +0,0 @@ -# Production Deployment Notes - -_Stub page — provide guidance for running Calimero in production._ - -- TODO: Document backup strategy, node upgrades, rolling deployments. -- TODO: Summarize security hardening (firewalls, key rotation, monitoring). -- TODO: Link to infra-as-code examples or reference architectures. diff --git a/docs/reference/commitments-consistency.md b/docs/reference/commitments-consistency.md deleted file mode 100644 index 9722508..0000000 --- a/docs/reference/commitments-consistency.md +++ /dev/null @@ -1,7 +0,0 @@ -# Commitments & Consistency Levels - -_Stub page — define processed, confirmed, finalized semantics._ - -- TODO: Provide comparison table across commitment levels. -- TODO: Explain how checkpoints and proofs tie into each level. -- TODO: Link to runtime documentation for detailed guarantees. diff --git a/docs/reference/error-codes.md b/docs/reference/error-codes.md deleted file mode 100644 index 4a9415f..0000000 --- a/docs/reference/error-codes.md +++ /dev/null @@ -1,7 +0,0 @@ -# Error Codes & Retries - -_Stub page — summarize canonical errors and retry guidance._ - -- TODO: List standard error codes with meanings. -- TODO: Recommend retry/backoff strategies per code category. -- TODO: Link to troubleshooting sections in tooling READMEs. diff --git a/docs/reference/http-methods.md b/docs/reference/http-methods.md deleted file mode 100644 index f5beed9..0000000 --- a/docs/reference/http-methods.md +++ /dev/null @@ -1,7 +0,0 @@ -# HTTP Methods - -_Stub page — catalog Calimero HTTP endpoints._ - -- TODO: Group methods by domain (Contexts, Applications, Identity, Admin). -- TODO: Provide tables with method, parameters, response shape, notes. -- TODO: Link to auto-generated API specs once available. diff --git a/docs/reference/index.md b/docs/reference/index.md index 0269f80..b14877a 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,19 +1,53 @@ # API Reference -API documentation for Calimero nodes and clients. +Complete API documentation for Calimero nodes and clients. -## Core API +## Server API -| Topic | Documentation | Repository | -| --- | --- | --- | -| **HTTP Methods** | [API Methods](http-methods.md) | [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) | -| **WebSocket** | [WebSocket Streams](websocket-streams.md) | [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) | -| **Error Codes** | [Error Codes](error-codes.md) | [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md) | +Calimero nodes expose a JSON-RPC API over HTTP with WebSocket support for real-time subscriptions. -## Additional Reference +**Base URL**: `http://localhost:2528` (default) -- **JSON-RPC**: Standard JSON-RPC 2.0 over HTTP -- **WebSocket/SSE**: Real-time event subscriptions -- **Admin API**: Node management endpoints +### Endpoints -For complete API documentation, see [`core/crates/server/README.md`](https://github.com/calimero-network/core/blob/master/crates/server/README.md). +- **JSON-RPC**: `/jsonrpc` - Standard JSON-RPC 2.0 calls +- **WebSocket**: `/ws` - Real-time subscriptions +- **SSE**: `/sse` - Server-Sent Events for subscriptions +- **Admin API**: `/admin-api/` - Node management endpoints + +### API Methods + +Common methods: +- `context.create` - Create a new context +- `context.list` - List all contexts +- `context.call` - Call a method on a context +- `app.install` - Install an application +- `identity.create` - Create an identity + +### Authentication + +Most endpoints require JWT authentication. See [Identity](../core-concepts/identity.md) for authentication flows. + +## Complete Documentation + +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)** + +## 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) + +## CLI Reference + +For command-line operations, see [`meroctl` CLI](../tools-apis/meroctl-cli.md). + +## Related Topics + +- [Tools & APIs](../tools-apis/index.md) - SDKs and developer tools +- [Core Concepts](../core-concepts/index.md) - Architecture and concepts +- [Running Nodes](../operator-track/run-a-local-network.md) - Node setup diff --git a/docs/reference/response-envelope.md b/docs/reference/response-envelope.md deleted file mode 100644 index 7c1adb0..0000000 --- a/docs/reference/response-envelope.md +++ /dev/null @@ -1,7 +0,0 @@ -# Response Envelope - -_Stub page — document the standard Calimero API response structure._ - -- TODO: Show JSON schema with `context`, `value`, `error` fields. -- TODO: Include success and failure examples. -- TODO: Reference SDK sections for typed client handling. diff --git a/docs/reference/versioning-changelog.md b/docs/reference/versioning-changelog.md deleted file mode 100644 index 9a84275..0000000 --- a/docs/reference/versioning-changelog.md +++ /dev/null @@ -1,7 +0,0 @@ -# Versioning & Changelog - -_Stub page — outline release cadence and change tracking._ - -- TODO: Describe how versions are tagged across repos. -- TODO: Link to individual `CHANGELOG.md` files. -- TODO: Explain how future site changelog aggregates updates. diff --git a/docs/reference/websocket-streams.md b/docs/reference/websocket-streams.md deleted file mode 100644 index 7d3bd5d..0000000 --- a/docs/reference/websocket-streams.md +++ /dev/null @@ -1,7 +0,0 @@ -# WebSocket Streams - -_Stub page — describe subscription and event streaming._ - -- TODO: Outline subscribe/unsubscribe flow and payload format. -- TODO: Provide sample messages and reconnection guidance. -- TODO: Reference client SDK sections handling real-time updates. diff --git a/mkdocs.yml b/mkdocs.yml index e74f114..dc8ca3f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -142,9 +142,7 @@ nav: - Client SDKs: tools-apis/client-sdks.md - Developer Tools: tools-apis/developer-tools.md - Reference: - - API Methods: reference/http-methods.md - - WebSocket: reference/websocket-streams.md - - Error Codes: reference/error-codes.md + - API Reference: reference/index.md # Extra configuration extra: From 5b68567b869c5508517926ffb391d06caff602bd Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:31:43 -0300 Subject: [PATCH 15/22] fix: Fix last broken link in core-concepts/index.md --- docs/core-concepts/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md index 6c06284..fc8b83c 100644 --- a/docs/core-concepts/index.md +++ b/docs/core-concepts/index.md @@ -131,7 +131,7 @@ graph TB - [Running Nodes](../operator-track/run-a-local-network.md) - Setup and deployment - [Monitoring](../operator-track/monitor-and-debug.md) - Observability -- [API Reference](../reference/http-methods.md) - HTTP endpoints +- [API Reference](../reference/index.md) - Complete API documentation --- From 30f0dcc0ff01086775b880a043f81f1c7c3002b6 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:35:11 -0300 Subject: [PATCH 16/22] fix: Fix Mermaid graph syntax errors and improve readability - Convert sequenceDiagram to flowchart (sequence diagrams don't support styles) - Simplify node labels (remove long text) - Change 'graph TB' to 'flowchart TD/LR' (modern syntax) - Remove nested subgraphs where possible - Shorten all labels for better readability - Fix syntax errors in all diagrams --- docs/core-concepts/applications.md | 21 ++--- docs/core-concepts/architecture.md | 139 ++++++++++++----------------- docs/core-concepts/contexts.md | 20 ++--- docs/core-concepts/identity.md | 19 ++-- docs/core-concepts/index.md | 33 ++++--- docs/core-concepts/nodes.md | 15 ++-- 6 files changed, 104 insertions(+), 143 deletions(-) diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index 484b2dc..a2a0e35 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -41,18 +41,19 @@ Build and deploy with [`meroctl`](../tools-apis/meroctl-cli.md). See [SDK Guide] ### WASM Execution Flow ```mermaid -sequenceDiagram - Client->>Node: call("add_item", args) - Node->>WASM: execute() - WASM->>Storage: CRDT operations - Storage->>Node: ExecutionOutcome - Node->>Network: Broadcast delta - Node->>Client: Result +flowchart LR + CLIENT[Client] --> NODE[Node] + NODE --> WASM[WASM] + WASM --> STORAGE[Storage] + STORAGE --> NODE + NODE --> NETWORK[Network] + NODE --> CLIENT - style Client fill:#ffffff,stroke:#000000,stroke-width:2px - style Node fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style CLIENT fill:#ffffff,stroke:#000000,stroke-width:2px + style NODE fill:#e5ffe5,stroke:#00ff00,stroke-width:2px style WASM fill:#ffffff,stroke:#000000,stroke-width:2px - style Storage fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style STORAGE fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style NETWORK fill:#ffffff,stroke:#00ff00,stroke-width:2px ``` ### Execution Model diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index 7dfd1b7..4e7580d 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -5,16 +5,16 @@ Calimero's architecture consists of four main layers that work together to enabl ## Four-Layer Architecture ```mermaid -graph TB - APP[Application Layer
WASM apps + SDK
CRDT collections
Event emission] - NODE[Node Layer
Synchronization & execution
Dual sync paths
Event handlers
Blob distribution] - STORAGE[Storage Layer
CRDT storage
DAG causal ordering
Out-of-order handling
Merkle trees] - NETWORK[Network Layer
libp2p P2P
JSON-RPC server
WebSocket/SSE
Authentication] +flowchart TD + APP[Application
WASM apps & SDK] + NODE[Node
Sync & execution] + STORAGE[Storage
CRDT & DAG] + NETWORK[Network
P2P & APIs] - APP -->|executes| NODE - NODE -->|stores| STORAGE - STORAGE -->|syncs via| NETWORK - NETWORK -->|provides| NODE + APP --> NODE + NODE --> STORAGE + STORAGE --> NETWORK + NETWORK --> NODE style APP fill:#e5ffe5,stroke:#000000,stroke-width:3px style NODE fill:#ffffff,stroke:#00ff00,stroke-width:3px @@ -24,36 +24,23 @@ graph TB ## Transaction Flow -**Simple view:** +**Transaction Flow:** ```mermaid -sequenceDiagram - Client->>Node: call("add_item", args) - Node->>WASM: execute() - WASM->>Storage: CRDT operations - Storage->>Node: ExecutionOutcome - Node->>Network: Broadcast delta - Network->>Peer: Propagate (~100ms) - Node->>Client: Result - - style Client fill:#ffffff,stroke:#000000 - style Node fill:#e5ffe5,stroke:#00ff00 - style WASM fill:#ffffff,stroke:#000000 -``` - -**Detailed execution:** -```mermaid -sequenceDiagram - WASM->>Storage: map.insert(key, value) - Storage->>Storage: Generate Action - Storage->>Storage: Calculate Merkle hash - Storage->>Storage: Collect in DELTA_CONTEXT - Storage->>Node: Return ExecutionOutcome - Node->>DAG: Create CausalDelta - Node->>Network: Broadcast via Gossipsub +flowchart LR + CLIENT[Client
RPC call] --> NODE[Node
Execute] + NODE --> WASM[WASM
Process] + WASM --> STORAGE[Storage
CRDT ops] + STORAGE --> NODE + NODE --> NETWORK[Network
Broadcast] + NETWORK --> PEER[Peer
~100ms] + NODE --> CLIENT - style WASM fill:#ffffff,stroke:#000000 - style Storage fill:#e5ffe5,stroke:#00ff00 - style Node fill:#ffffff,stroke:#00ff00 + style CLIENT fill:#ffffff,stroke:#000000,stroke-width:2px + style NODE fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style WASM fill:#ffffff,stroke:#000000,stroke-width:2px + style STORAGE fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style NETWORK fill:#ffffff,stroke:#00ff00,stroke-width:2px + style PEER fill:#e5ffe5,stroke:#000000,stroke-width:2px ``` See [`core/crates/runtime/README.md`](https://github.com/calimero-network/core/blob/master/crates/runtime/README.md) for execution details. @@ -68,38 +55,38 @@ Fast real-time propagation (~100-200ms): ```mermaid flowchart LR - A[Transaction
executed] --> B[Create
CausalDelta] - B --> C[Broadcast via
Gossipsub] - C --> D[All peers receive
~100-200ms] - D --> E{Parents
ready?} - E -->|Yes| F[Apply
immediately] - E -->|No| G[Buffer as
pending] - F --> H[Execute
event handlers] + TXN[Execute] --> DELTA[Create Delta] + DELTA --> GOSSIP[Gossipsub] + GOSSIP --> RECEIVE[Peers receive] + RECEIVE --> READY{Ready?} + READY -->|Yes| APPLY[Apply] + READY -->|No| BUFFER[Buffer] + APPLY --> EVENTS[Events] - style A fill:#ffffff,stroke:#000000,stroke-width:2px - style F fill:#e5ffe5,stroke:#00ff00,stroke-width:3px - style H fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style G fill:#ffffff,stroke:#00ff00,stroke-width:2px + style TXN fill:#ffffff,stroke:#000000,stroke-width:2px + style APPLY fill:#e5ffe5,stroke:#00ff00,stroke-width:3px + style EVENTS fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style BUFFER fill:#ffffff,stroke:#00ff00,stroke-width:2px ``` ### Path 2: Periodic P2P Sync (Fallback) -Catch-up every 10-30 seconds for eventual consistency: +Catch-up every 10-30 seconds: ```mermaid flowchart LR - T[SyncManager
timer] --> S[Select
random peer] - S --> O[Open P2P
stream] - O --> X[Exchange
DAG heads] - X --> D{Heads
differ?} - D -->|Yes| R[Request
missing deltas] - D -->|No| C[Up to date] - R --> A[Apply
deltas] - A --> C + TIMER[Timer] --> PEER[Select Peer] + PEER --> STREAM[Open Stream] + STREAM --> HEADS[Exchange Heads] + HEADS --> DIFF{Differ?} + DIFF -->|Yes| REQUEST[Request Deltas] + DIFF -->|No| SYNC[Synced] + REQUEST --> APPLY2[Apply] + APPLY2 --> SYNC - style T fill:#ffffff,stroke:#000000,stroke-width:2px - style C fill:#e5ffe5,stroke:#00ff00,stroke-width:3px - style A fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style TIMER fill:#ffffff,stroke:#000000,stroke-width:2px + style SYNC fill:#e5ffe5,stroke:#00ff00,stroke-width:3px + style APPLY2 fill:#e5ffe5,stroke:#00ff00,stroke-width:2px ``` **Why both paths?** @@ -110,13 +97,13 @@ See [`core/crates/node/README.md`](https://github.com/calimero-network/core/blob ## DAG-Based Causal Ordering -The DAG ensures deltas are applied in correct causal order, even when received out-of-order: +The DAG ensures deltas are applied in correct causal order: ```mermaid -graph LR - ROOT[Delta 0
ROOT] --> A[Delta 1A
Node A] - ROOT --> B[Delta 1B
Node B] - A --> MERGE[Delta 2
MERGE] +flowchart LR + ROOT[Root] --> A[Delta A] + ROOT --> B[Delta B] + A --> MERGE[Merge] B --> MERGE style ROOT fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff @@ -134,21 +121,13 @@ graph LR ## Key Components ```mermaid -graph TB - SDK[SDK
crates/sdk] - RUNTIME[Runtime
crates/runtime] - STORAGE[Storage
crates/storage] - DAG[DAG
crates/dag] - NODE[Node
crates/node] - NETWORK[Network
crates/network] - SERVER[Server
crates/server] - - SDK -->|executes via| RUNTIME - RUNTIME -->|uses| STORAGE - STORAGE -->|tracks in| DAG - NODE -->|orchestrates| RUNTIME - NODE -->|syncs via| NETWORK - SERVER -->|exposes| NODE +flowchart TD + SDK[SDK] --> RUNTIME[Runtime] + RUNTIME --> STORAGE[Storage] + STORAGE --> DAG[DAG] + NODE[Node] --> RUNTIME + NODE --> NETWORK[Network] + SERVER[Server] --> NODE style SDK fill:#e5ffe5,stroke:#000000,stroke-width:2px style RUNTIME fill:#ffffff,stroke:#00ff00,stroke-width:2px diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index 8d6220c..7f47c67 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -97,21 +97,13 @@ Context members have different permission levels: ## State Isolation Model ```mermaid -graph TB - subgraph "Context A" - CRDT1[Shared CRDT State
UnorderedMap, Vector, Counter
Replicated across nodes] - PRIVATE1[Private Storage
Node-local secrets
Never synced] - end +flowchart LR + CTX1[Context A
Shared State] --> PRIVATE1[Private
Storage] + CTX2[Context B
Shared State] --> PRIVATE2[Private
Storage] + CTX1 -.->|isolated| CTX2 - subgraph "Context B" - CRDT2[Shared CRDT State
Different data
Different members] - PRIVATE2[Private Storage
Node-local only] - end - - CRDT1 -.->|isolated| CRDT2 - - style CRDT1 fill:#e5ffe5,stroke:#000000,stroke-width:3px - style CRDT2 fill:#e5ffe5,stroke:#000000,stroke-width:3px + style CTX1 fill:#e5ffe5,stroke:#000000,stroke-width:2px + style CTX2 fill:#e5ffe5,stroke:#000000,stroke-width:2px style PRIVATE1 fill:#ffffff,stroke:#00ff00,stroke-width:2px style PRIVATE2 fill:#ffffff,stroke:#00ff00,stroke-width:2px ``` diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index 958044f..30d9b1f 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -7,19 +7,14 @@ Calimero uses **cryptographic identities** to manage access control and authenti Calimero supports a hierarchical identity model: ```mermaid -graph TD - ROOT[Root Key
Master Identity
alice.near] - CLIENT1[Client Key 1
Context A
ed25519:abc...] - CLIENT2[Client Key 2
Context B
ed25519:def...] - CLIENT3[Client Key 3
Context C
ed25519:ghi...] +flowchart TD + ROOT[Root Key
alice.near] --> CLIENT1[Client Key A] + ROOT --> CLIENT2[Client Key B] + ROOT --> CLIENT3[Client Key C] - ROOT -->|derives| CLIENT1 - ROOT -->|derives| CLIENT2 - ROOT -->|derives| CLIENT3 - - CLIENT1 -->|signs transactions| CTX1[Context A] - CLIENT2 -->|signs transactions| CTX2[Context B] - CLIENT3 -->|signs transactions| CTX3[Context C] + CLIENT1 --> CTX1[Context A] + CLIENT2 --> CTX2[Context B] + CLIENT3 --> CTX3[Context C] style ROOT fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff style CLIENT1 fill:#e5ffe5,stroke:#000000,stroke-width:2px diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md index fc8b83c..105c648 100644 --- a/docs/core-concepts/index.md +++ b/docs/core-concepts/index.md @@ -90,25 +90,24 @@ The **Architecture Overview** explains how all components work together: ## How Concepts Relate ```mermaid -graph TB - subgraph "Node (merod)" - subgraph "Context A" - APP1[Application WASM
CRDT State + Events] - MEMBERS1[Members Identities
Root Key: alice.near
Client Key: ed25519...] - end - subgraph "Context B" - APP2[Application WASM
CRDT State + Events] - MEMBERS2[Members Identities
Root Key: bob.near
Client Key: ed25519...] - end - end +flowchart LR + NODE[Node
merod] + CTX1[Context A
App + State] + CTX2[Context B
App + State] + ID1[Identity A
alice.near] + ID2[Identity B
bob.near] - APP1 -.->|isolated state| APP2 - MEMBERS1 -.->|separate access| MEMBERS2 + NODE --> CTX1 + NODE --> CTX2 + ID1 --> CTX1 + ID2 --> CTX2 + CTX1 -.->|isolated| CTX2 - style APP1 fill:#e5ffe5,stroke:#000000,stroke-width:3px - style APP2 fill:#e5ffe5,stroke:#000000,stroke-width:3px - style MEMBERS1 fill:#ffffff,stroke:#00ff00,stroke-width:2px - style MEMBERS2 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style NODE fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CTX1 fill:#e5ffe5,stroke:#000000,stroke-width:2px + style CTX2 fill:#e5ffe5,stroke:#000000,stroke-width:2px + style ID1 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style ID2 fill:#ffffff,stroke:#00ff00,stroke-width:2px ``` ## Learning Path diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md index 06e56c8..2a473e5 100644 --- a/docs/core-concepts/nodes.md +++ b/docs/core-concepts/nodes.md @@ -34,17 +34,12 @@ merod --node-type peer --swarm-addrs /ip4/127.0.0.1/tcp/2428 ## Node Architecture ```mermaid -graph TB - NODEMGR[NodeManager Actix Actor
Orchestrates all components
Periodic timers cleanup heartbeat] - CLIENTS[NodeClients
Context Node] - MANAGERS[NodeManagers
BlobManager SyncManager] - STATE[NodeState
BlobCache DeltaStores] +flowchart TD + MGR[NodeManager
Orchestrator] --> CLIENTS[Clients
Context & Node] + MGR --> MANAGERS[Managers
Blob & Sync] + MGR --> STATE[State
Cache & Deltas] - NODEMGR -->|manages| CLIENTS - NODEMGR -->|manages| MANAGERS - NODEMGR -->|manages| STATE - - style NODEMGR fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style MGR fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff style CLIENTS fill:#e5ffe5,stroke:#000000,stroke-width:2px style MANAGERS fill:#ffffff,stroke:#00ff00,stroke-width:2px style STATE fill:#e5ffe5,stroke:#000000,stroke-width:2px From 422fae813227bbe690a304ddcddd32caeab9a454 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:37:29 -0300 Subject: [PATCH 17/22] fix: Update all graphs to use dark fills with green borders for visibility - Change all nodes to dark fills (#1a1a1a) with green borders (#00ff00) - Set white text color for all nodes - Match the working style from Periodic P2P Sync graph - Ensure all graphs are visible on dark backgrounds --- docs/core-concepts/architecture.md | 65 +++++++++++++++++------------- 1 file changed, 37 insertions(+), 28 deletions(-) diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index 4e7580d..8b0e0a0 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -16,10 +16,10 @@ flowchart TD STORAGE --> NETWORK NETWORK --> NODE - style APP fill:#e5ffe5,stroke:#000000,stroke-width:3px - style NODE fill:#ffffff,stroke:#00ff00,stroke-width:3px - style STORAGE fill:#e5ffe5,stroke:#000000,stroke-width:3px - style NETWORK fill:#ffffff,stroke:#00ff00,stroke-width:3px + style APP fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style NODE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style STORAGE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style NETWORK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` ## Transaction Flow @@ -35,12 +35,12 @@ flowchart LR NETWORK --> PEER[Peer
~100ms] NODE --> CLIENT - style CLIENT fill:#ffffff,stroke:#000000,stroke-width:2px - style NODE fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style WASM fill:#ffffff,stroke:#000000,stroke-width:2px - style STORAGE fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style NETWORK fill:#ffffff,stroke:#00ff00,stroke-width:2px - style PEER fill:#e5ffe5,stroke:#000000,stroke-width:2px + style CLIENT fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style NODE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style WASM fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style STORAGE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style NETWORK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + 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. @@ -63,10 +63,14 @@ flowchart LR READY -->|No| BUFFER[Buffer] APPLY --> EVENTS[Events] - style TXN fill:#ffffff,stroke:#000000,stroke-width:2px - style APPLY fill:#e5ffe5,stroke:#00ff00,stroke-width:3px - style EVENTS fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style BUFFER fill:#ffffff,stroke:#00ff00,stroke-width:2px + style TXN fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style DELTA fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style GOSSIP fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style RECEIVE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style READY fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style APPLY fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style EVENTS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style BUFFER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` ### Path 2: Periodic P2P Sync (Fallback) @@ -84,9 +88,14 @@ flowchart LR REQUEST --> APPLY2[Apply] APPLY2 --> SYNC - style TIMER fill:#ffffff,stroke:#000000,stroke-width:2px - style SYNC fill:#e5ffe5,stroke:#00ff00,stroke-width:3px - style APPLY2 fill:#e5ffe5,stroke:#00ff00,stroke-width:2px + style TIMER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style PEER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style STREAM fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style HEADS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style DIFF fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style REQUEST fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style APPLY2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style SYNC fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff ``` **Why both paths?** @@ -106,10 +115,10 @@ flowchart LR A --> MERGE[Merge] B --> MERGE - style ROOT fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff - style A fill:#ffffff,stroke:#000000,stroke-width:2px - style B fill:#ffffff,stroke:#000000,stroke-width:2px - style MERGE fill:#e5ffe5,stroke:#00ff00,stroke-width:3px + style ROOT fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style A fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style B fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style MERGE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff ``` **Key properties**: @@ -129,13 +138,13 @@ flowchart TD NODE --> NETWORK[Network] SERVER[Server] --> NODE - style SDK fill:#e5ffe5,stroke:#000000,stroke-width:2px - style RUNTIME fill:#ffffff,stroke:#00ff00,stroke-width:2px - style STORAGE fill:#e5ffe5,stroke:#000000,stroke-width:2px - style DAG fill:#ffffff,stroke:#00ff00,stroke-width:2px - style NODE fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff - style NETWORK fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style SERVER fill:#ffffff,stroke:#000000,stroke-width:2px + style SDK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style RUNTIME fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style STORAGE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style DAG fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style NODE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style NETWORK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style SERVER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` | Component | Purpose | Repository | From f1f9e235487c0071813dd984f87684632a929b08 Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:40:18 -0300 Subject: [PATCH 18/22] fix: Update all remaining graphs to dark backgrounds with green borders - Fix WASM Execution Flow graph (applications.md) - Fix all graphs in contexts.md, identity.md, index.md, nodes.md - Fix graphs in js-sdk-guide.md - Use consistent style: dark fills (#1a1a1a) with green borders (#00ff00) - Set white text color for all nodes - Ensure all graphs are visible on dark backgrounds --- docs/builder-directory/js-sdk-guide.md | 20 ++++++++++---------- docs/core-concepts/applications.md | 10 +++++----- docs/core-concepts/contexts.md | 8 ++++---- docs/core-concepts/identity.md | 14 +++++++------- docs/core-concepts/index.md | 10 +++++----- docs/core-concepts/nodes.md | 8 ++++---- 6 files changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/builder-directory/js-sdk-guide.md b/docs/builder-directory/js-sdk-guide.md index 7d64dbc..e315572 100644 --- a/docs/builder-directory/js-sdk-guide.md +++ b/docs/builder-directory/js-sdk-guide.md @@ -29,11 +29,11 @@ flowchart LR QJS --> WASM[WASI-SDK
to WASM] WASM --> OPT[Optimize
~500KB] - style TS fill:#ffffff,stroke:#000000,stroke-width:2px - style BUILD fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style QJS fill:#ffffff,stroke:#000000,stroke-width:2px - style WASM fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style OPT fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style TS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style BUILD fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style QJS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style WASM fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style OPT fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff ``` ### Runtime Execution @@ -45,11 +45,11 @@ flowchart LR QJS --> HOST[Host
Functions] HOST --> RUNTIME[Calimero
Runtime] - style JS fill:#ffffff,stroke:#000000,stroke-width:2px - style SDK fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style QJS fill:#ffffff,stroke:#000000,stroke-width:2px - style HOST fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style RUNTIME fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff + style JS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style SDK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style QJS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style HOST fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style RUNTIME fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff ``` **How it works:** diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index a2a0e35..f4dc22d 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -49,11 +49,11 @@ flowchart LR NODE --> NETWORK[Network] NODE --> CLIENT - style CLIENT fill:#ffffff,stroke:#000000,stroke-width:2px - style NODE fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style WASM fill:#ffffff,stroke:#000000,stroke-width:2px - style STORAGE fill:#e5ffe5,stroke:#00ff00,stroke-width:2px - style NETWORK fill:#ffffff,stroke:#00ff00,stroke-width:2px + style CLIENT fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style NODE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style WASM fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style STORAGE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style NETWORK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` ### Execution Model diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index 7f47c67..11a5b55 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -102,10 +102,10 @@ flowchart LR CTX2[Context B
Shared State] --> PRIVATE2[Private
Storage] CTX1 -.->|isolated| CTX2 - style CTX1 fill:#e5ffe5,stroke:#000000,stroke-width:2px - style CTX2 fill:#e5ffe5,stroke:#000000,stroke-width:2px - style PRIVATE1 fill:#ffffff,stroke:#00ff00,stroke-width:2px - style PRIVATE2 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style CTX1 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CTX2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style PRIVATE1 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style PRIVATE2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` **Key points:** diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index 30d9b1f..c9b0811 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -16,13 +16,13 @@ flowchart TD CLIENT2 --> CTX2[Context B] CLIENT3 --> CTX3[Context C] - style ROOT fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff - style CLIENT1 fill:#e5ffe5,stroke:#000000,stroke-width:2px - style CLIENT2 fill:#e5ffe5,stroke:#000000,stroke-width:2px - style CLIENT3 fill:#e5ffe5,stroke:#000000,stroke-width:2px - style CTX1 fill:#ffffff,stroke:#00ff00,stroke-width:2px - style CTX2 fill:#ffffff,stroke:#00ff00,stroke-width:2px - style CTX3 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style ROOT fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style CLIENT1 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CLIENT2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CLIENT3 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CTX1 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CTX2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CTX3 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` ### Root Keys diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md index 105c648..2f4cd0c 100644 --- a/docs/core-concepts/index.md +++ b/docs/core-concepts/index.md @@ -103,11 +103,11 @@ flowchart LR ID2 --> CTX2 CTX1 -.->|isolated| CTX2 - style NODE fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff - style CTX1 fill:#e5ffe5,stroke:#000000,stroke-width:2px - style CTX2 fill:#e5ffe5,stroke:#000000,stroke-width:2px - style ID1 fill:#ffffff,stroke:#00ff00,stroke-width:2px - style ID2 fill:#ffffff,stroke:#00ff00,stroke-width:2px + style NODE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style CTX1 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CTX2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style ID1 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style ID2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` ## Learning Path diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md index 2a473e5..2d7734f 100644 --- a/docs/core-concepts/nodes.md +++ b/docs/core-concepts/nodes.md @@ -39,10 +39,10 @@ flowchart TD MGR --> MANAGERS[Managers
Blob & Sync] MGR --> STATE[State
Cache & Deltas] - style MGR fill:#000000,stroke:#00ff00,stroke-width:3px,color:#ffffff - style CLIENTS fill:#e5ffe5,stroke:#000000,stroke-width:2px - style MANAGERS fill:#ffffff,stroke:#00ff00,stroke-width:2px - style STATE fill:#e5ffe5,stroke:#000000,stroke-width:2px + style MGR fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style CLIENTS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style MANAGERS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style STATE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` ### Components From 78dbfa03ba2672b064332c34b0ba21f6d314c1ac Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:42:27 -0300 Subject: [PATCH 19/22] refactor: Simplify navigation structure - Merge Tools & APIs into Operate section - Rename Quick Start to Getting Started - Consolidate operational tools (nodes, monitoring, CLI, client SDKs, dev tools) under Operate - Reduce top-level tabs from 7 to 6 - Remove redundant Tools section --- docs/core-concepts/index.md | 4 ---- mkdocs.yml | 12 ++++-------- 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md index 2f4cd0c..8dd492a 100644 --- a/docs/core-concepts/index.md +++ b/docs/core-concepts/index.md @@ -2,10 +2,6 @@ Understanding Calimero's core concepts is essential for building and operating applications. This section covers the fundamental building blocks of the platform. -## Overview - -Calimero consists of several interconnected concepts: - - **[Contexts](contexts.md)** - Isolated application instances with their own state and members - **[Identity](identity.md)** - Cryptographic identities for access control and authentication - **[Applications](applications.md)** - WASM modules that run inside contexts diff --git a/mkdocs.yml b/mkdocs.yml index dc8ca3f..70efe41 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,29 +120,25 @@ extra_javascript: # Navigation structure nav: - Home: index.md - - Quick Start: getting-started/index.md - - Learn: - - Core Concepts: core-concepts/index.md + - Getting Started: getting-started/index.md + - Concepts: + - Overview: core-concepts/index.md - Architecture: core-concepts/architecture.md - Applications: core-concepts/applications.md - Contexts: core-concepts/contexts.md - Identity: core-concepts/identity.md - Nodes: core-concepts/nodes.md - Build: - - Overview: builder-directory/index.md - Rust SDK: builder-directory/sdk-guide.md - JavaScript SDK: builder-directory/js-sdk-guide.md - Examples: examples/index.md - Operate: - Running Nodes: operator-track/run-a-local-network.md - Monitoring: operator-track/monitor-and-debug.md - - Tools & APIs: - - Overview: tools-apis/index.md - CLI (meroctl): tools-apis/meroctl-cli.md - Client SDKs: tools-apis/client-sdks.md - Developer Tools: tools-apis/developer-tools.md - - Reference: - - API Reference: reference/index.md + - Reference: reference/index.md # Extra configuration extra: From 5d191c352273b2799e30a2058b1ed0b8c04baa9b Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:44:18 -0300 Subject: [PATCH 20/22] fix: Fix text visibility in Mermaid graphs - Convert stateDiagram to flowchart (state diagrams don't support inline styles) - Update Mermaid theme to dark with white text by default - Ensure all graphs use white text (#ffffff) for visibility - Fix black text on black background issue --- docs/core-concepts/contexts.md | 34 +++++++----------- mkdocs.yml | 66 +++++++++++++++++----------------- 2 files changed, 45 insertions(+), 55 deletions(-) diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index 11a5b55..f461d06 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -14,29 +14,19 @@ Contexts provide: ## Context Lifecycle ```mermaid -stateDiagram-v2 - [*] --> Created: Install App - Created --> Invited: Invite Members - Invited --> Joined: Accept Invitation - Joined --> Active: Start Using - Active --> [*]: Delete Context +flowchart TD + START[Start] --> CREATED[Created
WASM installed
State initialized
Creator = first member] + CREATED --> INVITED[Invited
Invitation sent
Permissions set] + INVITED --> JOINED[Joined
Accept invitation] + JOINED --> ACTIVE[Active
Members can call methods
State syncs
Events propagate] + ACTIVE --> END[End
Delete context] - note right of Created - - WASM installed - - State initialized - - Creator = first member - end note - - note right of Invited - - Invitation sent - - Permissions set - end note - - note right of Active - - Members can call methods - - State syncs across nodes - - Events propagate - end note + style START fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style CREATED fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style INVITED fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style JOINED fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff + style ACTIVE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff + style END fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff ``` ### 1. Creation diff --git a/mkdocs.yml b/mkdocs.yml index 70efe41..709f2c2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,42 +63,42 @@ plugins: - search # Built-in search functionality - mermaid2: # Mermaid diagram support arguments: - theme: "base" + theme: "dark" themeVariables: - primaryColor: "#ffffff" - primaryTextColor: "#000000" - primaryBorderColor: "#000000" - lineColor: "#000000" + primaryColor: "#1a1a1a" + primaryTextColor: "#ffffff" + primaryBorderColor: "#00ff00" + lineColor: "#00ff00" secondaryColor: "#00ff00" - tertiaryColor: "#e5ffe5" - background: "#ffffff" - mainBkg: "#ffffff" - secondBkg: "#f0f0f0" - textColor: "#000000" - noteBkgColor: "#ffffcc" - noteTextColor: "#000000" - noteBorderColor: "#000000" - actorBorder: "#000000" - actorBkg: "#ffffff" - actorTextColor: "#000000" - actorLineColor: "#000000" - signalColor: "#000000" - signalTextColor: "#000000" - labelBoxBkgColor: "#ffffff" - labelBoxBorderColor: "#000000" - labelTextColor: "#000000" - loopTextColor: "#000000" - activationBorderColor: "#000000" - activationBkgColor: "#e5ffe5" - sequenceNumberColor: "#000000" - sectionBkgColor: "#ffffff" - altBkgColor: "#f0f0f0" - clusterBkg: "#ffffff" - clusterBorder: "#000000" + tertiaryColor: "#1a1a1a" + background: "#1a1a1a" + mainBkg: "#1a1a1a" + secondBkg: "#2a2a2a" + textColor: "#ffffff" + noteBkgColor: "#2a2a2a" + noteTextColor: "#ffffff" + noteBorderColor: "#00ff00" + actorBorder: "#00ff00" + actorBkg: "#1a1a1a" + actorTextColor: "#ffffff" + actorLineColor: "#00ff00" + signalColor: "#00ff00" + signalTextColor: "#ffffff" + labelBoxBkgColor: "#1a1a1a" + labelBoxBorderColor: "#00ff00" + labelTextColor: "#ffffff" + loopTextColor: "#ffffff" + activationBorderColor: "#00ff00" + activationBkgColor: "#2a2a2a" + sequenceNumberColor: "#ffffff" + sectionBkgColor: "#1a1a1a" + altBkgColor: "#2a2a2a" + clusterBkg: "#1a1a1a" + clusterBorder: "#00ff00" defaultLinkColor: "#00ff00" - titleColor: "#000000" - edgeLabelBackground: "#ffffff" - labelBackground: "#ffffff" + titleColor: "#ffffff" + edgeLabelBackground: "#1a1a1a" + labelBackground: "#1a1a1a" # Custom CSS for branding and logo switching extra_css: From 62d93fe96706523965ed0e947b6db575ef51edfd Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 07:48:04 -0300 Subject: [PATCH 21/22] refactor: Merge Build, Operate, Reference into single Guides section - Consolidate Build, Operate, and Reference tabs into one 'Guides' section - Organize Guides into sub-sections: Building Applications, Running Nodes, Tools, API Reference - Reduce top-level tabs from 6 to 4 (Home, Getting Started, Concepts, Guides) - Remove Homebrew Tap, MPC Signer, Escrow from tools-apis - Remove Getting Help section from getting-started - Convert all vertical graphs (TD/TB) to horizontal (LR) for better readability --- docs/core-concepts/architecture.md | 25 ++++++++++--------------- docs/core-concepts/contexts.md | 8 ++++---- docs/core-concepts/identity.md | 2 +- docs/core-concepts/nodes.md | 2 +- docs/getting-started/index.md | 6 ------ docs/tools-apis/index.md | 8 -------- mkdocs.yml | 24 +++++++++++++----------- 7 files changed, 29 insertions(+), 46 deletions(-) diff --git a/docs/core-concepts/architecture.md b/docs/core-concepts/architecture.md index 8b0e0a0..787ef06 100644 --- a/docs/core-concepts/architecture.md +++ b/docs/core-concepts/architecture.md @@ -5,16 +5,11 @@ Calimero's architecture consists of four main layers that work together to enabl ## Four-Layer Architecture ```mermaid -flowchart TD - APP[Application
WASM apps & SDK] - NODE[Node
Sync & execution] - STORAGE[Storage
CRDT & DAG] - NETWORK[Network
P2P & APIs] - - APP --> NODE - NODE --> STORAGE - STORAGE --> NETWORK - NETWORK --> NODE +flowchart LR + APP[Application
WASM apps & SDK] --> NODE[Node
Sync & execution] + NODE --> STORAGE[Storage
CRDT & DAG] + STORAGE --> NETWORK[Network
P2P & APIs] + NETWORK -.-> NODE style APP fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff style NODE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff @@ -130,13 +125,13 @@ flowchart LR ## Key Components ```mermaid -flowchart TD - SDK[SDK] --> RUNTIME[Runtime] +flowchart LR + SERVER[Server] --> NODE[Node] + NODE --> RUNTIME[Runtime] + NODE --> NETWORK[Network] + SDK[SDK] --> RUNTIME RUNTIME --> STORAGE[Storage] STORAGE --> DAG[DAG] - NODE[Node] --> RUNTIME - NODE --> NETWORK[Network] - SERVER[Server] --> NODE style SDK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff style RUNTIME fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index f461d06..6cf1415 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -14,11 +14,11 @@ Contexts provide: ## Context Lifecycle ```mermaid -flowchart TD - START[Start] --> CREATED[Created
WASM installed
State initialized
Creator = first member] - CREATED --> INVITED[Invited
Invitation sent
Permissions set] +flowchart LR + START[Start] --> CREATED[Created
WASM installed] + CREATED --> INVITED[Invited
Invitation sent] INVITED --> JOINED[Joined
Accept invitation] - JOINED --> ACTIVE[Active
Members can call methods
State syncs
Events propagate] + JOINED --> ACTIVE[Active
Members can call] ACTIVE --> END[End
Delete context] style START fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index c9b0811..62ae647 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -7,7 +7,7 @@ Calimero uses **cryptographic identities** to manage access control and authenti Calimero supports a hierarchical identity model: ```mermaid -flowchart TD +flowchart LR ROOT[Root Key
alice.near] --> CLIENT1[Client Key A] ROOT --> CLIENT2[Client Key B] ROOT --> CLIENT3[Client Key C] diff --git a/docs/core-concepts/nodes.md b/docs/core-concepts/nodes.md index 2d7734f..82507c2 100644 --- a/docs/core-concepts/nodes.md +++ b/docs/core-concepts/nodes.md @@ -34,7 +34,7 @@ merod --node-type peer --swarm-addrs /ip4/127.0.0.1/tcp/2428 ## Node Architecture ```mermaid -flowchart TD +flowchart LR MGR[NodeManager
Orchestrator] --> CLIENTS[Clients
Context & Node] MGR --> MANAGERS[Managers
Blob & Sync] MGR --> STATE[State
Cache & Deltas] diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 79f5f83..bcee78b 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -281,9 +281,3 @@ A: Calimero supports wallet-based authentication (NEAR, Ethereum, ICP). See [Ide **Q: Can I use this offline?** A: Yes! Calimero is offline-first. Apps work offline and sync when online. - -## Getting Help - -- **Discord**: [Join our community](https://discord.gg/wZRC73DVpU) -- **GitHub Issues**: [Report bugs or ask questions](https://github.com/calimero-network/core/issues) -- **Documentation**: Browse the docs for detailed guides diff --git a/docs/tools-apis/index.md b/docs/tools-apis/index.md index 8790f39..dc499d7 100644 --- a/docs/tools-apis/index.md +++ b/docs/tools-apis/index.md @@ -46,14 +46,6 @@ Use this directory as a jumping-off point; it shows you **what exists** and **wh | --- | --- | --- | | 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. | -| Homebrew Tap | [`calimero-network/homebrew-tap`](https://github.com/calimero-network/homebrew-tap#readme) | Package distribution for CLI and runtime binaries. | - -## Advanced & Research - -| Project | Reference | Notes | -| --- | --- | --- | -| MPC Signer | [`calimero-network/experiments/mpc-signer`](https://github.com/calimero-network/experiments/tree/main/mpc-signer#readme) | Threshold signing, custody experiments, ZK exploration. | -| Escrow | [`calimero-network/escrow`](https://github.com/calimero-network/escrow#readme) | Bridge contracts, marketplace patterns, L1 attestations. | !!! 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/mkdocs.yml b/mkdocs.yml index 709f2c2..5a53947 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -128,17 +128,19 @@ nav: - Contexts: core-concepts/contexts.md - Identity: core-concepts/identity.md - Nodes: core-concepts/nodes.md - - Build: - - Rust SDK: builder-directory/sdk-guide.md - - JavaScript SDK: builder-directory/js-sdk-guide.md - - Examples: examples/index.md - - Operate: - - Running Nodes: operator-track/run-a-local-network.md - - Monitoring: operator-track/monitor-and-debug.md - - CLI (meroctl): tools-apis/meroctl-cli.md - - Client SDKs: tools-apis/client-sdks.md - - Developer Tools: tools-apis/developer-tools.md - - Reference: reference/index.md + - Guides: + - Building Applications: + - Rust SDK: builder-directory/sdk-guide.md + - JavaScript SDK: builder-directory/js-sdk-guide.md + - Examples: examples/index.md + - Running Nodes: + - Run a Local Network: operator-track/run-a-local-network.md + - Monitoring: operator-track/monitor-and-debug.md + - Tools: + - CLI (meroctl): tools-apis/meroctl-cli.md + - Client SDKs: tools-apis/client-sdks.md + - Developer Tools: tools-apis/developer-tools.md + - API Reference: reference/index.md # Extra configuration extra: From 251ac3281c354447160bfdd2912b1a23aaf053fb Mon Sep 17 00:00:00 2001 From: chefsale Date: Sun, 16 Nov 2025 08:07:33 -0300 Subject: [PATCH 22/22] fix: Resolve documentation bugs and add intro to navigation - Add intro/index.md to navigation menu - Fix malformed code block in applications.md (remove extra closing fence) - Fix tool naming: calimero-abi-generator -> @calimero-network/abi-codegen - Fix meroctl flag: --node-name -> --node throughout docs - Fix all command examples to use correct flags - Update package.json script examples with correct tool names --- docs/builder-directory/index.md | 6 +-- docs/builder-directory/js-sdk-guide.md | 6 +-- docs/builder-directory/sdk-guide.md | 4 +- docs/core-concepts/applications.md | 19 +++++--- docs/core-concepts/contexts.md | 2 +- docs/core-concepts/identity.md | 2 +- docs/examples/index.md | 2 +- docs/getting-started/index.md | 17 ++++--- docs/operator-track/monitor-and-debug.md | 4 +- docs/operator-track/run-a-local-network.md | 54 +++++++++++++++++++--- mkdocs.yml | 1 + 11 files changed, 80 insertions(+), 37 deletions(-) diff --git a/docs/builder-directory/index.md b/docs/builder-directory/index.md index 3391ff1..12445c0 100644 --- a/docs/builder-directory/index.md +++ b/docs/builder-directory/index.md @@ -14,7 +14,7 @@ Before we dive in, here are the tools we'll be using: - **`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) -- **`calimero-abi-generator `** - Generates TypeScript clients from your Rust backend, keeping frontend/backend in sync. +- **`@calimero-network/abi-codegen`** - Generates TypeScript clients from your Rust backend, keeping frontend/backend in sync. Don't worry about installing these individually - the setup process will handle it. @@ -549,7 +549,7 @@ After the Rust code is written, the AI runs: ```bash cargo build --target wasm32-unknown-unknown --release -calimero-abi-generator --input logic/res/abi.json --output app/src/api/AbiClient.ts +npx calimero-abi-codegen -i logic/res/abi.json -o app/src/api/AbiClient.ts ``` **What this generates:** @@ -844,7 +844,7 @@ This is why the first step after `pnpm network:bootstrap` is always to grab the "logic:build": "cd logic && cargo build --target wasm32-unknown-unknown --release", "logic:watch": "watchexec -w logic/src 'pnpm logic:build && pnpm logic:sync'", "logic:sync": "cp logic/target/wasm32-unknown-unknown/release/*.wasm workflows/", - "app:generate-client": "calimero-abi-generator --input logic/res/abi.json --output app/src/api/", + "app:generate-client": "calimero-abi-codegen -i logic/res/abi.json -o app/src/api/", "app:dev": "cd app && pnpm dev", "network:bootstrap": "merobox --workflow workflows/local-network.yml", "dev": "concurrently 'pnpm logic:watch' 'pnpm app:dev'" diff --git a/docs/builder-directory/js-sdk-guide.md b/docs/builder-directory/js-sdk-guide.md index e315572..7083647 100644 --- a/docs/builder-directory/js-sdk-guide.md +++ b/docs/builder-directory/js-sdk-guide.md @@ -112,16 +112,16 @@ export class CounterLogic extends CounterApp { npx calimero-sdk build src/index.ts -o build/service.wasm # Install on node -meroctl --node-name node1 app install \ +meroctl --node node1 app install \ --path build/service.wasm \ --context-id # Call methods -meroctl --node-name node1 call \ +meroctl --node node1 call \ --context-id \ --method increment -meroctl --node-name node1 call \ +meroctl --node node1 call \ --context-id \ --method getCount ``` diff --git a/docs/builder-directory/sdk-guide.md b/docs/builder-directory/sdk-guide.md index a9b4d21..5515268 100644 --- a/docs/builder-directory/sdk-guide.md +++ b/docs/builder-directory/sdk-guide.md @@ -285,7 +285,6 @@ impl KvStore { Ok(()) } - #[app::view] pub fn get(&self, key: &str) -> app::Result> { Ok(self.items.get(key)?.map(|v| v.get().clone())) } @@ -320,7 +319,6 @@ impl Metrics { Ok(()) } - #[app::view] pub fn get_views(&self, page: &str) -> app::Result { Ok(self.page_views.get(page)?.map(|c| c.value()).unwrap_or(0)) } @@ -404,7 +402,7 @@ calimero-abi extract \ ## Best Practices 1. **Always use CRDTs**: Don't use regular Rust collections for synchronized state -2. **Mark views with `#[app::view]`**: Improve performance and intent clarity +2. **Use `&self` for views**: Methods with `&self` are read-only and faster (no attribute needed) 3. **Handle errors properly**: Use `app::Result` and meaningful error types 4. **Use private storage for secrets**: Never put secrets in CRDT state 5. **Emit events for UI updates**: Enable real-time updates across nodes diff --git a/docs/core-concepts/applications.md b/docs/core-concepts/applications.md index f4dc22d..c781663 100644 --- a/docs/core-concepts/applications.md +++ b/docs/core-concepts/applications.md @@ -104,20 +104,25 @@ See [`core/crates/sdk/README.md`](https://github.com/calimero-network/core/blob/ ## Views vs Mutations -Mark read-only methods with `#[app::view]` to skip persistence: +In Rust, methods using `&self` are read-only views (no deltas generated), while `&mut self` methods are mutations: ```rust -#[app::view] // Read-only, no delta generated -pub fn get_item(&self, key: &str) -> Option { - self.items.get(key) +// View method (read-only, no delta generated) +pub fn get_item(&self, key: &str) -> app::Result> { + self.items.get(key)?.map(|v| v.get().clone()) +} + +// Mutation method (generates delta) +pub fn set_item(&mut self, key: String, value: String) -> app::Result<()> { + self.items.insert(key, value.into())?; + Ok(()) } -``` ``` **Benefits**: -- Views don't generate storage deltas +- View methods (`&self`) don't generate storage deltas - Faster execution (no persistence overhead) -- Clear intent in API +- Clear intent in API (Rust's type system enforces immutability) ## Resource Limits diff --git a/docs/core-concepts/contexts.md b/docs/core-concepts/contexts.md index 6cf1415..0b879ad 100644 --- a/docs/core-concepts/contexts.md +++ b/docs/core-concepts/contexts.md @@ -45,7 +45,7 @@ Context creators can invite other identities to join: ```bash # Generate identity for invitee -meroctl identity create --node-name node2 +meroctl identity create --node node2 # Create invitation meroctl context invite \ diff --git a/docs/core-concepts/identity.md b/docs/core-concepts/identity.md index 62ae647..314812f 100644 --- a/docs/core-concepts/identity.md +++ b/docs/core-concepts/identity.md @@ -51,7 +51,7 @@ A **root key** is the master identity for a user or node. It's typically: Generate identities with `meroctl`: ```bash -meroctl identity create --node-name node1 +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. diff --git a/docs/examples/index.md b/docs/examples/index.md index 8af2688..6ae56ef 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -19,7 +19,7 @@ These examples live in [`calimero-network/core/apps`](https://github.com/calimer ```bash cd core/apps/kv-store ./build.sh -meroctl --node-name node1 app install --path build/kv_store.wasm +meroctl --node node1 app install --path build/kv_store.wasm ``` ## Application Examples diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index bcee78b..784d606 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -98,10 +98,10 @@ docker run -p 2529:2528 ghcr.io/calimero-network/merod:edge \ ```bash # Check node health -meroctl --node-name node1 health +meroctl --node node1 health # List contexts -meroctl --node-name node1 context list +meroctl --node node1 context list ``` See [Running Nodes](../operator-track/run-a-local-network.md) for detailed node management. @@ -139,7 +139,7 @@ cd core/apps/kv-store ./build.sh # Install on node -meroctl --node-name node1 app install \ +meroctl --node node1 app install \ --path build/kv_store.wasm ``` @@ -174,9 +174,8 @@ impl MyApp { self.items.insert(key, value); } - #[app::view] - pub fn get_item(&self, key: &str) -> Option { - self.items.get(key) + pub fn get_item(&self, key: &str) -> app::Result> { + self.items.get(key)?.map(|v| v.get().clone()) } } ``` @@ -198,21 +197,21 @@ See [SDK Guide](../builder-directory/sdk-guide.md) or [JavaScript SDK Guide](../ **Create a context:** ```bash -meroctl --node-name node1 context create \ +meroctl --node node1 context create \ --application-id ``` **Call methods:** ```bash # Call a mutation -meroctl --node-name node1 call \ +meroctl --node node1 call \ --context-id \ --method add_item \ --args '{"key": "hello", "value": "world"}' \ --executor-public-key # Call a view -meroctl --node-name node1 call \ +meroctl --node node1 call \ --context-id \ --method get_item \ --args '{"key": "hello"}' diff --git a/docs/operator-track/monitor-and-debug.md b/docs/operator-track/monitor-and-debug.md index 4b41c77..2c13e22 100644 --- a/docs/operator-track/monitor-and-debug.md +++ b/docs/operator-track/monitor-and-debug.md @@ -6,13 +6,13 @@ Observability and troubleshooting for Calimero nodes. ```bash # Check node health -meroctl --node-name node1 health +meroctl --node node1 health # View logs merobox logs node1 --follow # List contexts -meroctl --node-name node1 context list +meroctl --node node1 context list ``` ## Admin Dashboard diff --git a/docs/operator-track/run-a-local-network.md b/docs/operator-track/run-a-local-network.md index 113388e..ed5a8c2 100644 --- a/docs/operator-track/run-a-local-network.md +++ b/docs/operator-track/run-a-local-network.md @@ -26,20 +26,60 @@ merobox bootstrap run workflow.yml ## Using merod Directly -For more control, run nodes directly: +For more control, run nodes directly without Docker: ```bash -# Install merod +# Install merod (from source) cargo install --path core/crates/merod -# Start coordinator -merobox run --name node1 +# Or build and use directly +cd core/crates/merod +cargo build --release +``` + +**Initialize and run a single node:** + +```bash +# Initialize a node with default settings +merod --node-name node1 init + +# Or with custom ports +merod --node-name node1 init --server-port 2428 --swarm-port 2528 + +# Run the node +merod --node-name node1 run +``` + +**Run multiple nodes manually:** + +```bash +# Terminal 1: Start first node (coordinator) +merod --node-name node1 init --server-port 2428 --swarm-port 2528 +merod --node-name node1 run + +# Terminal 2: Start second node (peer) +merod --node-name node2 init --server-port 2429 --swarm-port 2529 +merod --node-name node2 config --swarm-addrs /ip4/127.0.0.1/tcp/2528 +merod --node-name node2 run + +# Terminal 3: Start third node (peer) +merod --node-name node3 init --server-port 2430 --swarm-port 2530 +merod --node-name node3 config --swarm-addrs /ip4/127.0.0.1/tcp/2528 +merod --node-name node3 run +``` + +**Configuration:** + +```bash +# Configure node settings +merod --node-name node1 config --server-host 0.0.0.0 --server-port 3000 +merod --node-name node1 config --swarm-host 0.0.0.0 --swarm-port 2428 -# Start peer -merobox run --name node2 +# Use custom home directory +merod --home ~/.calimero-custom --node-name node1 init ``` -See [`core/crates/merod/README.md`](https://github.com/calimero-network/core/blob/master/crates/merod/README.md) for node options. +See [`meroctl CLI`](../tools-apis/meroctl-cli.md) for managing contexts and use `merod --help` for all available node options. ## Requirements diff --git a/mkdocs.yml b/mkdocs.yml index 5a53947..99d2f03 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,6 +120,7 @@ extra_javascript: # Navigation structure nav: - Home: index.md + - Introduction: intro/index.md - Getting Started: getting-started/index.md - Concepts: - Overview: core-concepts/index.md