feat: tranche-based partial refund countdown and automated alert system

[Devadakene]

Closes #376

Summary

This PR introduces the Tranche-Based Partial Refund Countdown & Automated Alert System.

Previously, if a buyer or seller abandoned a trade after only partially releasing funds (e.g., 1 of 3 tranches), the unreleased funds remained locked indefinitely until manual intervention occurred. This change automates the resolution of these abandoned trades.

Key additions:

• Database Tracking: Added pessimistic locking (SELECT FOR UPDATE) and a new tranche_refund_schedules table to keep track of partial refunds without risking concurrent execution conflicts.
• Smart Contracts: Updated refund() in escrow, htlc-core, and atomic-swap contracts to return the refunded amount (i128), ensuring the backend cleanly parses and traces exact refund amounts while preserving the strict accounting invariant.
• Backend Worker: Introduced a background Redis Stream worker (trancheRefundWorker.ts) that runs every 5 seconds. It handles automatic push alerts (sent 100 ledgers prior to timeout expiry) and seamlessly delegates refundEscrow() processing to the worker queue with automated retries.
• Frontend UI: Integrated a new TrancheCountdownBanner.tsx component into the ClaimQR page, surfacing a real-time progress bar of released tranches alongside a live ledger countdown timer.

Testing

The following commands were used to validate the change:

• Run backend unit and concurrency stress tests:
  npm run test -- apps/api/src/routes/__tests__/tranche-refund.test.ts
npm run test -- tests/concurrency/tranche_refund_stress.test.ts
• Ensure smart contract accounting invariants are preserved:
  cargo test -p escrow
• Start API locally to verify Redis queue consumer polling behavior:
  npm run dev

Checklist

• I read the contributing guide.
• I added or updated relevant documentation.
• I verified the change with the relevant tests or builds.

[vercel]

@Devadakene is attempting to deploy a commit to the jotelfootball-tech's projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
velo	Ready	Preview	Aug 26, 2026 2:33pm
velo-frontend	Ready	Preview	Aug 26, 2026 2:33pm

[jotel-dev]

Hey @Devadakene , looks like CI and the Vercel deployments are failing on this PR (node-ci build, and both velo/velo-frontend deployments). Could you fix those up before I review? Let me know if you need help debugging.

[jotel-dev]

Hey @Devadakene , this one now has a merge conflict in apps/api/src/app.ts, plus node-ci / build and both Vercel deployments are failing again.

A few other PRs (#414, #416) have touched app.ts and merged/are merging around the same time, so this branch is likely just out of date — worth pulling the latest main and rebasing rather than resolving the conflict in isolation. Let me know once it's synced up and I'll take another look at the checks.

[Devadakene]

please review

[jotel-dev]

Hey @Devadakene — nice work on the tranche-based partial refund countdown and alert system! ✅ Contracts CI, node build, and frontend deploy are all green, but there are merge conflicts blocking this one:

Merge conflicts in mobile/frontend/src/i18n/locales/en.json and es.json — can you resolve these against main?

Once that's sorted (and the main Vercel deploy finishes), this should be ready to merge. Thanks for the good work! 🙌