Ethereum Deposit Tracker

This project is an Ethereum Deposit Tracker that monitors and records ETH deposits to the Beacon Deposit Contract. The tracker integrates with Ethereum RPC methods (using Alchemy or Infura), stores deposit details in MongoDB, and sends Telegram notifications when a new deposit is detected.

Task provided by: Luganodes

Developer: Kaifur Rahman
Registration Number: 21BRS1147
College: VIT, Chennai

It is fully containerized using Docker, making it easy to set up and run on any machine.

Detailed Documentation: View Detailed Documentation

Architecture

Below is an architecture diagram of the project, showcasing the connections between Alchemy, MongoDB, Telegram, and the Ethereum contract:

Table of Contents

• Features
• Project Structure
• Prerequisites
• Installation
• Environment Variables
• Running the Project
• Testing the Project
• Logging and Error Handling
• Bonus: Dockerization
• API Endpoints
• Contributing

Features

• Monitors the Beacon Deposit Contract for ETH deposits.
• Stores deposit details (blockNumber, timestamp, fee, hash, pubkey) in MongoDB.
• Sends Telegram notifications for each new deposit.
• Full Docker support for easy deployment and scalability.
• Proper error handling and logging.

Project Structure

ETH-DEPOSIT-TRACKER/
├── config/
│   └── db.js                  # MongoDB connection setup
├── models/
│   └── Deposit.js             # Mongoose schema for storing deposit information
├── services/
│   └── depositService.js      # Service to process deposits and send notifications
├── utils/
│   └── logger.js              # Winston logger for logging
├── .env                       # Environment variables (not included, see section on ENV)
├── docker-compose.yml         # Docker Compose configuration
├── Dockerfile                 # Dockerfile for Node.js app
├── index.js                   # Main server file (Express app)
├── package.json               # Project dependencies and scripts
└── README.md                  # Documentation

Prerequisites

Ensure you have the following installed on your system:

• Node.js (version 16.x or higher)
• MongoDB (if not using Docker for MongoDB)
• Docker (if using Docker)
• An Alchemy or Infura Account for Ethereum RPC access

Installation

Clone the Repository

git clone <repository-url>
cd eth-deposit-tracker

Install Dependencies

Make sure you have Node.js installed. Run the following command to install the required Node packages:

npm install

Environment Variables Setup

Create a .env file in the root directory with the following contents:

ALCHEMY_API_KEY=your_alchemy_api_key
MONGODB_URI=mongodb://mongo:27017/eth-deposits
BEACON_CONTRACT=0x00000000219ab540356cBB839Cbe05303d7705Fa
ALCHEMY_SIGNING_KEY=your_alchemy_signing_key
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_telegram_chat_id

• Alchemy API Key: Sign up at Alchemy and create an Ethereum project to get your API key.
• MongoDB URI: Either use a local MongoDB instance or a cloud instance (e.g., MongoDB Atlas).
• Telegram Bot Token: Create a Telegram bot using BotFather and get the bot token.
• Telegram Chat ID: Use the bot to get your chat ID, you can find your chat ID by using the /getChatID command in your bot.

Running the Project

Option 1: Running Locally

Start MongoDB

If you have MongoDB running locally, you can start the MongoDB service:

mongod

Start the Node.js App

Run the following command to start the server:

npm start

Access the Application

The app will run on http://localhost:5000.

Option 2: Running with Docker

Build and Start Containers

Docker will handle running both the Node.js application and MongoDB. Use Docker Compose to build and start the containers:

docker-compose up --build

Access the Application

The application will be available on http://localhost:5000, and MongoDB will be accessible on localhost:27017.

Environment Variables

This project relies on environment variables that are defined in the .env file:

• ALCHEMY_API_KEY: Your Alchemy Ethereum API key for RPC communication.
• MONGODB_URI: MongoDB connection string (defaults to mongodb://mongo:27017/eth-deposits when using Docker).
• BEACON_CONTRACT: Ethereum Beacon Deposit Contract address (set to 0x00000000219ab540356cBB839Cbe05303d7705Fa).
• ALCHEMY_SIGNING_KEY: Signing key to verify webhook signatures from Alchemy.
• TELEGRAM_BOT_TOKEN: Token for the Telegram bot that will send deposit notifications.
• TELEGRAM_CHAT_ID: Your chat ID for receiving Telegram notifications.

How to Get the Variables:

• Alchemy API Key: Create an account at Alchemy, create a new Ethereum app, and retrieve the API key from your dashboard.
• Telegram Bot Token: Use BotFather to create a bot and get the token.
• Telegram Chat ID: Use the bot to send a message to your Telegram account, and retrieve the Chat ID by visiting the Telegram API.

Testing the Project

You can simulate Ethereum transactions to the Beacon Deposit Contract and check the logs to verify if the transactions are being tracked correctly.

Use tools like:

• Etherscan to view deposit contract transactions.
• Simulate deposits using Alchemy’s Ethereum testnet tools.

Logging and Error Handling

• Logging: The project uses winston for logging. Logs are stored both in the console and in error.log.
• Error Handling: The project uses try-catch blocks to handle exceptions in API calls and RPC interactions. Errors are logged using winston.

Bonus: Dockerization

This project is fully containerized using Docker, which makes it easier for anyone to run the project without worrying about dependency conflicts.

Docker Compose

• docker-compose.yml handles the setup for both the MongoDB service and the Node.js app.

To build and start the project using Docker:

docker-compose up --build

Volumes

MongoDB data is persisted in the mongo-data volume, which ensures that data is not lost when containers are stopped or restarted.

API Endpoints

• Webhook for Deposit Notifications: /api/webhook
  • This endpoint is used by Alchemy to send deposit notifications. It verifies the signature and processes the deposit.

Contributing

If you wish to contribute to this project, feel free to fork the repository and submit a pull request. Make sure to document any new features or improvements.