hiero-ledger · derektriley · Oct 24, 2025 · Oct 24, 2025 · Oct 24, 2025 · Oct 24, 2025
@@ -494,6 +494,11 @@ enum StateIdentifier {
     */
     STATE_ID_REGISTERED_NODES = 56;
 
+    /**
+     * A state identifier for the highest node identifier allocated so far.
+     */
+    STATE_ID_HIGHEST_NODE_ID = 57;
+
     /**
      * A state identifier for the round receipts queue. Queue state.
      */
@@ -736,6 +741,11 @@ message SingletonUpdateChange {
          * Node payments SHALL be updated for every non-empty block.
          */
         com.hedera.hapi.node.state.token.NodePayments node_payments_value = 19;
+
+        /**
+         * A change to the highest node id singleton.
+         */
+        com.hedera.hapi.platform.state.NodeId node_id_value = 20;
     }
 }
 

@@ -622,6 +622,11 @@ message StateValue {
      */
     com.hedera.hapi.node.state.token.NodePayments TokenService_I_NODE_PAYMENTS = 55;
 
+    /**
+     * A state identifier for the next node Identifier. Singleton state.
+     */
+    com.hedera.hapi.platform.state.NodeId EntityIdService_I_NODE_ID = 57;
+
     /**
      * Metadata of the round receipts queue.
      */
@@ -806,6 +811,11 @@ enum SingletonType {
    */
   TokenService_I_NODE_PAYMENTS = 55;
 
+  /**
+   * A state identifier for the highest node identifier allocated so far. Singleton state.
+   */
+  EntityIdService_I_NODE_ID = 57;
+
   // Queue metadata
 
   /**

@@ -56,6 +56,7 @@
             case STATE_ID_ROSTER_STATE -> "RosterService.ROSTER_STATE";
             case STATE_ID_ROSTERS -> "RosterService.ROSTERS";
             case STATE_ID_ENTITY_COUNTS -> "EntityIdService.ENTITY_COUNTS";
+            case STATE_ID_HIGHEST_NODE_ID -> "EntityIdService.HIGHEST_NODE_ID";
             case STATE_ID_TRANSACTION_RECEIPTS -> "RecordCache.TRANSACTION_RECEIPTS";
             case STATE_ID_SCHEDULES_BY_EQUALITY -> "ScheduleService.SCHEDULES_BY_EQUALITY";
             case STATE_ID_SCHEDULES_BY_EXPIRY_SEC -> "ScheduleService.SCHEDULES_BY_EXPIRY_SEC";
@@ -117,6 +118,7 @@
             case HISTORY_PROOF_CONSTRUCTION_VALUE -> singletonUpdateChange.historyProofConstructionValueOrThrow();
             case CRS_STATE_VALUE -> singletonUpdateChange.crsStateValueOrThrow();
             case NODE_PAYMENTS_VALUE -> singletonUpdateChange.nodePaymentsValueOrThrow();
+            case NODE_ID_VALUE -> singletonUpdateChange.nodeIdValueOrThrow();
         };
     }
 

@@ -10,7 +10,7 @@
 import com.hedera.hapi.node.state.roster.RosterEntry;
 import com.hedera.node.app.hapi.utils.EntityType;
 import com.hedera.node.app.service.addressbook.ReadableNodeStore;
-import com.hedera.node.app.service.entityid.ReadableEntityCounters;
+import com.hedera.node.app.service.entityid.ReadableEntityIdStore;
 import com.swirlds.state.spi.ReadableKVState;
 import com.swirlds.state.spi.ReadableStates;
 import edu.umd.cs.findbugs.annotations.NonNull;
@@ -32,17 +32,17 @@ public class ReadableNodeStoreImpl implements ReadableNodeStore {
      */
     private final ReadableKVState<EntityNumber, Node> nodesState;
 
-    private final ReadableEntityCounters entityCounters;
+    protected final ReadableEntityIdStore entityIdStore;
 
     /**
      * Create a new {@link ReadableNodeStoreImpl} instance.
      *
      * @param states The state to use.
      */
     public ReadableNodeStoreImpl(
-            @NonNull final ReadableStates states, @NonNull final ReadableEntityCounters entityCounters) {
+            @NonNull final ReadableStates states, @NonNull final ReadableEntityIdStore entityIdStore) {
         requireNonNull(states);
-        this.entityCounters = requireNonNull(entityCounters);
+        this.entityIdStore = requireNonNull(entityIdStore);
         this.nodesState = states.get(NODES_STATE_ID);
     }
 
@@ -65,12 +65,12 @@ public Node get(final long nodeId) {
     }
 
     /**
-     * Returns the number of topics in the state.
+     * Returns the number of nodes in the state.
      *
-     * @return the number of topics in the state
+     * @return the number of nodes in the state
      */
     public long sizeOfState() {
-        return entityCounters.getCounterFor(EntityType.NODE);
+        return entityIdStore.getCounterFor(EntityType.NODE);
     }
 
     protected <T extends ReadableKVState<EntityNumber, Node>> T nodesState() {
@@ -79,9 +79,9 @@ protected <T extends ReadableKVState<EntityNumber, Node>> T nodesState() {
 
     @NonNull
     public List<EntityNumber> keys() {
-        final var size = sizeOfState();
         final var keys = new ArrayList<EntityNumber>();
-        for (int i = 0; i < size; i++) {
+        final long highestExclusive = entityIdStore.peekAtNextNodeId();
+        for (long i = 0; i < highestExclusive; i++) {
             final var key = new EntityNumber(i);
             final var node = nodesState.get(key);
             if (node != null) {

@@ -6,7 +6,7 @@
 import com.hedera.hapi.node.state.addressbook.Node;
 import com.hedera.hapi.node.state.common.EntityNumber;
 import com.hedera.node.app.hapi.utils.EntityType;
-import com.hedera.node.app.service.entityid.WritableEntityCounters;
+import com.hedera.node.app.service.entityid.WritableEntityIdStore;
 import com.swirlds.state.spi.WritableKVState;
 import com.swirlds.state.spi.WritableStates;
 import edu.umd.cs.findbugs.annotations.NonNull;
@@ -20,16 +20,15 @@
  * This class is not complete, it will be extended with other methods like remove, update etc.,
  */
 public class WritableNodeStore extends ReadableNodeStoreImpl {
-    private final WritableEntityCounters entityCounters;
+    private final WritableEntityIdStore writableEntityIdStore;
     /**
      * Create a new {@link WritableNodeStore} instance.
      *
      * @param states The state to use.
      */
-    public WritableNodeStore(
-            @NonNull final WritableStates states, @NonNull final WritableEntityCounters entityCounters) {
-        super(states, entityCounters);
-        this.entityCounters = entityCounters;
+    public WritableNodeStore(@NonNull final WritableStates states, @NonNull final WritableEntityIdStore entityIdStore) {
+        super(states, entityIdStore);
+        this.writableEntityIdStore = entityIdStore;
     }
 
     @Override
@@ -56,7 +55,16 @@ public void put(@NonNull final Node node) {
      */
     public void putAndIncrementCount(@NonNull final Node node) {
         put(node);
-        entityCounters.incrementEntityTypeCount(EntityType.NODE);
+        writableEntityIdStore.incrementEntityTypeCount(EntityType.NODE);
+    }
+
+    /**
+     * Removes the node with the given id from state and decrements the node entity count.
+     * @param nodeId the node id to remove
+     */
+    public void remove(final long nodeId) {
+        nodesState().remove(EntityNumber.newBuilder().number(nodeId).build());
+        writableEntityIdStore.decrementEntityTypeCounter(EntityType.NODE);
     }
 
     /**

@@ -9,7 +9,7 @@
 import static com.hedera.hapi.node.base.ResponseCodeEnum.MAX_NODES_CREATED;
 import static com.hedera.node.app.service.addressbook.AddressBookHelper.checkDABEnabled;
 import static com.hedera.node.app.service.addressbook.impl.validators.AddressBookValidator.validateX509Certificate;
-import static com.hedera.node.app.spi.workflows.HandleException.validateFalse;
+import static com.hedera.node.app.spi.workflows.HandleContext.DispatchMetadata.Type.SYSTEM_TXN_CREATION_ENTITY_NUM;
 import static com.hedera.node.app.spi.workflows.HandleException.validateTrue;
 import static com.hedera.node.app.spi.workflows.PreCheckException.validateFalsePreCheck;
 import static java.util.Objects.requireNonNull;
@@ -18,10 +18,12 @@
 import com.hedera.hapi.node.base.HederaFunctionality;
 import com.hedera.hapi.node.base.SubType;
 import com.hedera.hapi.node.state.addressbook.Node;
+import com.hedera.node.app.service.addressbook.ReadableNodeStore;
 import com.hedera.node.app.service.addressbook.impl.WritableAccountNodeRelStore;
 import com.hedera.node.app.service.addressbook.impl.WritableNodeStore;
 import com.hedera.node.app.service.addressbook.impl.records.NodeCreateStreamBuilder;
 import com.hedera.node.app.service.addressbook.impl.validators.AddressBookValidator;
+import com.hedera.node.app.service.entityid.NodeIdGenerator;
 import com.hedera.node.app.service.token.ReadableAccountStore;
 import com.hedera.node.app.spi.fees.FeeContext;
 import com.hedera.node.app.spi.fees.Fees;
@@ -90,8 +92,13 @@ public void handle(@NonNull final HandleContext handleContext) {
         final var accountNodeRelStore = storeFactory.writableStore(WritableAccountNodeRelStore.class);
         final var accountStore = storeFactory.readableStore(ReadableAccountStore.class);
         final var accountId = op.accountIdOrElse(AccountID.DEFAULT);
-
-        validateFalse(nodeStore.sizeOfState() >= nodeConfig.maxNumber(), MAX_NODES_CREATED);
+        final var maybeSystemTxnDispatchEntityNum =
+                handleContext.dispatchMetadata().getMetadata(SYSTEM_TXN_CREATION_ENTITY_NUM, Long.class);
+        final var maybeNodeIsInStateForSystemTxn =
+                isNodeInStateForSystemTxn(handleContext.dispatchMetadata(), handleContext.nodeIdGenerator(), nodeStore);
+        validateTrue(
+                maybeNodeIsInStateForSystemTxn || (nodeStore.sizeOfState() < nodeConfig.maxNumber()),
+                MAX_NODES_CREATED);
         addressBookValidator.validateAccount(
                 accountId, accountStore, accountNodeRelStore, handleContext.expiryValidator());
         addressBookValidator.validateDescription(op.description(), nodeConfig);
@@ -116,12 +123,24 @@ public void handle(@NonNull final HandleContext handleContext) {
             nodeBuilder.grpcProxyEndpoint(op.grpcProxyEndpoint());
         }
 
-        // Since nodes won't be removed from state, we can set the nodeId to the next available id
-        // in the state based on the size of the state.
-        final var node = nodeBuilder.nodeId(nodeStore.sizeOfState()).build();
+        long nextNodeId;
+        Node node;
+
+        // If a system-dispatched transplant transaction for nodes in override network (non-prod environments)
+        // attempts to create a node that already exists in the state (even if marked as deleted),
+        // neither the highest node ID nor the entity count should be incremented.
+        if (maybeNodeIsInStateForSystemTxn) {
+            // Assign node id using the one provided by the system dispatch metadata
+            nextNodeId = maybeSystemTxnDispatchEntityNum.get();
+            node = nodeBuilder.nodeId(nextNodeId).build();
+            nodeStore.put(node);
+        } else {
+            // Assign node id using a dedicated generator to avoid reuse
+            nextNodeId = handleContext.nodeIdGenerator().newNodeId();
+            node = nodeBuilder.nodeId(nextNodeId).build();
+            nodeStore.putAndIncrementCount(node);
+        }
 
-        nodeStore.putAndIncrementCount(node);
-        // add account id relation
         accountNodeRelStore.put(op.accountIdOrThrow(), node.nodeId());
 
         final var recordBuilder = handleContext.savepointStack().getBaseBuilder(NodeCreateStreamBuilder.class);
@@ -141,4 +160,25 @@ public Fees calculateFees(@NonNull final FeeContext feeContext) {
         calculator.addVerificationsPerTransaction(Math.max(0, feeContext.numTxnSignatures() - 1));
         return calculator.calculate();
     }
+
+    /**
+     * Determines if a system-dispatched node creation transaction targets a node ID
+     * that already exists in the current state.
+     *
+     * <p>If the dispatch metadata provides a node ID (as in system transactions), this method checks
+     * if that node ID is already present in the node store. If not, it uses the next node ID from the generator.
+     *
+     * @param metadata the dispatch metadata containing optional system transaction node ID
+     * @param nodeIdGenerator the generator for new node IDs
+     * @param nodeStore the store containing current node state
+     * @return {@code true} if the node ID (from metadata or generator) already exists in the state; {@code false} otherwise
+     */
+    private boolean isNodeInStateForSystemTxn(
+            final HandleContext.DispatchMetadata metadata,
+            final NodeIdGenerator nodeIdGenerator,
+            final ReadableNodeStore nodeStore) {
+        final var systemTxnCreationNum = metadata.getMetadataIfPresent(SYSTEM_TXN_CREATION_ENTITY_NUM, Long.class);
+        final var nextNodeId = systemTxnCreationNum != null ? systemTxnCreationNum : nodeIdGenerator.peekAtNewNodeId();
+        return nodeStore.get(nextNodeId) != null;
+    }
 }
@@ -37,7 +37,7 @@ void registersExpectedSchema() {
         verify(schemaRegistry, times(2)).register(schemaCaptor.capture());
         final var schemas = schemaCaptor.getAllValues();
         assertThat(schemas).hasSize(2);
-        assertThat(schemas.getFirst()).isInstanceOf(V053AddressBookSchema.class);
-        assertThat(schemas.getLast()).isInstanceOf(V068AddressBookSchema.class);
+        assertThat(schemas.get(0)).isInstanceOf(V053AddressBookSchema.class);
+        assertThat(schemas.get(1)).isInstanceOf(V068AddressBookSchema.class);
     }
 }
@@ -87,10 +87,10 @@ void keysWorks() {
                 .value(new EntityNumber(2), mock(Node.class))
                 .value(new EntityNumber(3), mock(Node.class))
                 .value(new EntityNumber(0), mock(Node.class));
+        givenEntityCounters(3);
         readableNodeState = stateBuilder.build();
         given(readableStates.<EntityNumber, Node>get(NODES_STATE_ID)).willReturn(readableNodeState);
         subject = new ReadableNodeStoreImpl(readableStates, writableEntityCounters);
-        writableEntityCounters.adjustEntityCount(EntityType.NODE, 3L);
         final var keys = subject.keys();
         assertFalse(keys.isEmpty());
         assertEquals(keys, List.of(new EntityNumber(0), new EntityNumber(1), new EntityNumber(2), new EntityNumber(3)));
@@ -107,8 +107,8 @@ void snapshotOfFutureRosterIncludesAllUndeletedDefinitions() {
                         EntityNumber.newBuilder().number(4).build(),
                         Node.newBuilder().nodeId(4).weight(40).deleted(true).build())
                 .build();
+        givenEntityCounters(3);
         given(readableStates.<EntityNumber, Node>get(anyInt())).willReturn(nodesState);
-        writableEntityCounters.adjustEntityCount(EntityType.NODE, 3L);
 
         subject = new ReadableNodeStoreImpl(readableStates, writableEntityCounters);
         final var result = subject.snapshotOfFutureRoster(nodeId ->