Local Single-Node Time Control for Quickstart

[shaoningwang-57block]

Simple Summary

This proposal adds a local-only, explicit way to move the next ledger close time forward in quickstart-like single-node environments, and aligns RPC simulation time with ledger time so time-based tests behave predictably after that jump.

Motivation

The easiest way to understand the need is with a simple example.

Suppose a contract only allows an action once every 24 hours. In a local developer environment, a test may want to perform the first action, jump forward by one day, and then perform the second action immediately.

Today that workflow is awkward for two reasons:

• there is no explicit local admin flow for forcing the next ledger closeTime in a bounded way;
• simulateTransaction can still use wall-clock time, so after a forced jump the simulation timestamp can drift away from the actual chain state.

That mismatch makes local testing harder to reason about. A developer can move ledger time forward, but preflight and execution may still appear to live in different time contexts.

Design Principles

• Localnet-first: The feature should target local single-node developer setups, not general network behavior.
• Opt-in only: The time-jump behavior should require explicit configuration and should not be widened silently.
• No global consensus broadening: Do not change global parameters such as MAX_TIME_SLIP_SECONDS just to support this workflow.
• Additive design: Prefer adding narrowly scoped code paths and config rather than changing normal paths or semantics.
• Deterministic developer UX: After a forced time jump, RPC simulation should observe the same time context as the ledger state it is simulating against.

Proposal

1) stellar-core: /forceclosetime admin endpoint

Endpoint

GET /forceclosetime?t=<unix_timestamp>

Expected behavior

• validate that t is present and numeric;
• require t > lastClosedLedger.closeTime;
• apply t as a one-shot closeTime override for the next ledger nomination;
• clear the override after it is consumed;
• trigger the next ledger flow;
• after the forced close, subsequent ledgers may continue closing normally, but from the new ledger time rather than immediately returning to wall-clock time.

Security gate

Reject this endpoint when PUBLIC_HTTP_PORT=true.

2) Configuration

Config Variable	Default	Localnet Recommended	Description
ENABLE_FORCECLOSETIME_CHEATCODE	false	true	Enables the /forceclosetime admin endpoint.
FORCECLOSETIME_MAX_FUTURE_SECONDS	60	7776000	Limits how far into the future a forced jump can go in local development.

Notes

• these values are only suggestions for local developer environments;
• the default should remain conservative;
• this proposal does not change global MAX_TIME_SLIP_SECONDS.

3) stellar-rpc: align simulateTransaction preflight time with ledger time in localnet mode

For the simulateTransaction preflight path:

• add LedgerTime to the preflight getter parameters;
• when RPC is running in localnet mode, fetch the latest ledger close time and pass it as LedgerTime;
• when LedgerTime is present, prefer it in preflight ledger info; otherwise fall back to time.Now().Unix().

Result

After a forced time jump, the simulation context is aligned with the ledger closeTime instead of drifting back to wall-clock time.

4) Flow Overview

Flow A: force next ledger close time

Client / Test Tool
    |
    | GET /forceclosetime?t=TARGET
    v
stellar-core admin endpoint
    |
    | validate request
    | - t present and numeric
    | - t > lastClosedLedger.closeTime
    | - endpoint allowed only in local/admin mode
    | - t within FORCECLOSETIME_MAX_FUTURE_SECONDS
    v
store pending next-ledger closeTime override
    |
    | trigger next ledger flow
    v
next ledger nomination uses forced closeTime
    |
    | ledger closes at TARGET
    | clear pending override
    v
subsequent ledgers continue normally from the new ledger timeline

Flow B: localnet simulate time alignment

simulateTransaction
    |
    v
RPC preflight path
    |
    +--> non-localnet mode
    |       |
    |       v
    |   use wall-clock fallback
    |
    +--> localnet mode
            |
            v
      fetch latest ledger closeTime
            |
            v
      pass LedgerTime into preflight
            |
            v
      preflight ledger info uses LedgerTime
            |
            v
      simulation time matches actual ledger state

Why This Proposal Stays Local and Scoped

The main design goal is to solve a developer workflow problem without changing normal network behavior. Because of that, the proposal keeps the feature narrow in four ways:

• an explicit next-ledger closeTime override, rather than a persistent configurable offset model;
• bounded rather than unlimited;
• admin/local-only rather than public;
• localnet simulate alignment only, not a change to non-localnet behavior.

Non-goals

This proposal does not try to redefine global consensus time acceptance.

This proposal does not require changing the normal meaning of MAX_TIME_SLIP_SECONDS.

This proposal does not attempt to introduce a permanent clock offset for every future ledger.

Compatibility and Default Behavior

• default behavior remains effectively the same as upstream unless the cheatcode is explicitly enabled;
• a widened future offset is available only when explicitly configured;
• RPC simulation alignment is limited to localnet mode; non-localnet behavior remains unchanged.

Suggested Test Plan

stellar-core

• reject /forceclosetime when PUBLIC_HTTP_PORT=true;
• reject missing or invalid t;
• reject t <= lastCloseTime;
• reject large future t when the cheatcode is disabled or the bound is exceeded;
• accept large future t when the cheatcode is enabled and within the configured bound.

stellar-rpc

• when RPC is not running in localnet mode, do not fetch latest ledger close time and continue using wall-clock fallback;
• when RPC is running in localnet mode, fetch ledger close time and pass it into preflight;
• verify that getLedgerInfo prefers LedgerTime when provided.

Open Questions

• What naming best communicates that this is local/test-only behavior?
• Should enabling the cheatcode require both ENABLE_FORCECLOSETIME_CHEATCODE=true and PUBLIC_HTTP_PORT=false?
• Should quickstart templates show an example larger bound, while core defaults stay conservative?

[mootz12]

👋 Thanks for the proposal! @shaoningwang-57block do you have a use case you could add to the proposal? This might help give context to folks reading.

For contract testing alone, this can be done via the soroban-sdk, but IMO this has uses for testing offchain, RPC dependent applications like https://github.com/script3/auctioneer-bot.

Just giving this a brief glance, it seems like a time based offset model might be a bit simpler. E.g. just tracking the timeOffset, and exposing an endpoint to add time to this offset, to ensure it is monotonically increasing. Is there a reason you opted against it? An offset looks like it would behave similarly, as after a given "adjusted" close ledger, the following ledgers would have to continue from the adjusted close ledger timestamp.

cc @Shaptic for RPC feasibility
cc @dmkozh @sisuresh for core feasibility

[leighmcculloch]

I think we might be able to satisfy the need to shift time in quickstart by modifying the actual system time. In general it's problematic if one service sees a change while another doesn't, as evidenced by the ask to also support that changing time in RPC. It's possible that Horizon, Galexie, Lab, and other services may see odd behaviour if we also don't change their time.

I've thrown together a quick test to see how well changing the system time works, and from what I can see it works pretty well. The change is here:

• Add support for time shifting inside the container quickstart#921

You can try it out with:

docker run -it --name stellar -p 8000:8000 stellar/quickstart:pr921-testing --local

View the latest close time with:

curl -s http://localhost:8000 | jq '.history_latest_ledger_closed_at'

Wait for the system to start up completely first, and for ☝🏻 to return a non-zero value, then run:

$ docker exec stellar bash -c 'echo "+72h x1" > /etc/faketimerc'

View the latest close time and it should be 72 hours in the future with:

curl -s http://localhost:8000 | jq '.history_latest_ledger_closed_at'

Please try it out and provide feedback. If it's good we can look at polishing it.

[dmkozh]

It would be great if this works, because supporting this in Core might introduce quite significant maintenance burden, while also not solving the problem for another systems as you've mentioned.

[dmkozh]

Besides the system time proposal above, I wonder if it would make sense to make 24h threshold configurable instead of fudging time in the whole stack. Like just pass it as a parameter to constructor and set it to 5 minutes instead of 24 hours.