0
# Common Types and Interfaces
1

2
Core type definitions from @ant-design/web3-common including Account, Chain, Wallet, Token, and NFTMetadata interfaces that form the foundation of the Web3 component library.
3

4
## Core Interfaces
5

6
### Account
7

8
Interface representing a Web3 account with address, name, avatar, and connection status.
9

10
```typescript { .api }
11
/**
12
 * Interface representing a Web3 account with address, name, avatar, and connection status
13
 */
14
interface Account {
15
  address: string;
16
  name?: string;
17
  avatar?: string;
18
  addresses?: [`0x${string}`, ...`0x${string}`[]] | readonly `0x${string}`[];
19
  status?: ConnectStatus;
20
}
21

22
const enum ConnectStatus {
23
  Connected = 'connected',
24
  Disconnected = 'disconnected',
25
  Signed = 'signed',
26
}
27
```
28

29
### Chain
30

31
Interface representing a blockchain network with metadata and browser integration capabilities.
32

33
```typescript { .api }
34
/**
35
 * Interface representing a blockchain network with metadata and browser integration
36
 */
37
interface Chain {
38
  id: ChainIds | number;
39
  name: string;
40
  type?: ChainType;
41
  icon?: React.ReactNode;
42
  browser?: {
43
    icon?: React.ReactNode;
44
    getBrowserLink?: (address: string, type: BrowserLinkType) => string;
45
  };
46
  nativeCurrency?: BalanceMetadata & {
47
    name: string;
48
  };
49
}
50

51
enum ChainType {
52
  EVM = 'EVM',
53
  SVM = 'SVM',
54
  Bitcoin = 'Bitcoin',
55
  Sui = 'Sui',
56
}
57

58
type BrowserLinkType = 'address' | 'transaction';
59
```
60

61
### Wallet and WalletMetadata
62

63
Interface for wallet configuration and metadata including extensions, protocols, and capabilities.
64

65
```typescript { .api }
66
/**
67
 * Interface extending WalletMetadata with wallet connection capabilities
68
 */
69
interface Wallet extends WalletMetadata {
70
  _standardWallet?: any;
71
  _isMobileWallet?: boolean;
72
  hasWalletReady?: () => Promise<boolean>;
73
  hasExtensionInstalled?: () => Promise<boolean>;
74
  getQrCode?: () => Promise<{ uri: string }>;
75
  customQrCodePanel?: boolean;
76
}
77

78
/**
79
 * Type defining wallet metadata including name, icon, extensions, and universal protocol support
80
 */
81
type WalletMetadata = {
82
  name: string;
83
  remark: string;
84
  key?: React.Key;
85
  icon?: string | React.ReactNode;
86
  extensions?: false | WalletExtensionItem[];
87
  app?: false | { link: string };
88
  group?: string;
89
  universalProtocol?: { link: string };
90
  supportChainTypes?: ChainType[];
91
  transferQRCodeFormatter?: (params: Record<string, any>) => string;
92
  deeplink?: { urlTemplate: string };
93
};
94

95
interface WalletExtensionItem {
96
  key: string;
97
  browserIcon: string;
98
  browserName: string;
99
  link: string;
100
  description: string;
101
}
102
```
103

104
### Token
105

106
Type representing a token with its metadata and supported chains.
107

108
```typescript { .api }
109
/**
110
 * Type representing a token with its metadata and supported chains
111
 */
112
type Token = {
113
  name: string;
114
  symbol: string;
115
  icon: React.ReactNode;
116
  decimal: number;
117
  availableChains: Array<{
118
    chain: Chain;
119
    contract?: string;
120
  }>;
121
};
122
```
123

124
### NFTMetadata
125

126
Interface representing NFT metadata structure including attributes and compiler information.
127

128
```typescript { .api }
129
/**
130
 * Interface representing NFT metadata structure
131
 */
132
interface NFTMetadata {
133
  name?: string;
134
  description?: string;
135
  image?: string;
136
  dna?: string;
137
  edition?: string | number;
138
  date?: number;
139
  attributes?: Array<{
140
    trait_type?: string;
141
    value?: string;
142
  }>;
143
  compiler?: string;
144
}
145
```
146

147
### Balance and BalanceMetadata
148

149
Type representing account balance with optional value and metadata.
150

151
```typescript { .api }
152
/**
153
 * Type representing account balance with optional value and cover address flag
154
 */
155
type Balance = BalanceMetadata & {
156
  value?: bigint;
157
  coverAddress?: boolean;
158
};
159

160
interface BalanceMetadata {
161
  name?: string;
162
  symbol?: string;
163
  icon?: React.ReactNode;
164
  decimal?: number;
165
}
166
```
167

168
## Chain Identifiers
169

170
### Ethereum Compatible Chain IDs
171

172
```typescript { .api }
173
/**
174
 * Enum containing chain IDs for various Ethereum-compatible networks
175
 */
176
enum ChainIds {
177
  Mainnet = 1,
178
  Polygon = 137,
179
  BSC = 56,
180
  Arbitrum = 42_161,
181
  Optimism = 10,
182
  Goerli = 5,
183
  Avalanche = 43_114,
184
  X1Testnet = 195,
185
  Sepolia = 11_155_111,
186
  Holesky = 17_000,
187
  Scroll = 534_352,
188
  ScrollSepolia = 534_351,
189
  Hardhat = 31_337,
190
  Localhost = 1_337,
191
  Base = 8453,
192
}
193
```
194

195
### Solana Chain IDs
196

197
```typescript { .api }
198
/**
199
 * Enum for Solana chain IDs
200
 */
201
enum SolanaChainIds {
202
  MainnetBeta = 2,
203
  Devnet = 3,
204
  Testnet = 4,
205
}
206
```
207

208
### Sui Chain IDs
209

210
```typescript { .api }
211
/**
212
 * Enum for Sui chain IDs
213
 */
214
enum SuiChainIds {
215
  Mainnet = 1,
216
  Testnet = 2,
217
  Devnet = 3,
218
  Localnet = 4,
219
}
220
```
221

222
## Provider Interface
223

224
### UniversalWeb3ProviderInterface
225

226
Core interface defining the Web3 provider capabilities including wallet connection, chain switching, and NFT metadata retrieval.
227

228
```typescript { .api }
229
/**
230
 * Core interface defining the Web3 provider capabilities
231
 */
232
interface UniversalWeb3ProviderInterface {
233
  account?: Account;
234
  chain?: Chain;
235
  balance?: Balance;
236
  availableWallets?: Wallet[];
237
  availableChains?: Chain[];
238
  extendsContextFromParent?: boolean;
239
  addressPrefix?: string | false;
240
  connect?: (wallet?: Wallet, options?: ConnectOptions) => Promise<void | Account>;
241
  disconnect?: () => Promise<void>;
242
  switchChain?: (chain: Chain) => Promise<void>;
243
  getNFTMetadata?: (params: { address: string; tokenId?: bigint }) => Promise<NFTMetadata>;
244
  sign?: SignConfig;
245
}
246

247
interface ConnectOptions {
248
  connectType?: 'extension' | 'qrCode' | 'openMobile';
249
}
250

251
interface SignConfig {
252
  signIn: (address: string) => Promise<void>;
253
  signOut?: () => Promise<void>;
254
}
255
```
256

257
## Localization Types
258

259
### Locale Interfaces
260

261
```typescript { .api }
262
/**
263
 * Partial locale interface allowing customization of component text
264
 */
265
interface Locale {
266
  ConnectButton?: Partial<RequiredLocale['ConnectButton']>;
267
  ConnectModal?: Partial<RequiredLocale['ConnectModal']>;
268
  NFTCard?: Partial<RequiredLocale['NFTCard']>;
269
  Address?: Partial<RequiredLocale['Address']>;
270
  TokenSelect?: Partial<RequiredLocale['TokenSelect']>;
271
  CryptoInput?: Partial<RequiredLocale['CryptoInput']>;
272
  PayPanel?: Partial<RequiredLocale['PayPanel']>;
273
}
274

275
/**
276
 * Complete locale interface containing all required localized strings
277
 */
278
interface RequiredLocale {
279
  ConnectButton: {
280
    connect: string;
281
    disconnect: string;
282
    copyAddress: string;
283
    copied: string;
284
    disconnected: string;
285
    walletAddress: string;
286
  };
287
  ConnectModal: {
288
    title: string;
289
    walletGuideTitle: string;
290
    walletGuideInfos: Array<{
291
      title: string;
292
      description: string;
293
    }>;
294
    qrCodePanelTitle: string;
295
    qrCodePanelTip: string;
296
    qrCodePanelConnecting: string;
297
    qrCodePanelConnectingTip: string;
298
  };
299
  NFTCard: {
300
    actionText: string;
301
  };
302
  Address: {
303
    copied: string;
304
    copy: string;
305
  };
306
  TokenSelect: {
307
    placeholder: string;
308
  };
309
  CryptoInput: {
310
    placeholder: string;
311
    max: string;
312
  };
313
  PayPanel: {
314
    generalTips: string;
315
  };
316
}
317
```
318

319
## Utility Functions
320

321
### Format Utilities
322

323
```typescript { .api }
324
/**
325
 * Ensures address starts with '0x' prefix
326
 */
327
function fillAddressWith0x(address: string): `0x${string}`;
328

329
/**
330
 * Converts number to bigint safely
331
 */
332
function parseNumberToBigint(num?: number | bigint): bigint | undefined;
333

334
/**
335
 * Creates a function to generate blockchain explorer links
336
 */
337
function createGetBrowserLink(url: string): (address: string, type: string) => string;
338
```
339

340
### Web3 Asset Utilities
341

342
```typescript { .api }
343
/**
344
 * Converts IPFS URLs to HTTP URLs for asset loading
345
 */
346
function getWeb3AssetUrl(url?: string): string | undefined;
347

348
/**
349
 * Fetches and parses JSON from Web3 asset URLs
350
 */
351
async function requestWeb3Asset<T = any>(url: string): Promise<T>;
352
```
353

354
## Configuration Types
355

356
### Context Configuration
357

358
```typescript { .api }
359
/**
360
 * Props for the Web3ConfigProvider component
361
 */
362
interface Web3ConfigProviderProps extends UniversalWeb3ProviderInterface {
363
  children?: React.ReactNode;
364
  locale?: Locale;
365
}
366

367
/**
368
 * Configuration consumer props extending provider interface
369
 */
370
interface ConfigConsumerProps extends UniversalWeb3ProviderInterface {
371
  locale?: Locale;
372
}
373
```
374

375
### Component Props Base Types
376

377
```typescript { .api }
378
/**
379
 * Base props interface for components that trigger wallet connections
380
 */
381
interface ConnectorTriggerProps {
382
  account?: Account;
383
  loading?: boolean;
384
  onConnectClick?: (wallet?: Wallet) => void;
385
  onDisconnectClick?: () => void;
386
  onSwitchChain?: (chain: Chain) => Promise<void>;
387
  availableChains?: Chain[];
388
  availableWallets?: Wallet[];
389
  chain?: Chain;
390
  balance?: Balance;
391
}
392
```
393

394
## Built-in Locales
395

396
### Default Locales
397

398
```typescript { .api }
399
/**
400
 * Default English locale with complete translations for all components
401
 */
402
const en_US: RequiredLocale;
403

404
/**
405
 * Chinese locale with complete translations for all components
406
 */
407
const zh_CN: RequiredLocale;
408

409
/**
410
 * Default locale (English) exported as the fallback
411
 */
412
const defaultLocale: RequiredLocale;
413
```
414

415
## Usage Examples
416

417
### Type-Safe Configuration
418

419
```typescript
420
import type { 
421
  Account, 
422
  Chain, 
423
  Wallet, 
424
  Token, 
425
  UniversalWeb3ProviderInterface 
426
} from "@ant-design/web3";
427

428
// Type-safe account configuration
429
const userAccount: Account = {
430
  address: "0x1234567890abcdef1234567890abcdef12345678",
431
  name: "John Doe",
432
  status: ConnectStatus.Connected,
433
  addresses: ["0x1234567890abcdef1234567890abcdef12345678"]
434
};
435

436
// Type-safe chain configuration
437
const ethereumChain: Chain = {
438
  id: ChainIds.Mainnet,
439
  name: "Ethereum Mainnet",
440
  type: ChainType.EVM,
441
  nativeCurrency: {
442
    name: "Ether",
443
    symbol: "ETH",
444
    decimal: 18
445
  },
446
  browser: {
447
    getBrowserLink: (address, type) => 
448
      `https://etherscan.io/${type}/${address}`
449
  }
450
};
451

452
// Type-safe wallet configuration
453
const metaMaskWallet: Wallet = {
454
  name: "MetaMask",
455
  remark: "Connect using MetaMask browser extension",
456
  icon: "metamask-icon.svg",
457
  extensions: [{
458
    key: 'Chrome',
459
    browserIcon: 'chrome-icon.svg',
460
    browserName: 'Chrome',
461
    link: 'https://chrome.google.com/webstore/detail/metamask',
462
    description: 'MetaMask extension for Chrome'
463
  }],
464
  supportChainTypes: [ChainType.EVM]
465
};
466

467
// Type-safe token configuration
468
const usdcToken: Token = {
469
  name: "USD Coin",
470
  symbol: "USDC",
471
  icon: <USDCIcon />,
472
  decimal: 6,
473
  availableChains: [
474
    { chain: ethereumChain, contract: "0xA0b86a33E6441946E6f8443e0b802C7e8b5B0B3A" },
475
    { chain: polygonChain, contract: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174" }
476
  ]
477
};
478

479
// Type-safe provider configuration
480
const web3Config: UniversalWeb3ProviderInterface = {
481
  account: userAccount,
482
  chain: ethereumChain,
483
  availableWallets: [metaMaskWallet],
484
  availableChains: [ethereumChain, polygonChain],
485
  addressPrefix: "0x",
486
  connect: async (wallet, options) => {
487
    // Connection implementation
488
    return userAccount;
489
  },
490
  disconnect: async () => {
491
    // Disconnection implementation
492
  },
493
  switchChain: async (chain) => {
494
    // Chain switching implementation
495
  }
496
};
497
```
498

499
### Type Guards and Validation
500

501
```typescript
502
// Type guard functions for runtime validation
503
function isValidAccount(obj: any): obj is Account {
504
  return typeof obj === 'object' && 
505
         typeof obj.address === 'string' &&
506
         obj.address.startsWith('0x') &&
507
         obj.address.length === 42;
508
}
509

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

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

518
// Usage in components
519
function validateAndUseAccount(account: unknown) {
520
  if (isValidAccount(account)) {
521
    // TypeScript knows account is Account type here
522
    console.log('Valid account:', account.address);
523
    return account;
524
  }
525
  throw new Error('Invalid account format');
526
}
527
```