Wallet & Bridge Integration Guide

This document provides a comprehensive overview of how wallet connections and token bridging work in SmartBets, covering all chains, wallets, desktop vs mobile implementations, and the libraries/tools used.

Overview
Supported Chains & Wallets
Libraries & Tools Used
Wallet Connection Matrix
Desktop Wallet Connections
Mobile Wallet Connections
Bridging Overview
Bridge Provider Matrix
Known Issues & Workarounds
Adding New Wallets or Chains
Reference Links

Overview

SmartBets supports three blockchain networks:

Solana - Primary chain for betting (deposits go here)
EVM (Ethereum, Polygon, Arbitrum, Base) - For bridging assets to Solana
Tron - For bridging USDT/USDC to Solana

The application allows users to:

Connect their wallet on any supported chain
Bridge tokens from EVM/Tron to Solana

Supported Chains & Wallets

Solana

Wallet	Desktop	Mobile
Phantom	✅ Extension	✅ Deeplink Protocol
Solflare	✅ Extension	✅ WalletConnect (via Reown)
Trust Wallet	✅ Extension	✅ WalletConnect (via Reown)

EVM (Ethereum, Polygon, etc.)

Wallet	Desktop	Mobile
MetaMask	✅ Extension	✅ WalletConnect
Trust Wallet	✅ Extension	✅ WalletConnect

Tron

Wallet	Desktop	Mobile
TronLink	✅ Extension	❌ Not available
Trust Wallet	✅ Extension (via window.tronWeb)	✅ Custom WalletConnect + Deeplink
BitKeep	✅ Extension	❌ Not tested

Libraries & Tools Used

Solana Wallet Connection

@solana/wallet-adapter-react        - React hooks for wallet state
@solana/wallet-adapter-react-ui     - Pre-built wallet modal UI
@solana/wallet-adapter-wallets      - Wallet adapters (Phantom, Solflare, Trust)
@solana/web3.js                     - Solana JavaScript SDK

EVM Wallet Connection

wagmi                               - React hooks for Ethereum
viem                                - Low-level Ethereum library
@reown/appkit-adapter-wagmi         - Reown (WalletConnect) wagmi adapter

Tron Wallet Connection

@tronweb3/tronwallet-adapter-react-hooks  - React hooks for Tron wallets
@tronweb3/tronwallet-adapters            - Wallet adapters (TronLink, WalletConnect, BitKeep)
@walletconnect/universal-provider        - WalletConnect v2 UniversalProvider
@tronweb3/walletconnect-tron             - Tron-specific WalletConnect utilities

Multi-Chain Integration

@reown/appkit                       - Reown AppKit (formerly WalletConnect Web3Modal)
@reown/appkit-adapter-solana        - Solana adapter for Reown

Bridging

@allbridge/bridge-core-sdk          - Allbridge SDK (Tron mobile → Solana)
deBridge DLN API                    - REST API (EVM/Tron desktop → Solana)
TronGrid API                        - Tron node API for transaction building

Wallet Connection Matrix

How Each Combination Works

Chain	Wallet	Platform	Method	File
Solana	Phantom	Desktop	Browser extension via wallet-adapter	`SolanaChainProvider.tsx`
Solana	Phantom	Mobile	Deeplink protocol with encryption	`phantomDeeplink.ts`
Solana	Solflare	Desktop	Browser extension via wallet-adapter	`SolanaChainProvider.tsx`
Solana	Solflare	Mobile	WalletConnect via Reown AppKit	`ReownWalletContext.tsx`
Solana	Trust	Desktop	Browser extension via wallet-adapter	`SolanaChainProvider.tsx`
Solana	Trust	Mobile	WalletConnect via Reown AppKit	`ReownWalletContext.tsx`
EVM	MetaMask	Desktop	Injected provider via wagmi	`EVMChainProvider.tsx`
EVM	MetaMask	Mobile	WalletConnect via wagmi	`EVMChainProvider.tsx`
EVM	Trust	Desktop	Injected provider via wagmi	`EVMChainProvider.tsx`
EVM	Trust	Mobile	WalletConnect via wagmi	`EVMChainProvider.tsx`
Tron	TronLink	Desktop	`window.tronWeb` injection	`TronChainProvider.tsx`
Tron	Trust	Desktop	`window.tronWeb` (in dApp browser)	`TronChainProvider.tsx`
Tron	Trust	Mobile	Custom WalletConnect + Deeplink	`trustTronDeeplink.ts`

Desktop Wallet Connections

On desktop, wallet connections are straightforward using browser extensions:

Solana (Desktop)

Uses @solana/wallet-adapter-react with adapters for Phantom, Solflare, Trust
Extensions inject window.solana or window.phantom.solana
The wallet modal from @solana/wallet-adapter-react-ui handles wallet selection

EVM (Desktop)

Uses wagmi with injected connector
Extensions inject window.ethereum (or window.ethereum.providers[] for multiple)
Key Challenge: Multiple wallets (MetaMask, Phantom, Coinbase) all set isMetaMask=true
Solution: EVMChainProvider.tsx has getWalletProvider() that identifies the REAL MetaMask by checking for _metamask.isUnlocked method

Tron (Desktop)

TronLink extension injects window.tronWeb
Trust Wallet (in its dApp browser) also injects window.tronWeb
Uses @tronweb3/tronwallet-adapters with TronLinkAdapter

Mobile Wallet Connections

Mobile is more complex because there are no browser extensions. Each chain/wallet combination requires a different approach.

Solana + Phantom (Mobile) - DEEPLINK PROTOCOL

Phantom has its own deeplink protocol that doesn't use WalletConnect. This provides the best mobile UX.

How it works:

App generates an X25519 keypair for encryption (stored in localStorage)
User clicks "Connect Phantom" → App opens https://phantom.app/ul/v1/connect?...
Phantom app opens, user approves → Phantom redirects back to /wallet-callback?action=connect&...
Callback page decrypts response, extracts wallet public key
For signing: App opens https://phantom.app/ul/v1/signMessage?... with encrypted payload
Phantom returns signature via redirect

Key Files:

src/lib/phantomDeeplink.ts - All deeplink URL building and crypto
src/pages/WalletCallback.tsx - Handles all Phantom redirects
src/hooks/usePhantomDeeplink.ts - React hook for Phantom state

Reference: https://docs.phantom.com/phantom-deeplinks/provider-methods

Solana + Other Wallets (Mobile) - REOWN/WALLETCONNECT

For Solflare, Trust Wallet, and other Solana wallets on mobile:

How it works:

User clicks wallet → App opens Reown AppKit modal
Reown generates WalletConnect URI with QR code
On mobile, clicking wallet icon opens deeplink to that wallet app
Wallet app establishes WalletConnect session
Signing requests go through WalletConnect relay

Key Files:

src/contexts/ReownWalletContext.tsx - Reown AppKit setup with SolanaAdapter

EVM + Any Wallet (Mobile) - WALLETCONNECT

All EVM wallet connections on mobile use WalletConnect via wagmi.

How it works:

wagmi's WalletConnect connector generates connection URI
User scans QR or taps to open wallet app
Session established via WalletConnect relay
All signing requests go through WalletConnect

Key Files:

src/contexts/chains/EVMChainProvider.tsx - wagmi setup with WalletConnect connector
src/contexts/ReownWalletContext.tsx - WagmiAdapter for Reown

Tron + Trust Wallet (Mobile) - CUSTOM WALLETCONNECT

This is the most complex integration because:

No standard Tron mobile wallet adapter exists that works reliably
Trust Wallet's WalletConnect support for Tron uses non-standard message formats
The @tronweb3/tronwallet-adapters WalletConnectAdapter doesn't work properly on mobile

Our Custom Solution:

Connection:
- Create WalletConnect UniversalProvider with Tron chain (tron:0x2b6653dc)
- Generate WalletConnect URI
- Build Trust Wallet deeplink: trust://wc?uri={encoded_wc_uri}
- Open deeplink → Trust Wallet opens → User approves
- Session established, address extracted from session namespaces
Signing Transactions:
- Build raw transaction using TronGrid API (since window.tronWeb not available)
- Send tron_signTransaction request via UniversalProvider
- Try both v1 ({address, transaction}) and v2 ({address, transaction: {transaction}}) formats
- Trust Wallet signs and returns signed transaction
Broadcasting:
- Use TronGrid API /wallet/broadcasttransaction endpoint
- Parse TronGrid response (handles various error/success formats)

Key Files:

src/lib/trustTronDeeplink.ts - Custom WalletConnect + deeplink implementation
src/lib/tronGridApi.ts - TronGrid API for transaction building/broadcasting
src/contexts/chains/TronChainProvider.tsx - Integrates custom Trust mobile flow

Known Limitation:

App cannot automatically switch focus to Trust Wallet for signing requests
User must manually open Trust Wallet to see and approve signing prompts
This is a WalletConnect v2 limitation for "already connected" sessions

Bridging Overview

SmartBets supports bridging tokens FROM EVM/Tron chains TO Solana. The destination is always Solana (where betting happens).

Why Two Bridge Providers?

deBridge DLN: Works great for EVM chains and Tron on desktop
Allbridge Core: Required for Tron on mobile because deBridge transactions don't work with WalletConnect-signed transactions

Bridge Provider Matrix

Source Chain	Platform	Bridge Provider	Why
EVM (ETH, Polygon, etc.)	Desktop	deBridge DLN	Best liquidity, fast
EVM	Mobile	deBridge DLN	Works with WalletConnect
Tron	Desktop	deBridge DLN	Works with TronLink/window.tronWeb
Tron	Mobile	Allbridge Core	deBridge tx format incompatible with Trust WalletConnect

deBridge DLN (EVM & Tron Desktop)

How it works:

Call deBridge API: GET /dln/order/create-tx with source/dest chain, token, amount
API returns: estimated output, fees, and ready-to-sign transaction data
For EVM: Use wagmi's useSendTransaction to sign and broadcast
For Tron: Use tronWeb.transactionBuilder.triggerSmartContract + TronLink signing

Key File: src/lib/debridge.ts

API Docs: https://docs.debridge.finance/

Allbridge Core (Tron Mobile)

Why Allbridge for Tron Mobile? deBridge returns transaction data that requires calling triggerSmartContract with specific parameters. When using Trust Wallet via WalletConnect, we can't use window.tronWeb - we can only sign raw transactions. The Allbridge SDK provides a rawTxBuilder that returns transactions in a format compatible with Trust Wallet's tron_signTransaction method.

How it works:

Initialize Allbridge SDK
Get quote: sdk.getAmountToBeReceived(amount, sourceToken, destToken)
Check allowance: sdk.bridge.checkAllowance(token, owner)
If needed, build approval tx: sdk.bridge.rawTxBuilder.approve({token, owner})
Build bridge tx: sdk.bridge.rawTxBuilder.send({...})
Sign via Trust WalletConnect (tron_signTransaction)
Broadcast via TronGrid API

Key File: src/lib/allbridge.ts

API Docs: https://docs.allbridge.io/

Known Issues & Workarounds

1. Multiple Wallets Claiming to be MetaMask

Problem: Phantom, Coinbase, Trust all set isMetaMask=true on their EVM providers. Solution: Check for MetaMask's unique _metamask.isUnlocked function. File: src/contexts/chains/EVMChainProvider.tsx → getWalletProvider()

2. Trust Wallet Tron Mobile - No Standard Adapter

Problem: @tronweb3/tronwallet-adapters WalletConnectAdapter doesn't work on mobile. Solution: Custom implementation using UniversalProvider + deeplinks. File: src/lib/trustTronDeeplink.ts

3. Trust Wallet Tron - Transaction Format Variants

Problem: Trust Wallet accepts different JSON formats for tron_signTransaction. Solution: Try both v1 and v2 formats, use whichever succeeds. File: src/lib/trustTronDeeplink.ts → signTronTransactionViaTrust()

4. deBridge Tron - `input` vs `functionSelector`

Problem: TronWeb's triggerSmartContract sometimes modifies transaction data. Solution: Use empty functionSelector with input containing full calldata. File: src/pages/Bridge.tsx → handleBridgeTronDesktop()

5. TronGrid Broadcast - Variable Response Formats

Problem: TronGrid API returns success/error in multiple different formats. Solution: Parse all known response structures, decode hex error messages. File: src/lib/tronGridApi.ts → broadcastTransaction()

6. Phantom Deeplink - Domain Consistency

Problem: forsyt.io redirects to www.forsyt.io, causing localStorage mismatch. Solution: Always use www.forsyt.io as canonical URL for Phantom redirects. File: src/lib/phantomDeeplink.ts → CANONICAL_BASE_URL

7. WalletConnect Session Reconnection

Problem: Wallets auto-reconnect on page load, causing unexpected popups. Solution: Disable enableReconnect in Reown AppKit configuration. File: src/contexts/ReownWalletContext.tsx

8. Mobile App Switching for Signing

Problem: WalletConnect doesn't auto-switch to wallet app for signing requests. Workaround: Attempted trust://wc deeplink trigger (doesn't work reliably). Status: User must manually switch to wallet app to approve signing requests.

Adding New Wallets or Chains

Adding a New Solana Wallet

Check if wallet has an adapter in @solana/wallet-adapter-wallets

Add adapter to SolanaChainProvider.tsx:

import { NewWalletAdapter } from '@solana/wallet-adapter-wallets';
const wallets = [new PhantomWalletAdapter(), new NewWalletAdapter()];

If mobile support needed with WalletConnect, add to Reown's SolanaAdapter too

Adding a New EVM Wallet

Most EVM wallets work automatically via window.ethereum
If wallet needs special identification, update getWalletProvider() in EVMChainProvider.tsx
Add wallet type to ConnectorType type if needed

Adding a New EVM Chain

Add chain to evmNetworks array in ReownWalletContext.tsx
Add chain ID mapping to DEBRIDGE_CHAIN_IDS in debridge.ts
Add token addresses for that chain in TOKEN_ADDRESSES

Adding a New Tron Wallet (Desktop)

Check @tronweb3/tronwallet-adapters for available adapters
Add adapter to TronChainProvider.tsx adapters array
Test both connection and signing

Adding a New Tron Wallet (Mobile)

This is complex. You'll likely need to:

Create a custom WalletConnect implementation (see trustTronDeeplink.ts)
Figure out the wallet's deeplink format for opening WalletConnect URIs
Test the tron_signTransaction message format the wallet expects
Handle signing and broadcasting manually

Reference Links

Phantom Deeplinks

Trust Wallet

https://developer.trustwallet.com/developer/develop-for-trust/deeplinking
Deeplink format: trust://wc?uri={encoded_walletconnect_uri}

WalletConnect

https://docs.walletconnect.com/
Project ID required: Get from https://cloud.walletconnect.com/

Reown (formerly Web3Modal/WalletConnect)

https://docs.reown.com/
Provides unified modal for wallet selection

deBridge

https://docs.debridge.finance/
DLN API: https://dln.debridge.finance/v1.0/

Allbridge

Tron

TronWeb: https://tronweb.network/docu/
TronGrid API: https://www.trongrid.io/
Tron address format: Base58 (T...) or Hex (41...)

Solana Wallet Adapter

https://github.com/solana-labs/wallet-adapter

Wagmi (EVM)

https://wagmi.sh/

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                           ConnectWallet.tsx                          │
│                     (Entry point for all connections)                │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                ┌───────────────────┼───────────────────┐
                ▼                   ▼                   ▼
┌──────────────────────┐ ┌──────────────────┐ ┌──────────────────────┐
│  SolanaChainProvider │ │  EVMChainProvider │ │  TronChainProvider   │
│  (wallet-adapter)    │ │  (wagmi)          │ │  (tronwallet-adapter)│
└──────────────────────┘ └──────────────────┘ └──────────────────────┘
         │                        │                       │
         ▼                        ▼                       ▼
┌──────────────────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ Desktop: Extensions  │ │ Desktop: window. │ │ Desktop: window.     │
│ Mobile: Phantom deep-│ │         ethereum │ │         tronWeb      │
│ link OR Reown/WC     │ │ Mobile: WC/Reown │ │ Mobile: Custom WC    │
└──────────────────────┘ └──────────────────┘ │ (trustTronDeeplink)  │
                                              └──────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                            Bridge.tsx                                │
│                    (Entry point for all bridging)                    │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
        ┌──────────────────────┐       ┌──────────────────────┐
        │  deBridge DLN API    │       │  Allbridge Core SDK  │
        │  (EVM + Tron Desktop)│       │  (Tron Mobile only)  │
        └──────────────────────┘       └──────────────────────┘
                    │                               │
                    ▼                               ▼
        ┌──────────────────────┐       ┌──────────────────────┐
        │  EVM: wagmi send     │       │  Trust WalletConnect │
        │  Tron: tronWeb sign  │       │  tron_signTransaction│
        └──────────────────────┘       └──────────────────────┘
                                                    │
                                                    ▼
                                       ┌──────────────────────┐
                                       │  TronGrid broadcast  │
                                       └──────────────────────┘

Summary

Scenario	Solution	Complexity
Solana + Phantom Desktop	Wallet Adapter extension	Simple
Solana + Phantom Mobile	Custom deeplink protocol	Medium
Solana + Other Wallets	Reown AppKit + WalletConnect	Simple
EVM + Any Wallet Desktop	Wagmi injected provider	Simple
EVM + Any Wallet Mobile	Wagmi WalletConnect	Simple
Tron + TronLink Desktop	TronWallet Adapter	Simple
Tron + Trust Desktop	window.tronWeb (in dApp browser)	Simple
Tron + Trust Mobile	Custom WalletConnect + TronGrid	Complex
Bridge EVM → Solana	deBridge DLN API	Medium
Bridge Tron Desktop → Solana	deBridge DLN API	Medium
Bridge Tron Mobile → Solana	Allbridge Core SDK	Complex

Table of Contents​

Overview​

Supported Chains & Wallets​

Solana​

EVM (Ethereum, Polygon, etc.)​

Tron​

Libraries & Tools Used​

Solana Wallet Connection​

EVM Wallet Connection​

Tron Wallet Connection​

Multi-Chain Integration​

Bridging​

Wallet Connection Matrix​

How Each Combination Works​

Desktop Wallet Connections​

Solana (Desktop)​

EVM (Desktop)​

Tron (Desktop)​

Mobile Wallet Connections​

Solana + Phantom (Mobile) - DEEPLINK PROTOCOL​

Solana + Other Wallets (Mobile) - REOWN/WALLETCONNECT​

EVM + Any Wallet (Mobile) - WALLETCONNECT​

Tron + Trust Wallet (Mobile) - CUSTOM WALLETCONNECT​

Bridging Overview​

Bridge Provider Matrix​

deBridge DLN (EVM & Tron Desktop)​

Allbridge Core (Tron Mobile)​

Known Issues & Workarounds​

1. Multiple Wallets Claiming to be MetaMask​

2. Trust Wallet Tron Mobile - No Standard Adapter​

3. Trust Wallet Tron - Transaction Format Variants​

4. deBridge Tron - input vs functionSelector​

5. TronGrid Broadcast - Variable Response Formats​

6. Phantom Deeplink - Domain Consistency​

7. WalletConnect Session Reconnection​

8. Mobile App Switching for Signing​

Adding New Wallets or Chains​

Adding a New Solana Wallet​

Adding a New EVM Wallet​

Adding a New EVM Chain​

Adding a New Tron Wallet (Desktop)​

Adding a New Tron Wallet (Mobile)​

Reference Links​

Phantom Deeplinks​

Trust Wallet​

WalletConnect​

Reown (formerly Web3Modal/WalletConnect)​

deBridge​

Allbridge​

Tron​

Solana Wallet Adapter​

Wagmi (EVM)​

Architecture Diagram​

Summary​

Table of Contents

Overview

Supported Chains & Wallets

Solana

EVM (Ethereum, Polygon, etc.)

Tron

Libraries & Tools Used

Solana Wallet Connection

EVM Wallet Connection

Tron Wallet Connection

Multi-Chain Integration

Bridging

Wallet Connection Matrix

How Each Combination Works

Desktop Wallet Connections

Solana (Desktop)

EVM (Desktop)

Tron (Desktop)

Mobile Wallet Connections

Solana + Phantom (Mobile) - DEEPLINK PROTOCOL

Solana + Other Wallets (Mobile) - REOWN/WALLETCONNECT

EVM + Any Wallet (Mobile) - WALLETCONNECT

Tron + Trust Wallet (Mobile) - CUSTOM WALLETCONNECT

Bridging Overview

Bridge Provider Matrix

deBridge DLN (EVM & Tron Desktop)

Allbridge Core (Tron Mobile)

Known Issues & Workarounds

1. Multiple Wallets Claiming to be MetaMask

2. Trust Wallet Tron Mobile - No Standard Adapter

3. Trust Wallet Tron - Transaction Format Variants

4. deBridge Tron - `input` vs `functionSelector`

5. TronGrid Broadcast - Variable Response Formats

6. Phantom Deeplink - Domain Consistency

7. WalletConnect Session Reconnection

8. Mobile App Switching for Signing

Adding New Wallets or Chains

Adding a New Solana Wallet

Adding a New EVM Wallet

Adding a New EVM Chain

Adding a New Tron Wallet (Desktop)

Adding a New Tron Wallet (Mobile)

Reference Links

Phantom Deeplinks

Trust Wallet

WalletConnect

Reown (formerly Web3Modal/WalletConnect)

deBridge

Allbridge

Tron

Solana Wallet Adapter

Wagmi (EVM)

Architecture Diagram

Summary