Feature request: simple option to fast-forward ledgers in --local mode

[teddav]

Quickstart is great for local development. It would be great to add a feature for advancing ledgers quickly.

What I'm trying to do

When testing against --local, the network starts at ledger 1, which doesn't look or behave much like testnet/mainnet (where ledger numbers are in the millions and time has visibly passed). I'd like a way to quickly fast-forward to a higher ledger number. Both for realistic UI testing and for exercising time-based contract logic without waiting a long time.

What I tried

I went down the ENABLE_CORE_MANUAL_CLOSE=true + curl /manualclose path. It works in principle but isn't really convenient:

• Throughput is heavily bottlenecked when horizon/rpc are also enabled (their captive cores fall behind and constantly catch up). To get reasonable speed I had to disable everything except core, burn ledgers, then restart with horizon/rpc. But that two-phase workflow hits other rough edges: friendbot autostarts and crashes when horizon is disabled, taking down the container.
• It's not obvious from the docs which env vars actually exist vs. don't. I tried things like STELLAR_CORE_FLAGS, ENABLE_FRIENDBOT, etc. that turned out to be silently ignored. The set of supported env vars and flags also seems to change between image versions, so older tutorials, or responses on Discord point at things that no longer work.

What would be ideal

An endpoint to automatically advance by N ledgers

[LiamVanderdeg]

Thanks @teddav for opening this. Hit the exact same issues.

Confirming that on stellar/quickstart:future, the only way to get real throughput is:

1. Run --local with --core-config-unsafe-mode - this disables archive publishing + validation which bottleneck the captive cores
2. Keep horizon/rpc disabled while burning ledgers, otherwise they fall behind as you described
3. Call /manualclose in a loop

The two-phase workflow you mentioned is exactly what we use for ChathaPop.app testing: start core-only, fast-forward, restart with full stack. But friendbot crashing when horizon is down is painful.

A --preset dev-fastforward flag that:

• Sets --core-config-unsafe-mode
• Disables horizon/rpc/friendbot by default
• Adds /advance-ledgers?count=N endpoint

would solve this. This matches real testnet/mainnet behavior where ledger numbers are in millions, critical for time-based Soroban contract testing.

Building ChathaPop on Stellar/Soroban and this setup cut our local test time 90%. Happy to test a PR.

[LiamVanderdeg]

@teddav I opened PR #934 with the proposal for the /advance-ledgers endpoint.

Based on testing for my project, this setup cuts local test time ~90%.
Let me know what you think!

[leighmcculloch]

Is the goal only to have the local network start with a larger ledger number as part of startup? Or to be able to move around between ledgers after startup?

Asking because the possible solutions for both could be very different.

network starts at ledger 1, which doesn't look or behave much like testnet/mainnet (where ledger numbers are in the millions and time has visibly passed)

Could you share more about the problems this creates for an application integrating with quickstart?

[LiamVanderdeg]

@leighmcculloch It's the second option - advancing ledgers after startup.

PR #934 implements /advance-ledgers for exactly that. It lets you fast-forward once core is running, which matches the 2-phase workflow teddav described and solves the slow testing issue.

[leighmcculloch]

PR #934 implements /advance-ledgers for exactly that.

In the PR it says the following that I took to mean it happens once soon after startup. Because presumably you'd want to then startup horizon, rpc, and friendbot to be able to use quickstart.

Add --preset dev-fastforward that:

• Enables --core-config-unsafe-mode to disable archive publishing/validation
• Disables horizon/rpc/friendbot by default during fast-forward
• Exposes /advance-ledgers?count=N endpoint as requested by @teddav

This allows reaching ledger 1M+ in minutes, matching real network conditions for time-based contract testing.

Is the idea that you can startup, use advance-ledgers, do some testing, then use advance-ledgers again, do more testing? Or is the idea that you can startup, use advanced-ledgers once, then do some testing but not use it a second time?

[LiamVanderdeg]

Thanks for checking PR #934.

The idea is to use /advance-ledgers?count=N multiple times during a session.

Typical flow:
Start quickstart with --preset dev-fastforward
Call /advance-ledgers?count=1000 to jump to ledger 1000, run tests
Call /advance-ledgers?count=5000 again to jump further, run more time-based tests

The endpoint doesn’t lock after one use. You can advance ledgers repeatedly without restarting the container. This is useful for testing contracts with env.ledger().sequence() and env.ledger().timestamp() across different ledger ranges in the same dev run.

Let me know if you want me to clarify this in the proposal doc.

[teddav]

Yes, we need a way to keep advancing ledgers while we build.
For example: for the app I'm building, I rely on events, so I need a way to verify getEvents behavior on a large range of ledgers. Since most node allow to query events only up to 7 days, I need to run my own indexer. But I want to make sure it behaves correctly in the long run. So I want to be able to run a large number of transactions, then close a lot of ledgers, run another larger number of transactions, ...
@leighmcculloch ideally, each ledger would close really fast, so i can also quickly run many transactions.

@LiamVanderdeg regarding the API, imo advance-ledgers?count=1000 would fast-forward 1000 ledgers. Not "jump to ledger 1000`. Maybe we could add both behaviors

[LiamVanderdeg]

Thanks @teddav, good catch on the wording. You're right, count=1000 fast-forwards 1000 ledgers from the current state, not jump to ledger 1000. I'll update the proposal doc to make that clear.

I agree that having both count and to parameters would be useful. For now, the proposal focuses on count since that's what the current endpoint supports, but we can note the to behavior as a future improvement.

Glad to hear this use case matches your indexing workflow.

[LiamVanderdeg]

Done. Updated the proposal doc to clarify that count fast-forwards 1000 ledgers from the current state.

[leighmcculloch]

Disables horizon/rpc/friendbot by default during fast-forward

Is the idea with the above that everytime you call /advance-ledgers that horizon, rpc, and friendbot get shut down, or that in this mode there is never a running horizon, rpc, or friendbot?

[LiamVanderdeg]

It's the second one. In dev-fastforward mode, horizon, rpc, and friendbot are disabled for the entire fast-forward run. They aren't shut down/restarted per call - there are no running instances while fast-forward is active.

[teddav]

It would be better if everything could be enabled though. If we can find a way to keep rpc, horizon and friendbot enabled while still having that feature, it would be great. @LiamVanderdeg proposed to disable them because that's the only solution we found in order to close ledger faster. Otherwise Horizon would slow down the process, and friendbot would crash the node.
If we do have to disable them, we need an easy way to re-turn them back on for testing, and off for re-advancing