refactor: enhance consistency testing tool

platform-sdk/platform-apps/tests/ConsistencyTestingTool/build.gradle.kts

@@ -1,4 +1,19 @@
-// SPDX-License-Identifier: Apache-2.0
+/*
+ * Copyright (C) 2025 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 plugins { id("org.hiero.gradle.module.application") }
 
 application.mainClass = "com.swirlds.demo.consistency.ConsistencyTestingToolMain"
@@ -7,6 +22,7 @@ mainModuleInfo { annotationProcessor("com.swirlds.config.processor") }
 
 testModuleInfo {
     requires("com.swirlds.common.test.fixtures")
+    requires("org.assertj.core")
     requires("org.junit.jupiter.api")
     requires("org.mockito")
 }

platform-sdk/platform-apps/tests/ConsistencyTestingTool/src/main/java/com/swirlds/demo/consistency/ConsistencyTestingToolMain.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2023-2024 Hedera Hashgraph, LLC
+ * Copyright (C) 2023-2025 Hedera Hashgraph, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

platform-sdk/platform-apps/tests/ConsistencyTestingTool/src/main/java/com/swirlds/demo/consistency/ConsistencyTestingToolState.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2023-2024 Hedera Hashgraph, LLC
+ * Copyright (C) 2023-2025 Hedera Hashgraph, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

platform-sdk/platform-apps/tests/ConsistencyTestingTool/src/test/java/com/swirlds/demo/consistency/ConsistencyTestingToolStateTest.java

@@ -0,0 +1,287 @@
+/*
+ * Copyright (C) 2025 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.swirlds.demo.consistency;
+
+import static com.swirlds.platform.test.fixtures.state.FakeMerkleStateLifecycles.FAKE_MERKLE_STATE_LIFECYCLES;
+import static org.assertj.core.api.AssertionsForInterfaceTypes.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.hedera.hapi.platform.event.StateSignatureTransaction;
+import com.hedera.pbj.runtime.io.buffer.Bytes;
+import com.swirlds.common.config.StateCommonConfig;
+import com.swirlds.common.context.PlatformContext;
+import com.swirlds.common.platform.NodeId;
+import com.swirlds.config.api.Configuration;
+import com.swirlds.platform.components.transaction.system.ScopedSystemTransaction;
+import com.swirlds.platform.state.PlatformStateModifier;
+import com.swirlds.platform.system.BasicSoftwareVersion;
+import com.swirlds.platform.system.InitTrigger;
+import com.swirlds.platform.system.Platform;
+import com.swirlds.platform.system.Round;
+import com.swirlds.platform.system.SoftwareVersion;
+import com.swirlds.platform.system.events.ConsensusEvent;
+import com.swirlds.platform.system.transaction.ConsensusTransaction;
+import com.swirlds.platform.system.transaction.Transaction;
+import com.swirlds.platform.system.transaction.TransactionWrapper;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Random;
+import java.util.function.BiConsumer;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+public class ConsistencyTestingToolStateTest {
+
+    private static ConsistencyTestingToolState state;
+    private ConsistencyTestingToolMain main;
+    private Random random;
+    private PlatformStateModifier platformStateModifier;
+    private Platform platform;
+    private PlatformContext platformContext;
+    private Round round;
+    private ConsensusEvent event;
+    private List<ScopedSystemTransaction<StateSignatureTransaction>> consumedTransactions;
+    private Consumer<ScopedSystemTransaction<StateSignatureTransaction>> consumer;
+    private Transaction consensusTransaction;
+    private StateSignatureTransaction stateSignatureTransaction;
+    private InitTrigger initTrigger;
+    private SoftwareVersion softwareVersion;
+    private Configuration configuration;
+    private ConsistencyTestingToolConfig consistencyTestingToolConfig;
+    private StateCommonConfig stateCommonConfig;
+
+    @BeforeAll
+    static void initState() {
+        state = new ConsistencyTestingToolState(FAKE_MERKLE_STATE_LIFECYCLES, mock(Function.class));
+        FAKE_MERKLE_STATE_LIFECYCLES.initStates(state);
+    }
+
+    @BeforeEach
+    void setUp() {
+        platform = mock(Platform.class);
+        initTrigger = InitTrigger.GENESIS;
+        softwareVersion = new BasicSoftwareVersion(1);
+        platformContext = mock(PlatformContext.class);
+        configuration = mock(Configuration.class);
+        consistencyTestingToolConfig = mock(ConsistencyTestingToolConfig.class);
+        stateCommonConfig = mock(StateCommonConfig.class);
+
+        when(platform.getSelfId()).thenReturn(NodeId.of(1L));
+        when(platform.getContext()).thenReturn(platformContext);
+        when(platformContext.getConfiguration()).thenReturn(configuration);
+        when(configuration.getConfigData(ConsistencyTestingToolConfig.class)).thenReturn(consistencyTestingToolConfig);
+        when(configuration.getConfigData(StateCommonConfig.class)).thenReturn(stateCommonConfig);
+        when(consistencyTestingToolConfig.freezeAfterGenesis()).thenReturn(Duration.ZERO);
+        when(stateCommonConfig.savedStateDirectory()).thenReturn(Path.of("consistency-test"));
+        when(consistencyTestingToolConfig.logfileDirectory()).thenReturn("consistency-test");
+
+        state.init(platform, initTrigger, softwareVersion);
+
+        main = mock(ConsistencyTestingToolMain.class);
+        random = new Random();
+        platformStateModifier = mock(PlatformStateModifier.class);
+        round = mock(Round.class);
+        event = mock(ConsensusEvent.class);
+
+        consumedTransactions = new ArrayList<>();
+        consumer = systemTransaction -> consumedTransactions.add(systemTransaction);
+        consensusTransaction = mock(TransactionWrapper.class);
+
+        final byte[] signature = new byte[384];
+        random.nextBytes(signature);
+        final byte[] hash = new byte[48];
+        random.nextBytes(hash);
+        stateSignatureTransaction = StateSignatureTransaction.newBuilder()
+                .signature(Bytes.wrap(signature))
+                .hash(Bytes.wrap(hash))
+                .round(round.getRoundNum())
+                .build();
+    }
+
+    @Test
+    void handleConsensusRoundWithApplicationTransactionEmptySystemTransactionList() {
+        final var bytes = Bytes.wrap(new byte[] {1, 1, 1, 1, 1, 1, 1, 1});
+        when(consensusTransaction.getApplicationTransaction()).thenReturn(bytes);
+
+        doAnswer(invocation -> {
+                    BiConsumer<ConsensusEvent, Transaction> consumer = invocation.getArgument(0);
+                    consumer.accept(event, consensusTransaction);
+                    return null;
+                })
+                .when(round)
+                .forEachEventTransaction(any());
+
+        state.handleConsensusRound(round, platformStateModifier, consumer);
+
+        assertThat(consumedTransactions).isEmpty();
+    }
+
+    @Test
+    void handleConsensusRoundWithSystemTransaction() {
+        final var stateSignatureTransactionBytes =
+                StateSignatureTransaction.PROTOBUF.toBytes(stateSignatureTransaction);
+        when(main.encodeSystemTransaction(stateSignatureTransaction)).thenReturn(stateSignatureTransactionBytes);
+        when(consensusTransaction.getApplicationTransaction()).thenReturn(stateSignatureTransactionBytes);
+
+        doAnswer(invocation -> {
+                    BiConsumer<ConsensusEvent, Transaction> consumer = invocation.getArgument(0);
+                    consumer.accept(event, consensusTransaction);
+                    return null;
+                })
+                .when(round)
+                .forEachEventTransaction(any());
+
+        state.handleConsensusRound(round, platformStateModifier, consumer);
+
+        assertThat(consumedTransactions).hasSize(1);
+    }
+
+    @Test
+    void handleConsensusRoundWithMultipleSystemTransactions() {
+        // Given
+        final var secondConsensusTransaction = mock(TransactionWrapper.class);
+        final var thirdConsensusTransaction = mock(TransactionWrapper.class);
+        when(round.iterator()).thenReturn(Collections.singletonList(event).iterator());
+        when(event.getConsensusTimestamp()).thenReturn(Instant.now());
+        when(event.consensusTransactionIterator())
+                .thenReturn(List.of(
+                                (ConsensusTransaction) consensusTransaction,
+                                secondConsensusTransaction,
+                                thirdConsensusTransaction)
+                        .iterator());
+
+        final var stateSignatureTransactionBytes =
+                StateSignatureTransaction.PROTOBUF.toBytes(stateSignatureTransaction);
+        when(main.encodeSystemTransaction(stateSignatureTransaction)).thenReturn(stateSignatureTransactionBytes);
+        when(consensusTransaction.getApplicationTransaction()).thenReturn(stateSignatureTransactionBytes);
+        when(secondConsensusTransaction.getApplicationTransaction()).thenReturn(stateSignatureTransactionBytes);
+        when(thirdConsensusTransaction.getApplicationTransaction()).thenReturn(stateSignatureTransactionBytes);
+
+        doAnswer(invocation -> {
+                    BiConsumer<ConsensusEvent, Transaction> consumer = invocation.getArgument(0);
+                    consumer.accept(event, consensusTransaction);
+                    consumer.accept(event, secondConsensusTransaction);
+                    consumer.accept(event, thirdConsensusTransaction);
+                    return null;
+                })
+                .when(round)
+                .forEachEventTransaction(any());
+
+        // When
+        state.handleConsensusRound(round, platformStateModifier, consumer);
+
+        assertThat(consumedTransactions).hasSize(3);
+    }
+
+    @Test
+    void handleConsensusRoundWithDeprecatedSystemTransaction() {
+        when(consensusTransaction.getApplicationTransaction()).thenReturn(Bytes.EMPTY);
+        when(consensusTransaction.isSystem()).thenReturn(true);
+
+        doAnswer(invocation -> {
+                    BiConsumer<ConsensusEvent, Transaction> consumer = invocation.getArgument(0);
+                    consumer.accept(event, consensusTransaction);
+                    return null;
+                })
+                .when(round)
+                .forEachEventTransaction(any());
+
+        state.handleConsensusRound(round, platformStateModifier, consumer);
+
+        assertThat(consumedTransactions).isEmpty();
+    }
+
+    @Test
+    void preHandleEventWithMultipleSystemTransactions() {
+        when(round.iterator()).thenReturn(Collections.singletonList(event).iterator());
+        final var secondConsensusTransaction = mock(TransactionWrapper.class);
+        final var thirdConsensusTransaction = mock(TransactionWrapper.class);
+        when(event.transactionIterator())
+                .thenReturn(List.of(consensusTransaction, secondConsensusTransaction, thirdConsensusTransaction)
+                        .iterator());
+        final var stateSignatureTransactionBytes =
+                StateSignatureTransaction.PROTOBUF.toBytes(stateSignatureTransaction);
+        when(consensusTransaction.getApplicationTransaction()).thenReturn(stateSignatureTransactionBytes);
+        when(secondConsensusTransaction.getApplicationTransaction()).thenReturn(stateSignatureTransactionBytes);
+        when(thirdConsensusTransaction.getApplicationTransaction()).thenReturn(stateSignatureTransactionBytes);
+
+        doAnswer(invocation -> {
+                    Consumer<Transaction> consumer = invocation.getArgument(0);
+                    consumer.accept(consensusTransaction);
+                    consumer.accept(secondConsensusTransaction);
+                    consumer.accept(thirdConsensusTransaction);
+                    return null;
+                })
+                .when(event)
+                .forEachTransaction(any());
+
+        state.preHandle(event, consumer);
+
+        assertThat(consumedTransactions).hasSize(3);
+    }
+
+    @Test
+    void preHandleEventWithSystemTransaction() {
+        when(round.iterator()).thenReturn(Collections.singletonList(event).iterator());
+        when(event.transactionIterator())
+                .thenReturn(Collections.singletonList(consensusTransaction).iterator());
+        final var emptyStateSignatureBytes = StateSignatureTransaction.PROTOBUF.toBytes(stateSignatureTransaction);
+        when(consensusTransaction.getApplicationTransaction()).thenReturn(emptyStateSignatureBytes);
+
+        doAnswer(invocation -> {
+                    Consumer<Transaction> consumer = invocation.getArgument(0);
+                    consumer.accept(consensusTransaction);
+                    return null;
+                })
+                .when(event)
+                .forEachTransaction(any());
+
+        state.preHandle(event, consumer);
+
+        assertThat(consumedTransactions).hasSize(1);
+    }
+
+    @Test
+    void preHandleEventWithDeprecatedSystemTransaction() {
+        when(round.iterator()).thenReturn(Collections.singletonList(event).iterator());
+        when(event.transactionIterator())
+                .thenReturn(Collections.singletonList(consensusTransaction).iterator());
+        when(consensusTransaction.isSystem()).thenReturn(true);
+
+        doAnswer(invocation -> {
+                    Consumer<Transaction> consumer = invocation.getArgument(0);
+                    consumer.accept(consensusTransaction);
+                    return null;
+                })
+                .when(event)
+                .forEachTransaction(any());
+
+        state.preHandle(event, consumer);
+
+        assertThat(consumedTransactions).isEmpty();
+    }
+}

platform-sdk/swirlds-platform-core/src/main/java/com/swirlds/platform/system/SwirldMain.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2016-2024 Hedera Hashgraph, LLC
+ * Copyright (C) 2016-2025 Hedera Hashgraph, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

platform-sdk/swirlds-platform-core/src/main/java/com/swirlds/platform/system/SwirldState.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2016-2024 Hedera Hashgraph, LLC
+ * Copyright (C) 2016-2025 Hedera Hashgraph, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -71,7 +71,7 @@ default void init(
      * <strong>This method is always invoked on an immutable state.</strong>
      *
      * @param event the event to perform pre-handling on
-     * @param stateSignatureTransaction a consumer that accepts a list of {@link ScopedSystemTransaction}s that
+     * @param stateSignatureTransaction a consumer that accepts a {@link ScopedSystemTransaction} that
      *                                   will be used for callbacks
      */
     default void preHandle(
@@ -83,7 +83,7 @@ default void preHandle(
      *
      * @param round         the round to apply
      * @param platformState the platform state
-     * @param stateSignatureTransaction a consumer that accepts a list of {@link ScopedSystemTransaction}s that
+     * @param stateSignatureTransaction a consumer that accepts a {@link ScopedSystemTransaction} that
      *                                   will be used for callbacks
      */
     void handleConsensusRound(