Skip to content

feat(cli): add epoch next and watch subcommands#670

Draft
ByteYue wants to merge 2 commits into
mainfrom
feat/cli-epoch-enhance
Draft

feat(cli): add epoch next and watch subcommands#670
ByteYue wants to merge 2 commits into
mainfrom
feat/cli-epoch-enhance

Conversation

@ByteYue
Copy link
Copy Markdown
Contributor

@ByteYue ByteYue commented Apr 19, 2026

Summary

Two light additions on top of the existing epoch status:

  • epoch next — one-line prediction of when the chain will next transition epochs. Useful for "is my PR going to catch the boundary I care about?" sanity checks without the full status breakdown. Emits structured JSON with --output json.
  • epoch watch [--interval-secs 5] [--verbose] — polls and prints when the current epoch changes. Defaults to 5s, tolerates transient RPC errors (logs and retries), and only prints a [epoch watch] line on transitions unless --verbose is passed.

Scope note — QC / DKG future work

epoch/mod.rs has an inline TODO pointing at the consensus-layer queries (/consensus/qc/:epoch/:round, /consensus/ledger_info/:epoch, /consensus/validator_count/:epoch) that would belong alongside this tooling. They're intentionally not wired up: the blocker is that crates/api/src/consensus_api.rs currently mounts those routes under #[cfg(debug_assertions)], so they're missing in release builds. Once that gate is lifted or moved to an opt-in flag, the TODO gives a future contributor everything they need to add epoch qc / epoch ledger-info etc.

Implementation notes

Shared contract-call helper fetch_epoch_timing and format_hms live in epoch/next.rs and are reused by watch so the two commands see identical values. The existing epoch status continues to use its own (slightly richer) format so the behaviour users are already relying on is unchanged.

Test plan

  • cargo build -p gravity_cli --profile quick-release clean with RUSTFLAGS="--cfg tokio_unstable"
  • gravity-cli epoch --help lists status / next / watch
  • epoch next without --rpc-url → clean required-flag error with init hint
  • epoch next against unreachable RPC → clean error with node start hint
  • epoch watch --interval-secs 3 --verbose against a node without system contracts → emits retry lines rather than crashing (behaviour identical to existing epoch status in the same scenario)
  • Global --output json threads into epoch next

ByteYue added 2 commits April 19, 2026 18:50
Two light additions on top of the existing `epoch status`:

  - `epoch next` — one-line prediction of when the chain will next
    transition epochs. Useful for "is my PR going to catch the boundary
    I care about?" sanity checks without the full status breakdown.
    Emits structured JSON with `--output json`.
  - `epoch watch [--interval-secs 5] [--verbose]` — polls and prints
    when the current epoch changes. Defaults to 5s, tolerates transient
    RPC errors (logs and retries), and streams a `[epoch watch]` line
    only on transitions unless `--verbose` is passed.

Also leaves an inline TODO in `epoch/mod.rs` for the consensus-layer
QC / ledger_info / validator_count queries that belong alongside the
epoch tooling but are blocked on the consensus HTTP API currently
being gated behind `#[cfg(debug_assertions)]` in release builds.

Shared contract-call helpers (`fetch_epoch_timing`, `format_hms`) live
in `epoch/next.rs` and are reused by `watch` so the two commands see
identical values.
@ByteYue ByteYue marked this pull request as draft April 22, 2026 02:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant