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

Configuration Management

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

The Web3 configuration management system provides centralized settings control with event-driven updates and comprehensive blockchain-specific configuration options. It serves as the foundation for all Web3 instance behavior and transaction parameters.

Capabilities

Web3Config Class

Abstract base class providing configuration management with event emission for configuration changes.

/**
 * Abstract base configuration class with event emission for setting changes
 */
abstract class Web3Config extends Web3EventEmitter<{
  CONFIG_CHANGE: {
    name: string;
    oldValue: unknown;
    newValue: unknown;
  };
}> {
  constructor(options?: Partial<Web3ConfigOptions>);
  
  /**
   * Update multiple configuration options at once
   * @param options - Partial configuration options to update
   */
  setConfig(options: Partial<Web3ConfigOptions>): void;
  
  // Configuration properties (getters/setters)
  handleRevert: boolean;
  defaultAccount?: HexString;
  defaultBlock: BlockNumberOrTag;
  transactionSendTimeout: number;
  transactionBlockTimeout: number;
  transactionConfirmationBlocks: number;
  transactionPollingInterval: number;
  transactionPollingTimeout: number;
  transactionReceiptPollingInterval?: number;
  transactionConfirmationPollingInterval?: number;
  blockHeaderTimeout: number;
  maxListenersWarningThreshold: number;
  contractDataInputFill: 'data' | 'input' | 'both';
  defaultNetworkId?: Numbers;
  defaultChain: string;
  defaultHardfork: string;
  ignoreGasPricing: boolean;
  defaultCommon?: Common;
  defaultTransactionType: Numbers;
  defaultMaxPriorityFeePerGas: Numbers;
  enableExperimentalFeatures: {
    useSubscriptionWhenCheckingBlockTimeout: boolean;
    useRpcCallSpecification: boolean;
    [key: string]: boolean;
  };
  transactionBuilder?: TransactionBuilder;
  transactionTypeParser?: TransactionTypeParser;
  customTransactionSchema?: CustomTransactionSchema;
  defaultReturnFormat: DataFormat;
}

Usage Examples:

import { Web3Config } from "web3-core";

// Extend Web3Config for custom implementation
class MyWeb3Config extends Web3Config {
  constructor(options?: Partial<Web3ConfigOptions>) {
    super(options);
    
    // Listen to configuration changes
    this.on("CONFIG_CHANGE", ({ name, oldValue, newValue }) => {
      console.log(`Config ${name} changed from ${oldValue} to ${newValue}`);
    });
  }
}

// Create configuration instance
const config = new MyWeb3Config({
  defaultBlock: "latest",
  transactionSendTimeout: 60000,
  transactionConfirmationBlocks: 24,
  handleRevert: true
});

// Update individual properties
config.defaultAccount = "0x742d35Cc6634C0532925a3b8D0d3";
config.transactionSendTimeout = 120000;

// Update multiple properties at once
config.setConfig({
  defaultBlock: "pending",
  transactionPollingInterval: 4000,
  maxListenersWarningThreshold: 100
});

Configuration Options Interface

Comprehensive configuration interface defining all available Web3 settings.

/**
 * Complete configuration options for Web3 instances
 */
interface Web3ConfigOptions {
  /**
   * Handle revert reasons in failed transactions
   * @default false
   */
  handleRevert: boolean;
  
  /**
   * Default account address for transactions
   * @default undefined
   */
  defaultAccount?: HexString;
  
  /**
   * Default block parameter for calls ("latest", "earliest", "pending", or block number)
   * @default "latest"
   */
  defaultBlock: BlockNumberOrTag;
  
  /**
   * Timeout for sending transactions in milliseconds
   * @default 750000
   */
  transactionSendTimeout: number;
  
  /**
   * Timeout for waiting for blocks in milliseconds
   * @default 50000
   */
  transactionBlockTimeout: number;
  
  /**
   * Number of confirmation blocks required for transactions
   * @default 24
   */
  transactionConfirmationBlocks: number;
  
  /**
   * Polling interval for transaction receipts in milliseconds
   * @default 1000
   */
  transactionPollingInterval: number;
  
  /**
   * Timeout for polling transaction receipts in milliseconds
   * @default 750000
   */
  transactionPollingTimeout: number;
  
  /**
   * Optional custom polling interval for transaction receipts in milliseconds
   * @default undefined
   */
  transactionReceiptPollingInterval?: number;
  
  /**
   * Optional custom polling interval for transaction confirmations in milliseconds
   * @default undefined
   */
  transactionConfirmationPollingInterval?: number;
  
  /**
   * Timeout for block header subscriptions in milliseconds
   * @default 10000
   */
  blockHeaderTimeout: number;
  
  /**
   * Warning threshold for maximum event listeners
   * @default 100
   */
  maxListenersWarningThreshold: number;
  
  /**
   * Contract data input field preference
   * @default "data"
   */
  contractDataInputFill: 'data' | 'input' | 'both';
  
  /**
   * Default network ID for transactions
   * @default undefined
   */
  defaultNetworkId?: Numbers;
  
  /**
   * Default blockchain network
   * @default "mainnet"
   */
  defaultChain: string;
  
  /**
   * Default hardfork version
   * @default "london"
   */
  defaultHardfork: string;
  
  /**
   * Skip automatic gas pricing
   * @default false
   */
  ignoreGasPricing: boolean;
  
  /**
   * Default common configuration for transactions
   * @default undefined 
   */
  defaultCommon?: Common;
  
  /**
   * Default transaction type (0: legacy, 1: EIP-2930, 2: EIP-1559)
   * @default 2
   */
  defaultTransactionType: Numbers;
  
  /**
   * Default maximum priority fee per gas for EIP-1559 transactions
   * @default 2500000000
   */
  defaultMaxPriorityFeePerGas: Numbers;
  
  /**
   * Experimental feature flags
   * @default { useSubscriptionWhenCheckingBlockTimeout: false, useRpcCallSpecification: false }
   */
  enableExperimentalFeatures: {
    /** Use subscription for block timeout checking */
    useSubscriptionWhenCheckingBlockTimeout: boolean;
    /** Use RPC call specification (EIP-1474) */
    useRpcCallSpecification: boolean;
    /** Other experimental features */
    [key: string]: boolean;
  };
  
  /**
   * Custom transaction builder function
   * @default undefined
   */
  transactionBuilder?: TransactionBuilder;
  
  /**
   * Custom transaction type parser function
   * @default undefined
   */
  transactionTypeParser?: TransactionTypeParser;
  
  /**
   * Custom transaction schema for validation
   * @default undefined
   */
  customTransactionSchema?: CustomTransactionSchema;
  
  /**
   * Default data format for return values
   * @default DataFormat.JSON
   */
  defaultReturnFormat: DataFormat;
}

Usage Examples:

// Complete configuration example
const fullConfig: Web3ConfigOptions = {
  handleRevert: true,
  defaultAccount: "0x742d35Cc6634C0532925a3b8D0d3",
  defaultBlock: "latest",
  transactionSendTimeout: 60000,
  transactionBlockTimeout: 50000,
  transactionConfirmationBlocks: 24,
  transactionPollingInterval: 1000,
  transactionPollingTimeout: 750000,
  blockHeaderTimeout: 10000,
  maxListenersWarningThreshold: 100,
  contractDataInputFill: "data",
  defaultNetworkId: 1,
  defaultChain: "mainnet",
  defaultHardfork: "london",
  ignoreGasPricing: false,
  defaultTransactionType: 2,
  defaultMaxPriorityFeePerGas: 2500000000,
  enableExperimentalFeatures: {
    useNativeKeccak: true,
    useRpcCallSpecification: false
  },
  defaultReturnFormat: DataFormat.JSON
};

Configuration Events

Event system for tracking configuration changes across the application.

/**
 * Configuration change events
 */
enum Web3ConfigEvent {
  CONFIG_CHANGE = 'CONFIG_CHANGE'
}

/**
 * Configuration change event payload
 */
interface ConfigChangeEvent {
  name: string;
  oldValue: unknown;
  newValue: unknown;
}

Usage Examples:

// Listen to all configuration changes
config.on("CONFIG_CHANGE", ({ name, oldValue, newValue }) => {
  console.log(`Configuration '${name}' changed:`);
  console.log(`  Old value: ${JSON.stringify(oldValue)}`);
  console.log(`  New value: ${JSON.stringify(newValue)}`);
  
  // React to specific configuration changes
  switch (name) {
    case "defaultAccount":
      console.log("Default account updated, refreshing UI...");
      break;
    case "defaultBlock":
      console.log("Default block changed, clearing cache...");
      break;
    case "transactionSendTimeout":
      console.log("Transaction timeout updated");
      break;
  }
});

// Configuration changes trigger events
config.defaultBlock = "pending"; 
// Logs: Configuration 'defaultBlock' changed: Old value: "latest", New value: "pending"

config.setConfig({ 
  transactionSendTimeout: 90000,
  transactionConfirmationBlocks: 12
});
// Logs events for both changed properties

Transaction Configuration

Specialized configuration options for transaction behavior and gas management.

/**
 * Transaction builder function type
 */
type TransactionBuilder<ReturnType = Transaction> = (options: {
  transaction: TransactionWithFromLocalWalletIndex;
  web3Context: Web3Context;
  privateKey?: HexString;
  fillGasPrice?: boolean;
  fillGasLimit?: boolean;
}) => Promise<ReturnType>;

/**
 * Transaction type parser function type
 */
type TransactionTypeParser = (transaction: Transaction) => HexString | undefined;

/**
 * Custom transaction schema definition
 */
type CustomTransactionSchema = {
  type: string;
  properties: Record<string, Schema>;
};

Usage Examples:

// Custom transaction builder
const customBuilder: TransactionBuilder = async (options) => {
  const { transaction, web3Context, fillGasPrice, fillGasLimit } = options;
  
  // Custom transaction building logic
  const builtTransaction = { ...transaction };
  
  if (fillGasPrice && !builtTransaction.gasPrice) {
    const gasPrice = await web3Context.requestManager.send({
      method: "eth_gasPrice",
      params: []
    });
    builtTransaction.gasPrice = gasPrice;
  }
  
  if (fillGasLimit && !builtTransaction.gas) {
    const gasLimit = await web3Context.requestManager.send({
      method: "eth_estimateGas", 
      params: [transaction]
    });
    builtTransaction.gas = gasLimit;
  }
  
  return builtTransaction;
};

// Custom transaction type parser
const typeParser: TransactionTypeParser = (transaction) => {
  if (transaction.maxFeePerGas || transaction.maxPriorityFeePerGas) {
    return "0x2"; // EIP-1559
  } else if (transaction.accessList) {
    return "0x1"; // EIP-2930
  } else {
    return "0x0"; // Legacy
  }
};

// Apply custom configuration
config.setConfig({
  transactionBuilder: customBuilder,
  transactionTypeParser: typeParser,
  defaultTransactionType: 2,
  ignoreGasPricing: false
});

Network and Chain Configuration

Configuration options for blockchain network and consensus parameters.

/**
 * Common configuration object for blockchain parameters
 */
interface Common {
  customChain: {
    name?: string;
    networkId: number;
    chainId: number;
  };
  baseChain?: 'mainnet' | 'goerli' | 'sepolia' | 'holesky' | string;
  hardfork?: string;
}

Usage Examples:

// Configure for custom network
const customNetworkConfig: Partial<Web3ConfigOptions> = {
  defaultChain: "polygon",
  defaultNetworkId: 137,
  defaultHardfork: "london",
  defaultCommon: {
    customChain: {
      name: "Polygon Mainnet",
      networkId: 137,
      chainId: 137
    },
    baseChain: "mainnet",
    hardfork: "london"
  }
};

// Configure for testnet
const testnetConfig: Partial<Web3ConfigOptions> = {
  defaultChain: "goerli",
  defaultNetworkId: 5,
  defaultCommon: {
    customChain: {
      name: "Goerli Testnet", 
      networkId: 5,
      chainId: 5
    },
    baseChain: "goerli",
    hardfork: "london"
  },
  transactionConfirmationBlocks: 3 // Faster confirmations on testnet
};

config.setConfig(customNetworkConfig);

Data Format Configuration

Configuration for controlling data format of return values throughout the library.

/**
 * Data format enumeration for return values
 */
enum DataFormat {
  JSON = "JSON",
  HEX = "HEX"
}

Usage Examples:

// Configure return format
config.defaultReturnFormat = DataFormat.HEX;

// This affects all return values from methods
// Numbers will be returned as hex strings instead of numbers
// Addresses and hashes remain hex strings
// Booleans and strings are unaffected

Install with Tessl CLI