Address Validation

Purpose

Address Validation addresses the specific need to assess blockchain addresses for potential risk and legitimacy within the Proxy API Service. This subtopic integrates with the Elliptic Anti-Money Laundering (AML) service to provide automated, risk-based validation of blockchain addresses. By doing so, it helps clients and downstream services identify whether an address might be associated with illicit activities, such as fraud or money laundering, which is essential for compliance and security in blockchain interactions.

Functionality

This feature implements a seamless workflow to query Elliptic's AML API and cache the results for efficiency:

1. Address Query: When a client requests validation for a blockchain address via the Proxy API, the system first checks an internal cache to avoid redundant external calls.

2. Elliptic AML Request: If no cached result exists, the system sends a synchronous POST request to Elliptic's /v2/wallet/synchronous endpoint with the address details. The request specifies a "wallet_exposure" type to retrieve risk scoring.

3. Risk Scoring Evaluation: The response includes a risk_score value. If this score meets or exceeds a defined threshold (default is 1), the address is considered invalid (high risk). Otherwise, it is valid.

4. Cache Management: Validation results are cached for 6 hours to improve performance and reduce external API usage. Cache entries are automatically cleared after this TTL.

5. Error Handling: If Elliptic returns a 404 with a specific message indicating the address is not found on the blockchain, the system treats the address as valid, deferring further validation responsibility to the client.

Key Methods and Data Flow

• The Elliptic class encapsulates this logic, maintaining an AML client instance and an address cache.

• The validateAddress(address: string): Promise<{ valid: boolean }> method orchestrates the validation process described above.

Example snippet illustrating the validation check and caching:

async validateAddress(address: string): Promise<{ valid: boolean }> {
  const cached = this.addressCache[address]
  if (cached !== undefined) return { valid: cached }

  // ... call Elliptic AML API ...

  this.addressCache[address] = riskScoreValid
  return { valid: riskScoreValid }
}

• The Proxy API controller exposes this functionality via an HTTP GET endpoint /api/v1/validate/{address}, forwarding requests to the Elliptic instance and returning the validation result.

Integration

Address Validation is a critical subcomponent of the Proxy API Service, complementing other subtopics such as External API Proxy. It provides a specialized security layer by validating addresses before they are used in proxy or external API interactions, thereby enhancing trustworthiness and compliance.

• It abstracts Elliptic AML's complexity behind a simple REST interface, enabling other system components or clients to perform risk assessments without direct integration.

• The caching mechanism improves overall system performance and reduces latency in the Proxy API responses compared to calling Elliptic's service on every request.

• By delegating error and edge case handling (e.g., unknown addresses) gracefully, it supports robustness and reliability in the broader Proxy API ecosystem.

Diagram

The following sequence diagram visualizes the core validation workflow from client request to Elliptic API interaction and cache usage:

sequenceDiagram
    participant Client
    participant ProxyAPI
    participant EllipticAML

    Client->>ProxyAPI: GET /api/v1/validate/{address}
    ProxyAPI->>ProxyAPI: Check cache for address
    alt Cache hit
        ProxyAPI-->>Client: Return cached validation result
    else Cache miss
        ProxyAPI->>EllipticAML: POST /v2/wallet/synchronous { address }
        EllipticAML-->>ProxyAPI: Wallet response with risk_score
        ProxyAPI->>ProxyAPI: Evaluate risk_score >= threshold?
        ProxyAPI->>ProxyAPI: Cache validation result (valid or invalid)
        ProxyAPI-->>Client: Return validation result
    end

This flow ensures efficient and timely validation responses while maintaining a clear separation between external AML service calls and client-facing API endpoints.