feat: add GET /auth/metrics/efficiency endpoint

Add metrics efficiency endpoint that queries miner efficiency (W/TH) data
via tailLogCustomRangeAggr RPC. Adds AGGR_FIELDS.EFFICIENCY constant.

Author: mukama

tests/unit/handlers/metrics.handlers.test.js

@@ -7,7 +7,10 @@ const {
   calculateHashrateSummary,
   getConsumption,
   processConsumptionData,
-  calculateConsumptionSummary
+  calculateConsumptionSummary,
+  getEfficiency,
+  processEfficiencyData,
+  calculateEfficiencySummary
 } = require('../../../workers/lib/server/handlers/metrics.handlers')
 
 // ==================== Hashrate Tests ====================
@@ -300,3 +303,138 @@ test('calculateConsumptionSummary - handles empty log', (t) => {
   t.is(summary.avgPowerW, null, 'should be null')
   t.pass()
 })
+
+// ==================== Efficiency Tests ====================
+
+test('getEfficiency - happy path', async (t) => {
+  const dayTs = 1700006400000
+  const mockCtx = {
+    conf: {
+      orks: [{ rpcPublicKey: 'key1' }]
+    },
+    net_r0: {
+      jRequest: async () => {
+        return [{ type: 'miner', data: [{ ts: dayTs, val: { efficiency_w_ths_avg_aggr: 25.5 } }], error: null }]
+      }
+    }
+  }
+
+  const mockReq = {
+    query: { start: 1700000000000, end: 1700100000000 }
+  }
+
+  const result = await getEfficiency(mockCtx, mockReq)
+  t.ok(result.log, 'should return log array')
+  t.ok(result.summary, 'should return summary')
+  t.ok(Array.isArray(result.log), 'log should be array')
+  t.ok(result.log.length > 0, 'log should have entries')
+  t.is(result.log[0].efficiencyWThs, 25.5, 'should have efficiency value')
+  t.ok(result.summary.avgEfficiencyWThs !== null, 'should have avg efficiency')
+  t.pass()
+})
+
+test('getEfficiency - missing start throws', async (t) => {
+  const mockCtx = {
+    conf: { orks: [] },
+    net_r0: { jRequest: async () => ({}) }
+  }
+
+  try {
+    await getEfficiency(mockCtx, { query: { end: 1700100000000 } })
+    t.fail('should have thrown')
+  } catch (err) {
+    t.is(err.message, 'ERR_MISSING_START_END', 'should throw missing start/end error')
+  }
+  t.pass()
+})
+
+test('getEfficiency - invalid range throws', async (t) => {
+  const mockCtx = {
+    conf: { orks: [] },
+    net_r0: { jRequest: async () => ({}) }
+  }
+
+  try {
+    await getEfficiency(mockCtx, { query: { start: 1700100000000, end: 1700000000000 } })
+    t.fail('should have thrown')
+  } catch (err) {
+    t.is(err.message, 'ERR_INVALID_DATE_RANGE', 'should throw invalid range error')
+  }
+  t.pass()
+})
+
+test('getEfficiency - empty ork results', async (t) => {
+  const mockCtx = {
+    conf: { orks: [{ rpcPublicKey: 'key1' }] },
+    net_r0: { jRequest: async () => ({}) }
+  }
+
+  const result = await getEfficiency(mockCtx, { query: { start: 1700000000000, end: 1700100000000 } })
+  t.ok(result.log, 'should return log array')
+  t.is(result.log.length, 0, 'log should be empty with no data')
+  t.is(result.summary.avgEfficiencyWThs, null, 'avg should be null')
+  t.pass()
+})
+
+test('processEfficiencyData - processes array data from ORK', (t) => {
+  const results = [
+    [{ type: 'miner', data: [{ ts: 1700006400000, val: { efficiency_w_ths_avg_aggr: 25.5 } }], error: null }]
+  ]
+
+  const daily = processEfficiencyData(results)
+  t.ok(typeof daily === 'object', 'should return object')
+  t.ok(Object.keys(daily).length > 0, 'should have entries')
+  const key = Object.keys(daily)[0]
+  t.is(daily[key].total, 25.5, 'should extract efficiency total')
+  t.is(daily[key].count, 1, 'should track count')
+  t.pass()
+})
+
+test('processEfficiencyData - processes object-keyed data', (t) => {
+  const results = [
+    [{ data: { 1700006400000: { efficiency_w_ths_avg_aggr: 25.5 } } }]
+  ]
+
+  const daily = processEfficiencyData(results)
+  t.ok(typeof daily === 'object', 'should return object')
+  t.ok(Object.keys(daily).length > 0, 'should have entries')
+  t.pass()
+})
+
+test('processEfficiencyData - handles error results', (t) => {
+  const results = [{ error: 'timeout' }]
+  const daily = processEfficiencyData(results)
+  t.ok(typeof daily === 'object', 'should return object')
+  t.is(Object.keys(daily).length, 0, 'should be empty for error results')
+  t.pass()
+})
+
+test('processEfficiencyData - averages across multiple orks', (t) => {
+  const results = [
+    [{ data: { 1700006400000: { efficiency_w_ths_avg_aggr: 20 } } }],
+    [{ data: { 1700006400000: { efficiency_w_ths_avg_aggr: 30 } } }]
+  ]
+
+  const daily = processEfficiencyData(results)
+  const key = Object.keys(daily)[0]
+  t.is(daily[key].total, 50, 'should sum efficiency totals')
+  t.is(daily[key].count, 2, 'should track count from multiple orks')
+  t.pass()
+})
+
+test('calculateEfficiencySummary - calculates from log entries', (t) => {
+  const log = [
+    { ts: 1700006400000, efficiencyWThs: 25 },
+    { ts: 1700092800000, efficiencyWThs: 27 }
+  ]
+
+  const summary = calculateEfficiencySummary(log)
+  t.is(summary.avgEfficiencyWThs, 26, 'should average efficiency')
+  t.pass()
+})
+
+test('calculateEfficiencySummary - handles empty log', (t) => {
+  const summary = calculateEfficiencySummary([])
+  t.is(summary.avgEfficiencyWThs, null, 'should be null')
+  t.pass()
+})

tests/unit/routes/metrics.routes.test.js

@@ -17,6 +17,7 @@ test('metrics routes - route definitions', (t) => {
   const routeUrls = routes.map(route => route.url)
   t.ok(routeUrls.includes('/auth/metrics/hashrate'), 'should have hashrate route')
   t.ok(routeUrls.includes('/auth/metrics/consumption'), 'should have consumption route')
+  t.ok(routeUrls.includes('/auth/metrics/efficiency'), 'should have efficiency route')
 
   t.pass()
 })

workers/lib/constants.js

@@ -136,7 +136,8 @@ const ENDPOINTS = {
 
   // Metrics endpoints
   METRICS_HASHRATE: '/auth/metrics/hashrate',
-  METRICS_CONSUMPTION: '/auth/metrics/consumption'
+  METRICS_CONSUMPTION: '/auth/metrics/consumption',
+  METRICS_EFFICIENCY: '/auth/metrics/efficiency'
 }
 
 const HTTP_METHODS = {
@@ -236,7 +237,8 @@ const AGGR_FIELDS = {
   SITE_POWER: 'site_power_w',
   ENERGY_AGGR: 'energy_aggr',
   ACTIVE_ENERGY_IN: 'active_energy_in_aggr',
-  UTE_ENERGY: 'ute_energy_aggr'
+  UTE_ENERGY: 'ute_energy_aggr',
+  EFFICIENCY: 'efficiency_w_ths_avg_aggr'
 }
 
 const PERIOD_TYPES = {

workers/lib/server/handlers/metrics.handlers.js

@@ -182,11 +182,102 @@ function calculateConsumptionSummary (log) {
   }
 }
 
+// ==================== Efficiency ====================
+
+async function getEfficiency (ctx, req) {
+  const start = Number(req.query.start)
+  const end = Number(req.query.end)
+
+  if (!start || !end) {
+    throw new Error('ERR_MISSING_START_END')
+  }
+
+  if (start >= end) {
+    throw new Error('ERR_INVALID_DATE_RANGE')
+  }
+
+  const startDate = new Date(start).toISOString()
+  const endDate = new Date(end).toISOString()
+
+  const results = await requestRpcEachLimit(ctx, RPC_METHODS.TAIL_LOG_RANGE_AGGR, {
+    keys: [{
+      type: WORKER_TYPES.MINER,
+      startDate,
+      endDate,
+      fields: { [AGGR_FIELDS.EFFICIENCY]: 1 },
+      shouldReturnDailyData: 1
+    }]
+  })
+
+  const daily = processEfficiencyData(results)
+  const log = Object.keys(daily).sort().map(dayTs => ({
+    ts: Number(dayTs),
+    efficiencyWThs: daily[dayTs].total / daily[dayTs].count
+  }))
+
+  const summary = calculateEfficiencySummary(log)
+
+  return { log, summary }
+}
+
+function processEfficiencyData (results) {
+  const daily = {}
+  for (const res of results) {
+    if (res.error || !res) continue
+    const data = Array.isArray(res) ? res : (res.data || res.result || [])
+    if (!Array.isArray(data)) continue
+    for (const entry of data) {
+      if (!entry || entry.error) continue
+      const items = entry.data || entry.items || entry
+      if (Array.isArray(items)) {
+        for (const item of items) {
+          const ts = getStartOfDay(item.ts || item.timestamp)
+          if (!ts) continue
+          const val = item.val || item
+          const eff = val[AGGR_FIELDS.EFFICIENCY] || 0
+          if (!eff) continue
+          if (!daily[ts]) daily[ts] = { total: 0, count: 0 }
+          daily[ts].total += eff
+          daily[ts].count += 1
+        }
+      } else if (typeof items === 'object') {
+        for (const [key, val] of Object.entries(items)) {
+          const ts = getStartOfDay(Number(key))
+          if (!ts) continue
+          const eff = typeof val === 'object' ? (val[AGGR_FIELDS.EFFICIENCY] || 0) : (Number(val) || 0)
+          if (!eff) continue
+          if (!daily[ts]) daily[ts] = { total: 0, count: 0 }
+          daily[ts].total += eff
+          daily[ts].count += 1
+        }
+      }
+    }
+  }
+  return daily
+}
+
+function calculateEfficiencySummary (log) {
+  if (!log.length) {
+    return {
+      avgEfficiencyWThs: null
+    }
+  }
+
+  const total = log.reduce((sum, entry) => sum + (entry.efficiencyWThs || 0), 0)
+
+  return {
+    avgEfficiencyWThs: safeDiv(total, log.length)
+  }
+}
+
 module.exports = {
   getHashrate,
   processHashrateData,
   calculateHashrateSummary,
   getConsumption,
   processConsumptionData,
-  calculateConsumptionSummary
+  calculateConsumptionSummary,
+  getEfficiency,
+  processEfficiencyData,
+  calculateEfficiencySummary
 }

workers/lib/server/routes/metrics.routes.js

@@ -6,7 +6,8 @@ const {
 } = require('../../constants')
 const {
   getHashrate,
-  getConsumption
+  getConsumption,
+  getEfficiency
 } = require('../handlers/metrics.handlers')
 const { createCachedAuthRoute } = require('../lib/routeHelpers')
 
@@ -47,6 +48,23 @@ module.exports = (ctx) => {
         ENDPOINTS.METRICS_CONSUMPTION,
         getConsumption
       )
+    },
+    {
+      method: HTTP_METHODS.GET,
+      url: ENDPOINTS.METRICS_EFFICIENCY,
+      schema: {
+        querystring: schemas.query.efficiency
+      },
+      ...createCachedAuthRoute(
+        ctx,
+        (req) => [
+          'metrics/efficiency',
+          req.query.start,
+          req.query.end
+        ],
+        ENDPOINTS.METRICS_EFFICIENCY,
+        getEfficiency
+      )
     }
   ]
 }

workers/lib/server/schemas/metrics.schemas.js

@@ -19,6 +19,15 @@ const schemas = {
         overwriteCache: { type: 'boolean' }
       },
       required: ['start', 'end']
+    },
+    efficiency: {
+      type: 'object',
+      properties: {
+        start: { type: 'integer' },
+        end: { type: 'integer' },
+        overwriteCache: { type: 'boolean' }
+      },
+      required: ['start', 'end']
     }
   }
 }