Skip to content

feat(cli): add \stellar ledger lookup\ subcommand to convert between timestamp and seq (#2285) - #2856

Closed
jdjioe5-cpu wants to merge 1 commit into
stellar:mainfrom
jdjioe5-cpu:feat/issue-2285-ledger-lookup-timestamp-seq
Closed

jdjioe5-cpu wants to merge 1 commit into
stellar:mainfrom
jdjioe5-cpu:feat/issue-2285-ledger-lookup-timestamp-seq

Conversation

@jdjioe5-cpu

Copy link
Copy Markdown

PR: feat(cli): add stellar ledger lookup subcommand to convert between timestamp and ledger sequence (#2285)

Summary

Resolves #2285.

Adds a new stellar ledger lookup (with alias convert) subcommand under stellar ledger that enables bidirectional conversion between timestamps (closed at) and ledger sequence numbers:

  1. Timestamp to Ledger Sequence (--timestamp <TIMESTAMP>):
    • Accepts Unix epoch timestamps in seconds (or milliseconds) or RFC3339 / ISO-8601 strings (e.g. 2024-05-01T12:00:00Z).
    • Retrieves the available ledger boundary (oldest_ledger to latest_ledger) from the network RPC.
    • If the target timestamp is newer than or equal to the latest ledger, returns the latest ledger.
    • If the target timestamp is within the available RPC history window, performs an accelerated binary/interpolation search to precisely find the ledger closed at or immediately before the target time ("the closest ledger that happened just before the time").
    • If the target timestamp is older than the oldest ledger retained by the RPC, returns a descriptive error indicating the available retention range.
  2. Ledger Sequence to Timestamp (--seq <SEQ>):
    • Queries the specified ledger from the network RPC and returns its formatted closed-at time (RFC3339), Unix timestamp (seconds), and block hash.
  3. Structured & Human-Readable Output:
    • Supports --output text (default), --output json, and --output json-formatted.
    • Text output displays Ledger Sequence, Closed At, Unix Timestamp, and Hash.

Changes

  • cmd/soroban-cli/src/commands/ledger/lookup.rs: Implements Cmd, LookupResult, timestamp parser, interpolation midpoint calculation, and find_closest_ledger_before_or_at.
  • cmd/soroban-cli/src/commands/ledger/mod.rs: Registers Cmd::Lookup (with alias convert) and Error::Lookup.
  • Added 8 unit tests in cmd/soroban-cli/src/commands/ledger/lookup.rs covering:
    • Unix seconds and milliseconds parsing
    • RFC3339 / ISO-8601 string parsing with timezone offsets
    • Invalid format rejection
    • Clap argument parsing and mutual exclusion (--timestamp vs --seq)
    • Interpolated search ledger matching logic (find_closest_ledger_before_or_at)
    • JSON serialization

Verification

  • cargo test --package soroban-cli --lib commands::ledger: 9 passed (8 new lookup tests + 1 existing)
  • cargo clippy --package soroban-cli -- -D warnings: 0 warnings
  • cargo fmt --check: Clean formatting

@github-project-automation github-project-automation Bot moved this to Backlog (Not Ready) in DevX Oct 23, 2026
@github-project-automation github-project-automation Bot moved this from Backlog (Not Ready) to Done in DevX Oct 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Add a command for converting between timestamp (closed at) and nearest ledger seq

2 participants