{"id":18003,"library":"web3-provider-engine","title":"Web3 ProviderEngine","description":"Web3 ProviderEngine is a JavaScript library designed for composing custom Ethereum provider objects using a stack of middleware-like modules called 'sub-providers'. It enables fine-grained control over RPC requests, facilitating features like caching and custom transaction signing workflows. Originally developed for MetaMask, this package has been officially deprecated since version 17.0.0, released in March 2023. Development has largely ceased, and the current stable version is 17.0.1. Users are strongly advised to migrate to modern alternatives such as `@metamask/json-rpc-engine`, `@metamask/eth-json-rpc-middleware`, and `@metamask/eth-json-rpc-provider`. Its key differentiator was its highly modular architecture, allowing developers to assemble a customized provider pipeline for diverse DApp requirements, acting as a 'zero-client' that processes local requests and passes data lookups to a data source.","status":"deprecated","version":"17.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/MetaMask/web3-provider-engine","tags":["javascript"],"install":[{"cmd":"npm install web3-provider-engine","lang":"bash","label":"npm"},{"cmd":"yarn add web3-provider-engine","lang":"bash","label":"yarn"},{"cmd":"pnpm add web3-provider-engine","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used alongside Web3 ProviderEngine to interact with the Ethereum blockchain. Note that Web3.js itself is also in a sunsetting phase as of early 2025.","package":"web3","optional":false}],"imports":[{"note":"The package exports a default `ProviderEngine` class, but it's a CommonJS module. For ESM, use `import * as` or direct `require` syntax. Direct named import will result in a TypeError.","wrong":"import { ProviderEngine } from 'web3-provider-engine';","symbol":"ProviderEngine","correct":"import * as ProviderEngine from 'web3-provider-engine';\n// Or for CommonJS:\nconst ProviderEngine = require('web3-provider-engine');"},{"note":"Subproviders are also CommonJS modules. Use `import * as` for ESM or `require` for CommonJS. Specific file extensions (`.js`) might be needed in some Node.js ESM environments or bundlers for subpath imports.","wrong":"import { RpcSubprovider } from 'web3-provider-engine/subproviders/rpc';","symbol":"RpcSubprovider","correct":"import * as RpcSubprovider from 'web3-provider-engine/subproviders/rpc';\n// Or for CommonJS:\nconst RpcSubprovider = require('web3-provider-engine/subproviders/rpc.js');"},{"note":"Subproviders are CommonJS modules. Named imports (even if they appear to be default in CJS) are not directly supported with `import Name from 'module'` in ESM. Use `import * as` or `require`.","wrong":"import HookedWalletSubprovider from 'web3-provider-engine/subproviders/hooked-wallet';","symbol":"HookedWalletSubprovider","correct":"import * as HookedWalletSubprovider from 'web3-provider-engine/subproviders/hooked-wallet';\n// Or for CommonJS:\nconst HookedWalletSubprovider = require('web3-provider-engine/subproviders/hooked-wallet.js');"}],"quickstart":{"code":"const ProviderEngine = require('web3-provider-engine');\nconst CacheSubprovider = require('web3-provider-engine/subproviders/cache.js');\nconst FixtureSubprovider = require('web3-provider-engine/subproviders/fixture.js');\nconst FilterSubprovider = require('web3-provider-engine/subproviders/filters.js');\nconst VmSubprovider = require('web3-provider-engine/subproviders/vm.js');\nconst HookedWalletSubprovider = require('web3-provider-engine/subproviders/hooked-wallet.js');\nconst NonceSubprovider = require('web3-provider-engine/subproviders/nonce-tracker.js');\nconst RpcSubprovider = require('web3-provider-engine/subproviders/rpc.js');\nconst Web3 = require('web3'); // Ensure web3 is installed: npm install web3\n\n// Create a new ProviderEngine instance\nvar engine = new ProviderEngine();\n// Connect it to a Web3.js instance\nvar web3 = new Web3(engine);\n\n// Add various subproviders to the engine stack:\n\n// 1. Static results for common RPC methods\nengine.addProvider(new FixtureSubprovider({\n  web3_clientVersion: 'ProviderEngine/v0.0.0/javascript',\n  net_listening: true,\n  eth_hashrate: '0x00',\n  eth_mining: false,\n  eth_syncing: true,\n}));\n\n// 2. Caching layer for RPC results\nengine.addProvider(new CacheSubprovider());\n\n// 3. Filter handling for log and block subscriptions\nengine.addProvider(new FilterSubprovider());\n\n// 4. Nonce tracking for transaction management\nengine.addProvider(new NonceSubprovider());\n\n// 5. Ethereum Virtual Machine (VM) for local execution\nengine.addProvider(new VmSubprovider());\n\n// 6. Hooked wallet for identity management and transaction signing\nengine.addProvider(new HookedWalletSubprovider({\n  getAccounts: function(cb){ console.log('getAccounts called'); cb(null, ['0x9E75379dE05C552E5C9A367E9FfF1B9C7e5A83D0']); }, // Placeholder account\n  approveTransaction: function(cb){ console.log('approveTransaction called'); cb(null, true); }, // Auto-approve for demo\n  signTransaction: function(cb){ console.log('signTransaction called'); cb(null, '0xf86180808094000000000000000000000000000000000000000080801ba0483c6d860d843825a0a4c0384737d9953835032a76f23e74c1067e812d4d8cae6a053c8c7344933a3889151c76c0e5272a7281c7e949d212a4507119e075c12891'); }, // Placeholder signed tx\n}));\n\n// 7. RPC data source (Infura) - requires an API key since v16.0.0\nengine.addProvider(new RpcSubprovider({\n  rpcUrl: 'https://mainnet.infura.io/v3/' + (process.env.INFURA_API_KEY ?? ''), // Replace with your Infura project ID\n}));\n\n// Set up event listeners\nengine.on('block', function(block){\n  console.log('================================');\n  console.log('BLOCK CHANGED:', '#'+block.number.toString('hex'), '0x'+block.hash.toString('hex'));\n  console.log('================================');\n});\n\n// Handle network connectivity errors\nengine.on('error', function(err){\n  console.error('ProviderEngine error:', err.stack);\n});\n\n// Start the ProviderEngine\nengine.start();\n\n// Example usage: Make a simple request using web3.js\nweb3.eth.getChainId().then(chainId => {\n  console.log('Successfully connected to Chain ID:', chainId);\n}).catch(error => {\n  console.error('Failed to get Chain ID:', error);\n});\n\n// Keep the process alive for a short period to observe block events\n// In a real application, you would manage engine lifecycle based on usage.\nsetTimeout(() => {\n  console.log('Stopping ProviderEngine after 30 seconds.');\n  engine.stop();\n}, 30000);\n","lang":"javascript","description":"This quickstart demonstrates how to initialize `Web3 ProviderEngine`, configure a stack of diverse subproviders including caching, filtering, a mocked wallet, and an Infura-based RPC data source. It then connects the engine to a `Web3.js` instance, showcases basic event handling for new blocks, and makes a sample `eth_chainId` RPC request, emphasizing the modular design and the requirement for an Infura API key since version 16.0.0."},"warnings":[{"fix":"Plan a migration strategy to the `@metamask/json-rpc-engine` ecosystem. The `web3-provider-engine` README provides an example of how to recreate similar functionality with the modern MetaMask packages.","message":"This package has been officially deprecated since version 17.0.0 (March 2023). It is no longer actively maintained. All users are strongly advised to migrate to the recommended `@metamask/json-rpc-engine` and related packages for continued support, security updates, and new features.","severity":"breaking","affected_versions":">=17.0.0"},{"fix":"Upgrade your Node.js environment to version 16.20, 18.16, 20, or newer, as specified in the package's `engines` field.","message":"Version 17.0.0 increased the minimum required Node.js version to 16. Applications running on older Node.js versions (e.g., 14 or lower) will encounter runtime errors or fail to install.","severity":"breaking","affected_versions":">=17.0.0"},{"fix":"Obtain an API key from Infura.io and ensure it is passed in the `rpcUrl` when configuring `RpcSubprovider`, e.g., `rpcUrl: 'https://mainnet.infura.io/v3/YOUR_API_KEY'`.","message":"Version 16.0.0 introduced a breaking change where the Infura provider (used via `RpcSubprovider`) now explicitly requires an API key for the Infura V3 API. Attempts to use Infura without a valid API key will result in RPC errors.","severity":"breaking","affected_versions":">=16.0.0"},{"fix":"Upgrade `web3-provider-engine` to version 16.0.7 or later to incorporate these security fixes.","message":"Multiple security vulnerabilities related to the `request` dependency were addressed in versions 16.0.6 and 16.0.7 by replacing it with the patched `@cypress/request`. Older versions may be exposed to known vulnerabilities.","severity":"gotcha","affected_versions":"<16.0.6"},{"fix":"Upgrade `web3-provider-engine` to version 16.0.4 or later to mitigate this vulnerability.","message":"A security vulnerability discovered in the `cross-fetch` dependency was patched in version 16.0.4. Applications using older versions could be at risk.","severity":"gotcha","affected_versions":"<16.0.4"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"For CommonJS modules, use `require` syntax: `const ProviderEngine = require('web3-provider-engine');`. For ESM compatibility, use the `import * as` syntax: `import * as ProviderEngine from 'web3-provider-engine';`.","cause":"This error typically occurs when attempting to import `ProviderEngine` using named ESM import syntax (e.g., `import { ProviderEngine } from 'web3-provider-engine';`) in an ESM module, but the package is a CommonJS module with a default export.","error":"TypeError: ProviderEngine is not a constructor"},{"fix":"Ensure you have an Infura API key and include it in the `rpcUrl` configuration for `RpcSubprovider`, e.g., `rpcUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID'`.","cause":"Using `RpcSubprovider` to connect to Infura after `web3-provider-engine` v16.0.0 without providing a valid Infura API key.","error":"Error: Invalid JSON RPC response: {\"jsonrpc\":\"2.0\",\"error\":{\"code\":-32003,\"message\":\"project ID is required\"}}"},{"fix":"Upgrade your Node.js environment to a compatible version (e.g., Node.js 16.20, 18.16, 20, or newer) as indicated in the package's `engines` field.","cause":"Attempting to run `web3-provider-engine` version 17.0.0 or higher on an unsupported Node.js version, as the minimum requirement was increased.","error":"Node.js version must be ^16.20 || ^18.16 || >=20"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}