From cec6f28c777e23dc7b57429cf8e1851074a7dc1f Mon Sep 17 00:00:00 2001 From: "Abdel @ StarkWare" Date: Wed, 4 Sep 2024 14:17:15 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20add=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/benchmarks.zig | 6 ++++++ src/lib.zig | 11 +++++++++++ src/miner/miner.zig | 6 ++++++ src/network/p2p.zig | 32 ++++++++++++++++++++++++++------ src/network/rpc.zig | 20 +++++++++++++++++++- src/node/node.zig | 9 +++++++++ src/types/block.zig | 0 src/types/lib.zig | 7 +++++++ src/wallet/wallet.zig | 7 +++++++ 9 files changed, 91 insertions(+), 7 deletions(-) create mode 100644 src/miner/miner.zig create mode 100644 src/types/block.zig create mode 100644 src/types/lib.zig diff --git a/src/benchmarks.zig b/src/benchmarks.zig index cb51bbe..9baaa82 100644 --- a/src/benchmarks.zig +++ b/src/benchmarks.zig @@ -1,3 +1,9 @@ +//! Benchmark module handles the benchmarking of btczee. +//! Currently, it is using the zul library to run the benchmarks. +//! The benchmarks can be run with: +//! ``` +//! zig build bench +//! ``` const std = @import("std"); const zul = @import("zul"); diff --git a/src/lib.zig b/src/lib.zig index 1fc416c..e6713dc 100644 --- a/src/lib.zig +++ b/src/lib.zig @@ -1,9 +1,20 @@ +//! btczee is a Bitcoin protocol implementation in Zig. +//! It can be used as a binary or a library. +//! Warning: This is still a work in progress and is not yet ready for production use. +//! +//! btczee can be run as: +//! - a wallet +//! - a miner +//! - a full node +//! +//! btczee is licensed under the MIT license. pub const config = @import("config/config.zig"); pub const mempool = @import("core/mempool.zig"); pub const p2p = @import("network/p2p.zig"); pub const rpc = @import("network/rpc.zig"); pub const storage = @import("storage/storage.zig"); pub const wallet = @import("wallet/wallet.zig"); +pub const miner = @import("miner/miner.zig"); test { @import("std").testing.refAllDeclsRecursive(@This()); diff --git a/src/miner/miner.zig b/src/miner/miner.zig new file mode 100644 index 0000000..1522f6c --- /dev/null +++ b/src/miner/miner.zig @@ -0,0 +1,6 @@ +//! Miner module handles the miner features of btczee. +//! It is responsible for mining blocks and validating transactions. +const std = @import("std"); + +/// Miner service. +const Miner = struct {}; diff --git a/src/network/p2p.zig b/src/network/p2p.zig index ce1d56f..a1f2651 100644 --- a/src/network/p2p.zig +++ b/src/network/p2p.zig @@ -1,3 +1,6 @@ +//! P2P module handles the peer-to-peer networking of btczee. +//! It is responsible for the connection to other nodes in the network. +//! It can receive and send messages to other nodes, based on the Bitcoin protocol. const std = @import("std"); const net = std.net; const Config = @import("../config/config.zig").Config; @@ -5,12 +8,21 @@ const Peer = @import("peer.zig").Peer; /// P2P network handler. pub const P2P = struct { + /// Allocator. allocator: std.mem.Allocator, + /// Configuration. config: *const Config, + /// List of peers. peers: std.ArrayList(*Peer), + /// Listener. listener: ?net.Server, - /// Initialize the P2P network + /// Initialize the P2P network handler. + /// # Arguments + /// - `allocator`: Allocator. + /// - `config`: Configuration. + /// # Returns + /// - `P2P`: P2P network handler. pub fn init(allocator: std.mem.Allocator, config: *const Config) !P2P { return P2P{ .allocator = allocator, @@ -20,7 +32,7 @@ pub const P2P = struct { }; } - /// Deinitialize the P2P network + /// Deinitialize the P2P network handler. pub fn deinit(self: *P2P) void { if (self.listener) |*l| l.deinit(); for (self.peers.items) |peer| { @@ -29,10 +41,11 @@ pub const P2P = struct { self.peers.deinit(); } - /// Start the P2P network + /// Start the P2P network handler. pub fn start(self: *P2P) !void { std.log.info("Starting P2P network on port {}", .{self.config.p2p_port}); + // TODO: Implement the P2P network handler // Initialize the listener // const address = try net.Address.parseIp4("0.0.0.0", self.config.p2p_port); // const stream = try net.tcpConnectToAddress(address); @@ -49,7 +62,8 @@ pub const P2P = struct { // try self.connectToSeedNodes(); } - /// Accept incoming connections + /// Accept incoming connections. + /// The P2P network handler will accept incoming connections and handle them in a separate thread. fn acceptConnections(self: *P2P) !void { while (true) { const connection = self.listener.?.accept() catch |err| { @@ -63,7 +77,10 @@ pub const P2P = struct { } } - /// Handle a new connection + /// Handle a new connection. + /// # Arguments + /// - `self`: P2P network handler. + /// - `connection`: Connection. fn handleConnection(self: *P2P, connection: net.Server.Connection) void { const peer = Peer.init(self.allocator, connection) catch |err| { std.log.err("Failed to initialize peer: {}", .{err}); @@ -71,12 +88,14 @@ pub const P2P = struct { return; }; + // Add the peer to the list of peers self.peers.append(peer) catch |err| { std.log.err("Failed to add peer: {}", .{err}); peer.deinit(); return; }; + // Start the peer in a new thread peer.start() catch |err| { std.log.err("Peer encountered an error: {}", .{err}); _ = self.peers.swapRemove(self.peers.items.len - 1); @@ -84,8 +103,9 @@ pub const P2P = struct { }; } - /// Connect to seed nodes + /// Connect to seed nodes. fn connectToSeedNodes(self: *P2P) !void { + // If no seed nodes are configured, do nothing if (self.config.seednode.len == 0) { return; } diff --git a/src/network/rpc.zig b/src/network/rpc.zig index 98de765..336c06d 100644 --- a/src/network/rpc.zig +++ b/src/network/rpc.zig @@ -1,3 +1,6 @@ +//! RPC module handles the RPC server of btczee. +//! It is responsible for the communication between the node and the clients. +//! See https://developer.bitcoin.org/reference/rpc/ const std = @import("std"); const Config = @import("../config/config.zig").Config; const Mempool = @import("../core/mempool.zig").Mempool; @@ -8,13 +11,24 @@ const httpz = @import("httpz"); /// /// The RPC server is responsible for handling the RPC requests from the clients. /// -/// See https://developer.bitcoin.org/reference/rpc/ pub const RPC = struct { + /// Allocator . allocator: std.mem.Allocator, + /// Configuration. config: *const Config, + /// Transaction pool. mempool: *Mempool, + /// Blockchain storage. storage: *Storage, + /// Initialize the RPC server. + /// # Arguments + /// - `allocator`: Allocator. + /// - `config`: Configuration. + /// - `mempool`: Transaction pool. + /// - `storage`: Blockchain storage. + /// # Returns + /// - `RPC`: RPC server. pub fn init( allocator: std.mem.Allocator, config: *const Config, @@ -31,10 +45,14 @@ pub const RPC = struct { return rpc; } + /// Deinitialize the RPC server. + /// Clean up the RPC server resources. pub fn deinit(self: *RPC) void { _ = self; } + /// Start the RPC server. + /// The RPC server will start a HTTP server and listen on the RPC port. pub fn start(self: *RPC) !void { std.log.info("Starting RPC server on port {}", .{self.config.rpc_port}); var handler = Handler{}; diff --git a/src/node/node.zig b/src/node/node.zig index fe8249e..17eb875 100644 --- a/src/node/node.zig +++ b/src/node/node.zig @@ -1,3 +1,5 @@ +//! Contains functionalities to run a Bitcoin full node on the Bitcoin network. +//! It enables the validation of transactions and blocks, the exchange of transactions and blocks with other peers. const std = @import("std"); const Config = @import("../config/config.zig").Config; const Mempool = @import("../core/mempool.zig").Mempool; @@ -5,6 +7,13 @@ const Storage = @import("../storage/storage.zig").Storage; const P2P = @import("../network/p2p.zig").P2P; const RPC = @import("../network/rpc.zig").RPC; +/// Start the node. +/// +/// # Arguments +/// - `mempool`: Transaction pool. +/// - `storage`: Blockchain storage. +/// - `p2p`: P2P network handler. +/// - `rpc`: RPC server. pub fn startNode(_: *Mempool, _: *Storage, p2p: *P2P, rpc: *RPC) !void { std.log.info("Starting btczee node...", .{}); diff --git a/src/types/block.zig b/src/types/block.zig new file mode 100644 index 0000000..e69de29 diff --git a/src/types/lib.zig b/src/types/lib.zig new file mode 100644 index 0000000..f3445cb --- /dev/null +++ b/src/types/lib.zig @@ -0,0 +1,7 @@ +//! Types module contains the definitions of the data structures used in the node. + +/// Block +pub const block = @import("block.zig"); + +/// Transaction +pub const transaction = @import("transaction.zig"); diff --git a/src/wallet/wallet.zig b/src/wallet/wallet.zig index e69de29..0997722 100644 --- a/src/wallet/wallet.zig +++ b/src/wallet/wallet.zig @@ -0,0 +1,7 @@ +//! Wallet module handles the wallet features of btczee. +//! It is responsible for creating, managing, and storing wallets. +//! It also handles the generation of wallet addresses and the storage of private keys. +const std = @import("std"); + +/// Wallet struct represents a wallet with its addresses and keys. +const Wallet = struct {};