Implement heartbeat (#213)

* Implement heartbeat

* Update CI pnpm/action-setup

* Serialize config before creating the hash

Author: Siegrift

.env.example

@@ -2,3 +2,4 @@ LOGGER_ENABLED=true
 LOG_COLORIZE=true
 LOG_FORMAT=pretty
 LOG_LEVEL=info
+LOG_HEARTBEAT=true

.github/workflows/main.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Clone repo
         uses: actions/checkout@v4
       - name: Install pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v3
         with:
           version: 8.x
       - name: Setup Node
@@ -51,7 +51,7 @@ jobs:
       - name: Clone repo
         uses: actions/checkout@v4
       - name: Install pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v3
         with:
           version: 8.x
       - name: Setup Node

README.md

@@ -111,6 +111,15 @@ Defines the minimum level of logs. Logs with smaller level (severity) will be si
 
 Default: `info`.
 
+### `LOG_HEARTBEAT` _(optional)_
+
+Enables or disables the heartbeat log. The heartbeat log is a cryptographically secure log that is emitted every 60
+seconds to indicate that the service is running. The log includes useful information such as the configuration hash.
+Options:
+
+- `true` - Enables the heartbeat log.
+- `false` - Disables the heartbeat log.
+
 ### Configuration files
 
 Airseeker needs two configuration files, `airseeker.json` and `secrets.env`. All expressions of a form `${SECRET_NAME}`

src/config/index.ts

@@ -7,12 +7,16 @@ import dotenv from 'dotenv';
 import { configSchema } from './schema';
 import { interpolateSecrets, parseSecrets } from './utils';
 
-export const loadConfig = () => {
-  const configPath = join(__dirname, '../../config');
-  const rawSecrets = dotenv.parse(readFileSync(join(configPath, 'secrets.env'), 'utf8'));
+export const getConfigPath = () => join(__dirname, '../../config');
+
+export const loadRawConfig = () => JSON.parse(readFileSync(join(getConfigPath(), 'airseeker.json'), 'utf8'));
 
+export const loadRawSecrets = () => dotenv.parse(readFileSync(join(getConfigPath(), 'secrets.env'), 'utf8'));
+
+export const loadConfig = () => {
   const goLoadConfig = goSync(() => {
-    const rawConfig = JSON.parse(readFileSync(join(configPath, 'airseeker.json'), 'utf8'));
+    const rawConfig = loadRawConfig();
+    const rawSecrets = loadRawSecrets();
     const secrets = parseSecrets(rawSecrets);
     return configSchema.parse(interpolateSecrets(rawConfig, secrets));
   });

src/constants.ts

@@ -11,3 +11,7 @@ export const INT224_MIN = 2n ** 223n * -1n;
 
 // Solidity type(int224).max
 export const INT224_MAX = 2n ** 223n - 1n;
+
+// Intentionally making the message as constant so that it is not accidentally changed. Heartbeat logs subscribers will
+// listen for this exact message to parse the heartbeat.
+export const HEARTBEAT_LOG_MESSAGE = 'Sending heartbeat log.';

src/env/schema.ts

@@ -39,6 +39,7 @@ export const envConfigSchema = z
       })
       .default('info'),
     LOGGER_ENABLED: envBooleanSchema.default('true'),
+    LOG_HEARTBEAT: envBooleanSchema.default('true'),
   })
   .strip(); // We parse from ENV variables of the process which has many variables that we don't care about
 

src/heartbeat-loop/heartbeat-loop.ts

@@ -0,0 +1,56 @@
+import { createSha256Hash, serializePlainObject } from '@api3/commons';
+import { go } from '@api3/promise-utils';
+import { ethers } from 'ethers';
+
+import { loadRawConfig } from '../config';
+import { HEARTBEAT_LOG_MESSAGE } from '../constants';
+import { logger } from '../logger';
+import { getState } from '../state';
+
+import { heartbeatLogger } from './logger';
+
+export const startHeartbeatLoop = () => {
+  logger.info('Initiating heartbeat loop.');
+
+  setInterval(async () => {
+    const goLogHeartbeat = await go(logHeartbeat);
+    if (!goLogHeartbeat.success) logger.error('Failed to log heartbeat.', goLogHeartbeat.error);
+  }, 1000 * 60); // Frequency is hardcoded to 1 minute.
+};
+
+export interface HeartbeatPayload {
+  currentTimestamp: string;
+  configHash: string;
+  signature: string;
+}
+
+export const logHeartbeat = async () => {
+  logger.debug('Creating heartbeat log.');
+
+  const rawConfig = loadRawConfig(); // We want to log the raw config, not the one with interpolated secrets.
+  const configHash = createSha256Hash(serializePlainObject(rawConfig));
+  const {
+    config: { sponsorWalletMnemonic },
+  } = getState();
+
+  logger.debug('Creating heartbeat payload.');
+  const currentTimestamp = Math.floor(Date.now() / 1000).toString();
+  const unsignedHeartbeatPayload = {
+    currentTimestamp,
+    configHash,
+  };
+  const sponsorWallet = ethers.Wallet.fromPhrase(sponsorWalletMnemonic);
+  const signature = await signHeartbeat(sponsorWallet, unsignedHeartbeatPayload);
+  const heartbeatPayload: HeartbeatPayload = { ...unsignedHeartbeatPayload, signature };
+
+  heartbeatLogger.info(HEARTBEAT_LOG_MESSAGE, heartbeatPayload);
+};
+
+export const signHeartbeat = async (
+  sponsorWallet: ethers.HDNodeWallet,
+  unsignedHeartbeatPayload: Omit<HeartbeatPayload, 'signature'>
+) => {
+  logger.debug('Signing heartbeat payload.');
+  const messageToSign = ethers.getBytes(createSha256Hash(serializePlainObject(unsignedHeartbeatPayload)));
+  return sponsorWallet.signMessage(messageToSign);
+};

src/heartbeat-loop/index.ts

@@ -0,0 +1 @@
+export * from './heartbeat-loop';

src/heartbeat-loop/logger.ts

@@ -0,0 +1,14 @@
+import { createLogger } from '@api3/commons';
+
+import { loadEnv } from '../env/env';
+
+// We need to load the environment variables before we can use the logger. Because we want the logger to always be
+// available, we load the environment variables as a side effect during the module import.
+const env = loadEnv();
+
+export const heartbeatLogger = createLogger({
+  colorize: env.LOG_COLORIZE,
+  format: env.LOG_FORMAT,
+  enabled: env.LOGGER_ENABLED,
+  minLevel: 'info', // The heartbeat is sent with INFO severity.
+});

src/index.ts

@@ -1,5 +1,7 @@
 import { loadConfig } from './config';
 import { startDataFetcherLoop } from './data-fetcher-loop';
+import { loadEnv } from './env/env';
+import { startHeartbeatLoop } from './heartbeat-loop';
 import { logger } from './logger';
 import { setInitialState } from './state';
 import { startUpdateFeedsLoops } from './update-feeds-loops';
@@ -12,6 +14,8 @@ function main() {
   logger.info('Starting Airseeker loops.');
   startDataFetcherLoop();
   void startUpdateFeedsLoops();
+  const env = loadEnv();
+  if (env.LOG_HEARTBEAT) startHeartbeatLoop();
 }
 
 main();