Building on Archeum

A primer for developers and AI assistants · the full reference lives at archeum.dev

Archeum apps are mobile-only (Android for v1). Apps connect to the user's node - which runs on their phone - using their wallet credentials. Only the Archeum app itself provisions nodes; normal apps never do.

The model in one breath

Every user owns a node on their phone and a handle like @alice. Your app signs in as a user, then reads and writes data on that user's node over QUIC. There is no backend to run and no blockchain - handle ownership lives in Archeum's feeless mesh consensus, and the SDK resolves a handle to a node endpoint for you.

Three primitives

Identity - a user, addressed by handle. Creates Items and Reactors owned by that user.
Item - key-value storage for arbitrary bytes, with optional end-to-end encryption. String, JSON, list, and nesting helpers included.
Reactor - collaborative data structures for social features, invoked by any authenticated user and run in a sandbox on the owner's node.

You build app-specific types (Profile, Post, Conversation, Event…) by composing these three.

Encryption

Default: items are end-to-end encrypted with AGE for the owner only. The key is generated on the device and never leaves it - the node operator cannot read the content.
Public: mark an item public to store it unencrypted (readable by anyone on the network).
Multi-recipient: encrypt for specific handles in addition to the owner; each recipient gets their own wrapped key.

Wallet identity and signatures are Ed25519. Reads are public at the protocol level (any authenticated caller may attempt them), which is exactly why encryption exists: encrypted bytes stay private even though the read succeeds. Writes are owner-only.

Reactor types

HandleSet - a set of identities that reacted. Use for likes, follows, attendees.
FirstCall - identity → data, first write wins. Use for RSVPs, poll votes.
LastCall - identity → data, last write wins. Use for status, presence, location.

Reactors are the only cross-identity write path. They run as sandboxed WASM on the node, can touch many items in a single call, and never see your encryption keys.

A taste of the API

// Identity-based Profile, composing the primitives
profile = Identity.new("alice")
await profile.item("bio").put_string("Software engineer", public = true)

post = profile.item("post-123")
await post.put_string("My first post!", public = true)

likes = post.reactor("likes", HandleSet)
await likes.start()
await likes.react()        // any signed-in user can like

// private by default: encrypted to the owner's key only
await profile.item("notes").put_string("just for me", public = false)

Authentication & authorization

Sign in once; the SDK manages connection pooling and handle resolution.
Reads: any authenticated caller (encrypted data stays unreadable without the key).
Writes: owner-only.
Reactors: anyone can react; only the owner creates them.
Pub/Sub: anyone can subscribe; only the owner publishes.

Full reference

This page is a primer. For the complete API - every method, the pub/sub streaming model, error handling, namespaces, and composition patterns - see the docs at archeum.dev.