Merge pull request #12 from withtally/component/calculator

Base Calculator Component

Author: 0xSero

.gitignore

@@ -2,12 +2,16 @@
 node_modules/
 .pnpm-store/
 pnpm-lock.yaml
+
 # Environment variables
 .env
 **/.env
 .env.*
 !.env.example
 
+# Output files
+staker-monitor-db.json
+
 # Build output
 dist/
 build/
@@ -20,6 +24,7 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 
+
 # IDE specific files
 .vscode/
 .idea/

package.json

@@ -6,8 +6,12 @@
   "scripts": {
     "start": "tsx src/index.ts",
     "dev": "tsx watch src/index.ts",
-    "monitor": "tsx src/monitor/index.ts",
-    "monitor:dev": "tsx watch src/monitor/index.ts",
+    "start:monitor": "COMPONENTS=monitor tsx src/index.ts",
+    "start:calculator": "COMPONENTS=calculator tsx src/index.ts",
+    "start:all": "COMPONENTS=monitor,calculator tsx src/index.ts",
+    "dev:monitor": "COMPONENTS=monitor tsx watch src/index.ts",
+    "dev:calculator": "COMPONENTS=calculator tsx watch src/index.ts",
+    "dev:all": "COMPONENTS=monitor,calculator tsx watch src/index.ts",
     "lint": "eslint . --ext .ts",
     "format": "prettier --write .",
     "format:check": "prettier --check ."

src/calculator/Calculator.ts

@@ -0,0 +1,159 @@
+import { ethers } from 'ethers';
+import { IDatabase } from '@/database';
+import { ConsoleLogger, Logger } from '@/monitor/logging';
+import { CalculatorWrapper } from './CalculatorWrapper';
+import { MonitorConfig } from '@/monitor/types';
+
+export class Calculator {
+  private readonly db: IDatabase;
+  private readonly provider: ethers.Provider;
+  private readonly logger: Logger;
+  private readonly calculator: CalculatorWrapper;
+  private readonly config: MonitorConfig;
+  private isRunning: boolean;
+  private processingPromise?: Promise<void>;
+  private lastProcessedBlock: number;
+
+  constructor(config: MonitorConfig) {
+    this.config = config;
+    this.db = config.database;
+    this.provider = config.provider;
+    this.logger = new ConsoleLogger(config.logLevel);
+    this.calculator = new CalculatorWrapper(this.db, this.provider);
+    this.isRunning = false;
+    this.lastProcessedBlock = config.startBlock;
+  }
+
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      this.logger.warn('Calculator is already running');
+      return;
+    }
+
+    this.isRunning = true;
+    this.logger.info('Starting Calculator', {
+      network: this.config.networkName,
+      chainId: this.config.chainId,
+      rewardCalculatorAddress: this.config.rewardCalculatorAddress,
+    });
+
+    // Check for existing checkpoint first
+    const checkpoint = await this.db.getCheckpoint('calculator');
+
+    if (checkpoint) {
+      this.lastProcessedBlock = checkpoint.last_block_number;
+      this.logger.info('Resuming from checkpoint', {
+        blockNumber: this.lastProcessedBlock,
+        blockHash: checkpoint.block_hash,
+        lastUpdate: checkpoint.last_update,
+      });
+    } else {
+      // Initialize with start block if no checkpoint exists
+      this.lastProcessedBlock = this.config.startBlock;
+      await this.db.updateCheckpoint({
+        component_type: 'calculator',
+        last_block_number: this.config.startBlock,
+        block_hash:
+          '0x0000000000000000000000000000000000000000000000000000000000000000',
+        last_update: new Date().toISOString(),
+      });
+      this.logger.info('Starting from initial block', {
+        blockNumber: this.lastProcessedBlock,
+      });
+    }
+
+    await this.calculator.start();
+    this.processingPromise = this.processLoop();
+  }
+
+  async stop(): Promise<void> {
+    this.logger.info('Stopping calculator...');
+    this.isRunning = false;
+    await this.calculator.stop();
+    if (this.processingPromise) {
+      await this.processingPromise;
+    }
+    this.logger.info('Calculator stopped');
+  }
+
+  async getCalculatorStatus(): Promise<{
+    isRunning: boolean;
+    lastProcessedBlock: number;
+    currentChainBlock: number;
+    processingLag: number;
+  }> {
+    const currentBlock = await this.getCurrentBlock();
+    return {
+      isRunning: this.isRunning,
+      lastProcessedBlock: this.lastProcessedBlock,
+      currentChainBlock: currentBlock,
+      processingLag: currentBlock - this.lastProcessedBlock,
+    };
+  }
+
+  private async processLoop(): Promise<void> {
+    while (this.isRunning) {
+      try {
+        const currentBlock = await this.getCurrentBlock();
+        const targetBlock = currentBlock - this.config.confirmations;
+
+        if (targetBlock <= this.lastProcessedBlock) {
+          this.logger.debug('Waiting for new blocks', {
+            currentBlock,
+            targetBlock,
+            lastProcessedBlock: this.lastProcessedBlock,
+          });
+          await new Promise((resolve) =>
+            setTimeout(resolve, this.config.pollInterval * 1000),
+          );
+          continue;
+        }
+
+        const fromBlock = this.lastProcessedBlock + 1;
+        const toBlock = Math.min(
+          targetBlock,
+          fromBlock + this.config.maxBlockRange - 1,
+        );
+
+        this.logger.info('Processing new blocks', {
+          fromBlock,
+          toBlock,
+          currentBlock,
+          blockRange: toBlock - fromBlock + 1,
+        });
+
+        await this.calculator.processScoreEvents(fromBlock, toBlock);
+
+        const block = await this.provider.getBlock(toBlock);
+        if (!block) throw new Error(`Block ${toBlock} not found`);
+
+        // Update checkpoint
+        await this.db.updateCheckpoint({
+          component_type: 'calculator',
+          last_block_number: toBlock,
+          block_hash: block.hash!,
+          last_update: new Date().toISOString(),
+        });
+
+        this.lastProcessedBlock = toBlock;
+        this.logger.info('Blocks processed successfully', {
+          fromBlock,
+          toBlock,
+          blockHash: block.hash,
+        });
+      } catch (error) {
+        this.logger.error('Error in processing loop', {
+          error,
+          lastProcessedBlock: this.lastProcessedBlock,
+        });
+        await new Promise((resolve) =>
+          setTimeout(resolve, this.config.pollInterval * 1000),
+        );
+      }
+    }
+  }
+
+  private async getCurrentBlock(): Promise<number> {
+    return this.provider.getBlockNumber();
+  }
+}

src/calculator/CalculatorWrapper.ts

@@ -0,0 +1,72 @@
+import { ICalculatorStrategy } from './interfaces/ICalculatorStrategy';
+import { BinaryEligibilityOracleEarningPowerCalculator } from './strategies/BinaryEligibilityOracleEarningPowerCalculator';
+import { CalculatorConfig, CalculatorStatus } from './interfaces/types';
+import { IDatabase } from '@/database';
+import { ethers } from 'ethers';
+
+export class CalculatorWrapper implements ICalculatorStrategy {
+  private strategy: ICalculatorStrategy;
+  private isRunning: boolean;
+  private lastProcessedBlock: number;
+
+  constructor(
+    db: IDatabase,
+    provider: ethers.Provider,
+    config: CalculatorConfig = { type: 'binary' },
+  ) {
+    // Initialize with BinaryEligibilityOracleEarningPowerCalculator strategy by default
+    this.strategy = new BinaryEligibilityOracleEarningPowerCalculator(
+      db,
+      provider,
+    );
+    this.isRunning = false;
+    this.lastProcessedBlock = 0;
+
+    // Can extend here to support other calculator types
+    if (config.type !== 'binary') {
+      throw new Error(`Calculator type ${config.type} not supported`);
+    }
+  }
+
+  async start(): Promise<void> {
+    this.isRunning = true;
+  }
+
+  async stop(): Promise<void> {
+    this.isRunning = false;
+  }
+
+  async getStatus(): Promise<CalculatorStatus> {
+    return {
+      isRunning: this.isRunning,
+      lastProcessedBlock: this.lastProcessedBlock,
+    };
+  }
+
+  async getEarningPower(
+    amountStaked: bigint,
+    staker: string,
+    delegatee: string,
+  ): Promise<bigint> {
+    return this.strategy.getEarningPower(amountStaked, staker, delegatee);
+  }
+
+  async getNewEarningPower(
+    amountStaked: bigint,
+    staker: string,
+    delegatee: string,
+    oldEarningPower: bigint,
+  ): Promise<[bigint, boolean]> {
+    return this.strategy.getNewEarningPower(
+      amountStaked,
+      staker,
+      delegatee,
+      oldEarningPower,
+    );
+  }
+
+  async processScoreEvents(fromBlock: number, toBlock: number): Promise<void> {
+    await this.strategy.processScoreEvents(fromBlock, toBlock);
+    this.lastProcessedBlock = toBlock;
+  }
+}

src/calculator/README.md

@@ -0,0 +1,83 @@
+# Calculator Component
+
+The Calculator component is responsible for monitoring and processing delegatee score updates from the Reward Calculator contract.
+
+## Overview
+
+The calculator monitors the `DelegateeScoreUpdated` events emitted by the Reward Calculator contract at `${CONFIG.monitor.rewardCalculatorAddress}`. These events are emitted whenever a delegatee's score is updated.
+
+## Components
+
+### CalculatorWrapper
+
+- Main entry point for the calculator functionality
+- Implements strategy pattern to support different calculation methods
+- Manages calculator state (running/stopped)
+- Tracks last processed block
+
+### BinaryEligibilityOracleEarningPowerCalculator
+
+- Default calculator strategy implementation
+- Monitors `DelegateeScoreUpdated` events
+- Calculates earning power based on stake amount and delegatee score
+- Maintains a score cache for quick lookups
+
+## Event Structure
+
+```solidity
+event DelegateeScoreUpdated(
+    address indexed delegatee,  // The delegatee whose score was updated
+    uint256 oldScore,          // Previous score
+    uint256 newScore           // New score
+);
+```
+
+## Database Schema
+
+Score events are stored in the database with the following structure:
+
+```typescript
+type ScoreEvent = {
+  delegatee: string; // Delegatee address
+  score: string; // Current score (stored as string due to bigint)
+  block_number: number; // Block where the event occurred
+  created_at?: string; // Timestamp of database entry
+  updated_at?: string; // Last update timestamp
+};
+```
+
+## Usage
+
+### Running the Calculator
+
+```bash
+# Run only the calculator
+npm run start:calculator
+
+# Run with monitor
+npm run start:all
+```
+
+### Environment Variables
+
+- `REWARD_CALCULATOR_ADDRESS`: Address of the reward calculator contract
+- `START_BLOCK`: Starting block number for event processing
+- `POLL_INTERVAL`: How often to check for new events (in seconds)
+- `MAX_BLOCK_RANGE`: Maximum number of blocks to process in one batch
+- `CONFIRMATIONS`: Number of block confirmations to wait before processing
+
+### Health Checks
+
+The calculator includes built-in health monitoring:
+
+- Processing status (running/stopped)
+- Last processed block
+- Processing lag (current chain height - last processed block)
+- Event processing statistics
+
+## Error Handling
+
+- Automatic retries for failed event processing
+- Checkpoint system to resume from last processed block
+- Detailed error logging for debugging
+- Score caching to reduce contract calls

src/calculator/constants.ts

@@ -0,0 +1,5 @@
+export const REWARD_CALCULATOR_ABI = [
+  'function getEarningPower(uint256 amountStaked, address staker, address delegatee) view returns (uint256)',
+  'function getNewEarningPower(uint256 amountStaked, address staker, address delegatee, uint256 oldEarningPower) view returns (uint256, bool)',
+  'event DelegateeScoreUpdated(address indexed delegatee, uint256 oldScore, uint256 newScore)',
+];

src/calculator/index.ts

@@ -0,0 +1,4 @@
+export * from './CalculatorWrapper';
+export * from './interfaces/ICalculatorStrategy';
+export * from './interfaces/types';
+export * from './strategies/BinaryEligibilityOracleEarningPowerCalculator';

src/calculator/interfaces/ICalculatorStrategy.ts

@@ -0,0 +1,16 @@
+export interface ICalculatorStrategy {
+  getEarningPower(
+    amountStaked: bigint,
+    staker: string,
+    delegatee: string,
+  ): Promise<bigint>;
+
+  getNewEarningPower(
+    amountStaked: bigint,
+    staker: string,
+    delegatee: string,
+    oldEarningPower: bigint,
+  ): Promise<[bigint, boolean]>;
+
+  processScoreEvents(fromBlock: number, toBlock: number): Promise<void>;
+}