feat: Block Verification Feature

common/src/main/java/com/hedera/block/common/utils/MathUtilities.java

@@ -19,5 +19,15 @@ public static boolean isPowerOfTwo(final int toCheck) {
         return (0 < toCheck) && ((toCheck & (toCheck - 1)) == 0);
     }
 
+    /**
+     * This method checks if the given number is even.
+     *
+     * @param toCheck the number to check if it is even
+     * @return {@code true} if the given number is even
+     */
+    public static boolean isEven(final int toCheck) {
+        return (toCheck & 1) == 0;
+    }
+
     private MathUtilities() {}
 }

common/src/main/java/com/hedera/block/common/utils/Preconditions.java

@@ -15,6 +15,7 @@ public final class Preconditions {
             "The input number [%d] is required to be a whole number.";
     private static final String DEFAULT_REQUIRE_POWER_OF_TWO_MESSAGE =
             "The input number [%d] is required to be a power of two.";
+    private static final String DEFAULT_REQUIRE_IS_EVEN = "The input number [%d] is required to be even.";
 
     /**
      * This method asserts a given {@link String} is not blank.
@@ -267,5 +268,31 @@ public static int requirePowerOfTwo(final int toCheck, @NonNull final String err
         }
     }
 
+    /**
+     * This method asserts a given integer is even.
+     *
+     * @param toCheck the number to check if it is even
+     * @return the number to check if it is even
+     * @throws IllegalArgumentException if the input number to check is not even
+     */
+    public static int requireEven(final int toCheck, @NonNull final String errorMessage) {
+        if (!MathUtilities.isEven(toCheck)) {
+            throw new IllegalArgumentException(errorMessage.formatted(toCheck));
+        } else {
+            return toCheck;
+        }
+    }
+
+    /**
+     * This method asserts a given integer is even.
+     * Uses default error message DEFAULT_REQUIRE_IS_EVEN if the check fails.
+     *
+     * @param toCheck the number to check if it is even
+     * @return the number to check if it is even
+     */
+    public static int requireEven(final int toCheck) {
+        return requireEven(toCheck, DEFAULT_REQUIRE_IS_EVEN);
+    }
+
     private Preconditions() {}
 }

common/src/test/java/com/hedera/block/common/CommonsTestUtility.java

@@ -192,6 +192,40 @@ public static Stream<Arguments> negativeIntegers() {
                 Arguments.of(-10_000_000));
     }
 
+    /**
+     * Some even numbers.
+     */
+    public static Stream<Arguments> evenIntegers() {
+        return Stream.of(
+                Arguments.of(-4),
+                Arguments.of(-2),
+                Arguments.of(0),
+                Arguments.of(2),
+                Arguments.of(4),
+                Arguments.of(6),
+                Arguments.of(8),
+                Arguments.of(10),
+                Arguments.of(100),
+                Arguments.of(1_000));
+    }
+
+    /**
+     * Some odd numbers.
+     */
+    public static Stream<Arguments> oddIntegers() {
+        return Stream.of(
+                Arguments.of(-3),
+                Arguments.of(-1),
+                Arguments.of(1),
+                Arguments.of(3),
+                Arguments.of(5),
+                Arguments.of(7),
+                Arguments.of(9),
+                Arguments.of(11),
+                Arguments.of(101),
+                Arguments.of(1_001));
+    }
+
     /**
      * Provides valid test data for cases where the value to test is greater than or equal to the base value.
      *

common/src/test/java/com/hedera/block/common/utils/MathUtilitiesTest.java

@@ -34,4 +34,26 @@ void testIsPowerOfTwoFail(final int toTest) {
         final boolean actual = MathUtilities.isPowerOfTwo(toTest);
         assertThat(actual).isFalse();
     }
+
+    /**
+     * This test aims to verify that the {@link MathUtilities#isEven(int)}
+     * returns {@code true} if the input number is even.
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#evenIntegers")
+    void testIsEvenPass(final int toTest) {
+        final boolean actual = MathUtilities.isEven(toTest);
+        assertThat(actual).isTrue();
+    }
+
+    /**
+     * This test aims to verify that the {@link MathUtilities#isEven(int)}
+     * returns {@code false} if the input number is odd.
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#oddIntegers")
+    void testIsEvenFail(final int toTest) {
+        final boolean actual = MathUtilities.isEven(toTest);
+        assertThat(actual).isFalse();
+    }
 }

common/src/test/java/com/hedera/block/common/utils/PreconditionsTest.java

@@ -24,6 +24,7 @@ class PreconditionsTest {
             "The input number [%d] is required to be a whole number.";
     private static final String DEFAULT_REQUIRE_POWER_OF_TWO_MESSAGE =
             "The input number [%d] is required to be a power of two.";
+    private static final String DEFAULT_REQUIRE_IS_EVEN = "The input number [%d] is required to be even.";
 
     /**
      * This test aims to verify that the
@@ -327,6 +328,43 @@ void testRequireInRangeFail(final int toTest, final int lowerBoundary, final int
                 .withMessage(expectedTestMessage);
     }
 
+    /**
+     * This test aims to verify that the
+     * {@link Preconditions#requireEven(int)} will return the input 'toTest'
+     * parameter if the even check passes. Test includes overloads.
+     *
+     * @param toTest parameterized, the number to test
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#evenIntegers")
+    void testRequireEvenPass(final int toTest) {
+        final Consumer<Integer> asserts = actual -> assertThat(actual).isEven().isEqualTo(toTest);
+
+        final int actual = Preconditions.requireEven(toTest);
+        assertThat(actual).satisfies(asserts);
+
+        final int actualOverload = Preconditions.requireEven(toTest, "test error message");
+        assertThat(actualOverload).satisfies(asserts);
+    }
+
+    /** This test aims to verify that the {@link Preconditions#requireEven(int)} will throw an {@link IllegalArgumentException} if the even check fails. Test includes overloads.
+     *
+     * @param toTest parameterized, the number to test
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#oddIntegers")
+    void testRequireEvenFail(final int toTest) {
+        assertThatIllegalArgumentException()
+                .isThrownBy(() -> Preconditions.requireEven(toTest))
+                .withMessage(DEFAULT_REQUIRE_IS_EVEN.formatted(toTest));
+
+        final String testMessage = DEFAULT_REQUIRE_IS_EVEN.concat(" custom test error message");
+        final String expectedTestMessage = testMessage.formatted(toTest);
+        assertThatIllegalArgumentException()
+                .isThrownBy(() -> Preconditions.requireEven(toTest, testMessage))
+                .withMessage(expectedTestMessage);
+    }
+
     private static Stream<Arguments> validRequireInRangeValues() {
         return Stream.of(
                 Arguments.of(0, 0, 0),