feat: implemented decorator-based RPC method dispatcher and parameter handling system

[quiet-node]

Overview

This PR introduces a fully decorator-based API architecture for JSON-RPC method handling. It provides a centralized solution that ensures a clean, type-safe approach to defining, exposing, validating, and dispatching RPC methods across the Relay package.

Key Components

New Single & Centralized API Entry Point

• RpcMethodDispatcher is a centralized and robust class that serves as the sole public API entry point for server packages and all consumers. It provides a structured solution for executing RPC methods by autonomously validating requests and routing them to the appropriate operation handler.
• Streamlined request handling flow, incorporating pre-execution method validation, execution, and error-handling phases.
• Standardized response format, ensuring that methods either return a valid result or throw a JsonRpcError back to consumers.

// RpcMethodDispatcher used in Relay to create the signle API Entry Point
// relay.ts
public async executeRpcMethod(
    rpcMethodName: string,
    rpcMethodParams: any,
    requestDetails: RequestDetails,
): Promise<any> {
    return this.rpcMethodDispatcher.dispatch(rpcMethodName, rpcMethodParams, requestDetails);
}


// Usage from server or other consumer
// koaJsonRpc.ts in Server package
const result = await relay.executeRpcMethod('eth_getBalance', ['0x123...', 'latest'], requestId);

Decorator-Based Components

• @rpcMethod annotates methods for RPC exposure and automatic registration.
• @rpcParamValidationRules defines validation rules for method parameters, ensuring data integrity.
• @rpcParamLayoutConfig manages parameter arrangement and transformation for correct parameters layout.
• All decorators function cohesively to establish a declarative, self-documenting API.

// Class implementation with decorators
class EthImpl {
    // decorators usage
    @rpcMethod
    @rpcParamLayoutConfig(RPC_LAYOUT.REQUEST_DETAILS_ONLY)
    chainId(requestDetails: RequestDetails): string {
        // Implementation
    }

    @rpcMethod
    @rpcParamValidationRules({
      0: { type: 'blockHash', required: true },
      1: { type: 'boolean', required: false }
    })
    @rpcParamLayoutConfig(RPC_LAYOUT.custom((params) => [params[0], params[1]]))
    async estimateGas(
        transaction: IContractCallRequest,
        _blockParam: string | null,
        requestDetails: RequestDetails,
    ): Promise<string | JsonRpcError> {
        // Implementation
    }
}

Centralized Method Registry

• rpcMethodRegistry serves as the single source of truth for all RPC method implementations
• The method registerRpcMethod():
  • Scans implementation classes for methods decorated with @rpcMethod
  • Preserves validation rules from @rpcParamValidationRules for runtime parameter validation
  • Retains parameter layout configurations from @rpcParamLayoutConfig for correct invocation
  • Maps RPC method names to their implementations in a centralized registry

Parameter Handling

• Clean separation between validation and parameter structuring
• Autonomous parameter transformation based on method signature
• Support for special parameter layouts (request-details-only, custom params layout, etc.)
• Advanced parameter parsing for complex methods like traceTransaction

Server Package Simplification

• Eliminated Manual Method Registration:

  • Removed the logAndHandleResponse() and useRpc() pattern previously used to register RPC methods
  • Deleted route files (ethRoutes.ts, debugRoutes.ts, netRoutes.ts, etc.) as methods are now auto-registered in the Relay pacakge
  • Server no longer needs to maintain method mappings or handle routing logic

• Validator Migration:

  • Migrated the entire Validator service from Server package to Relay
  • Validator now works directly with @rpcParamValidationRules decorators
  • Validation happens automatically during the dispatch process
  • Simplified error handling with consistent response formats

Additional Context

Related issue(s): EPIC #3551

Fixes #3553
Fixes #3575

Notes for reviewer:

• The Validator service was migrated from the Server package to the Relay component by component, ensuring the preservation of validation logic.
• MirrorNodeClientError and SdkClientError are currently handled at the dispatcher only for timeout errors. A more comprehensive error mapping will be introduced in a follow-up PR for Stage 3.

Acknowledgments

Special kudos to @acuarica for initially proposing this approach and for the excellent work on the POC PR (#3548). His contributions laid the foundation for this implementation and significantly influenced the design of this PR.

[github-actions]

Test Results

 20 files   -  2  298 suites  +29   35m 4s ⏱️ - 34m 54s
623 tests  -  4  615 ✅ + 5  4 💤 ±0  4 ❌  -  9 
778 runs   - 92  768 ✅  - 81  6 💤 +2  4 ❌  - 13 

For more details on these failures, see this check.

Results for commit edc1a1c. ± Comparison against base commit 7f226e3.

♻️ This comment has been updated with latest results.

[acuarica]

Initial round of reviews, thanks for the effort! we are on good track.

[natanasow]

At first sight, it looks good. Thanks for the crazy amount of work you have already done 🚀.