📝 architecture diagram and description of components

zig-bitcoin · Sep 4, 2024 · 7b5f9f9 · 7b5f9f9
1 parent cec6f28
commit 7b5f9f9
Show file tree

Hide file tree

Showing 4 changed files with 207 additions and 53 deletions.
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -3,9 +3,7 @@
   "projectOwner": "zig-bitcoin",
   "repoType": "github",
   "repoHost": "https://github.com",
-  "files": [
-    "README.md"
-  ],
+  "files": ["README.md"],
   "imageSize": 100,
   "commit": true,
   "commitConvention": "gitmoji",
@@ -29,9 +27,7 @@
       "name": "lanaivina",
       "avatar_url": "https://avatars.githubusercontent.com/u/31368580?v=4",
       "profile": "https://github.com/lana-shanghai",
-      "contributions": [
-        "code"
-      ]
+      "contributions": ["code"]
     }
   ],
   "contributorsPerLine": 7,

diff --git a/README.md b/README.md
@@ -15,7 +15,51 @@
 
 ## Architecture
 
-You can find the architecture of the project in the [docs/architecture.md](./docs/architecture.md) file.
+You can find the architecture of the project and description of components in the [docs/architecture.md](./docs/architecture.md) file.
+
+```mermaid
+graph TD
+    Node[Node] --> Network
+    Node --> Mempool
+    Node --> Wallet
+    Node --> Storage
+    Node --> Miner
+
+    Network --> Mempool
+    Network --> Storage
+
+    Mempool --> Wallet
+    Mempool --> Storage
+
+    Wallet --> Storage
+
+    Miner --> Mempool
+    Miner --> Storage
+
+    subgraph "Core Components"
+        Node
+        Network
+        Mempool
+        Wallet
+        Storage
+        Miner
+    end
+
+    subgraph "Supporting Components"
+        Types
+        Primitives
+        Config
+    end
+
+    Node -.-> Types
+    Node -.-> Primitives
+    Node -.-> Config
+
+    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
+    classDef support fill:#bbf,stroke:#333,stroke-width:1px;
+    class Node,Network,Mempool,Wallet,Storage,Miner core;
+    class Types,Primitives,Config support;
+```
 
 ## Run
 
@@ -97,4 +141,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,27 +1,130 @@
-# Architecture
+# btczee Architecture
+
+This document describes the high-level architecture of btczee, a Bitcoin implementation in Zig. The project is structured into several key components, each responsible for specific functionality within the Bitcoin protocol.
 
 ## Components
 
-### P2P
+### 1. Node
+
+**Location**: `src/node/node.zig`
+
+The Node component is the central coordination point for the Bitcoin node. It initializes and manages other components, handles the node's lifecycle, and coordinates communication between different parts of the system.
+
+### 2. Network
+
+**Location**: `src/network/`
+
+The Network component handles all peer-to-peer communication within the Bitcoin network, as well as the RPC interface for interacting with the node. It's divided into several subcomponents:
+
+- `p2p.zig`: Manages the P2P network layer
+- `peer.zig`: Handles individual peer connections
+- `protocol.zig`: Implements the Bitcoin network protocol
+- `rpc.zig`: Provides an RPC interface for interacting with the node
+
+### 3. Mempool
+
+**Location**: `src/core/mempool.zig`
+
+The Mempool component manages the node's memory pool of unconfirmed transactions. It handles transaction validation, fee estimation, and transaction selection for block creation (if mining is enabled).
+
+### 4. Wallet
+
+**Location**: `src/wallet/wallet.zig`
+
+The Wallet component manages the user's Bitcoin wallet, including key management, transaction creation and signing, and balance tracking.
+
+### 5. Storage
+
+**Location**: `src/storage/storage.zig`
+
+The Storage component handles persistent storage of blockchain data, including blocks, transactions, and the UTXO set.
+
+### 6. Miner
+
+**Location**: `src/miner/miner.zig`
+
+The Miner component implements Bitcoin mining functionality, including block template creation and Proof-of-Work calculation.
+
+### 7. Types
+
+**Location**: `src/types/`
+
+The Types component defines core Bitcoin data structures:
+
+- `block.zig`: Defines the Block structure
+- `transaction.zig`: Defines the Transaction structure
+
+### 8. Primitives
+
+**Location**: `src/primitives/lib.zig`
+
+The Primitives component provides low-level Bitcoin primitives and utilities used throughout the codebase.
+
+### 9. Config
+
+**Location**: `src/config/config.zig`
+
+The Config component manages node configuration and settings.
+
+## Component Interactions
+
+The following diagram illustrates the high-level interactions between components:
 
-P2P is responsible for handling the peer-to-peer network.
+```mermaid
+graph TD
+    Node[Node] --> Network
+    Node --> Mempool
+    Node --> Wallet
+    Node --> Storage
+    Node --> Miner
 
-The main logic is implemented in `src/p2p.zig`.
+    Network --> Mempool
+    Network --> Storage
 
-### RPC
+    Mempool --> Wallet
+    Mempool --> Storage
 
-RPC is responsible for handling the RPC requests from the clients.
+    Wallet --> Storage
 
-The main logic is implemented in `src/rpc.zig`.
+    Miner --> Mempool
+    Miner --> Storage
 
-### Storage
+    subgraph "Core Components"
+        Node
+        Network
+        Mempool
+        Wallet
+        Storage
+        Miner
+    end
 
-Storage is responsible for handling the blockchain data.
+    subgraph "Supporting Components"
+        Types
+        Primitives
+        Config
+    end
 
-The main logic is implemented in `src/storage.zig`.
+    Node -.-> Types
+    Node -.-> Primitives
+    Node -.-> Config
 
-### Mempool
+    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
+    classDef support fill:#bbf,stroke:#333,stroke-width:1px;
+    class Node,Network,Mempool,Wallet,Storage,Miner core;
+    class Types,Primitives,Config support;
+```
 
-Mempool is responsible for handling the mempool of pending transactions.
+## Interaction Descriptions
 
-The main logic is implemented in `src/mempool.zig`.
+1. **Node and Network**: The Node initializes the Network component, which handles all incoming and outgoing network communication. The Network component notifies the Node of new blocks and transactions.
+2. **Node and Mempool**: The Node uses the Mempool to validate and store unconfirmed transactions. The Mempool notifies the Node of changes in the transaction pool.
+3. **Node and Wallet**: The Node interacts with the Wallet for transaction creation and signing. The Wallet notifies the Node of new transactions that need to be broadcast.
+4. **Node and Storage**: The Node uses the Storage component to persist and retrieve blockchain data, including blocks and the UTXO set.
+5. **Node and Miner**: The Node coordinates with the Miner for block creation and Proof-of-Work calculation.
+6. **Network and Mempool**: The Network component passes new transactions to the Mempool for validation and storage.
+7. **Network and Storage**: The Network component retrieves block and transaction data from Storage for peer requests.
+8. **Mempool and Wallet**: The Mempool interacts with the Wallet to validate transactions and check for double-spends.
+   Mempool and Storage: The Mempool uses Storage to persist the mempool state and check against the UTXO set.
+9. **Wallet and Storage**: The Wallet uses Storage to persist wallet data and retrieve historical transaction information.
+10. **Miner and Mempool**: The Miner requests transactions from the Mempool for block creation.
+11. **Miner and Storage**: The Miner interacts with Storage to retrieve necessary data for block creation and to store newly mined blocks.
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -1,46 +1,57 @@
 ## Roadmap [in progress]
 
-### Cryptographic primitives 
-* [ ] SHA-256
-* [ ] RIPEMD160
-* [ ] ECDSA
+### Cryptographic primitives
+
+- [ ] SHA-256
+- [ ] RIPEMD160
+- [ ] ECDSA
 
 ### Primitives (data structures)
-* [ ] Transaction structure
-* [ ] Block structure
-* [ ] Merkle tree
 
-### Networking 
-* [ ] Peer-to-peer network implementation
-* [ ] Message handling and serialization
+- [ ] Transaction structure
+- [ ] Block structure
+- [ ] Merkle tree
+
+### Networking
+
+- [ ] Peer-to-peer network implementation
+- [ ] Message handling and serialization
 
-### Transaction 
-* [ ] Transaction checks: CoinBase, duplicate inputs, overflows
-* [ ] Transaction validation
+### Transaction
 
-### Chain 
-* [ ] Block validation
-* [ ] Chain management
-* [ ] UTXO set
+- [ ] Transaction checks: CoinBase, duplicate inputs, overflows
+- [ ] Transaction validation
+
+### Chain
+
+- [ ] Block validation
+- [ ] Chain management
+- [ ] UTXO set
 
 ### Consensus
-* [ ] Parameters: genesis hash, BIP block numbers, difficulty
-* [ ] Proof of work algorithm
-* [ ] Difficulty adjustment
 
-### Wallet 
-* [ ] Address generation
-* [ ] Transaction creation and signing 
+- [ ] Parameters: genesis hash, BIP block numbers, difficulty
+- [ ] Proof of work algorithm
+- [ ] Difficulty adjustment
+
+### Wallet
+
+- [ ] Address generation
+- [ ] Transaction creation and signing
+
+### Miner
+
+- [ ] Block creation
+- [ ] Mining algorithm and rewards
+
+### Bitcoin Script
+
+- [ ] Bitcoin Script interpreter
 
-### Miner 
-* [ ] Block creation
-* [ ] Mining algorithm and rewards
+### Mempool
 
-### Bitcoin Script 
-* [ ] Bitcoin Script interpreter
+- [ ] Transaction pool management
 
-### Mempool 
-* [ ] Transaction pool management
+### RPC
 
-### RPC 
-* [ ] API calls to the node 
+- [ ] API calls to the node