Skip to content

Commit bdfc829

Browse files
AlejandroCabezaAlejandroCabeza
authored
chore: Improve README (#1089)
1 parent 693d2bc commit bdfc829

File tree

1 file changed

+112
-27
lines changed

1 file changed

+112
-27
lines changed

‎README.md

+112-27
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,54 @@
1-
# nomos-node
2-
Nomos blockchain node mvp
1+
# Nomos
32

3+
Nomos is the blockchain layer of the Logos technology stack, providing a privacy-preserving and censorship-resistant
4+
framework for decentralized network states.
45

5-
## Project structure
6+
This monorepo serves as a unified codebase for the Nomos ecosystem, housing all core components, services, and tools
7+
necessary for running and interacting with the Nomos blockchain. Key features include:
68

7-
- `nomos-core`: Nomos core is the collection of essential structures for the Nomos mvp and experimental nodes.
8-
- `nomos-services`: Nomos services is the collection of components that are used as building blocks of the Nomos node prototype and the experimental nodes.
9-
- consensus
10-
- log
11-
- http
12-
- mempool
13-
- network
14-
- `nodes`: Nomos nodes is the collection of nodes that are used to run the Nomos mvp and experimental nodes.
15-
- `nomos-node`: main implementation of the Nomos mvp node.
16-
- `mockpool-node`: node with single mempool service, used to measure transaction dissemination.
9+
- Consensus mechanisms for secure and scalable network agreement
10+
- Ledger management for state persistence and validation
11+
- Networking layers leveraging libp2p for peer-to-peer communication
12+
- CLI tools and clients for seamless interaction with the blockchain
13+
- Testnet configurations for development and experimentation
1714

15+
## Table of Contents
1816

19-
## Services
17+
- [Requirements](#requirements)
18+
- [Design Goals](#design-goals)
19+
- [Service Architecture](#service-architecture)
20+
- [Static Dispatching](#static-dispatching)
21+
- [Project Structure](#project-structure)
22+
- [Development Workflow](#development-workflow)
23+
- [Docker](#docker)
24+
- [Running Tests](#running-tests)
25+
- [Generating Documentation](#generating-documentation)
26+
- [Contributing](#contributing)
27+
- [License](#license)
28+
- [Community](#community)
2029

21-
The Nomos node uses `Overwatch` as its main internal framework. This means that services request communication channels
22-
to other services to interchange information through a specified messaging API.
30+
## Requirements
2331

24-
### Service architecture
32+
- **Rust**
33+
- We aim to maintain compatibility with the latest stable version of Rust.
34+
- [Installation Guide](https://www.rust-lang.org/tools/install)
2535

26-
Most of the services are implemented with the same idea behind. There is a front layer responsible for handling the `Overwatch` service
27-
and a back layer that implements the actual service logic.
36+
- **Risc0**
37+
- Required for zero-knowledge proof functionality.
38+
- [Installation Guide](https://dev.risczero.com/api/zkvm/install)
39+
40+
## Design Goals
41+
42+
### Service Architecture
43+
44+
Nomos services follow a consistent design pattern: a front layer handles the `Overwatch` service, while a back layer
45+
implements the actual service logic.
46+
47+
This modular approach allows for easy replacement of components in a declarative manner.
2848

29-
This allows us to easily replace components as needed in a type level system. In any case, a node can be setup in a declarative way composing the types.
3049
For example:
3150

32-
```rust
33-
...
51+
```rust ignore
3452
#[derive(Services)]
3553
struct MockPoolNode {
3654
logging: OpaqueServiceHandle<Logger>,
@@ -41,20 +59,61 @@ struct MockPoolNode {
4159
}
4260
```
4361

62+
### Static Dispatching
4463

64+
Nomos favours static dispatching over dynamic, influenced by Overwatch.
65+
This means you'll encounter Generics sprinkled throughout the codebase.
66+
While it might occasionally feel a bit over the top, it brings some solid advantages, such as:
4567

46-
## Docker
68+
- Compile-time type checking
69+
- Highly modular and adaptable applications
70+
71+
## Project Structure
72+
73+
```
74+
nomos/
75+
├── book/ # Documentation in Markdown format
76+
├── ci/ # Non-GitHub scripts, such as Jenkins' nightly integration and fuzzy testing
77+
├── clients/ # General-purpose clients
78+
├── consensus/ # Engine and protocols for agreement and validation
79+
├── ledger/ # Ledger management and state transition logic
80+
├── nodes/ # Node implementations
81+
├── nomos-blend/ # Blend Network, our privacy routing protocol
82+
├── nomos-bundler/ # Crate packaging and bundling
83+
├── nomos-cli/ # Command-line interface for interacting with the Nomos blockchain
84+
├── nomos-core/ # Collection of essential structures
85+
├── nomos-da/ # Data availability layer
86+
├── nomos-libp2p/ # Libp2p integration
87+
├── nomos-services/ # Building blocks for the Node
88+
├── nomos-tracing/ # Tracing, logging, and metrics
89+
├── nomos-utils/ # Shared utility functions and helpers
90+
├── testnet/ # Testnet configurations, monitoring, and deployment scripts
91+
└── tests/ # Integration and E2E test suites
92+
```
4793

48-
To build and run a docker container with the Nomos node you need to mount both `config.yml` and `global_params_path` specified in the configuration.
94+
## Development Workflow
95+
96+
### Docker
97+
98+
#### Building the Image
99+
100+
To build the Nomos Docker image, run:
49101

50102
```bash
51103
docker build -t nomos .
104+
```
52105

53-
docker run -v "/path/to/config.yml" -v "/path/to/global_params:global/params/path" nomos /etc/nomos/config.yml
106+
#### Running a Nomos Node
107+
108+
To run a docker container with the Nomos node you need to mount both `config.yml` and `global_params_path` specified in
109+
the configuration.
54110

111+
```bash
112+
docker run -v "/path/to/config.yml" -v "/path/to/global_params:global/params/path" nomos /etc/nomos/config.yml
55113
```
56114

57-
To use an example configuration located at `nodes/nomos-node/config.yaml`, first run the test that generates the random kzgrs file and then run the docker container with the appropriate config and global params:
115+
To use an example configuration located at `nodes/nomos-node/config.yaml`, first run the test that generates the random
116+
kzgrs file and then run the docker container with the appropriate config and global params:
58117

59118
```bash
60119
cargo test --package kzgrs-backend write_random_kzgrs_params_to_file -- --ignored
@@ -63,10 +122,36 @@ docker run -v "$(pwd)/nodes/nomos-node/config.yaml:/etc/nomos/config.yml" -v "$(
63122

64123
```
65124

125+
## Running Tests
126+
127+
To run the test suite, use:
128+
129+
```bash
130+
cargo test
131+
```
132+
133+
## Generating Documentation
134+
135+
To generate the project documentation locally, run:
136+
137+
```bash
138+
cargo doc
139+
```
140+
141+
## Contributing
142+
143+
We welcome contributions! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.
66144

67145
## License
68146

69147
This project is primarily distributed under the terms defined by either the MIT license or the
70148
Apache License (Version 2.0), at your option.
71149

72-
See [LICENSE-APACHE](LICENSE-APACHE2.0) and [LICENSE-MIT](LICENSE-MIT) for details.
150+
See [LICENSE-APACHE2.0](LICENSE-APACHE2.0) and [LICENSE-MIT](LICENSE-MIT) for details.
151+
152+
## Community
153+
154+
Join the Nomos community on [Discord](https://discord.gg/8Q7Q7vz) and follow us
155+
on [Twitter](https://twitter.com/nomos_tech).
156+
157+
For more information, visit [nomos.tech](https://nomos.tech/?utm_source=chatgpt.com).

0 commit comments

Comments
 (0)