Acropolis

Acropolis is a modular Rust implementation of a Cardano node, built using the Caryatid framework. It provides a kit of modular parts for flexible construction of clients, services, and APIs for the Cardano ecosystem. The project seeks parity with the Haskell Cardano node implementation and is intended to be a full block-producing node on mainnet.

Please see the overview document for development phases, deliverables, and expected use cases.

Quick Start

Prerequisites: Rust 1.93+ (installed automatically via rust-toolchain.toml), a C compiler, and on Linux: pkg-config and libssl-dev. See the Getting Started guide for full details.

# Run on mainnet (genesis sync via Mithril)
make run

# Or run on the preview testnet
make run-preview

# Or bootstrap from a ledger state snapshot (faster)
make run-bootstrap

Set the log level with make run LOG_LEVEL=debug (options: error, warn, info, debug, trace).

Docker

docker compose up omnibus-mainnet

See Getting Started — Docker Compose for all services and port mappings.

Architecture

Acropolis uses a publish-subscribe message-passing architecture. Modules communicate via messages on topics rather than direct function calls, providing module isolation, easy replacement, and natural parallelism.

By default, modules run in a single process communicating over an in-memory message bus (zero-copy Rust structs). Optionally, modules can run in separate processes communicating via RabbitMQ.

graph TB
  subgraph Process A
    Module1(Module 1)
    Module2(Module 2)
    Caryatid1(Caryatid Framework)
    Module1 <--> Caryatid1
    Module2 <--> Caryatid1
  end

  subgraph Process B
    Module3(Module 3)
    Caryatid2(Caryatid Framework)
    Module3 <--> Caryatid2

  end

  RabbitMQ([RabbitMQ Message Bus])
  style RabbitMQ fill: #eff
  Caryatid1 <--> RabbitMQ
  Caryatid2 <--> RabbitMQ

Loading

Modules

Bootstrapping

• Genesis Bootstrapper — reads the Genesis files for a network and initializes initial UTxOs and protocol parameters
• Mithril Snapshot Fetcher — fetches a chain snapshot from Mithril and replays all blocks
• Snapshot Bootstrapper — downloads and streams ledger state snapshots (UTXOs, pools, accounts, DReps, proposals)

Network & Consensus

• Peer Network Interface — Node-to-Node (N2N) client protocol for chain synchronisation and block fetching
• Consensus — Ouroboros Praos consensus protocol

Block & Transaction Processing

• Block Unpacker — unpacks received blocks into individual transactions
• Tx Unpacker — parses transactions and generates UTXO changes
• Block VRF Validator — validates block VRF proofs
• Block KES Validator — validates block KES signatures

Ledger State

• UTXO State — maintains in-memory UTXO state
• SPO State — tracks stake pool registrations and retirements
• DRep State — tracks DRep registrations
• Accounts State — stake and reward accounts tracker
• Epochs State — tracks fees, blocks minted, and epoch history
• Parameters State — tracks protocol parameters and updates
• Governance State — tracks governance actions and voting

Distribution Snapshots

• SPDD State — stake pool delegation distribution snapshots
• DRDD State — DRep delegation distribution snapshots
• Stake Delta Filter — filters stake address changes and resolves stake pointers

API Persistent State

• Assets State — tracks native asset supply, metadata, transactions, and addresses
• Address State — address-level transaction and balance tracking
• Historical Accounts State — historical account state (rewards, delegations, registrations)
• Historical Epochs State — historical epoch data

Storage & Interfaces

• Chain Store — persistent block storage (Fjall LSM)
• REST Blockfrost API — Blockfrost-compatible REST API
• MCP Server — Model Context Protocol server
• TX Submitter — transaction submission
• Custom Indexer — user-defined indexing
• Stats — runtime statistics

Processes

Processes are executable binaries that bundle modules together:

• Omnibus — all-inclusive testing process containing all modules (in-memory message bus)
• Replayer — replay previously downloaded messages from JSON files
• Golden Tests — end-to-end golden test execution
• TX Submitter CLI — command-line wrapper for transaction submission
• Midnight Indexer — Midnight-specific block indexing

Documentation

Document	Description
Getting Started	Prerequisites, build, run, configuration, Docker
Configuration Reference	All module settings, defaults, and API feature flags
Overview & Deliverables	Development phases and node deliverables
Bootstrap Guide	Snapshot bootstrap architecture and quick start
Architecture: Modularity	Pub-sub design and module communication
Epoch Timing	Epoch boundaries, rewards, and snapshot rotation
Memory Profiling	Heap profiling with jemalloc
Performance Profiling	CPU profiling with Linux perf
API Specification	Blockfrost-compatible REST API (OpenAPI)
Modules Reference	All modules with descriptions
Processes Reference	Available process binaries

License

See LICENSE.