fix(bindings): detect xelma-bindings/contract ABI version skew in CI and startup #499 - #506
Open
abimbolaalabi wants to merge 5 commits into
Open
Conversation
…and startup Closes TevaLabs#499 ## Overview Add automated checks that vendored @tevalabs/xelma-bindings commit/ABI matches expected contract interface used by soroban.service, failing CI/startup on skew. Silent bindings drift causes runtime method mismatches that are costly to debug during campaigns. ## Changes - [ADD] .bindings-metadata.json — pins expected commit SHA and required Client methods / module exports - [ADD] scripts/validate-bindings.js — standalone CI validation script - [ADD] BINDINGS_UPGRADE.md — documented upgrade procedure - [MODIFY] src/utils/bindings-validator.ts — expanded to assert required export methods/types, SHA pin matching, and API surface checks via dynamic import - [MODIFY] src/index.ts — split startup into sync structural + async surface validation; FAIL_ON_BINDINGS_MISMATCH env var support - [MODIFY] .github/workflows/ci.yml — new bindings-drift job - [MODIFY] src/tests/bindings-validator.spec.ts — 20 tests covering structural checks, SHA matching, missing methods/exports, and metadata loading ## Acceptance Criteria - CI fails if required binding surface missing ✅ - Startup warns/fails per environment policy ✅ - Upgrade docs written ✅ - Test covers validator success/fail ✅
- Remove TS-only types (BetSide, OraclePayload, UserStats, UserPosition) from requiredExports in .bindings-metadata.json — these don't exist at runtime - Switch Client method validation to check .d.ts declarations instead of prototype inspection — methods are dynamically generated by ContractSpec - Add .d.ts fixture files to tests and update test expectations - Fix orphaned catch block in tournaments.routes.ts (pre-existing) - Fix duplicate class definition in hackathon.service.ts (pre-existing)
…oss test and route files - Fix duplicate imports/exports in bet-store, user.ts, bet-audit.service - Add missing betRateLimiter import in rounds.routes.ts - Fix rateLimiter mock paths in security and api-contract tests - Add missing rate limiter exports to test mocks - Fix tournament test mocks to include listTournaments and getMockById - Add round/tournament service mocks to http-logger-unified test - Fix Zod enum case mismatch in tournament tests
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
This PR adds automated checks that vendored @tevalabs/xelma-bindings\ commit/ABI matches expected contract interface used by \soroban.service, failing CI/startup on skew. Silent bindings drift causes runtime method mismatches that are costly to debug during campaigns.
Related Issue
Closes #499
Changes
Bindings Validation Engine
Verification Resultsving
\
npx jest src/tests/bindings-validator.spec.ts
PASS unit src/tests/bindings-validator.spec.ts
validateVendoredBindingsSync
√ reports missing vendor directory entirely
√ reports missing ESM entry when only CJS is present
√ reports missing CJS entry when only ESM is present
√ reports wrong package name
√ returns ok=true when ESM + CJS + correct package.json present
√ treats a missing .commit-sha as non-fatal
√ detects SHA mismatch when metadata pins a specific SHA
√ confirms SHA match when vendor SHA matches metadata
√ reports missing .commit-sha when metadata pins a SHA
√ skips SHA check when metadata SHA is PLACEHOLDER
validateVendoredBindings (async surface checks)
√ returns ok=true when all surface checks pass
√ detects missing Client methods
√ detects missing module exports
√ skips surface checks when structural checks fail
√ skips surface checks when metadata is absent
loadBindingsMetadata
√ returns null when metadata file does not exist
√ parses valid metadata file
√ returns null for invalid JSON
helper functions
√ getVendorBindingsRoot returns correct path
√ getMetadataPath returns correct path
Test Suites: 1 passed, 1 total
Tests: 20 passed, 20 total
\\
Acceptance Criteria