Docs

include/evmc/mocked_host.hpp

@@ -21,13 +21,16 @@ struct MockedAccount
     /// Extended value (by dirty flag) for account storage.
     struct storage_value
     {
+        /// The storage value.
         bytes32 value;
 
         /// True means this value has been modified already by the current transaction.
         bool dirty{false};
 
+        /// Default constructor.
         storage_value() noexcept = default;
 
+        /// Constructor.
         storage_value(const bytes32& _value, bool _dirty = false) noexcept  // NOLINT
           : value{_value}, dirty{_dirty}
         {}
@@ -61,10 +64,16 @@ class MockedHost : public Host
     /// LOG record.
     struct log_record
     {
+        /// The address of the account which created the log.
         address creator;
+
+        /// The data attached to the log.
         bytes data;
+
+        /// The log topics.
         std::vector<bytes32> topics;
 
+        /// Equal operator.
         bool operator==(const log_record& other) const noexcept
         {
             return creator == other.creator && data == other.data &&
@@ -76,9 +85,13 @@ class MockedHost : public Host
     /// SELFDESTRUCT record.
     struct selfdestuct_record
     {
+        /// The address of the account which has self-destructed.
         address selfdestructed;
+
+        /// The address of the beneficiary account.
         address beneficiary;
 
+        /// Equal operator.
         bool operator==(const selfdestuct_record& other) const noexcept
         {
             return selfdestructed == other.selfdestructed && beneficiary == other.beneficiary;
@@ -88,26 +101,44 @@ class MockedHost : public Host
     /// The set of all accounts in the Host, organized by their addresses.
     std::unordered_map<address, MockedAccount> accounts;
 
+    /// The EVMC transaction context to be returned by get_tx_context().
     evmc_tx_context tx_context = {};
 
-    bytes32 blockhash = {};
+    /// The block header hash value to be returned by get_block_hash().
+    bytes32 block_hash = {};
 
+    /// The call result to be returned by the call() method.
     evmc_result call_result = {};
 
+    /// The record of all block numbers for which get_block_hash() was called.
     std::vector<int64_t> recorded_blockhashes;
 
-    static constexpr auto max_recorded_account_accesses = 200;
+    /// The record of all account accesses.
     std::vector<address> recorded_account_accesses;
 
-    static constexpr auto max_recorded_calls = 100;
+    /// The maximum number of entries in recorded_account_accesses record.
+    /// This is arbitrary value useful in fuzzing when we don't want the record to explode.
+    static constexpr auto max_recorded_account_accesses = 200;
+
+    /// The record of all call messages requested in the call() method.
     std::vector<evmc_message> recorded_calls;
 
+    /// The maximum number of entries in recorded_calls record.
+    /// This is arbitrary value useful in fuzzing when we don't want the record to explode.
+    static constexpr auto max_recorded_calls = 100;
+
+    /// The record of all LOGs passed to the emit_log() method.
     std::vector<log_record> recorded_logs;
+
+    /// The record of all SELFDESTRUCTs from the selfdestruct() method.
     std::vector<selfdestuct_record> recorded_selfdestructs;
 
 protected:
+    /// The copy of call inputs for the recorded_calls record.
     std::vector<bytes> m_recorded_calls_inputs;
 
+    /// Record an account access.
+    /// @param addr  The address of the accessed account.
     void record_account_access(const address& addr)
     {
         if (recorded_account_accesses.empty())
@@ -117,12 +148,14 @@ class MockedHost : public Host
             recorded_account_accesses.emplace_back(addr);
     }
 
+    /// Returns true if an account exists (EVMC Host method).
     bool account_exists(const address& addr) noexcept override
     {
         record_account_access(addr);
         return accounts.count(addr) != 0;
     }
 
+    /// Get the account's storage value at the given key (EVMC Host method).
     bytes32 get_storage(const address& addr, const bytes32& key) noexcept override
     {
         record_account_access(addr);
@@ -137,6 +170,7 @@ class MockedHost : public Host
         return {};
     }
 
+    /// Set the account's storage value (EVMC Host method).
     evmc_storage_status set_storage(const address& addr,
                                     const bytes32& key,
                                     const bytes32& value) noexcept override
@@ -174,6 +208,7 @@ class MockedHost : public Host
         return status;
     }
 
+    /// Get the account's balance (EVMC Host method).
     uint256be get_balance(const address& addr) noexcept override
     {
         record_account_access(addr);
@@ -184,6 +219,7 @@ class MockedHost : public Host
         return it->second.balance;
     }
 
+    /// Get the account's code size (EVMC host method).
     size_t get_code_size(const address& addr) noexcept override
     {
         record_account_access(addr);
@@ -193,6 +229,7 @@ class MockedHost : public Host
         return it->second.code.size();
     }
 
+    /// Get the account's code hash (EVMC host method).
     bytes32 get_code_hash(const address& addr) noexcept override
     {
         record_account_access(addr);
@@ -202,6 +239,7 @@ class MockedHost : public Host
         return it->second.codehash;
     }
 
+    /// Copy the account's code to the given buffer (EVMC host method).
     size_t copy_code(const address& addr,
                      size_t code_offset,
                      uint8_t* buffer_data,
@@ -224,12 +262,14 @@ class MockedHost : public Host
         return n;
     }
 
+    /// Selfdestruct the account (EVMC host method).
     void selfdestruct(const address& addr, const address& beneficiary) noexcept override
     {
         record_account_access(addr);
         recorded_selfdestructs.push_back({addr, beneficiary});
     }
 
+    /// Call/create other contract (EVMC host method).
     result call(const evmc_message& msg) noexcept override
     {
         record_account_access(msg.destination);
@@ -254,14 +294,17 @@ class MockedHost : public Host
         return result{call_result};
     }
 
+    /// Get transaction context (EVMC host method).
     evmc_tx_context get_tx_context() noexcept override { return tx_context; }
 
+    /// Get the block header hash (EVMC host method).
     bytes32 get_block_hash(int64_t block_number) noexcept override
     {
         recorded_blockhashes.emplace_back(block_number);
-        return blockhash;
+        return block_hash;
     }
 
+    /// Emit LOG (EVMC host method).
     void emit_log(const address& addr,
                   const uint8_t* data,
                   size_t data_size,