Example Plugin Implementation

CHANGELOG.md

@@ -739,6 +739,9 @@ should use 4.0.1-alpha.0 for testing.
 #### web3-core
 
 -   If the response error was `execution reverted`, raise `ContractExecutionError` and pass the response error to it in order to be set as `innerError` (this innerError will be decoded at web3-eth-contract if its ABI was provided according to EIP-838). (#5434)
+-   `registerPlugin` method to `Web3Context` (#5393)
+-   `Web3PluginBase` exported abstract class (#5393)
+-   `Web3EthPluginBase` exported abstract class (#5393)
 
 #### web3-error
 
@@ -749,6 +752,7 @@ should use 4.0.1-alpha.0 for testing.
 -   Added `SignatureError` to `web3-errors/src/errors/signature_errors.ts` (moved from `web3-eth/src/errors.ts`) (#5462)
 -   Added the errors' classes to `web3-errors/src/errors/transaction_errors.ts` from `web3-eth/src/errors.ts` (#5462)
 -   Added `TransactionBlockTimeoutError` class and its error code `ERR_TX_BLOCK_TIMEOUT` (#5294)
+-   `ExistingPluginNamespaceError` class and it's error code `ERR_EXISTING_PLUGIN_NAMESPACE` (#5393)
 
 #### web3-eth
 
@@ -765,12 +769,22 @@ should use 4.0.1-alpha.0 for testing.
 -   Decoding error data, using Error ABI if available, according to EIP-838. (#5434)
 -   The class `Web3ContractError` is moved from this package to `web3-error`. (#5434)
 
+#### web3-plugin-example
+
+-   Example plugin for wrapping contract methods to provide custom functionality (#5393)
+-   Example plugin for custom RPC methods using the `requestManager` (#5393)
+
 #### web3-utils
 
 -   Added and exported three reusable utility functions: `pollTillDefined`, `rejectIfTimeout` and `rejectIfConditionAtInterval` which are useful when dealing with promises that involves polling, rejecting after timeout or rejecting if a condition was met when calling repeatably at every time intervals.
 
 ### Changed
 
+#### web3-core
+
+-   Default value for `API` generic for `Web3ContextObject` from `any` to `unknown` (#5393)
+-   Default value for `API` generic for `Web3ContextInitOptions` from `any` to `unknown` (#5393)
+
 #### web3-error
 
 -   Moved `SignerError` from `web3-errors/src/errors/signature_errors.ts` to `web3-errors/src/errors/transaction_errors.ts`, and renamed it to `TransactionSigningError` (#5462)
@@ -789,6 +803,10 @@ should use 4.0.1-alpha.0 for testing.
 
 -   Return `BigInt` instead of `string` when decoding function parameters for large numbers, such as `uint256`. (#5435)
 
+#### web3-types
+
+-   `Web3APISpec`, `Web3APIMethod`, and `Web3APIParams` now supports `unknown` APIs (#5393)
+
 ### Removed
 
 #### web3-eth

packages/web3-core/CHANGELOG.md

@@ -40,6 +40,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 -   If the response error was `execution reverted`, raise `ContractExecutionError` and pass the response error to it in order to be set as `innerError` (this innerError will be decoded at web3-eth-contract if its ABI was provided according to EIP-838). (#5434)
+-   `registerPlugin` method to `Web3Context` (#5393)
+-   `Web3PluginBase` exported abstract class (#5393)
+-   `Web3EthPluginBase` exported abstract class (#5393)
 
+### Changed
+
+-   Default value for `API` generic for `Web3ContextObject` from `any` to `unknown` (#5393)
+-   Default value for `API` generic for `Web3ContextInitOptions` from `any` to `unknown` (#5393)
 -   Added validation when `defaultHardfork` and `defaultCommon.hardfork` are different in web3config
 -   Added validation when `defaultChain` and `defaultCommon.basechain` are different in web3config

packages/web3-core/src/web3_context.ts

@@ -14,16 +14,19 @@ GNU Lesser General Public License for more details.
 You should have received a copy of the GNU Lesser General Public License
 along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
-
+// eslint-disable-next-line max-classes-per-file
 import {
 	Web3APISpec,
 	Web3BaseWallet,
 	Web3BaseWalletAccount,
 	Web3AccountProvider,
 	SupportedProviders,
 	HexString,
+	EthExecutionAPI,
 } from 'web3-types';
 import { isNullish } from 'web3-utils';
+import { ExistingPluginNamespaceError } from 'web3-errors';
+
 import { isSupportedProvider } from './utils';
 // eslint-disable-next-line import/no-cycle
 import { Web3Config, Web3ConfigEvent, Web3ConfigOptions } from './web3_config';
@@ -34,8 +37,7 @@ import { Web3BatchRequest } from './web3_batch_request';
 
 // To avoid circular dependencies, we need to export type from here.
 export type Web3ContextObject<
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	API extends Web3APISpec = any,
+	API extends Web3APISpec = unknown,
 	RegisteredSubs extends {
 		[key: string]: Web3SubscriptionConstructor<API>;
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -52,8 +54,7 @@ export type Web3ContextObject<
 };
 
 export type Web3ContextInitOptions<
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	API extends Web3APISpec = any,
+	API extends Web3APISpec = unknown,
 	RegisteredSubs extends {
 		[key: string]: Web3SubscriptionConstructor<API>;
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -68,23 +69,22 @@ export type Web3ContextInitOptions<
 	wallet?: Web3BaseWallet<Web3BaseWalletAccount>;
 };
 
-export type Web3ContextConstructor<
-	// eslint-disable-next-line no-use-before-define, @typescript-eslint/no-explicit-any
-	T extends Web3Context<any>,
-	T2 extends unknown[],
-> = new (...args: [...extras: T2, context: Web3ContextObject]) => T;
+// eslint-disable-next-line no-use-before-define
+export type Web3ContextConstructor<T extends Web3Context, T2 extends unknown[]> = new (
+	...args: [...extras: T2, context: Web3ContextObject]
+) => T;
 
 // To avoid circular dependencies, we need to export type from here.
 export type Web3ContextFactory<
-	// eslint-disable-next-line no-use-before-define, @typescript-eslint/no-explicit-any
-	T extends Web3Context<any>,
+	// eslint-disable-next-line no-use-before-define
+	T extends Web3Context,
 	T2 extends unknown[],
 > = Web3ContextConstructor<T, T2> & {
 	fromContextObject(this: Web3ContextConstructor<T, T2>, contextObject: Web3ContextObject): T;
 };
 
 export class Web3Context<
-	API extends Web3APISpec,
+	API extends Web3APISpec = unknown,
 	RegisteredSubs extends {
 		[key: string]: Web3SubscriptionConstructor<API>;
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -172,7 +172,7 @@ export class Web3Context<
 	}
 
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	public static fromContextObject<T extends Web3Context<any>, T3 extends unknown[]>(
+	public static fromContextObject<T extends Web3Context, T3 extends unknown[]>(
 		this: Web3ContextConstructor<T, T3>,
 		...args: [Web3ContextObject, ...T3]
 	) {
@@ -198,8 +198,7 @@ export class Web3Context<
 	 * and link it to current context. This can be used to initiate a global context object
 	 * and then use it to create new objects of any type extended by `Web3Context`.
 	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	public use<T extends Web3Context<any>, T2 extends unknown[]>(
+	public use<T extends Web3Context, T2 extends unknown[]>(
 		ContextRef: Web3ContextConstructor<T, T2>,
 		...args: [...T2]
 	) {
@@ -218,7 +217,7 @@ export class Web3Context<
 	/**
 	 * Link current context to another context.
 	 */
-	public link<T extends Web3Context<API, RegisteredSubs>>(parentContext: T) {
+	public link<T extends Web3Context>(parentContext: T) {
 		this.setConfig(parentContext.getConfig());
 		this._requestManager = parentContext.requestManager;
 		this.provider = parentContext.provider;
@@ -232,6 +231,19 @@ export class Web3Context<
 		});
 	}
 
+	// eslint-disable-next-line no-use-before-define
+	public registerPlugin(plugin: Web3PluginBase) {
+		// @ts-expect-error No index signature with a parameter of type 'string' was found on type 'Web3Context<API, RegisteredSubs>'
+		if (this[plugin.pluginNamespace] !== undefined)
+			throw new ExistingPluginNamespaceError(plugin.pluginNamespace);
+
+		const _pluginObject = {
+			[plugin.pluginNamespace]: plugin,
+		};
+		_pluginObject[plugin.pluginNamespace].link(this);
+		Object.assign(this, _pluginObject);
+	}
+
 	public get provider(): SupportedProviders<API> | string | undefined {
 		return this.requestManager.provider;
 	}
@@ -268,11 +280,52 @@ export class Web3Context<
 
 // To avoid cycle dependency declare this type in this file
 // TODO: When we have `web3-types` package we can share TransactionType
-export type TransactionBuilder<
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	API extends Web3APISpec = any,
-> = <ReturnType = Record<string, unknown>>(options: {
+export type TransactionBuilder<API extends Web3APISpec = unknown> = <
+	ReturnType = Record<string, unknown>,
+>(options: {
 	transaction: Record<string, unknown>;
 	web3Context: Web3Context<API>;
 	privateKey?: HexString | Buffer;
 }) => Promise<ReturnType>;
+
+/**
+ * Extend this class when creating a plugin that either doesn't require {@link EthExecutionAPI},
+ * or interacts with a RPC node that doesn't fully implement {@link EthExecutionAPI}.
+ *
+ * To add type support for RPC methods to the {@link Web3RequestManager},
+ * define a {@link Web3APISpec} and pass it as a generic to Web3PluginBase like so:
+ *
+ * ```ts
+ * type CustomRpcApi = {
+ *	custom_rpc_method: () => string;
+ *	custom_rpc_method_with_parameters: (parameter1: string, parameter2: number) => string;
+ * };
+ *
+ * class CustomPlugin extends Web3PluginBase<CustomRpcApi> {...}
+ * ```
+ */
+export abstract class Web3PluginBase<
+	API extends Web3APISpec = Web3APISpec,
+> extends Web3Context<API> {
+	public abstract pluginNamespace: string;
+}
+
+/**
+ * Extend this class when creating a plugin that makes use of {@link EthExecutionAPI},
+ * or depends on other Web3 packages (such as `web3-eth-contract`) that depend on {@link EthExecutionAPI}.
+ *
+ * To add type support for RPC methods to the {@link Web3RequestManager} (in addition to {@link EthExecutionAPI}),
+ * define a {@link Web3APISpec} and pass it as a generic to Web3PluginBase like so:
+ *
+ * ```ts
+ * type CustomRpcApi = {
+ *	custom_rpc_method: () => string;
+ *	custom_rpc_method_with_parameters: (parameter1: string, parameter2: number) => string;
+ * };
+ *
+ * class CustomPlugin extends Web3PluginBase<CustomRpcApi> {...}
+ * ```
+ */
+export abstract class Web3EthPluginBase<API extends Web3APISpec = unknown> extends Web3PluginBase<
+	API & EthExecutionAPI
+> {}

packages/web3-core/test/unit/web3_context.test.ts

@@ -16,8 +16,9 @@ along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 // eslint-disable-next-line max-classes-per-file
+import { ExistingPluginNamespaceError } from 'web3-errors';
 import HttpProvider from 'web3-providers-http';
-import { Web3Context } from '../../src/web3_context';
+import { Web3Context, Web3PluginBase } from '../../src/web3_context';
 import { Web3RequestManager } from '../../src/web3_request_manager';
 
 // eslint-disable-next-line @typescript-eslint/ban-types
@@ -201,4 +202,23 @@ describe('Web3Context', () => {
 			expect(child.provider).toBe(parent.provider);
 		});
 	});
+
+	describe('registerPlugin', () => {
+		it('should throw ExistingPluginNamespaceError', () => {
+			const context = new Context1('http://test/abc');
+			const pluginNamespace = 'plugin';
+
+			class Plugin extends Web3PluginBase {
+				public pluginNamespace = pluginNamespace;
+			}
+			class Plugin2 extends Web3PluginBase {
+				public pluginNamespace = pluginNamespace;
+			}
+
+			context.registerPlugin(new Plugin());
+			expect(() => context.registerPlugin(new Plugin2())).toThrow(
+				new ExistingPluginNamespaceError(pluginNamespace),
+			);
+		});
+	});
 });

packages/web3-errors/CHANGELOG.md

@@ -46,6 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Added `SignatureError` to `web3-errors/src/errors/signature_errors.ts` (moved from `web3-eth/src/errors.ts`) (#5462)
 -   Added the errors' classes to `web3-errors/src/errors/transaction_errors.ts` from `web3-eth/src/errors.ts` (#5462)
 -   Added `TransactionBlockTimeoutError` class and its error code `ERR_TX_BLOCK_TIMEOUT` (#5294)
+-   `ExistingPluginNamespaceError` class and it's error code `ERR_EXISTING_PLUGIN_NAMESPACE` (#5393)
 
 ### Changed
 

packages/web3-errors/src/error_codes.ts

@@ -26,6 +26,7 @@ export const ERR_METHOD_NOT_IMPLEMENTED = 202;
 export const ERR_OPERATION_TIMEOUT = 203;
 export const ERR_OPERATION_ABORT = 204;
 export const ERR_ABI_ENCODING = 205;
+export const ERR_EXISTING_PLUGIN_NAMESPACE = 206;
 
 // Contract error codes
 export const ERR_CONTRACT = 300;

packages/web3-errors/src/errors/generic_errors.ts

@@ -24,6 +24,7 @@ import {
 	ERR_OPERATION_ABORT,
 	ERR_OPERATION_TIMEOUT,
 	ERR_PARAM,
+	ERR_EXISTING_PLUGIN_NAMESPACE,
 } from '../error_codes';
 import { Web3Error } from '../web3_error_base';
 
@@ -67,3 +68,11 @@ export class OperationAbortError extends Web3Error {
 export class AbiError extends Web3Error {
 	public code = ERR_ABI_ENCODING;
 }
+
+export class ExistingPluginNamespaceError extends Web3Error {
+	public code = ERR_EXISTING_PLUGIN_NAMESPACE;
+
+	public constructor(pluginNamespace: string) {
+		super(`A plugin with the namespace: ${pluginNamespace} has already been registered.`);
+	}
+}

packages/web3-eth/test/integration/defaults.test.ts

@@ -693,7 +693,7 @@ describe('defaults', () => {
 					value: '0x174876e800',
 					gas: '0x5208',
 				},
-				web3Context: eth2 as Web3Context<any>,
+				web3Context: eth2 as Web3Context,
 			});
 			expect(res.networkId).toBe(4);
 
@@ -706,7 +706,7 @@ describe('defaults', () => {
 					gas: '0x5208',
 					networkId: 5,
 				},
-				web3Context: eth2 as Web3Context<any>,
+				web3Context: eth2 as Web3Context,
 			});
 
 			expect(resWithPassNetworkId.networkId).toBe(BigInt(5));
@@ -736,7 +736,7 @@ describe('defaults', () => {
 					value: '0x174876e800',
 					gas: '0x5208',
 				},
-				web3Context: eth2 as Web3Context<any>,
+				web3Context: eth2 as Web3Context,
 			});
 			expect(res.chain).toBe('rinkeby');
 		});

packages/web3-types/CHANGELOG.md

@@ -42,3 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   `Web3EthExecutionAPI` export (#5441)
 -   `Web3NetAPI` export (#5441)
 -   `EthPersonalAPI` export (#5441)
+
+### Changed
+
+-   `Web3APISpec`, `Web3APIMethod`, and `Web3APIParams` now supports `unknown` APIs (#5393)

packages/web3-types/src/web3_api_types.ts

@@ -17,12 +17,12 @@ along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 
 import { JsonRpcId, JsonRpcIdentifier } from './json_rpc_types';
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type Web3APISpec = Record<string, (...params: any) => any>;
-export type Web3APIMethod<T extends Web3APISpec> = string & keyof T;
-export type Web3APIParams<API extends Web3APISpec, Method extends Web3APIMethod<API>> = Parameters<
-	API[Method]
->;
+export type Web3APISpec = Record<string, (...params: any) => any> | unknown;
+export type Web3APIMethod<T extends Web3APISpec> = string & keyof Exclude<T, unknown>;
+export type Web3APIParams<
+	API extends Web3APISpec,
+	Method extends Web3APIMethod<API>,
+> = API extends Exclude<Web3APISpec, unknown> ? Parameters<API[Method]> : unknown;
 
 export interface Web3APIRequest<API extends Web3APISpec, Method extends Web3APIMethod<API>> {
 	method: Method;
@@ -38,4 +38,4 @@ export interface Web3APIPayload<API extends Web3APISpec, Method extends Web3APIM
 export type Web3APIReturnType<
 	API extends Web3APISpec,
 	Method extends Web3APIMethod<API>,
-> = ReturnType<API[Method]>;
+> = API extends Record<string, (...params: any) => any> ? ReturnType<API[Method]> : any;

packages/web3/src/web3.ts

@@ -31,7 +31,7 @@ import { initAccountsForContext } from './accounts';
 import { Web3EthInterface } from './types';
 import { Web3PkgInfo } from './version';
 
-export default class Web3 extends Web3Context<EthExecutionAPI> {
+export class Web3 extends Web3Context<EthExecutionAPI> {
 	public static version = Web3PkgInfo.version;
 	public static utils = utils;
 	public static modules = {
@@ -128,3 +128,4 @@ export default class Web3 extends Web3Context<EthExecutionAPI> {
 		});
 	}
 }
+export default Web3;