feat(integration): verify receipts, schema validation, wallet persistence, account-merge handling

[topsonDev]

Summary

This PR resolves four integration issues in a single focused change.

---

#1162 – Verify blockchain transaction receipts before confirming success

What changed: Added TransactionMonitor.verifyTransactionReceipt() — a polling method that waits for a terminal on-chain state (success / failed / timeout) before returning a result to the caller. The app no longer assumes success on submission.

How it works:

• Polls checkTransactionStatus() with exponential backoff (reuses existing calculateBackoffDelay / USER_RETRY_CONFIG).
• Transient network errors are retried; non-retryable errors surface immediately as failed.
• Configurable timeoutMs (defaults to the monitor's configured timeout).

Polling policy: same interval and backoff as the existing startMonitoring path — 3 s base, capped at 30 s, 2-minute total timeout.

Tests: 6 integration tests covering success, failure, timeout, non-retryable error, and retry-then-success.

---

#1165 – Validate IPFS metadata against a versioned schema before acceptance

What changed: New services/metadataSchema.ts with a validateMetadataSchema() function. IPFSService.uploadMetadata() now validates the constructed metadata object before pinning and throws a descriptive error on failure.

Schema versions:

• v1 (default, backwards-compatible): name, description, image — all required non-empty strings.
• v2: extends v1 with an optional attributes array ({ trait_type: string; value: string | number }).
• Metadata without a schemaVersion field is treated as v1.
• Any other version is rejected with a clear error listing supported versions.

Tests: 11 integration tests covering valid v1/v2, missing required fields, empty strings, malformed attributes, and unsupported version numbers.

---

#1161 – Persist Freighter wallet connection state across reloads

What changed: useWallet now persists the connected address and network to localStorage (key: nova_wallet_state) in addition to the existing boolean flag (nova_wallet_connected).

Storage approach:

• On connect / network change: both keys are written atomically.
• On reload: persisted state is restored optimistically (no blank UI flash) while re-validation runs against the live Freighter API in the background.
• On revocation / uninstall: both keys are cleared and the session is reset.
• Malformed or incomplete storage is ignored and treated as no session.

Tests: 6 integration tests covering persist-on-connect, restore-on-reload, clear-on-disconnect, malformed JSON, missing address field, and revocation.

---

#1166 – Handle Stellar account-merge and missing-account scenarios gracefully

What changed: Added StellarService.getAccountSafe(address) returning a typed AccountLookupResult discriminated union instead of throwing.

type AccountLookupResult =
  | { found: true; account: any }
  | { found: false; reason: 'missing' | 'error'; error?: string };

Detection logic: error messages containing not found, 404, or does not exist map to reason: 'missing' (covers both missing and merged accounts); all other errors map to reason: 'error' with the original message attached.

Tests: 5 integration tests covering existing account, 404/not-found, merged account (does not exist), unexpected errors, and the no-throw guarantee.

---

Files changed

File	Change
services/transactionMonitor.ts	Add verifyTransactionReceipt()
services/metadataSchema.ts	New — versioned schema validator
services/IPFSService.ts	Call validateMetadataSchema() before pinning
hooks/useWallet.ts	Persist address + network; restore on reload; clear on revocation
services/stellar.service.ts	Add AccountLookupResult type + getAccountSafe()
test/integration/tx-receipt-verification.integration.test.ts	New — 6 tests
test/integration/metadata-schema-validation.integration.test.ts	New — 11 tests
test/integration/wallet-state-persistence.integration.test.ts	New — 6 tests
test/integration/account-merge-handling.integration.test.ts	New — 5 tests

Total: 28 new tests, all passing.

Closes #1162
Closes #1165
Closes #1161
Closes #1166

[drips-wave]

@topsonDev 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