⏱ Implement Real-Time Transaction Status Tracking #73
Description
🧭 Overview
BridgeWise executes cross-chain transfers, and users need real-time visibility of transaction progress:
- Pending → Confirmed → Completed/Failed
- Accurate status updates improve trust and user experience
- Enables developers to build responsive UIs and notifications
This issue implements Real-Time Transaction Status Tracking, integrating with transaction history (Issue #19), quote refresh (Issue #17), and slippage monitoring (Issue #20).
🎯 Problem
- Users cannot track transaction progress live
- UI may display stale or incorrect statuses
- Developers embedding the SDK lack hooks or events for status updates
- Failed transactions may go unnoticed until settlement
Without real-time tracking, BridgeWise UX is incomplete and error-prone.
💡 Proposed Solution
Implement a transaction status monitoring system that:
- Subscribes to blockchain events for each transaction
- Updates transaction state (
pending,confirmed,failed) in real-time - Exposes hooks and callbacks for developers:
useTransactionStatus() - Integrates with UI components
<BridgeStatus />,<BridgeHistory /> - Provides optional notifications for users
🛠 Scope of Work
1️⃣ Transaction Status Hook
const { status, confirmations, error, refreshStatus } = useTransactionStatus(txHash);status: 'pending' | 'confirmed' | 'failed'confirmations: number of confirmations (if applicable)error: structured error info if transaction failsrefreshStatus(): manual refresh trigger- SSR-safe
2️⃣ Integration With Components
<BridgeStatus />shows real-time status updates<BridgeHistory />reflects status changes immediately- Optional toast or banner notifications for status changes
3️⃣ Event Subscriptions
- Listen to network events for Stellar and EVM chains
- Poll APIs where subscriptions are unavailable
- Handle network latency gracefully
4️⃣ Error Handling & Fallbacks
- Gracefully handle dropped or failed subscriptions
- Provide cached or last-known status
- Structured error messages for developers
📊 Expected Outcome
- Users see accurate, real-time transaction statuses
- Developers can integrate notifications or custom UI
- Reduced failed transaction confusion
- Complete transaction visibility in the SDK
✅ Acceptance Criteria
-
useTransactionStatus()hook implemented and SSR-safe - Integration with
<BridgeStatus />and<BridgeHistory /> - Supports pending, confirmed, and failed states
- Optional notifications functional
- Handles Stellar and EVM chains
- Fallback and error handling implemented
- Unit tests covering status updates and hooks
- Documentation updated with usage examples
📈 Measurable Impact
- Increased user trust in cross-chain transfers
- Real-time visibility reduces failed transfer confusion
- Developers gain hooks for responsive UI and notifications
- Strengthens BridgeWise as a production-ready SDK
🧪 Testing Requirements
- Simulate transactions across Stellar and EVM chains
- Verify real-time status updates in hooks and UI
- Test manual refresh via
refreshStatus() - Validate fallback behavior for network errors
- Confirm SSR-safe rendering and headless mode compatibility
📚 Documentation Requirements
- Add “Transaction Status Tracking” section in README
- Provide hook usage example:
const { status, confirmations, error } = useTransactionStatus(txHash);- Include integration examples with
<BridgeStatus />and<BridgeHistory /> - Document notifications and fallback behavior