Addresses some comments

Signed-off-by: Konstantina Blazhukova <[email protected]>

docs/design/additional-endpoints.md

@@ -1,67 +1,131 @@
-# Design Document: ERC20/ERC721/ERC1155 Token Transfer Events API, Tokens Owned by an Address
+# Block Explorer API Support
 
 ## Overview
-- This document outlines the design for implementing new endpoints allowing exposure of more EVM centric data, similar to Etherscan's and BlockScout's APIs.
-+ The endpoints will support:
-+ - ERC20 token transfers 
-+ - ERC721 NFT transfers
-+ - ERC1155 multi-token transfers
-+ - Tokens owned by an address
 
-## Problem Statement
-- Currently MN doesn't support EVM centric queries, like token transfer events for specific standards like ERC20, ERC721, ERC1155 or balance of an address for a specific token.
+This document outlines the design for implementing new package for REST API endpoints allowing exposure of more EVM centric data that support Block Explorer (e.g. Etherscan, BlockScout) API needs.
+
+The endpoints will support:
+*  ERC20 token transfers 
+*  ERC721 NFT transfers
+* ERC1155 multi-token transfers (TBD)
+*  Tokens owned by an address (TBD)
+
+## Problem Statement
+
+Currently MN doesn't support EVM centric queries, like token transfer events for specific standards like ERC20, ERC721, ERC1155 or balance of an address for a specific token.
 
 ## Goals
-- Provide API endpoints to fetch token transfer events
-+ - Support filtering by sender address
-+ - Support filtering by block range
-+ - Support filtering by specific token contract
-+ - Support ERC20, ERC721, and ERC1155 token standards
-- Match Etherscan's response format for easy integration
-- Maintain performance with large datasets
-- Provide endpoints to fetch tokens owned by an address
+*  Provide API endpoints to fetch token transfer events
+*  Support filtering by sender address
+*  Support filtering by block range
+*  Support filtering by specific token contract
+*  Support ERC20, ERC721, and ERC1155 token standards
+*  Match Etherscan's response format for easy integration
+*  Maintain performance with large datasets
+*  Provide endpoints to fetch tokens owned by an address
+
+## Non-Goals
+*  Support all Blockscout and Etherscan API endpoints
+*  Support other events except for Transfer events
+
+## Proposed Solution
 
-## Proposed Solution
+Introduce a new package `rest-api` with two new REST endpoints:
 
-### Overview
+- `GET /api/token/transfers?standard={standard}&address={address}&contractaddress={contractAddress}&startblock={blockNum}&endblock={blockNum}&page={page}&offset={offset}&sort={asc|desc}` - to fetch token transfer events
+- `GET /api/account/{address}/tokens?page={page}&offset={offset}` - to fetch tokens owned by an address (TBD)
+
+The package will be a standalone package with no relay dependencies, its own mirror node client implementation and its own cache service conncting to redis.
+This allows for a more modular and scalable solution, with the ability to easily add more endpoints in the future.
+
+### Package Structure
+```
+ packages/
+   rest-api/
+     └── src/
+         ├── config/           # Configuration for REST API
+         │   ├── index.ts
+         │   └── mirrorNode.ts # Mirror Node configuration
+         ├── controllers/
+         │   ├── tokenController.ts
+         │   └── accountController.ts
+         ├── routes/
+         │   ├── tokenRoutes.ts
+         │   └── accountRoutes.ts
+         ├── types/
+         │   ├── index.ts
+         │   └── mirrorNode.ts # Mirror Node types
+         ├── services/
+         │   ├── cacheService/
+         │   │   └── index.ts
+         │   ├── tokenService/
+         │   │   ├── index.ts
+         │   │   └── interfaces.ts
+         │   ├── accountService/
+         │   │   ├── index.ts
+         │   │   └── interfaces.ts
+         │   └── mirrorNode/   # Mirror Node client implementation
+         │       ├── client.ts
+         │       ├── types.ts
+         │       └── utils.ts
+         ├── middleware/
+         │   ├── validation.ts
+         │   ├── errorHandler.ts
+         │   ├── rateLimiter.ts
+         │   └── cache.ts
+         ├── app.ts           # Express/Koa app setup
+         └── index.ts
+     ├── package.json
+     └── tsconfig.json
+```
 
-Introduce two new endpoints:
-- `getTokenTransfers` - to fetch token transfer events
-- `getTokensOwnedByAddress` - to fetch tokens owned by an address (TBD)
+### Endpoint `GET /api/token/transfers`
 
-##  `getTokenTransfers`
+### Main Components
 
-### Components
+#### 1. TokenController
+Main controller handling HTTP requests:
+- Validates request parameters
+- Handles response formatting
+- Manages error responses
+- Implements rate limiting (TBD)
 
-#### 1. EthImpl
-Main service class handling token transfer event logic:
-- Validates block ranges
-- Filters logs for token transfer events
-- Checks the contracts in the MN response for the token standard needed
-- Transforms logs to transfer events format
+#### 2. TokenService
+Core business logic service:
+- Processes token transfer requests
+- Handles token standard detection
+- Manages data transformation
+- Coordinates with other services
 
-#### 2. CommonService Integration
-Utilizes existing CommonService for:
-- Block range validation
-- Timestamp parameter handling
+#### 3. MirrorNodeClient
+Custom client for Mirror Node interaction:
+- Handles HTTP requests to Mirror Node
 
-#### 3. MirrorNodeClient Integration
-Uses MirrorNodeClient for:
-- Fetching contract logs
-- Block information retrieval
+#### 4. CacheService
+Redis-based caching service:
+- Caches frequent queries
+- Manages cache invalidation
+- Handles cache hits/misses
+- Provides consistent caching strategy
 
 ### Data Flow
 ```mermaid
 sequenceDiagram
-    Client->>EthImpl: getTokenTransfers()
-    EthImpl->>CommonService: getLogs()
-    CommonService->>CommonService: getLogsWithParams()
-    CommonService->>MirrorNodeClient: getContractResultsLogs()
-    MirrorNodeClient->>CommonService: ''
-    CommonService->>EthImpl: ''
-    EthImpl->>EthImpl: getErcRegistry()
-    EthImpl->>EthImpl: checkContracts()
-    EthImpl->>Client: Return Response
+    Client->>REST API: GET /api/token/transfers
+    REST API->>CacheService: Check cache
+    alt Cache hit
+        CacheService->>REST API: Return cached data
+    else Cache miss
+        REST API->>TokenService: getTokenTransfers
+        TokenService->>MirrorNodeClient: getContractLogs
+        MirrorNodeClient->>Mirror Node: HTTP Request
+        Mirror Node->>MirrorNodeClient: HTTP Response
+        MirrorNodeClient->>TokenService: HTTP Response
+        TokenService->>TokenService: getErcRegistry
+        TokenService->>CacheService: Cache results
+        TokenService->>REST API: Return response
+    end
+    REST API->>Client: HTTP Response
 ```
 
 ### Technical Details