fix(#620) user-friendly balance errors + feat(#636) E2E job-lifecycle…

[Bashibawa]

… tests

Issue #620 — [BUG-03] No error feedback when contract call fails due to insufficient balance

Problem

When a Soroban contract call failed because the user's wallet did not hold enough XLM (or allowed token), the frontend either:

• silently swallowed the error, or
• displayed the raw SDK/XDR error string (e.g. 'HostError: Error(Contract, [SC-5] Prevent client from indefinitely withholding approval #10)' or a 60-character Base64 blob), which is meaningless to end users.

Fix

frontend/lib/stellar.ts — added parseContractError(error, currentBalance?)
A single utility function that normalises every known Stellar/Soroban error
surface into a readable English sentence:
• Insufficient balance patterns:
- 'insufficient balance', 'balance is not sufficient', 'op_underfunded', 'underfunded', Error(Contract, #10) (SAC balance error) → "Insufficient balance. Your current balance is X XLM. Please add funds and try again." (when currentBalance is supplied) • Known escrow contract error codes #1–#15 (mapped from contracts/escrow/src/lib.rs): #1 Not authorized, #2 Job not found, #3 Invalid status, #4 Zero amount, #5 Token not allowed, #6 Description too large, #7 Platform paused, #8 Past deadline, #9 Active-job limit, #10 Insufficient balance, #11 Deadline not passed, #12 Freelancer-only, #13 Client-only, #14 Revision limit, #15 Dispute already raised • Wallet / signing: 'user declined', 'user rejected', 'cancelled' → "Transaction was cancelled." • Fee errors: 'tx_insufficient_fee' → "Transaction fee is too low…" • Network/timeout errors • Fallback: original message with XDR blobs stripped (regex replaces runs of 60+ Base64 chars with '[data]') and truncated to 200 chars.

frontend/app/job/[id]/page.tsx — updated handleAction catch block:

• Imports parseContractError and getNativeBalance from stellar.ts.
• Before displaying an error, fetches the user's current native (XLM) balance via Horizon so the message can include "Your current balance is X XLM".
• Falls back gracefully if the balance fetch itself fails (balance stays undefined; parseContractError emits the version without the balance detail).

frontend/app/post-job/page.tsx — updated the contract-call catch block:

• Same pattern: imports parseContractError + getNativeBalance, fetches balance before calling the parser, then passes the result to setError.

---

Issue #636 — [TEST-09] Add end-to-end tests for complete job lifecycle

Problem

No Playwright E2E tests existed for the core escrow lifecycle: connect wallet → post job → accept job → submit work → approve work. State transitions were only covered by unit/integration tests that cannot catch UI-layer regressions.

Fix

frontend/e2e/job-lifecycle.spec.ts — new file, 440 lines, 17 tests

Design decisions:
• Real Soroban transactions require a funded Testnet account and deployed
contract, which is unavailable in CI. The suite uses two complementary
stubs injected via page.addInitScript (Playwright's pre-load hook):

1. `injectMockWallet(page, address)` — Defines `window.freighter` with `isConnected`, `getPublicKey`, `getNetwork`, and `signTransaction` all returning deterministic values. Also sets `window.__mockFreighterAddress` for the modern @stellar/freighter-api shim.

2. `injectContractStubs(page)` — Populates `window.__contractStubs` with per-method success payloads (post_job, accept_job, submit_work, approve_work, get_job, etc.) and sets `window.__contractStubEnabled = true` so the app layer can detect test mode without modifying production code.

Test groups and coverage:

[TEST-09] Complete Job Lifecycle E2E (13 tests)
1. Connect wallet button / wallet menu visible on homepage
2. Post Job page loads with required form fields
3. Post Job form shows validation errors on empty submit
4. Post Job form accepts valid input without JS crash
5. Job detail page renders for valid numeric job ID
6. Job detail page shows invalid-id error for non-numeric ID
7. Job detail page shows invalid-id error for negative ID
8. Dashboard loads and shows Posted / Accepted sections
9. Insufficient balance → user-friendly error message visible in UI
10. Navigate: homepage → post-job → back
11. Navigate: job detail → back to homepage
12. Post Job form submits → job detail redirect or success feedback
13. Accept Job button visible for Open jobs (wallet connected)

[TEST-09] Job Lifecycle – UI State Transitions (4 tests)
14. Full round-trip: post → detail → dashboard (no crash)
15. Wallet connect flow — no unhandled JS exception
16. Opaque contract errors do not reach the UI as raw XDR/hex noise
17. Client / freelancer test addresses match the Stellar G-key format

Closes #620
Closes #636

Pull Request Template

Linked Issue

PR Title

This PR title follows the Conventional Commits format as required by CI. See PR Title Conventions for details.

What Changed

Describe the main changes and any relevant design trade-offs.

Validation

• I referenced the related issue in this PR.
• Contract checks pass (soroban contract build and cargo test in contracts/escrow) if contract code changed.
• Frontend checks/build pass for changed frontend files.
• I included screenshots or short clips for UI changes (or noted N/A).

Additional Notes

Add any follow-up work, risks, or reviewer context.

[drips-wave]

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

[gitguardian]

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

Since your pull request originates from a forked repository, GitGuardian is not able to associate the secrets uncovered with secret incidents on your GitGuardian dashboard.
Skipping this check run and merging your pull request will create secret incidents on your GitGuardian dashboard.

🔎 Detected hardcoded secret in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
-	-	Generic High Entropy Secret	3bb650b	frontend/e2e/job-lifecycle.spec.ts	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secret safely. Learn here the best practices.
3. Revoke and rotate this secret.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[Bashibawa]

Hello Maintainer, late PR submission, kindly merge. Thank you