Feat/fees

[nafiuishaaq]

BridgeWise provides cross-chain quotes, but fees can vary based on:

Network congestion
Liquidity pool depth
Gas price fluctuations (EVM)
Bridge-specific transaction costs
This issue introduces a Dynamic Fee Estimation Engine to provide accurate, real-time fee predictions per route.

Accurate fee estimates are critical for:

Smart ranking (Issue #5)
Slippage calculations (Issue #7)
Transparency for users
Reducing failed transactions due to insufficient funds
🎯 Problem
Static fee estimates are inaccurate during network congestion.
Users may be charged more than expected.
Ranking based purely on outdated fees can select suboptimal routes.
Lack of dynamic fees reduces trust in the SDK.
Without dynamic fee estimation, BridgeWise risks misleading quotes and poor UX.

💡 Proposed Solution
Build a Dynamic Fee Estimation Engine that:

Fetches real-time network fees for EVM chains
Estimates liquidity-based fees for AMM/bridge pools
Calculates total route cost including gas + bridge fees
Integrates with ranking, slippage, and status components
Exposes API and hooks for developers
🛠 Scope of Work
1️⃣ Define Fee Data Model
interface FeeEstimate {
bridgeName: string;
sourceChain: string;
destinationChain: string;
totalFee: number; // in native token
gasFee: number; // network-specific
bridgeFee: number; // provider-specific
lastUpdated: Date;
}
Include all components contributing to total cost
Normalized across chains for ranking
2️⃣ Implement Fee Fetching Logic
Fetch gas prices for EVM chains
Fetch bridge-specific fees
Estimate liquidity impact for AMM-based bridges
Update dynamically on quote requests
3️⃣ Integrate With Ranking Engine
Feed dynamic fees into Smart Bridge Ranking (Issue #5)
Ensure real-time adjustments influence route selection
Provide transparency in fee breakdown to UI components
4️⃣ Hooks and API Exposure
useFeeEstimate() hook for React developers
Optional REST endpoint for SDK integrators
Return normalized fee breakdown
SSR-compatible for Next.js
5️⃣ Error Handling & Fallbacks
Provide fallback static fee if dynamic fetch fails
Show warning for high network congestion
Ensure calculations never block UI rendering
📊 Expected Outcome
Accurate, real-time fee estimates for all routes
Improved route selection and ranking
Transparent cost breakdown for users
Reduced failed or underfunded transactions
✅ Acceptance Criteria

Fee data model implemented

Real-time EVM gas price fetching

Bridge-specific fee estimation implemented

Liquidity-based fee calculation included

Integrated with ranking engine

useFeeEstimate() hook available

SSR-safe implementation

Fallback fees provided if dynamic fetch fails

Unit tests for dynamic fee logic

Documentation updated with usage examples
📈 Measurable Impact
Reduced unexpected fees during cross-chain transfers
Increased user trust in BridgeWise quotes
Improved accuracy in Smart Bridge Ranking
Fewer failed or aborted transactions
🧪 Testing Requirements
Simulate varying network congestion
Validate fee breakdown for multiple bridges
Confirm fallback fees are correctly applied
Test hook and REST API outputs
Verify integration with ranking engine
Ensure SSR-safe behavior in Next.js
📚 Documentation Requirements
Add “Dynamic Fee Estimation” section to README
Provide usage examples with hook
Include breakdown explanation in UI
Document fallback behavior and error handling

Closes #62