Implement contract state snapshots, pinning, and historical queries

[Just-Bamford]

Description

Problem

Contract state changes continuously, making it difficult to reproduce historical conditions or investigate bugs that depend on a previous state.

There is currently no high-level mechanism for identifying, storing, and querying historical contract state snapshots.

Solution

Implement contract state snapshot infrastructure.

Snapshots should be associated with a contract ID, ledger/version identifier, timestamp, and deterministic state fingerprint.

Applications should be able to pin a specific state version and later query or compare historical snapshots.

Acceptance Criteria

• Contract state snapshot infrastructure is implemented.
• pinContractState(contractId, version) is supported.
• Snapshots contain contract ID, version/ledger reference, timestamp, and state fingerprint.
• Historical snapshots can be queried.
• Snapshot integrity can be verified.
• Multiple snapshots for the same contract are supported.
• State comparison between versions is available.
• Missing or unavailable historical state is reported clearly.
• Tests cover snapshot creation, pinning, retrieval, integrity validation, and comparison.
• Exported through src/soroban/index.ts and src/index.ts.

Note for Contributors

Do not imply that arbitrary historical blockchain state can always be reconstructed locally. Clearly distinguish SDK-managed snapshots from externally retrievable ledger state.

[Dekah101]

@Dekah101 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I would like to work on this

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

[Mayor-Isaac]

@Mayor-Isaac has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi Maintainer! I’m interested in contributing to this task and can work toward delivering a clean solution on time.

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

[obedojukwu16-jpg]

@obedojukwu16-jpg has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I will like to work on this project, I know exactly what to do and I will deliver efficiently.

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

[dimin4241-svg]

@dimin4241-svg has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’ve prepared the complete implementation locally on branch feat/issue-524-contract-state-history (commit aa08f67). It adds pinContractState(contractId, version) with an injectable current/archival reader and an SDK-managed in-memory store; deterministic SHA-256 fingerprints; version/ledger/timestamp/source metadata; retrieval and filtered history queries; integrity verification; multi-version storage; structured state comparison; and clear errors when a requested historical version is unavailable instead of silently substituting current state. The API is exported through both required entry points and documented with the important SDK-managed vs externally retrievable distinction.

I added 6 tests covering creation/pinning, reader/version forwarding, multiple versions and queries, deterministic fingerprints across key order, integrity/tampering, comparison, and unavailable archival state. Targeted tests pass 6/6, repository lint passes, the new module passes strict TypeScript, JS CJS/ESM builds succeed, and export validation passes. The current main branch has unrelated pre-existing escrow export errors in its declaration build; this patch does not touch those files. I’ll rebase and rerun checks after assignment, then open the PR according to the repository guidelines.

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

[Johnalex-hub]

@Johnalex-hub has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Good day team. My name is John and i am a fullstack web3 developer. I have gone through the scope of the issue and i can guarantee my ability in getting this done. Can i please get assigned

ETA :48 hrs

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

[drips-wave]

Congratulations, @Johnalex-hub! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Johnalex-hub: 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 awarded 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 🌊