Architecture Overview

Velarium is built around a single core invariant: For each pair of state accesses of a single address, stale reads are disallowed.. The entire system is a harness around preserving this rule: parallel work is permitted only when it can be reconciled without ever serving stale slot reads.

The architecture revolves around two core subsystems:

• Celerity — the execution runtime. It schedules and runs transaction batches in parallel. It orchestrates both in-machine parallelization and horizontal scaling across multiple machines in a cluster.
• Shipyard — the compilation and synthesis pipeline. It turns contract bytecode into Vehicles (sandboxed execution units) and produces the analysis metadata Celerity uses for contention-domain formation and other execution decisions. Shipyard also embeds chain’s semantics and the trace/witness schema expected downstream.

System context

Velarium ingests batches of transactions from the upstream ordering layer. A batch does not have to correspond 1:1 with a block (though it can, if an operator prefers). Once a batch enters Velarium, the runtime pulls contract code from storage and tries to load a prebuilt Vehicle for each contract. If no Vehicle is available, Velarium falls back to the source bytecode and invokes Shipyard to compile and synthesize one as needed.

Celerity uses Shipyard’s analysis metadata to discover contention domains within the batch. It then schedules execution in phases, structuring work into locality domains that compress and resolve those contention hotspots.

By the end of batch execution, Celerity produces a deterministic state transition, and emits the resulting state updates and/or execution traces to downstream consumers.

Integration point

Velarium sits between the sequencer/mempool and the proof pipeline, handling contract execution. It integrates with state storage and an oracle through an adapter.

Component map

Celerity (execution kernel / scheduler)

Celerity is Velarium’s execution runtime: it ingests optionally ordered batches of transactions, orchestrates parallel work, and produces committed outputs that preserve the chain’s execution semantics.

Celerity schedules work at the granularity of state slots, not transactions. Unlike conventional executors that treat entire transactions as atomic scheduling units, Celerity breaks transactions into segments and schedules those segments based on which state addresses they touch. This slot-level contention awareness allows finer-grained parallelism: non-conflicting segments can run concurrently even when their parent transactions would otherwise appear to conflict.

The scheduler uses analysis metadata from Shipyard to discover contention domains and state access patterns for each transaction. It then organizes work into locality domains to resolve contention clusters efficiently. Combined with state-slot-level scheduling granularity, Celerity can process hotspots quickly while maintaining high core utilization.

Concurrency is cooperative: execution can yield and resume at safe points, enabling selective descheduling for risky speculative state accesses and efficient execution plan convergence. During niche exectuion phases, transactions can handoff execution time slots directly, avoiding global coordination efforts. Since the access order is already known within a phase, conflict checking is unnecessary—execution simply proceeds through the allocated transaction segments sequentially.

Progress is governed by a commit frontier that advances as results become safe to commit; downstream consumers receive state deltas and traces as the frontier moves.

Shipyard (compiler / build pipeline)

Shipyard is the pipeline that turns contract bytecode into Vehicles—sandboxed execution units optimized for Velarium’s runtime. It creates two main artifacts:

• Vehicle – a natively compiled execution unit. It embeds the chain’s semantics, accounting and trace/witness generation schema eliminating the need to look up gas costs, opcode semantics, and chain parameters at runtime and allowing low level optimizations to take place. Additionally it embeds the cooperation machinery required by Celerity’s scheduler.
• Analysis metadata – includes information about contract effects along with the state and oracle access patterns. This information is used by Celerity for contention domains discovery, execution phases formation and scheduling decisions.

Shipyard uses a pluggable frontend to ingest and lift different bytecodes into VIR, a unified intermediate representation used for analysis. Over VIR we derive state/oracle access patterns and track dataflow/propagation through the contract, while abstracting away chain-specific semantic quirks so analysis stays focused on contract logic.

VIR is a stack-aware SSA: it represents as much code as possible in SSA form (ideally whole functions), while retaining an explicit operand stack on SSA domain boundaries. This has an advantage of eliminating source VM machinery semantics, like dispatch loop and the VM state itself. The contract is lifted into a more direct form enabling more effective analysis and more efficient execution.

From VIR, Shipyard lowers the Vehicle into native code inside a sandboxed envelope using SFI. Read more about Vehicle security in Security model.

State adapter & state tiers

Velarium’s state integration is intentionally conservative: it reads and writes through state and oracle adapters and produces the same logical state transition as a conventional sequential executor—just with different internal execution strategy. This lets operators integrate Velarium without rewriting state backends or changing persistence guarantees.

Internally, state is organized into tiers to make parallel execution practical (caching, locality, and fast conflict checks). The execution and data flow are organized such as to always keep relevant state as close to the consumer as possible. In practice we try to keep the working state set from ever leaving L3 CPU cache. This design extends to distributed execution, where cross-machine coordination is structured to preserve the same cache-locality properties.

The external contract remains straightforward: reads/writes are served via the adapter, and committed results are emitted as deltas suitable for persistence, receipts, and downstream verification.

Trace definition

Velarium treats tracing as a first-class, configurable output. Operators define the trace schema (what gets emitted, and in what shape) and Shipyard embeds that schema into the compiled execution unit so trace emission is efficient from inside the sandboxed runtime.

This lets the executor use compact layouts and hardware-friendly writes (e.g., vectorized emission paths and non-temporal stores where appropriate), rather than expensive generic hook-based logging.

The same “schema-first” approach extends to custom state/oracle access semantics provided by alternative frontends: the operator supplies a system access schema, and Shipyard binds it into the execution unit so instrumentation and downstream consumption remain consistent. This allows using non-dedicated bytecode formats (RISC-V, WebAssembly) with custom semantics without requiring a chain dedicated frontend.

Cluster ring (optional)

Celerity can scale out across a cluster with an elastic, fault-tolerant runtime topology. The cluster layer is designed for runtime faults—node loss, link loss, transient partitions—while preserving correct outputs; it does not aim to provide offline state restoration on its own. The design is cache-aware: hot state and execution locality are treated as placement signals so frequently accessed data tends to stay warm where it is needed, reducing cross-node churn under contention.

End-to-end dataflow

1. Input → ordered transaction batch + chain context (from sequencer adapter)
2. Preparation → Vehicles + analysis metadata are made available (cache or JIT)
3. Plan-Execute loop:
   1. Planning → contention domains are discovered; scheduling decisions are made
   2. Execution → transactions run within the scheduled envelope. Non deterministic metadata is discovered.
4. Commit → transactions are committed at the runtime, once their execution is settled
5. Outputs → committed state deltas + schema-defined traces are emitted
6. Handoff → deltas go to persistence/state adapter; traces go to prover/observability via the trace sink