Common Types and Interfaces

/**
 * Interface representing a Web3 account with address, name, avatar, and connection status
 */
interface Account {
  address: string;
  name?: string;
  avatar?: string;
  addresses?: [`0x${string}`, ...`0x${string}`[]] | readonly `0x${string}`[];
  status?: ConnectStatus;
}

const enum ConnectStatus {
  Connected = 'connected',
  Disconnected = 'disconnected',
  Signed = 'signed',
}

/**
 * Interface representing a blockchain network with metadata and browser integration
 */
interface Chain {
  id: ChainIds | number;
  name: string;
  type?: ChainType;
  icon?: React.ReactNode;
  browser?: {
    icon?: React.ReactNode;
    getBrowserLink?: (address: string, type: BrowserLinkType) => string;
  };
  nativeCurrency?: BalanceMetadata & {
    name: string;
  };
}

enum ChainType {
  EVM = 'EVM',
  SVM = 'SVM',
  Bitcoin = 'Bitcoin',
  Sui = 'Sui',
}

type BrowserLinkType = 'address' | 'transaction';

/**
 * Interface extending WalletMetadata with wallet connection capabilities
 */
interface Wallet extends WalletMetadata {
  _standardWallet?: any;
  _isMobileWallet?: boolean;
  hasWalletReady?: () => Promise<boolean>;
  hasExtensionInstalled?: () => Promise<boolean>;
  getQrCode?: () => Promise<{ uri: string }>;
  customQrCodePanel?: boolean;
}

/**
 * Type defining wallet metadata including name, icon, extensions, and universal protocol support
 */
type WalletMetadata = {
  name: string;
  remark: string;
  key?: React.Key;
  icon?: string | React.ReactNode;
  extensions?: false | WalletExtensionItem[];
  app?: false | { link: string };
  group?: string;
  universalProtocol?: { link: string };
  supportChainTypes?: ChainType[];
  transferQRCodeFormatter?: (params: Record<string, any>) => string;
  deeplink?: { urlTemplate: string };
};

interface WalletExtensionItem {
  key: string;
  browserIcon: string;
  browserName: string;
  link: string;
  description: string;
}

/**
 * Type representing a token with its metadata and supported chains
 */
type Token = {
  name: string;
  symbol: string;
  icon: React.ReactNode;
  decimal: number;
  availableChains: Array<{
    chain: Chain;
    contract?: string;
  }>;
};

/**
 * Interface representing NFT metadata structure
 */
interface NFTMetadata {
  name?: string;
  description?: string;
  image?: string;
  dna?: string;
  edition?: string | number;
  date?: number;
  attributes?: Array<{
    trait_type?: string;
    value?: string;
  }>;
  compiler?: string;
}

/**
 * Type representing account balance with optional value and cover address flag
 */
type Balance = BalanceMetadata & {
  value?: bigint;
  coverAddress?: boolean;
};

interface BalanceMetadata {
  name?: string;
  symbol?: string;
  icon?: React.ReactNode;
  decimal?: number;
}

/**
 * Enum containing chain IDs for various Ethereum-compatible networks
 */
enum ChainIds {
  Mainnet = 1,
  Polygon = 137,
  BSC = 56,
  Arbitrum = 42_161,
  Optimism = 10,
  Goerli = 5,
  Avalanche = 43_114,
  X1Testnet = 195,
  Sepolia = 11_155_111,
  Holesky = 17_000,
  Scroll = 534_352,
  ScrollSepolia = 534_351,
  Hardhat = 31_337,
  Localhost = 1_337,
  Base = 8453,
}

/**
 * Enum for Solana chain IDs
 */
enum SolanaChainIds {
  MainnetBeta = 2,
  Devnet = 3,
  Testnet = 4,
}

/**
 * Enum for Sui chain IDs
 */
enum SuiChainIds {
  Mainnet = 1,
  Testnet = 2,
  Devnet = 3,
  Localnet = 4,
}

/**
 * Core interface defining the Web3 provider capabilities
 */
interface UniversalWeb3ProviderInterface {
  account?: Account;
  chain?: Chain;
  balance?: Balance;
  availableWallets?: Wallet[];
  availableChains?: Chain[];
  extendsContextFromParent?: boolean;
  addressPrefix?: string | false;
  connect?: (wallet?: Wallet, options?: ConnectOptions) => Promise<void | Account>;
  disconnect?: () => Promise<void>;
  switchChain?: (chain: Chain) => Promise<void>;
  getNFTMetadata?: (params: { address: string; tokenId?: bigint }) => Promise<NFTMetadata>;
  sign?: SignConfig;
}

interface ConnectOptions {
  connectType?: 'extension' | 'qrCode' | 'openMobile';
}

interface SignConfig {
  signIn: (address: string) => Promise<void>;
  signOut?: () => Promise<void>;
}

/**
 * Partial locale interface allowing customization of component text
 */
interface Locale {
  ConnectButton?: Partial<RequiredLocale['ConnectButton']>;
  ConnectModal?: Partial<RequiredLocale['ConnectModal']>;
  NFTCard?: Partial<RequiredLocale['NFTCard']>;
  Address?: Partial<RequiredLocale['Address']>;
  TokenSelect?: Partial<RequiredLocale['TokenSelect']>;
  CryptoInput?: Partial<RequiredLocale['CryptoInput']>;
  PayPanel?: Partial<RequiredLocale['PayPanel']>;
}

/**
 * Complete locale interface containing all required localized strings
 */
interface RequiredLocale {
  ConnectButton: {
    connect: string;
    disconnect: string;
    copyAddress: string;
    copied: string;
    disconnected: string;
    walletAddress: string;
  };
  ConnectModal: {
    title: string;
    walletGuideTitle: string;
    walletGuideInfos: Array<{
      title: string;
      description: string;
    }>;
    qrCodePanelTitle: string;
    qrCodePanelTip: string;
    qrCodePanelConnecting: string;
    qrCodePanelConnectingTip: string;
  };
  NFTCard: {
    actionText: string;
  };
  Address: {
    copied: string;
    copy: string;
  };
  TokenSelect: {
    placeholder: string;
  };
  CryptoInput: {
    placeholder: string;
    max: string;
  };
  PayPanel: {
    generalTips: string;
  };
}

/**
 * Ensures address starts with '0x' prefix
 */
function fillAddressWith0x(address: string): `0x${string}`;

/**
 * Converts number to bigint safely
 */
function parseNumberToBigint(num?: number | bigint): bigint | undefined;

/**
 * Creates a function to generate blockchain explorer links
 */
function createGetBrowserLink(url: string): (address: string, type: string) => string;

/**
 * Converts IPFS URLs to HTTP URLs for asset loading
 */
function getWeb3AssetUrl(url?: string): string | undefined;

/**
 * Fetches and parses JSON from Web3 asset URLs
 */
async function requestWeb3Asset<T = any>(url: string): Promise<T>;

/**
 * Props for the Web3ConfigProvider component
 */
interface Web3ConfigProviderProps extends UniversalWeb3ProviderInterface {
  children?: React.ReactNode;
  locale?: Locale;
}

/**
 * Configuration consumer props extending provider interface
 */
interface ConfigConsumerProps extends UniversalWeb3ProviderInterface {
  locale?: Locale;
}

/**
 * Base props interface for components that trigger wallet connections
 */
interface ConnectorTriggerProps {
  account?: Account;
  loading?: boolean;
  onConnectClick?: (wallet?: Wallet) => void;
  onDisconnectClick?: () => void;
  onSwitchChain?: (chain: Chain) => Promise<void>;
  availableChains?: Chain[];
  availableWallets?: Wallet[];
  chain?: Chain;
  balance?: Balance;
}

/**
 * Default English locale with complete translations for all components
 */
const en_US: RequiredLocale;

/**
 * Chinese locale with complete translations for all components
 */
const zh_CN: RequiredLocale;

/**
 * Default locale (English) exported as the fallback
 */
const defaultLocale: RequiredLocale;

import type { 
  Account, 
  Chain, 
  Wallet, 
  Token, 
  UniversalWeb3ProviderInterface 
} from "@ant-design/web3";

// Type-safe account configuration
const userAccount: Account = {
  address: "0x1234567890abcdef1234567890abcdef12345678",
  name: "John Doe",
  status: ConnectStatus.Connected,
  addresses: ["0x1234567890abcdef1234567890abcdef12345678"]
};

// Type-safe chain configuration
const ethereumChain: Chain = {
  id: ChainIds.Mainnet,
  name: "Ethereum Mainnet",
  type: ChainType.EVM,
  nativeCurrency: {
    name: "Ether",
    symbol: "ETH",
    decimal: 18
  },
  browser: {
    getBrowserLink: (address, type) => 
      `https://etherscan.io/${type}/${address}`
  }
};

// Type-safe wallet configuration
const metaMaskWallet: Wallet = {
  name: "MetaMask",
  remark: "Connect using MetaMask browser extension",
  icon: "metamask-icon.svg",
  extensions: [{
    key: 'Chrome',
    browserIcon: 'chrome-icon.svg',
    browserName: 'Chrome',
    link: 'https://chrome.google.com/webstore/detail/metamask',
    description: 'MetaMask extension for Chrome'
  }],
  supportChainTypes: [ChainType.EVM]
};

// Type-safe token configuration
const usdcToken: Token = {
  name: "USD Coin",
  symbol: "USDC",
  icon: <USDCIcon />,
  decimal: 6,
  availableChains: [
    { chain: ethereumChain, contract: "0xA0b86a33E6441946E6f8443e0b802C7e8b5B0B3A" },
    { chain: polygonChain, contract: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174" }
  ]
};

// Type-safe provider configuration
const web3Config: UniversalWeb3ProviderInterface = {
  account: userAccount,
  chain: ethereumChain,
  availableWallets: [metaMaskWallet],
  availableChains: [ethereumChain, polygonChain],
  addressPrefix: "0x",
  connect: async (wallet, options) => {
    // Connection implementation
    return userAccount;
  },
  disconnect: async () => {
    // Disconnection implementation
  },
  switchChain: async (chain) => {
    // Chain switching implementation
  }
};

// Type guard functions for runtime validation
function isValidAccount(obj: any): obj is Account {
  return typeof obj === 'object' && 
         typeof obj.address === 'string' &&
         obj.address.startsWith('0x') &&
         obj.address.length === 42;
}

function isEVMChain(chain: Chain): boolean {
  return chain.type === ChainType.EVM;
}

function isSolanaChain(chain: Chain): boolean {
  return chain.type === ChainType.SVM;
}

// Usage in components
function validateAndUseAccount(account: unknown) {
  if (isValidAccount(account)) {
    // TypeScript knows account is Account type here
    console.log('Valid account:', account.address);
    return account;
  }
  throw new Error('Invalid account format');
}