comment

Signed-off-by: turuslan <[email protected]>

Author: turuslan

src/blockchain/block_tree.hpp

@@ -153,11 +153,24 @@ namespace lean::blockchain {
      */
     [[nodiscard]] virtual BlockIndex lastFinalized() const = 0;
 
+    /**
+     * Get message for "/leanconsensus/req/status/1/ssz_snappy" protocol.
+     * Returns hash and slot for finalized and best blocks.
+     */
     virtual StatusMessage getStatusMessage() const = 0;
 
+    /**
+     * Get `SignedBlock` for "/leanconsensus/req/blocks_by_root/1/ssz_snappy"
+     * protocol.
+     */
     virtual outcome::result<std::optional<SignedBlock>> tryGetSignedBlock(
         const BlockHash block_hash) const = 0;
 
+    // TODO(turuslan): state transition function
+    /**
+     * Import pre-sorted batch of `SignedBlock`.
+     * May change best and finalized block.
+     */
     virtual void import(std::vector<SignedBlock> blocks) = 0;
   };
 

src/blockchain/impl/block_tree_impl.cpp

@@ -824,14 +824,14 @@ namespace lean::blockchain {
                 .state_root = header.state_root,
                 .body = std::move(body),
             },
-        // TODO: signature
+        // TODO(turuslan): signature
         .signature = {},
     };
   }
 
   void BlockTreeImpl::import(std::vector<SignedBlock> blocks) {
     for (auto &block : blocks) {
-      // TODO: signature
+      // TODO(turuslan): signature
       std::ignore = addBlock(block.message);
     }
   }

src/libp2p/peer/peer_id_from.hpp

@@ -12,6 +12,9 @@
 #include <qtils/bytes.hpp>
 
 namespace libp2p {
+  /**
+   * Convert secp256k1 public key to `PeerId`.
+   */
   inline PeerId peerIdFromSecp256k1(
       const crypto::secp256k1::PublicKey &public_key) {
     return libp2p::PeerId::fromPublicKey(

src/modules/networking/networking.cpp

@@ -26,7 +26,7 @@
 #include "utils/sample_peer.hpp"
 
 namespace lean::modules {
-  // TODO: gossip [from,seqno,signature,key]=None
+  // TODO(turuslan): gossip [from,seqno,signature,key]=None
 
   inline auto gossipTopic(std::string_view type) {
     return std::format("/leanconsensus/devnet0/{}/ssz_snappy", type);
@@ -421,7 +421,7 @@ namespace lean::modules {
                       });
   }
 
-  // TODO: detect finalized change
+  // TODO(turuslan): detect finalized change
   void NetworkingImpl::receiveBlock(std::optional<libp2p::PeerId> from_peer,
                                     SignedBlock &&block) {
     auto slot_hash = block.message.slotHash();

src/modules/networking/networking.hpp

@@ -32,6 +32,18 @@ namespace lean::modules {
   class StatusProtocol;
   class BlockRequestProtocol;
 
+  /**
+   * Network module.
+   *
+   * Sends produced blocks and signed votes.
+   * Syncs blocks from other peers.
+   * Receives votes from other peers.
+   *
+   * Protocols:
+   * - Status handshake protocol (best and finalized block info).
+   * - Block request protocol (`SignedBlock` by hash).
+   * - `SignedBlock` and `SignedVote` gossip protocol.
+   */
   class NetworkingImpl final : public Singleton<Networking>, public Networking {
     NetworkingImpl(NetworkingLoader &loader,
                    qtils::SharedRef<log::LoggingSystem> logging_system,

src/modules/production/production.cpp

@@ -68,7 +68,7 @@ namespace lean::modules {
       // Notify subscribers
       loader_.dispatch_block_produced(std::make_shared<const Block>(block));
 
-      // TODO: signature
+      // TODO(turuslan): signature
       loader_.dispatch_SendSignedBlock(
           std::make_shared<messages::SendSignedBlock>(
               SignedBlock{.message = block}));

src/modules/shared/macro.hpp

@@ -6,6 +6,37 @@
 
 #pragma once
 
+/**
+ * Macro to work with subscriptions and messages.
+ *
+ *   struct Message { ... };
+ *
+ *   struct IModule {
+ *     // Send `Message` to subscription
+ *     VIRTUAL_DISPATCH(Message);
+ *
+ *     // Received `Message` from subscription
+ *     VIRTUAL_ON_DISPATCH(Message);
+ *   };
+ *   struct Module : IModule {
+ *     ON_DISPATCH_SUBSCRIPTION(Message);
+ *
+ *     void start() {
+ *       ON_DISPATCH_SUBSCRIBE(Message);
+ *     }
+ *
+ *     DISPATCH_OVERRIDE(Message) {
+ *       log("dispatch Message");
+ *       dispatchDerive(subscription, message);
+ *     }
+ *
+ *     ON_DISPATCH_OVERRIDE(Message);
+ *   };
+ *   ON_DISPATCH_IMPL(Module, Message) {
+ *     log("received Message");
+ *   }
+ */
+
 #define VIRTUAL_DISPATCH(T) \
   virtual void dispatch_##T(std::shared_ptr<const messages::T> message) = 0
 #define DISPATCH_OVERRIDE(T) \

src/qtils/to_shared_ptr.hpp

@@ -9,6 +9,9 @@
 #include <memory>
 
 namespace qtils {
+  /**
+   * Make `shared_ptr` from object of type `T`.
+   */
   template <typename T>
   auto toSharedPtr(T &&t) {
     return std::make_shared<std::remove_cvref_t<T>>(std::forward<T>(t));

src/se/subscription_fwd.hpp

@@ -89,6 +89,9 @@ namespace lean {
     Derive,
   };
 
+  /**
+   * Get `EventType` auto-assigned to type `T`.
+   */
   class DeriveEventType {
    public:
     template <typename T>
@@ -105,6 +108,9 @@ namespace lean {
     }
   };
 
+  /**
+   * Call `notify` with `EventType` auto-assigned to type `T`.
+   */
   template <typename T>
   void dispatchDerive(auto &subscription, const std::shared_ptr<T> &message) {
     subscription.notify(DeriveEventType::get<std::remove_cvref_t<T>>(),

src/utils/__debug_env.hpp

@@ -3,7 +3,7 @@
 #include <cstdlib>
 #include <string>
 
-// TODO: config
+// TODO(turuslan): config
 inline size_t getPeerIndex() {
   static size_t i = [] {
     if (auto s = getenv("PeerIndex")) {