Detect ABI-version mismatch between src/starknet/abi.ts and the deployed contract at startup

[Jagadeeshftw]

📌 Description

src/starknet/abi.ts bundles a static ABI used to decode on-chain events and calls. If the deployed contract is upgraded and the bundled ABI drifts, decoding fails or silently mis-decodes fields — there's currently no startup check to catch this early.

🧩 Requirements and context

• On boot, fetch the deployed contract's class hash/ABI and compare a fingerprint against the bundled ABI.
• Fail startup loudly (or log a prominent warning, configurable) on mismatch rather than degrading silently later.

🛠️ Suggested execution

1. Add a verifyAbiCompatibility() helper in src/starknet/abi.ts.
2. Call it during app startup in src/index.ts, gated by an env flag for environments without RPC access.
3. Add a test with a mocked mismatched class hash.

✅ Acceptance criteria

• Mismatch is detected and surfaced clearly at startup.
• Matching ABI passes silently.
• Behavior is configurable (fail-fast vs warn-only) via env.

🔒 Security notes

A silently mis-decoded event could misrepresent payment amounts in the API — treat this as a data-integrity control, not just a nicety.

📋 Guidelines

• Minimum 95% test coverage
• Clear documentation
• Timeframe: 96 hours

[sir-emmy1]

@sir-emmy1 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi! I'd love to work on this issue. Please assign it to me

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

[Jagadeeshftw]

Assigned @sir-emmy1 to this issue. Please open a PR referencing this issue (e.g. Closes #121) when you're ready. If you have questions along the way, feel free to join our contributor chat: https://t.me/+vTbe0hOUKrFhNTJl

[drips-wave]

Congratulations, @sir-emmy1! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

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

[Jagadeeshftw]

Thanks for applying here. Please also join our Telegram group here: https://t.me/+vTbe0hOUKrFhNTJl. It helps us keep communication clear while we review contributions.