43. [Advanced] Implement "Sandbox Mode" for manual state overrides

[dotandev]

Description
Allow users to manually override ledger entries (e.g., balance, contract data) before replaying a transaction.

Requirements and Context

• Background: Enables "What-if" scenarios: "What if I had 1000 XLM instead of 10?".
• Success Criteria (Done):
  • --override-state ./overrides.json flag supported.
  • Replay uses overridden values instead of chain data.

Suggested Execution

• Fork/Branch: feature/advanced-sandbox
• Implementation:
  • Define an override JSON format for LedgerEntries.
  • Merge overrides with fetched chain state before injection into the simulator.

Test and Commit

• Testing:
  • Override a balance and verify the contract execution reflects the new value.
• PR Inclusions:
  • State merger logic and override parser.

Example Commit Message
feat(advanced): add sandbox mode for state overrides

Guidelines

• Must-haves: Log when an override is active to prevent confusion.

---

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 200 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[DanielEmmanuel1]

@DanielEmmanuel1 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Can i work on this, i can get this deliverd in 24 hrs max.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @DanielEmmanuel1 to this issue.

[EbukaMoses]

@EbukaMoses has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hello Maintainer,

I’d like to apply to work on this issue.

I’m Ebuka Moses, a full-stack and blockchain developer with experience building, testing, and maintaining smart contracts, particularly using Rust and blockchain-based architectures. I’m comfortable working with contract logic, validation, access control, persistent storage, and event handling, and I always pay close attention to correctness, security, and edge cases.

I take time to fully understand the issue requirements before implementing a solution, and I ensure my work follows the project’s coding standards. I also write clear, well-tested code and submit clean pull requests with meaningful commits.

I’m confident I can deliver a solid solution that meets the acceptance criteria and adds value to the project.

Thank you for your consideration, and I look forward to contributing.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @EbukaMoses to this issue.

[JerryIdoko]

@JerryIdoko has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi team, I would like to work on this issue.

I have reviewed the requirements and the context. Here is my plan for the Sandbox Mode:

Flag Implementation: Add the --override-state flag to the CLI args parser.

State Logic: Implement the logic to parse the overrides.json and merge it with the fetched chain state before the simulation starts.

Logging: Ensure a clear warning log is emitted whenever an override is active, as per the guidelines.

Testing: Verify that contract execution reflects the manually overridden balances/data.

I will work on the branch feature/advanced-sandbox as requested. Please assign this to me!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @JerryIdoko to this issue.

[sublime247]

@sublime247 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I would like to work on this issues

ℹ️ Repo Maintainers: To accept this application, review their application or assign @sublime247 to this issue.

[OtowoSamuel]

@OtowoSamuel has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I would like to work on this issue because sandbox modes are essential for safely testing complex systems. I have experience building and reviewing backend and blockchain systems where isolated state overrides and non-production execution paths are used to validate logic without impacting real data. I can implement a clean, secure, and well-scoped sandbox mode that fits the existing architecture.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @OtowoSamuel to this issue.

[Yusufolosun]

@Yusufolosun has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hello Maintainer, I'm Yusuf, and I'm a Full-Stack-Engineer with years of experience. This issue is within my capabilities so I'm confident in solving it quickly
Please kindly issue to me so I can get started.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Yusufolosun to this issue.

[drips-wave]

Congratulations, @Yusufolosun! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on January 31, 2026.

🧑‍💻 @Yusufolosun: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are issued when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊