Skip to content

Commit 30b811d

Browse files
will-break-itwill-break-it
authored
Topology checker tool (#138)
feat: Add topology checker for Ouroboros network analysis Introduces a new tool for analyzing and validating Ouroboros network topologies. The topology checker provides comprehensive insights into network structure, connectivity patterns, and stake distribution. Key features: - Network statistics (connections, diameter, clustering) - Stake-weighted metrics for analyzing high-stake node connectivity - Network reliability analysis identifying critical nodes - Geographic stake distribution analysis - Connection symmetry analysis in directed graph - Triangle inequality validation for latency optimization The tool accepts YAML topology files and generates detailed Markdown reports with: - Basic network metrics (nodes, connections, latencies) - Stake distribution analysis with Gini coefficient - Geographic distribution of stake across regions - Critical nodes that could isolate significant stake - Potential topology optimizations
1 parent ae63afc commit 30b811d

File tree

11 files changed

+1163
-0
lines changed

11 files changed

+1163
-0
lines changed

‎.github/workflows/ci.yaml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,33 @@ jobs:
224224
echo "Cargo test failed"
225225
exit 1
226226
fi
227+
################################################################################
228+
# Tools - Topology checker
229+
################################################################################
230+
231+
topology-checker-check:
232+
name: "topology-checker: Check and Test"
233+
if: |
234+
github.event_name == 'push' &&
235+
(contains(github.event.commits.*.modified, 'topology-checker/') ||
236+
contains(github.event.commits.*.modified, 'data/simulation/topology*.yaml') ||
237+
contains(github.event.commits.*.modified, 'data/simulation/topology*.json')) ||
238+
github.event_name == 'pull_request' &&
239+
(contains(github.event.pull_request.files.*.path, 'topology-checker/') ||
240+
contains(github.event.pull_request.files.*.path, 'data/simulation/topology*.yaml') ||
241+
contains(github.event.pull_request.files.*.path, 'data/simulation/topology*.json'))
242+
runs-on: ubuntu-22.04
243+
steps:
244+
- uses: actions/checkout@v4
245+
- name: Check and test topology checker
246+
working-directory: topology-checker
247+
run: |
248+
cargo check
249+
cargo test
250+
if [ $? -ne 0 ]; then
251+
echo "Topology checker tests failed"
252+
exit 1
253+
fi
227254
228255
################################################################################
229256
# Documentation - under various directories

‎topology-checker/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Generated by Cargo
2+
/target/
3+
4+
# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
5+
# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
6+
Cargo.lock
7+
8+
# IDE specific files
9+
.idea/
10+
.vscode/
11+
*.swp
12+
*.swo
13+
14+
# Debug files
15+
**/*.rs.bk
16+
*.pdb
17+
18+
# Generated reports
19+
report.md
20+
*.log
21+
22+
# OS specific files
23+
.DS_Store
24+
.env

‎topology-checker/Cargo.toml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[package]
2+
name = "topology-checker"
3+
version = "0.1.0"
4+
edition = "2021"
5+
6+
[dependencies]
7+
clap = { version = "4.4.11", features = ["derive"] }
8+
serde = { version = "1.0", features = ["derive"] }
9+
serde_yaml = "0.9"
10+
indexmap = { version = "2.1.0", features = ["serde"] }

‎topology-checker/README.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Topology Checker
2+
3+
A tool for analyzing and validating Ouroboros network topologies.
4+
5+
## Input Format
6+
7+
The tool accepts topology files in YAML format that conform to the
8+
[Ouroboros topology schema](../data/simulation/topology.schema.json). The
9+
topology describes:
10+
11+
- Nodes with their stake and location (cluster-based or coordinate-based)
12+
- Producer relationships between nodes
13+
- Network characteristics (latency, bandwidth, CPU cores)
14+
15+
See the [example topology](../data/simulation/topology-dense-52.yaml) for a
16+
complete reference.
17+
18+
## Features
19+
20+
The following metrics and checks are available. Click on any metric name for
21+
detailed information.
22+
23+
### Network Statistics
24+
25+
| Metric | Description |
26+
| ------------------------------------------ | ----------------------------------------- |
27+
| [Node Counts](#network-metrics) | Distribution of node types in the network |
28+
| [Connection Metrics](#network-metrics) | Network connection density |
29+
| [Network Diameter](#network-metrics) | Maximum hops between any two nodes |
30+
| [Clustering Coefficient](#network-metrics) | Local interconnectedness measure |
31+
| [Latency Statistics](#network-metrics) | Network delay measurements |
32+
| [Connection Symmetry](#network-metrics) | Analysis of bidirectional connections |
33+
| [Stake-Weighted Metrics](#network-metrics) | Impact of topology on high-stake nodes |
34+
35+
### Stake Distribution Analysis
36+
37+
| Metric | Description |
38+
| ------------------------------------------------------ | ------------------------------------- |
39+
| [Total Stake](#stake-distribution-metrics) | Sum of stake across all nodes |
40+
| [Gini Coefficient](#stake-distribution-metrics) | Stake distribution equality measure |
41+
| [Top Stake Holders](#stake-distribution-metrics) | Highest stake concentration analysis |
42+
| [Geographic Distribution](#stake-distribution-metrics) | Regional stake concentration analysis |
43+
44+
### Connectivity Analysis
45+
46+
| Check | Description |
47+
| -------------------------------------------- | ----------------------------- |
48+
| [Triangle Inequality](#connectivity-metrics) | Suboptimal path detection |
49+
| [Network Resilience](#connectivity-metrics) | Connectivity failure analysis |
50+
51+
## Usage
52+
53+
Run the topology checker with:
54+
55+
```bash
56+
cargo run -- -i <topology_file>
57+
```
58+
59+
Example using the dense topology:
60+
61+
```bash
62+
cargo run -- -i ../data/simulation/topology-dense-52.yaml -o report.md
63+
```
64+
65+
The tool will analyze the topology and generate a report containing:
66+
67+
- Basic network statistics
68+
- Stake distribution analysis
69+
- Latency analysis
70+
- Connectivity issues and suggestions
71+
72+
## Example Output
73+
74+
Below is an example report generated from a dense topology with 52 nodes:
75+
76+
```markdown
77+
# Topology Analysis Report
78+
79+
Source topology: ../data/simulation/topology-dense-52.yaml
80+
81+
## Network Statistics
82+
83+
| Metric | Value |
84+
| ---------------------------- | --------- |
85+
| Total nodes | 52 |
86+
| Block producers | 52 |
87+
| Relay nodes | 0 |
88+
| Total connections | 312 |
89+
| Network diameter | 5 hops |
90+
| Average connections per node | 6.00 |
91+
| Clustering coefficient | 0.284 |
92+
| Average latency | 31.41 ms |
93+
| Maximum latency | 138.44 ms |
94+
| Stake-weighted latency | 35.62 ms |
95+
| Bidirectional connections | 156 |
96+
| Asymmetric connections | 68 |
97+
| Asymmetry ratio | 21.79% |
98+
99+
## Network Reliability
100+
101+
The following nodes, if removed, would isolate significant stake:
102+
103+
| Node | Isolated Stake | % of Total Stake |
104+
| ------- | -------------- | ---------------- |
105+
| node-12 | 800 | 15.38% |
106+
| node-45 | 600 | 11.54% |
107+
| node-31 | 400 | 7.69% |
108+
109+
## Stake Distribution
110+
111+
| Metric | Value |
112+
| ---------------- | ----- |
113+
| Total stake | 5200 |
114+
| Gini coefficient | 0.000 |
115+
116+
### Top 5 Stake Holders
117+
118+
| Node | Stake | % of Total |
119+
| ------ | ----- | ---------- |
120+
| node-0 | 100 | 1.92% |
121+
| node-1 | 100 | 1.92% |
122+
| node-2 | 100 | 1.92% |
123+
| node-3 | 100 | 1.92% |
124+
| node-4 | 100 | 1.92% |
125+
126+
### Geographic Stake Distribution
127+
128+
| Region | Nodes | Total Stake | % of Network |
129+
| -------------- | ----- | ----------- | ------------ |
130+
| ap-southeast-2 | 17 | 1700 | 32.69% |
131+
| eu-central-1 | 18 | 1800 | 34.62% |
132+
| us-east-1 | 17 | 1700 | 32.69% |
133+
134+
## Geographic Validation
135+
136+
✅ No geographic violations found
137+
```
138+
139+
## Glossary
140+
141+
### Network Metrics
142+
143+
- **Network Diameter**: The maximum number of hops needed to reach any node from
144+
any other node. A smaller diameter (e.g., 5 hops) indicates a well-connected
145+
network where information can propagate quickly.
146+
147+
- **Connection Symmetry**: Analysis of bidirectional connectivity between nodes.
148+
- Bidirectional Connections: Number of node pairs with connections in both
149+
directions
150+
- Asymmetric Connections: Number of one-way connections between nodes
151+
- Asymmetry Ratio: Percentage of total connections that are asymmetric
152+
- Important for understanding communication patterns and potential bottlenecks
153+
154+
- **Clustering Coefficient** (0-1): Measures how well nodes are interconnected
155+
with their neighbors.
156+
- 0: No clustering, nodes' neighbors are not connected to each other
157+
- 1: Perfect clustering, all possible connections exist between neighbors
158+
- Example: 0.284 indicates moderate local connectivity
159+
160+
- **Latency**: Time delay between nodes.
161+
- Average latency: Mean delay across all connections
162+
- Maximum latency: Worst-case delay in the network
163+
- High latencies can impact block propagation and consensus
164+
165+
- **Stake-Weighted Metrics**: Analysis of network properties weighted by stake.
166+
- Stake-Weighted Latency: Average latency weighted by stake importance
167+
- For each connection, weight = (stake of connecting node) × (stake of
168+
producer node)
169+
- Higher weights make latencies between high-stake nodes more significant
170+
- Lower values indicate better connectivity between important nodes
171+
- Higher values suggest high-stake nodes might have suboptimal connections
172+
- Network Reliability: Analysis of stake isolation risk
173+
- Lists nodes whose failure would disconnect portions of stake from the
174+
network
175+
- Shows percentage of total stake that would be isolated
176+
- Helps identify critical nodes for network resilience
177+
178+
### Stake Distribution Metrics
179+
180+
- **Gini Coefficient** (0-1): Measures inequality in stake distribution.
181+
- 0.000: Perfect equality (all nodes have equal stake)
182+
- 0.500: Moderate inequality
183+
- 1.000: Perfect inequality (one node has all stake)
184+
- Lower values indicate more decentralized networks
185+
186+
- **Total Stake**: Sum of all stake in the network. Used as the denominator when
187+
calculating stake percentages.
188+
189+
- **Top Stake Holders**: Identifies concentration of stake.
190+
- Lists nodes with highest stake
191+
- Shows percentage of total network stake
192+
- Helps identify potential centralization
193+
194+
- **Geographic Distribution**: Analysis of stake distribution across
195+
regions/clusters.
196+
- Shows stake concentration by region
197+
- Indicates regional node density
198+
- Helps identify geographic centralization risks
199+
- Important for network resilience against regional outages
200+
201+
### Connectivity Metrics
202+
203+
- **Triangle Inequality Violations**: Cases where an indirect path between nodes
204+
has lower latency than the direct connection.
205+
- May indicate suboptimal network topology
206+
- Could suggest missing beneficial direct connections
207+
208+
- **Network Resilience**: Analysis of network's ability to maintain connectivity
209+
if nodes or connections fail.
210+
- Identifies critical paths
211+
- Suggests redundancy improvements
212+
- Important for network reliability
213+
214+
## Requirements
215+
216+
- Rust toolchain
217+
- Cargo package manager

0 commit comments

Comments
 (0)