@calimero-network/calimero-sdk-js

Core SDK for building Calimero P2P applications with automatic CRDT-based state synchronization.

Installation

npm install @calimero-network/calimero-sdk-js
# or
pnpm add @calimero-network/calimero-sdk-js

Usage

import { State, Logic, Init, View, createUnorderedMap } from '@calimero-network/calimero-sdk-js';
import type { UnorderedMap } from '@calimero-network/calimero-sdk-js/collections';

@State
export class MyApp {
  items: UnorderedMap<string, string> = createUnorderedMap();
}

@Logic(MyApp)
export class MyAppLogic extends MyApp {
  @Init
  static initialize(): MyApp {
    return new MyApp();
  }

  set(key: string, value: string): void {
    this.items.set(key, value);
  }

  @View()
  get(key: string): string | null {
    return this.items.get(key) ?? null;
  }
}

Use the helper factories (createUnorderedMap, createVector, createCounter, createLwwRegister, createUnorderedSet) to initialize CRDT collections directly on your state fields. Avoid constructor side effects; the decorators will hydrate the state instance on each call.

Decorate read-only methods with @View() so the runtime skips persistence for calls that do not mutate state. Views still run inside the same execution sandbox but won’t emit storage deltas, which keeps the DAG compact and avoids redundant writes.

All values, return payloads, and collection snapshots are serialized with Calimero’s Borsh encoder. Nested CRDTs or complex objects are supported as long as you keep data structures serializable (avoid functions, symbols, etc.).

Private Storage

Use createPrivateEntry for node-local data that should not replicate across the network:

import { createPrivateEntry } from '@calimero-network/calimero-sdk-js';

const secrets = createPrivateEntry<{ token: string }>('private:secrets');

secrets.getOrInit(() => ({ token: '' }));
secrets.modify(
  value => {
    value.token = 'latest-token';
  },
  () => ({ token: '' })
);

Values are serialized with the same helper as service state, but they are written via storageRead/storageWrite directly and never appear in CRDT deltas.

Documentation

Updating the storage shim

@calimero-network/calimero-sdk-js ships a prebuilt storage_wasm.wasm that mirrors the Rust storage-wasm crate. Whenever the Rust runtime or storage crate changes, regenerate the artifact and the C header that embeds it. From the repository root:

1. Build the updated shim for WASI:

cargo build --release --target wasm32-wasip1 -p storage-wasm

2. Copy the resulting WASM into the SDK package:

cp target/wasm32-wasip1/release/storage_wasm.wasm calimero-sdk-js/packages/sdk/src/wasm/storage_wasm.wasm

3. Refresh the header used by the CLI builder:

xxd -i calimero-sdk-js/packages/sdk/src/wasm/storage_wasm.wasm > calimero-sdk-js/packages/cli/builder/storage_wasm.h

Both the SDK and the Calimero runtime load this shim at build time, so keep the binary and header in sync with the latest runtime changes before publishing packages or rebuilding Docker images.

See the main repository documentation for complete guides and API reference.

License

Apache-2.0