FullNode API based on determining chain state

[yanghang8612]

Background

In the TRON FullNode API suite, a variety of endpoints are provided for reading on-chain state. These include methods such as getaccount, getdelegatedresourcev2, getcontract, triggerconstantcontract, and many others. These interfaces are extensively used by wallets, DApps, indexers, explorers, and backend services to query the current blockchain state.

At present, most read operations are performed against the node's latest in-memory state, which can vary depending on block propagation, mempool contents, and internal node synchronization. While this is sufficient for real-time interaction, it can introduce subtle inconsistencies or non-determinism when:

• State changes between consecutive reads
• State is queried during reorg or finalization windows
• Downstream systems need to reproduce state as it was at a particular block height

To support more robust and reproducible behavior, this proposal introduces deterministic state query capability that allows callers to specify a recent block height to be used as the state root for read operations.

Motivation

Adding deterministic context to state queries can improve:

• Snapshot consistency for voting, airdrops, and retroactive logic
• Test suite repeatability and CI validation for smart contract developers
• UI rendering stability across polling intervals in frontend applications
• Historical verification tools and audit pipelines
• Off-chain computation engines relying on exact state simulation

Feature Specification

Affected APIs

This feature applies to all read-only state access methods in FullNode, including but not limited to:

• getaccount
• getaccountresource
• getdelegatedresourcev2
• getcontract
• triggerconstantcontract
• ...

Any API that reflects blockchain state is a candidate for deterministic extension.

New Parameters

Each of these APIs will support the following optional parameters:

Parameter	Type	Description
block_number	int	Target block height to query against. Must be within the node's recent memory window.
deterministic	boolean	If true, query is resolved strictly against state at block_number.

Behavior

When deterministic is set to true and block_number is provided:

• The node resolves state using only the data from the specified in-memory block height.
• Dynamic values like block.timestamp and block.number reflect the queried block.
• No pending transactions or newer block state is included.
• If the requested block has already been finalized and removed from memory, an error such as BLOCK_STATE_UNAVAILABLE will be returned.

Example Payloads

getaccount

{
  "address": "T...",
  "block_number": 71234567,
  "deterministic": true
}

triggerconstantcontract

{
  "owner_address": "T...",
  "contract_address": "T...",
  "function_selector": "balanceOf(address)",
  "parameter": "00000000000000000000000041xxxxxxxx...",
  "visible": true,
  "block_number": 71234567,
  "deterministic": true
}

Response Extensions (Optional)

To clarify the execution context, responses MAY include:

{
  "execution_mode": "deterministic",
  "executed_at_block": 71234567,
  "result": { ... }
}

Error Handling

If the block specified by block_number is:

• Too old and no longer in memory: return BLOCK_STATE_UNAVAILABLE
• Not yet received by the node: return BLOCK_NOT_FOUND
• Valid but deterministic is false or omitted: fallback to current behavior

Node Requirements

• Nodes must maintain recent block states in memory for a sliding window (e.g., 512 or 1024 blocks)
• No changes to consensus logic or state mutation logic are needed
• Query cost and latency should remain similar to current behavior for recent blocks

Compatibility

• Fully backward-compatible (new parameters are optional)
• Applies only to a recent window of block state
• Clients not using block_number or deterministic will see no change in behavior

Future Considerations

• Support for finalized blocks or archive-state access beyond in-memory window (e.g., through full archive mode)
• Support for deterministic filters and paginated state views (e.g., account list snapshots)
• Integration with light clients or trustless proof systems

Request for Comments

We welcome feedback from:

• Smart contract developers: Would this capability improve testing or off-chain simulation?
• Wallet and frontend developers: Does this help in offering consistent UI snapshots?
• Node operators: Are there challenges in managing a sliding window of in-memory block state?
• Analytics and indexer providers: Would deterministic reads simplify your pipelines?

[waynercheung]

Hi @yanghang8612 , it's a good idea and it is very useful for developers who want to fetch data from a specific block state.

I have questions about the API parameters:

1. For block_number , it is only useful when deterministic is set to true, right? These two parameters are new, so what about just adding one block_number parameter?
   If users use the new block_number parameter, they are most likely attempting to retrieve data from a specific block state, and the deterministic parameter may be redundant.

2. Besides, do you have a plan to support the JSON-RPC which also supports the block parameter? such as:

   • eth_getBalance
   • eth_getCode
   • eth_getStorageAt
   • eth_call

3. How many blocks' state are stored in-memory? 18 or 19?

[Sunny6889]

@yanghang8612 Very good suggestions. Since current this proposal only apply for non-solidated blocks, as non-solidated blocks do have the risk of being forked, so here the deterministic = true will it misleading the users?

[Sunny6889]

I would suggest we pass block_hash only as the reference without deterministic. As long as there is a block_hash we only refer certain data from this block. Even the block later removed by fork, it is still valid as block hash will be changed, but block number is the same.

[yanghang8612]

The purpose of adding the additional deterministic field is to make the interface design clearer and easier to understand, and to improve compatibility and maintainability with existing interfaces.

However, according to the suggestions of @waynercheung and @Sunny6889, it is not necessary to add this field in the definition of the interface, and their main consideration is that this field is redundant on one hand, and misleading to the user in the chain reorganization scenario on the other hand.

It is likely that for most developers, a block_number parameter is sufficient to clarify the calling intent of the interface without the need for additional design parameters.

[yanghang8612]

@waynercheung

2. Besides, do you have a plan to support the JSON-RPC which also supports the block parameter? such as:

Of course, JSON-RPC is part of the standard FullNode APIs, where interfaces involving stateful queries are also supported in this issue.

3. How many blocks' state are stored in-memory? 18 or 19?

In the java-tron design, the number of snapshots in memory is related to the maxFlushCount field of the database and the number of unsolidified blocks. Whereas the number of unsolidified blocks is a constant value i.e. 18 (2/3 of the number of SRs) in the mainnet. maxFlushCount parameter tends to be 1 in FullNode where the synchronization is complete, if we configure this value then the node will have the ability to customize the number of snapshots maintained in memory. This will be very helpful in implementing deterministic state queries in this issue.

[yanghang8612]

I would suggest we pass block_hash only as the reference without deterministic. As long as there is a block_hash we only refer certain data from this block. Even the block later removed by fork, it is still valid as block hash will be changed, but block number is the same.

@Sunny6889 You're right, but why not provide it both ways, then the parameter will become blockNrOrHash.

After all, number will be easy to read and understand, but at the loss of a certain degree of certainty; hash has absolute certainty, but doesn't conform to the user's reading and understanding habits.

Chain reorganization is a small probability event, and the certainty provided by number is sufficient. If in some extremely strict certainty requirements of the scene, you can use hash.

[Sunny6889]

@yanghang8612 I agree block number is more user friendly.

[waynercheung]

@yanghang8612 I agree block number is more user friendly.

Yes, block number is more friendly for users.

And for JSON-RPC, the block parameter can be either block_number, block hash and TAG(latest, earliest, finalized), so I think we may need to also consider block_hash as a parameter. If block number has been supported, block hash will be more easier.

[waynercheung]

Nodes must maintain recent block states in memory for a sliding window (e.g., 512 or 1024 blocks)

@yanghang8612 How do you maintain recent blocks' state in memory?

[King31T]

Nodes must maintain recent block states in memory for a sliding window (e.g., 512 or 1024 blocks)

@yanghang8612 How do you maintain recent blocks' state in memory?

Also interested in how to implement it

[yanghang8612]

@waynercheung @King31T There is no definitive way to do this, so feel free to discuss.