feat(listener): add event payload version handling (#784)

[Jessepriase]

Introduce version-aware event payload parsing so future contract event schema changes can be handled without breaking existing integrations.

Changes

• event-utils.ts: add CURRENT_EVENT_VERSION, SUPPORTED_EVENT_VERSIONS, EventVersionParseResult, parseEventVersion(), validateEventVersion()
• notification-fixture-builder.ts: add StellarEventBuilder.withPayloadVersion()
• event-utils.test.ts: 31 new tests covering version parsing and validation
• mocks/@stellar/stellar-sdk.ts: re-export real xdr and scValToNative so ScVal fixture helpers work correctly in all tests

Details

parseEventVersion() extracts payload_version from:

• ScvMap payloads (NotificationScheduled contract event shape)
• Bare integer ScVals (ScvU32/ScvU64)
• Returns found=false for pre-versioned events (backward compatible)
• Catches XDR decode failures gracefully without throwing

validateEventVersion() wraps the parser result into EventValidationResult:

• No version field -> valid (backward compatibility preserved)
• Version in SUPPORTED_EVENT_VERSIONS -> valid
• Unknown/future version -> valid=false with actionable reason including the unsupported version number and the list of supported versions
• Malformed version value -> valid=false with descriptive reason

StellarEventBuilder.withPayloadVersion(version) sets event.value to an ScvMap with a payload_version key, matching the on-chain NotificationScheduled event shape for realistic test fixtures.

The @stellar/stellar-sdk mock fix re-exports xdr and scValToNative from the real installed package. The prior mock wiped out the entire SDK namespace, making xdr.ScVal undefined in every test that constructed ScVal fixtures — a pre-existing breakage now resolved.

Acceptance criteria met

• Supported versions are parsed correctly: version 1 accepted from both ScvMap and bare ScvU32 payloads
• Unsupported versions generate actionable errors: reason includes the rejected version number and the supported versions list
• Existing event formats remain supported: all pre-versioned (no version field) payloads continue to be accepted unchanged

Overview

Related Issue

Closes #

Changes

Verification

# e.g.
cd dashboard && npm test
cd listener && npm run typecheck && npm test
cd contract/contracts/hello-world && cargo test

How to Test

Checklist

• Branch is up to date with main
• Tests added/updated and all pass locally
• cargo fmt --all run (if Rust changes)
• npm run lint passes (if TypeScript changes)
• Documentation updated if behavior changed
  closes Add Event Payload Version Handling #784

[drips-wave]

@Jessepriase Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits