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?