[Owolabenjade]

Closes #144, Closes #143, Closes #142, Closes #141

Summary & Motivation

This PR delivers comprehensive solutions for four core contract integration, developer tooling, and portfolio usability issues:

1. Issue Detect at runtime when deployed contracts don't match the bundled bindings #144 (Runtime Contract Integrity Detection):

   • Detects mismatches between frontend bundled contract bindings (lib/stellar/generated/*.ts) and deployed bytecode on-chain.
   • Prevents silent failures or corrupt transactions when operators point NEXT_PUBLIC_*_CONTRACT_ID to forked or outdated contract deployments.
   • Decodes contractspecv0 sections from WASM bytecode at runtime via custom ULEB-128 parsing, computes canonical SHA-256 spec fingerprints, verifies SAC contracts, and gates write transactions before submission.
   • Displays a non-intrusive IntegrityBanner alerting operators with Stellar Expert explorer links and error summaries.

2. Issue Report contract interface changes when the contracts submodule moves #143 (Contract Interface Diff & Error Coverage):

   • Eliminates blind contract interface changes when the contracts/ submodule is updated.
   • Adds a static AST and spec diff engine (scripts/spec-diff.mjs) comparing local generated bindings against origin/develop, detecting additions, deletions, or signature modifications and scanning all frontend files for impacted call sites.
   • Guarantees 100% human-friendly coverage for all Soroban error codes defined in bindings with an automated test guard in lib/stellar/errors.ts.

3. Issue Coordinate the upgrade to stellar-sdk 17 and a newer wallets kit #142 (Stellar SDK & Wallets Kit Multi-Dependency Guard):

   • Coordinates multi-package dependency health and guards against diamond dependency splitting across @stellar/stellar-sdk and @creit.tech/stellar-wallets-kit.
   • Adds a lockfile validator (scripts/check-sdk-major.mjs) run in CI to verify that only a single major version of @stellar/stellar-sdk exists in the dependency tree.
   • Cleanly separates and isolates hardware wallet transitive paths (@trezor, ledger) from core frontend SDK alignment checks.

4. Issue Watch-only mode to inspect any address's positions and history #141 (Watch-Only Mode for Addresses):

   • Introduces a type-safe identity abstraction separating SignerAddress (allowed to sign transactions) from ViewedAddress (the subject of portfolio inspections).
   • Allows users to inspect any Stellar address's positions, transaction history, and live valuations via URL query parameter (?watch=G...), manual input, or preset pills without requiring wallet connection.
   • Batches persistent ledger entry queries (DataKey::Position(market_id, holder)) in chunks up to 200 keys per RPC request, drastically reducing latency compared to sequential contract simulations.
   • Strictly write-gates all mutating contract calls (useBuy, useSell, useRedeem, useUsdcTransfer) and copy-trade balance sizing to prevent unauthorized transaction preparation while inspecting third-party addresses.

How the Flow Works Now

• Contract Verification at Runtime (Detect at runtime when deployed contracts don't match the bundled bindings #144): On initial load, useContractIntegrity() fetches deployed contract bytecode using getLedgerEntries, parses Wasm custom sections to extract the spec, normalizes parameter structures, and compares the fingerprint with bundled client specs. If mismatch or archived status is detected, the UI displays IntegrityBanner, and useWriteGuard blocks transaction signing with a clear UserFacingError.
• Spec Diff Reporting in CI (Report contract interface changes when the contracts submodule moves #143): Running npm run spec:diff inspects git diffs against the upstream branch and parses TypeScript AST declarations. If signatures drift or functions are removed, it prints a GitHub markdown report detailing affected call sites. errors-coverage.test.ts validates that every contract error code has an intuitive user message.
• SDK Lockfile Check in CI (Coordinate the upgrade to stellar-sdk 17 and a newer wallets kit #142): Running npm run check:sdk parses package-lock.json packages, validating that no duplicated or mismatched @stellar/stellar-sdk major versions are installed.
• Watch-Only Inspection Flow (Watch-only mode to inspect any address's positions and history #141):
  • Users enter an address or click a quick pick in /portfolio, or load any page with ?watch=G....
  • useViewedAddress parses and validates the address checksum and stores it in session storage.
  • A persistent top-level banner (ViewingBanner.tsx) displays the watched address and a one-click "Stop watching" control.
  • Portfolio position loading uses fetchPositionsFor(viewedAddress) to chunk ledger lookups up to 200 keys per call.
  • Trade execution buttons on market pages are automatically disabled with explanatory text, and the underlying mutation hooks assert that viewedAddress === signerAddress.

Changed

• Issue Detect at runtime when deployed contracts don't match the bundled bindings #144: Runtime Contract Integrity Check:
  • Added lib/stellar/contract-check.ts: Custom Wasm section parser (ULEB-128 decoder), canonical spec normalizer, SHA-256 fingerprint generator, Stellar Asset Contract (SAC) validator, and useContractIntegrity hook.
  • Added components/layout/IntegrityBanner.tsx: Operator warning banner with explorer links and refresh action; mounted in app/layout.tsx.
  • Added lib/stellar/__tests__/contract-check.test.ts: 8 unit tests covering custom section extraction, fingerprinting, SAC verification, archived contracts, and error conditions.
• Issue Report contract interface changes when the contracts submodule moves #143: Interface Diff Reporter & Error Coverage:
  • Added scripts/lib/files.mjs and scripts/lib/spec.mjs: AST extraction for Soroban bindings and reference scanner for frontend call sites.
  • Added scripts/spec-diff.mjs: CLI diff reporter supporting git revisions with markdown table outputs.
  • Updated lib/stellar/errors.ts: Complete mapping of contract errors to user-friendly messages and UNFRIENDLY_ALLOWLIST validator.
  • Added package.json script "spec:diff" and integrated step into .github/workflows/ci.yml.
  • Added scripts/__tests__/spec-diff.test.ts (8 tests) and lib/stellar/__tests__/errors-coverage.test.ts (1 test).
• Issue Coordinate the upgrade to stellar-sdk 17 and a newer wallets kit #142: SDK Major Version Check:
  • Added lib/stellar/sdk-major.ts: Lockfile analyzer detecting split or duplicate SDK dependencies with hardware wallet path filtering.
  • Added scripts/check-sdk-major.mjs: CLI script for CI validation.
  • Added package.json script "check:sdk" and integrated step into .github/workflows/ci.yml.
  • Added lib/stellar/__tests__/sdk-major.test.ts: 4 unit tests covering single/multiple installations, major mismatches, and hardware wallet exclusions.
• Issue Watch-only mode to inspect any address's positions and history #141: Watch-Only Mode:
  • Added lib/stellar/identity.ts: Branded types SignerAddress and ViewedAddress with runtime StrKey validation.
  • Added lib/stellar/write-guard.ts: Pure assertion assertCanWrite preventing write actions when in watch mode.
  • Added lib/stellar/positions.ts: Batched persistent ledger entry queries for DataKey::Position(market_id, holder) chunked up to 200 keys/request.
  • Added lib/hooks/useViewedAddress.tsx: React context syncing viewed address with URL search params (?watch=) and session storage.
  • Added components/layout/ViewingBanner.tsx: Global status banner indicating watch mode.
  • Updated components/layout/WalletDropdown.tsx: Added "Stop watching" action when watch mode is active.
  • Updated app/portfolio/page.tsx: Added address watch form, quick picks, live position listing, and valuation for viewed address.
  • Updated app/portfolio/wallets/page.tsx: Display viewed identity and watched balances.
  • Updated components/market/buy-ticket.tsx and app/markets/quick-view/page.tsx: Render viewed address positions and gate trade buttons.
  • Updated app/copy-trade/page.tsx: Bound copy-trade balance checks strictly to signer wallet USDC.
  • Added unit test suites lib/stellar/__tests__/identity.test.ts (7 tests), lib/hooks/__tests__/write-guard.test.ts (8 tests), and lib/stellar/__tests__/positions.test.ts (4 tests).
• Architecture & Testing Documentation:
  • Updated docs/architecture.md with "Contract integrity check" and "Viewed address vs signer (Watch-only mode)" sections.
  • Updated docs/manual-test.md with complete manual verification protocol for Watch-Only mode.

Testing

Ran the following verification test suites and build checks:

• npm run check:sdk (passed: exit code 0)
• npm run spec:diff (passed: exit code 0)
• npx vitest run lib/stellar/__tests__/contract-check.test.ts scripts/__tests__/spec-diff.test.ts lib/stellar/__tests__/errors-coverage.test.ts lib/stellar/__tests__/sdk-major.test.ts lib/stellar/__tests__/identity.test.ts lib/stellar/__tests__/positions.test.ts lib/hooks/__tests__/write-guard.test.ts (passed: 7 files, 40 tests)
• npm run typecheck (passed: exit code 0, 0 errors)
• npx eslint lib/stellar/contract-check.ts lib/stellar/identity.ts lib/stellar/positions.ts lib/stellar/sdk-major.ts lib/stellar/write-guard.ts lib/hooks/useViewedAddress.tsx components/layout/IntegrityBanner.tsx components/layout/ViewingBanner.tsx scripts/spec-diff.mjs scripts/check-sdk-major.mjs (passed: 0 errors, 0 warnings)
• npm run build (passed: exit code 0, all 28 routes compiled and static pages generated successfully)

Scope Notes

• Frontend & Tooling Only: All changes are confined to the frontend web application, developer scripts, and CI workflows.
• Zero Smart Contract Mutations: No smart contract Rust code or deployment configurations were modified.
• Backwards Compatibility: Connected wallet workflows remain identical when no ?watch= query or watched address is specified.
• Hardware Wallet Isolation: Transitive @stellar/stellar-sdk packages bundled within Ledger/Trezor hardware drivers are intentionally scoped and isolated from core SDK version validation.

Push Command

git push -u origin feature/assigned-issues-144-143-142-141

[drips-wave]

@Owolabenjade 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]

@Alosnireda is attempting to deploy a commit to the Marvel's projects Team on Vercel.

A member of the Team first needs to authorize it.