Skip to content

Commit dffa20b

Browse files
buddhistheadbuddhisthead
authored
Merge pull request #351 from input-output-hk/cet-overview-doc
Add some overview documentation about what we're building; update README
2 parents 1db69bc + eeb9259 commit dffa20b

File tree

3 files changed

+186
-74
lines changed

3 files changed

+186
-74
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,17 @@
1-
# Pull Request Title
2-
3-
<!--
4-
Use a short, descriptive title:
5-
Example: `node: fix crash when config is absent`
6-
-->
7-
81
## Description
92

10-
<!--
113
Describe what this PR does and why. Keep it concise but include enough context
124
for reviewers who are not familiar with the area.
13-
-->
145

156
## Related Issue(s)
16-
17-
<!--
187
Link any related issues, e.g. `Fixes #123` or `Relates to #456`.
19-
-->
208

219
## How was this tested?
22-
23-
<!--
2410
Describe the tests that you ran to verify your changes. Include instructions
2511
so reviewers can reproduce. Examples:
2612
- unit tests (command)
2713
- integration tests (how to run)
2814
- manual steps
29-
-->
3015

3116
## Checklist
3217

@@ -36,14 +21,8 @@ so reviewers can reproduce. Examples:
3621
- [ ] CI is green for this PR
3722

3823
## Impact / Side effects
39-
40-
<!--
4124
Describe any potential side effects, e.g. performance, compatibility, or security concerns.
4225
If the PR introduces a breaking change, explain migration steps for users.
43-
-->
4426

4527
## Reviewer notes / Areas to focus
46-
47-
<!--
4828
If you want specific feedback, list files/functions to review or aspects you are unsure about.
49-
-->

‎README.md‎

Lines changed: 30 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,24 @@
11
# Acropolis
22

3-
Acropolis is a project to create a kit of micro-service parts, written in
3+
Acropolis is a project to create a kit of modular parts, written in
44
Rust, which allows flexible construction of clients, services and APIs for
55
the Cardano ecosystem.
66

7+
## Status
8+
9+
This project has moved out of the experimental phase and is being implemented
10+
according to a set of deliverables documented in the Treasury Fund Milestones.
11+
12+
# Overview and Deliverables
13+
14+
The Acropolis Cardano Node is a rust implementation that seeks parity with the
15+
Haskell implementation and is intended to be a full block producing node on mainnet.
16+
Please see the [overview document](docs/overview.md) that describes the phases of
17+
development, descriptions, expected use cases, and runtime environments expected
18+
of each of the deliverables.
19+
20+
# Architecture
21+
722
Acropolis is based on the
823
[Caryatid framework](https://github.com/input-output-hk/caryatid),
924
which in turn uses a message bus such as [RabbitMQ](https://www.rabbitmq.com/)
@@ -12,7 +27,7 @@ to communicate between micro-services.
1227
```mermaid
1328
graph TB
1429
15-
subgraph Microservice A
30+
subgraph Process A
1631
Module1(Module 1)
1732
Module2(Module 2)
1833
Caryatid1(Caryatid Framework)
@@ -21,7 +36,7 @@ graph TB
2136
Module2 <--> Caryatid1
2237
end
2338
24-
subgraph Microservice B
39+
subgraph Process B
2540
Module3(Module 3)
2641
2742
Caryatid2(Caryatid Framework)
@@ -39,9 +54,6 @@ graph TB
3954

4055
## Modules
4156

42-
This project is in an experimental phase at the moment, and the module
43-
structure is highly subject to change:
44-
4557
- [Upstream Chain Fetcher](modules/upstream_chain_fetcher) -
4658
implementation of the Node-to-Node (N2N) client-side (initiator)
4759
protocol, allowing chain synchronisation and block fetching
@@ -62,56 +74,21 @@ structure is highly subject to change:
6274
- [Accounts State](modules/accounts_state) - stake and reward accounts tracker
6375
- [Assets State](modules/assets_state) - tracks native asset supply, metadata, transactions, and addresses
6476

65-
```mermaid
66-
graph LR
67-
68-
UpstreamChainFetcher(Upstream Chain Fetcher)
69-
GenesisBootstrapper(Genesis Bootstrapper)
70-
MithrilSnapshotFetcher(Mithril Snapshot Fetcher)
71-
BlockUnpacker(Block Unpacker)
72-
TxUnpacker(Transaction Unpacker)
73-
UTXOState(UTXO State)
74-
SPOState(SPO State)
75-
DRepState(DRep State)
76-
GovernanceState(Governance State)
77-
StakeDeltaFilter(Stake Delta Filter)
78-
EpochsState(Epochs State)
79-
AccountsState(Accounts State)
80-
AssetsState(Assets State)
81-
ParametersState(Parameters State)
82-
83-
UpstreamChainFetcher --> BlockUnpacker
84-
MithrilSnapshotFetcher --> BlockUnpacker
85-
BlockUnpacker --> TxUnpacker
86-
GenesisBootstrapper --> UTXOState
87-
TxUnpacker --> UTXOState
88-
TxUnpacker --> AssetsState
89-
TxUnpacker --> EpochsState
90-
TxUnpacker --> AccountsState
91-
TxUnpacker --> DRepState
92-
TxUnpacker --> SPOState
93-
TxUnpacker --> GovernanceState
94-
GovernanceState --> ParametersState
95-
TxUnpacker --> ParametersState
96-
UTXOState --> StakeDeltaFilter
97-
StakeDeltaFilter --> AccountsState
98-
UpstreamChainFetcher --> EpochsState
99-
MithrilSnapshotFetcher --> EpochsState
100-
EpochsState --> AccountsState
101-
SPOState --> AccountsState
102-
DRepState --> GovernanceState
103-
GovernanceState --> AccountsState
104-
ParametersState --> AccountsState
105-
```
106-
107-
## Messages
108-
109-
The messages passed between modules are defined in a single global enum in
110-
the [Messages](messages) crate.
111-
11277
## Processes
11378

11479
There is currently only one process, for testing:
11580

11681
- [Omnibus](processes/omnibus) - includes all the above modules for
11782
testing, by default using the internal message bus only
83+
84+
## Build
85+
86+
Everything is locally contained or is a crate dependency. To build the node,
87+
88+
`make build`
89+
90+
## Running the node
91+
92+
The following will run the omnibus process.
93+
94+
`make run`

‎docs/overview.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Acropolis Cardano Node
2+
## Deliverable Descriptions:
3+
4+
### **1. Archival Node** (formerly "Data node")
5+
6+
A read-only node that synchronizes blockchain data and provides query access without participating in validation or consensus.
7+
8+
**Who Uses This:**
9+
- Users requiring blockchain data access without validation responsibilities
10+
- Applications needing transaction submission capabilities to the network, e.g. DApps
11+
12+
**Components Required:**
13+
- Network: Miniprotocols, Upstream Chain Fetch, Snapshot Boot, Tx Submission Outbound
14+
- Consensus: Chain Store
15+
- Ledger: UTXOs, Pools, Governance, Stake, Monetary, Rewards
16+
- APIs: Blockfrost
17+
18+
**What It Does for External Users:**
19+
- Synchronizes with the Cardano blockchain from genesis or a snapshot
20+
- Stores a window complete ledger state (UTXOs, stake distribution, pool info, governance data)
21+
- Provides REST API access (Blockfrost-compatible) to query blockchain data over the window of history
22+
- Allows users to submit transactions to the network
23+
- Acts as a read-only data source for wallets and applications
24+
25+
**External Runtime Requirements:**
26+
- **Needs to connect to:** Established Cardano relay nodes for initial sync
27+
- **Network access:** Must reach multiple relay nodes (typically 3-5) for chain-fetch protocol ("multi-peer basic")
28+
- **Storage:** Significant disk space for blockchain data (hundreds of GB)
29+
- **Does NOT need:** Block producer credentials, stake pool keys, or direct peer-to-peer listening capabilities
30+
31+
---
32+
33+
### **2. Validation Node** (formerly "Wallet")
34+
35+
A node that fully validates all blocks and transactions according to Cardano's ledger rules, providing trustless verification of chain state.
36+
37+
**Who Uses This:**
38+
- Users requiring independent verification of blockchain state
39+
- Applications needing cryptographic guarantees of chain validity
40+
- Wallet applications
41+
42+
**Components Required:**
43+
- All components from Archival Node, plus:
44+
- Network: Multi-peer Consensus
45+
- Consensus: Header Validation, Tx Validation Phase 1, Chain Selection, Peer Management
46+
- Ledger: Ledger Validation (full validation rules)
47+
48+
**What It Does for External Users:**
49+
- Validates all blocks and transactions according to ledger rules
50+
- Maintains validated chain state with cryptographic guarantees
51+
- Supports wallet backends with trusted validation
52+
- Enables secure local transaction construction
53+
- Provides confidence in chain data without trusting external APIs
54+
- Can detect and reject invalid blocks/transactions
55+
56+
**External Runtime Requirements:**
57+
- **Needs to connect to:** Multiple diverse relay nodes for redundancy (5-10 peers recommended)
58+
- **Network access:** Bidirectional TCP connections, can accept incoming connections from untrusted peers
59+
- **Validation overhead:** Higher CPU usage for script validation and signature checks
60+
- **Does NOT need:** Ability to produce blocks, VRF keys, or KES keys
61+
- **Does NOT provide:** Full mempool services or block propagation
62+
63+
---
64+
65+
### **3. Relay Node**
66+
67+
A publicly accessible node that propagates blocks and transactions across the network while maintaining a mempool and validating Plutus scripts.
68+
69+
**Who Uses This:**
70+
- **Stake pool operators (SPOs)** as part of their stake pool infrastructure to protect block-producing nodes
71+
- Network participants contributing to blockchain decentralization and resilience
72+
73+
**Components Required:**
74+
- All components from Validation Node, plus:
75+
- Network: Peer Server, Tx Submission Inbound
76+
- Consensus: Tx Validation Phase 2 (Plutus Scripts), MemPool, Block Production (block validation only)
77+
78+
**What It Does for External Users:**
79+
- Acts as a network relay, propagating blocks and transactions across the network
80+
- Validates Plutus scripts (Phase 2 validation)
81+
- Maintains a mempool of pending transactions
82+
- Accepts incoming connections from other nodes and wallets
83+
- Serves as infrastructure for the decentralized network
84+
- Provides high-availability access point for SPOs' block producers
85+
86+
**External Runtime Requirements:**
87+
- **Needs to connect to:** 20-50 other relay nodes in a diverse topology
88+
- **Network access:** Must accept incoming connections (public IP or port forwarding)
89+
- **Firewall configuration:** Open TCP port (typically 3001) for P2P communication
90+
- **Bandwidth:** Sustained bandwidth for continuous block/tx propagation
91+
- **Does NOT need:** Block signing keys, stake pool operational certificates
92+
- **Topology:** Should connect to both community relays and your own block producer (if applicable)
93+
94+
---
95+
96+
### **4. Block Producing Node** (formerly "Praos Block Producing Node")
97+
98+
A full consensus node that participates in Ouroboros Praos to produce blocks when elected as slot leader.
99+
100+
**Who Uses This:**
101+
- **Stake pool operators (SPOs)** running registered stake pools to produce blocks and earn rewards
102+
103+
**Components Required:**
104+
- All components from Relay Node, plus:
105+
- Network: Multi-peer Auto P2P, OP N164 Protocols, EB Distribution
106+
- Consensus: Full block production capability
107+
- Ledger:
108+
109+
**What It Does for External Users:**
110+
- Participates in Ouroboros Praos consensus as a block producer
111+
- Generates blocks when elected by VRF lottery
112+
- Signs blocks with operational certificates and KES keys
113+
- Maintains full consensus state including leadership schedule
114+
- Enables stake pool operation
115+
- Can participate in governance actions (voting)
116+
117+
**External Runtime Requirements:**
118+
- **Needs to connect to:** Your own relay nodes (private topology) + trusted community relays
119+
- **Network topology:** Should NOT be directly exposed to internet; connects through relay(s)
120+
- **Credentials required:**
121+
- VRF key (for leader election)
122+
- KES keys (for block signing, rotated periodically)
123+
- Operational certificate
124+
- Stake pool registration on-chain
125+
- **High availability:** Needs reliable uptime during slot leadership
126+
- **Time synchronization:** NTP critical for accurate slot timing
127+
- **Secure environment:** Air-gapped or highly secured key management
128+
129+
---
130+
131+
### **5. Leios Node** (formerly "Leios Block Producing Node")
132+
133+
A next-generation consensus node implementing the Leios protocol for significantly higher transaction throughput while maintaining Praos compatibility.
134+
135+
**Who Uses This:**
136+
- Early protocol adopters and testers (specific user types not yet documented as Leios is in research/development phase)
137+
138+
**Components Required:**
139+
- All components from Block Producing Node, plus:
140+
- Network: Additional Leios-specific protocols
141+
- Consensus: Leios consensus mechanism, EB/RB production
142+
- Ledger: Leios voting, Blockfrost Leios extensions
143+
144+
**What It Does for External Users:**
145+
- Implements next-generation Leios consensus protocol
146+
- Provides significantly higher transaction throughput
147+
- Enables faster block production with Input Blocks (IBs) and Endorsement Blocks (EBs)
148+
- Maintains backward compatibility with Praos
149+
- Allows participation in experimental high-performance network
150+
151+
**External Runtime Requirements:**
152+
- **Needs to connect to:** Other Leios-enabled nodes (likely testnet initially)
153+
- **Network requirements:** Higher bandwidth for increased throughput
154+
- **All requirements from Block Producing Node:** Plus Leios-specific credentials
155+
- **Experimental phase:** May require separate network or testnet participation
156+
- **Does NOT immediately replace:** Praos consensus (gradual transition expected)

0 commit comments

Comments
 (0)