> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumera.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Protocol architecture
> How Lumera's layered architecture coordinates consensus, protocol services, and decentralized execution.
Lumera separates consensus, protocol logic, decentralized services, and developer interfaces into distinct architectural layers. The blockchain serves as the protocol's control plane, coordinating requests, governance, settlement, and cryptographic proofs, while economically bonded SuperNodes execute decentralized intelligent services. Together, these layers allow protocol services to scale independently while preserving the security and trust guarantees of blockchain consensus.
## Protocol Foundation
The protocol foundation provides consensus, accounts, governance, interoperability, and multiple smart contract execution environments. Together, these components provide the shared foundation upon which Lumera's protocol services are built.
| Component | Purpose |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cosmos SDK** | Core blockchain framework providing accounts, staking, governance, transactions, gRPC, and REST APIs shipped as a single `lumerad` binary. |
| **CometBFT** | Byzantine Fault Tolerant consensus engine providing fast deterministic finality. |
| **CosmWasm** | Deterministic Rust smart contracts executed within a WebAssembly sandbox and gas metering. |
| **Cosmos EVM** | Native Solidity execution with Ethereum-compatible tooling and accounts. [Find out how →](/smart-contracts/overview) |
| **IBC** | Native interoperability with other Cosmos chains through token transfers, messaging, and Interchain Accounts. [Learn more →](/cascade/concepts/interchain-accounts) |
## Validator–SuperNode architecture
Lumera separates consensus from decentralized service execution through two complementary node types. This architectural separation allows the blockchain to establish shared truth while specialized infrastructure performs the protocol services applications consume.
**Validators** secure the network through Delegated Proof of Stake, proposing and validating blocks with CometBFT, maintaining consensus, and participating in on-chain governance. Together, they provide the security guarantees upon which every protocol service depends. [Run a validator →](/validators/overview)
**SuperNodes** are specialized network nodes operated alongside validators. They execute decentralized intelligent services—including permanent storage, verification, retrieval, and decentralized execution—while remaining economically bonded to the validator they serve. Because protocol services execute outside of consensus, Lumera can scale sophisticated decentralized services without increasing the cost or complexity of block production. [Learn more about SuperNodes →](/supernodes/overview)
The blockchain acts as the protocol's **control plane**, recording requests, commitments, payments, governance, and cryptographic proofs. SuperNodes form the **execution and data plane**, performing work directly for applications and returning verifiable evidence of completion. Data moves directly between clients and SuperNodes without passing through consensus, allowing the network to remain both scalable and trust-minimized.
## Protocol Modules
Lumera's protocol logic is implemented through a set of custom Cosmos SDK modules that coordinate protocol services, decentralized identity, SuperNode operations, and network state. Support modules introduced with the Cosmos EVM extend interoperability while preserving the same architectural model.
The EVM upgrade has added support modules (`x/vm`, `x/feemarket`, `x/precisebank`, `x/erc20`, `x/evmigration`) documented [here](/upgrades/evm-upgrade).
| Module | What it does |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `x/action` | Coordinates the lifecycle of protocol Actions from registration through settlement |
| `x/supernode` | Registers SuperNodes, maintains the active service set, tracks performance, and distributes Proof-of-Service rewards. |
| `x/lumeraid` | Anchors decentralized identities to Lumera addresses |
| `x/claim` | Handles legacy token claims and migration |
### The action lifecycle
Every decentralized intelligent service is executed as one or more protocol Actions—on-chain records that move through a common lifecycle from registration to settlement.
A client submits the registration transaction. The service fee is locked in escrow and the action gets a unique ID. The state is `PENDING`.
Top ranked SuperNodes pick up the action, receive the file over gRPC, and do the work. The state is `PROCESSING`.
When the work completes and results are committed, the state becomes `DONE`. A failed or expired action becomes `FAILED` and the escrowed fee is refunded.
Where a flow requires explicit approval, an approval transaction moves the action to `APPROVED` and the escrowed fee pays out to the SuperNodes that served it.
Fee escrow aligns incentives for both clients and service providers. Applications pay only when protocol services complete successfully, while SuperNodes are compensated only after verifiable completion. Governance determines the fee parameters for each protocol service.
### SuperNode registry and ranking
The `x/supernode` module is the source of truth for SuperNode registrations. It stores each node's address, endpoint, and stake, maintains the ranked top list that `x/action` routes work to, and accounts for completed actions. A SuperNode must stay tied to an active validator. If the validator is jailed or unbonds, the SuperNode drops off the list.
## Protocol Services
Protocol services are the decentralized capabilities applications consume through Lumera. Every service is implemented through the Action framework, executed by economically bonded SuperNodes, and coordinated by the blockchain through a common execution and settlement lifecycle.
Current protocol services demonstrate this architecture today, while future services extend the same framework rather than introducing separate systems.
Each SuperNode runs the `supernode` binary alongside `lumerad`.
### Cascade
Cascade is permanent file storage with a pay once, store forever model. The SuperNode receives a file through its streaming gRPC endpoint, encodes it with RaptorQ erasure coding, and spreads the symbols across a Kademlia DHT. Any sufficiently large subset of symbols rebuilds the file, so the network self heals when nodes leave. Start with [how Cascade works](/cascade/how-cascade-works) and go deeper in [erasure coding](/cascade/concepts/erasure-coding).
### Identity with LumeraID
LumeraID anchors identity records to Lumera addresses through the `x/lumeraid` module. There is no separate username. Your address is your identity, and the record is controlled by your private key. The protocol uses it wherever ownership must be proven. Cascade downloads of private files require a signature that matches the registering identity, which is why files are private by default even though their encoded symbols live on a public network. Signatures follow ADR-036, the Cosmos standard for signing arbitrary data.
### Future Services
Lumera's execution framework is designed to support a growing ecosystem of decentralized intelligent services. Because every service shares the same Action framework, execution lifecycle, settlement model, and verification architecture, new capabilities extend the protocol rather than introducing separate systems.
Future protocol services extend this same architectural foundation to capabilities such as durable memory, decentralized identity, verifiable execution, settlement, and additional decentralized intelligent services.
## Developer Interfaces
**Lumera Hub** is the official client for web, desktop, and mobile at [hub.lumera.io](https://hub.lumera.io). It covers balances, staking, storage, and identity. See the [Hub overview](/hub/overview).
**LumeScope** is a read-only REST API aggregator for developers who want decoded network state without running a node. It decodes action metadata, aggregates SuperNode metrics, and serves 16 endpoints with a Swagger UI. See the [LumeScope API reference](/api/lumescope).
**`lumerad`** is the chain binary and CLI. It runs nodes, manages keys, broadcasts transactions, and queries every module. See the [CLI reference](/sdk/lumerad-cli).
## Extending the Protocol
The architecture above is intentionally composable. Every new decentralized intelligent service is implemented as another protocol Action moving through the same registration, execution, verification, and settlement lifecycle.
Rather than introducing separate systems for memory, identity, execution, settlement, or future protocol capabilities, Lumera extends a shared architectural foundation built on common protocol modules, economically bonded SuperNodes, and a unified execution framework.
As the protocol evolves, developers continue building against the same APIs, execution model, and architectural foundation while inheriting new protocol capabilities as native services.
The [SDKs](/sdk/javascript) wrap the chain APIs and the SuperNode protocol for JavaScript and Go applications.
## Next steps
The full journey of a Cascade upload through these layers.
The EVM environment on the base layer.
Join the consensus layer.