diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 81162d27..fff9aada 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,28 +1,17 @@ -# Pull Request Title - - ## Description - ## Related Issue(s) - ## How was this tested? - ## Checklist - [ ] My code builds and passes local tests @@ -31,12 +20,8 @@ so reviewers can reproduce. Examples: - [ ] CI is green for this PR ## Impact / Side effects - ## Reviewer notes / Areas to focus - diff --git a/README.md b/README.md index 4f3f4a69..e3ccc48d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,24 @@ # Acropolis -Acropolis is a project to create a kit of micro-service parts, written in +Acropolis is a project to create a kit of modular parts, written in Rust, which allows flexible construction of clients, services and APIs for the Cardano ecosystem. +## Status + +This project has moved out of the experimental phase and is being implemented +according to a set of deliverables documented in the Treasury Fund Milestones. + +# Overview and Deliverables + +The Acropolis Cardano Node is a rust implementation that seeks parity with the +Haskell implementation and is intended to be a full block producing node on mainnet. +Please see the [overview document](docs/overview.md) that describes the phases of +development, descriptions, expected use cases, and runtime environments expected +of each of the deliverables. + +# Architecture + Acropolis is based on the [Caryatid framework](https://github.com/input-output-hk/caryatid), which in turn uses a message bus such as [RabbitMQ](https://www.rabbitmq.com/) @@ -12,7 +27,7 @@ to communicate between micro-services. ```mermaid graph TB - subgraph Microservice A + subgraph Process A Module1(Module 1) Module2(Module 2) Caryatid1(Caryatid Framework) @@ -21,7 +36,7 @@ graph TB Module2 <--> Caryatid1 end - subgraph Microservice B + subgraph Process B Module3(Module 3) Caryatid2(Caryatid Framework) @@ -39,9 +54,6 @@ graph TB ## Modules -This project is in an experimental phase at the moment, and the module -structure is highly subject to change: - - [Upstream Chain Fetcher](modules/upstream_chain_fetcher) - implementation of the Node-to-Node (N2N) client-side (initiator) protocol, allowing chain synchronisation and block fetching @@ -62,56 +74,21 @@ structure is highly subject to change: - [Accounts State](modules/accounts_state) - stake and reward accounts tracker - [Assets State](modules/assets_state) - tracks native asset supply, metadata, transactions, and addresses -```mermaid -graph LR - - UpstreamChainFetcher(Upstream Chain Fetcher) - GenesisBootstrapper(Genesis Bootstrapper) - MithrilSnapshotFetcher(Mithril Snapshot Fetcher) - BlockUnpacker(Block Unpacker) - TxUnpacker(Transaction Unpacker) - UTXOState(UTXO State) - SPOState(SPO State) - DRepState(DRep State) - GovernanceState(Governance State) - StakeDeltaFilter(Stake Delta Filter) - EpochsState(Epochs State) - AccountsState(Accounts State) - AssetsState(Assets State) - ParametersState(Parameters State) - - UpstreamChainFetcher --> BlockUnpacker - MithrilSnapshotFetcher --> BlockUnpacker - BlockUnpacker --> TxUnpacker - GenesisBootstrapper --> UTXOState - TxUnpacker --> UTXOState - TxUnpacker --> AssetsState - TxUnpacker --> EpochsState - TxUnpacker --> AccountsState - TxUnpacker --> DRepState - TxUnpacker --> SPOState - TxUnpacker --> GovernanceState - GovernanceState --> ParametersState - TxUnpacker --> ParametersState - UTXOState --> StakeDeltaFilter - StakeDeltaFilter --> AccountsState - UpstreamChainFetcher --> EpochsState - MithrilSnapshotFetcher --> EpochsState - EpochsState --> AccountsState - SPOState --> AccountsState - DRepState --> GovernanceState - GovernanceState --> AccountsState - ParametersState --> AccountsState -``` - -## Messages - -The messages passed between modules are defined in a single global enum in -the [Messages](messages) crate. - ## Processes There is currently only one process, for testing: - [Omnibus](processes/omnibus) - includes all the above modules for testing, by default using the internal message bus only + +## Build + +Everything is locally contained or is a crate depedency. To build the node, + +`make build` + +## Running the node + +The following will run the omnibus process. + +`make run` diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 00000000..0a60599e --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,160 @@ +# Acropolis Cardano Node +## Deliverable Descriptions: + +### **1. Archival Node** (formerly "Data node") + +A read-only node that synchronizes blockchain data and provides query access without participating in validation or consensus. + +**Who Uses This:** +- Users requiring blockchain data access without validation responsibilities +- Applications needing transaction submission capabilities to the network, e.g. DApps + +**Components Required:** +- Network: Miniprotocols, Upstream Chain Fetch, Snapshot Boot, Tx Submission Outbound +- Consensus: Chain Store +- Ledger: UTXOs, Pools, Governance, Stake, Monetary, Rewards +- APIs: Blockfrost + +**What It Does for External Users:** +- Synchronizes with the Cardano blockchain from genesis or a snapshot +- Stores a window complete ledger state (UTXOs, stake distribution, pool info, governance data) +- Provides REST API access (Blockfrost-compatible) to query blockchain data over the window of history +- Allows users to submit transactions to the network +- Acts as a read-only data source for wallets and applications + +**External Runtime Requirements:** +- **Needs to connect to:** Established Cardano relay nodes for initial sync +- **Network access:** Must reach multiple relay nodes (typically 3-5) for chain-fetch protocol +- **Storage:** Significant disk space for blockchain data (hundreds of GB) +- **Does NOT need:** Block producer credentials, stake pool keys, or direct peer-to-peer listening capabilities + +--- + +### **2. Validation Node** (formerly "Wallet") + +A node that fully validates all blocks and transactions according to Cardano's ledger rules, providing trustless verification of chain state. + +**Who Uses This:** +- Users requiring independent verification of blockchain state +- Applications needing cryptographic guarantees of chain validity +- Wallet applications + +**Components Required:** +- All components from Archival Node, plus: +- Network: Multi-peer Basic, Multi-peer Consensus +- Consensus: Header Validation, Tx Validation Phase 1, Chain Selection, Peer Management +- Ledger: Ledger Validation (full validation rules) + +**What It Does for External Users:** +- Validates all blocks and transactions according to ledger rules +- Maintains validated chain state with cryptographic guarantees +- Supports wallet backends with trusted validation +- Enables secure local transaction construction +- Provides confidence in chain data without trusting external APIs +- Can detect and reject invalid blocks/transactions + +**External Runtime Requirements:** +- **Needs to connect to:** Multiple diverse relay nodes for redundancy (5-10 peers recommended) +- **Network access:** Bidirectional TCP connections, can accept incoming connections from trusted peers +- **Validation overhead:** Higher CPU usage for script validation and signature checks +- **Does NOT need:** Ability to produce blocks, VRF keys, or KES keys +- **Does NOT provide:** Full mempool services or block propagation + +--- + +### **3. Relay Node** + +A publicly accessible node that propagates blocks and transactions across the network while maintaining a mempool and validating Plutus scripts. + +**Who Uses This:** +- **Stake pool operators (SPOs)** as part of their stake pool infrastructure to protect block-producing nodes +- Network participants contributing to blockchain decentralization and resilience + +**Components Required:** +- All components from Validation Node, plus: +- Network: Peer Server, Tx Submission Inbound +- Consensus: Tx Validation Phase 2 (Plutus Scripts), MemPool, Block Production (block validation only) + +**What It Does for External Users:** +- Acts as a network relay, propagating blocks and transactions across the network +- Validates Plutus scripts (Phase 2 validation) +- Maintains a mempool of pending transactions +- Accepts incoming connections from other nodes and wallets +- Serves as infrastructure for the decentralized network +- Provides high-availability access point for SPOs' block producers + +**External Runtime Requirements:** +- **Needs to connect to:** 20-50 other relay nodes in a diverse topology +- **Network access:** Must accept incoming connections (public IP or port forwarding) +- **Firewall configuration:** Open TCP port (typically 3001) for P2P communication +- **Bandwidth:** Sustained bandwidth for continuous block/tx propagation +- **Does NOT need:** Block signing keys, stake pool operational certificates +- **Topology:** Should connect to both community relays and your own block producer (if applicable) + +--- + +### **4. Block Producing Node** (formerly "Praos Block Producing Node") + +A full consensus node that participates in Ouroboros Praos to produce blocks when elected as slot leader. + +**Who Uses This:** +- **Stake pool operators (SPOs)** running registered stake pools to produce blocks and earn rewards + +**Components Required:** +- All components from Relay Node, plus: +- Network: Multi-peer Auto P2P, OP N164 Protocols, EB Distribution +- Consensus: Full block production capability, Leios MemPool +- Ledger: Leios Voting + +**What It Does for External Users:** +- Participates in Ouroboros Praos consensus as a block producer +- Generates blocks when elected by VRF lottery +- Signs blocks with operational certificates and KES keys +- Maintains full consensus state including leadership schedule +- Enables stake pool operation +- Can participate in governance actions (voting) + +**External Runtime Requirements:** +- **Needs to connect to:** Your own relay nodes (private topology) + trusted community relays +- **Network topology:** Should NOT be directly exposed to internet; connects through relay(s) +- **Credentials required:** + - VRF key (for leader election) + - KES keys (for block signing, rotated periodically) + - Operational certificate + - Stake pool registration on-chain +- **High availability:** Needs reliable uptime during slot leadership +- **Time synchronization:** NTP critical for accurate slot timing +- **Secure environment:** Air-gapped or highly secured key management + +--- + +### **5. Leios Node** (formerly "Leois Block Producing Node") + +A next-generation consensus node implementing the Leios protocol for significantly higher transaction throughput while maintaining Praos compatibility. + +**Who Uses This:** +- Early protocol adopters and testers (specific user types not yet documented as Leios is in research/development phase) + +**Components Required:** +- All components from Block Producing Node, plus: +- Network: Additional Leios-specific protocols +- Consensus: Leios consensus mechanism, EB/RB production +- Ledger: Leios voting, Blockfrost Leios extensions + +**What It Does for External Users:** +- Implements next-generation Leios consensus protocol +- Provides significantly higher transaction throughput +- Enables faster block production with Input Blocks (IBs) and Endorsement Blocks (EBs) +- Maintains backward compatibility with Praos +- Allows participation in experimental high-performance network + +**External Runtime Requirements:** +- **Needs to connect to:** Other Leios-enabled nodes (likely testnet initially) +- **Network requirements:** Higher bandwidth for increased throughput +- **All requirements from Block Producing Node:** Plus Leios-specific credentials +- **Experimental phase:** May require separate network or testnet participation +- **Does NOT immediately replace:** Praos consensus (gradual transition expected) + +--- + +Would you like me to elaborate on any specific deliverable or adjust the terminology?