tessl/npm-web3-core

Core tools and utilities for the web3.js ecosystem, providing foundational layer functionality for blockchain interactions.

—

Pending

Overview

Eval results

Files

Request Management

Name: tessl/npm-web3-core
Author: tessl

The Web3 request management system handles JSON-RPC communication with blockchain providers, offering comprehensive provider abstraction, middleware support, and batch processing capabilities. It provides the core networking layer for all blockchain interactions.

Capabilities

Web3RequestManager Class

The main request manager class that handles JSON-RPC requests to blockchain providers with full middleware and event support.

/**
 * Manages JSON-RPC requests to blockchain providers with middleware support
 * @template API - JSON-RPC API specification type
 */
class Web3RequestManager<API extends Web3APISpec = Web3APISpec> extends Web3EventEmitter<{
  PROVIDER_CHANGED: SupportedProviders<API>;
  BEFORE_PROVIDER_CHANGE: SupportedProviders<API>;
}> {
  constructor(
    provider?: SupportedProviders<API> | string, 
    useRpcCallSpecification?: boolean, 
    requestManagerMiddleware?: RequestManagerMiddleware<API>
  );
  
  // Request handling
  send<Method extends Web3APIMethod<API>, ResponseType = Web3APIReturnType<API, Method>>(
    request: Web3APIRequest<API, Method>
  ): Promise<ResponseType>;
  
  sendBatch(request: JsonRpcBatchRequest): Promise<JsonRpcBatchResponse<unknown, unknown>>;
  
  // Provider management
  setProvider(provider?: SupportedProviders<API> | string): boolean;
  readonly provider: SupportedProviders<API> | undefined;
  
  // Middleware
  setMiddleware(requestManagerMiddleware: RequestManagerMiddleware<API>): void;
  readonly middleware?: RequestManagerMiddleware<API>;
  
  // Static provider constructors
  static readonly providers: {
    HttpProvider: typeof HttpProvider;
    WebsocketProvider: typeof WebsocketProvider;
  };
  
  // Provider access
  readonly providers: typeof Web3RequestManager.providers;
}

Usage Examples:

import { Web3RequestManager } from "web3-core";
import { EthExecutionAPI } from "web3-types";

// Create with HTTP provider URL
const requestManager = new Web3RequestManager<EthExecutionAPI>(
  "https://eth-mainnet.g.alchemy.com/v2/your-api-key"
);

// Create with WebSocket provider
const wsRequestManager = new Web3RequestManager(
  "wss://eth-mainnet.ws.alchemyapi.io/v2/your-api-key"
);

// Send single request
const blockNumber = await requestManager.send({
  method: "eth_blockNumber",
  params: []
});

// Send request with parameters
const balance = await requestManager.send({
  method: "eth_getBalance", 
  params: ["0x742d35Cc6634C0532925a3b8D0d3", "latest"]
});

// Listen to provider changes
requestManager.on("PROVIDER_CHANGED", (newProvider) => {
  console.log("Provider changed:", newProvider);
});

// Change provider
requestManager.setProvider("https://polygon-rpc.com/");

Provider Management

Static and instance methods for managing blockchain providers with automatic detection and validation.

/**
 * Set or change the blockchain provider
 * @param provider - Provider instance, URL string, or undefined to clear
 * @returns Boolean indicating if provider was successfully set
 */
setProvider(provider?: SupportedProviders<API> | string): boolean;

/**
 * Access to provider constructor classes
 */
static readonly providers: {
  HttpProvider: typeof HttpProvider;
  WebsocketProvider: typeof WebsocketProvider;
};

Usage Examples:

// Change provider to different network
const success = requestManager.setProvider("https://bsc-dataseed.binance.org/");
console.log("Provider changed:", success);

// Use provider constructors
const httpProvider = new Web3RequestManager.providers.HttpProvider(
  "https://eth-mainnet.g.alchemy.com/v2/your-api-key",
  {
    timeout: 30000,
    headers: { "User-Agent": "MyApp/1.0" }
  }
);

const wsProvider = new Web3RequestManager.providers.WebsocketProvider(
  "wss://eth-mainnet.ws.alchemyapi.io/v2/your-api-key",
  {
    timeout: 30000,
    reconnect: { auto: true, delay: 5000, maxAttempts: 5 }
  }
);

// Create request manager with configured provider
const customRequestManager = new Web3RequestManager(httpProvider);

Batch Request Processing

Efficient batch processing capabilities for sending multiple JSON-RPC requests in a single network call.

/**
 * Send multiple JSON-RPC requests in a single batch call
 * @param request - Array of JSON-RPC request objects
 * @returns Promise resolving to batch response with all results
 */
sendBatch(request: JsonRpcBatchRequest): Promise<JsonRpcBatchResponse<unknown, unknown>>;

Usage Examples:

// Create batch request array
const batchRequest: JsonRpcBatchRequest = [
  { 
    id: 1,
    jsonrpc: "2.0",
    method: "eth_blockNumber", 
    params: [] 
  },
  { 
    id: 2,
    jsonrpc: "2.0",
    method: "eth_gasPrice", 
    params: [] 
  },
  {
    id: 3, 
    jsonrpc: "2.0",
    method: "eth_getBalance",
    params: ["0x742d35Cc6634C0532925a3b8D0d3", "latest"]
  }
];

// Send batch request
const batchResponse = await requestManager.sendBatch(batchRequest);

// Process results
batchResponse.forEach((response, index) => {
  if ('result' in response) {
    console.log(`Request ${index + 1} result:`, response.result);
  } else if ('error' in response) {
    console.error(`Request ${index + 1} error:`, response.error);
  }
});

Middleware System

Request and response middleware for intercepting and modifying JSON-RPC communications.

/**
 * Middleware interface for processing requests and responses
 * @template API - JSON-RPC API specification type
 */
interface RequestManagerMiddleware<API extends Web3APISpec = Web3APISpec> {
  /**
   * Process outgoing JSON-RPC requests before sending
   * @param request - The JSON-RPC request payload
   * @param options - Additional processing options
   * @returns Promise resolving to processed request
   */
  processRequest<ParamType = unknown[]>(
    request: JsonRpcPayload<ParamType>, 
    options?: {[key: string]: unknown}
  ): Promise<JsonRpcPayload<ParamType>>;
  
  /**
   * Process incoming JSON-RPC responses after receiving
   * @param response - The JSON-RPC response payload
   * @param options - Additional processing options
   * @returns Promise resolving to processed response
   */
  processResponse<AnotherMethod extends Web3APIMethod<API> = Web3APIMethod<API>, ResponseType = Web3APIReturnType<API, AnotherMethod>>(
    response: JsonRpcResponse<ResponseType>, 
    options?: {[key: string]: unknown}
  ): Promise<JsonRpcResponse<ResponseType>>;
}

/**
 * Set middleware for request/response processing
 * @param requestManagerMiddleware - Middleware implementation
 */
setMiddleware(requestManagerMiddleware: RequestManagerMiddleware<API>): void;

Usage Examples:

// Create logging middleware
const loggingMiddleware: RequestManagerMiddleware<EthExecutionAPI> = {
  async processRequest(request, options) {
    console.log("Outgoing request:", request.method, request.params);
    return request;
  },
  
  async processResponse(response, options) {
    if ('result' in response) {
      console.log("Response result:", response.result);
    } else if ('error' in response) {
      console.error("Response error:", response.error);
    }
    return response;
  }
};

// Create authentication middleware
const authMiddleware: RequestManagerMiddleware<EthExecutionAPI> = {
  async processRequest(request, options) {
    // Add authentication headers or modify request
    return {
      ...request,
      // Add custom properties if needed
    };
  },
  
  async processResponse(response, options) {
    // Process or validate response
    return response;
  }
};

// Apply middleware
requestManager.setMiddleware(loggingMiddleware);

// Create request manager with middleware
const authenticatedManager = new Web3RequestManager(
  "https://protected-api.example.com/",
  false, // useRpcCallSpecification
  authMiddleware
);

Event System Integration

Event emission for provider lifecycle and request management events.

/**
 * Events emitted by Web3RequestManager
 */
enum Web3RequestManagerEvent {
  PROVIDER_CHANGED = 'PROVIDER_CHANGED',
  BEFORE_PROVIDER_CHANGE = 'BEFORE_PROVIDER_CHANGE'
}

Usage Examples:

// Listen to provider change events
requestManager.on("PROVIDER_CHANGED", (newProvider) => {
  console.log("New provider set:", newProvider);
  
  // Reinitialize dependent components
  if (newProvider) {
    console.log("Provider type:", typeof newProvider);
  }
});

requestManager.on("BEFORE_PROVIDER_CHANGE", (oldProvider) => {
  console.log("About to change provider from:", oldProvider);
  
  // Cleanup or save state before provider change
  if (oldProvider) {
    // Perform cleanup
  }
});

// Provider change triggers events
requestManager.setProvider("https://polygon-rpc.com/");
// Logs: "About to change provider from: [previous provider]"
// Logs: "New provider set: [new provider]"

Advanced Request Configuration

Configuration options for request manager behavior and RPC specification handling.

/**
 * Create request manager with advanced configuration
 * @param provider - Blockchain provider
 * @param useRpcCallSpecification - Use RPC call specification for validation
 * @param requestManagerMiddleware - Middleware for request/response processing
 */
constructor(
  provider?: SupportedProviders<API> | string, 
  useRpcCallSpecification?: boolean, 
  requestManagerMiddleware?: RequestManagerMiddleware<API>
);

Usage Examples:

// Create with RPC specification validation
const strictRequestManager = new Web3RequestManager(
  "https://eth-mainnet.g.alchemy.com/v2/your-api-key",
  true, // Enable RPC call specification validation
  loggingMiddleware
);

// This will validate requests against the API specification
try {
  const result = await strictRequestManager.send({
    method: "eth_getBalance",
    params: ["0x742d35Cc6634C0532925a3b8D0d3", "latest"]
  });
} catch (error) {
  // Handle validation or network errors
  console.error("Request failed:", error);
}

Install with Tessl CLI