Skip to content

Commit 6998140

Browse files
arec1b0arec1b0
committed
new file: LICENS
 modified: README.md modified: docs/architecture.md modified: docs/contributing.md modified: docs/getting_started.md modified: docs/setup_guide.md
1 parent f4c96cd commit 6998140

File tree

6 files changed

+335
-26
lines changed

6 files changed

+335
-26
lines changed

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Daniil Krizhanovskyi
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the \"Software\"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Nim Blockchain Node
2+
3+
## 🚀 Introduction
4+
The Nim Blockchain Node is a modular, high-performance blockchain node implementation written in the Nim programming language, designed for security, scalability, and maintainability. It provides a clear separation of concerns through distinct layers and leverages advanced cryptographic techniques.
5+
6+
## 🧱 Key Components
7+
- **Core Engine Layer:** Handles consensus mechanisms, virtual machine execution, and state management.
8+
- **Cryptography Layer:** Provides key management, signature verification, and zero-knowledge proofs.
9+
- **Network Layer:** Manages peer-to-peer communication, mempool handling, and block propagation.
10+
- **Storage Layer:** Offers efficient and reliable blockchain, index, and state data storage.
11+
12+
## 🚀 Quick Start
13+
```shell
14+
git clone https://github.com/dkrizhanovskyi/nim-blockchain-node.git
15+
cd nim-blockchain-node
16+
nimble install
17+
nimble build
18+
.\main.exe
19+
```
20+
21+
## 🧪 Testing
22+
Run tests to ensure reliability:
23+
```shell
24+
nimble test
25+
```
26+
27+
## 📚 Documentation
28+
Explore more detailed documentation in the `docs` folder:
29+
- [Architecture](docs/architecture.md)
30+
- [Setup Guide](docs/setup_guide.md)
31+
- [Getting Started](docs/getting_started.md)
32+
- [Contributing](docs/contributing.md)
33+
34+
## 🔐 Security
35+
Follow security best practices outlined in the documentation and regularly update cryptographic dependencies.
36+
37+
## 🙌 Contributing
38+
We welcome contributions! See [Contributing Guide](docs/contributing.md) for more details.
39+

‎docs/architecture.md

Lines changed: 83 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,88 @@
1-
# Architecture Overview
1+
# Nim Blockchain Node Architecture
22

3-
## Layers
3+
## 🔍 Introduction
4+
This document outlines the architectural design of the Nim Blockchain Node, focusing on its modular structure, scalability, performance, and security considerations. It provides a detailed breakdown of the various components and their interactions within the blockchain system.
45

5-
- **Core Engine**
6-
- Consensus mechanisms (PoS/BFT)
7-
- Virtual Machine (transaction execution)
8-
- State management
6+
## 🧱 Architectural Layers
7+
The architecture is composed of distinct, modular layers designed explicitly for clarity, security, scalability, and ease of maintenance:
98

10-
- **Cryptography Layer**
11-
- Key management and secure storage
12-
- Signature verification
13-
- Zero-knowledge proofs (future integration)
9+
### 1. Core Engine Layer
1410

15-
- **Network Layer**
16-
- Peer-to-peer communication
17-
- Mempool management
18-
- Block propagation strategies
11+
#### **Consensus Module**
12+
- Implements a hybrid consensus mechanism (Proof-of-Stake combined with Byzantine Fault Tolerance).
13+
- Manages validator participation, quorum calculation, and block finality.
14+
- Ensures network integrity and secure block generation.
1915

20-
- **Storage Layer**
21-
- Blockchain data storage
22-
- State database
23-
- Indexing database
16+
#### **Virtual Machine (VM) Module**
17+
- Executes smart contracts and transactions with efficient gas metering.
18+
- Controls resource allocation to ensure predictable execution.
19+
20+
#### **State Management Module**
21+
- Tracks blockchain state transitions.
22+
- Ensures state consistency, supports concurrent updates, and manages state pruning.
23+
24+
### 2. Cryptography Layer
25+
26+
#### **Key Management Module**
27+
- Generates, stores, and manages cryptographic keys securely.
28+
- Supports multiple cryptographic curves for flexibility and compatibility.
29+
30+
#### **Signature Verification Module**
31+
- Validates digital signatures to ensure transaction authenticity and integrity.
32+
- Implements efficient batch verification methods.
33+
34+
#### **Zero-Knowledge Proof Module**
35+
- Enables privacy-preserving transactions through zero-knowledge proofs.
36+
- Supports verification mechanisms (zk-SNARKs, zk-STARKs) explicitly designed for blockchain privacy.
37+
38+
### 3. Network Layer
39+
40+
#### **P2P Communication Module**
41+
- Manages peer discovery, connections, and network stability.
42+
- Implements NAT traversal and optimized network protocols.
43+
44+
#### **Mempool Module**
45+
- Manages transaction storage and ordering before block inclusion.
46+
- Ensures efficient transaction processing and prevents duplication.
47+
48+
#### **Block Propagation Module**
49+
- Efficiently propagates blocks to the network.
50+
- Minimizes network latency and bandwidth usage.
51+
52+
### 4. Storage Layer
53+
54+
#### **Blockchain Database Module**
55+
- Stores blocks in an append-only structure optimized for immutable data.
56+
- Ensures fast retrieval and persistence of blockchain data.
57+
58+
#### **Index Database Module**
59+
- Provides fast indexing and retrieval of transaction-related data.
60+
- Enhances query performance for blockchain analytics.
61+
62+
#### **State Database Module**
63+
- Manages the blockchain state efficiently, supporting versioned storage.
64+
- Enables quick historical state access and efficient caching.
65+
66+
## 📐 Component Interactions
67+
- **Transactions** flow from network modules (P2P/Mempool) into the Core Engine for execution and validation.
68+
- **Consensus** validates blocks and determines block acceptance.
69+
- **Validated blocks** are stored securely in the Blockchain Database.
70+
- **Indexes** are updated for quick transaction retrieval, while the **State Database** maintains accurate blockchain state.
71+
72+
## 🔒 Security and Cryptographic Measures
73+
- Employs explicit cryptographic standards for key generation and signature verification.
74+
- Incorporates advanced cryptographic techniques (e.g., zero-knowledge proofs) to enhance privacy and security.
75+
- Clearly separates concerns to isolate security-critical modules.
76+
77+
## 🚧 Scalability and Performance
78+
- Designed explicitly for high-performance operation leveraging Nim’s concurrency and system-level capabilities.
79+
- Modular design allows horizontal scaling and future enhancements such as sharding.
80+
81+
## 🚀 Future Enhancements
82+
- Integration of robust cryptographic libraries for production-grade security.
83+
- Implementation of advanced network protocols (libp2p).
84+
- Enhanced error handling, logging, and analytics modules.
85+
86+
---
87+
88+
This architecture explicitly addresses critical blockchain requirements such as security, scalability, maintainability, and performance. Its clear modular design allows for robust future expansion and ongoing development.

‎docs/contributing.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Contributing to Nim Blockchain Node
2+
3+
## Introduction
4+
Thank you for your interest in contributing to the Nim Blockchain Node project! Your contributions will help enhance the blockchain node's security, scalability, and overall functionality. Below you'll find guidelines on how to effectively participate.
5+
6+
## 🚧 Contribution Guidelines
7+
8+
### 💡 Reporting Issues
9+
- Clearly describe the issue, including steps to reproduce, expected vs. actual behavior, and relevant screenshots or logs.
10+
- Label issues appropriately (bug, feature request, enhancement, etc.).
11+
12+
### 🛠️ Development Workflow
13+
- Fork the repository and create your feature branch:
14+
```sh
15+
git checkout -b feature/new-feature-name
16+
```
17+
- Ensure your code adheres to existing architecture, clearly documented practices, and coding standards.
18+
- Commit your changes clearly and explicitly:
19+
```sh
20+
git commit -m "Implement new consensus algorithm"
21+
```
22+
- Push your feature branch:
23+
```sh
24+
git push origin feature/new-feature-name
25+
```
26+
- Submit a pull request against the main branch and clearly outline your changes.
27+
28+
### 📐 Code Standards
29+
- Follow SOLID principles for clear modularity and maintainability.
30+
- Adhere to DRY and KISS principles to ensure clarity and simplicity.
31+
- Write clear and concise documentation and comments to facilitate peer review.
32+
33+
### 🧪 Testing
34+
- All new features or bug fixes must include relevant tests.
35+
- Run the full test suite before submitting a pull request:
36+
```sh
37+
nimble test
38+
```
39+
40+
## 🔒 Security
41+
- Report security vulnerabilities responsibly by directly contacting maintainers.
42+
- Follow cryptographic best practices and avoid custom cryptographic implementations without thorough review.
43+
44+
## 📝 Documentation
45+
- Update documentation in the `docs` folder with your contribution to reflect changes accurately.
46+
- Use clear, technical English, focusing on clarity, completeness, and readability.
47+
48+
## 🙌 Code of Conduct
49+
- Be respectful, collaborative, and inclusive.
50+
- Provide constructive feedback and be open to receiving feedback from others.
51+
52+
---
53+
54+
We look forward to your valuable contributions to enhancing the Nim Blockchain Node!

‎docs/getting_started.md

Lines changed: 50 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,56 @@
1-
# Getting Started
1+
# Getting Started with Nim Blockchain Node
22

3-
## Requirements
4-
- Nim (latest stable version)
5-
- Nimble package manager
6-
- Git
3+
## Introduction
4+
This guide provides clear instructions to quickly set up your development environment and start running your Nim Blockchain Node. Follow these straightforward steps to get your node operational.
75

8-
## Installation (Windows 11)
6+
## 🚀 Environment Setup
7+
Ensure you have the following prerequisites installed and configured:
98

10-
```powershell
11-
git clone <repository-url>
9+
### 1. Nim Programming Language
10+
Download and install Nim from the official [Nim website](https://nim-lang.org/install.html).
11+
12+
### 2. Git
13+
Install Git from the [official Git website](https://git-scm.com/).
14+
15+
### 3. Development Tools
16+
- Install Visual Studio Code or your preferred IDE for Nim development.
17+
- Install [Nim extension](https://marketplace.visualstudio.com/items?itemName=kosz78.nim) for syntax highlighting and Nim support.
18+
19+
## 🛠️ Project Setup
20+
Clone the repository and initialize dependencies:
21+
```shell
22+
git clone https://github.com/dkrizhanovskyi/nim-blockchain-node.git nim-blockchain-node
1223
cd nim-blockchain-node
1324
nimble install
25+
```
26+
27+
## ✅ Build and Run
28+
Build and run the blockchain node:
29+
```shell
1430
nimble build
31+
.\main.exe
32+
```
33+
34+
You should see a confirmation message indicating the node has successfully started:
35+
```shell
36+
🚀 Starting Nim Blockchain Node...
37+
✅ Block stored successfully.
38+
🎉 Node initialized successfully.
39+
```
40+
41+
## 🧪 Running Tests
42+
Execute the suite of unit and integration tests:
43+
```shell
44+
nimble test
45+
```
46+
Verify all tests pass to ensure system stability.
47+
48+
## 📖 Next Steps
49+
After successfully setting up and testing your node, consider:
50+
- Reviewing the detailed architecture documentation (`docs/architecture.md`).
51+
- Exploring further implementation details provided in `docs/overview.md`.
52+
53+
### 🛡️ Security Considerations
54+
Regularly review cryptographic practices and keep dependencies updated. Pay attention to cryptographic library versions and potential vulnerabilities.
55+
56+
For further information or to contribute, see [contributing.md](contributing.md).

‎docs/setup_guide.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Nim Blockchain Node Setup Guide
2+
3+
## Introduction
4+
This document outlines detailed, step-by-step instructions to set up your Nim Blockchain Node development environment on Windows 11. Follow these explicit steps to configure your system properly and efficiently.
5+
6+
## 🔧 Prerequisites
7+
8+
Before proceeding, ensure your system meets the following prerequisites:
9+
10+
- **Windows 11** (64-bit)
11+
- [Nim Programming Language](https://nim-lang.org/install.html) (version 2.2.2 or higher)
12+
- Git
13+
14+
## 📌 Installation Steps
15+
16+
### 1. Install Nim
17+
- Download and install the latest Nim version from [Nim Official Site](https://nim-lang.org/install_windows.html).
18+
- Confirm the installation in your terminal:
19+
```powershell
20+
nim --version
21+
```
22+
23+
### 2. Install Nimble (Nim's Package Manager)
24+
- Nimble comes bundled with Nim; ensure it's properly installed by running:
25+
```powershell
26+
nimble --version
27+
```
28+
29+
### 2. Clone the Repository
30+
```powershell
31+
git clone https://github.com/dkrizhanovskyi/nim-blockchain-node.git
32+
cd nim-blockchain-node
33+
```
34+
35+
### 3. Install Project Dependencies
36+
Run Nimble to install necessary dependencies:
37+
```powershell
38+
nimble install
39+
```
40+
41+
## ⚙️ Project Structure
42+
43+
```
44+
nim-blockchain-node/
45+
├── config/
46+
├── docs
47+
├── scripts
48+
├── src
49+
│ ├── core_engine
50+
│ ├── cryptography
51+
│ ├── network
52+
│ └── storage
53+
└── tests
54+
```
55+
56+
## 🚀 Building the Node
57+
To build the blockchain node:
58+
```powershell
59+
nimble build
60+
```
61+
62+
## 🧪 Running Tests
63+
Execute all unit and integration tests:
64+
```powershell
65+
nimble test
66+
```
67+
68+
## 🖥️ Running the Node
69+
Run the node after building:
70+
```powershell
71+
.\main.exe
72+
```
73+
74+
You should see the node initialization logs:
75+
```powershell
76+
🚀 Starting Nim Blockchain Node...
77+
✅ Block stored successfully.
78+
🎉 Node initialized successfully.
79+
```
80+
81+
## 🛡️ Security and Maintenance
82+
- Regularly update Nim and dependencies.
83+
- Monitor and integrate cryptographic library updates.
84+
- Follow best practices for security audits and code reviews.
85+
86+
---
87+
88+
Your Nim Blockchain Node is now successfully set up and ready for further development or deployment. Refer to [overview.md](overview.md) and [architecture.md](architecture.md) for deeper insights.

0 commit comments

Comments
 (0)