Deprecate verify(), use verify_against_boundary()

include/ethash/ethash.h

@@ -6,10 +6,30 @@
 #pragma once
 
 #include <ethash/hash_types.h>
-
 #include <stdbool.h>
 #include <stdint.h>
 
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wreserved-id-macro"
+
+#ifndef __has_cpp_attribute
+#define __has_cpp_attribute(X) 0
+#endif
+
+#ifndef __has_attribute
+#define __has_attribute(X) 0
+#endif
+
+#pragma clang diagnostic pop
+
+#if defined(__cplusplus) && __has_cpp_attribute(deprecated) < __cplusplus
+#define DEPRECATED(MSG) [[deprecated(MSG)]]
+#elif __has_attribute(deprecated)
+#define DEPRECATED(MSG) __attribute__((deprecated(MSG)))
+#else
+#define DEPRECATED(MSG)
+#endif
+
 #ifdef __cplusplus
 #define NOEXCEPT noexcept
 #else
@@ -116,16 +136,32 @@ struct ethash_result ethash_hash(const struct ethash_epoch_context* context,
     const union ethash_hash256* header_hash, uint64_t nonce) NOEXCEPT;
 
 /**
- * Verify Ethash validity of a header hash.
+ * Verify Ethash validity of a header hash against given boundary.
+ *
+ * This checks if final hash header_hash is within difficulty boundary header_hash <= boundary,
+ * where boundary = 2^256 / difficulty.
+ * It also checks if the Ethash result produced out of (header_hash, nonce) matches the provided
+ * mix_hash.
  *
  * @return  Error code: ::ETHASH_SUCCESS if valid, ::ETHASH_INVALID_FINAL_HASH if the final hash is
  *          not within provided boundary, ::ETHASH_INVALID_MIX_HASH if the provided mix hash
  *          mismatches the computed one.
  */
-ethash_errc ethash_verify(const struct ethash_epoch_context* context,
+ethash_errc ethash_verify_against_boundary(const struct ethash_epoch_context* context,
     const union ethash_hash256* header_hash, const union ethash_hash256* mix_hash, uint64_t nonce,
     const union ethash_hash256* boundary) NOEXCEPT;
 
+/**
+ * @deprecated Use ethash_verify_against_boundary().
+ */
+DEPRECATED("use ethash_verify_against_boundary()")
+static inline ethash_errc ethash_verify(const struct ethash_epoch_context* context,
+    const union ethash_hash256* header_hash, const union ethash_hash256* mix_hash, uint64_t nonce,
+    const union ethash_hash256* boundary) NOEXCEPT
+{
+    return ethash_verify_against_boundary(context, header_hash, mix_hash, nonce, boundary);
+}
+
 /**
  * Verify only the final hash. This can be performed quickly without accessing Ethash context.
  *

include/ethash/ethash.hpp

@@ -146,10 +146,18 @@ inline std::error_code verify_final_hash(const hash256& header_hash, const hash2
     return ethash_verify_final_hash(&header_hash, &mix_hash, nonce, &boundary);
 }
 
-inline std::error_code verify(const epoch_context& context, const hash256& header_hash,
-    const hash256& mix_hash, uint64_t nonce, const hash256& boundary) noexcept
+inline std::error_code verify_against_boundary(const epoch_context& context,
+    const hash256& header_hash, const hash256& mix_hash, uint64_t nonce,
+    const hash256& boundary) noexcept
 {
-    return ethash_verify(&context, &header_hash, &mix_hash, nonce, &boundary);
+    return ethash_verify_against_boundary(&context, &header_hash, &mix_hash, nonce, &boundary);
+}
+
+[[deprecated("use verify_against_boundary()")]] inline std::error_code verify(
+    const epoch_context& context, const hash256& header_hash, const hash256& mix_hash,
+    uint64_t nonce, const hash256& boundary) noexcept
+{
+    return ethash_verify_against_boundary(&context, &header_hash, &mix_hash, nonce, &boundary);
 }
 
 search_result search_light(const epoch_context& context, const hash256& header_hash,

lib/ethash/ethash.cpp

@@ -423,7 +423,7 @@ ethash_errc ethash_verify_final_hash(const hash256* header_hash, const hash256*
                                                                 ETHASH_INVALID_FINAL_HASH;
 }
 
-ethash_errc ethash_verify(const epoch_context* context, const hash256* header_hash,
+ethash_errc ethash_verify_against_boundary(const epoch_context* context, const hash256* header_hash,
     const hash256* mix_hash, uint64_t nonce, const hash256* boundary) noexcept
 {
     const hash512 seed = hash_seed(*header_hash, nonce);

test/benchmarks/ethash_benchmarks.cpp

@@ -3,7 +3,6 @@
 // Licensed under the Apache License, Version 2.0.
 
 #include "../unittests/helpers.hpp"
-
 #include <benchmark/benchmark.h>
 #include <ethash/ethash-internal.hpp>
 #include <ethash/global_context.hpp>
@@ -141,13 +140,13 @@ static void verify(benchmark::State& state)
     const ethash::hash256 mix_hash =
         to_hash256("94cd4e844619ee20989578276a0a9046877d569d37ba076bf2e8e34f76189dea");
     const uint64_t nonce = 0x4617a20003ba3f25;
-    const ethash::hash256 boundry =
+    const ethash::hash256 boundary =
         to_hash256("0000000000001a5c000000000000000000000000000000000000000000000000");
 
     static const auto ctx = ethash::create_epoch_context(ethash::get_epoch_number(block_number));
 
     for (auto _ : state)
-        ethash::verify(*ctx, header_hash, mix_hash, nonce, boundry);
+        ethash::verify_against_boundary(*ctx, header_hash, mix_hash, nonce, boundary);
 }
 BENCHMARK(verify);
 
@@ -160,13 +159,13 @@ static void verify_mt(benchmark::State& state)
     const ethash::hash256 mix_hash =
         to_hash256("94cd4e844619ee20989578276a0a9046877d569d37ba076bf2e8e34f76189dea");
     const uint64_t nonce = 0x4617a20003ba3f25;
-    const ethash::hash256 boundry =
+    const ethash::hash256 boundary =
         to_hash256("0000000000001a5c000000000000000000000000000000000000000000000000");
 
     static const auto ctx = ethash::create_epoch_context(ethash::get_epoch_number(block_number));
 
     for (auto _ : state)
-        ethash::verify(*ctx, header_hash, mix_hash, nonce, boundry);
+        ethash::verify_against_boundary(*ctx, header_hash, mix_hash, nonce, boundary);
 }
 BENCHMARK(verify_mt)->Threads(1)->Threads(2)->Threads(4)->Threads(8);
 
@@ -179,7 +178,7 @@ static void verify_managed(benchmark::State& state)
     const ethash::hash256 mix_hash =
         to_hash256("94cd4e844619ee20989578276a0a9046877d569d37ba076bf2e8e34f76189dea");
     const uint64_t nonce = 0x4617a20003ba3f25;
-    const ethash::hash256 boundry =
+    const ethash::hash256 boundary =
         to_hash256("0000000000001a5c000000000000000000000000000000000000000000000000");
 
     const int epoch_number = ethash::get_epoch_number(block_number);
@@ -190,7 +189,7 @@ static void verify_managed(benchmark::State& state)
     for (auto _ : state)
     {
         auto& context = ethash::get_global_epoch_context(epoch_number);
-        ethash::verify(context, header_hash, mix_hash, nonce, boundry);
+        ethash::verify_against_boundary(context, header_hash, mix_hash, nonce, boundary);
     }
 }
 BENCHMARK(verify_managed)->Threads(1)->Threads(2)->Threads(4)->Threads(8);

test/unittests/test_ethash.cpp

@@ -582,13 +582,13 @@ TEST(ethash, verify_hash_light)
         ec = verify_final_hash(header_hash, mix_hash, nonce, dec(boundary));
         EXPECT_EQ(ec, ETHASH_INVALID_FINAL_HASH);
 
-        ec = verify(*context, header_hash, mix_hash, nonce, boundary);
+        ec = verify_against_boundary(*context, header_hash, mix_hash, nonce, boundary);
         EXPECT_EQ(ec, ETHASH_SUCCESS);
 
-        ec = verify(*context, header_hash, mix_hash, nonce, dec(boundary));
+        ec = verify_against_boundary(*context, header_hash, mix_hash, nonce, dec(boundary));
         EXPECT_EQ(ec, ETHASH_INVALID_FINAL_HASH);
 
-        ec = verify(*context, header_hash, mix_hash, nonce, inc(boundary));
+        ec = verify_against_boundary(*context, header_hash, mix_hash, nonce, inc(boundary));
         EXPECT_EQ(ec, ETHASH_SUCCESS);
 
         const bool within_significant_boundary = r.final_hash.bytes[0] == 0;
@@ -597,12 +597,12 @@ TEST(ethash, verify_hash_light)
             ec = verify_final_hash(header_hash, mix_hash, nonce + 1, boundary);
             EXPECT_EQ(ec, ETHASH_INVALID_FINAL_HASH) << t.final_hash_hex;
 
-            ec = verify(*context, header_hash, mix_hash, nonce + 1, boundary);
+            ec = verify_against_boundary(*context, header_hash, mix_hash, nonce + 1, boundary);
             EXPECT_EQ(ec, ETHASH_INVALID_FINAL_HASH);
         }
         else
         {
-            ec = verify(*context, header_hash, mix_hash, nonce + 1, boundary);
+            ec = verify_against_boundary(*context, header_hash, mix_hash, nonce + 1, boundary);
             EXPECT_EQ(ec, ETHASH_INVALID_MIX_HASH);
         }
     }
@@ -651,7 +651,8 @@ TEST(ethash, verify_final_hash_only)
         to_hash256("000000ffffffffffffffffffffffffffffffffffffffffffffffffffffffffff");
 
     EXPECT_EQ(verify_final_hash(header_hash, mix_hash, nonce, boundary), ETHASH_SUCCESS);
-    EXPECT_EQ(verify(context, header_hash, mix_hash, nonce, boundary), ETHASH_INVALID_MIX_HASH);
+    EXPECT_EQ(verify_against_boundary(context, header_hash, mix_hash, nonce, boundary),
+        ETHASH_INVALID_MIX_HASH);
 }
 
 TEST(ethash, verify_boundary)
@@ -675,16 +676,17 @@ TEST(ethash, verify_boundary)
     EXPECT_EQ(r.final_hash, boundary_eq);
     EXPECT_EQ(to_hex(r.final_hash), to_hex(boundary_eq));
 
-    EXPECT_EQ(verify(context, example_header_hash, r.mix_hash, nonce, boundary_eq), ETHASH_SUCCESS);
-    EXPECT_EQ(verify(context, example_header_hash, r.mix_hash, nonce, boundary_gt), ETHASH_SUCCESS);
-    EXPECT_EQ(verify(context, example_header_hash, r.mix_hash, nonce, boundary_lt),
+    EXPECT_EQ(verify_against_boundary(context, example_header_hash, r.mix_hash, nonce, boundary_eq),
+        ETHASH_SUCCESS);
+    EXPECT_EQ(verify_against_boundary(context, example_header_hash, r.mix_hash, nonce, boundary_gt),
+        ETHASH_SUCCESS);
+    EXPECT_EQ(verify_against_boundary(context, example_header_hash, r.mix_hash, nonce, boundary_lt),
         ETHASH_INVALID_FINAL_HASH);
 }
 
 TEST(ethash_multithreaded, small_dataset)
 {
-    // This test creates an extremely small dataset for full search to discover
-    // sync issues between threads.
+    // This test creates a tiny dataset for full search to discover sync issues between threads.
 
     constexpr size_t num_treads = 8;
     constexpr int num_dataset_items = 501;

test/unittests/test_global_context.cpp

@@ -75,7 +75,8 @@ TEST(managed_multithreaded, verify_all)
                 const hash256 boundary = final_hash;
                 const int epoch_number = get_epoch_number(t.block_number);
                 auto& context = get_global_epoch_context(epoch_number);
-                const auto ec = verify(context, header_hash, mix_hash, nonce, boundary);
+                const auto ec =
+                    verify_against_boundary(context, header_hash, mix_hash, nonce, boundary);
                 EXPECT_EQ(ec, ETHASH_SUCCESS);
             }
         });
@@ -98,7 +99,7 @@ TEST(managed_multithreaded, verify_parallel)
             const hash256 boundary = final_hash;
             const int epoch_number = get_epoch_number(t.block_number);
             auto& context = get_global_epoch_context(epoch_number);
-            return verify(context, header_hash, mix_hash, nonce, boundary);
+            return verify_against_boundary(context, header_hash, mix_hash, nonce, boundary);
         }));
     }