Skip to content

Commit d3b0dea

Browse files
refcellrefcell
committed
cleanup
1 parent 12013e6 commit d3b0dea

51 files changed

Lines changed: 757 additions & 185 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 107 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,117 @@
1-
# kora
1+
<h1 align="center">
2+
<img src="./assets/banner.svg" alt="Kora" width="100%" align="center">
3+
</h1>
4+
5+
<h4 align="center">
6+
A minimal commonware + revm execution client. Built in Rust.
7+
</h4>
8+
9+
<p align="center">
10+
<img src="https://img.shields.io/crates/msrv/kora?style=flat&labelColor=1C2C2E&color=fbbf24&logo=rust&logoColor=white" alt="MSRV">
11+
<a href="https://github.com/refcell/kora/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/refcell/kora/ci.yml?style=flat&labelColor=1C2C2E&label=ci&logo=GitHub%20Actions&logoColor=white" alt="CI"></a>
12+
<a href="https://github.com/refcell/kora/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-d1d1f6.svg?style=flat&labelColor=1C2C2E&color=a78bfa&logo=googledocs&logoColor=white" alt="License"></a>
13+
</p>
14+
15+
<p align="center">
16+
<a href="#whats-kora">What's Kora?</a> •
17+
<a href="#usage">Usage</a> •
18+
<a href="#architecture">Architecture</a> •
19+
<a href="#contributing">Contributing</a> •
20+
<a href="#license">License</a>
21+
</p>
22+
23+
> [!CAUTION]
24+
> Kora is pre-alpha software. Do not expect this to run. Do not run this in production.
225
326
> [!IMPORTANT]
4-
>
5-
> This is pre-alpha software.
6-
> Do not expect this to run.
7-
> Do not run this in production.
27+
> Kora uses BLS12-381 threshold consensus via [commonware](https://github.com/commonwarexyz/monorepo), [REVM](https://github.com/bluealloy/revm) for EVM execution, and [QMDB](https://github.com/kora-labs/qmdb) for state storage.
28+
29+
## What's Kora?
30+
31+
Kora is a minimal, high-performance execution client built entirely in Rust. It combines commonware's BLS12-381 threshold consensus with REVM for EVM execution and QMDB for efficient state storage.
832

9-
A minimal [commonware](https://github.com/commonwarexyz/monorepo) + [revm](https://github.com/bluealloy/revm) execution client.
33+
The architecture is modular with distinct layers:
34+
- **Consensus** - BLS12-381 threshold signatures via commonware simplex
35+
- **Execution** - EVM state transitions powered by REVM
36+
- **Storage** - High-performance state management with QMDB
37+
- **Network** - P2P transport and message marshaling
1038

11-
## Build
39+
## Usage
40+
41+
Start the devnet with interactive DKG (Distributed Key Generation):
1242

1343
```sh
14-
cargo build --release
44+
just devnet
1545
```
1646

47+
> [!TIP]
48+
> See the [Justfile](./Justfile) for other useful commands.
49+
50+
### Devnet Commands
51+
52+
| Command | Description |
53+
|---------|-------------|
54+
| `just devnet` | Start the devnet with interactive DKG |
55+
| `just devnet-down` | Stop the devnet |
56+
| `just devnet-reset` | Reset devnet (clears all state, requires fresh DKG) |
57+
| `just devnet-logs` | View devnet logs |
58+
| `just devnet-status` | View devnet status |
59+
| `just devnet-stats` | Live devnet monitoring dashboard |
60+
61+
## Architecture
62+
63+
The devnet runs in three phases:
64+
65+
### Phase 0: Init Config
66+
Generates ed25519 identity keys for each validator node.
67+
68+
### Phase 1: DKG Ceremony
69+
Interactive threshold key generation using Ed25519 simplex consensus. Validators collaborate to generate a shared BLS12-381 threshold key.
70+
71+
### Phase 2: Validators
72+
Full validator nodes running:
73+
- BLS12-381 threshold consensus
74+
- REVM execution engine
75+
- QMDB state storage
76+
77+
### Observability
78+
Prometheus metrics with Grafana dashboards for monitoring.
79+
80+
### Crate Structure
81+
82+
```
83+
bin/
84+
├── kora # Main validator binary
85+
└── keygen # Key generation for devnet
86+
87+
crates/
88+
├── node/ # Node components
89+
│ ├── consensus # BLS threshold consensus
90+
│ ├── executor # REVM execution
91+
│ ├── ledger # Block/transaction ledger
92+
│ ├── txpool # Transaction pool
93+
│ ├── service # Node service orchestration
94+
│ ├── dkg # Distributed key generation
95+
│ └── ...
96+
├── storage/ # Storage layer
97+
│ ├── qmdb # QMDB integration
98+
│ ├── backend # Storage backend
99+
│ ├── handlers # State handlers
100+
│ ├── overlay # State overlay
101+
│ └── ...
102+
├── network/ # Network layer
103+
│ ├── transport # P2P transport
104+
│ └── marshal # Message serialization
105+
└── utilities/ # Utilities
106+
├── cli # CLI helpers
107+
├── crypto # Cryptographic utilities
108+
└── sys # System utilities
109+
```
110+
111+
## Contributing
112+
113+
Contributions are welcome! Please feel free to submit a Pull Request.
114+
17115
## License
18116

19-
MIT
117+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

‎assets/.gitkeep‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎assets/banner.svg‎

Lines changed: 15 additions & 0 deletions
Loading

‎bin/kora/README.md‎

Lines changed: 51 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,70 @@
33
[![CI](https://github.com/refcell/kora/actions/workflows/ci.yml/badge.svg)](https://github.com/refcell/kora/actions/workflows/ci.yml)
44
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
55

6-
A minimal commonware + revm execution client.
6+
The main Kora node binary. Implements BLS12-381 threshold consensus via [commonware], EVM execution with [revm], and state storage using [QMDB].
7+
8+
[commonware]: https://github.com/commonwarexyz/monorepo
9+
[revm]: https://github.com/bluealloy/revm
10+
[QMDB]: https://github.com/LayerZero-Labs/qmdb
711

812
## Usage
913

14+
### Running the Devnet
15+
1016
```bash
11-
# Run with default configuration
17+
just devnet
18+
```
19+
20+
### CLI Options
21+
22+
```bash
23+
# Run with default configuration (legacy mode)
1224
kora
1325

1426
# Run with a custom configuration file
1527
kora --config /path/to/config.toml
1628

1729
# Run with CLI overrides
1830
kora --chain-id 1 --data-dir /path/to/data
31+
32+
# Run DKG ceremony
33+
kora dkg --peers peers.json
34+
35+
# Run as validator (requires completed DKG)
36+
kora validator --peers peers.json
37+
```
38+
39+
| Flag | Description |
40+
|------|-------------|
41+
| `-c, --config <FILE>` | Path to TOML configuration file |
42+
| `--chain-id <ID>` | Override the chain ID |
43+
| `--data-dir <PATH>` | Override the data directory |
44+
| `-v, --verbose` | Enable verbose logging |
45+
46+
### Environment Variables
47+
48+
| Variable | Description |
49+
|----------|-------------|
50+
| `RUST_LOG` | Controls log level (e.g., `info`, `debug`, `kora=trace`) |
51+
52+
## Configuration
53+
54+
Kora uses TOML configuration files. See [`kora-config`](../../crates/node/config) for the full schema.
55+
56+
```toml
57+
chain_id = 1337
58+
data_dir = "/var/lib/kora"
59+
60+
[network]
61+
listen_addr = "0.0.0.0:9000"
62+
bootstrap_peers = []
1963
```
2064

65+
## Related Crates
66+
67+
- [`kora-service`](../../crates/node/service) - Node service orchestration
68+
- [`kora-config`](../../crates/node/config) - Configuration types and loading
69+
2170
## License
2271

2372
[MIT License](https://opensource.org/licenses/MIT)

‎crates/e2e/Cargo.toml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ workspace = true
1212

1313
[dependencies]
1414
# Local crates
15-
# kora-config.workspace = true # not currently used
1615
kora-consensus.workspace = true
1716
kora-crypto = { workspace = true, features = ["test-utils"] }
1817
kora-domain = { workspace = true, features = ["evm"] }
@@ -22,12 +21,10 @@ kora-marshal.workspace = true
2221
kora-overlay.workspace = true
2322
kora-qmdb-ledger.workspace = true
2423
kora-reporters.workspace = true
25-
# kora-service.workspace = true # not currently used
2624
kora-simplex.workspace = true
2725
kora-transport-sim.workspace = true
2826

2927
# Commonware
30-
# commonware-codec.workspace = true # not currently used
3128
commonware-consensus.workspace = true
3229
commonware-cryptography.workspace = true
3330
commonware-p2p.workspace = true
@@ -55,7 +52,6 @@ thiserror.workspace = true
5552

5653
# Tracing
5754
tracing.workspace = true
58-
# tracing-subscriber.workspace = true # not currently used
5955

6056
[dev-dependencies]
6157
rstest.workspace = true

‎crates/e2e/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# `kora-e2e`
2+
3+
[![CI](https://github.com/refcell/kora/actions/workflows/ci.yml/badge.svg)](https://github.com/refcell/kora/actions/workflows/ci.yml)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5+
6+
End-to-end testing framework for Kora consensus network.
7+
8+
This crate provides a simulation-based testing infrastructure for running
9+
multi-validator consensus tests without real networking. It enables testing
10+
of:
11+
12+
- Consensus finalization across multiple validators
13+
- Transaction execution and state convergence
14+
- Block production with proper ordering
15+
- Network partition recovery
16+
- Contract deployment and interaction
17+
18+
## Key Types
19+
20+
- `TestHarness` - Main test orchestration harness
21+
- `TestNode` - Individual validator node in tests
22+
- `TestSetup` - Test configuration and initialization
23+
- `TestConfig` - Configuration for test scenarios
24+
25+
## Running Tests
26+
27+
Tests in this crate use file-based storage and are resource-intensive.
28+
For reliable results, run with a single test thread:
29+
30+
```bash
31+
cargo test -p kora-e2e -- --test-threads=1
32+
```
33+
34+
## License
35+
36+
[MIT License](https://opensource.org/licenses/MIT)

‎crates/e2e/src/lib.rs‎

Lines changed: 6 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,15 @@
1-
//! End-to-end testing framework for Kora consensus network.
2-
//!
3-
//! This crate provides a simulation-based testing infrastructure for running
4-
//! multi-validator consensus tests without real networking. It enables testing
5-
//! of:
6-
//!
7-
//! - Consensus finalization across multiple validators
8-
//! - Transaction execution and state convergence
9-
//! - Block production with proper ordering
10-
//! - Network partition recovery
11-
//! - Contract deployment and interaction
12-
//!
13-
//! # Running Tests
14-
//!
15-
//! Tests in this crate use file-based storage and are resource-intensive.
16-
//! For reliable results, run with a single test thread:
17-
//!
18-
//! ```bash
19-
//! cargo test -p kora-e2e -- --test-threads=1
20-
//! ```
21-
1+
#![doc = include_str!("../README.md")]
2+
#![doc(issue_tracker_base_url = "https://github.com/refcell/kora/issues/")]
223
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
234
#![cfg_attr(not(test), warn(unused_crate_dependencies))]
245

256
mod harness;
26-
mod node;
27-
mod setup;
28-
297
pub use harness::{HarnessError, TestHarness, TestOutcome};
8+
9+
mod node;
3010
pub use node::TestNode;
11+
12+
mod setup;
3113
pub use setup::{TestConfig, TestSetup};
3214

3315
#[cfg(test)]

‎crates/network/marshal/README.md‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,26 @@
11
# `kora-marshal`
22

3-
The marshal handles block dissemination through commonware's
4-
[`Marshaled`][marshaled] application adapter.
3+
<a href="https://github.com/refcell/kora/actions/workflows/ci.yml"><img src="https://github.com/refcell/kora/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
4+
<a href="https://github.com/refcell/kora/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-d1d1f6.svg" alt="License"></a>
55

6+
Block dissemination handler using commonware's [`Marshaled`][marshaled] application adapter.
67

7-
The [`Marshaled`][marshaled] adapter handles epoch transitions
8-
and validates block ancestry. This adapter "wraps" the application
9-
to handle the following ancestry checks automatically during
10-
verification:
8+
## Overview
9+
10+
The [`Marshaled`][marshaled] adapter handles epoch transitions and validates block ancestry.
11+
This adapter "wraps" the application to handle the following ancestry checks automatically
12+
during verification:
1113

1214
- **Block Ancestry**: Parent Commitment matches the consensus context's expected parent.
1315
- **Epoch Transitions**: Block height is exactly one greater than the parent's height.
1416

17+
## Key Types
18+
19+
- `Marshal` - Core block dissemination handler
20+
- `MarshalConfig` - Configuration for marshal behavior
21+
22+
## License
23+
24+
[MIT License](https://github.com/refcell/kora/blob/main/LICENSE)
25+
1526
[marshaled]: https://docs.rs/commonware-consensus/latest/commonware_consensus/application/marshaled/struct.Marshaled.html

‎crates/network/transport-sim/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# `kora-transport-sim`
2+
3+
[![CI](https://github.com/refcell/kora/actions/workflows/ci.yml/badge.svg)](https://github.com/refcell/kora/actions/workflows/ci.yml)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5+
6+
Simulated P2P transport for Kora node testing and development.
7+
8+
## Key Types
9+
10+
- `SimMarshalChannels` - Marshaled channel abstraction for simulated transport
11+
- `SimSimplexChannels` - Simplex channel implementation for one-way communication
12+
- `SimContext` - Context for managing simulated transport state
13+
- `SimTransportError` - Error types for simulated transport operations
14+
- `SimTransportProvider` - Provider implementation for simulated transport
15+
- `SimControl` - Control interface for managing simulated network behavior
16+
17+
## License
18+
19+
[MIT License](https://opensource.org/licenses/MIT)

‎crates/network/transport-sim/src/lib.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! Simulated P2P transport for Kora node testing and development.
1+
#![doc = include_str!("../README.md")]
22
#![doc(issue_tracker_base_url = "https://github.com/refcell/kora/issues/")]
33
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
44
#![cfg_attr(not(test), warn(unused_crate_dependencies))]

0 commit comments

Comments
 (0)