docs/architecture-layers.mdpinned to impactium@637886d

Architecture: Layers

Impactium is built in two on-chain layers, wrapped by a set of read and serving tiers. This page is the map of where each piece lives — and, in particular, the answer to "where do dApps run?"

The two chain layers

Layer 1 — the base chain

L1 is the settlement layer and the source of truth. It is CometBFT consensus driving the native Impact SDK modules, and it holds every permanent fact the network commits to:

verified impact — Capsules, mint records, residual, and true cost,
identity and lineage — governed classifications, the accountability and impact chains, and referral multi-root partitions,
governance — the Universal Constitution,
and Chain Resources — the manifests that anchor on-chain code and living documents.

Everything on L1 is permanent, attributed, and provable against the chain's committed state root. Its invariants are structural, enforced by the SDK itself: impact is non-transferable, records are permanent, execution is deterministic, and failures commit visibly.

Layer 2 — the execution layer

L2 is where dApps run on-chain. An application like Bliss — the on-chain OS described below — does not merely read the chain and submit transactions from the sidelines; it executes on Impactium's own purpose-built execution layer.

L2 is Impactium's own execution layer, built to Impactium's own invariants (see The Impact SDK). Whatever a dApp does, its execution is deterministic, its impact records are permanent and non-transferable, and its failures stay visible — the same structural rules that govern L1. dApps get their code content-addressed and certified through Chain Resources.

The relationship between the layers is simple:

L2 executes application logic;
L1 settles what that logic means for impact, identity, and governance — the permanent record;
dApps read through Karma and write as signed transactions that settle on L1.

The execution layer's internal model is in active design. This page fixes the layer and its role; the internals — how execution is expressed, and how L2 anchors to L1 — are being worked out.

The tiers around the chain

Two things people loosely call "layers" in Impactium are not chain layers at all — they are services that make the chain usable:

Karma — the read side. A disposable projection of the chain into a walkable Hive-Knowledge Graph with a typed GraphQL API. Delete it and it rebuilds by replaying the chain; nothing of value lives only in it. It exists to make perspectival lookups fast.
The resource-serving tier. Holds the bytes of Chain Resources — packages, documents, and eventually repositories — each chunk verified against an L1-committed hash. It also speaks npm.

And at the edge, clients — the wallet, dashboards, and the dApps themselves — are generated from the chain's own protocol definitions, so the wire contract is shared and versioned across languages.

So how many layers are there?

Two protocol layers — the L1 base chain and the L2 execution layer — wrapped by the read side (Karma) and the resource tier, with clients at the edge. When someone asks "where does my dApp live?", the answer is the L2: on-chain, on Impactium's own execution layer, settling to the permanent record on L1.

Bliss — the first on-chain OS

The first application on the L2 is Bliss — an on-chain operating system that carries the influx of data and the automated pipelines people work through, subliminally, so users stay in flow rather than minding the machinery.

It matters to this page for one structural reason: Bliss is not merely the first app on the execution layer, it is the runtime other apps are served by. A layer with one hard-coded application is not a proven execution layer; a layer whose first application serves other applications is.

Bliss is also a gate on Genesis — the record does not become permanent until the OS people actually live in is real. See Bliss for what ships today (a deterministic, governed job queue) and what does not.