#239 [SCF high][easy] Normalize cross-chain addresses before comparison

[veloura-dev]

CLOSE #239
What & Why
for inconsistent Ethereum/Stellar address formatting.
Adds shared address canonicalization via @oversync/sdk/addresses.
Ethereum addresses are trimmed, validated with EIP-55 checksum rules, and stored/compared lowercase.
Stellar addresses remain case-sensitive and must be valid G + 55 Base32 account IDs.
Canonicalization is enforced at store/compare boundaries to reject malformed addresses early with 400 errors.
Corrects an invalid 39-hex-digit Ethereum USDC testnet constant.
Touched Surface
Frontend: USDC data constant, test mock, test script.
SDK: New address canonicalization module and stricter asset resolution.
Coordinator: Address normalization and API validation.
Relayer: Address validators plus a pre-existing syntax fix.
Resolver: Tests re-run; no code changes.
Contracts/Soroban: No source changes; re-tested where tooling allowed.
Docs: Added settlement-semantics/review documentation.
CI/config: Refreshed lockfile and fixed Stellar workspace dependency packaging.
Settlement & Refund Semantics
Application-layer settlement bookkeeping changed around address/secret normalization.
recordSecret() now canonicalizes preimages and makes legitimate re-reveals idempotent while rejecting different preimages.
Malformed Stellar token addresses are rejected instead of being incorrectly mapped to XLM.
Corrected the testnet USDC contract mapping.
No on-chain contracts, claim paths, timelocks, refund paths, or non-custodial invariants were changed.
Tests & Validation
SDK, coordinator, resolver, frontend, contracts, E2E, address verification, and full recursive test suites pass.
653/653 tests passed across 8 workspaces.
pnpm build: 6/6 workspaces passed.
Address verification: 21 passed, 0 failed.
Testnet asset checks: 17 passed, 0 failed.
Evidence links: 491 checked; 12 pre-existing broken links, 0 introduced.
Rust/Stellar and Foundry tests were not run because the required toolchains were unavailable.
Pre-existing Fixes Included
Fixed relayer syntax error.
Fixed coordinator recordSecret idempotency issue.
Fixed frontend test mock.
Configured Stellar tests to pass with no tests.
Changed frontend Vitest to non-watch mode.
Fixed E2E Hardhat process cleanup.
Fixed SDK JSON import compatibility with Node ≥22/Node 24.
UI / Evidence
No frontend screenshot is applicable because there is no visible UI-flow change.
Coordinator API captures demonstrate:
Canonical lowercase Ethereum storage.
Mixed-case and whitespace-padded valid queries matching correctly.
Invalid EIP-55 checksums returning 400.
Invalid Stellar addresses returning 400.
The old 39-digit Ethereum address returning 400.
Metrics / KPI
No metrics, KPI, status-table, or README changes.
Coordinator API evidence is the relevant verification.
Secrets, Logging & PII
No secrets, private keys, credentials, mnemonics, or preimages added.
No new logging of secrets or PII.
No production devtools/build exposure changes.
No new logging statements were added.
Breaking Change & Rollback
Yes — minor API-tightening breaking change.
Previously malformed addresses may have been persisted, silently mis-mapped, or returned empty results; they now receive 400 errors.
Valid callers are unaffected, although Ethereum API responses are now consistently lowercase.
No migration or feature flag is required.
Existing rows may optionally be lowercased with a one-off update.
A single git revert restores the previous behavior.
Reviewer Checklist
English PR description/comments.
Issue number still needs to be replaced with the real number.
Seven pre-existing repairs are explicitly disclosed and isolated by hunk.
New tests cover SDK addresses, assets, coordinator canonicalization/API behavior, and relayer validation.
PR is reversible with a single revert.
Files Changed
Created: 3 files, including the shared SDK address module and new address tests.
Modified: 21 files across SDK, coordinator, relayer, frontend, scripts, Stellar config, E2E, docs, and lockfile.

[drips-wave]

@veloura-dev 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

[vercel]

@veloura-dev is attempting to deploy a commit to the karagoz's projects Team on Vercel.

A member of the Team first needs to authorize it.