From 441d39baf6100a47ed1b73dafffa1403d53c576b Mon Sep 17 00:00:00 2001 From: Konstantina Blazhukova Date: Tue, 7 Jan 2025 16:23:06 +0200 Subject: [PATCH] Addresses some comments Signed-off-by: Konstantina Blazhukova --- docs/design/additional-endpoints.md | 158 +++++++++++++++++++--------- 1 file changed, 111 insertions(+), 47 deletions(-) diff --git a/docs/design/additional-endpoints.md b/docs/design/additional-endpoints.md index 751f7aaabd..befe492fab 100644 --- a/docs/design/additional-endpoints.md +++ b/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