0
# Network Management
1

2
Ethereum network configuration and Web3 provider management with support for multiple networks and custom RPC endpoints.
3

4
## Capabilities
5

6
### Network Provider Configuration
7

8
Change the Ethereum network configuration for the wallet and provider.
9

10
```typescript { .api }
11
/**
12
 * Change the Ethereum network provider configuration
13
 * Opens provider change confirmation window for user approval
14
 * @param network - Network configuration parameters
15
 * @returns Promise that resolves when network change is complete
16
 */
17
setProvider(network: NetworkInterface): Promise<void>;
18

19
interface NetworkInterface {
20
  /** Ethereum network host (predefined network or custom RPC URL) */
21
  host: ETHEREUM_NETWORK_TYPE | string;
22
  /** Network chain ID (auto-detected if not provided) */
23
  chainId?: number;
24
  /** Display name for the network */
25
  networkName?: string;
26
  /** Block explorer URL for transactions */
27
  blockExplorer?: string;
28
  /** Native currency ticker symbol */
29
  ticker?: string;
30
  /** Native currency display name */
31
  tickerName?: string;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
// Switch to Polygon network
39
await torus.setProvider({
40
  host: "matic",
41
  chainId: 137,
42
  networkName: "Polygon Mainnet",
43
  blockExplorer: "https://polygonscan.com",
44
  ticker: "MATIC",
45
  tickerName: "Polygon"
46
});
47

48
// Switch to custom RPC
49
await torus.setProvider({
50
  host: "https://rpc.ankr.com/avalanche",
51
  chainId: 43114,
52
  networkName: "Avalanche Network",
53
  blockExplorer: "https://snowtrace.io",
54
  ticker: "AVAX",
55
  tickerName: "Avalanche"
56
});
57

58
// Switch to mainnet (minimal config)
59
await torus.setProvider({
60
  host: "mainnet"
61
});
62
```
63

64
### Public Address Resolution
65

66
Get public address information for specific verifiers and users.
67

68
```typescript { .api }
69
/**
70
 * Get public address for a verifier and verifier ID
71
 * Can return extended public key information
72
 * @param args - Verifier arguments
73
 * @returns Promise resolving to address string or extended public key
74
 */
75
getPublicAddress(args: VerifierArgs): Promise<string | TorusPublicKey>;
76

77
interface VerifierArgs {
78
  /** OAuth verifier type */
79
  verifier: "google" | "reddit" | "discord";
80
  /** User identifier for the verifier */
81
  verifierId: string;
82
  /** Return extended public key information */
83
  isExtended?: boolean;
84
}
85

86
interface TorusPublicKey {
87
  /** Ethereum address */
88
  address: string;
89
  /** X coordinate of public key */
90
  X: string;
91
  /** Y coordinate of public key */
92
  Y: string;
93
}
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
// Get basic address
100
const address = await torus.getPublicAddress({
101
  verifier: "google",
102
  verifierId: "user@gmail.com"
103
});
104
console.log("Address:", address);
105

106
// Get extended public key information
107
const publicKey = await torus.getPublicAddress({
108
  verifier: "discord",
109
  verifierId: "user-discord-id",
110
  isExtended: true
111
}) as TorusPublicKey;
112

113
console.log("Extended info:", {
114
  address: publicKey.address,
115
  publicKeyX: publicKey.X,
116
  publicKeyY: publicKey.Y
117
});
118
```
119

120
### Supported Networks
121

122
```typescript { .api }
123
type ETHEREUM_NETWORK_TYPE = 
124
  | "sepolia"      // Ethereum Sepolia testnet
125
  | "mainnet"      // Ethereum mainnet
126
  | "goerli"       // Ethereum Goerli testnet (deprecated)
127
  | "localhost"    // Local development network
128
  | "matic"        // Polygon mainnet
129
  | "mumbai"       // Polygon Mumbai testnet
130
  | "xdai"         // Gnosis Chain
131
  | "bsc_mainnet"  // Binance Smart Chain mainnet
132
  | "bsc_testnet"; // Binance Smart Chain testnet
133
```
134

135
### Network Information Access
136

137
Access current network state through the provider.
138

139
```typescript { .api }
140
/** Access Ethereum provider instance */
141
readonly provider: TorusInpageProvider;
142
readonly ethereum: TorusInpageProvider; // Alias for provider
143

144
// Provider properties for network information
145
interface TorusInpageProvider {
146
  /** Current chain ID in hex format */
147
  readonly chainId: string | null;
148
  /** Current network version */
149
  readonly networkVersion: string | null;
150
  /** Currently selected account address */
151
  readonly selectedAddress: string | null;
152
}
153
```
154

155
**Usage Example:**
156

157
```typescript
158
// Get current network information
159
console.log("Current network:", {
160
  chainId: torus.provider.chainId,
161
  networkVersion: torus.provider.networkVersion,
162
  selectedAddress: torus.provider.selectedAddress
163
});
164

165
// Listen for network changes
166
torus.provider.on("chainChanged", (chainId) => {
167
  console.log("Network changed to:", chainId);
168
});
169

170
torus.provider.on("accountsChanged", (accounts) => {
171
  console.log("Account changed to:", accounts[0]);
172
});
173
```
174

175
### Custom Network Configuration
176

177
For applications requiring specific network configurations or enterprise deployments.
178

179
```typescript { .api }
180
// Example custom network configurations
181
const customNetworks = {
182
  // Private enterprise network
183
  enterprise: {
184
    host: "https://rpc.enterprise.com",
185
    chainId: 12345,
186
    networkName: "Enterprise Network",
187
    blockExplorer: "https://explorer.enterprise.com",
188
    ticker: "ENT",
189
    tickerName: "Enterprise Token"
190
  },
191
  
192
  // Layer 2 solution
193
  arbitrum: {
194
    host: "https://arb1.arbitrum.io/rpc",
195
    chainId: 42161,
196
    networkName: "Arbitrum One",
197
    blockExplorer: "https://arbiscan.io",
198
    ticker: "ETH",
199
    tickerName: "Ether"
200
  },
201
  
202
  // Optimism network
203
  optimism: {
204
    host: "https://mainnet.optimism.io",
205
    chainId: 10,
206
    networkName: "Optimism",
207
    blockExplorer: "https://optimistic.etherscan.io",
208
    ticker: "ETH",
209
    tickerName: "Ether"
210
  }
211
};
212

213
// Usage
214
await torus.setProvider(customNetworks.arbitrum);
215
```
216

217
### Network Validation
218

219
The provider automatically validates network configurations and will prompt users for approval when switching networks.
220

221
```typescript
222
// The following operations may trigger user confirmation dialogs:
223

224
// 1. Network switching
225
await torus.setProvider({ host: "matic" });
226

227
// 2. Custom RPC addition
228
await torus.setProvider({ 
229
  host: "https://custom-rpc.com",
230
  chainId: 999,
231
  networkName: "Custom Network"
232
});
233

234
// Error handling for network operations
235
try {
236
  await torus.setProvider(networkConfig);
237
} catch (error) {
238
  if (error.code === 4001) {
239
    console.log("User rejected network change");
240
  } else {
241
    console.error("Network change failed:", error.message);
242
  }
243
}
244
```
245

246
### Network Constants
247

248
```typescript { .api }
249
// Predefined payment networks (for fiat-to-crypto)
250
type SUPPORTED_PAYMENT_NETWORK_TYPE =
251
  | "mainnet"           // Ethereum mainnet
252
  | "matic"             // Polygon
253
  | "bsc_mainnet"       // Binance Smart Chain
254
  | "avalanche_mainnet" // Avalanche
255
  | "xdai"              // Gnosis Chain
256
  | "arbitrum_mainnet"  // Arbitrum
257
  | "optimism_mainnet"; // Optimism
258

259
const SUPPORTED_PAYMENT_NETWORK = {
260
  MAINNET: "mainnet",
261
  MATIC: "matic", 
262
  BSC_MAINNET: "bsc_mainnet",
263
  AVALANCHE_MAINNET: "avalanche_mainnet",
264
  XDAI: "xdai",
265
  ARBITRUM_MAINNET: "arbitrum_mainnet",
266
  OPTIMISM_MAINNET: "optimism_mainnet"
267
} as const;
268
```