feat(rpc): add tn_syncing, tn_epochInfo, tn_currentCommittee methods by TanguyDeTaxis · Pull Request #539 · Telcoin-Association/telcoin-network

TanguyDeTaxis · 2026-02-04T22:57:30Z

Summary

Add tn_syncing, tn_epochInfo, and tn_currentCommittee RPC methods to the tn namespace
Add current_committee watch channel to ConsensusBus so RPC can access committee info
Fix tn_syncing to check both epoch and execution progress before declaring a node synced (addresses review feedback)
Add currentEpoch / highestEpoch fields to the sync progress response for better validator visibility
Add comprehensive tests: 7 serialization tests + 11 sync logic tests
Fix JSON-RPC error codes to use the standard server error range (-32000 to -32099)

`tn_syncing` behavior

Returns false when synced, or a progress object when syncing:

{
  "startingBlock": 100,
  "currentBlock": 5000,
  "highestBlock": 10000,
  "currentEpoch": 3,
  "highestEpoch": 5
}

A node is considered synced when:

It is an active CVV (CvvActive), or
Its local epoch >= network epoch and execution has caught up to the latest known consensus block

Previously, condition 2 only checked the epoch — a node could report as synced while execution was still lagging behind consensus. This is now fixed.

Files changed

File	Change
`crates/consensus/primary/src/consensus_bus.rs`	Add `current_committee` watch channel
`crates/node/src/manager.rs`	Populate committee channel on epoch creation
`crates/execution/tn-rpc/src/rpc_ext.rs`	New RPC types, methods, and serialization tests
`crates/execution/tn-rpc/src/lib.rs`	Extend `EngineToPrimary` trait with new methods
`crates/execution/tn-rpc/src/error.rs`	Fix JSON-RPC error codes
`crates/node/src/lib.rs`	Implement sync logic fix + add 11 logic tests
`crates/execution/faucet/tests/it/faucet.rs`	Update mock to implement new trait methods

tn_syncing previously returned Synced based only on epoch comparison, ignoring execution lag. A node could have consensus data for the current epoch but still be behind on execution. Now requires both epoch AND execution to be caught up before declaring synced. Also adds currentEpoch/highestEpoch fields to SyncProgress and comprehensive tests for serialization and sync_status logic.

Add a watch channel to track the current committee in ConsensusBus, enabling RPC and other components to access committee info without going through the primary node. Updated epoch manager to populate the channel when creating a committee.

Extend the tn RPC namespace with sync status, epoch info, and committee endpoints. Add SyncStatus, SyncProgress, EpochInfo, CommitteeInfo, ValidatorInfo types. Fix JSON-RPC error codes to use the standard server error range (-32000 to -32099). Update EngineToPrimary trait with the new methods and adapt faucet test mock accordingly.

# Conflicts: # crates/consensus/primary/src/consensus_bus.rs

grantkee

@TanguyDeTaxis Thank you for taking this on. It's going in the right direction, but I think there is more to consider. I'm leaving feedback for you, but I am still reviewing/thinking about some of the implementation details. Your work reflects the issue #530 however, I'm realizing there are still outstanding design decisions I need to figure out. I will follow up soon with more comments

grantkee · 2026-02-18T21:00:26Z

crates/node/src/lib.rs

nit: please move everything after L47 to execution/tn-rpc/src/rpc_ext.rs - this was missed in a previous refactor and aligns better with the separation of domain logic

Thanks, agreed on separation. I moved this out of node/lib.rs into node/engine_to_primary_rpc.rs in f586ad9 so lib.rs is only wiring now. I kept it in node for now because it depends on node-side consensus bus/reth wiring, but I can move it into execution/tn-rpc if you want that boundary in this PR.

crates/node/src/lib.rs

grantkee · 2026-02-18T21:03:56Z

crates/node/src/lib.rs

+            return SyncStatus::Synced;
+        }
+
+        // Block-level progress: compare executed blocks vs known consensus blocks.


I pointed out a similar problem in PR feedback for #542. This is comparing execution state with consensus state which is no longer guaranteed to be 1:1+ after #531

After addressing #542, I think the same approach will work here

Agreed. In e98b524 I removed the 1:1 execution<->consensus assumption. Sync now tracks consensus progress and execution progress independently (round-based), and returns Synced only when epoch + consensus + execution are all caught up.

grantkee · 2026-02-18T21:14:37Z

crates/node/src/lib.rs

+    fn current_epoch_info(&self) -> Option<EpochInfo> {
+        let (_, record) = self.db.last_record::<EpochRecords>()?;
+        Some(record.into())
+    }


Epoch records are only generated after the epoch concludes, so this logic needs to be adjusted

Updated in e98b524. network_epoch is now derived from the highest downloaded epoch record + 1, with explicit handling for the epoch-0 dummy record.

grantkee · 2026-02-18T21:20:36Z

crates/node/src/lib.rs

    db: DB,
+    /// The block number when sync started, captured on first syncing status check.
+    /// Derived from the last EpochRecord's parent_state as specified in issue #530.
+    sync_starting_block: OnceLock<u64>,


I made RethEnv thread-safe and cheap to clone in #549 so we can use it in the RPC struct

pub struct EngineToPrimaryRpc<DB> { /// Access to the execution database. reth_env: RethEnv, //...snip }

This will help address other feedback

Done, I wired RethEnv directly into EngineToPrimaryRpc (new signature includes reth_env), and use it in sync and epoch RPC paths.

grantkee · 2026-02-18T22:56:41Z

crates/node/src/lib.rs

+        // Epoch-based sync decision: compare network epoch (from committee) vs local epoch (from
+        // DB). This follows the issue #530 spec: "A node is considered synced when its
+        // execution state is within the current consensus epoch."


The content is good, and I appreciate well-commented code. That being said, please remove the reference to the "issue #530"

The comment might be more accurate by saying:

...compare network epoch (from last epoch record) vs local epoch (from execution DB). A node is considered synced when its execution state is within the current consensus epoch

Done. I removed the issue #530 wording and updated the comments to describe the data sources directly (network epoch from epoch records, local epoch from execution state).

grantkee · 2026-02-18T22:59:45Z

crates/node/src/manager.rs

+        self.consensus_bus.current_committee().send_replace(Some(committee.clone()));
+


This committee is the local committee - loaded from the latest execution state per epoch. I think the consensus_bus.current_committee().send_replace() should happen when a new epoch record is verified (~manger.rs:1238)

Good call. I now publish current_committee after persisting a new epoch record (manager.rs around save_epoch_record path), and also publish at committee load so RPC reflects the live epoch promptly.

grantkee · 2026-02-18T23:02:19Z

crates/node/src/lib.rs

+
+        // Synced only when both epoch AND execution are caught up.
+        // A node can have consensus data for the current epoch but execution may still
+        // lag behind — we must wait for execution to complete before declaring synced.


Yes, I agree with this comment (which is more specific than the "execution state is within the current consensus epoch" from the issue. The problem is even with ~6h epochs, a node might not be synced for some time

Agreed, and this is now reflected in e98b524: even with long epochs we do not report Synced unless execution progress has also caught up.

grantkee · 2026-02-18T23:04:54Z

crates/node/src/lib.rs

+            return SyncStatus::Synced;
+        }
+
+        // Fallback when committee info is unavailable (e.g. early startup):


Another edge case to consider is the 0 epoch when there is only a dummy epoch record until the first epoch closes

Handled in e98b524: I added the epoch-0 dummy-record guard so network_epoch does not advance incorrectly before the first real epoch record.

grantkee · 2026-02-18T23:09:55Z

crates/execution/tn-rpc/src/rpc_ext.rs

+pub struct SyncProgress {
+    /// The block number the node started syncing from.
+    pub starting_block: u64,
+    /// The current block number the node has reached.
+    pub current_block: u64,
+    /// The highest known block number.
+    pub highest_block: u64,
+    /// The node's current local epoch.
+    pub current_epoch: u64,
+    /// The network's current epoch.
+    pub highest_epoch: u64,
+}


The starting_block, current_block, highest_block should all mention and correlate to consensus blocks (aka - ConsensusHeader). Please add another field to this struct that includes execution_block_height or something along those lines that uses RethEnv::canonical_tip() number

Implemented. I clarified these fields as consensus block metrics and added execution_block_height from reth canonical tip, with serialization/deserialization test updates.

grantkee · 2026-02-19T12:55:29Z

crates/node/src/lib.rs

+        // DB). This follows the issue #530 spec: "A node is considered synced when its
+        // execution state is within the current consensus epoch."
+        let network_epoch =
+            self.consensus_bus.current_committee().borrow().as_ref().map(|c| c.epoch());


The network_epoch is most likely the highest downloaded epoch record (from DB) + 1 (assuming the node has successfully fetched all existing epoch records as outlined in SYNC.md)

local_epoch = epoch from the node's execution state (current_committee epoch, or canonical tip)

Implemented this approach in e98b524: network_epoch uses highest downloaded epoch record + 1, while local_epoch comes from execution state (canonical tip epoch), with committee fallback.

TanguyDeTaxis · 2026-02-19T22:36:16Z

Thanks for the detailed feedback, @grantkee .

I pushed a follow-up series tonight to address the sync/epoch/committee points and improve maintainability:

e98b524: reworked tn_syncing to align consensus + execution progress (including consensus round tracking), and added executionBlockHeight in SyncProgress.
90e73d2: tn_epochInfo now reflects active execution epoch data (instead of relying only on the latest persisted epoch record), and the active committee is now published earlier so RPC reflects live epoch state.
f586ad9: extracted EngineToPrimaryRpc from node::lib into a dedicated module for clarity and easier iteration.

I also added/updated tests around sync status and active-epoch behavior. Happy to adjust further if you want a different interpretation for specific edge cases.

TanguyDeTaxis had a problem deploying to merge-into-main February 4, 2026 22:57 — with GitHub Actions Failure

TanguyDeTaxis force-pushed the 530-tn-rpc-methods branch from ae01506 to b4d8c3b Compare February 5, 2026 22:05

TanguyDeTaxis had a problem deploying to merge-into-main February 5, 2026 22:05 — with GitHub Actions Failure

TanguyDeTaxis added 3 commits February 5, 2026 23:08

TanguyDeTaxis force-pushed the 530-tn-rpc-methods branch from b4d8c3b to 8f2132f Compare February 5, 2026 22:09

TanguyDeTaxis had a problem deploying to merge-into-main February 5, 2026 22:09 — with GitHub Actions Failure

TanguyDeTaxis marked this pull request as ready for review February 5, 2026 22:14

TanguyDeTaxis had a problem deploying to merge-into-main February 5, 2026 22:14 — with GitHub Actions Failure

grantkee assigned TanguyDeTaxis Feb 6, 2026

grantkee self-requested a review February 11, 2026 20:41

grantkee linked an issue Feb 11, 2026 that may be closed by this pull request

feat: tn_ RPC Namespace Methods #530

Open

grantkee mentioned this pull request Feb 11, 2026

Make RethEnv Thread-Safe with Arc<RethEnvInner> #548

Closed

Merge branch 'main' into 530-tn-rpc-methods

f6f855c

# Conflicts: # crates/consensus/primary/src/consensus_bus.rs

TanguyDeTaxis had a problem deploying to merge-into-main February 13, 2026 23:18 — with GitHub Actions Failure

ci: retrigger checks after transient rustup timeout

77c4b9a

TanguyDeTaxis had a problem deploying to merge-into-main February 13, 2026 23:23 — with GitHub Actions Failure

grantkee mentioned this pull request Feb 18, 2026

feat: observer diagnostics, sync-aware healthcheck and e2e tests #542

Merged

4 tasks

grantkee requested changes Feb 18, 2026

View reviewed changes

grantkee reviewed Feb 19, 2026

View reviewed changes

TanguyDeTaxis added 3 commits February 19, 2026 21:53

fix(rpc): align tn_syncing with consensus and execution state

e98b524

fix(rpc): return active epoch info and publish live committee

90e73d2

refactor(node): extract EngineToPrimaryRpc from lib root

f586ad9

TanguyDeTaxis had a problem deploying to merge-into-main February 19, 2026 21:56 — with GitHub Actions Failure

		self.consensus_bus.current_committee().send_replace(Some(committee.clone()));

Conversation

TanguyDeTaxis commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

tn_syncing behavior

Files changed

Uh oh!

grantkee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TanguyDeTaxis commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

TanguyDeTaxis commented Feb 4, 2026 •

edited

Loading

`tn_syncing` behavior

TanguyDeTaxis commented Feb 19, 2026 •

edited

Loading