controller.ts

Overview

The [controller.ts](/projects/291/68853) file defines the `Proxy` controller class, which is a part of the Proxy API Service. This service acts as an intermediary layer that provides RESTful API endpoints, notably exposing an **address validation** endpoint. The controller leverages the `Elliptic` class to perform address validation by interacting with the Elliptic AML API.

This file's primary responsibility is to expose the [/api/v1/validate/{address}](/projects/291/69210) GET endpoint, which clients can call to verify the validity and risk status of a blockchain address. It handles request routing, response typing, validation annotations, and error handling using common API error classes.

Detailed Breakdown

Imports

• tsoa decorators and classes:
  Used to define routes, HTTP methods, response types, path parameters, and API documentation metadata.

• Error classes (BadRequestError, InternalServerError, ValidationError):
  Represent different API error responses that can be returned to clients.

• ValidationResult:
  The response model describing the result of address validation (e.g., { valid: boolean }).

• Elliptic:
  The class encapsulating address validation logic and interaction with the Elliptic AML API.

• handleError:
  A utility function to process errors and convert them into proper API error responses.

Class: Proxy

The `Proxy` class extends [Controller](/projects/291/69211) from tsoa and exposes the address validation endpoint.

Decorators:

• @Route('api/v1'):
  Declares the base route path for all endpoints in this controller.

Method: validateAddress

async validateAddress(@Path() address: string): Promise<ValidationResult>

• Purpose:
  Validates a blockchain address by querying the Elliptic AML API and returns whether the address is considered valid.

• Parameters:

  • address (string): The blockchain address to validate. It is extracted from the URL path parameter.

• Returns:

  • Promise<ValidationResult>: An object indicating the validation result, typically { valid: boolean }.

• Decorators:

  • @Get('/validate/{address}'):
    Defines a GET HTTP method and URL path with the address as a path parameter.

  • @Path():
    Marks the address parameter as coming from the route path.

  • @Example<ValidationResult>({ valid: true }):
    Provides an example response for API documentation.

  • @Response<BadRequestError>(400, 'Bad Request'):
    Documents that a 400 status code with this error type may be returned.

  • @Response<ValidationError>(422, 'Validation Error'):
    Documents that a 422 status code may be returned on validation failure.

  • @Response<InternalServerError>(500, 'Internal Server Error'):
    Documents that a 500 status code may be returned on unexpected server errors.

  • @Tags('Validation'):
    Tags this endpoint under "Validation" in the API documentation.

• Implementation Details:

  • Calls elliptic.validateAddress(address) asynchronously, which performs the validation logic including caching and AML API interaction.

  • Wraps the call in a try-catch block to handle errors gracefully by passing them to handleError, which converts exceptions into meaningful API responses.

• Usage Example:

const proxy = new Proxy();

proxy.validateAddress('0x1234abcd...').then(result => {
  console.log(result.valid ? 'Address is valid' : 'Address is invalid');
}).catch(err => {
  console.error('Validation failed:', err);
});

Important Implementation Details

• Address validation logic is delegated to the Elliptic class instance (elliptic), which contains the business logic for verifying the address against the AML provider.

• Error handling is centralized by using a common handleError function that interprets and throws API-specific error types, ensuring consistent error responses.

• The controller uses tsoa decorators extensively to provide automatic API documentation generation, type validation, and routing.

• The controller itself does not implement caching or direct API calls; it acts as a thin layer exposing the core validation service.

Interaction with Other Modules

• elliptic.ts:
  The controller depends on the Elliptic class from this file to perform address validation. This separation keeps the controller focused on API concerns, while elliptic.ts handles external API communication, caching, and validation logic.

• models.ts:
  Provides the ValidationResult model defining the structure of the validation response.

• common-api error classes:
  Used to standardize error responses across the API.

• Express app (app.ts):
  Registers this controller's routes and integrates it within the overall HTTP server.

Mermaid Class Diagram

The following class diagram shows the structure of the `Proxy` controller class, its method, and its relationship with the `Elliptic` instance.

classDiagram
    class Proxy {
        +validateAddress(address: string): Promise<ValidationResult>
    }
    class Elliptic {
        +validateAddress(address: string): Promise<ValidationResult>
    }
    Proxy --> Elliptic : uses

Summary

• File Role: Defines the API controller for address validation endpoint.

• Main Functionality: Exposes /api/v1/validate/{address} GET endpoint to validate blockchain addresses.

• Key Class: Proxy controller.

• Key Method: validateAddress(address: string).

• Delegation: Uses Elliptic class for the validation logic.

• Error Handling: Uses handleError to translate exceptions into API errors.

• API Documentation: Uses tsoa decorators for route, responses, tags, and examples.

• Integration: Part of the Proxy API Service handling address validation as one aspect of the broader proxy functionality.

This file acts as the entry point for clients seeking address validation services, providing a clean, well-documented REST interface that abstracts the complexities of AML checks and caching handled elsewhere in the system.