🔄 Implement Cross-Chain Token Compatibility Validation

[mijinummi]

🧭 Overview

BridgeWise supports multi-chain transfers across Stellar and EVM networks.

To ensure safe and successful transfers, it must validate token compatibility across chains:

• Prevent users from bridging unsupported or non-existent tokens
• Provide clear feedback for incompatible token selections
• Integrate with <BridgeCompare />, useBridgeQuotes(), and transaction execution hooks

This ensures transfers are reliable and reduces failed transactions.

---

🎯 Problem

• Not all tokens exist on both source and destination chains
• Users may attempt unsupported transfers, leading to failed transactions
• Developers embedding BridgeWise have no automated token validation
• Lack of validation increases risk of errors and poor UX

Without compatibility checks, BridgeWise cannot provide a safe, production-ready cross-chain experience.

---

💡 Proposed Solution

Implement a Cross-Chain Token Compatibility Validation Layer that:

• Maintains a token registry per chain and bridge
• Validates token availability before quote calculation or transaction execution
• Returns structured errors/warnings for unsupported token routes
• Provides hooks (useTokenValidation()) for developers
• Supports both UI components and headless mode

---

🛠 Scope of Work

1️⃣ Define Token Registry

interface TokenInfo {
  symbol: string;
  name: string;
  chain: string;
  bridgeSupported: string[];
  decimals: number;
  logoURI?: string;
}

• Centralized token list for supported bridges and chains
• Easily updatable and extendable

---

2️⃣ Implement Validation Logic

• isTokenSupported(token: string, sourceChain: string, destinationChain: string): boolean

• Validate before:

  • Fetching quotes (useBridgeQuotes())
  • Initiating transfers (useBridgeExecution())

• Return structured error messages for UI or headless integration

---

3️⃣ Hook Implementation

• useTokenValidation(token: string, sourceChain: string, destinationChain: string)

  • Returns:

    • isValid: boolean
    • errors: string[]

  • SSR-safe

  • Integrates with <BridgeCompare /> to disable unsupported routes

---

4️⃣ UI Integration

• <BridgeCompare />: highlight or disable unsupported routes
• <BridgeStatus />: prevent execution for incompatible tokens
• Optional tooltip or alert for end-users

---

5️⃣ Error Handling & Fallbacks

• Handle unknown tokens gracefully
• Provide default “unsupported token” warning
• Ensure hooks and UI do not break with invalid input

---

📊 Expected Outcome

• Users cannot attempt unsupported cross-chain transfers
• Developers have a simple API to validate token compatibility
• Reduced failed transactions and errors
• Consistent, safe, production-ready UX across bridges

---

✅ Acceptance Criteria

• Token registry implemented per chain and bridge
• Validation logic functional for all supported routes
• useTokenValidation() hook available and SSR-safe
• Integration with <BridgeCompare /> and <BridgeStatus />
• Structured error messages returned for incompatible tokens
• Unit tests covering validation logic, hook, and UI integration
• Documentation updated with usage examples

---

📈 Measurable Impact

• Fewer failed transfers due to unsupported tokens
• Developers can confidently embed BridgeWise without additional validation logic
• Improved user trust and overall UX
• Reduced support and troubleshooting effort

---

🧪 Testing Requirements

• Test token validation across multiple chains and bridges
• Simulate unsupported tokens and ensure proper error handling
• Validate hook output and UI integration
• Ensure SSR-safe behavior for headless mode
• Test fallback for unknown or invalid token symbols

---

📚 Documentation Requirements

• Add “Token Compatibility Validation” section in README
• Provide hook usage example:

const { isValid, errors } = useTokenValidation("USDC", "Ethereum", "Stellar");

• Document integration with <BridgeCompare /> and <BridgeStatus />
• Include supported token list and update instructions

---

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 150 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[blessme247]

@blessme247 has applied to work on this issue as part of the Stellar Wave Program's 2nd wave.

I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @blessme247 to this issue.