[Feature] SolidityNode supports conditional shutdown

[liuyifei001]

Background

A SolidityNode is designed to provide query services for blocks and events that are finalized. Its core value lies in stability, determinism, and suitability for production workloads. Since it does not need to perform signature verification for transactions and blocks, its synchronization speed is over 30% faster than a FullNode.

However, compared to a FullNode, SolidityNode lacks certain functionalities, which introduces inconvenience for users. For example, it currently does not support conditional shutdown, which is critical for scenarios such as verifying the global state at a specific block height.

Rationale

Why should this feature exist?

• To enable the SolidityNode to stop automatically based on specified conditions, allowing users to query and verify the state at a target block.

What are the use cases?

• Synchronizing a specific block range more quickly than FullNode
• Performing state consistency verification across nodes

Specification

The following configuration allows customizing the automatic shutdown conditions. Only one of the three options can be enabled at a time:

node.shutdown = {
#  BlockTime  = "54 59 08 * * ?"  # Trigger shutdown when block header time matches
#  BlockHeight = 33350800         # Trigger shutdown when block height matches
#  BlockCount = 12                # Trigger shutdown after syncing a number of blocks since startup
}

Design Context

To verify global execution consistency across heterogeneous architectures (e.g., x86 vs.  ARM) during full sync, the blockchain is partitioned into segments based on snapshots for parallel processing. Data continuity is validated by ensuring the Final State of a preceding segment perfectly matches the Initial State of the subsequent one. While SolidityNodes accelerate this synchronization, their current inability to halt at a specific block height necessitates further enhancements.

Implementation Approach

We introduce these three condition checks from TronNetDelegate into the org.tron.program.SolidityNode class.

Additionally: Force p2pdisable = true, ensure that:

• Core block processing logic remains unchanged
• Shutdown conditions can still be triggered correctly

No modification is required for the existing configuration format.

Test Specification

Set different conditions to verify whether the node shutdowns as expected.

Scope of Impact

This change only affects the Solidity Node.

Implementation

Do you have ideas regarding the implementation of this feature?

Yes

Are you willing to implement this feature?

Yes

[halibobo1205]

That’s a very good suggestion. Looking forward to this feature being supported in the SolidityNode. Previously, in the FullNode, the session flush was triggered after the session build rather than on session commit. This design caused the FullNode’s conditional shutdown, in rare cases, to stop at an unexpected height.

[xxo1shine]

SolidityNode and FullNode have basically the same block handling logic, so theoretically they can share a common solution. There is no need to develop a new solution specifically for SolidityNode, right?

[lxcmyf]

One suggestion: could you clarify the exact shutdown timing?
When the target BlockHeight/BlockTime is hit, will the node stop only after that block is fully processed and persisted?
Since this feature is meant for state verification, that detail seems pretty important.

[liuyifei001]

SolidityNode and FullNode have basically the same block handling logic, so theoretically they can share a common solution. There is no need to develop a new solution specifically for SolidityNode, right?

@xxo1shine It only imports solution into SolidityNode, doesn't create new solution.

[warku123]

Here is one thing worth considering: FullNode and SolidityNode operate on different block types (head block vs. solidified block).

Could you clarify how the shutdown conditions would behave differently between these two node types? Specifically, would BlockHeight and BlockTime triggers use the same height reference (head vs. solidified), and how would that impact state verification scenarios where the two heights diverge?

Understanding this distinction would help ensure the implementation aligns with the intended use cases.

[halibobo1205]

@warku123 More precisely, it is neither head nor solidified, but the height that has been persisted to disk. As for why solidified is not equal to the persisted disk height, please refer to the explanation above: #6610 (comment)

[waynercheung]

@liuyifei001 Hi, @halibobo1205 has raised an important historical issue: in FullNode, session flush was triggered after session build rather than on session commit, which could cause the node to halt at an unexpected height in rare cases.

Since the proposal is to import the same condition-check logic from TronNetDelegate into SolidityNode, this raises a critical question:

• Has this flush-timing bug been fixed in the FullNode implementation that will
  be imported?
• Or will SolidityNode inherit the same race condition?

If the bug still exists upstream, importing the logic as-is would carry the same risk into SolidityNode — which is particularly problematic here, since the primary use case is state verification, where an off-by-one shutdown height would silently invalidate the entire verification result.

[waynercheung]

The spec states "only one of the three options can be enabled at a time", but the enforcement strategy isn't defined.
There are two approaches:

Option A — Fail-fast at startup (recommended)

ERROR: Multiple shutdown conditions configured. 
Only one of [BlockHeight, BlockTime, BlockCount] may be active at a time.

Option B — Runtime precedence rule (e.g., BlockHeight > BlockTime > BlockCount)

Option A is strongly preferred for a state-verification tool — silent precedence rules could lead to the node stopping at an unintended condition without any indication to the operator.

@liuyifei001 Which behavior is intended, and whether config validation will be added to the startup sequence?

[halibobo1205]

The enforcement strategy has been defined in Manager#initAutoStop: @waynercheung cc @liuyifei001

if (exitHeight > 0 && exitCount > 0) {
      throw new IllegalArgumentException(
          String.format("shutDownBlockHeight %d and shutDownBlockCount %d set both",
              exitHeight, exitCount));
    }

    if (exitHeight > 0 && blockTime != null) {
      throw new IllegalArgumentException(
          String.format("shutDownBlockHeight %d and shutDownBlockTime %s set both",
              exitHeight, blockTime));
    }

    if (exitCount > 0 && blockTime != null) {
      throw new IllegalArgumentException(
          String.format("shutDownBlockCount %d and shutDownBlockTime %s set both",
              exitCount, blockTime));
    }

[waynercheung]

The enforcement strategy has been defined in Manager#initAutoStop: @waynercheung cc @liuyifei001

@halibobo1205 Got it, thanks.

[waynercheung]

After checking the current code, I think this feature should reuse the existing auto-stop semantics instead of introducing a SolidityNode-specific shutdown definition.

The important point is that the shutdown reference should be the local persisted height, not the in-memory head height.

Now, the config format and basic plumbing already exist (node.shutdown, Args parsing, Manager.initAutoStop). In FullNode, the actual stop check is based on latestBlockHeaderNumberFromDB, which is read from the root DB state. That means the node stops only after the target block has been persisted locally.

This distinction matters because SnapshotManager.flush() is triggered from buildSession(), not from commit(). So "block processed" is not always equal to "block flushed to the local root DB". That is exactly why stopping immediately after processing the target block can be unsafe for state verification.

For SolidityNode, there is one more detail: it does not go through TronNetDelegate.processBlock(), and it updates LATEST_SOLIDIFIED_BLOCK_NUM after pushVerifiedBlock() returns. So if we simply copy the shutdown check into SolidityNode and use the just-processed block number as the trigger, we may still stop too early.

My suggestion is:

1. Keep the existing config format unchanged.
2. Reuse a common shutdown helper/shared logic for FullNode and SolidityNode, instead of duplicating the condition in TronNetDelegate.
3. Define BlockHeight, BlockTime, and BlockCount against the local persisted block in DB.
4. Clarify explicitly in the spec that shutdown happens only after the target block is fully processed and the local DB root has reached that block.
5. Add a SolidityNode test for the startup edge case where the current local height already equals the target height, especially if p2pDisable is forced to true.

So overall, I think the specification should state "persisted local height" very explicitly. That is the only definition that matches the state verification use case.