Implement contract metadata versioning and compatibility validation

[Just-Bamford]

Description

Problem

Contract metadata can evolve as contracts are upgraded. The SDK currently has no standardized mechanism for determining whether cached or generated metadata remains compatible with the contract version being invoked.

This can lead to confusing runtime failures when function signatures, argument types, storage definitions, or contract interfaces change.

Solution

Introduce metadata version tracking and compatibility validation.

The SDK should associate metadata with a contract identifier and version/fingerprint. Before using cached metadata, it should validate that the metadata corresponds to the expected contract interface.

Provide compatibility checks capable of identifying breaking and non-breaking changes and expose migration hooks for supported metadata transformations.

Acceptance Criteria

• Contract metadata contains a deterministic version or fingerprint.
• Metadata versions are associated with contract identifiers.
• Compatibility checking distinguishes compatible and breaking changes.
• Stale metadata is detected before contract invocation.
• Clear compatibility errors/warnings are returned.
• Metadata migration hooks are supported.
• Cached metadata is invalidated when incompatible metadata is detected.
• Tests cover identical, compatible, incompatible, and missing metadata versions.
• Existing metadata consumers remain backward compatible.
• Exported through src/soroban/index.ts and src/index.ts.

Note for Contributors

Avoid relying exclusively on semantic version strings. Contract interface fingerprints should provide deterministic compatibility validation where possible.

[Vicistar-V]

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

I’d like to work on this issue because it addresses an important area of the project and presents a great opportunity to make a meaningful contribution. I’m particularly interested in delivering a solution that is reliable, maintainable, and aligned with the project’s existing architecture and development standards.

I have experience working across software development, including backend and frontend development, APIs, databases, testing, DevOps, and blockchain-based applications. I’m comfortable understanding existing codebases, identifying the root cause of issues, implementing clean and scalable solutions, and writing thorough tests to prevent regressions.

My approach would be to first understand the existing implementation and project conventions, then develop the solution in a focused and incremental way. I’ll ensure the changes are well-tested, documented where necessary, and do not introduce unnecessary complexity or break existing functionality. I’m also committed to clear communication, responding to review feedback, and delivering a polished contribution that provides real value to the project.

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

[vijay11149]

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

i will love to work on this issue

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

[connelevalsam]

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

I will like to work on this issue

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

[drips-wave]

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

🧑‍💻 @connelevalsam: 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 🌊