tessl/npm-web3

Ethereum JavaScript API for interacting with the Ethereum blockchain with comprehensive TypeScript support, modular architecture, and plugin extensibility.

—

Pending

Overview

Eval results

Files

Provider Management

Name: tessl/npm-web3
Author: tessl

The provider system in Web3.js offers flexible connection management for interacting with Ethereum networks. It supports multiple transport protocols (HTTP, WebSocket, IPC), automatic provider detection, and EIP-6963 browser provider discovery with robust connection handling and configuration options.

Capabilities

HTTP Provider

HTTP provider for standard JSON-RPC connections over HTTP/HTTPS.

/**
 * HTTP provider for Ethereum RPC connections
 */
class HttpProvider implements EthExecutionAPI {
  /**
   * Create HTTP provider instance
   * @param url - RPC endpoint URL
   * @param options - Provider configuration options
   */
  constructor(url: string, options?: HttpProviderOptions);
  
  /**
   * Send RPC request
   * @param request - JSON-RPC request
   * @returns Promise with RPC response
   */
  request<T>(request: JsonRpcRequest): Promise<JsonRpcResponse<T>>;
  
  /**
   * Get provider configuration
   */
  get config(): HttpProviderOptions;
  
  /**
   * Get provider URL
   */
  get url(): string;
}

interface HttpProviderOptions {
  /** HTTP keep-alive setting */
  keepAlive?: boolean;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Custom headers */
  headers?: Record<string, string>;
  /** Request credentials mode */
  credentials?: RequestCredentials;
  /** Custom HTTP agent */
  agent?: any;
  /** Provider-specific configuration */
  providerOptions?: RequestInit;
}

Usage Examples:

import { HttpProvider } from 'web3-providers-http';

// Basic HTTP provider
const provider = new HttpProvider('https://mainnet.infura.io/v3/YOUR-PROJECT-ID');

// HTTP provider with options
const providerWithOptions = new HttpProvider('https://localhost:8545', {
  timeout: 10000,
  headers: {
    'Authorization': 'Bearer token123'
  },
  keepAlive: true,
  providerOptions: {
    credentials: 'include'
  }
});

// Use with Web3
const web3 = new Web3(provider);

WebSocket Provider

WebSocket provider for real-time connections with subscription support.

/**
 * WebSocket provider for real-time Ethereum connections
 */
class WebSocketProvider implements EthExecutionAPI {
  /**
   * Create WebSocket provider instance
   * @param url - WebSocket endpoint URL
   * @param clientOptions - WebSocket client options
   * @param reconnectOptions - Reconnection configuration
   */
  constructor(
    url: string, 
    clientOptions?: ClientOptions, 
    reconnectOptions?: ReconnectOptions
  );
  
  /**
   * Send RPC request
   * @param request - JSON-RPC request
   * @returns Promise with RPC response
   */
  request<T>(request: JsonRpcRequest): Promise<JsonRpcResponse<T>>;
  
  /**
   * Connect to WebSocket endpoint
   */
  connect(): Promise<void>;
  
  /**
   * Disconnect from WebSocket
   */
  disconnect(): Promise<void>;
  
  /**
   * Check connection status
   */
  get connected(): boolean;
  
  /**
   * Subscribe to events
   */
  on(event: string, listener: (...args: any[]) => void): void;
  
  /**
   * Remove event listener
   */
  removeListener(event: string, listener: (...args: any[]) => void): void;
}

interface ClientOptions {
  /** Custom headers for connection */
  headers?: Record<string, string>;
  /** Authentication protocols */
  protocols?: string[];
  /** Connection timeout */
  timeout?: number;
  /** Maximum payload size */
  maxPayload?: number;
}

interface ReconnectOptions {
  /** Enable automatic reconnection */
  autoReconnect?: boolean;
  /** Delay between reconnection attempts */
  delay?: number;
  /** Maximum reconnection attempts */
  maxAttempts?: number;
}

Usage Examples:

import { WebSocketProvider } from 'web3-providers-ws';

// Basic WebSocket provider
const wsProvider = new WebSocketProvider('wss://mainnet.infura.io/ws/v3/YOUR-PROJECT-ID');

// WebSocket provider with options
const wsProviderWithOptions = new WebSocketProvider(
  'wss://localhost:8546',
  {
    headers: { 'Authorization': 'Bearer token123' },
    timeout: 30000
  },
  {
    autoReconnect: true,
    delay: 5000,
    maxAttempts: 5
  }
);

// Connection management
await wsProvider.connect();
console.log('Connected:', wsProvider.connected);

// Event handling
wsProvider.on('connect', () => console.log('Connected'));
wsProvider.on('disconnect', () => console.log('Disconnected'));
wsProvider.on('error', console.error);

// Use with Web3
const web3 = new Web3(wsProvider);

EIP-6963 Provider Discovery

Browser provider discovery following EIP-6963 standard for wallet integration.

/**
 * Request available EIP-6963 providers
 * @returns Promise with discovered providers map
 */
function requestEIP6963Providers(): Promise<EIP6963ProviderResponse>;

/**
 * Listen for new provider discoveries
 * @param callback - Function called when new provider is discovered
 */
function onNewProviderDiscovered(
  callback: (providerEvent: EIP6963ProvidersMapUpdateEvent) => void
): void;

interface EIP6963ProviderInfo {
  /** Unique provider identifier */
  uuid: string;
  /** Human-readable provider name */
  name: string;
  /** Provider icon URL */
  icon: string;
  /** Reverse domain name */
  rdns: string;
}

interface EIP6963ProviderDetail<API = Web3APISpec> {
  /** Provider information */
  info: EIP6963ProviderInfo;
  /** EIP-1193 provider instance */
  provider: EIP1193Provider<API>;
}

type EIP6963ProviderResponse = Map<string, EIP6963ProviderDetail>;

interface EIP6963ProvidersMapUpdateEvent extends CustomEvent {
  type: string;
  detail: EIP6963ProviderResponse;
}

/** Global providers map */
const eip6963ProvidersMap: EIP6963ProviderResponse;

enum Eip6963EventName {
  eip6963announceProvider = 'eip6963:announceProvider',
  eip6963requestProvider = 'eip6963:requestProvider'
}

Usage Examples:

// Request available providers
const providers = await Web3.requestEIP6963Providers();
console.log('Available providers:', providers.size);

providers.forEach((providerDetail, uuid) => {
  console.log('Provider:', providerDetail.info.name);
  console.log('UUID:', uuid);
});

// Listen for new providers
Web3.onNewProviderDiscovered((event) => {
  console.log('New providers available:', event.detail.size);
  
  event.detail.forEach((providerDetail) => {
    console.log('New provider:', providerDetail.info.name);
  });
});

// Use discovered provider
const firstProvider = providers.values().next().value;
if (firstProvider) {
  const web3 = new Web3(firstProvider.provider);
}

Provider Configuration

Common provider configuration and management utilities.

/**
 * Check if value is supported provider
 * @param provider - Provider to check
 * @returns Boolean indicating support
 */
function isSupportedProvider<T>(provider: unknown): provider is SupportedProviders<T>;

/**
 * Set provider for Web3 instance
 * @param provider - New provider
 * @returns Boolean indicating success
 */
setProvider(provider: string | SupportedProviders<EthExecutionAPI>): boolean;

/**
 * Get current provider
 * @returns Current provider or undefined
 */
get currentProvider(): SupportedProviders<EthExecutionAPI> | undefined;

/**
 * Get given provider (from browser)
 * @returns Browser-injected provider or undefined
 */
static get givenProvider(): SupportedProviders<EthExecutionAPI> | undefined;

type SupportedProviders<API = unknown> = 
  | EIP1193Provider<API>
  | Web3BaseProvider<API>
  | HttpProvider
  | WebSocketProvider;

Usage Examples:

// Check provider support
const provider = new HttpProvider('https://localhost:8545');
console.log('Supported:', isSupportedProvider(provider)); // true

// Provider switching
const web3 = new Web3('https://mainnet.infura.io/v3/YOUR-PROJECT-ID');

// Switch to WebSocket
web3.setProvider('wss://mainnet.infura.io/ws/v3/YOUR-PROJECT-ID');

// Check current provider
console.log('Current provider:', web3.currentProvider);

// Check for browser-injected provider
if (Web3.givenProvider) {
  console.log('Browser provider available');
  web3.setProvider(Web3.givenProvider);
}

Provider Events

Event handling for provider lifecycle and connection state.

interface ProviderEvents {
  /** Connection established */
  connect: (connectInfo: { chainId: string }) => void;
  
  /** Connection lost */
  disconnect: (error: { code: number; message: string }) => void;
  
  /** Chain changed */
  chainChanged: (chainId: string) => void;
  
  /** Accounts changed */
  accountsChanged: (accounts: string[]) => void;
  
  /** Error occurred */
  error: (error: Error) => void;
  
  /** Message received */
  message: (message: any) => void;
}

/**
 * Add event listener to provider
 * @param event - Event name
 * @param listener - Event handler
 */
on<K extends keyof ProviderEvents>(event: K, listener: ProviderEvents[K]): void;

/**
 * Remove event listener from provider
 * @param event - Event name
 * @param listener - Event handler
 */
removeListener<K extends keyof ProviderEvents>(event: K, listener: ProviderEvents[K]): void;

Usage Examples:

// Provider event handling
const provider = new WebSocketProvider('wss://localhost:8546');

provider.on('connect', (connectInfo) => {
  console.log('Connected to chain:', connectInfo.chainId);
});

provider.on('disconnect', (error) => {
  console.log('Disconnected:', error.message);
});

provider.on('chainChanged', (chainId) => {
  console.log('Chain changed to:', chainId);
});

provider.on('accountsChanged', (accounts) => {
  console.log('Accounts changed:', accounts);
});

provider.on('error', (error) => {
  console.error('Provider error:', error);
});

Types

interface JsonRpcRequest {
  jsonrpc: '2.0';
  method: string;
  params?: unknown[];
  id?: string | number;
}

interface JsonRpcResponse<T = unknown> {
  jsonrpc: '2.0';
  id?: string | number;
  result?: T;
  error?: {
    code: number;
    message: string;
    data?: unknown;
  };
}

interface EIP1193Provider<API = unknown> {
  request<T>(request: JsonRpcRequest): Promise<T>;
  on?(event: string, listener: (...args: any[]) => void): void;
  removeListener?(event: string, listener: (...args: any[]) => void): void;
}

interface Web3BaseProvider<API = unknown> {
  request<T>(request: JsonRpcRequest): Promise<JsonRpcResponse<T>>;
}

interface EIP6963ProviderInfo {
  uuid: string;
  name: string;
  icon: string;
  rdns: string;
}

interface EIP6963ProviderDetail {
  info: EIP6963ProviderInfo;
  provider: EIP1193Provider;
}

interface EIP6963ProviderResponse {
  [uuid: string]: EIP6963ProviderDetail;
}

type EIP6963ProvidersMapUpdateEvent = CustomEvent<{
  providersMap: Map<string, EIP6963ProviderDetail>;
}>;

EIP-6963 Provider Discovery

Modern Web3 applications can automatically discover and connect to browser wallets using the EIP-6963 standard for provider discovery.

Provider Discovery Functions

Discover available wallet providers in the browser environment.

/**
 * Request all available EIP-6963 compatible providers
 * @returns Promise resolving to map of available providers
 */
function requestEIP6963Providers(): Promise<EIP6963ProviderResponse>;

/**
 * Listen for new provider discoveries
 * @param callback - Function called when new providers are discovered
 */
function onNewProviderDiscovered(
  callback: (providerEvent: EIP6963ProvidersMapUpdateEvent) => void
): void;

Usage Examples:

import { Web3, requestEIP6963Providers, onNewProviderDiscovered } from 'web3';

// Discover all available providers
async function connectToWallet() {
  const providers = await requestEIP6963Providers();
  
  // List available wallets
  Object.values(providers).forEach((provider) => {
    console.log(`Found wallet: ${provider.info.name}`);
    console.log(`Icon: ${provider.info.icon}`);
    console.log(`RDNS: ${provider.info.rdns}`);
  });
  
  // Connect to first available provider
  if (Object.keys(providers).length > 0) {
    const firstProvider = Object.values(providers)[0];
    const web3 = new Web3(firstProvider.provider);
    return web3;
  }
}

// Listen for newly installed wallets
onNewProviderDiscovered((event) => {
  const providersMap = event.detail.providersMap;
  providersMap.forEach((providerDetail, uuid) => {
    console.log(`New wallet discovered: ${providerDetail.info.name}`);
  });
});

// Usage with provider selection
async function selectWalletProvider(walletName: string) {
  const providers = await requestEIP6963Providers();
  
  const selectedProvider = Object.values(providers).find(
    (provider) => provider.info.name === walletName
  );
  
  if (selectedProvider) {
    return new Web3(selectedProvider.provider);
  }
  
  throw new Error(`Wallet "${walletName}" not found`);
}

// Connect to MetaMask specifically
const web3 = await selectWalletProvider('MetaMask');

Provider Information Structure

Each discovered provider includes detailed metadata for user interface display.

interface EIP6963ProviderInfo {
  /** Unique identifier for the provider */
  uuid: string;
  
  /** Human-readable name of the wallet */
  name: string;
  
  /** Data URL or HTTP URL of wallet icon */
  icon: string;
  
  /** Reverse DNS notation identifier */
  rdns: string;
}

interface EIP6963ProviderDetail {
  /** Provider metadata */
  info: EIP6963ProviderInfo;
  
  /** EIP-1193 compatible provider instance */
  provider: EIP1193Provider;
}

Install with Tessl CLI