diff --git a/packages/http-explorer-server/README.md b/packages/http-explorer-server/README.md new file mode 100644 index 000000000..7bfce90e0 --- /dev/null +++ b/packages/http-explorer-server/README.md @@ -0,0 +1,84 @@ +# Hedera HTTP Explorer Server + +This package provides REST API endpoints for exposing EVM-centric data from the Hedera network, similar to Etherscan's API. It supports querying token transfers for ERC20, ERC721, and ERC1155 tokens, as well as fetching tokens owned by an address. + +## Features + +- ERC20 token transfer events +- ERC721 NFT transfer events +- ERC1155 multi-token transfer events +- Tokens owned by an address +- Pagination support +- Block range filtering +- Address filtering +- Contract filtering + +## API Endpoints + +### Token Transfers + +Get ERC20 token transfers: +``` +GET /api?module=account&action=tokentx&address={address}&contractaddress={contractaddress}&startblock={startblock}&endblock={endblock}&page={page}&offset={offset}&sort={asc|desc} +``` + +Get ERC721 (NFT) token transfers: +``` +GET /api?module=account&action=tokennfttx&address={address}&contractaddress={contractaddress}&startblock={startblock}&endblock={endblock}&page={page}&offset={offset}&sort={asc|desc} +``` + +Get ERC1155 token transfers: +``` +GET /api?module=account&action=token1155tx&address={address}&contractaddress={contractaddress}&startblock={startblock}&endblock={endblock}&page={page}&offset={offset}&sort={asc|desc} +``` + +### Account Tokens + +Get tokens owned by an address: +``` +GET /api/account/{address}/tokens?page={page}&offset={offset} +``` + +## Installation + +```bash +npm install +npm run build +``` + +## Usage + +```bash +npm start +``` + +## Configuration + +The server can be configured through environment variables: + +- `PORT` - Server port (default: 3000) +- `HOST` - Server host (default: localhost) +- `RATE_LIMIT` - Rate limiting configuration +- `PAGINATION_DEFAULT_SIZE` - Default page size (default: 100) +- `PAGINATION_MAX_SIZE` - Maximum page size (default: 1000) +- `MAX_BLOCK_RANGE` - Maximum block range for queries (default: 1000) +- `REDIS_URL` - Redis connection URL for caching + +## Development + +```bash +# Install dependencies +npm install + +# Build +npm run build + +# Run tests +npm test + +# Lint +npm run lint + +# Fix linting issues +npm run lint:fix +``` diff --git a/packages/http-explorer-server/app.ts b/packages/http-explorer-server/app.ts new file mode 100644 index 000000000..c23949287 --- /dev/null +++ b/packages/http-explorer-server/app.ts @@ -0,0 +1,29 @@ +/*- + * + * Hedera JSON RPC Relay + * + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ + +import Koa from 'koa'; + +import { TokenRoutes } from './src/routes'; + +const app = new Koa(); + +app.use(TokenRoutes.routes()); + +export default app; diff --git a/packages/http-explorer-server/index.ts b/packages/http-explorer-server/index.ts new file mode 100644 index 000000000..8382e7816 --- /dev/null +++ b/packages/http-explorer-server/index.ts @@ -0,0 +1,26 @@ +/*- + * + * Hedera JSON RPC Relay + * + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ +import app from './app'; + +function main() { + app.listen(3000); +} + +main(); diff --git a/packages/http-explorer-server/package.json b/packages/http-explorer-server/package.json new file mode 100644 index 000000000..738c0d95c --- /dev/null +++ b/packages/http-explorer-server/package.json @@ -0,0 +1,35 @@ +{ + "name": "@hashgraph/http-explorer-server", + "version": "0.1.0", + "description": "HTTP server exposing Etherscan-like REST APIs for Hedera network", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "clean": "rimraf dist/", + "start": "node dist/index.js", + "lint": "eslint . --ext .ts", + "lint:fix": "eslint . --ext .ts --fix" + }, + "dependencies": { + "@hashgraph/json-rpc-relay": "file:../relay", + "@koa/cors": "^4.0.0", + "koa": "^2.14.2", + "koa-bodyparser": "^4.4.1", + "koa-router": "^12.0.0", + "pino": "^8.15.0", + "pino-pretty": "^10.2.0", + "prom-client": "^14.2.0" + }, + "devDependencies": { + "@types/koa": "^2.13.8", + "@types/koa__cors": "^4.0.0", + "@types/koa-bodyparser": "^4.3.10", + "@types/koa-router": "^7.4.4", + "@types/node": "^20.5.7", + "@typescript-eslint/eslint-plugin": "^6.5.0", + "@typescript-eslint/parser": "^6.5.0", + "eslint": "^8.48.0", + "rimraf": "^5.0.1", + "typescript": "^5.2.2" + } +} diff --git a/packages/http-explorer-server/src/config/config.ts b/packages/http-explorer-server/src/config/config.ts new file mode 100644 index 000000000..d0eba926f --- /dev/null +++ b/packages/http-explorer-server/src/config/config.ts @@ -0,0 +1,19 @@ +/*- + * + * Hedera JSON RPC Relay + * + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ diff --git a/packages/http-explorer-server/src/controllers/tokenController.ts b/packages/http-explorer-server/src/controllers/tokenController.ts new file mode 100644 index 000000000..d0eba926f --- /dev/null +++ b/packages/http-explorer-server/src/controllers/tokenController.ts @@ -0,0 +1,19 @@ +/*- + * + * Hedera JSON RPC Relay + * + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ diff --git a/packages/http-explorer-server/src/middleware/validator.ts b/packages/http-explorer-server/src/middleware/validator.ts new file mode 100644 index 000000000..d0eba926f --- /dev/null +++ b/packages/http-explorer-server/src/middleware/validator.ts @@ -0,0 +1,19 @@ +/*- + * + * Hedera JSON RPC Relay + * + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ diff --git a/packages/http-explorer-server/src/routes/index.ts b/packages/http-explorer-server/src/routes/index.ts new file mode 100644 index 000000000..ef3538b86 --- /dev/null +++ b/packages/http-explorer-server/src/routes/index.ts @@ -0,0 +1,20 @@ +/*- + * + * Hedera JSON RPC Relay + * + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ +export { TokenRoutes } from './tokenRoutes'; diff --git a/packages/http-explorer-server/src/routes/tokenRoutes.ts b/packages/http-explorer-server/src/routes/tokenRoutes.ts new file mode 100644 index 000000000..ba0a56322 --- /dev/null +++ b/packages/http-explorer-server/src/routes/tokenRoutes.ts @@ -0,0 +1,21 @@ +/*- + * + * Hedera JSON RPC Relay + * + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ + +class TokenRoutes {} diff --git a/packages/http-explorer-server/src/types/index.ts b/packages/http-explorer-server/src/types/index.ts new file mode 100644 index 000000000..d0eba926f --- /dev/null +++ b/packages/http-explorer-server/src/types/index.ts @@ -0,0 +1,19 @@ +/*- + * + * Hedera JSON RPC Relay + * + * Copyright (C) 2025 Hedera Hashgraph, LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ diff --git a/packages/http-explorer-server/tsconfig.json b/packages/http-explorer-server/tsconfig.json new file mode 100644 index 000000000..22cd79da8 --- /dev/null +++ b/packages/http-explorer-server/tsconfig.json @@ -0,0 +1,23 @@ +{ + "compilerOptions": { + "composite": true, + "target": "es6", + "lib": [ + "es6" + ], + "module": "commonjs", + "rootDir": "src/", + "moduleResolution": "node", + "outDir": "./dist", + "esModuleInterop": true, + "allowSyntheticDefaultImports": true, + "forceConsistentCasingInFileNames": true, + "noImplicitAny": false, + "declaration": true, + "strict": true, + "sourceMap": true + }, + "include": [ + "src" + ] +}