controller.ts

Overview

`controller.ts` defines the API controller for interacting with the Arbitrum Nova blockchain network using EVM-compatible RPC calls. It provides RESTful endpoints for estimating gas costs (`POST /gas/estimate`) and retrieving current gas fee recommendations (`GET /gas/fees`).

This file acts as a specialized extension of a generic EVM controller tailored for the Arbitrum Nova network. It connects blockchain data indexing (via Blockbook), gas fee estimation (via a Gas Oracle), and RPC interaction to expose critical gas-related blockchain operations in a secure, validated API.

Key responsibilities include:

Environment configuration validation.
Initialization of blockchain clients and services.
Implementation of gas estimation and fee retrieval endpoints.
Integration with common EVM controller and service abstractions to maximize reuse.

Classes and Methods

`class ArbitrumNova extends EVM implements BaseAPI, API`

This class extends the generic `EVM` controller and implements interfaces [BaseAPI](/projects/291/69264) and `API`. It defines HTTP routes under `/api/v1` with `v1` tags, exposing methods for gas-related blockchain queries specific to Arbitrum Nova.

`estimateGas(body: EstimateGasBody): Promise<GasEstimate>`

Estimates the gas required for a transaction on the Arbitrum Nova network.

HTTP Method & Path: POST /api/v1/gas/estimate
Parameters:
- body (EstimateGasBody): Transaction details containing:
  - data (string): Hex-encoded transaction data.
  - from (string): Sender address.
  - to (string): Recipient address.
  - value (string): Amount of native tokens (wei).
Return: Promise resolving to a GasEstimate object containing:
- gasLimit (string): Estimated gas limit for the transaction.
Errors:
- 422 ValidationError if input validation fails.
- 500 InternalServerError for unexpected failures.
Usage Example:

POST /api/v1/gas/estimate
{
  "data": "0x",
  "from": "0x0000000000000000000000000000000000000000",
  "to": "0x6e249a692314bceb8ac43b296262df1800915bf4",
  "value": "1337"
}

Response:
{
  "gasLimit": "30641"
}

Implementation Details:
Delegates to the service.estimateGas method which interacts with the blockchain and gas oracle to compute the gas estimate.

`getGasFees(): Promise<GasFees>`

Retrieves the current recommended gas fees for transactions on the Arbitrum Nova network.

HTTP Method & Path: GET /api/v1/gas/fees
Parameters: None
Return: Promise resolving to a GasFees object, which includes:
- baseFeePerGas (string): Current base fee per gas unit.
- slow, average, fast (objects): Fee tiers with:
  - gasPrice (string)
  - maxFeePerGas (string)
  - maxPriorityFeePerGas (string)
Errors:
- 500 InternalServerError for unexpected failures.
Usage Example:

GET /api/v1/gas/fees

Response:
{
  "baseFeePerGas": "10000000",
  "slow": {
    "gasPrice": "1166100000",
    "maxFeePerGas": "1167100000",
    "maxPriorityFeePerGas": "1157100000"
  },
  "average": {
    "gasPrice": "1240550000",
    "maxFeePerGas": "1241050000",
    "maxPriorityFeePerGas": "1231050000"
  },
  "fast": {
    "gasPrice": "1240550000",
    "maxFeePerGas": "1241050000",
    "maxPriorityFeePerGas": "1231050000"
  }
}

Implementation Details:
Calls service.getGasFees() which queries the GasOracle for live fee data and formats it for response.

Important Implementation Details

Environment Variables:
The controller requires several critical environment variables and throws errors at startup if any are missing:
- ETHERSCAN_API_KEY - API key for Etherscan blockchain explorer.
- INDEXER_URL and INDEXER_WS_URL - URLs for the Blockbook HTTP and WebSocket indexers.
- NETWORK - Specifies the blockchain network.
- RPC_URL - RPC endpoint for JSON-RPC calls.
Clients and Services:
- client: Created using viem's createPublicClient for RPC calls to Arbitrum Nova.
- blockbook: Provides blockchain data indexing and transaction history access.
- gasOracle: Computes current gas fee estimates from network data.
- service: Combines the above clients with explorer API and logging to provide core logic.
Inheritance and Service Injection:
- The ArbitrumNova class inherits from the generic EVM controller.
- The service instance is assigned to the static EVM.service property, enabling reuse of EVM logic within Arbitrum Nova context.
API Documentation and Validation:
Uses decorators from tsoa for:
- Route definitions (@Route, @Post, @Get).
- Request/response schemas (@Body, @Response, @Example).
- Tagging for Swagger/OpenAPI generation.

Interaction with Other System Components

Common EVM Module:
Extends base controller and service classes from the shared EVM module (common/api/src/evm), promoting code reuse.
Blockbook Indexer:
Uses Blockbook for blockchain data retrieval, ensuring up-to-date transaction and block information.
Gas Oracle:
Integrates GasOracle for precise gas fee calculations, crucial for transaction cost estimations.
Logging:
Uses a namespaced logger instance for consistent logging across the Arbitrum Nova API components.
External APIs:
Connects to Etherscan APIs with an API key for supplementary blockchain explorer data.

Visual Diagram

classDiagram
    class ArbitrumNova {
        +estimateGas(body: EstimateGasBody): Promise<GasEstimate>
        +getGasFees(): Promise<GasFees>
    }
    class EVM {
        <<abstract>>
        +service: Service
    }
    class Service {
        -blockbook: Blockbook
        -gasOracle: GasOracle
        -explorerApiUrl: URL
        -client: PublicClient
        -logger: Logger
        +estimateGas(body: EstimateGasBody): Promise<GasEstimate>
        +getGasFees(): Promise<GasFees>
    }
    class Blockbook {
        -httpURL: string
        -wsURL: string
        -logger: Logger
    }
    class GasOracle {
        -logger: Logger
        -client: PublicClient
        -coinstack: string
    }
    class Logger {
        -namespace: string[]
        -level: string
    }
    class PublicClient {}

    ArbitrumNova --|> EVM
    EVM o-- Service
    Service *-- Blockbook
    Service *-- GasOracle
    Service *-- Logger
    Service *-- PublicClient
    Blockbook *-- Logger
    GasOracle *-- Logger
    GasOracle *-- PublicClient

Summary

`controller.ts` is a specialized Arbitrum Nova blockchain API controller that exposes gas estimation and fee retrieval endpoints. It leverages a modular service layer built on shared EVM components and integrates with blockchain indexers and gas oracles to provide accurate and reliable transaction cost data. This file is a critical part of the broader system's API layer, enabling clients to interact seamlessly with the Arbitrum Nova network through standardized REST endpoints.