Merge pull request #9 from AppLayerLabs/development

Sync infos for bdk-cpp

Author: Jean-Lessa

.gitbook/assets/contract-folder.png

@@ -6,33 +6,42 @@ description: How the functional elements of AppLayer interact with each other.
 
 This chapter aims to explain in technical detail how the BDK is implemented, as well as its submodules and how everything comes together to deliver a blazing fast blockchain.
 
-The first few subchapters paint a more holistic view of the BDK, as most components are pretty straight-forward to understand, and developers are expected to use the [Doxygen](https://doxygen.nl) documentation as a reference to further understand how the project works. The later subchapters show some components that are particularly denser and/or complex enough that they warrant their own separated explanations.
+The first few subchapters paint a more holistic view of the BDK, as most components are pretty straight-forward to understand. Developers are expected to use the [Doxygen](https://doxygen.nl) documentation as a reference to further understand how the project works. The later subchapters show some components that are particularly denser and/or complex enough that they warrant their own separated explanations.
 
 Looking at a higher level of abstraction, the original C++ implementation of the BDK is structured like this:
 
-* The `src/bins` folder contains the source files for the project's main executables - the blockchain executable itself, contract ABI generator and other testing-related executables are all coded here in their respective subfolders
+* The `src/bins` folder contains the source files for the project's main executables - the blockchain executable itself, contract ABI generator, network simulator, faucet API and other testing-related executables are all coded here in their respective subfolders
+* The `src/bytes` folder contains code related to the `bytes` class, a container that deals with raw bytes - specifically the `bytes::join()` function and the `bytes::View` class, both used extensively across the project
 * The `src/contract` folder contains everything related to the logic of smart contracts - from ABI parsing to custom variable types and template contracts
 * The `src/core` folder contains the heart of the BDK - the main components of the blockchain and what makes it tick
 * The `src/libs` folder contains third-party libraries not inherently tied to the project but used throughout development
 * The `src/net` folder contains everything related to networking, communication between nodes and support for protocols such as gRPC, HTTP, P2P, JSON-RPC, etc.
 * The `src/utils` folder contains several commonly-used functions, structures, classes and overall logic to support the functioning of the BDK as a whole
 
+There is also a `tests` folder that contains several unit tests for each of the components described above.
+
 ## Source tree
 
 For the more visually inclined, here is a source tree (headers only) containing all of the files inside the `src` folder (except `src/bins` as it only contains source files), their respective subfolders and which components are declared in them. Each component is further explained through the following subchapters of this documentation. For more technical details (e.g. API references for developers), please refer to the [Doxygen](https://www.doxygen.nl) documentation on the project's own repository.
 
 ```
 src
+├── bytes
+│   ├── initializer.h (bytes::Initializer, bytes::SizedInitializer)
+│   ├── join.h (bytes::join())
+│   ├── range.h (bytes::Range, bytes::DataRange, bytes::BorrowedDataRange)
+│   └── view.h (bytes::View, bytes::Span)
 ├── contract (Contracts)
 │   ├── abi.h (ABI - encoders, decoders, helper structs, etc.)
+│   ├── calltracer.h (trace namespace, Call struct, CallTracer class)
 │   ├── contractfactory.h (ContractFactory)
 │   ├── contract.h (ContractGlobals, ContractLocals, BaseContract)
 │   ├── contracthost.h (ContractHost)
 │   ├── contractmanager.h (ContractManager)
 │   ├── contractstack.h (ContractStack)
 │   ├── customcontracts.h (for declaring custom contracts)
 │   ├── dynamiccontract.h (DynamicContract)
-│   ├── event.h (Event, EventManager)
+│   ├── event.h (Event)
 │   ├── templates (folder for contract templates)
 │   │   ├── dexv2 (subfolder for the DEXV2 contract components)
 │   │   │   ├── dexv2factory.h (DEXV2Factory)
@@ -44,71 +53,83 @@ src
 │   │   ├── erc20wrapper.h (ERC20Wrapper)
 │   │   ├── erc721.h (ERC721)
 │   │   ├── erc721test.h (ERC721Test, used solely for testing purposes)
+│   │   ├── erc721uristorage.h (ERC721URIStorage, converted from OpenZeppelin)
 │   │   ├── nativewrapper.h (NativeWrapper)
+│   │   ├── ownable.h (Ownable, converted from OpenZeppelin)
+│   │   ├── pebble.h (Pebble)
 │   │   ├── randomnesstest.h (RandomnessTest)
 │   │   ├── simplecontract.h (SimpleContract)
+│   │   ├── snailtracer.h, snailtraceroptimized.h (SnailTracer and SnailTracerOptimized, converted from the original EVM impl)
 │   │   ├── testThrowVars.h (TestThrowVars, used solely for testing purposes)
-│   │   └── throwtestA.h, throwtestB.h, throwtestC.h (for testing CM nested calls)
+│   │   └── throwtestA.h, throwtestB.h, throwtestC.h (for testing nested contract calls)
 │   └── variables (Safe Variables for use within Dynamic Contracts)
 │       ├── reentrancyguard.h (ReentrancyGuard)
 │       ├── safeaddress.h (SafeAddress)
 │       ├── safearray.h (SafeArray)
 │       ├── safebase.h (SafeBase - used as base for all other types)
 │       ├── safebool.h (SafeBool)
-│       ├── safeint.h (SafeInt)
+│       ├── safebytes.h (SafeBytes)
+│       ├── safeint.h (SafeInt and respective aliases)
 │       ├── safestring.h (SafeString)
 │       ├── safetuple.h (SafeTuple)
-│       ├── safeuint.h (SafeUint)
+│       ├── safeuint.h (SafeUint and respective aliases)
 │       ├── safeunorderedmap.h (SafeUnorderedMap)
 │       └── safevector.h (SafeVector)
 ├── core (Core components)
 │   ├── blockchain.h (Blockchain, Syncer)
 │   ├── consensus.h (Consensus)
 │   ├── dump.h (Dumpable, DumpManager, DumpWorker)
-│   ├── rdpos.h (Validator, rdPoS, rdPoSWorker)
-│   ├── state.h (State)
+│   ├── rdpos.h (Validator, rdPoS)
+│   ├── state.h (BlockValidationStatus, State)
 │   └── storage.h (Storage)
-├── libs (Third-party libs)
+├── libs (Third-party libraries)
 │   ├── BS_thread_pool_light.hpp (https://github.com/bshoshany/thread-pool)
 │   ├── catch2/catch_amalgamated.hpp (https://github.com/catchorg/Catch2)
-│   └── json.hpp (https://github.com/nlohmann/json)
+│   ├── json.hpp (https://github.com/nlohmann/json)
+│   ├── wyhash.h (https://github.com/wangyi-fudan/wyhash)
+│   └── zpp_bits.h (https://github.com/eyalz800/zpp_bits)
 ├── net (Networking)
-│   ├── grpcclient.h (gRPCClient)
-│   ├── grpcserver.h (gRPCServer)
 │   ├── http (HTTP part of networking)
 │   │   ├── httpclient.h (HTTPClient)
 │   │   ├── httplistener.h (HTTPListener)
 │   │   ├── httpparser.h (parser functions for HTTP requests)
 │   │   ├── httpserver.h (HTTPServer)
 │   │   ├── httpsession.h (HTTPQueue, HTTPSession)
 │   │   └── jsonrpc (Namespace for handling JSONRPC data)
-│   │       ├── decoding.h (functions for decoding JSONRPC data)
-│   │       ├── encoding.h (functions for encoding JSONRPC data)
-│   │       └── methods.h (declarations for JSONRPC methods)
+│   │       ├── blocktag.h (BlockTag, BlockTagOrNumber)
+│   │       ├── call.h (call() - a function that processes a JSON RPC call)
+│   │       ├── error.h (Error - for abstracting JSON RPC errors)
+│   │       ├── methods.h (contains all implemented JSON RPC methods)
+│   │       ├── parser.h (Parser and helper tempate functions)
+│   │       └── variadicparser.h (VariadicParser and helper template functions)
 │   └── p2p (P2P part of networking)
-│       ├── client.h (ClientFactory)
+│       ├── broadcaster.h (Broadcaster)
 │       ├── discovery.h (DiscoveryWorker - worker thread for ManagerDiscovery)
 │       ├── encoding.h (collection of enums, structs, classes, encoders and decoders used in P2P communications)
 │       ├── managerbase.h (ManagerBase - used as base for ManagerDiscovery and ManagerNormal)
 │       ├── managerdiscovery.h (ManagerDiscovery)
 │       ├── managernormal.h (ManagerNormal)
 │       ├── nodeconns.h (NodeConns)
-│       ├── server.h (ServerListener, Server)
 │       └── session.h (Session)
-└── utils (Base components)
-    ├── contractreflectioninterface.h (ContractReflectionInterface - interface for registering contracts)
+└── utils (Utility components)
+    ├── clargs.h (definitions for helper functions, enums and structs that deal with command-line argument parsing)
+    ├── contractreflectioninterface.h (ContractReflectionInterface - interface for registering Dynamic Contracts)
     ├── db.h (DBPrefix, DBServer, DBEntry, DBBatch, DB)
     ├── dynamicexception.h (DynamicException - custom exception class)
     ├── ecdsa.h (PrivKey, Pubkey, UPubkey, Secp256k1)
+    ├── evmcconv.h (EVMCConv - namespace for EVMC-related data conversion functions)
     ├── finalizedblock.h (FinalizedBlock)
     ├── hex.h (Hex)
+    ├── intconv.h (IntConv - namespace for signed integer aliases and data conversion functions)
     ├── jsonabi.h (JsonAbi - namespace for writing contract ABIs to JSON format)
-    ├── logger.h (LogType, Log, LogInfo, Logger)
+    ├── logger.h (LogType, Log, LogInfo, Logger, LogicalLocationProvider)
     ├── merkle.h (Merkle)
     ├── options.h (Options singleton - generated by CMake through a .in file)
     ├── randomgen.h (RandomGen)
     ├── safehash.h (SafeHash, FNVHash)
-    ├── strings.h (FixedBytes, Hash, Functor, Signature, Address)
+    ├── strconv.h (StrConv - namespace for string-related data conversion and manipulation functions)
+    ├── strings.h (FixedBytes and its derivatives - Hash, Functor, Signature, Address, StorageKey)
     ├── tx.h (TxBlock, TxValidator)
-    └── utils.h (definitions for Bytes/Account structs, uint/ethCallInfo types, Networks, and the Utils namespace)
+    ├── uintconv.h (UintConv - namespace for unsigned integer aliases and data conversion functions)
+    └── utils.h (Utils namespace and other misc struct and enum definitions)
 ```

.gitbook/assets/core-folder.png

@@ -12,69 +12,42 @@ For example, a call with a variable that starts with the value "10", then five c
 
 ## ContractStack class overview
 
-Here's an overview of the `ContractStack` class definition and functionalities:
+Here's an overview of the `ContractStack` class definition and functionalities (comments removed for easier reading, check the `contract/contractstack.h` file for more details):
 
 ```c++
 class ContractStack {
   private:
-    std::unordered_map<Address, Bytes, SafeHash> code_;
-    std::unordered_map<Address, uint256_t, SafeHash> balance_;
-    std::unordered_map<Address, uint64_t, SafeHash> nonce_;
-    std::unordered_map<StorageKey, Hash, SafeHash> storage_;
+    boost::unordered_flat_map<Address, Bytes, SafeHash> code_;
+    boost::unordered_flat_map<Address, uint256_t, SafeHash> balance_;
+    boost::unordered_flat_map<Address, uint64_t, SafeHash> nonce_;
+    boost::unordered_flat_map<StorageKey, Hash, SafeHash> storage_;
     std::vector<Event> events_;
-    std::vector<Address> contracts_; // Contracts that have been created during the execution of the call, we need to revert them if the call reverts.
+    std::vector<std::pair<Address,BaseContract*>> contracts_;
     std::vector<std::reference_wrapper<SafeBase>> usedVars_;
 
   public:
-    ContractStack() = default;
-    ~ContractStack() = default;
-
-    inline void registerCode(const Address& addr, const Bytes& code)  {
-      if (!this->code_.contains(addr)) {
-        this->code_[addr] = code;
-      }
-    }
-
-    inline void registerBalance(const Address& addr, const uint256_t& balance) {
-      if (!this->balance_.contains(addr)) {
-        this->balance_[addr] = balance;
-      }
-    }
-
-    inline void registerNonce(const Address& addr, const uint64_t& nonce) {
-      if (!this->nonce_.contains(addr)) {
-        this->nonce_[addr] = nonce;
-      }
-    }
-
-    inline void registerStorageChange(const StorageKey& key, const Hash& value) {
-      if (!this->storage_.contains(key)) {
-        this->storage_[key] = value;
-      }
-    }
-
-    inline void registerEvent(Event&& event) {
-      this->events_.emplace_back(std::move(event));
-    }
-
-    inline void registerContract(const Address& addr) {
-      this->contracts_.push_back(addr);
-    }
-
-    inline void registerVariableUse(SafeBase& var) {
-      this->usedVars_.emplace_back(var);
-    }
-
-    /// Getters
-    inline const std::unordered_map<Address, Bytes, SafeHash>& getCode() const { return this->code_; }
-    inline const std::unordered_map<Address, uint256_t, SafeHash>& getBalance() const { return this->balance_; }
-    inline const std::unordered_map<Address, uint64_t, SafeHash>& getNonce() const { return this->nonce_; }
-    inline const std::unordered_map<StorageKey, Hash, SafeHash>& getStorage() const { return this->storage_; }
+    inline void registerCode(const Address& addr, const Bytes& code) { this->code_.try_emplace(addr, code); }
+
+    inline void registerBalance(const Address& addr, const uint256_t& balance) { this->balance_.try_emplace(addr, balance); }
+
+    inline void registerNonce(const Address& addr, const uint64_t& nonce) { this->nonce_.try_emplace(addr, nonce); }
+
+    inline void registerStorageChange(const StorageKey& key, const Hash& value) { this->storage_.try_emplace(key, value); }
+
+    inline void registerEvent(Event event) { this->events_.emplace_back(std::move(event)); }
+
+    inline void registerContract(const Address& addr, BaseContract* contract) { this->contracts_.emplace_back(addr, contract); }
+
+    inline void registerVariableUse(SafeBase& var) { this->usedVars_.emplace_back(var); }
+
+    inline const boost::unordered_flat_map<Address, Bytes, SafeHash>& getCode() const { return this->code_; }
+    inline const boost::unordered_flat_map<Address, uint256_t, SafeHash>& getBalance() const { return this->balance_; }
+    inline const boost::unordered_flat_map<Address, uint64_t, SafeHash>& getNonce() const { return this->nonce_; }
+    inline const boost::unordered_flat_map<StorageKey, Hash, SafeHash>& getStorage() const { return this->storage_; }
     inline std::vector<Event>& getEvents() { return this->events_; }
-    inline const std::vector<Address>& getContracts() const { return this->contracts_; }
+    inline const std::vector<std::pair<Address,BaseContract*>>& getContracts() const { return this->contracts_; }
     inline const std::vector<std::reference_wrapper<SafeBase>>& getUsedVars() const { return this->usedVars_; }
 };
 ```
 
-The existence of only *one* instance of `ContractStack` per `ContractHost`, and its integration within the RAII framework of `ContractHost`, guarantees that state values are meticulously committed or reverted upon the completion or rollback of transactions. This robust design prevents state spill-over between different contract executions, fortifying transaction isolation and integrity across the blockchain network - even in the dynamic and mutable landscape of blockchain transactions, the integrity and consistency of state changes are meticulously maintained, safeguarding against unintended consequences and errors during contract execution.
-
+The existence of only *one* instance of `ContractStack` per `ContractHost`, as well as its integration within the RAII framework of `ContractHost`, guarantees that state values are meticulously committed or reverted upon the completion or rollback of transactions. This robust design prevents state spill-over between different contract executions, fortifying transaction isolation and integrity across the blockchain network - even in the dynamic and mutable landscape of blockchain transactions, the integrity and consistency of state changes are meticulously maintained, safeguarding against unintended consequences and errors during contract execution.