feat: SNP integration (#2291)

* chore: upgrade to nodejs LTS (from v20 to v22)

* feat: snp integration tests

* chore: lint fix

* ci: run snp ci step separate

* ci: attempt fix on linux with ExtraHosts config

* chore: use onceWhen from api-toolkit lib

Author: zone117x

.env

@@ -209,3 +209,10 @@ STACKS_NODE_TYPE=L1
 
 # Folder with events to be imported by the event-replay.
 STACKS_EVENTS_DIR=./events
+
+# If enabled this service will connect to the specified SNP redis server and consume events from the SNP stream.
+# This is an alternative to consuming events directly from a stacks-node.
+# SNP_EVENT_STREAMING=true
+# SNP_REDIS_URL=redis://127.0.0.1:6379
+# Only specify `SNP_REDIS_STREAM_KEY_PREFIX` if `REDIS_STREAM_KEY_PREFIX` is configured on the SNP server.
+# SNP_REDIS_STREAM_KEY_PREFIX=

.github/workflows/ci.yml

@@ -131,6 +131,45 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
         if: always()
 
+  test-snp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+
+      # https://github.com/actions/cache/blob/main/examples.md#node---npm
+      - name: Get npm cache directory
+        id: npm-cache-dir
+        shell: bash
+        run: echo "dir=$(npm config get cache)" >> ${GITHUB_OUTPUT}
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache # use this to check for `cache-hit` ==> if: steps.npm-cache.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.npm-cache-dir.outputs.dir }}
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install deps
+        run: npm ci --audit=false
+
+      - name: Install client deps
+        working-directory: client
+        run: npm ci --audit=false
+      - name: Run tests
+        run: npm run test:snp -- --coverage
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+        if: always()
+
   test-2_5:
     strategy:
       fail-fast: false

.nvmrc

@@ -1 +1 @@
-v20
+v22

.vscode/launch.json

@@ -54,7 +54,7 @@
       "skipFiles": [
         "<node_internals>/**"
       ],
-      "runtimeVersion": "20",
+      "runtimeVersion": "22",
       "runtimeArgs": ["-r", "ts-node/register/transpile-only", "-r", "tsconfig-paths/register"],
       "args": ["${workspaceFolder}/src/index.ts"],
       "outputCapture": "std",
@@ -446,6 +446,23 @@
         "STACKS_CHAIN_ID": "0x80000000"
       }
     },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Jest: SNP",
+      "program": "${workspaceFolder}/node_modules/.bin/jest",
+      "args": [
+        "--testTimeout=3600000",
+        "--runInBand",
+        "--no-cache",
+        "--config",
+        "${workspaceRoot}/tests/jest.config.snp.js"
+      ],
+      "outputCapture": "std",
+      "console": "integratedTerminal",
+      "nodeVersionHint": 22,
+      "runtimeVersion": "22"
+    },
     {
       "type": "node",
       "request": "launch",

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-bookworm-slim
+FROM node:22-bookworm-slim
 
 WORKDIR /app
 COPY . .

docker/rosetta.Dockerfile

@@ -12,7 +12,7 @@ ARG ARCHIVE_VERSION=latest
 
 #######################################################################
 ## Build the stacks-blockchain-api
-FROM node:20-bookworm-slim as stacks-blockchain-api-build
+FROM node:22-bookworm-slim as stacks-blockchain-api-build
 ARG STACKS_API_VERSION
 ENV STACKS_API_REPO=hirosystems/stacks-blockchain-api
 ENV STACKS_API_VERSION=${STACKS_API_VERSION}

docker/standalone-regtest.Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1
 
-FROM node:20-bookworm-slim as api-builder
+FROM node:22-bookworm-slim as api-builder
 
 ARG API_GIT_COMMIT
 ARG STACKS_API_VERSION

migrations/1748256987656_snp-state.js

@@ -0,0 +1,25 @@
+// @ts-check
+/** @param { import("node-pg-migrate").MigrationBuilder } pgm */
+exports.up = pgm => {
+  pgm.createTable('snp_state', {
+    id: {
+      type: 'boolean',
+      primaryKey: true,
+      default: true,
+    },
+    last_redis_msg_id: {
+      type: 'text',
+      notNull: true,
+      default: '0',
+    },
+  });
+  // Ensure only a single row can exist
+  pgm.addConstraint('snp_state', 'snp_state_one_row', 'CHECK(id)');
+  // Create the single row
+  pgm.sql('INSERT INTO snp_state VALUES(DEFAULT)');
+};
+
+/** @param { import("node-pg-migrate").MigrationBuilder } pgm */
+exports.down = pgm => {
+  pgm.dropTable('snp_state');
+};