feat(stellar): pin and verify escrow contract metadata

[Muyideen-js]

Closes #271

Description:

Adds contract metadata pinning and verification to prevent operating on swapped/unexpected escrow contracts.
Loads an optional pinned metadata hash from SOROBAN_ESCROW_CONTRACT_METADATA_HASH and verifies fetched on-chain metadata against it before use.
On mismatch: refuses to operate, throws a safe ContractMetadataMismatchError, and increments Prometheus metric contract_metadata_mismatch_total{contract}.
Includes deterministic canonicalization and SHA-256 hashing for stable verification.
Adds unit tests for match and mismatch behavior.
Files changed:

Added: contractMetadata.ts, contractMetadata.unit.test.ts
Modified: sorobanEnv.ts, safeErrors.ts, appError.ts
Testing:

Unit tests added cover canonicalization, successful verification, and mismatch + metric.
Please run:
Acceptance criteria:

Integration tests should cover both matching metadata (allowed) and mismatched metadata (rejected). The new unit tests demonstrate the core behavior. I recommend adding an integration test that wires the module into the Soroban RPC integration path (e.g., via an injected fetcher or a mock RPC server) to exercise end-to-end behavior.
Security notes & assumptions

The pinned hash is a SHA-256 hex digest of a canonicalized JSON representation of contract metadata. Rotation procedure: update SOROBAN_ESCROW_CONTRACT_METADATA_HASH in your environment/secrets, deploy with a canary, and verify metric / health checks before promoting.
No secrets are stored in code. Use environment secrets in deployment.
The verification function accepts an injectable fetcher (for safe unit/integration testing). In production, wire it to your Soroban RPC client with appropriate retry/backoff and auth if required.
On mismatch, the module throws a safe error code contract_metadata_mismatch. The safe message is mapped in safeErrors.ts.
Added Prometheus counter metric contract_metadata_mismatch_total to alert on unexpected contract metadata changes.

[drips-wave]

@Muyideen-js 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