Add SV2 DATUM payout hardening

This reverts commit 817f416b79.

.env.example

@@ -10,21 +10,50 @@ BITCOIN_RPC_PASSWORD=
 BITCOIN_RPC_PORT=8332
 BITCOIN_RPC_TIMEOUT=10000
 
-# Enable in bitcoin.conf with
+# Enable in bitcoin.conf with:
-# zmqpubrawblock=tcp://*:3000
+# zmqpubrawblock=tcp://0.0.0.0:3000
-# BITCOIN_ZMQ_HOST="tcp://192.168.1.100:3000"
+BITCOIN_ZMQ_HOST=tcp://192.168.1.100:3000
 
 API_PORT=3334
+# Docker host/IP and public host port for the API listener.
+# Keep API_BIND_HOST as 127.0.0.1 when a reverse proxy terminates public traffic.
+API_BIND_HOST=127.0.0.1
+API_PUBLIC_PORT=3334
+API_WORKERS=4
+
+# Docker json-file log rotation. Applies when using the compose files.
+DOCKER_LOG_MAX_SIZE=100m
+DOCKER_LOG_MAX_FILES=5
 
 # Plain TCP Stratum ports accept both SV1 JSON-RPC and SV2 Noise/binary traffic.
 STRATUM_PORTS=3333,3332,3331,3330
+STRATUM_WORKERS=2
+STRATUM_WORKER_MAX_MEMORY_RESTART=4096M
+STRATUM_MIN_DIFFICULTY=1
+STRATUM_SOCKET_TIMEOUT_MS=3600000
+STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS=60000
 
 # Optional additional SV2-only mining ports. Usually unnecessary when STRATUM_PORTS are exposed.
 #STRATUM_V2_PORTS=
 #SV2_START_DIFFICULTY=100000
 #SV2_TARGET_SHARES_PER_MINUTE=2
 #SV2_DIFFICULTY_CHECK_INTERVAL_MS=60000
+#STRATUM_V2_SOCKET_TIMEOUT_MS=3600000
 #SV2_AUTHORITY_PRIVKEY=
+#SV2_JDP_PORTS=
+#SV2_JDP_POOL_PAYOUT_ADDRESS=
+#SV2_JDP_TOKEN_TTL_MS=600000
+#SV2_TDP_PORTS=
+#SV2_TDP_POOL_PAYOUT_ADDRESS=
+
+# Optional DATUM Prime-compatible listener. DATUM_POOL_PAYOUT_ADDRESS is the
+# required pool coinbase output DATUM gateways must include in custom templates.
+#DATUM_PORTS=
+#DATUM_POOL_PAYOUT_ADDRESS=
+#DATUM_SHARE_DIFFICULTY=1
+# 32-byte hex seed for the DATUM server identity key. DATUM clients must be
+# configured with the matching logged public key.
+#DATUM_IDENTITY_SEED=
 
 STRATUM_SECURE=true
 SECURE_STRATUM_PORTS=4333,4332,4331,4330
@@ -47,10 +76,40 @@ NETWORK=mainnet
 API_SECURE=false
 
 #postgresql
-DB_HOST=
+DB_HOST=timescaledb
-DB_PORT=
+DB_PORT=5432
-DB_USERNAME=
+DB_USERNAME=public_pool
-DB_PASSWORD=
+DB_PASSWORD=public_pool
-DB_DATABASE=
+DB_DATABASE=public_pool
+DB_POOL_SIZE=10
+DB_SSL=false
+DB_SSL_REJECT_UNAUTHORIZED=true
+
+#accepted share accounting
+SHARE_ACCOUNTING_BATCH_SIZE=500
+SHARE_ACCOUNTING_FLUSH_INTERVAL_MS=25
+SHARE_ACCOUNTING_MAX_QUEUE_SIZE=50000
+SHARE_ACCOUNTING_SUMMARY_CACHE_MS=2500
+SHARE_ACCOUNTING_SUMMARY_CACHE_MAX=10000
+SHARE_ROLLUP_ENABLED=true
+SHARE_ROLLUP_INTERVAL_MS=60000
+SHARE_ROLLUP_SAFETY_LAG_SECONDS=30
+SHARE_ROLLUP_MAX_SHARES_PER_BATCH=5000000
+
+# payout snapshot accounting
+PAYOUT_SNAPSHOT_ENABLED=true
+PAYOUT_METHOD=pplns
+PAYOUT_WINDOW_FACTOR=4
+# solo preserves current one-address coinbase payouts. Set to snapshot to pay
+# the latest payout snapshot directly in coinbase outputs.
+PAYOUT_COINBASE_MODE=solo
+PAYOUT_MAX_COINBASE_OUTPUTS=10
+PAYOUT_MIN_OUTPUT_SATS=546
+PAYOUT_FEE_ADDRESS=
+PAYOUT_FEE_PERCENT=0
+PAYOUT_COINBASE_WEIGHT_BUDGET=50000
+
+#redis
+REDIS_URL=redis://redis:6379
 
 PRODUCTION=false

.gitignore

@@ -13,10 +13,14 @@ lerna-debug.log*
 
 # OS
 .DS_Store
+._*
 
 # Tests
 /coverage
 /.nyc_output
+/.baseline-*.json
+/.test-artifacts
+/.profiles
 
 # IDEs and editors
 /.idea
@@ -38,7 +42,7 @@ settings.json
 
 #DB
 **.sqlite**
-./full-setup/data/*
+/full-setup/data/
 
 #https
 **.pem

Dockerfile

@@ -11,6 +11,8 @@ RUN DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
         python3 \
         build-essential \
         cmake \
+        curl \
+        ca-certificates \
     && apt clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
 WORKDIR /build
@@ -18,7 +20,7 @@ WORKDIR /build
 COPY . .
 
 # Build Public Pool using NPM
-RUN npm i && npm run build
+RUN npm ci && npm run build && npm prune --omit=dev
 
 ############################
 # Docker final environment #
@@ -35,4 +37,4 @@ WORKDIR /public-pool
 COPY --from=build /build .
 #COPY .env.example .env
 
-CMD ["/usr/local/bin/node", "dist/main"]
+CMD ["npm", "run", "start:docker"]

Dockerfile.test

@@ -0,0 +1,19 @@
+FROM node:24.16.0-bookworm
+
+RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        python3 \
+        build-essential \
+        cmake \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+CMD ["npm", "run", "test:integration"]

README.md

@@ -39,9 +39,13 @@ See [public-pool-ui](https://github.com/benjamin-wilson/public-pool-ui)
 
 ## Deployment
 
-Install pm2 (https://pm2.keymetrics.io/)
+The production Docker image runs database migrations and then starts PM2
+automatically. For a manual host deployment, install pm2
+(https://pm2.keymetrics.io/), run migrations, then start the app.
 
 ```bash
+$ npm run build
+$ npm run migration:run:prod
 $ pm2 start dist/main.js
 ```
 
@@ -61,43 +65,101 @@ with the default limit of `10000` allow up to `280000` connections on one port.
 
 ## Docker
 
-Build container:
+The default compose stack includes Public Pool, TimescaleDB, and Redis. TimescaleDB
+stores normal Postgres tables plus immutable accepted-share rows in a hypertable.
+Chart and hashrate APIs read from Timescale continuous aggregates plus recent raw
+shares for realtime buckets. Redis is used only for process messaging and latest
+mining-template replay.
+
+Start the stack:
 
 ```bash
-$ docker build -t public-pool .
+$ docker compose up --build -d
 ```
 
-Run container:
+Use an external TimescaleDB/Postgres server:
 
 ```bash
-$ docker container run --name public-pool --rm -p 3333:3333 -p 3334:3334 -p 8332:8332 -v .env:/public-pool/.env public-pool
+$ DB_HOST=postgres.example.com \
+  DB_PORT=5432 \
+  DB_USERNAME=public_pool \
+  DB_PASSWORD='change-me' \
+  DB_DATABASE=public_pool \
+  DB_SSL=false \
+  docker compose -f docker-compose.external-db.yml up --build -d
 ```
 
-### Docker Compose
+The external database must be TimescaleDB-compatible and reachable from the
+Public Pool container. The startup script waits for the remote `DB_HOST:DB_PORT`,
+runs migrations, then starts PM2. Redis still runs locally in this compose file
+unless `REDIS_URL` is pointed at an external Redis instance.
+
+Set `DB_SSL=true` if the external database requires TLS. For private CA or
+self-signed test deployments, `DB_SSL_REJECT_UNAUTHORIZED=false` disables
+certificate verification; do not use that setting for normal internet-facing
+production databases.
+
+For a fresh external database, create the role/database first:
+
+```sql
+CREATE USER public_pool WITH PASSWORD 'change-me';
+CREATE DATABASE public_pool OWNER public_pool;
+\c public_pool
+CREATE EXTENSION IF NOT EXISTS timescaledb;
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+```
+
+If TimescaleDB is managed by another operator, make sure the `public_pool` role
+can create tables, indexes, continuous aggregates, and Timescale policies in the
+target database.
+
+Run only the database migrations:
 
-Build container:
 ```bash
-$ docker compose build
+$ docker compose run --rm public-pool npm run migration:run:prod
 ```
 
-Run container:
+Watch logs:
+
 ```bash
-$ docker compose up -d
+$ docker compose logs --tail 100 -f public-pool
 ```
 
-The docker-compose binds to `127.0.0.1` by default. To expose the Stratum services on your server change:
+Back up TimescaleDB:
-```diff
+
-    ports:
+```bash
--      - "127.0.0.1:3333:3333/tcp"
+$ docker compose exec timescaledb pg_dump -U public_pool public_pool > public-pool.sql
--      - "127.0.0.1:3334:3334/tcp"
-+      - "3333"
-+      - "3334"
 ```
 
+Redis does not hold durable accounting data. Losing Redis requires workers to
+replay the latest template from Redis after reconnect or fall back to the saved
+RPC block template table.
+
 **note**: To successfully connect to the bitcoin RPC you will need to add
 
 ```
 rpcallowip=172.16.0.0/12
+zmqpubrawblock=tcp://0.0.0.0:3000
 ```
 
 to your bitcoin.conf.
+
+## Testing
+
+Baseline unit regression capture:
+
+```bash
+$ npm run test:baseline
+```
+
+Unit tests:
+
+```bash
+$ npm test
+```
+
+Integration tests against real TimescaleDB and Redis:
+
+```bash
+$ docker compose -f docker-compose.test.yml up --build --abort-on-container-exit
+```

docker-compose.external-db.yml

@@ -0,0 +1,99 @@
+x-log-limits: &log-limits
+  driver: json-file
+  options:
+    max-size: ${DOCKER_LOG_MAX_SIZE:-100m}
+    max-file: "${DOCKER_LOG_MAX_FILES:-5}"
+
+services:
+  redis:
+    image: redis:8-alpine
+    container_name: public-pool-redis
+    restart: unless-stopped
+    logging: *log-limits
+    ports:
+      - "127.0.0.1:${REDIS_PORT:-6379}:6379/tcp"
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  public-pool:
+    container_name: public-pool
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    logging: *log-limits
+    depends_on:
+      redis:
+        condition: service_healthy
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    ports:
+      - "0.0.0.0:3333:3333/tcp"
+      - "0.0.0.0:3332:3332/tcp"
+      - "0.0.0.0:3331:3331/tcp"
+      - "0.0.0.0:3330:3330/tcp"
+      - "0.0.0.0:4333:4333/tcp"
+      - "0.0.0.0:4332:4332/tcp"
+      - "0.0.0.0:4331:4331/tcp"
+      - "0.0.0.0:4330:4330/tcp"
+      - "${API_BIND_HOST:-127.0.0.1}:${API_PUBLIC_PORT:-3334}:3334/tcp"
+    volumes:
+      - "./.env:/public-pool/.env:ro"
+      - "./secrets:/public-pool/secrets:ro"
+    environment:
+      NODE_ENV: production
+      DB_HOST: ${DB_HOST:?set DB_HOST to your external TimescaleDB/Postgres host}
+      DB_PORT: ${DB_PORT:-5432}
+      DB_USERNAME: ${DB_USERNAME:-public_pool}
+      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD for your external database}
+      DB_DATABASE: ${DB_DATABASE:-public_pool}
+      DB_POOL_SIZE: ${DB_POOL_SIZE:-10}
+      DB_SSL: ${DB_SSL:-false}
+      DB_SSL_REJECT_UNAUTHORIZED: ${DB_SSL_REJECT_UNAUTHORIZED:-true}
+      REDIS_URL: ${REDIS_URL:-redis://redis:6379}
+      API_PORT: ${API_PORT:-3334}
+      API_SECURE: ${API_SECURE:-false}
+      API_WORKERS: ${API_WORKERS:-4}
+      PM2_ENABLED: ${PM2_ENABLED:-true}
+      STRATUM_WORKERS: ${STRATUM_WORKERS:-2}
+      STRATUM_PORTS: ${STRATUM_PORTS:-3333,3332,3331,3330}
+      STRATUM_MIN_DIFFICULTY: ${STRATUM_MIN_DIFFICULTY:-1}
+      STRATUM_SOCKET_TIMEOUT_MS: ${STRATUM_SOCKET_TIMEOUT_MS:-3600000}
+      STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS: ${STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS:-60000}
+      STRATUM_SECURE: ${STRATUM_SECURE:-true}
+      SECURE_STRATUM_PORTS: ${SECURE_STRATUM_PORTS:-4333,4332,4331,4330}
+      STRATUM_MAX_CONNECTIONS_PER_LISTENER: ${STRATUM_MAX_CONNECTIONS_PER_LISTENER:-10000}
+      STRATUM_TLS_HANDSHAKE_TIMEOUT_MS: ${STRATUM_TLS_HANDSHAKE_TIMEOUT_MS:-10000}
+      STRATUM_BACKPRESSURE_ENABLED: "${STRATUM_BACKPRESSURE_ENABLED:-false}"
+      STRATUM_V2_PORTS: ${STRATUM_V2_PORTS:-}
+      SHARE_ACCOUNTING_BATCH_SIZE: ${SHARE_ACCOUNTING_BATCH_SIZE:-500}
+      SHARE_ACCOUNTING_FLUSH_INTERVAL_MS: ${SHARE_ACCOUNTING_FLUSH_INTERVAL_MS:-25}
+      SHARE_ACCOUNTING_MAX_QUEUE_SIZE: ${SHARE_ACCOUNTING_MAX_QUEUE_SIZE:-50000}
+      SHARE_ACCOUNTING_SUMMARY_CACHE_MS: ${SHARE_ACCOUNTING_SUMMARY_CACHE_MS:-2500}
+      SHARE_ACCOUNTING_SUMMARY_CACHE_MAX: ${SHARE_ACCOUNTING_SUMMARY_CACHE_MAX:-10000}
+      SHARE_ROLLUP_ENABLED: ${SHARE_ROLLUP_ENABLED:-true}
+      SHARE_ROLLUP_INTERVAL_MS: ${SHARE_ROLLUP_INTERVAL_MS:-60000}
+      SHARE_ROLLUP_SAFETY_LAG_SECONDS: ${SHARE_ROLLUP_SAFETY_LAG_SECONDS:-30}
+      SHARE_ROLLUP_MAX_SHARES_PER_BATCH: ${SHARE_ROLLUP_MAX_SHARES_PER_BATCH:-5000000}
+      PAYOUT_SNAPSHOT_ENABLED: ${PAYOUT_SNAPSHOT_ENABLED:-true}
+      PAYOUT_METHOD: ${PAYOUT_METHOD:-pplns}
+      PAYOUT_WINDOW_FACTOR: ${PAYOUT_WINDOW_FACTOR:-4}
+      PAYOUT_COINBASE_MODE: ${PAYOUT_COINBASE_MODE:-solo}
+      PAYOUT_MAX_COINBASE_OUTPUTS: ${PAYOUT_MAX_COINBASE_OUTPUTS:-10}
+      PAYOUT_MIN_OUTPUT_SATS: ${PAYOUT_MIN_OUTPUT_SATS:-546}
+      PAYOUT_FEE_ADDRESS: ${PAYOUT_FEE_ADDRESS:-}
+      PAYOUT_FEE_PERCENT: ${PAYOUT_FEE_PERCENT:-0}
+      PAYOUT_COINBASE_WEIGHT_BUDGET: ${PAYOUT_COINBASE_WEIGHT_BUDGET:-50000}
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"const http=require('http'); const https=require('https'); const secure=process.env.API_SECURE==='true'; const client=secure?https:http; const req=client.get({hostname:'127.0.0.1',port:process.env.API_PORT||3334,path:'/api/network',rejectUnauthorized:false},res=>process.exit(res.statusCode<500?0:1)); req.on('error',()=>process.exit(1)); req.setTimeout(5000,()=>{req.destroy(); process.exit(1);});\""]
+      interval: 30s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  redis-data:

docker-compose.test.yml

@@ -0,0 +1,65 @@
+name: public-pool-test
+
+x-log-limits: &log-limits
+  driver: json-file
+  options:
+    max-size: ${DOCKER_LOG_MAX_SIZE:-100m}
+    max-file: "${DOCKER_LOG_MAX_FILES:-5}"
+
+services:
+  timescaledb:
+    image: timescale/timescaledb:latest-pg17
+    logging: *log-limits
+    environment:
+      POSTGRES_DB: public_pool_test
+      POSTGRES_USER: public_pool
+      POSTGRES_PASSWORD: public_pool
+    command:
+      - postgres
+      - -c
+      - max_wal_size=16GB
+      - -c
+      - min_wal_size=2GB
+      - -c
+      - checkpoint_timeout=15min
+      - -c
+      - checkpoint_completion_target=0.9
+      - -c
+      - wal_compression=on
+    ports:
+      - "127.0.0.1:15432:5432/tcp"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U public_pool -d public_pool_test"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  redis:
+    image: redis:8-alpine
+    logging: *log-limits
+    ports:
+      - "127.0.0.1:16379:6379/tcp"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  integration-tests:
+    build:
+      context: .
+      dockerfile: Dockerfile.test
+    logging: *log-limits
+    depends_on:
+      timescaledb:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    environment:
+      NODE_ENV: integration
+      DB_HOST: timescaledb
+      DB_PORT: 5432
+      DB_USERNAME: public_pool
+      DB_PASSWORD: public_pool
+      DB_DATABASE: public_pool_test
+      REDIS_URL: redis://redis:6379

docker-compose.yml

@@ -1,20 +1,111 @@
-version: '3.8'
+x-log-limits: &log-limits
+  driver: json-file
+  options:
+    max-size: ${DOCKER_LOG_MAX_SIZE:-100m}
+    max-file: "${DOCKER_LOG_MAX_FILES:-5}"
 
 services:
+  timescaledb:
+    image: timescale/timescaledb:latest-pg17
+    container_name: public-pool-timescaledb
+    restart: unless-stopped
+    logging: *log-limits
+    environment:
+      POSTGRES_DB: ${DB_DATABASE:-public_pool}
+      POSTGRES_USER: ${DB_USERNAME:-public_pool}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-public_pool}
+    command:
+      - postgres
+      - -c
+      - max_wal_size=16GB
+      - -c
+      - min_wal_size=2GB
+      - -c
+      - checkpoint_timeout=15min
+      - -c
+      - checkpoint_completion_target=0.9
+      - -c
+      - wal_compression=on
+    ports:
+      - "127.0.0.1:${DB_PORT:-5432}:5432/tcp"
+    volumes:
+      - timescaledb-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-public_pool} -d ${DB_DATABASE:-public_pool}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:8-alpine
+    container_name: public-pool-redis
+    restart: unless-stopped
+    logging: *log-limits
+    ports:
+      - "127.0.0.1:${REDIS_PORT:-6379}:6379/tcp"
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
   public-pool:
     container_name: public-pool
     build:
       context: .
       dockerfile: Dockerfile
     restart: unless-stopped
+    logging: *log-limits
+    depends_on:
+      timescaledb:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
     extra_hosts:
       - "host.docker.internal:host-gateway"
     ports:
-      - "127.0.0.1:${STRATUM_PORT}:${STRATUM_PORT}/tcp"
+      - "0.0.0.0:3333:3333/tcp"
-      - "127.0.0.1:${API_PORT}:${API_PORT}/tcp"
+      - "0.0.0.0:3332:3332/tcp"
+      - "0.0.0.0:3331:3331/tcp"
+      - "0.0.0.0:3330:3330/tcp"
+      - "0.0.0.0:4333:4333/tcp"
+      - "0.0.0.0:4332:4332/tcp"
+      - "0.0.0.0:4331:4331/tcp"
+      - "0.0.0.0:4330:4330/tcp"
+      - "${API_BIND_HOST:-127.0.0.1}:${API_PUBLIC_PORT:-3334}:3334/tcp"
     volumes:
-      - "./${NETWORK}-DB:/public-pool/DB"
       - "./.env:/public-pool/.env:ro"
+      - "./secrets:/public-pool/secrets:ro"
     environment:
-      - NODE_ENV=production
+      NODE_ENV: production
+      DB_HOST: timescaledb
+      DB_PORT: 5432
+      DB_USERNAME: ${DB_USERNAME:-public_pool}
+      DB_PASSWORD: ${DB_PASSWORD:-public_pool}
+      DB_DATABASE: ${DB_DATABASE:-public_pool}
+      REDIS_URL: redis://redis:6379
+      API_PORT: ${API_PORT:-3334}
+      API_SECURE: ${API_SECURE:-false}
+      API_WORKERS: ${API_WORKERS:-4}
+      PM2_ENABLED: ${PM2_ENABLED:-true}
+      STRATUM_WORKERS: ${STRATUM_WORKERS:-2}
+      STRATUM_PORTS: ${STRATUM_PORTS:-3333,3332,3331,3330}
+      STRATUM_MIN_DIFFICULTY: ${STRATUM_MIN_DIFFICULTY:-1}
+      STRATUM_SOCKET_TIMEOUT_MS: ${STRATUM_SOCKET_TIMEOUT_MS:-3600000}
+      STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS: ${STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS:-60000}
+      STRATUM_SECURE: ${STRATUM_SECURE:-true}
+      SECURE_STRATUM_PORTS: ${SECURE_STRATUM_PORTS:-4333,4332,4331,4330}
+      STRATUM_MAX_CONNECTIONS_PER_LISTENER: ${STRATUM_MAX_CONNECTIONS_PER_LISTENER:-10000}
+      STRATUM_TLS_HANDSHAKE_TIMEOUT_MS: ${STRATUM_TLS_HANDSHAKE_TIMEOUT_MS:-10000}
+      STRATUM_V2_PORTS: ${STRATUM_V2_PORTS:-}
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"const http=require('http'); const https=require('https'); const secure=process.env.API_SECURE==='true'; const client=secure?https:http; const req=client.get({hostname:'127.0.0.1',port:process.env.API_PORT||3334,path:'/api/network',rejectUnauthorized:false},res=>process.exit(res.statusCode<500?0:1)); req.on('error',()=>process.exit(1)); req.setTimeout(5000,()=>{req.destroy(); process.exit(1);});\""]
+      interval: 30s
+      timeout: 5s
+      retries: 10
 
+volumes:
+  timescaledb-data:
+  redis-data:

ecosystem.config.js

@@ -1,23 +1,52 @@
+const dockerLogConfig = {
+  out_file: '/dev/stdout',
+  error_file: '/dev/stderr',
+  merge_logs: true,
+};
+
 module.exports = {
     apps: [
+      // API instance
+      {
+        ...dockerLogConfig,
+        name: 'api',
+        script: './dist/main.js',
+        instances: parseInt(process.env.API_WORKERS || '4', 10),
+        exec_mode: 'cluster',
+        env: {
+          MASTER: 'false',
+          API_ONLY: 'true',
+          API_ENABLED: 'true',
+          NODE_CLUSTER_SCHED_POLICY: 'none',
+        },
+        time: true
+      },
       // Master instance
       {
+        ...dockerLogConfig,
         name: 'master',
         script: './dist/main.js',
         instances: 1,
+        exec_mode: 'fork',
         env: {
           MASTER: 'true',
+          API_ENABLED: 'false',
+          NODE_CLUSTER_SCHED_POLICY: 'none',
         },
         time: true
       },
       // Worker instances
       {
+        ...dockerLogConfig,
         name: 'workers',
         script: './dist/main.js',
-        instances: 2,
+        instances: parseInt(process.env.STRATUM_WORKERS || '2', 10),
         exec_mode: "cluster",
+        max_memory_restart: process.env.STRATUM_WORKER_MAX_MEMORY_RESTART || '4096M',
         env: {
           MASTER: 'false',
+          API_ENABLED: 'false',
+          NODE_CLUSTER_SCHED_POLICY: 'none',
         },
         time: true
       },

full-setup/README.md

@@ -1,6 +1,7 @@
 # Full Setup for public pool
 
-This setup provides a docker-compose setup consisting of Bitcoin Core Node and Public-Pool running in Mainnet or Testnet.
+This setup provides Docker Compose stacks for Bitcoin Core, Public Pool,
+TimescaleDB, and Redis on mainnet, testnet, and regtest.
 
 It exposes following ports:
 
@@ -8,6 +9,7 @@ It exposes following ports:
 - `8333/18333` Bitcoin peering on `0.0.0.0`
 - `3333/13333` Public-Pool Stratum port on `0.0.0.0`
 - `3334/13334` Public-Pool API port on `localhost`
+- TimescaleDB and Redis only on the internal compose network
 
 The docker-compose setups for Mainnet and Testnet can be run in parallel without any problems.
 
@@ -42,6 +44,9 @@ There are 4 config files for Mainnet and Testnet
 - `bitcoin-testnet.conf`
 
 **note: pruning (`prune=550`) is enabled by default in the config**
+**note: Bitcoin ZMQ raw block publishing is enabled on the internal compose
+network so the Public Pool master can refresh templates immediately after new
+blocks.**
 # Running the setup
 
 To start the setup in foreground mode:
@@ -65,6 +70,25 @@ To stop the setup use:
 docker compose -f docker-compose-mainnet.yml down
 ```
 
+Database and Redis data are stored under `full-setup/data/<network>/`. To remove
+all runtime data, stop the stack and delete the relevant `bitcoin`,
+`timescaledb`, and `redis` directories.
+
+# Migrations and backups
+
+The Public Pool container waits for TimescaleDB and Redis, runs migrations, and
+then starts PM2. To run migrations manually:
+
+```bash
+docker compose -f docker-compose-mainnet.yml run --rm public-pool npm run migration:run:prod
+```
+
+To back up mainnet accounting data:
+
+```bash
+docker compose -f docker-compose-mainnet.yml exec timescaledb pg_dump -U public_pool public_pool_mainnet > public-pool-mainnet.sql
+```
+
 # Regtest
 
 After running the `regtest` setup a couple of blocks need to be generated:

full-setup/bitcoin-mainnet.conf

@@ -18,6 +18,9 @@ rpcuser=bitcoin
 # enable server
 server=1
 
+# notify pool master about new blocks
+zmqpubrawblock=tcp://0.0.0.0:3000
+
 [main]
 [test]
 rpcbind=0.0.0.0

full-setup/bitcoin-regtest.conf

@@ -20,3 +20,6 @@ rpcuser=bitcoin
 
 # set pruning
 prune=550
+
+# notify pool master about new blocks
+zmqpubrawblock=tcp://0.0.0.0:3000

full-setup/bitcoin-testnet.conf

@@ -18,6 +18,9 @@ rpcuser=bitcoin
 # enable server
 server=1
 
+# notify pool master about new blocks
+zmqpubrawblock=tcp://0.0.0.0:3000
+
 [main]
 [test]
 rpcbind=0.0.0.0

full-setup/docker-compose-mainnet.yml

@@ -1,4 +1,8 @@
-version: '3.8'
+x-log-limits: &log-limits
+  driver: json-file
+  options:
+    max-size: ${DOCKER_LOG_MAX_SIZE:-100m}
+    max-file: "${DOCKER_LOG_MAX_FILES:-5}"
 
 services:
   bitcoin:
@@ -8,6 +12,7 @@ services:
       dockerfile: Dockerfile
     restart: unless-stopped
     stop_grace_period: 30s
+    logging: *log-limits
     networks:
       - bitcoin
     ports:
@@ -20,6 +25,52 @@ services:
       - "./data/mainnet/bitcoin:/app/data"
       - "./bitcoin-mainnet.conf:/app/data/bitcoin.conf:ro"
 
+  timescaledb:
+    image: timescale/timescaledb:latest-pg17
+    container_name: public-pool-mainnet-timescaledb
+    restart: unless-stopped
+    logging: *log-limits
+    networks:
+      - bitcoin
+    environment:
+      POSTGRES_DB: public_pool_mainnet
+      POSTGRES_USER: public_pool
+      POSTGRES_PASSWORD: public_pool
+    command:
+      - postgres
+      - -c
+      - max_wal_size=16GB
+      - -c
+      - min_wal_size=2GB
+      - -c
+      - checkpoint_timeout=15min
+      - -c
+      - checkpoint_completion_target=0.9
+      - -c
+      - wal_compression=on
+    volumes:
+      - "./data/mainnet/timescaledb:/var/lib/postgresql/data"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U public_pool -d public_pool_mainnet"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:8-alpine
+    container_name: public-pool-mainnet-redis
+    restart: unless-stopped
+    logging: *log-limits
+    networks:
+      - bitcoin
+    volumes:
+      - "./data/mainnet/redis:/data"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
   public-pool:
     container_name: public-pool
     build:
@@ -27,16 +78,54 @@ services:
       dockerfile: Dockerfile
     restart: unless-stopped
     stop_grace_period: 30s
+    logging: *log-limits
+    depends_on:
+      timescaledb:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
     networks:
       - bitcoin
     ports:
       - "0.0.0.0:3333:3333/tcp"
-      - "127.0.0.1:3334:3334/tcp"
+      - "0.0.0.0:3332:3332/tcp"
+      - "0.0.0.0:3331:3331/tcp"
+      - "0.0.0.0:3330:3330/tcp"
+      - "0.0.0.0:4333:4333/tcp"
+      - "0.0.0.0:4332:4332/tcp"
+      - "0.0.0.0:4331:4331/tcp"
+      - "0.0.0.0:4330:4330/tcp"
+      - "${API_BIND_HOST:-127.0.0.1}:${API_PUBLIC_PORT:-3334}:3334/tcp"
     volumes:
-      - "./data/mainnet/public-pool:/public-pool/DB"
       - "./public-pool-mainnet.env:/public-pool/.env:ro"
+      - "../secrets:/public-pool/secrets:ro"
     environment:
-      - NODE_ENV=production
+      NODE_ENV: production
+      DB_HOST: timescaledb
+      DB_PORT: 5432
+      DB_USERNAME: public_pool
+      DB_PASSWORD: public_pool
+      DB_DATABASE: public_pool_mainnet
+      REDIS_URL: redis://redis:6379
+      API_WORKERS: ${API_WORKERS:-4}
+      PM2_ENABLED: "true"
+      STRATUM_WORKERS: ${STRATUM_WORKERS:-2}
+      STRATUM_MIN_DIFFICULTY: ${STRATUM_MIN_DIFFICULTY:-1}
+      STRATUM_SOCKET_TIMEOUT_MS: ${STRATUM_SOCKET_TIMEOUT_MS:-3600000}
+      STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS: ${STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS:-60000}
+      SHARE_ROLLUP_ENABLED: ${SHARE_ROLLUP_ENABLED:-true}
+      SHARE_ROLLUP_INTERVAL_MS: ${SHARE_ROLLUP_INTERVAL_MS:-60000}
+      SHARE_ROLLUP_SAFETY_LAG_SECONDS: ${SHARE_ROLLUP_SAFETY_LAG_SECONDS:-30}
+      SHARE_ROLLUP_MAX_SHARES_PER_BATCH: ${SHARE_ROLLUP_MAX_SHARES_PER_BATCH:-5000000}
+      PAYOUT_SNAPSHOT_ENABLED: ${PAYOUT_SNAPSHOT_ENABLED:-true}
+      PAYOUT_METHOD: ${PAYOUT_METHOD:-pplns}
+      PAYOUT_WINDOW_FACTOR: ${PAYOUT_WINDOW_FACTOR:-4}
+      PAYOUT_COINBASE_MODE: ${PAYOUT_COINBASE_MODE:-solo}
+      PAYOUT_MAX_COINBASE_OUTPUTS: ${PAYOUT_MAX_COINBASE_OUTPUTS:-10}
+      PAYOUT_MIN_OUTPUT_SATS: ${PAYOUT_MIN_OUTPUT_SATS:-546}
+      PAYOUT_FEE_ADDRESS: ${PAYOUT_FEE_ADDRESS:-}
+      PAYOUT_FEE_PERCENT: ${PAYOUT_FEE_PERCENT:-0}
+      PAYOUT_COINBASE_WEIGHT_BUDGET: ${PAYOUT_COINBASE_WEIGHT_BUDGET:-50000}
 
 networks:
   bitcoin:

full-setup/docker-compose-regtest.yml

@@ -1,4 +1,8 @@
-version: '3.8'
+x-log-limits: &log-limits
+  driver: json-file
+  options:
+    max-size: ${DOCKER_LOG_MAX_SIZE:-100m}
+    max-file: "${DOCKER_LOG_MAX_FILES:-5}"
 
 services:
   bitcoin-regtest:
@@ -8,6 +12,7 @@ services:
       dockerfile: Dockerfile
     restart: unless-stopped
     stop_grace_period: 30s
+    logging: *log-limits
     networks:
       - bitcoin-regtest
     ports:
@@ -22,6 +27,52 @@ services:
       - "./data/regtest/bitcoin:/app/data"
       - "./bitcoin-regtest.conf:/app/data/bitcoin.conf:ro"
 
+  timescaledb-regtest:
+    image: timescale/timescaledb:latest-pg17
+    container_name: public-pool-regtest-timescaledb
+    restart: unless-stopped
+    logging: *log-limits
+    networks:
+      - bitcoin-regtest
+    environment:
+      POSTGRES_DB: public_pool_regtest
+      POSTGRES_USER: public_pool
+      POSTGRES_PASSWORD: public_pool
+    command:
+      - postgres
+      - -c
+      - max_wal_size=16GB
+      - -c
+      - min_wal_size=2GB
+      - -c
+      - checkpoint_timeout=15min
+      - -c
+      - checkpoint_completion_target=0.9
+      - -c
+      - wal_compression=on
+    volumes:
+      - "./data/regtest/timescaledb:/var/lib/postgresql/data"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U public_pool -d public_pool_regtest"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  redis-regtest:
+    image: redis:8-alpine
+    container_name: public-pool-regtest-redis
+    restart: unless-stopped
+    logging: *log-limits
+    networks:
+      - bitcoin-regtest
+    volumes:
+      - "./data/regtest/redis:/data"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
   public-pool-regtest:
     container_name: public-pool-regtest
     build:
@@ -29,16 +80,36 @@ services:
       dockerfile: Dockerfile
     restart: unless-stopped
     stop_grace_period: 30s
+    logging: *log-limits
+    depends_on:
+      timescaledb-regtest:
+        condition: service_healthy
+      redis-regtest:
+        condition: service_healthy
     networks:
       - bitcoin-regtest
     ports:
       - "0.0.0.0:23333:23333/tcp"
+      - "0.0.0.0:23332:23332/tcp"
+      - "0.0.0.0:23331:23331/tcp"
+      - "0.0.0.0:23330:23330/tcp"
       - "127.0.0.1:23334:23334/tcp"
     volumes:
-      - "./data/regtest/public-pool:/public-pool/DB"
       - "./public-pool-regtest.env:/public-pool/.env:ro"
+      - "../secrets:/public-pool/secrets:ro"
     environment:
-      - NODE_ENV=production
+      NODE_ENV: production
+      DB_HOST: timescaledb-regtest
+      DB_PORT: 5432
+      DB_USERNAME: public_pool
+      DB_PASSWORD: public_pool
+      DB_DATABASE: public_pool_regtest
+      REDIS_URL: redis://redis-regtest:6379
+      PM2_ENABLED: "true"
+      STRATUM_WORKERS: ${STRATUM_WORKERS:-2}
+      STRATUM_MIN_DIFFICULTY: ${STRATUM_MIN_DIFFICULTY:-1}
+      STRATUM_SOCKET_TIMEOUT_MS: ${STRATUM_SOCKET_TIMEOUT_MS:-3600000}
+      STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS: ${STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS:-60000}
 
 networks:
   bitcoin-regtest:

full-setup/docker-compose-testnet.yml

@@ -1,4 +1,8 @@
-version: '3.8'
+x-log-limits: &log-limits
+  driver: json-file
+  options:
+    max-size: ${DOCKER_LOG_MAX_SIZE:-100m}
+    max-file: "${DOCKER_LOG_MAX_FILES:-5}"
 
 services:
   bitcoin-testnet:
@@ -8,6 +12,7 @@ services:
       dockerfile: Dockerfile
     restart: unless-stopped
     stop_grace_period: 30s
+    logging: *log-limits
     networks:
       - bitcoin-testnet
     ports:
@@ -21,6 +26,52 @@ services:
       - "./data/testnet/bitcoin:/app/data"
       - "./bitcoin-testnet.conf:/app/data/bitcoin.conf:ro"
 
+  timescaledb-testnet:
+    image: timescale/timescaledb:latest-pg17
+    container_name: public-pool-testnet-timescaledb
+    restart: unless-stopped
+    logging: *log-limits
+    networks:
+      - bitcoin-testnet
+    environment:
+      POSTGRES_DB: public_pool_testnet
+      POSTGRES_USER: public_pool
+      POSTGRES_PASSWORD: public_pool
+    command:
+      - postgres
+      - -c
+      - max_wal_size=16GB
+      - -c
+      - min_wal_size=2GB
+      - -c
+      - checkpoint_timeout=15min
+      - -c
+      - checkpoint_completion_target=0.9
+      - -c
+      - wal_compression=on
+    volumes:
+      - "./data/testnet/timescaledb:/var/lib/postgresql/data"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U public_pool -d public_pool_testnet"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  redis-testnet:
+    image: redis:8-alpine
+    container_name: public-pool-testnet-redis
+    restart: unless-stopped
+    logging: *log-limits
+    networks:
+      - bitcoin-testnet
+    volumes:
+      - "./data/testnet/redis:/data"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
   public-pool-testnet:
     container_name: public-pool-testnet
     build:
@@ -28,16 +79,36 @@ services:
       dockerfile: Dockerfile
     restart: unless-stopped
     stop_grace_period: 30s
+    logging: *log-limits
+    depends_on:
+      timescaledb-testnet:
+        condition: service_healthy
+      redis-testnet:
+        condition: service_healthy
     networks:
       - bitcoin-testnet
     ports:
       - "0.0.0.0:13333:13333/tcp"
+      - "0.0.0.0:13332:13332/tcp"
+      - "0.0.0.0:13331:13331/tcp"
+      - "0.0.0.0:13330:13330/tcp"
       - "127.0.0.1:13334:13334/tcp"
     volumes:
-      - "./data/testnet/public-pool:/public-pool/DB"
       - "./public-pool-testnet.env:/public-pool/.env:ro"
+      - "../secrets:/public-pool/secrets:ro"
     environment:
-      - NODE_ENV=production
+      NODE_ENV: production
+      DB_HOST: timescaledb-testnet
+      DB_PORT: 5432
+      DB_USERNAME: public_pool
+      DB_PASSWORD: public_pool
+      DB_DATABASE: public_pool_testnet
+      REDIS_URL: redis://redis-testnet:6379
+      PM2_ENABLED: "true"
+      STRATUM_WORKERS: ${STRATUM_WORKERS:-2}
+      STRATUM_MIN_DIFFICULTY: ${STRATUM_MIN_DIFFICULTY:-1}
+      STRATUM_SOCKET_TIMEOUT_MS: ${STRATUM_SOCKET_TIMEOUT_MS:-3600000}
+      STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS: ${STRATUM_TCP_KEEPALIVE_INITIAL_DELAY_MS:-60000}
 
 networks:
   bitcoin-testnet:

full-setup/public-pool-mainnet.env

@@ -4,12 +4,14 @@ BITCOIN_RPC_PASSWORD=bitcoin
 BITCOIN_RPC_PORT=8332
 BITCOIN_RPC_TIMEOUT=10000
 
-# Enable in bitcoin.conf with
+BITCOIN_ZMQ_HOST=tcp://bitcoin:3000
-# zmqpubrawblock=tcp://*:3000
-# BITCOIN_ZMQ_HOST="tcp://192.168.1.100:3000"
 
 API_PORT=3334
-STRATUM_PORT=3333
+STRATUM_PORTS=3333,3332,3331,3330
+STRATUM_SECURE=true
+SECURE_STRATUM_PORTS=4333,4332,4331,4330
+STRATUM_MAX_CONNECTIONS_PER_LISTENER=10000
+STRATUM_TLS_HANDSHAKE_TIMEOUT_MS=10000
 
 #optional telegram bot
 #TELEGRAM_BOT_TOKEN=
@@ -25,3 +27,11 @@ DEV_FEE_ADDRESS=
 NETWORK=mainnet
 
 API_SECURE=false
+
+DB_HOST=timescaledb
+DB_PORT=5432
+DB_USERNAME=public_pool
+DB_PASSWORD=public_pool
+DB_DATABASE=public_pool_mainnet
+REDIS_URL=redis://redis:6379
+PRODUCTION=true

full-setup/public-pool-regtest.env

@@ -4,12 +4,14 @@ BITCOIN_RPC_PASSWORD=bitcoin
 BITCOIN_RPC_PORT=28332
 BITCOIN_RPC_TIMEOUT=10000
 
-# Enable in bitcoin.conf with
+BITCOIN_ZMQ_HOST=tcp://bitcoin-regtest:3000
-# zmqpubrawblock=tcp://*:3000
-# BITCOIN_ZMQ_HOST="tcp://192.168.1.100:3000"
 
 API_PORT=23334
-STRATUM_PORT=23333
+STRATUM_PORTS=23333,23332,23331,23330
+STRATUM_SECURE=false
+SECURE_STRATUM_PORTS=
+STRATUM_MAX_CONNECTIONS_PER_LISTENER=10000
+STRATUM_TLS_HANDSHAKE_TIMEOUT_MS=10000
 
 #optional telegram bot
 #TELEGRAM_BOT_TOKEN=
@@ -25,3 +27,11 @@ DEV_FEE_ADDRESS=
 NETWORK=regtest
 
 API_SECURE=false
+
+DB_HOST=timescaledb-regtest
+DB_PORT=5432
+DB_USERNAME=public_pool
+DB_PASSWORD=public_pool
+DB_DATABASE=public_pool_regtest
+REDIS_URL=redis://redis-regtest:6379
+PRODUCTION=true

full-setup/public-pool-testnet.env

@@ -4,12 +4,14 @@ BITCOIN_RPC_PASSWORD=bitcoin
 BITCOIN_RPC_PORT=18332
 BITCOIN_RPC_TIMEOUT=10000
 
-# Enable in bitcoin.conf with
+BITCOIN_ZMQ_HOST=tcp://bitcoin-testnet:3000
-# zmqpubrawblock=tcp://*:3000
-# BITCOIN_ZMQ_HOST="tcp://192.168.1.100:3000"
 
 API_PORT=13334
-STRATUM_PORT=13333
+STRATUM_PORTS=13333,13332,13331,13330
+STRATUM_SECURE=false
+SECURE_STRATUM_PORTS=
+STRATUM_MAX_CONNECTIONS_PER_LISTENER=10000
+STRATUM_TLS_HANDSHAKE_TIMEOUT_MS=10000
 
 #optional telegram bot
 #TELEGRAM_BOT_TOKEN=
@@ -25,3 +27,11 @@ DEV_FEE_ADDRESS=
 NETWORK=testnet
 
 API_SECURE=false
+
+DB_HOST=timescaledb-testnet
+DB_PORT=5432
+DB_USERNAME=public_pool
+DB_PASSWORD=public_pool
+DB_DATABASE=public_pool_testnet
+REDIS_URL=redis://redis-testnet:6379
+PRODUCTION=true

package.json

@@ -16,8 +16,13 @@
     "start:dev": "nest start --watch",
     "start:debug": "nest start --debug --watch",
     "start:prod": "node dist/main",
+    "start:docker": "node dist/scripts/start-docker.js",
+    "migration:run": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js -d src/data-source.ts migration:run",
+    "migration:run:prod": "node dist/scripts/run-migrations.js",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
     "test": "jest",
+    "test:baseline": "jest --runInBand --json --outputFile=.baseline-jest-results.json",
+    "test:integration": "jest --config ./test/jest-integration.json --runInBand",
     "test:watch": "jest --watch",
     "test:cov": "jest --coverage",
     "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
@@ -34,7 +39,6 @@
     "@nestjs/typeorm": "^11.0.1",
     "@scure/btc-signer": "^2.2.0",
     "axios": "^1.16.0",
-    "better-sqlite3": "^12.9.0",
     "bitcoin-address-validation": "^2.2.3",
     "bitcoinjs-lib": "^6.1.7",
     "bs58": "^5.0.0",
@@ -42,9 +46,12 @@
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.4",
     "discord.js": "^14.26.4",
+    "dotenv": "^16.6.1",
+    "libsodium-wrappers-sumo": "^0.8.4",
     "merkle-lib": "^2.0.10",
     "pg": "^8.20.0",
-    "pg-pubsub": "^0.8.1",
+    "pm2": "^7.0.1",
+    "redis": "^5.12.1",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tiny-secp256k1": "^2.2.4",
@@ -58,6 +65,7 @@
     "@types/cron": "^2.0.1",
     "@types/express": "^4.17.25",
     "@types/jest": "^29.5.14",
+    "@types/libsodium-wrappers-sumo": "^0.7.8",
     "@types/node": "^18.19.130",
     "@types/supertest": "^7.2.0",
     "@typescript-eslint/eslint-plugin": "^5.0.0",

src/ORM/_migrations/AcceptedShareIndex1780862400000.ts

@@ -0,0 +1,41 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AcceptedShareIndex1780862400000 implements MigrationInterface {
+    public name = 'AcceptedShareIndex1780862400000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE SEQUENCE IF NOT EXISTS "accepted_share_index_seq"`);
+        await queryRunner.query(`ALTER TABLE "accepted_share_entity" ADD COLUMN IF NOT EXISTS "shareIndex" bigint`);
+        await queryRunner.query(`
+            SELECT setval(
+                'accepted_share_index_seq',
+                GREATEST(
+                    (SELECT COUNT(*) FROM "accepted_share_entity") + 1,
+                    (SELECT COALESCE(MAX("shareIndex"), 0) + 1 FROM "accepted_share_entity"),
+                    1
+                ),
+                false
+            )
+        `);
+        await queryRunner.query(`
+            ALTER TABLE "accepted_share_entity"
+            ALTER COLUMN "shareIndex" SET DEFAULT nextval('accepted_share_index_seq')
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_order"
+            ON "accepted_share_entity" ("shareIndex" DESC)
+            WHERE "shareIndex" IS NOT NULL
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_order"`);
+        await queryRunner.query(`
+            ALTER TABLE "accepted_share_entity"
+            ALTER COLUMN "shareIndex" DROP DEFAULT
+        `);
+        await queryRunner.query(`ALTER TABLE "accepted_share_entity" DROP COLUMN IF EXISTS "shareIndex"`);
+        await queryRunner.query(`DROP SEQUENCE IF EXISTS "accepted_share_index_seq"`);
+    }
+}

src/ORM/_migrations/AcceptedShareProtocolMetadata1781130600000.ts

@@ -0,0 +1,74 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AcceptedShareProtocolMetadata1781130600000 implements MigrationInterface {
+    public name = 'AcceptedShareProtocolMetadata1781130600000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await this.decompressAcceptedShareChunks(queryRunner);
+        await queryRunner.query(`
+            DO $$
+            BEGIN
+                IF EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_name = 'accepted_share_entity'
+                      AND column_name = 'protocol'
+                      AND COALESCE(character_maximum_length, 0) < 16
+                ) THEN
+                    ALTER TABLE "accepted_share_entity" ALTER COLUMN "protocol" TYPE varchar(16);
+                END IF;
+            END
+            $$
+        `);
+        await queryRunner.query(`ALTER TABLE "accepted_share_entity" ADD COLUMN IF NOT EXISTS "workSource" varchar(16) NOT NULL DEFAULT 'pool_template'`);
+        await queryRunner.query(`ALTER TABLE "accepted_share_entity" ADD COLUMN IF NOT EXISTS "workProtocol" varchar(16) NOT NULL DEFAULT 'pool'`);
+        await this.restoreAcceptedShareCompression(queryRunner);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_protocol_work"
+            ON "accepted_share_entity" ("protocol", "workSource", "workProtocol", "acceptedAt" DESC)
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await this.decompressAcceptedShareChunks(queryRunner);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_protocol_work"`);
+        await queryRunner.query(`ALTER TABLE "accepted_share_entity" DROP COLUMN IF EXISTS "workProtocol"`);
+        await queryRunner.query(`ALTER TABLE "accepted_share_entity" DROP COLUMN IF EXISTS "workSource"`);
+        await queryRunner.query(`ALTER TABLE "accepted_share_entity" ALTER COLUMN "protocol" TYPE varchar(8)`);
+        await this.restoreAcceptedShareCompression(queryRunner);
+    }
+
+    private async decompressAcceptedShareChunks(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`SELECT remove_compression_policy('accepted_share_entity', if_exists => TRUE)`);
+        await queryRunner.query(`
+            DO $$
+            DECLARE
+                chunk_name regclass;
+            BEGIN
+                FOR chunk_name IN SELECT show_chunks('accepted_share_entity')
+                LOOP
+                    PERFORM decompress_chunk(chunk_name, if_compressed => TRUE);
+                END LOOP;
+            END
+            $$
+        `);
+    }
+
+    private async restoreAcceptedShareCompression(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            ALTER TABLE "accepted_share_entity" SET (
+                timescaledb.compress,
+                timescaledb.compress_orderby = '"acceptedAt" DESC',
+                timescaledb.compress_segmentby = '"address","clientName"'
+            )
+        `);
+        await queryRunner.query(`
+            SELECT add_compression_policy(
+                'accepted_share_entity',
+                INTERVAL '24 hours',
+                if_not_exists => TRUE
+            )
+        `);
+    }
+}

src/ORM/_migrations/AcceptedShareRetentionCompression1780966200000.ts

@@ -0,0 +1,54 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AcceptedShareRetentionCompression1780966200000 implements MigrationInterface {
+    public name = 'AcceptedShareRetentionCompression1780966200000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            ALTER TABLE "accepted_share_entity" SET (
+                timescaledb.compress,
+                timescaledb.compress_orderby = '"acceptedAt" DESC',
+                timescaledb.compress_segmentby = '"address","clientName"'
+            )
+        `);
+
+        await queryRunner.query(`SELECT remove_compression_policy('accepted_share_entity', if_exists => TRUE)`);
+        await queryRunner.query(`
+            SELECT add_compression_policy(
+                'accepted_share_entity',
+                INTERVAL '24 hours',
+                if_not_exists => TRUE
+            )
+        `);
+
+        await queryRunner.query(`SELECT remove_retention_policy('accepted_share_entity', if_exists => TRUE)`);
+        await queryRunner.query(`
+            SELECT add_retention_policy(
+                'accepted_share_entity',
+                INTERVAL '7 days',
+                if_not_exists => TRUE
+            )
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`SELECT remove_compression_policy('accepted_share_entity', if_exists => TRUE)`);
+        await queryRunner.query(`
+            SELECT add_compression_policy(
+                'accepted_share_entity',
+                INTERVAL '1 day',
+                if_not_exists => TRUE
+            )
+        `);
+
+        await queryRunner.query(`SELECT remove_retention_policy('accepted_share_entity', if_exists => TRUE)`);
+        await queryRunner.query(`
+            SELECT add_retention_policy(
+                'accepted_share_entity',
+                INTERVAL '30 days',
+                if_not_exists => TRUE
+            )
+        `);
+    }
+}

src/ORM/_migrations/AcceptedShareRollupIndexes1780865400000.ts

@@ -0,0 +1,32 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AcceptedShareRollupIndexes1780865400000 implements MigrationInterface {
+    public name = 'AcceptedShareRollupIndexes1780865400000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_10m_bucket"
+            ON "accepted_share_10m" ("bucket" DESC)
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_10m_address_bucket"
+            ON "accepted_share_10m" ("address", "bucket" DESC)
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_10m_group_bucket"
+            ON "accepted_share_10m" ("address", "clientName", "bucket" DESC)
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_10m_client_bucket"
+            ON "accepted_share_10m" ("clientId", "bucket" DESC)
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_10m_client_bucket"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_10m_group_bucket"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_10m_address_bucket"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_10m_bucket"`);
+    }
+}

src/ORM/_migrations/ActiveOnlyUserAgentReport1780860200000.ts

@@ -0,0 +1,36 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class ActiveOnlyUserAgentReport1780860200000 implements MigrationInterface {
+    name = 'ActiveOnlyUserAgentReport1780860200000';
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP MATERIALIZED VIEW IF EXISTS "user_agent_report_view"`);
+        await queryRunner.query(`
+            CREATE MATERIALIZED VIEW "user_agent_report_view" AS
+            SELECT
+                "userAgent",
+                COUNT("userAgent") AS "count",
+                MAX("bestDifficulty") AS "bestDifficulty",
+                SUM("hashRate") AS "totalHashRate"
+            FROM "client_entity"
+            WHERE "deletedAt" IS NULL
+            GROUP BY "userAgent"
+            ORDER BY "totalHashRate" DESC
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP MATERIALIZED VIEW IF EXISTS "user_agent_report_view"`);
+        await queryRunner.query(`
+            CREATE MATERIALIZED VIEW "user_agent_report_view" AS
+            SELECT
+                "userAgent",
+                COUNT("userAgent") AS "count",
+                MAX("bestDifficulty") AS "bestDifficulty",
+                SUM("hashRate") AS "totalHashRate"
+            FROM "client_entity"
+            GROUP BY "userAgent"
+            ORDER BY "totalHashRate" DESC
+        `);
+    }
+}

src/ORM/_migrations/BlocksSubmissionMetadata1781220000000.ts

@@ -0,0 +1,27 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class BlocksSubmissionMetadata1781220000000 implements MigrationInterface {
+    public name = 'BlocksSubmissionMetadata1781220000000';
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE "blocks_entity" ADD COLUMN IF NOT EXISTS "blockHash" varchar`);
+        await queryRunner.query(`ALTER TABLE "blocks_entity" ADD COLUMN IF NOT EXISTS "blockSubmissionResult" varchar`);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_blocks_successful_found"
+            ON "blocks_entity" ("height" DESC, "createdAt" DESC)
+            WHERE "blockSubmissionResult" IS NULL OR "blockSubmissionResult" = 'SUCCESS!'
+        `);
+        await queryRunner.query(`
+            CREATE UNIQUE INDEX IF NOT EXISTS "UQ_blocks_block_hash"
+            ON "blocks_entity" ("blockHash")
+            WHERE "blockHash" IS NOT NULL
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "UQ_blocks_block_hash"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_blocks_successful_found"`);
+        await queryRunner.query(`ALTER TABLE "blocks_entity" DROP COLUMN IF EXISTS "blockSubmissionResult"`);
+        await queryRunner.query(`ALTER TABLE "blocks_entity" DROP COLUMN IF EXISTS "blockHash"`);
+    }
+}

src/ORM/_migrations/CurrentRoundBestShareIndex1780897600000.ts

@@ -0,0 +1,22 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CurrentRoundBestShareIndex1780897600000 implements MigrationInterface {
+    public name = 'CurrentRoundBestShareIndex1780897600000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_address_settings_best_difficulty"`);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_round_best"
+            ON "accepted_share_entity" ("submissionDifficulty" DESC, "acceptedAt" DESC, "blockHeight")
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_round_best"`);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_address_settings_best_difficulty"
+            ON "address_settings_entity" ("bestDifficulty" DESC)
+        `);
+    }
+}

src/ORM/_migrations/CurrentRoundWorkRollup1780899000000.ts

@@ -0,0 +1,43 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CurrentRoundWorkRollup1780899000000 implements MigrationInterface {
+    public name = 'CurrentRoundWorkRollup1780899000000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE MATERIALIZED VIEW IF NOT EXISTS "accepted_share_block_10m"
+            WITH (timescaledb.continuous) AS
+            SELECT
+                time_bucket(INTERVAL '10 minutes', "acceptedAt") AS "bucket",
+                "blockHeight",
+                SUM("creditedDifficulty") AS "shares",
+                COUNT(*) AS "acceptedCount",
+                MAX("networkDifficulty") AS "networkDifficulty",
+                MAX("submissionDifficulty") AS "bestSubmissionDifficulty"
+            FROM "accepted_share_entity"
+            GROUP BY "bucket", "blockHeight"
+            WITH NO DATA
+        `);
+
+        await queryRunner.query(`
+            SELECT add_continuous_aggregate_policy(
+                'accepted_share_block_10m',
+                start_offset => INTERVAL '180 days',
+                end_offset => INTERVAL '1 minute',
+                schedule_interval => INTERVAL '1 minute',
+                if_not_exists => TRUE
+            )
+        `);
+
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_block_10m_height_bucket"
+            ON "accepted_share_block_10m" ("blockHeight" DESC, "bucket" DESC)
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_block_10m_height_bucket"`);
+        await queryRunner.query(`DROP MATERIALIZED VIEW IF EXISTS "accepted_share_block_10m"`);
+    }
+}

src/ORM/_migrations/FixClientSessionActiveIndex1780863600000.ts

@@ -0,0 +1,40 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class FixClientSessionActiveIndex1780863600000 implements MigrationInterface {
+    public name = 'FixClientSessionActiveIndex1780863600000';
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_unique_nonce"`);
+        await queryRunner.query(`
+            DELETE FROM "client_entity"
+            WHERE ctid IN (
+                SELECT ctid
+                FROM (
+                    SELECT
+                        ctid,
+                        row_number() OVER (
+                            PARTITION BY "sessionId"
+                            ORDER BY "createdAt" DESC, "id" DESC
+                        ) AS rn
+                    FROM "client_entity"
+                    WHERE "deletedAt" IS NULL
+                ) duplicates
+                WHERE rn > 1
+            )
+        `);
+        await queryRunner.query(`
+            CREATE UNIQUE INDEX IF NOT EXISTS "IDX_unique_nonce"
+            ON "client_entity" ("sessionId")
+            WHERE "deletedAt" IS NULL
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_unique_nonce"`);
+        await queryRunner.query(`
+            CREATE UNIQUE INDEX IF NOT EXISTS "IDX_unique_nonce"
+            ON "client_entity" ("sessionId")
+            WHERE "deletedAt" IS NOT NULL
+        `);
+    }
+}

src/ORM/_migrations/InitialTimescaleSchema1780859300000.ts

@@ -0,0 +1,217 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class InitialTimescaleSchema1780859300000 implements MigrationInterface {
+    public name = 'InitialTimescaleSchema1780859300000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
+        await queryRunner.query(`CREATE EXTENSION IF NOT EXISTS timescaledb`);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "address_settings_entity" (
+                "address" varchar(62) PRIMARY KEY,
+                "shares" integer NOT NULL DEFAULT 0,
+                "bestDifficulty" numeric NOT NULL DEFAULT 0,
+                "bestDifficultyUserAgent" varchar,
+                "miscCoinbaseScriptData" varchar,
+                "deletedAt" timestamptz,
+                "createdAt" timestamptz NOT NULL DEFAULT now(),
+                "updatedAt" timestamptz NOT NULL DEFAULT now()
+            )
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "client_entity" (
+                "id" uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
+                "address" varchar(62) NOT NULL,
+                "clientName" varchar(64) NOT NULL,
+                "sessionId" varchar(8) NOT NULL,
+                "userAgent" varchar(128),
+                "startTime" timestamptz NOT NULL,
+                "bestDifficulty" numeric NOT NULL DEFAULT 0,
+                "hashRate" numeric NOT NULL DEFAULT 0,
+                "deletedAt" timestamptz,
+                "createdAt" timestamptz NOT NULL DEFAULT now(),
+                "updatedAt" timestamptz NOT NULL DEFAULT now()
+            )
+        `);
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "IDX_client_entity_address" ON "client_entity" ("address")`);
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "idx_client_cleanup" ON "client_entity" ("id") WHERE "deletedAt" IS NULL`);
+        await queryRunner.query(`CREATE UNIQUE INDEX IF NOT EXISTS "IDX_unique_nonce" ON "client_entity" ("sessionId") WHERE "deletedAt" IS NULL`);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "accepted_share_entity" (
+                "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+                "acceptedAt" timestamptz NOT NULL,
+                "protocol" varchar(8) NOT NULL,
+                "address" varchar(62) NOT NULL,
+                "clientName" varchar NOT NULL,
+                "sessionId" varchar(8) NOT NULL,
+                "clientId" uuid NOT NULL,
+                "jobId" varchar NOT NULL,
+                "jobTemplateId" varchar NOT NULL,
+                "blockHeight" bigint NOT NULL,
+                "creditedDifficulty" numeric NOT NULL,
+                "submissionDifficulty" numeric NOT NULL,
+                "networkDifficulty" numeric NOT NULL,
+                "nonce" varchar NOT NULL,
+                "ntime" varchar NOT NULL,
+                "version" varchar NOT NULL,
+                "extraNonce2" varchar NOT NULL,
+                "isBlockCandidate" boolean NOT NULL DEFAULT false,
+                "blockSubmissionResult" text,
+                "createdAt" timestamptz NOT NULL DEFAULT now(),
+                PRIMARY KEY ("id", "acceptedAt")
+            )
+        `);
+        await queryRunner.query(`
+            SELECT create_hypertable(
+                '"accepted_share_entity"',
+                'acceptedAt',
+                chunk_time_interval => INTERVAL '1 day',
+                if_not_exists => TRUE
+            )
+        `);
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "IDX_accepted_share_accounting_lookup" ON "accepted_share_entity" ("address", "clientName", "acceptedAt" DESC)`);
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "IDX_accepted_share_client_lookup" ON "accepted_share_entity" ("clientId", "acceptedAt" DESC)`);
+        await queryRunner.query(`
+            CREATE UNIQUE INDEX IF NOT EXISTS "IDX_accepted_share_unique_submission"
+            ON "accepted_share_entity" ("acceptedAt", "protocol", "sessionId", "jobId", "nonce", "ntime", "version", "extraNonce2")
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "blocks_entity" (
+                "id" bigserial PRIMARY KEY,
+                "height" integer NOT NULL,
+                "minerAddress" varchar(62) NOT NULL,
+                "worker" varchar NOT NULL,
+                "sessionId" varchar(8) NOT NULL,
+                "blockData" varchar NOT NULL,
+                "blockHash" varchar,
+                "blockSubmissionResult" varchar,
+                "deletedAt" timestamptz,
+                "createdAt" timestamptz NOT NULL DEFAULT now(),
+                "updatedAt" timestamptz NOT NULL DEFAULT now()
+            )
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "rpc_block_entity" (
+                "blockHeight" integer PRIMARY KEY,
+                "data" varchar
+            )
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "telegram_subscriptions_entity" (
+                "id" bigserial PRIMARY KEY,
+                "address" varchar(62) NOT NULL,
+                "telegramChatId" integer NOT NULL,
+                "deletedAt" timestamptz,
+                "createdAt" timestamptz NOT NULL DEFAULT now(),
+                "updatedAt" timestamptz NOT NULL DEFAULT now()
+            )
+        `);
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "IDX_telegram_subscriptions_address" ON "telegram_subscriptions_entity" ("address")`);
+
+        await queryRunner.query(`
+            CREATE MATERIALIZED VIEW IF NOT EXISTS "user_agent_report_view" AS
+            SELECT
+                "userAgent",
+                COUNT("userAgent") AS "count",
+                MAX("bestDifficulty") AS "bestDifficulty",
+                SUM("hashRate") AS "totalHashRate"
+            FROM "client_entity"
+            WHERE "deletedAt" IS NULL
+            GROUP BY "userAgent"
+            ORDER BY "totalHashRate" DESC
+        `);
+
+        await queryRunner.query(`
+            CREATE MATERIALIZED VIEW IF NOT EXISTS "accepted_share_10m"
+            WITH (timescaledb.continuous) AS
+            SELECT
+                time_bucket(INTERVAL '10 minutes', "acceptedAt") AS "bucket",
+                "address",
+                "clientName",
+                "sessionId",
+                "clientId",
+                SUM("creditedDifficulty") AS "shares",
+                COUNT(*) AS "acceptedCount",
+                ROUND(((SUM("creditedDifficulty") * 4294967296) / 600)) AS "hashRate"
+            FROM "accepted_share_entity"
+            GROUP BY "bucket", "address", "clientName", "sessionId", "clientId"
+            WITH NO DATA
+        `);
+
+        await queryRunner.query(`
+            CREATE MATERIALIZED VIEW IF NOT EXISTS "accepted_share_1h"
+            WITH (timescaledb.continuous) AS
+            SELECT
+                time_bucket(INTERVAL '1 hour', "acceptedAt") AS "bucket",
+                "address",
+                "clientName",
+                SUM("creditedDifficulty") AS "shares",
+                COUNT(*) AS "acceptedCount"
+            FROM "accepted_share_entity"
+            GROUP BY "bucket", "address", "clientName"
+            WITH NO DATA
+        `);
+
+        await queryRunner.query(`
+            CREATE MATERIALIZED VIEW IF NOT EXISTS "accepted_share_1d"
+            WITH (timescaledb.continuous) AS
+            SELECT
+                time_bucket(INTERVAL '1 day', "acceptedAt") AS "bucket",
+                "address",
+                SUM("creditedDifficulty") AS "shares",
+                COUNT(*) AS "acceptedCount"
+            FROM "accepted_share_entity"
+            GROUP BY "bucket", "address"
+            WITH NO DATA
+        `);
+
+        await queryRunner.query(`
+            SELECT add_continuous_aggregate_policy(
+                'accepted_share_10m',
+                start_offset => INTERVAL '2 days',
+                end_offset => INTERVAL '1 minute',
+                schedule_interval => INTERVAL '1 minute',
+                if_not_exists => TRUE
+            )
+        `);
+        await queryRunner.query(`
+            SELECT add_continuous_aggregate_policy(
+                'accepted_share_1h',
+                start_offset => INTERVAL '30 days',
+                end_offset => INTERVAL '10 minutes',
+                schedule_interval => INTERVAL '10 minutes',
+                if_not_exists => TRUE
+            )
+        `);
+        await queryRunner.query(`
+            SELECT add_continuous_aggregate_policy(
+                'accepted_share_1d',
+                start_offset => INTERVAL '365 days',
+                end_offset => INTERVAL '1 hour',
+                schedule_interval => INTERVAL '1 hour',
+                if_not_exists => TRUE
+            )
+        `);
+        await queryRunner.query(`SELECT add_retention_policy('accepted_share_entity', INTERVAL '90 days', if_not_exists => TRUE)`);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP MATERIALIZED VIEW IF EXISTS "accepted_share_1d"`);
+        await queryRunner.query(`DROP MATERIALIZED VIEW IF EXISTS "accepted_share_1h"`);
+        await queryRunner.query(`DROP MATERIALIZED VIEW IF EXISTS "accepted_share_10m"`);
+        await queryRunner.query(`DROP MATERIALIZED VIEW IF EXISTS "user_agent_report_view"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "accepted_share_entity" CASCADE`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "telegram_subscriptions_entity"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "rpc_block_entity"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "blocks_entity"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "client_entity"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "address_settings_entity"`);
+    }
+}

src/ORM/_migrations/PayoutSnapshots1780969800000.ts

@@ -0,0 +1,143 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class PayoutSnapshots1780969800000 implements MigrationInterface {
+    public name = 'PayoutSnapshots1780969800000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "payout_snapshot" (
+                "id" bigserial PRIMARY KEY,
+                "method" varchar(32) NOT NULL,
+                "status" varchar(16) NOT NULL DEFAULT 'finalized',
+                "blockHeight" bigint NOT NULL,
+                "coinbaseValueSats" bigint NOT NULL,
+                "networkDifficulty" numeric NOT NULL,
+                "windowTargetDifficulty" numeric NOT NULL DEFAULT 0,
+                "windowFactor" numeric NOT NULL DEFAULT 4,
+                "feeAddress" varchar(62),
+                "feeSats" bigint NOT NULL DEFAULT 0,
+                "minPayoutSats" integer NOT NULL DEFAULT 546,
+                "coinbaseWeightBudget" integer NOT NULL DEFAULT 50000,
+                "startBatchId" bigint NOT NULL REFERENCES "share_rollup_batch" ("id"),
+                "endBatchId" bigint NOT NULL REFERENCES "share_rollup_batch" ("id"),
+                "windowStartShareIndex" bigint NOT NULL,
+                "windowEndShareIndex" bigint NOT NULL,
+                "totalCreditedDifficulty" numeric NOT NULL,
+                "totalAcceptedShareCount" bigint NOT NULL,
+                "eligibleAddressCount" integer NOT NULL,
+                "includedOutputCount" integer NOT NULL,
+                "distributedSats" bigint NOT NULL,
+                "unallocatedRemainderSats" bigint NOT NULL,
+                "createdAt" timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_payout_snapshot_latest"
+            ON "payout_snapshot" ("status", "createdAt" DESC, "id" DESC)
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_payout_snapshot_window"
+            ON "payout_snapshot" ("windowEndShareIndex" DESC)
+        `);
+        await queryRunner.query(`
+            CREATE UNIQUE INDEX IF NOT EXISTS "IDX_payout_snapshot_template_window"
+            ON "payout_snapshot" ("method", "blockHeight", "coinbaseValueSats", "windowEndShareIndex")
+            WHERE "status" = 'finalized'
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "payout_snapshot_entry" (
+                "id" bigserial PRIMARY KEY,
+                "snapshotId" bigint NOT NULL REFERENCES "payout_snapshot" ("id") ON DELETE CASCADE,
+                "address" varchar(62) NOT NULL,
+                "creditedDifficulty" numeric NOT NULL,
+                "acceptedShareCount" bigint NOT NULL,
+                "payoutWeight" numeric NOT NULL,
+                "grossPayoutSats" bigint NOT NULL,
+                "payoutSats" bigint NOT NULL,
+                "balanceBeforeSats" bigint NOT NULL DEFAULT 0,
+                "balanceAfterSats" bigint NOT NULL DEFAULT 0,
+                "includedInCoinbase" boolean NOT NULL DEFAULT true,
+                "rowType" varchar(16) NOT NULL DEFAULT 'coinbase',
+                "rank" integer NOT NULL,
+                "createdAt" timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+        `);
+        await queryRunner.query(`
+            CREATE UNIQUE INDEX IF NOT EXISTS "IDX_payout_snapshot_entry_snapshot_address"
+            ON "payout_snapshot_entry" ("snapshotId", "address")
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_payout_snapshot_entry_snapshot_rank"
+            ON "payout_snapshot_entry" ("snapshotId", "rank")
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_payout_snapshot_entry_address"
+            ON "payout_snapshot_entry" ("address")
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "payout_balance" (
+                "address" varchar(62) PRIMARY KEY,
+                "balanceSats" bigint NOT NULL DEFAULT 0,
+                "totalPaidSats" bigint NOT NULL DEFAULT 0,
+                "lastAcceptedShareAt" timestamptz,
+                "updatedAt" timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_payout_balance_nonzero"
+            ON "payout_balance" ("balanceSats")
+            WHERE "balanceSats" != 0
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "payout_history" (
+                "id" bigserial PRIMARY KEY,
+                "blockHeight" bigint NOT NULL,
+                "payoutSnapshotId" bigint NOT NULL REFERENCES "payout_snapshot" ("id") ON DELETE CASCADE,
+                "address" varchar(62) NOT NULL,
+                "paidSats" bigint NOT NULL DEFAULT 0,
+                "percent" numeric NOT NULL DEFAULT 0,
+                "balanceBeforeSats" bigint NOT NULL DEFAULT 0,
+                "balanceAfterSats" bigint NOT NULL DEFAULT 0,
+                "rowType" varchar(16) NOT NULL DEFAULT 'coinbase',
+                "createdAt" timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+        `);
+        await queryRunner.query(`
+            CREATE UNIQUE INDEX IF NOT EXISTS "UQ_payout_history_block_address"
+            ON "payout_history" ("blockHeight", "address")
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_payout_history_address_created"
+            ON "payout_history" ("address", "createdAt" DESC)
+        `);
+
+        await queryRunner.query(`ALTER TABLE "blocks_entity" ADD COLUMN IF NOT EXISTS "payoutSnapshotId" bigint`);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_blocks_payout_snapshot"
+            ON "blocks_entity" ("payoutSnapshotId")
+            WHERE "payoutSnapshotId" IS NOT NULL
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_blocks_payout_snapshot"`);
+        await queryRunner.query(`ALTER TABLE "blocks_entity" DROP COLUMN IF EXISTS "payoutSnapshotId"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_payout_history_address_created"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "UQ_payout_history_block_address"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "payout_history"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_payout_balance_nonzero"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "payout_balance"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_payout_snapshot_entry_address"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_payout_snapshot_entry_snapshot_rank"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_payout_snapshot_entry_snapshot_address"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "payout_snapshot_entry"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_payout_snapshot_template_window"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_payout_snapshot_window"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_payout_snapshot_latest"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "payout_snapshot"`);
+    }
+}

src/ORM/_migrations/PoolAccountingDashboardIndexes1780867200000.ts

@@ -0,0 +1,22 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class PoolAccountingDashboardIndexes1780867200000 implements MigrationInterface {
+    public name = 'PoolAccountingDashboardIndexes1780867200000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_accepted_at"
+            ON "accepted_share_entity" ("acceptedAt" DESC)
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_accepted_share_round_best"
+            ON "accepted_share_entity" ("submissionDifficulty" DESC, "acceptedAt" DESC, "blockHeight")
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_round_best"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_accepted_share_accepted_at"`);
+    }
+}

src/ORM/_migrations/RemoveAcceptedShareRetention1780959000000.ts

@@ -0,0 +1,14 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class RemoveAcceptedShareRetention1780959000000 implements MigrationInterface {
+    public name = 'RemoveAcceptedShareRetention1780959000000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`SELECT remove_retention_policy('accepted_share_entity', if_exists => TRUE)`);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`SELECT add_retention_policy('accepted_share_entity', INTERVAL '30 days', if_not_exists => TRUE)`);
+    }
+}

src/ORM/_migrations/ShareRollupBatches1780962600000.ts

@@ -0,0 +1,62 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class ShareRollupBatches1780962600000 implements MigrationInterface {
+    public name = 'ShareRollupBatches1780962600000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "share_rollup_batch" (
+                "id" bigserial PRIMARY KEY,
+                "startShareIndex" bigint NOT NULL,
+                "endShareIndex" bigint NOT NULL,
+                "startAcceptedAt" timestamptz NOT NULL,
+                "endAcceptedAt" timestamptz NOT NULL,
+                "acceptedShareCount" bigint NOT NULL,
+                "creditedDifficulty" numeric NOT NULL,
+                "status" varchar(16) NOT NULL DEFAULT 'finalized',
+                "createdAt" timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                "finalizedAt" timestamptz,
+                CONSTRAINT "CHK_share_rollup_batch_index_order"
+                    CHECK ("endShareIndex" >= "startShareIndex")
+            )
+        `);
+        await queryRunner.query(`
+            CREATE UNIQUE INDEX IF NOT EXISTS "IDX_share_rollup_batch_range"
+            ON "share_rollup_batch" ("startShareIndex", "endShareIndex")
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_share_rollup_batch_finalized_end"
+            ON "share_rollup_batch" ("endShareIndex" DESC)
+            WHERE "status" = 'finalized'
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE IF NOT EXISTS "share_rollup_batch_summary" (
+                "batchId" bigint NOT NULL REFERENCES "share_rollup_batch" ("id") ON DELETE CASCADE,
+                "address" varchar(62) NOT NULL,
+                "clientName" varchar NOT NULL,
+                "protocol" varchar(8) NOT NULL,
+                "blockHeight" integer NOT NULL,
+                "creditedDifficulty" numeric NOT NULL,
+                "acceptedShareCount" bigint NOT NULL,
+                "bestSubmissionDifficulty" numeric NOT NULL,
+                "firstShareAt" timestamptz NOT NULL,
+                "lastShareAt" timestamptz NOT NULL,
+                PRIMARY KEY ("batchId", "address", "clientName", "protocol", "blockHeight")
+            )
+        `);
+        await queryRunner.query(`
+            CREATE INDEX IF NOT EXISTS "IDX_share_rollup_summary_address_batch"
+            ON "share_rollup_batch_summary" ("address", "clientName", "blockHeight", "batchId")
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_share_rollup_summary_address_batch"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "share_rollup_batch_summary"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_share_rollup_batch_finalized_end"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_share_rollup_batch_range"`);
+        await queryRunner.query(`DROP TABLE IF EXISTS "share_rollup_batch"`);
+    }
+}

src/ORM/_migrations/TimescaleOperationalHardening1780861200000.ts

@@ -0,0 +1,33 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class TimescaleOperationalHardening1780861200000 implements MigrationInterface {
+    public name = 'TimescaleOperationalHardening1780861200000';
+    public transaction = false;
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            ALTER TABLE "accepted_share_entity" SET (
+                timescaledb.compress,
+                timescaledb.compress_orderby = '"acceptedAt" DESC',
+                timescaledb.compress_segmentby = '"address","clientName"'
+            )
+        `);
+
+        await queryRunner.query(`
+            SELECT add_compression_policy(
+                'accepted_share_entity',
+                INTERVAL '1 day',
+                if_not_exists => TRUE
+            )
+        `);
+
+        await queryRunner.query(`SELECT remove_retention_policy('accepted_share_entity', if_exists => TRUE)`);
+        await queryRunner.query(`SELECT add_retention_policy('accepted_share_entity', INTERVAL '30 days', if_not_exists => TRUE)`);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`SELECT remove_compression_policy('accepted_share_entity', if_exists => TRUE)`);
+        await queryRunner.query(`SELECT remove_retention_policy('accepted_share_entity', if_exists => TRUE)`);
+        await queryRunner.query(`SELECT add_retention_policy('accepted_share_entity', INTERVAL '90 days', if_not_exists => TRUE)`);
+    }
+}

src/ORM/_migrations/UniqueNonceIndex.ts

@@ -4,12 +4,12 @@ export class UniqueNonceIndex implements MigrationInterface {
 
     public async up(queryRunner: QueryRunner): Promise<void> {
         await queryRunner.query(
-            `CREATE UNIQUE INDEX "IDX_unique_nonce" ON "client_entity" ("sessionId") WHERE "deletedAt" IS NOT NULL`
+            `CREATE UNIQUE INDEX IF NOT EXISTS "IDX_unique_nonce" ON "client_entity" ("sessionId") WHERE "deletedAt" IS NULL`
         );
     }
 
     public async down(queryRunner: QueryRunner): Promise<void> {
-        await queryRunner.query(`DROP INDEX "IDX_unique_nonce"`);
+        await queryRunner.query(`DROP INDEX IF EXISTS "IDX_unique_nonce"`);
     }
 
 }

src/ORM/_views/user-agent-report/user-agent-report.module.ts

@@ -3,12 +3,13 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { UserAgentReportService } from './user-agent-report.service';
 import { UserAgentReportView } from './user-agent-report.view';
+import { ClientEntity } from '../../client/client.entity';
 
 
 
 @Global()
 @Module({
-    imports: [TypeOrmModule.forFeature([UserAgentReportView])],
+    imports: [TypeOrmModule.forFeature([UserAgentReportView, ClientEntity])],
     providers: [UserAgentReportService],
     exports: [TypeOrmModule, UserAgentReportService],
 })

src/ORM/_views/user-agent-report/user-agent-report.service.ts

@@ -2,30 +2,106 @@ import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 
+import { ClientEntity } from '../../client/client.entity';
 import { UserAgentReportView } from './user-agent-report.view';
+import { RedisMessagingService } from '../../../services/redis-messaging.service';
 
 @Injectable()
 export class UserAgentReportService {
+    private readonly liveReportCacheKey = 'presence:user-agent-report';
+    private liveRefreshPromise: Promise<UserAgentReportView[]> | null = null;
 
     constructor(
         @InjectRepository(UserAgentReportView)
         private userAgentReport: Repository<UserAgentReportView>,
+        @InjectRepository(ClientEntity)
+        private clientRepository: Repository<ClientEntity>,
+        private redisMessagingService: RedisMessagingService,
     ) {
 
     }
 
     public async getReport() {
+        const cachedReport = await this.redisMessagingService
+            .getJsonCache<UserAgentReportView[]>(this.liveReportCacheKey)
+            .catch(error => {
+                console.error(`Live user-agent report cache read failed: ${error.message}`);
+                return null;
+            });
+        if (cachedReport != null) {
+            return cachedReport;
+        }
+
+        if (process.env.API_ONLY == 'true') {
             return await this.userAgentReport.find();
         }
 
+        return await this.refreshLiveReport();
+    }
+
+    public async refreshLiveReport() {
+        if (this.liveRefreshPromise != null) {
+            return this.liveRefreshPromise;
+        }
+
+        this.liveRefreshPromise = this.buildLiveReport()
+            .finally(() => {
+                this.liveRefreshPromise = null;
+            });
+
+        return this.liveRefreshPromise;
+    }
+
+    private async buildLiveReport() {
+        const presences = await this.redisMessagingService.getAllClientPresence();
+        const rows = new Map<string, {
+            userAgent: string;
+            count: number;
+            bestDifficulty: number;
+            totalHashRate: number;
+        }>();
+
+        presences.forEach(presence => {
+            const userAgent = presence.userAgent == null || presence.userAgent.length === 0
+                ? 'Other'
+                : presence.userAgent;
+            const row = rows.get(userAgent) ?? {
+                userAgent,
+                count: 0,
+                bestDifficulty: 0,
+                totalHashRate: 0,
+            };
+            row.count++;
+            row.bestDifficulty = Math.max(
+                row.bestDifficulty,
+                Number(presence.bestDifficulty ?? 0),
+            );
+            row.totalHashRate += Number(presence.hashRate ?? 0);
+            rows.set(userAgent, row);
+        });
+
+        const report = [...rows.values()]
+            .sort((left, right) => right.totalHashRate - left.totalHashRate)
+            .map(row => ({
+                userAgent: row.userAgent,
+                count: row.count.toString(),
+                bestDifficulty: row.bestDifficulty,
+                totalHashRate: row.totalHashRate.toString(),
+            }));
+
+        await this.redisMessagingService
+            .setJsonCache(this.liveReportCacheKey, report, 60 * 1000)
+            .catch(error => {
+                console.error(`Live user-agent report cache write failed: ${error.message}`);
+            });
+
+        return report;
+    }
+
     public async refreshReport() {
         try {
-            return await this.userAgentReport.query(`
+            await this.userAgentReport.query(`REFRESH MATERIALIZED VIEW user_agent_report_view`);
-            COMMIT;
+            return await this.refreshLiveReport();
-            BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
-            REFRESH MATERIALIZED VIEW user_agent_report_view;
-            COMMIT;
-        `);
         } catch (e) {
 
             console.log(e)

src/ORM/_views/user-agent-report/user-agent-report.view.ts

@@ -12,6 +12,7 @@ import { ClientEntity } from '../../client/client.entity';
             .addSelect('MAX(client.bestDifficulty)', 'bestDifficulty')
             .addSelect('SUM(client.hashRate)', 'totalHashRate')
             .from(ClientEntity, 'client')
+            .where('client.deletedAt IS NULL')
             .groupBy('client.userAgent')
             .orderBy('"totalHashRate"', 'DESC')
 })

src/ORM/accepted-share/accepted-share.entity.ts

@@ -0,0 +1,77 @@
+import { Column, Entity, Index, PrimaryColumn, PrimaryGeneratedColumn } from 'typeorm';
+
+@Entity()
+@Index('IDX_accepted_share_accounting_lookup', ['address', 'clientName', 'acceptedAt'])
+@Index('IDX_accepted_share_client_lookup', ['clientId', 'acceptedAt'])
+@Index('IDX_accepted_share_order', ['shareIndex'])
+@Index('IDX_accepted_share_unique_submission', ['acceptedAt', 'protocol', 'sessionId', 'jobId', 'nonce', 'ntime', 'version', 'extraNonce2'], { unique: true })
+export class AcceptedShareEntity {
+    @PrimaryGeneratedColumn('uuid')
+    id: string;
+
+    @PrimaryColumn({ type: 'timestamptz' })
+    acceptedAt: Date;
+
+    @Column({ type: 'bigint', default: () => `nextval('accepted_share_index_seq')` })
+    shareIndex: number;
+
+    @Column({ length: 16, type: 'varchar' })
+    protocol: 'sv1' | 'sv1_tls' | 'sv2' | 'sv2_jdp' | 'datum';
+
+    @Column({ length: 16, type: 'varchar', default: 'pool_template' })
+    workSource: 'pool_template' | 'miner_template';
+
+    @Column({ length: 16, type: 'varchar', default: 'pool' })
+    workProtocol: 'pool' | 'sv2_jdp' | 'datum';
+
+    @Column({ length: 62, type: 'varchar' })
+    address: string;
+
+    @Column()
+    clientName: string;
+
+    @Column({ length: 8, type: 'varchar' })
+    sessionId: string;
+
+    @Column({ type: 'uuid' })
+    clientId: string;
+
+    @Column()
+    jobId: string;
+
+    @Column()
+    jobTemplateId: string;
+
+    @Column({ type: 'bigint' })
+    blockHeight: number;
+
+    @Column({ type: 'decimal' })
+    creditedDifficulty: number;
+
+    @Column({ type: 'decimal' })
+    submissionDifficulty: number;
+
+    @Column({ type: 'decimal' })
+    networkDifficulty: number;
+
+    @Column()
+    nonce: string;
+
+    @Column()
+    ntime: string;
+
+    @Column()
+    version: string;
+
+    @Column()
+    extraNonce2: string;
+
+    @Column({ default: false })
+    isBlockCandidate: boolean;
+
+    @Column({ type: 'text', nullable: true })
+    blockSubmissionResult?: string;
+
+    @Column({ type: 'timestamptz', default: () => 'CURRENT_TIMESTAMP' })
+    createdAt: Date;
+}

src/ORM/blocks/blocks.entity.ts

@@ -24,4 +24,13 @@ export class BlocksEntity extends TrackedEntity {
     @Column()
     blockData: string;
 
+    @Column({ nullable: true })
+    blockHash?: string;
+
+    @Column({ type: 'varchar', nullable: true })
+    blockSubmissionResult?: string;
+
+    @Column({ type: 'bigint', nullable: true })
+    payoutSnapshotId?: string;
+
 }

src/ORM/blocks/blocks.service.spec.ts

@@ -0,0 +1,87 @@
+import * as bitcoinjs from 'bitcoinjs-lib';
+import { BlocksService } from './blocks.service';
+
+describe('BlocksService', () => {
+    it('computes block hash metadata when saving found blocks', async () => {
+        const repository = createRepository();
+        repository.findOne.mockResolvedValue(null);
+        const service = new BlocksService({} as any, repository as any);
+        const blockHex = createBlockHex();
+        const blockHash = bitcoinjs.Block.fromHex(blockHex).getId();
+
+        await service.save({
+            height: 123,
+            minerAddress: 'tb1qexample',
+            worker: 'worker',
+            sessionId: 'abcd1234',
+            blockData: blockHex,
+            blockSubmissionResult: 'SUCCESS!',
+        });
+
+        expect(repository.save).toHaveBeenCalledWith(expect.objectContaining({
+            blockHash,
+            blockSubmissionResult: 'SUCCESS!',
+        }));
+    });
+
+    it('does not downgrade an existing successful block on duplicate rejected submissions', async () => {
+        const repository = createRepository();
+        repository.findOne.mockResolvedValue({
+            id: 9,
+            blockSubmissionResult: 'SUCCESS!',
+            payoutSnapshotId: '7',
+        });
+        const service = new BlocksService({} as any, repository as any);
+
+        await service.save({
+            blockData: createBlockHex(),
+            blockSubmissionResult: 'duplicate',
+            payoutSnapshotId: '8',
+        });
+
+        expect(repository.update).not.toHaveBeenCalled();
+        expect(repository.save).not.toHaveBeenCalled();
+    });
+
+    it('returns one public found-block row per block hash or legacy height', async () => {
+        const repository = createRepository();
+        repository.find.mockResolvedValue([
+            { height: 124, minerAddress: 'addr2', worker: 'b', sessionId: '2222', blockHash: 'hash-b' },
+            { height: 124, minerAddress: 'addr2', worker: 'b-dup', sessionId: '3333', blockHash: 'hash-b' },
+            { height: 123, minerAddress: 'addr1', worker: 'a', sessionId: '1111', blockHash: null },
+            { height: 123, minerAddress: 'addr1', worker: 'a-dup', sessionId: '4444', blockHash: null },
+        ]);
+        const service = new BlocksService({} as any, repository as any);
+
+        await expect(service.getFoundBlocks()).resolves.toEqual([
+            { height: 124, minerAddress: 'addr2', worker: 'b', sessionId: '2222', blockHash: 'hash-b' },
+            { height: 123, minerAddress: 'addr1', worker: 'a', sessionId: '1111', blockHash: null },
+        ]);
+    });
+
+    function createRepository() {
+        return {
+            save: jest.fn().mockResolvedValue(undefined),
+            find: jest.fn().mockResolvedValue([]),
+            findOne: jest.fn().mockResolvedValue(null),
+            update: jest.fn().mockResolvedValue(undefined),
+        };
+    }
+
+    function createBlockHex(): string {
+        const tx = new bitcoinjs.Transaction();
+        tx.version = 1;
+        tx.addInput(Buffer.alloc(32), 0xffffffff, 0xffffffff, Buffer.from([0x01]));
+        tx.addOutput(Buffer.from('6a', 'hex'), 0);
+
+        const block = new bitcoinjs.Block();
+        block.version = 1;
+        block.prevHash = Buffer.alloc(32);
+        block.timestamp = 1;
+        block.bits = 0x207fffff;
+        block.nonce = 1;
+        block.transactions = [tx];
+        block.merkleRoot = bitcoinjs.Block.calculateMerkleRoot(block.transactions, false);
+        return block.toHex(false);
+    }
+});

src/ORM/blocks/blocks.service.ts

@@ -1,6 +1,7 @@
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { DataSource, Repository } from 'typeorm';
+import * as bitcoinjs from 'bitcoinjs-lib';
+import { DataSource, IsNull, Repository } from 'typeorm';
 
 import { BlocksEntity } from './blocks.entity';
 
@@ -19,31 +20,106 @@ export class BlocksService {
 
 
     public async save(block: Partial<BlocksEntity>) {
-        await this.blocksRepository.save(block);
+        const blockHash = block.blockHash ?? this.getBlockHash(block.blockData);
+        const existing = blockHash == null
+            ? null
+            : await this.blocksRepository.findOne({
+                select: { id: true, blockSubmissionResult: true, payoutSnapshotId: true },
+                where: { blockHash },
+            });
+        if (existing != null) {
+            if (this.isSuccessfulBlockSubmission(block.blockSubmissionResult)) {
+                await this.blocksRepository.update(existing.id, {
+                    blockSubmissionResult: 'SUCCESS!',
+                    payoutSnapshotId: block.payoutSnapshotId ?? existing.payoutSnapshotId,
+                });
+            }
+            return;
+        }
+
+        await this.blocksRepository.save({
+            ...block,
+            blockHash,
+        });
     }
 
     public async getFoundBlocks() {
-        return await this.blocksRepository.find({
+        const rows = await this.blocksRepository.find({
             select: {
                 height: true,
                 minerAddress: true,
                 worker: true,
-                sessionId: true
+                sessionId: true,
-            }
+                blockHash: true,
+                blockSubmissionResult: true,
+                createdAt: true,
+            },
+            where: [
+                { blockSubmissionResult: 'SUCCESS!' },
+                { blockSubmissionResult: IsNull() },
+            ],
+            order: {
+                height: 'DESC',
+                createdAt: 'DESC',
+            },
         });
+        return this.uniqueFoundBlocks(rows);
     }
 
     public async getFoundBlocksByAddress(address: string) {
-        return await this.blocksRepository.find({
+        const rows = await this.blocksRepository.find({
             select: {
                 height: true,
                 minerAddress: true,
                 worker: true,
-                sessionId: true
+                sessionId: true,
+                blockHash: true,
+                blockSubmissionResult: true,
+                createdAt: true,
             },
-            where: {
+            where: [
-                minerAddress: address
+                { minerAddress: address, blockSubmissionResult: 'SUCCESS!' },
+                { minerAddress: address, blockSubmissionResult: IsNull() },
+            ],
+            order: {
+                height: 'DESC',
+                createdAt: 'DESC',
+            },
+        });
+        return this.uniqueFoundBlocks(rows);
     }
+
+    private uniqueFoundBlocks(rows: Partial<BlocksEntity>[]): Partial<BlocksEntity>[] {
+        const seenBlocks = new Set<string>();
+        const seenHeights = new Set<number>();
+        return rows.filter(row => {
+            if (row.height != null && seenHeights.has(row.height)) {
+                return false;
+            }
+            const key = row.blockHash || `height:${row.height}`;
+            if (seenBlocks.has(key)) {
+                return false;
+            }
+            seenBlocks.add(key);
+            if (row.height != null) {
+                seenHeights.add(row.height);
+            }
+            return true;
         });
     }
+
+    private getBlockHash(blockData?: string): string | undefined {
+        if (blockData == null || blockData.length < 160) {
+            return undefined;
+        }
+        try {
+            return bitcoinjs.Block.fromHex(blockData).getId();
+        } catch {
+            return undefined;
+        }
+    }
+
+    private isSuccessfulBlockSubmission(result?: string | null): boolean {
+        return result == null || result === 'SUCCESS!';
+    }
 }

src/ORM/client-statistics/client-statistics.entity.ts

@@ -1,48 +0,0 @@
-import { Column, Entity, Index, ManyToOne } from 'typeorm';
-
-import { ClientEntity } from '../client/client.entity';
-import { PrimaryGeneratedBigIntColumn } from '../utils/PrimaryGeneratedBigIntColumn';
-import { TrackedEntity } from '../utils/TrackedEntity.entity';
-
-@Entity()
-//Index for statistics save
-@Index(["clientId", "time"])
-export class ClientStatisticsEntity extends TrackedEntity {
-
-    @PrimaryGeneratedBigIntColumn()
-    id: number;
-
-    @Column({ length: 62, type: 'varchar' })
-    address: string;
-
-    @Column()
-    clientName: string;
-
-    @Column({ length: 8, type: 'varchar' })
-    sessionId: string;
-
-    @Index()
-    @Column({ type: 'bigint' })
-    time: number;
-
-    @Column({ type: 'decimal' })
-    shares: number;
-
-    @Column({ default: 0, type: 'bigint' })
-    acceptedCount: number;
-
-
-
-    @ManyToOne(
-        () => ClientEntity,
-        clientEntity => clientEntity.statistics,
-        { nullable: false, }
-    )
-    client: ClientEntity;
-
-    @Index()
-    @Column({ name: 'clientId' })
-    public clientId: string;
-
-
-}

src/ORM/client-statistics/client-statistics.module.ts

@@ -1,14 +1,11 @@
 import { Global, Module } from '@nestjs/common';
-import { TypeOrmModule } from '@nestjs/typeorm';
 
-import { ClientStatisticsEntity } from './client-statistics.entity';
 import { ClientStatisticsService } from './client-statistics.service';
 
 
 @Global()
 @Module({
-    imports: [TypeOrmModule.forFeature([ClientStatisticsEntity])],
     providers: [ClientStatisticsService],
-    exports: [TypeOrmModule, ClientStatisticsService],
+    exports: [ClientStatisticsService],
 })
 export class ClientStatisticsModule { }

src/ORM/client-statistics/client-statistics.service.ts

@@ -1,264 +1,104 @@
 import { Injectable } from '@nestjs/common';
-import { InjectDataSource, InjectRepository } from '@nestjs/typeorm';
+import { InjectDataSource } from '@nestjs/typeorm';
-import { DataSource, Repository } from 'typeorm';
+import { DataSource } from 'typeorm';
-
-import { ClientStatisticsEntity } from './client-statistics.entity';
 
+const HASHES_PER_DIFFICULTY = 4294967296;
+const CHART_BUCKET_SECONDS = 600;
+const CHART_WINDOW = '24 hours';
+const SITE_CHART_WINDOW = '7 days';
 
 @Injectable()
 export class ClientStatisticsService {
 
-    private bulkAsyncUpdates: {
-        [key: string]: Partial<ClientStatisticsEntity>
-    } = {};
-
     constructor(
-
         @InjectDataSource()
         private dataSource: DataSource,
-        @InjectRepository(ClientStatisticsEntity)
-        private clientStatisticsRepository: Repository<ClientStatisticsEntity>,
     ) {
 
     }
 
-    // public async update(clientStatistic: Partial<ClientStatisticsEntity>) {
+    public async getChartDataForSite(limit: number = 144 * 7) {
-
+        return this.getAcceptedShareChartData('', [], limit, SITE_CHART_WINDOW);
-    //     await this.clientStatisticsRepository.update({ clientId: clientStatistic.clientId, time: clientStatistic.time },
-    //     {
-    //         shares: clientStatistic.shares,
-    //         acceptedCount: clientStatistic.acceptedCount,
-    //         updatedAt: new Date()
-    //     });
-    // }
-
-    public updateBulkAsync(clientStatistic: Partial<ClientStatisticsEntity>) {
-        const key = clientStatistic.clientId + clientStatistic.time.toString();
-        if(this.bulkAsyncUpdates[key] != null){
-            this.bulkAsyncUpdates[key].shares = clientStatistic.shares;
-            this.bulkAsyncUpdates[key].acceptedCount = clientStatistic.acceptedCount;
-            return;
     }
 
-        this.bulkAsyncUpdates[clientStatistic.clientId + clientStatistic.time.toString()] = clientStatistic;
-    }
-
-    public async doBulkAsyncUpdate(){
-        if(Object.keys(this.bulkAsyncUpdates).length < 1){
-            console.log('No client stats to update.')
-            return;
-        }
-
-        // Step 1: Prepare data for bulk update
-        const values = Object.entries(this.bulkAsyncUpdates).map(([key, value]) => {
-            return  `('${value.clientId}', ${value.time}, ${value.shares}, ${value.acceptedCount}, NOW())`
-        }).join(',');
-        
-    
-        const query = `
-            DO $$
-            BEGIN
-                CREATE TEMP TABLE temp_stats (
-                    "clientId" UUID,
-                    time BIGINT,
-                    shares NUMERIC,
-                    "acceptedCount" INT,
-                    "updatedAt" TIMESTAMP
-                ) ON COMMIT DROP;
-    
-                INSERT INTO temp_stats ("clientId", time, shares, "acceptedCount", "updatedAt")
-                VALUES ${values};
-    
-                UPDATE "client_statistics_entity" cse
-                SET shares = ts.shares,
-                    "acceptedCount" = ts."acceptedCount",
-                    "updatedAt" = ts."updatedAt"
-                FROM temp_stats ts
-                WHERE cse."clientId" = ts."clientId" AND cse.time = ts.time;
-            END;
-            $$;
-        `;
-    
-        try {
-            await this.clientStatisticsRepository.query(query);
-            //console.log(`Bulk updated ${Object.keys(this.bulkAsyncUpdates).length} statistics`)
-        } catch (error) {
-            console.error('Bulk update failed:', error.message, query);
-            throw error;
-        }
-
-        this.bulkAsyncUpdates = {};
-    }
-
-    public async insert(clientStatistic: Partial<ClientStatisticsEntity>) {
-        await this.clientStatisticsRepository.insert(clientStatistic);
-    }
-
-    public async deleteOldStatistics() {
-        const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
-
-        return await this.clientStatisticsRepository
-            .createQueryBuilder()
-            .delete()
-            .from(ClientStatisticsEntity)
-            .where('time < :time', { time: oneDayAgo.getTime() })
-            .execute();
-    }
-
-
-
     public async getChartDataForAddress(address: string) {
-
+        return this.getAcceptedShareChartData(
-        var yesterday = new Date(new Date().getTime() - (24 * 60 * 60 * 1000));
+            'AND "address" = $1',
-
+            [address],
-        const query = `
+            144,
-                SELECT
+            CHART_WINDOW,
-                    time AS label,
+        );
-                    (SUM(shares) * 4294967296) / 600 AS data
-                FROM
-                    client_statistics_entity AS entry
-                WHERE
-                    entry.address = $1 AND entry.time > $2
-                GROUP BY
-                    time
-                ORDER BY
-                    time
-                LIMIT 144;
-
-        `;
-
-        const result = await this.clientStatisticsRepository.query(query, [address, yesterday.getTime()]);
-
-        return result.map(res => {
-            res.label = new Date(parseInt(res.label)).toISOString();
-            return res;
-        }).slice(0, result.length - 1);
-
-
     }
 
-
     public async getHashRateForGroup(address: string, clientName: string) {
-
+        const result = await this.dataSource.query(`
-        var oneHour = new Date(new Date().getTime() - (60 * 60 * 1000));
-
-        const query = `
             SELECT
-            SUM(entry.shares) AS difficultySum
+                COALESCE((SUM("creditedDifficulty") * ${HASHES_PER_DIFFICULTY}) / ${CHART_BUCKET_SECONDS}, 0) AS "hashRate"
-            FROM
+            FROM "accepted_share_entity"
-                client_statistics_entity AS entry
+            WHERE "address" = $1
-            WHERE
+                AND "clientName" = $2
-                entry.address = $1 AND entry.clientName = $2 AND entry.time > ${oneHour.getTime()}
+                AND "acceptedAt" > NOW() - INTERVAL '1 hour'
-        `;
+        `, [address, clientName]);
-
-        const result = await this.clientStatisticsRepository.query(query, [address, clientName]);
-
-
-        const difficultySum = result[0].difficultySum;
-
-        return (difficultySum * 4294967296) / (600);
 
+        return parseFloat(result[0]?.hashRate ?? '0');
     }
 
     public async getChartDataForGroup(address: string, clientName: string) {
-        var yesterday = new Date(new Date().getTime() - (24 * 60 * 60 * 1000));
+        return this.getAcceptedShareChartData(
-
+            'AND "address" = $1 AND "clientName" = $2',
-        const query = `
+            [address, clientName],
-            SELECT
+            144,
-                time AS label,
+            CHART_WINDOW,
-                (SUM(shares) * 4294967296) / 600 AS data
+        );
-            FROM
-                client_statistics_entity AS entry
-            WHERE
-                entry.address = $1 AND entry."clientName" = $2 AND entry.time > ${yesterday.getTime()}
-            GROUP BY
-                time
-            ORDER BY
-                time
-            LIMIT 144;
-        `;
-
-        const result = await this.clientStatisticsRepository.query(query, [address, clientName]);
-
-        return result.map(res => {
-            res.label = new Date(parseInt(res.label)).toISOString();
-            return res;
-        }).slice(0, result.length - 1);
-
-
     }
 
-
-    // public async getHashRateForSession(clientId: string) {
-
-    //     const query = `
-    //         SELECT
-    //             "createdAt",
-    //             "updatedAt",
-    //             shares
-    //         FROM
-    //             client_statistics_entity AS entry
-    //         WHERE
-    //             entry."clientId" = $1
-    //         ORDER BY time DESC
-    //         LIMIT 2;
-    //     `;
-
-    //     const result = await this.clientStatisticsRepository.query(query, [clientId]);
-
-    //     if (result.length < 1) {
-    //         return 0;
-    //     }
-
-    //     const latestStat = result[0];
-
-    //     if (result.length < 2) {
-    //         const time = new Date(latestStat.updatedAt).getTime() - new Date(latestStat.createdAt).getTime();
-    //         // 1min
-    //         if (time < 1000 * 60) {
-    //             return 0;
-    //         }
-    //         return (parseFloat(latestStat.shares) * 4294967296) / (time / 1000);
-    //     } else {
-    //         const secondLatestStat = result[1];
-    //         const time = new Date(latestStat.updatedAt).getTime() - new Date(secondLatestStat.createdAt).getTime();
-    //         // 1min
-    //         if (time < 1000 * 60) {
-    //             return 0;
-    //         }
-    //         return ((parseFloat(latestStat.shares) + parseFloat(secondLatestStat.shares)) * 4294967296) / (time / 1000);
-    //     }
-
-    // }
-
     public async getChartDataForSession(clientId: string) {
-        var yesterday = new Date(new Date().getTime() - (24 * 60 * 60 * 1000));
+        return this.getAcceptedShareChartData(
+            'AND "clientId" = $1',
+            [clientId],
+            144,
+            CHART_WINDOW,
+        );
+    }
 
+    private async getAcceptedShareChartData(filterSql: string, params: unknown[], limit: number, windowSql: string) {
         const query = `
+            WITH bounds AS (
                 SELECT
-                time AS label,
+                    NOW() - INTERVAL '${windowSql}' AS since,
-                (SUM(shares) * 4294967296) / 600 AS data
+                    time_bucket(INTERVAL '10 minutes', NOW()) AS current_bucket
-            FROM
+            )
-                client_statistics_entity AS entry
+            SELECT
-            WHERE
+                "label",
-                entry."clientId" = $1 AND entry.time > ${yesterday.getTime()}
+                "data",
-            GROUP BY
+                "shares",
-                time
+                "acceptedCount"
-            ORDER BY
+            FROM (
-                time
+                SELECT
-            LIMIT 144;
+                    "bucket" AS "label",
+                    ROUND((SUM("shares") * ${HASHES_PER_DIFFICULTY}) / ${CHART_BUCKET_SECONDS}) AS "data",
+                    SUM("shares") AS "shares",
+                    SUM("acceptedCount") AS "acceptedCount"
+                FROM "accepted_share_10m", bounds
+                WHERE "bucket" > bounds.since
+                    AND "bucket" < bounds.current_bucket
+                    ${filterSql}
+                GROUP BY "bucket"
+                ORDER BY "bucket" DESC
+                LIMIT ${limit}
+            ) AS limited_rows
+            ORDER BY "label"
         `;
 
-        const result = await this.clientStatisticsRepository.query(query, [clientId]);
+        const result = await this.dataSource.query(query, params);
 
         return result.map(res => {
-            res.label = new Date(parseInt(res.label)).toISOString();
+            return {
-            return res;
+                label: new Date(res.label).toISOString(),
-        }).slice(0, result.length - 1);
+                data: res.data,
-
+                shares: Number(res.shares ?? 0),
-    }
+                acceptedCount: Number(res.acceptedCount ?? 0),
-
+            };
-    public async deleteAll() {
+        });
-        return await this.clientStatisticsRepository.clear()
     }
 }

src/ORM/client/client.entity.ts

@@ -1,6 +1,5 @@
-import { Column, Entity, Index, OneToMany, PrimaryGeneratedColumn } from 'typeorm';
+import { Column, Entity, Index, PrimaryGeneratedColumn } from 'typeorm';
 
-import { ClientStatisticsEntity } from '../client-statistics/client-statistics.entity';
 import { TrackedEntity } from '../utils/TrackedEntity.entity';
 
 
@@ -39,10 +38,4 @@ export class ClientEntity extends TrackedEntity {
     @Column({ default: 0, type: 'decimal' })
     hashRate: number;
 
-    @OneToMany(
-        () => ClientStatisticsEntity,
-        clientStatisticsEntity => clientStatisticsEntity.client
-    )
-    statistics: ClientStatisticsEntity[]
-
 }

src/ORM/client/client.service.ts

@@ -1,6 +1,6 @@
 import { Injectable } from '@nestjs/common';
-import { InjectDataSource, InjectRepository } from '@nestjs/typeorm';
+import { InjectRepository } from '@nestjs/typeorm';
-import { DataSource, Repository } from 'typeorm';
+import { Repository } from 'typeorm';
 
 import { ClientEntity } from './client.entity';
 
@@ -9,106 +9,13 @@ import { ClientEntity } from './client.entity';
 @Injectable()
 export class ClientService {
 
-    private heartbeatBulkUpdate: { [id: string]: { id: string, hashRate: number, updatedAt: Date } } = {};
-
     constructor(
-        @InjectDataSource()
-        private dataSource: DataSource,
         @InjectRepository(ClientEntity)
         private clientRepository: Repository<ClientEntity>
     ) {
 
     }
 
-    // client.service.ts
-    public async killDeadClients(): Promise<boolean> {
-        const BATCH_SIZE = 10000;
-
-        return this.dataSource.transaction('READ COMMITTED', async (manager) => {  // ← CHANGE HERE
-            const deadClients: { id: string }[] = await manager.query(`
-                SELECT id
-                FROM client_entity
-                WHERE "deletedAt" IS NULL
-                  AND "updatedAt" < NOW() - INTERVAL '5 minutes'
-                ORDER BY id
-                LIMIT $1
-                FOR UPDATE SKIP LOCKED
-            `, [BATCH_SIZE]);
-
-            if (deadClients.length === 0) {
-                return false;
-            }
-
-            await manager
-                .createQueryBuilder()
-                .update(ClientEntity)
-                .set({ deletedAt: () => 'NOW()' })
-                .whereInIds(deadClients.map(c => c.id))
-                .execute();
-
-            console.log(`Killed ${deadClients.length} dead clients`);
-
-            return true;
-        });
-    }
-
-    //public async heartbeat(id, hashRate: number, updatedAt: Date) {
-    //     return await this.clientRepository.update({ id }, { hashRate, deletedAt: null, updatedAt });
-    // }
-
-    public heartbeatBulkAsync(id, hashRate: number, updatedAt: Date) {
-        if (this.heartbeatBulkUpdate[id] != null) {
-            this.heartbeatBulkUpdate[id].hashRate = hashRate;
-            this.heartbeatBulkUpdate[id].updatedAt = updatedAt;
-            return;
-        }
-        this.heartbeatBulkUpdate[id] = { id, hashRate, updatedAt };
-    }
-
-    public async doBulkHeartbeatUpdate() {
-        if (Object.keys(this.heartbeatBulkUpdate).length < 1) {
-            console.log('No heartbeats to update.')
-            return;
-        }
-
-        const values = Object.entries(this.heartbeatBulkUpdate).map(([key, value]) => {
-            return `('${value.id}', ${value.hashRate}, NOW())`
-        }).join(',');
-
-        const query = `
-            DO $$
-            BEGIN
-                CREATE TEMP TABLE temp_heartbeats (
-                    id UUID,
-                    "hashRate" DECIMAL,
-                    "updatedAt" TIMESTAMP
-                ) ON COMMIT DROP;
-
-                INSERT INTO temp_heartbeats (id, "hashRate", "updatedAt")
-                VALUES ${values};
-
-                UPDATE "client_entity" ce
-                SET "hashRate" = th."hashRate",
-                    "deletedAt" = NULL,
-                    "updatedAt" = th."updatedAt"
-                FROM temp_heartbeats th
-                WHERE ce.id = th.id;
-            END;
-            $$;
-        `;
-
-        try {
-            await this.clientRepository.query(query);
-            console.log(`Bulk updated ${Object.keys(this.heartbeatBulkUpdate).length} client heartbeats`);
-        } catch (error) {
-            console.error('Bulk heartbeat failed:', error.message, 'Query:', query);
-            throw error;
-        }
-
-        this.heartbeatBulkUpdate = {};
-    }
-
-
     public async insert(partialClient: Partial<ClientEntity>): Promise<ClientEntity> {
         const insertResult = await this.clientRepository.insert(partialClient);
 
@@ -186,7 +93,9 @@ export class ClientService {
     public async deleteAll() {
         return await this.clientRepository
             .createQueryBuilder()
-            .softDelete()
+            .delete()
+            .from(ClientEntity)
+            .where('"deletedAt" IS NULL')
             .execute();
     }
 

src/ORM/home-graph/home-graph.entity.ts

@@ -1,16 +0,0 @@
-import { Column, Entity } from 'typeorm';
-
-import { PrimaryGeneratedBigIntColumn } from '../utils/PrimaryGeneratedBigIntColumn';
-
-@Entity()
-export class HomeGraphEntity {
-
-    @PrimaryGeneratedBigIntColumn()
-    id: number;
-
-    @Column({ type: 'bigint' })
-    label: number;
-
-    @Column({ type: 'bigint' })
-    data: number;
-}

src/ORM/home-graph/home-graph.module.ts

@@ -1,15 +0,0 @@
-import { Global, Module } from '@nestjs/common';
-import { TypeOrmModule } from '@nestjs/typeorm';
-
-import { HomeGraphEntity } from './home-graph.entity';
-import { HomeGraphService } from './home-graph.service';
-
-
-
-@Global()
-@Module({
-    imports: [TypeOrmModule.forFeature([HomeGraphEntity])],
-    providers: [HomeGraphService],
-    exports: [TypeOrmModule, HomeGraphService],
-})
-export class HomeGraphModule { }

src/ORM/home-graph/home-graph.service.ts

@@ -1,45 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
-
-import { HomeGraphEntity } from './home-graph.entity';
-
-@Injectable()
-export class HomeGraphService {
-    constructor(
-        @InjectRepository(HomeGraphEntity) private homeGraphRepository: Repository<HomeGraphEntity>
-    ) {
-
-    }
-
-    public async getLatestTime(): Promise<Date> {
-        const result = await this.homeGraphRepository.createQueryBuilder('entity')
-            .select('MAX(entity.label)', 'maxNumber')
-            .getRawOne();
-
-        if (result.maxNumber == null) {
-            return new Date(new Date().getTime() - (24 * 60 * 60 * 1000));
-        }
-
-        return new Date(parseInt(result.maxNumber));
-    }
-
-    public async save(graph: { label: number, data: number }[]) {
-        await this.homeGraphRepository.insert(graph);
-    }
-
-    public async getChartDataForSite(limit: number = 144 * 7) {
-        const records = await this.homeGraphRepository
-            .createQueryBuilder('homeGraph')
-            .orderBy('homeGraph.id', 'DESC')
-            .limit(limit)
-            .getRawMany();
-
-        return records.map(res => {
-            return {
-                label: new Date(parseInt(res.homeGraph_label)).toISOString(),
-                data: res.homeGraph_data
-            }
-        });
-    }
-}

src/ORM/payout-snapshot/payout-balance.entity.ts

@@ -0,0 +1,24 @@
+import { Column, Entity, PrimaryColumn, UpdateDateColumn } from 'typeorm';
+
+const bigintTransformer = {
+    from: (value: string | number | null): number => Number(value ?? 0),
+    to: (value: number): number => Math.trunc(value ?? 0),
+};
+
+@Entity({ name: 'payout_balance' })
+export class PayoutBalanceEntity {
+    @PrimaryColumn({ length: 62, type: 'varchar' })
+    address: string;
+
+    @Column({ type: 'bigint', default: 0, transformer: bigintTransformer })
+    balanceSats: number;
+
+    @Column({ type: 'bigint', default: 0, transformer: bigintTransformer })
+    totalPaidSats: number;
+
+    @Column({ type: 'timestamptz', nullable: true })
+    lastAcceptedShareAt: Date | null;
+
+    @UpdateDateColumn()
+    updatedAt: Date;
+}

src/ORM/payout-snapshot/payout-distribution.spec.ts

@@ -0,0 +1,135 @@
+import { buildPayoutDistribution } from './payout-distribution';
+
+const ADDRESS_A = 'bc1qs29kyaqqc0fkvj897ke9e5xa9utljjey0y5jjn';
+const ADDRESS_B = 'bc1q99n3pu025yyu0jlywpmwzalyhm36tg5u37w20d';
+const ADDRESS_C = 'bc1q7yx4d3xspf4xvssmsm4prf4mg2slkv8jtkc5l6';
+
+describe('buildPayoutDistribution', () => {
+    it('should conserve the full coinbase reward across outputs', () => {
+        const result = buildPayoutDistribution({
+            addressWork: [
+                { address: ADDRESS_A, creditedDifficulty: 2, acceptedShareCount: 2 },
+                { address: ADDRESS_B, creditedDifficulty: 1, acceptedShareCount: 1 },
+            ],
+            balances: [],
+            coinbaseValueSats: 1000,
+            feePercent: 0,
+            minOutputSats: 546,
+            coinbaseWeightBudget: 50_000,
+        });
+
+        expect(result.payoutOutputs.map(entry => ({
+            address: entry.address,
+            payoutSats: entry.payoutSats,
+            balanceAfterSats: entry.balanceAfterSats,
+        }))).toEqual([
+            { address: ADDRESS_A, payoutSats: 1000, balanceAfterSats: -334 },
+        ]);
+        expect(result.entries.find(entry => entry.address === ADDRESS_B))
+            .toEqual(expect.objectContaining({ includedInCoinbase: false, balanceAfterSats: 333 }));
+        expect(result.distributedSats).toBe(1000);
+        expect(result.unallocatedRemainderSats).toBe(0);
+    });
+
+    it('should carry sub-dust work forward as signed credit', () => {
+        const result = buildPayoutDistribution({
+            addressWork: [
+                { address: ADDRESS_A, creditedDifficulty: 999, acceptedShareCount: 999 },
+                { address: ADDRESS_B, creditedDifficulty: 1, acceptedShareCount: 1 },
+            ],
+            balances: [],
+            coinbaseValueSats: 1000,
+            feePercent: 0,
+            minOutputSats: 546,
+            coinbaseWeightBudget: 50_000,
+        });
+
+        const pending = result.entries.find(entry => entry.address === ADDRESS_B);
+        const paid = result.entries.find(entry => entry.address === ADDRESS_A);
+
+        expect(pending).toEqual(expect.objectContaining({
+            includedInCoinbase: false,
+            grossPayoutSats: 1,
+            payoutSats: 0,
+            balanceAfterSats: 1,
+        }));
+        expect(paid).toEqual(expect.objectContaining({
+            includedInCoinbase: true,
+            payoutSats: 1000,
+            balanceAfterSats: -1,
+        }));
+        expect(result.distributedSats).toBe(1000);
+    });
+
+    it('should trim outputs that do not fit the coinbase weight budget', () => {
+        const result = buildPayoutDistribution({
+            addressWork: [
+                { address: ADDRESS_A, creditedDifficulty: 10, acceptedShareCount: 1 },
+                { address: ADDRESS_B, creditedDifficulty: 9, acceptedShareCount: 1 },
+                { address: ADDRESS_C, creditedDifficulty: 8, acceptedShareCount: 1 },
+            ],
+            balances: [],
+            coinbaseValueSats: 3000,
+            feePercent: 0,
+            minOutputSats: 546,
+            coinbaseWeightBudget: 850,
+        });
+
+        expect(result.payoutOutputs).toHaveLength(1);
+        expect(result.payoutOutputs[0].address).toBe(ADDRESS_A);
+        expect(result.entries.find(entry => entry.address === ADDRESS_B))
+            .toEqual(expect.objectContaining({ includedInCoinbase: false, balanceAfterSats: 1000 }));
+        expect(result.entries.find(entry => entry.address === ADDRESS_C))
+            .toEqual(expect.objectContaining({ includedInCoinbase: false, balanceAfterSats: 888 }));
+    });
+
+    it('should apply positive and negative carried balances to the next distribution', () => {
+        const result = buildPayoutDistribution({
+            addressWork: [
+                { address: ADDRESS_A, creditedDifficulty: 10, acceptedShareCount: 1 },
+                { address: ADDRESS_B, creditedDifficulty: 10, acceptedShareCount: 1 },
+            ],
+            balances: [
+                { address: ADDRESS_A, balanceSats: 100 },
+                { address: ADDRESS_B, balanceSats: -100 },
+            ],
+            coinbaseValueSats: 2000,
+            feePercent: 0,
+            minOutputSats: 546,
+            coinbaseWeightBudget: 50_000,
+        });
+
+        expect(result.payoutOutputs.map(entry => ({
+            address: entry.address,
+            payoutSats: entry.payoutSats,
+            balanceAfterSats: entry.balanceAfterSats,
+        }))).toEqual([
+            { address: ADDRESS_A, payoutSats: 1100, balanceAfterSats: 0 },
+            { address: ADDRESS_B, payoutSats: 900, balanceAfterSats: 0 },
+        ]);
+        expect(result.unallocatedRemainderSats).toBe(0);
+    });
+
+    it('should reserve a configured fee output before miner distribution', () => {
+        const result = buildPayoutDistribution({
+            addressWork: [
+                { address: ADDRESS_A, creditedDifficulty: 1, acceptedShareCount: 1 },
+            ],
+            balances: [],
+            coinbaseValueSats: 100000,
+            feeAddress: ADDRESS_C,
+            feePercent: 2,
+            minOutputSats: 546,
+            coinbaseWeightBudget: 50_000,
+        });
+
+        expect(result.payoutOutputs[0]).toEqual(expect.objectContaining({
+            address: ADDRESS_C,
+            payoutSats: 2000,
+        }));
+        expect(result.payoutOutputs[1]).toEqual(expect.objectContaining({
+            address: ADDRESS_A,
+            payoutSats: 98000,
+        }));
+    });
+});

src/ORM/payout-snapshot/payout-distribution.ts

@@ -0,0 +1,276 @@
+import { AddressType, getAddressInfo } from 'bitcoin-address-validation';
+
+export interface PayoutAddressWork {
+    address: string;
+    creditedDifficulty: number;
+    acceptedShareCount: number;
+}
+
+export interface PayoutBalanceInput {
+    address: string;
+    balanceSats: number;
+}
+
+export interface PayoutDistributionEntry {
+    address: string;
+    creditedDifficulty: number;
+    acceptedShareCount: number;
+    payoutWeight: number;
+    grossPayoutSats: number;
+    payoutSats: number;
+    balanceBeforeSats: number;
+    balanceAfterSats: number;
+    includedInCoinbase: boolean;
+    rank: number;
+}
+
+export interface PayoutDistributionResult {
+    entries: PayoutDistributionEntry[];
+    payoutOutputs: PayoutDistributionEntry[];
+    consideredAddressCount: number;
+    distributedSats: number;
+    unallocatedRemainderSats: number;
+    feeSats: number;
+}
+
+export interface PayoutDistributionInput {
+    addressWork: PayoutAddressWork[];
+    balances: PayoutBalanceInput[];
+    coinbaseValueSats: number;
+    feeAddress?: string;
+    feePercent: number;
+    minOutputSats: number;
+    coinbaseWeightBudget: number;
+}
+
+const DEFAULT_COINBASE_WEIGHT_BUDGET = 50_000;
+const DUST_LIMIT_SATS = 546;
+const COINBASE_BASE_WEIGHT = 328;
+const COINBASE_WITNESS_COMMITMENT_WEIGHT = 188;
+const COINBASE_OUTPUT_WEIGHT = 172;
+const BUDGET_SAFETY_MARGIN_WEIGHT = 200;
+
+const OUTPUT_WEIGHT_BY_TYPE: Record<string, number> = {
+    [AddressType.p2wpkh]: 124,
+    [AddressType.p2sh]: 128,
+    [AddressType.p2pkh]: 136,
+    [AddressType.p2wsh]: 172,
+    [AddressType.p2tr]: 172,
+};
+
+const outputWeightCache = new Map<string, number>();
+
+interface ComputedAddress {
+    address: string;
+    creditedDifficulty: number;
+    acceptedShareCount: number;
+    payoutWeight: number;
+    rawFairSats: number;
+    balanceBeforeSats: number;
+    targetSats: number;
+    payoutSats: number;
+    balanceAfterSats: number;
+    includedInCoinbase: boolean;
+}
+
+export function buildPayoutDistribution(input: PayoutDistributionInput): PayoutDistributionResult {
+    const coinbaseValueSats = Math.max(0, Math.floor(input.coinbaseValueSats));
+    const minOutputSats = Math.max(DUST_LIMIT_SATS, Math.floor(input.minOutputSats));
+    const coinbaseWeightBudget = input.coinbaseWeightBudget > 0
+        ? input.coinbaseWeightBudget
+        : DEFAULT_COINBASE_WEIGHT_BUDGET;
+    const feePercent = Number.isFinite(input.feePercent) && input.feePercent > 0
+        ? input.feePercent
+        : 0;
+    const feeAddress = input.feeAddress?.trim() ?? '';
+    const wantedFeeSats = Math.floor((feePercent / 100) * coinbaseValueSats);
+    const feeSats = feeAddress.length > 0 && wantedFeeSats >= minOutputSats ? wantedFeeSats : 0;
+    const minerRewardSats = coinbaseValueSats - feeSats;
+
+    const workByAddress = new Map<string, { creditedDifficulty: number; acceptedShareCount: number }>();
+    for (const work of input.addressWork) {
+        if (!work.address || !Number.isFinite(work.creditedDifficulty) || work.creditedDifficulty <= 0) {
+            continue;
+        }
+        const existing = workByAddress.get(work.address) ?? { creditedDifficulty: 0, acceptedShareCount: 0 };
+        existing.creditedDifficulty += work.creditedDifficulty;
+        existing.acceptedShareCount += work.acceptedShareCount;
+        workByAddress.set(work.address, existing);
+    }
+
+    const balanceByAddress = new Map<string, number>();
+    for (const balance of input.balances) {
+        if (balance.address && Number.isFinite(balance.balanceSats) && balance.balanceSats !== 0) {
+            balanceByAddress.set(balance.address, Math.trunc(balance.balanceSats));
+        }
+    }
+
+    let totalCreditedDifficulty = 0;
+    for (const work of workByAddress.values()) {
+        totalCreditedDifficulty += work.creditedDifficulty;
+    }
+    if (coinbaseValueSats <= 0 || totalCreditedDifficulty <= 0) {
+        return {
+            entries: [],
+            payoutOutputs: [],
+            consideredAddressCount: 0,
+            distributedSats: 0,
+            unallocatedRemainderSats: coinbaseValueSats,
+            feeSats,
+        };
+    }
+
+    const computations = new Map<string, ComputedAddress>();
+    const considered = new Set<string>([...workByAddress.keys(), ...balanceByAddress.keys()]);
+
+    for (const address of considered) {
+        const work = workByAddress.get(address);
+        const creditedDifficulty = work?.creditedDifficulty ?? 0;
+        const acceptedShareCount = work?.acceptedShareCount ?? 0;
+        const payoutWeight = creditedDifficulty > 0 ? creditedDifficulty / totalCreditedDifficulty : 0;
+        const rawFairSats = Math.floor(payoutWeight * minerRewardSats);
+        const balanceBeforeSats = balanceByAddress.get(address) ?? 0;
+        const targetSats = rawFairSats + balanceBeforeSats;
+        computations.set(address, {
+            address,
+            creditedDifficulty,
+            acceptedShareCount,
+            payoutWeight,
+            rawFairSats,
+            balanceBeforeSats,
+            targetSats,
+            payoutSats: 0,
+            balanceAfterSats: targetSats,
+            includedInCoinbase: false,
+        });
+    }
+
+    const feeWeight = feeSats > 0 ? outputWeightForAddress(feeAddress) : 0;
+    let usedWeight = COINBASE_BASE_WEIGHT + COINBASE_WITNESS_COMMITMENT_WEIGHT + feeWeight;
+    const effectiveBudget = coinbaseWeightBudget - BUDGET_SAFETY_MARGIN_WEIGHT;
+    const eligible = [...computations.values()]
+        .filter(row => row.targetSats >= minOutputSats)
+        .sort((a, b) => b.targetSats - a.targetSats || a.address.localeCompare(b.address));
+
+    for (const row of eligible) {
+        const outputWeight = outputWeightForAddress(row.address);
+        if (usedWeight + outputWeight > effectiveBudget) {
+            continue;
+        }
+        row.includedInCoinbase = true;
+        row.payoutSats = row.targetSats;
+        row.balanceAfterSats = 0;
+        usedWeight += outputWeight;
+    }
+
+    let distributedToMiners = 0;
+    for (const row of computations.values()) {
+        distributedToMiners += row.payoutSats;
+    }
+
+    const remainder = minerRewardSats - distributedToMiners;
+    if (remainder > 0) {
+        const keptActive = [...computations.values()]
+            .filter(row => row.includedInCoinbase && row.creditedDifficulty > 0)
+            .sort((a, b) => b.creditedDifficulty - a.creditedDifficulty || a.address.localeCompare(b.address));
+        if (keptActive.length > 0) {
+            let assigned = 0;
+            for (const row of keptActive) {
+                const bonus = Math.floor((remainder * row.creditedDifficulty) / totalCreditedDifficulty);
+                row.payoutSats += bonus;
+                row.balanceAfterSats -= bonus;
+                assigned += bonus;
+            }
+            const residual = remainder - assigned;
+            if (residual > 0) {
+                keptActive[0].payoutSats += residual;
+                keptActive[0].balanceAfterSats -= residual;
+            }
+        }
+    }
+
+    const feeEntry = feeSats > 0
+        ? {
+            address: feeAddress,
+            creditedDifficulty: 0,
+            acceptedShareCount: 0,
+            payoutWeight: 0,
+            grossPayoutSats: feeSats,
+            payoutSats: feeSats,
+            balanceBeforeSats: 0,
+            balanceAfterSats: 0,
+            includedInCoinbase: true,
+            rank: 1,
+        }
+        : null;
+
+    const minerEntries = [...computations.values()]
+        .filter(row => row.includedInCoinbase || row.balanceBeforeSats !== row.balanceAfterSats || row.balanceAfterSats !== 0)
+        .sort((a, b) => {
+            if (a.includedInCoinbase !== b.includedInCoinbase) {
+                return a.includedInCoinbase ? -1 : 1;
+            }
+            return b.payoutSats - a.payoutSats || b.targetSats - a.targetSats || a.address.localeCompare(b.address);
+        })
+        .map(row => ({
+            address: row.address,
+            creditedDifficulty: row.creditedDifficulty,
+            acceptedShareCount: row.acceptedShareCount,
+            payoutWeight: row.payoutWeight,
+            grossPayoutSats: row.rawFairSats,
+            payoutSats: row.payoutSats,
+            balanceBeforeSats: row.balanceBeforeSats,
+            balanceAfterSats: row.balanceAfterSats,
+            includedInCoinbase: row.includedInCoinbase,
+            rank: 0,
+        }));
+
+    const mergedEntries = feeEntry == null
+        ? minerEntries
+        : mergeFeeEntry(feeEntry, minerEntries);
+    const entries = mergedEntries
+        .map((entry, index) => ({ ...entry, rank: index + 1 }));
+    const payoutOutputs = entries.filter(entry => entry.includedInCoinbase);
+    const distributedSats = payoutOutputs.reduce((sum, entry) => sum + entry.payoutSats, 0);
+
+    return {
+        entries,
+        payoutOutputs,
+        consideredAddressCount: considered.size,
+        distributedSats,
+        unallocatedRemainderSats: coinbaseValueSats - distributedSats,
+        feeSats,
+    };
+}
+
+function mergeFeeEntry(
+    feeEntry: PayoutDistributionEntry,
+    minerEntries: Omit<PayoutDistributionEntry, 'rank'>[],
+): Omit<PayoutDistributionEntry, 'rank'>[] {
+    const existing = minerEntries.find(entry => entry.address === feeEntry.address && entry.includedInCoinbase);
+    if (existing == null) {
+        return [feeEntry, ...minerEntries];
+    }
+    existing.payoutSats += feeEntry.payoutSats;
+    existing.grossPayoutSats += feeEntry.grossPayoutSats;
+    return minerEntries;
+}
+
+export function outputWeightForAddress(address: string): number {
+    if (!address) {
+        return COINBASE_OUTPUT_WEIGHT;
+    }
+    const cached = outputWeightCache.get(address);
+    if (cached != null) {
+        return cached;
+    }
+    let weight = COINBASE_OUTPUT_WEIGHT;
+    try {
+        const info = getAddressInfo(address);
+        weight = OUTPUT_WEIGHT_BY_TYPE[info.type] ?? COINBASE_OUTPUT_WEIGHT;
+    } catch {
+        weight = COINBASE_OUTPUT_WEIGHT;
+    }
+    outputWeightCache.set(address, weight);
+    return weight;
+}

src/ORM/payout-snapshot/payout-history.entity.ts

@@ -0,0 +1,41 @@
+import { Column, CreateDateColumn, Entity, Index, PrimaryGeneratedColumn } from 'typeorm';
+
+const bigintTransformer = {
+    from: (value: string | number | null): number => Number(value ?? 0),
+    to: (value: number): number => Math.trunc(value ?? 0),
+};
+
+@Entity({ name: 'payout_history' })
+@Index('UQ_payout_history_block_address', ['blockHeight', 'address'], { unique: true })
+@Index('IDX_payout_history_address_created', ['address', 'createdAt'])
+export class PayoutHistoryEntity {
+    @PrimaryGeneratedColumn({ type: 'bigint' })
+    id: string;
+
+    @Column({ type: 'bigint' })
+    blockHeight: number;
+
+    @Column({ type: 'bigint' })
+    payoutSnapshotId: string;
+
+    @Column({ length: 62, type: 'varchar' })
+    address: string;
+
+    @Column({ type: 'bigint', default: 0, transformer: bigintTransformer })
+    paidSats: number;
+
+    @Column({ type: 'decimal', default: 0 })
+    percent: number;
+
+    @Column({ type: 'bigint', default: 0, transformer: bigintTransformer })
+    balanceBeforeSats: number;
+
+    @Column({ type: 'bigint', default: 0, transformer: bigintTransformer })
+    balanceAfterSats: number;
+
+    @Column({ length: 16, type: 'varchar', default: 'coinbase' })
+    rowType: 'coinbase' | 'pending';
+
+    @CreateDateColumn()
+    createdAt: Date;
+}

src/ORM/payout-snapshot/payout-snapshot-entry.entity.ts

@@ -0,0 +1,54 @@
+import { Column, Entity, Index, JoinColumn, ManyToOne, PrimaryGeneratedColumn } from 'typeorm';
+
+import { PayoutSnapshotEntity } from './payout-snapshot.entity';
+
+@Entity({ name: 'payout_snapshot_entry' })
+@Index('IDX_payout_snapshot_entry_snapshot_rank', ['snapshotId', 'rank'])
+@Index('IDX_payout_snapshot_entry_address', ['address'])
+export class PayoutSnapshotEntryEntity {
+    @PrimaryGeneratedColumn({ type: 'bigint' })
+    id: string;
+
+    @Column({ type: 'bigint' })
+    snapshotId: string;
+
+    @ManyToOne(() => PayoutSnapshotEntity, snapshot => snapshot.entries, { onDelete: 'CASCADE' })
+    @JoinColumn({ name: 'snapshotId' })
+    snapshot: PayoutSnapshotEntity;
+
+    @Column({ length: 62, type: 'varchar' })
+    address: string;
+
+    @Column({ type: 'decimal' })
+    creditedDifficulty: number;
+
+    @Column({ type: 'bigint' })
+    acceptedShareCount: string;
+
+    @Column({ type: 'decimal' })
+    payoutWeight: number;
+
+    @Column({ type: 'bigint' })
+    grossPayoutSats: string;
+
+    @Column({ type: 'bigint' })
+    payoutSats: string;
+
+    @Column({ type: 'bigint', default: 0 })
+    balanceBeforeSats: string;
+
+    @Column({ type: 'bigint', default: 0 })
+    balanceAfterSats: string;
+
+    @Column({ type: 'boolean', default: true })
+    includedInCoinbase: boolean;
+
+    @Column({ length: 16, type: 'varchar', default: 'coinbase' })
+    rowType: 'coinbase' | 'pending';
+
+    @Column({ type: 'integer' })
+    rank: number;
+
+    @Column({ type: 'timestamptz', default: () => 'CURRENT_TIMESTAMP' })
+    createdAt: Date;
+}

src/ORM/payout-snapshot/payout-snapshot.entity.ts

@@ -0,0 +1,80 @@
+import { Column, Entity, Index, OneToMany, PrimaryGeneratedColumn } from 'typeorm';
+
+import { PayoutSnapshotEntryEntity } from './payout-snapshot-entry.entity';
+
+@Entity({ name: 'payout_snapshot' })
+@Index('IDX_payout_snapshot_latest', ['status', 'createdAt'])
+@Index('IDX_payout_snapshot_window', ['windowEndShareIndex'])
+export class PayoutSnapshotEntity {
+    @PrimaryGeneratedColumn({ type: 'bigint' })
+    id: string;
+
+    @Column({ length: 32, type: 'varchar' })
+    method: string;
+
+    @Column({ length: 16, type: 'varchar', default: 'finalized' })
+    status: 'finalized';
+
+    @Column({ type: 'bigint' })
+    blockHeight: number;
+
+    @Column({ type: 'bigint' })
+    coinbaseValueSats: string;
+
+    @Column({ type: 'decimal' })
+    networkDifficulty: number;
+
+    @Column({ type: 'decimal', default: 0 })
+    windowTargetDifficulty: number;
+
+    @Column({ type: 'decimal', default: 4 })
+    windowFactor: number;
+
+    @Column({ length: 62, type: 'varchar', nullable: true })
+    feeAddress?: string | null;
+
+    @Column({ type: 'bigint', default: 0 })
+    feeSats: string;
+
+    @Column({ type: 'integer', default: 546 })
+    minPayoutSats: number;
+
+    @Column({ type: 'integer', default: 50000 })
+    coinbaseWeightBudget: number;
+
+    @Column({ type: 'bigint' })
+    startBatchId: string;
+
+    @Column({ type: 'bigint' })
+    endBatchId: string;
+
+    @Column({ type: 'bigint' })
+    windowStartShareIndex: string;
+
+    @Column({ type: 'bigint' })
+    windowEndShareIndex: string;
+
+    @Column({ type: 'decimal' })
+    totalCreditedDifficulty: number;
+
+    @Column({ type: 'bigint' })
+    totalAcceptedShareCount: string;
+
+    @Column({ type: 'integer' })
+    eligibleAddressCount: number;
+
+    @Column({ type: 'integer' })
+    includedOutputCount: number;
+
+    @Column({ type: 'bigint' })
+    distributedSats: string;
+
+    @Column({ type: 'bigint' })
+    unallocatedRemainderSats: string;
+
+    @Column({ type: 'timestamptz', default: () => 'CURRENT_TIMESTAMP' })
+    createdAt: Date;
+
+    @OneToMany(() => PayoutSnapshotEntryEntity, entry => entry.snapshot)
+    entries: PayoutSnapshotEntryEntity[];
+}

src/ORM/payout-snapshot/payout-snapshot.module.ts

@@ -0,0 +1,21 @@
+import { Global, Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { PayoutBalanceEntity } from './payout-balance.entity';
+import { PayoutHistoryEntity } from './payout-history.entity';
+import { PayoutSnapshotEntryEntity } from './payout-snapshot-entry.entity';
+import { PayoutSnapshotEntity } from './payout-snapshot.entity';
+import { PayoutSnapshotService } from './payout-snapshot.service';
+
+@Global()
+@Module({
+    imports: [TypeOrmModule.forFeature([
+        PayoutBalanceEntity,
+        PayoutHistoryEntity,
+        PayoutSnapshotEntity,
+        PayoutSnapshotEntryEntity,
+    ])],
+    providers: [PayoutSnapshotService],
+    exports: [TypeOrmModule, PayoutSnapshotService],
+})
+export class PayoutSnapshotModule { }

src/ORM/payout-snapshot/payout-snapshot.service.spec.ts

@@ -0,0 +1,213 @@
+import { DataSource, EntityManager } from 'typeorm';
+
+import { PayoutSnapshotService } from './payout-snapshot.service';
+
+const ADDRESS_A = 'bc1qs29kyaqqc0fkvj897ke9e5xa9utljjey0y5jjn';
+const ADDRESS_B = 'bc1q99n3pu025yyu0jlywpmwzalyhm36tg5u37w20d';
+
+describe('PayoutSnapshotService', () => {
+    let originalEnv: NodeJS.ProcessEnv;
+    let manager: { query: jest.Mock };
+    let dataSource: { transaction: jest.Mock; query: jest.Mock };
+    let service: PayoutSnapshotService;
+
+    beforeEach(() => {
+        originalEnv = { ...process.env };
+        process.env.PAYOUT_SNAPSHOT_ENABLED = 'true';
+        process.env.PAYOUT_METHOD = 'pplns';
+        process.env.PAYOUT_WINDOW_FACTOR = '4';
+        process.env.PAYOUT_MAX_COINBASE_OUTPUTS = '10';
+        process.env.PAYOUT_MIN_OUTPUT_SATS = '546';
+        process.env.PAYOUT_FEE_PERCENT = '0';
+        process.env.PAYOUT_FEE_ADDRESS = '';
+        process.env.PAYOUT_COINBASE_WEIGHT_BUDGET = '50000';
+        manager = { query: jest.fn() };
+        dataSource = {
+            transaction: jest.fn(async callback => callback(manager as unknown as EntityManager)),
+            query: jest.fn(),
+        };
+        service = new PayoutSnapshotService(dataSource as unknown as DataSource);
+    });
+
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+
+    it('should create a PPLNS payout snapshot from finalized rollup batches', async () => {
+        manager.query
+            .mockResolvedValueOnce([{
+                startBatchId: '10',
+                endBatchId: '12',
+                windowStartShareIndex: '1000',
+                windowEndShareIndex: '2000',
+                totalCreditedDifficulty: '100',
+                totalAcceptedShareCount: '5',
+            }])
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([
+                { address: ADDRESS_A, creditedDifficulty: 60, acceptedShareCount: 3 },
+                { address: ADDRESS_B, creditedDifficulty: 40, acceptedShareCount: 2 },
+            ])
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([{ id: '55' }])
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([{
+                id: '55',
+                method: 'pplns',
+                blockHeight: 900000,
+                coinbaseValueSats: '1000',
+                windowStartShareIndex: '1000',
+                windowEndShareIndex: '2000',
+                totalCreditedDifficulty: 100,
+                totalAcceptedShareCount: '5',
+                eligibleAddressCount: 2,
+                includedOutputCount: 1,
+                distributedSats: '1000',
+                unallocatedRemainderSats: '0',
+            }])
+            .mockResolvedValueOnce([
+                { address: ADDRESS_A, payoutSats: '1000' },
+            ]);
+
+        const snapshot = await service.createSnapshotForTemplate({
+            blockHeight: 900000,
+            coinbaseValueSats: 1000,
+            networkDifficulty: 25,
+        });
+
+        expect(snapshot).toEqual(expect.objectContaining({
+            id: '55',
+            method: 'pplns',
+            blockHeight: 900000,
+            totalCreditedDifficulty: 100,
+            totalAcceptedShareCount: 5,
+            distributedSats: '1000',
+            unallocatedRemainderSats: '0',
+        }));
+        expect(snapshot.payoutOutputs).toEqual([
+            { address: ADDRESS_A, amountSats: 1000, percent: 100 },
+        ]);
+        expect(manager.query).toHaveBeenCalledTimes(9);
+        expect(manager.query.mock.calls[0][1]).toEqual([100]);
+    });
+
+    it('should not create a snapshot when there is no finalized rollup work', async () => {
+        manager.query.mockResolvedValueOnce([{
+            startBatchId: null,
+            endBatchId: null,
+            windowStartShareIndex: null,
+            windowEndShareIndex: null,
+            totalCreditedDifficulty: '0',
+            totalAcceptedShareCount: '0',
+        }]);
+
+        await expect(service.createSnapshotForTemplate({
+            blockHeight: 900000,
+            coinbaseValueSats: 1000,
+            networkDifficulty: 25,
+        })).resolves.toBeNull();
+        expect(manager.query).toHaveBeenCalledTimes(1);
+    });
+
+    it('should reuse an existing snapshot for the same template and rollup window', async () => {
+        manager.query
+            .mockResolvedValueOnce([{
+                startBatchId: '10',
+                endBatchId: '12',
+                windowStartShareIndex: '1000',
+                windowEndShareIndex: '2000',
+                totalCreditedDifficulty: '100',
+                totalAcceptedShareCount: '5',
+            }])
+            .mockResolvedValueOnce([{ id: '55' }])
+            .mockResolvedValueOnce([{
+                id: '55',
+                method: 'pplns',
+                blockHeight: 900000,
+                coinbaseValueSats: '1000',
+                windowStartShareIndex: '1000',
+                windowEndShareIndex: '2000',
+                totalCreditedDifficulty: 100,
+                totalAcceptedShareCount: '5',
+                eligibleAddressCount: 2,
+                includedOutputCount: 1,
+                distributedSats: '1000',
+                unallocatedRemainderSats: '0',
+            }])
+            .mockResolvedValueOnce([
+                { address: ADDRESS_A, payoutSats: '1000' },
+            ]);
+
+        const snapshot = await service.createSnapshotForTemplate({
+            blockHeight: 900000,
+            coinbaseValueSats: 1000,
+            networkDifficulty: 25,
+        });
+
+        expect(snapshot.id).toBe('55');
+        expect(snapshot.payoutOutputs).toEqual([
+            { address: ADDRESS_A, amountSats: 1000, percent: 100 },
+        ]);
+        expect(manager.query).toHaveBeenCalledTimes(4);
+    });
+
+    it('should finalize snapshot balances and payout history for a found block', async () => {
+        manager.query
+            .mockResolvedValueOnce([{ id: '55', coinbaseValueSats: '1000' }])
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([
+                {
+                    address: ADDRESS_A,
+                    payoutSats: '1000',
+                    balanceBeforeSats: '0',
+                    balanceAfterSats: '-400',
+                    creditedDifficulty: 60,
+                    includedInCoinbase: true,
+                    rowType: 'coinbase',
+                },
+                {
+                    address: ADDRESS_B,
+                    payoutSats: '0',
+                    balanceBeforeSats: '0',
+                    balanceAfterSats: '400',
+                    creditedDifficulty: 40,
+                    includedInCoinbase: false,
+                    rowType: 'pending',
+                },
+            ])
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([]);
+
+        await expect(service.finalizeSnapshotForBlock({
+            payoutSnapshotId: '55',
+            blockHeight: 900000,
+            blockSubmissionResult: 'SUCCESS!',
+        })).resolves.toEqual({
+            finalized: true,
+            payoutSnapshotId: '55',
+            historyRows: 2,
+            balanceRows: 2,
+        });
+        expect(manager.query).toHaveBeenCalledTimes(7);
+    });
+
+    it('should skip finalization when a block was already processed', async () => {
+        manager.query
+            .mockResolvedValueOnce([{ id: '55', coinbaseValueSats: '1000' }])
+            .mockResolvedValueOnce([{ id: '99' }]);
+
+        await expect(service.finalizeSnapshotForBlock({
+            payoutSnapshotId: '55',
+            blockHeight: 900000,
+            blockSubmissionResult: 'SUCCESS!',
+        })).resolves.toEqual({
+            finalized: false,
+            reason: 'already-finalized',
+            payoutSnapshotId: '55',
+        });
+        expect(manager.query).toHaveBeenCalledTimes(2);
+    });
+});

src/ORM/payout-snapshot/payout-snapshot.service.ts

@@ -0,0 +1,617 @@
+import { Injectable } from '@nestjs/common';
+import { DataSource, EntityManager } from 'typeorm';
+
+import type { AddressObject } from '../../models/MiningJob';
+import {
+    buildPayoutDistribution,
+    PayoutAddressWork,
+    PayoutBalanceInput,
+    PayoutDistributionEntry,
+} from './payout-distribution';
+
+export interface PayoutSnapshotForTemplate {
+    id: string;
+    method: string;
+    blockHeight: number;
+    coinbaseValueSats: string;
+    windowStartShareIndex: string;
+    windowEndShareIndex: string;
+    totalCreditedDifficulty: number;
+    totalAcceptedShareCount: number;
+    eligibleAddressCount: number;
+    includedOutputCount: number;
+    distributedSats: string;
+    unallocatedRemainderSats: string;
+    payoutOutputs: AddressObject[];
+}
+
+export interface PayoutFinalizationResult {
+    finalized: boolean;
+    reason?: 'disabled' | 'missing-snapshot' | 'already-finalized' | 'duplicate';
+    payoutSnapshotId?: string;
+    historyRows?: number;
+    balanceRows?: number;
+}
+
+const DEFAULT_MAX_COINBASE_OUTPUTS = 10;
+const DEFAULT_MIN_OUTPUT_SATS = 546;
+const DEFAULT_PAYOUT_METHOD = 'pplns';
+const DEFAULT_PAYOUT_WINDOW_FACTOR = 4;
+const DEFAULT_COINBASE_WEIGHT_BUDGET = 50_000;
+
+@Injectable()
+export class PayoutSnapshotService {
+    private readonly snapshotsEnabled = this.readBoolean('PAYOUT_SNAPSHOT_ENABLED', true);
+    private readonly method = process.env.PAYOUT_METHOD ?? DEFAULT_PAYOUT_METHOD;
+    private readonly windowFactor = this.readPositiveNumber('PAYOUT_WINDOW_FACTOR', DEFAULT_PAYOUT_WINDOW_FACTOR);
+    private readonly maxCoinbaseOutputs = this.readPositiveInt('PAYOUT_MAX_COINBASE_OUTPUTS', DEFAULT_MAX_COINBASE_OUTPUTS);
+    private readonly minOutputSats = this.readNonNegativeInt('PAYOUT_MIN_OUTPUT_SATS', DEFAULT_MIN_OUTPUT_SATS);
+    private readonly feeAddress = process.env.PAYOUT_FEE_ADDRESS?.trim() ?? '';
+    private readonly feePercent = this.readNonNegativeNumber('PAYOUT_FEE_PERCENT', 0);
+    private readonly coinbaseWeightBudget = this.readPositiveInt('PAYOUT_COINBASE_WEIGHT_BUDGET', DEFAULT_COINBASE_WEIGHT_BUDGET);
+
+    constructor(
+        private readonly dataSource: DataSource,
+    ) { }
+
+    public async createSnapshotForTemplate(input: {
+        blockHeight: number;
+        coinbaseValueSats: number;
+        networkDifficulty: number;
+    }): Promise<PayoutSnapshotForTemplate | null> {
+        if (!this.snapshotsEnabled || input.coinbaseValueSats <= 0 || input.networkDifficulty <= 0) {
+            return null;
+        }
+
+        return this.dataSource.transaction(async manager => {
+            const windowTargetDifficulty = input.networkDifficulty * this.windowFactor;
+            const window = await this.getPplnsWindow(manager, windowTargetDifficulty);
+            if (window == null || this.toNumber(window.totalCreditedDifficulty) <= 0) {
+                return null;
+            }
+
+            const existing = await this.getExistingSnapshot(manager, {
+                blockHeight: input.blockHeight,
+                coinbaseValueSats: input.coinbaseValueSats,
+                windowEndShareIndex: window.windowEndShareIndex,
+            });
+            if (existing != null) {
+                return existing;
+            }
+
+            const addressWork = await this.getAddressWork(manager, window);
+            const balances = await this.getOpenBalances(manager);
+            if (addressWork.length === 0) {
+                return null;
+            }
+
+            const distribution = buildPayoutDistribution({
+                addressWork,
+                balances,
+                coinbaseValueSats: input.coinbaseValueSats,
+                feeAddress: this.feeAddress,
+                feePercent: this.feePercent,
+                minOutputSats: this.minOutputSats,
+                coinbaseWeightBudget: this.coinbaseWeightBudget,
+            });
+            const entries = this.limitCoinbaseOutputs(distribution.entries);
+            if (entries.every(entry => !entry.includedInCoinbase)) {
+                return null;
+            }
+
+            const includedOutputCount = entries.filter(entry => entry.includedInCoinbase).length;
+            const distributedSats = entries
+                .filter(entry => entry.includedInCoinbase)
+                .reduce((sum, entry) => sum + entry.payoutSats, 0);
+            const unallocatedRemainderSats = input.coinbaseValueSats - distributedSats;
+            const [snapshotRow] = await manager.query(`
+                INSERT INTO "payout_snapshot" (
+                    "method",
+                    "status",
+                    "blockHeight",
+                    "coinbaseValueSats",
+                    "networkDifficulty",
+                    "windowTargetDifficulty",
+                    "windowFactor",
+                    "feeAddress",
+                    "feeSats",
+                    "minPayoutSats",
+                    "coinbaseWeightBudget",
+                    "startBatchId",
+                    "endBatchId",
+                    "windowStartShareIndex",
+                    "windowEndShareIndex",
+                    "totalCreditedDifficulty",
+                    "totalAcceptedShareCount",
+                    "eligibleAddressCount",
+                    "includedOutputCount",
+                    "distributedSats",
+                    "unallocatedRemainderSats"
+                ) VALUES (
+                    $1,
+                    'finalized',
+                    $2::bigint,
+                    $3::bigint,
+                    $4::numeric,
+                    $5::numeric,
+                    $6::numeric,
+                    NULLIF($7, ''),
+                    $8::bigint,
+                    $9::int,
+                    $10::int,
+                    $11::bigint,
+                    $12::bigint,
+                    $13::bigint,
+                    $14::bigint,
+                    $15::numeric,
+                    $16::bigint,
+                    $17::int,
+                    $18::int,
+                    $19::bigint,
+                    $20::bigint
+                )
+                RETURNING "id"::text AS "id"
+            `, [
+                this.method,
+                input.blockHeight,
+                input.coinbaseValueSats.toString(),
+                input.networkDifficulty,
+                windowTargetDifficulty,
+                this.windowFactor,
+                this.feeAddress,
+                distribution.feeSats.toString(),
+                this.minOutputSats,
+                this.coinbaseWeightBudget,
+                window.startBatchId,
+                window.endBatchId,
+                window.windowStartShareIndex,
+                window.windowEndShareIndex,
+                window.totalCreditedDifficulty,
+                window.totalAcceptedShareCount,
+                distribution.consideredAddressCount,
+                includedOutputCount,
+                distributedSats.toString(),
+                unallocatedRemainderSats.toString(),
+            ]);
+
+            for (const entry of entries) {
+                await this.insertSnapshotEntry(manager, snapshotRow.id, entry);
+            }
+
+            return this.getSnapshotById(manager, snapshotRow.id);
+        });
+    }
+
+    public async finalizeSnapshotForBlock(input: {
+        payoutSnapshotId?: string | null;
+        blockHeight: number;
+        blockSubmissionResult?: string | null;
+    }): Promise<PayoutFinalizationResult> {
+        if (!this.snapshotsEnabled) {
+            return { finalized: false, reason: 'disabled' };
+        }
+        if (!this.isSuccessfulBlockSubmission(input.blockSubmissionResult)) {
+            return { finalized: false, reason: 'missing-snapshot' };
+        }
+        if (input.payoutSnapshotId == null) {
+            return { finalized: false, reason: 'missing-snapshot' };
+        }
+
+        return this.dataSource.transaction<PayoutFinalizationResult>(async manager => {
+            const [snapshot] = await manager.query(`
+                SELECT "id"::text AS "id", "coinbaseValueSats"::text AS "coinbaseValueSats"
+                FROM "payout_snapshot"
+                WHERE "id" = $1::bigint
+                LIMIT 1
+            `, [input.payoutSnapshotId]);
+            if (snapshot == null) {
+                return { finalized: false, reason: 'missing-snapshot' };
+            }
+
+            const [existing] = await manager.query(`
+                SELECT "id"::text AS "id"
+                FROM "payout_history"
+                WHERE "blockHeight" = $1::bigint
+                LIMIT 1
+            `, [input.blockHeight]);
+            if (existing != null) {
+                return {
+                    finalized: false,
+                    reason: 'already-finalized',
+                    payoutSnapshotId: input.payoutSnapshotId,
+                };
+            }
+
+            const entries = await manager.query(`
+                SELECT
+                    "address",
+                    "payoutSats"::text AS "payoutSats",
+                    "balanceBeforeSats"::text AS "balanceBeforeSats",
+                    "balanceAfterSats"::text AS "balanceAfterSats",
+                    "creditedDifficulty"::float AS "creditedDifficulty",
+                    "includedInCoinbase",
+                    "rowType"
+                FROM "payout_snapshot_entry"
+                WHERE "snapshotId" = $1::bigint
+                ORDER BY "rank"
+            `, [input.payoutSnapshotId]);
+            if (entries.length === 0) {
+                return { finalized: false, reason: 'missing-snapshot' };
+            }
+
+            let balanceRows = 0;
+            let historyRows = 0;
+            const coinbaseValue = this.toNumber(snapshot.coinbaseValueSats);
+            for (const entry of entries) {
+                const payoutSats = this.toNumber(entry.payoutSats);
+                const balanceBeforeSats = this.toNumber(entry.balanceBeforeSats);
+                const balanceAfterSats = this.toNumber(entry.balanceAfterSats);
+                const isCoinbase = entry.includedInCoinbase === true;
+                const wasActive = this.toNumber(entry.creditedDifficulty) > 0;
+
+                await manager.query(`
+                    INSERT INTO "payout_balance" (
+                        "address",
+                        "balanceSats",
+                        "totalPaidSats",
+                        "lastAcceptedShareAt",
+                        "updatedAt"
+                    ) VALUES (
+                        $1,
+                        $2::bigint,
+                        $3::bigint,
+                        CASE WHEN $4::boolean THEN NOW() ELSE NULL END,
+                        NOW()
+                    )
+                    ON CONFLICT ("address") DO UPDATE SET
+                        "balanceSats" = EXCLUDED."balanceSats",
+                        "totalPaidSats" = "payout_balance"."totalPaidSats" + EXCLUDED."totalPaidSats",
+                        "lastAcceptedShareAt" = CASE
+                            WHEN $4::boolean THEN NOW()
+                            ELSE "payout_balance"."lastAcceptedShareAt"
+                        END,
+                        "updatedAt" = NOW()
+                `, [
+                    entry.address,
+                    balanceAfterSats.toString(),
+                    isCoinbase ? payoutSats.toString() : '0',
+                    wasActive,
+                ]);
+                balanceRows++;
+
+                await manager.query(`
+                    INSERT INTO "payout_history" (
+                        "blockHeight",
+                        "payoutSnapshotId",
+                        "address",
+                        "paidSats",
+                        "percent",
+                        "balanceBeforeSats",
+                        "balanceAfterSats",
+                        "rowType"
+                    ) VALUES (
+                        $1::bigint,
+                        $2::bigint,
+                        $3,
+                        $4::bigint,
+                        $5::numeric,
+                        $6::bigint,
+                        $7::bigint,
+                        $8
+                    )
+                    ON CONFLICT ("blockHeight", "address") DO NOTHING
+                `, [
+                    input.blockHeight,
+                    input.payoutSnapshotId,
+                    entry.address,
+                    payoutSats.toString(),
+                    coinbaseValue > 0 && isCoinbase ? (payoutSats / coinbaseValue) * 100 : 0,
+                    balanceBeforeSats.toString(),
+                    balanceAfterSats.toString(),
+                    isCoinbase ? 'coinbase' : 'pending',
+                ]);
+                historyRows++;
+            }
+
+            return {
+                finalized: true,
+                payoutSnapshotId: input.payoutSnapshotId,
+                historyRows,
+                balanceRows,
+            };
+        }).catch(error => {
+            if (error?.code === '23505') {
+                return {
+                    finalized: false,
+                    reason: 'duplicate',
+                    payoutSnapshotId: input.payoutSnapshotId ?? undefined,
+                };
+            }
+            throw error;
+        });
+    }
+
+    public async getLatestSnapshot(): Promise<PayoutSnapshotForTemplate | null> {
+        const [snapshot] = await this.dataSource.query(`
+            SELECT "id"::text AS "id"
+            FROM "payout_snapshot"
+            WHERE "status" = 'finalized'
+            ORDER BY "createdAt" DESC, "id" DESC
+            LIMIT 1
+        `);
+        if (snapshot?.id == null) {
+            return null;
+        }
+        return this.dataSource.transaction(manager => this.getSnapshotById(manager, snapshot.id));
+    }
+
+    private async getPplnsWindow(manager: EntityManager, windowTargetDifficulty: number): Promise<{
+        startBatchId: string;
+        endBatchId: string;
+        windowStartShareIndex: string;
+        windowEndShareIndex: string;
+        totalCreditedDifficulty: string;
+        totalAcceptedShareCount: string;
+    } | null> {
+        const [window] = await manager.query(`
+            WITH ordered AS MATERIALIZED (
+                SELECT
+                    "id",
+                    "startShareIndex",
+                    "endShareIndex",
+                    "acceptedShareCount",
+                    "creditedDifficulty",
+                    COALESCE(
+                        SUM("creditedDifficulty") OVER (
+                            ORDER BY "endShareIndex" DESC
+                            ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING
+                        ),
+                        0
+                    ) AS "difficultyAfter"
+                FROM "share_rollup_batch"
+                WHERE "status" = 'finalized'
+            ),
+            selected AS MATERIALIZED (
+                SELECT *
+                FROM ordered
+                WHERE "difficultyAfter" < $1::numeric
+            )
+            SELECT
+                MIN("id")::text AS "startBatchId",
+                MAX("id")::text AS "endBatchId",
+                MIN("startShareIndex")::text AS "windowStartShareIndex",
+                MAX("endShareIndex")::text AS "windowEndShareIndex",
+                COALESCE(SUM("creditedDifficulty"), 0)::numeric AS "totalCreditedDifficulty",
+                COALESCE(SUM("acceptedShareCount"), 0)::bigint AS "totalAcceptedShareCount"
+            FROM selected
+        `, [windowTargetDifficulty]);
+
+        if (window?.startBatchId == null || window?.windowEndShareIndex == null) {
+            return null;
+        }
+        return window;
+    }
+
+    private async getAddressWork(
+        manager: EntityManager,
+        window: { windowStartShareIndex: string; windowEndShareIndex: string },
+    ): Promise<PayoutAddressWork[]> {
+        const rows = await manager.query(`
+            SELECT
+                s."address",
+                COALESCE(SUM(s."creditedDifficulty"), 0)::float AS "creditedDifficulty",
+                COALESCE(SUM(s."acceptedShareCount"), 0)::int AS "acceptedShareCount"
+            FROM "share_rollup_batch_summary" s
+            JOIN "share_rollup_batch" b ON b."id" = s."batchId"
+            WHERE b."status" = 'finalized'
+              AND b."endShareIndex" >= $1::bigint
+              AND b."endShareIndex" <= $2::bigint
+            GROUP BY s."address"
+            HAVING COALESCE(SUM(s."creditedDifficulty"), 0) > 0
+        `, [
+            window.windowStartShareIndex,
+            window.windowEndShareIndex,
+        ]);
+        return rows.map(row => ({
+            address: row.address,
+            creditedDifficulty: this.toNumber(row.creditedDifficulty),
+            acceptedShareCount: this.toNumber(row.acceptedShareCount),
+        }));
+    }
+
+    private async getOpenBalances(manager: EntityManager): Promise<PayoutBalanceInput[]> {
+        const rows = await manager.query(`
+            SELECT "address", "balanceSats"::text AS "balanceSats"
+            FROM "payout_balance"
+            WHERE "balanceSats" != 0
+        `);
+        return rows.map(row => ({
+            address: row.address,
+            balanceSats: this.toNumber(row.balanceSats),
+        }));
+    }
+
+    private async getExistingSnapshot(
+        manager: EntityManager,
+        input: { blockHeight: number; coinbaseValueSats: number; windowEndShareIndex: string },
+    ): Promise<PayoutSnapshotForTemplate | null> {
+        const [snapshot] = await manager.query(`
+            SELECT "id"::text AS "id"
+            FROM "payout_snapshot"
+            WHERE "method" = $1
+              AND "status" = 'finalized'
+              AND "blockHeight" = $2::bigint
+              AND "coinbaseValueSats" = $3::bigint
+              AND "windowEndShareIndex" = $4::bigint
+            ORDER BY "id" DESC
+            LIMIT 1
+        `, [
+            this.method,
+            input.blockHeight,
+            input.coinbaseValueSats.toString(),
+            input.windowEndShareIndex,
+        ]);
+
+        if (snapshot?.id == null) {
+            return null;
+        }
+        return this.getSnapshotById(manager, snapshot.id);
+    }
+
+    private async getSnapshotById(manager: EntityManager, id: string): Promise<PayoutSnapshotForTemplate | null> {
+        const [snapshot] = await manager.query(`
+            SELECT
+                "id"::text AS "id",
+                "method",
+                "blockHeight"::int AS "blockHeight",
+                "coinbaseValueSats"::text AS "coinbaseValueSats",
+                "windowStartShareIndex"::text AS "windowStartShareIndex",
+                "windowEndShareIndex"::text AS "windowEndShareIndex",
+                "totalCreditedDifficulty"::float AS "totalCreditedDifficulty",
+                "totalAcceptedShareCount"::bigint AS "totalAcceptedShareCount",
+                "eligibleAddressCount",
+                "includedOutputCount",
+                "distributedSats"::text AS "distributedSats",
+                "unallocatedRemainderSats"::text AS "unallocatedRemainderSats"
+            FROM "payout_snapshot"
+            WHERE "id" = $1::bigint
+        `, [id]);
+        if (snapshot == null) {
+            return null;
+        }
+
+        const entries = await manager.query(`
+            SELECT
+                "address",
+                "payoutSats"::text AS "payoutSats"
+            FROM "payout_snapshot_entry"
+            WHERE "snapshotId" = $1::bigint
+              AND "includedInCoinbase" = true
+            ORDER BY "rank"
+        `, [id]);
+        const coinbaseValue = Number(snapshot.coinbaseValueSats);
+
+        return {
+            id: snapshot.id,
+            method: snapshot.method,
+            blockHeight: this.toNumber(snapshot.blockHeight),
+            coinbaseValueSats: snapshot.coinbaseValueSats,
+            windowStartShareIndex: snapshot.windowStartShareIndex,
+            windowEndShareIndex: snapshot.windowEndShareIndex,
+            totalCreditedDifficulty: this.toNumber(snapshot.totalCreditedDifficulty),
+            totalAcceptedShareCount: this.toNumber(snapshot.totalAcceptedShareCount),
+            eligibleAddressCount: this.toNumber(snapshot.eligibleAddressCount),
+            includedOutputCount: this.toNumber(snapshot.includedOutputCount),
+            distributedSats: snapshot.distributedSats,
+            unallocatedRemainderSats: snapshot.unallocatedRemainderSats,
+            payoutOutputs: entries.map(entry => ({
+                address: entry.address,
+                amountSats: this.toNumber(entry.payoutSats),
+                percent: coinbaseValue > 0
+                    ? (this.toNumber(entry.payoutSats) / coinbaseValue) * 100
+                    : 0,
+            })),
+        };
+    }
+
+    private async insertSnapshotEntry(manager: EntityManager, snapshotId: string, entry: PayoutDistributionEntry): Promise<void> {
+        await manager.query(`
+            INSERT INTO "payout_snapshot_entry" (
+                "snapshotId",
+                "address",
+                "creditedDifficulty",
+                "acceptedShareCount",
+                "payoutWeight",
+                "grossPayoutSats",
+                "payoutSats",
+                "balanceBeforeSats",
+                "balanceAfterSats",
+                "includedInCoinbase",
+                "rowType",
+                "rank"
+            ) VALUES (
+                $1::bigint,
+                $2,
+                $3::numeric,
+                $4::bigint,
+                $5::numeric,
+                $6::bigint,
+                $7::bigint,
+                $8::bigint,
+                $9::bigint,
+                $10::boolean,
+                $11,
+                $12::int
+            )
+        `, [
+            snapshotId,
+            entry.address,
+            entry.creditedDifficulty,
+            entry.acceptedShareCount,
+            entry.payoutWeight,
+            entry.grossPayoutSats,
+            entry.payoutSats,
+            entry.balanceBeforeSats,
+            entry.balanceAfterSats,
+            entry.includedInCoinbase,
+            entry.includedInCoinbase ? 'coinbase' : 'pending',
+            entry.rank,
+        ]);
+    }
+
+    private limitCoinbaseOutputs(entries: PayoutDistributionEntry[]): PayoutDistributionEntry[] {
+        let included = 0;
+        return entries.map(entry => {
+            if (!entry.includedInCoinbase) {
+                return entry;
+            }
+            included++;
+            if (included <= this.maxCoinbaseOutputs) {
+                return entry;
+            }
+            return {
+                ...entry,
+                payoutSats: 0,
+                balanceAfterSats: entry.balanceAfterSats + entry.payoutSats,
+                includedInCoinbase: false,
+            };
+        });
+    }
+
+    private isSuccessfulBlockSubmission(result?: string | null): boolean {
+        return result == null || result === 'SUCCESS!';
+    }
+
+    private toNumber(value: unknown): number {
+        const parsed = Number(value ?? 0);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+
+    private readPositiveInt(name: string, defaultValue: number): number {
+        const value = Number(process.env[name]);
+        return Number.isInteger(value) && value > 0 ? value : defaultValue;
+    }
+
+    private readNonNegativeInt(name: string, defaultValue: number): number {
+        const value = Number(process.env[name]);
+        return Number.isInteger(value) && value >= 0 ? value : defaultValue;
+    }
+
+    private readPositiveNumber(name: string, defaultValue: number): number {
+        const value = Number(process.env[name]);
+        return Number.isFinite(value) && value > 0 ? value : defaultValue;
+    }
+
+    private readNonNegativeNumber(name: string, defaultValue: number): number {
+        const value = Number(process.env[name]);
+        return Number.isFinite(value) && value >= 0 ? value : defaultValue;
+    }
+
+    private readBoolean(name: string, defaultValue: boolean): boolean {
+        const value = process.env[name]?.toLowerCase();
+        if (value == null || value.length === 0) {
+            return defaultValue;
+        }
+        return value === 'true' || value === '1' || value === 'yes';
+    }
+}

src/ORM/share-accounting/share-accounting.module.ts

@@ -0,0 +1,13 @@
+import { Global, Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { AcceptedShareEntity } from '../accepted-share/accepted-share.entity';
+import { ShareAccountingService } from './share-accounting.service';
+
+@Global()
+@Module({
+    imports: [TypeOrmModule.forFeature([AcceptedShareEntity])],
+    providers: [ShareAccountingService],
+    exports: [TypeOrmModule, ShareAccountingService],
+})
+export class ShareAccountingModule { }

src/ORM/share-accounting/share-accounting.service.spec.ts

@@ -0,0 +1,434 @@
+import { ShareAccountingService } from './share-accounting.service';
+
+describe('ShareAccountingService', () => {
+    const originalEnv = process.env;
+
+    beforeEach(() => {
+        jest.useRealTimers();
+        jest.restoreAllMocks();
+        process.env = { ...originalEnv };
+    });
+
+    afterAll(() => {
+        process.env = originalEnv;
+    });
+
+    it('should normalize and save accepted share records', async () => {
+        const repository = {
+            create: jest.fn(value => value),
+            insert: jest.fn().mockResolvedValue({}),
+        };
+        process.env.SHARE_ACCOUNTING_BATCH_SIZE = '1';
+        const service = new ShareAccountingService(repository as any);
+        const acceptedAt = new Date('2026-06-07T12:00:00Z');
+
+        await expect(service.recordAcceptedShare({
+            protocol: 'sv1',
+            acceptedAt,
+            address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+            clientName: 'worker',
+            sessionId: '57a6f098',
+            clientId: '6df7beea-921a-46cb-b7dc-e8075f916232',
+            jobId: '1',
+            jobTemplateId: '2',
+            blockHeight: 900000,
+            creditedDifficulty: 1024,
+            submissionDifficulty: 2048,
+            networkDifficulty: 100000,
+            nonce: 123,
+            ntime: 456,
+            version: 536870912,
+            extraNonce2: 'c708000000000000',
+            isBlockCandidate: false,
+            blockSubmissionResult: null,
+        })).resolves.toEqual(expect.objectContaining({
+            protocol: 'sv1',
+            creditedDifficulty: 1024,
+        }));
+
+        expect(repository.create).toHaveBeenCalledWith(expect.objectContaining({
+            acceptedAt,
+            nonce: '123',
+            ntime: '456',
+            version: '536870912',
+            blockSubmissionResult: null,
+        }));
+        expect(repository.insert).toHaveBeenCalledWith([expect.objectContaining({
+            protocol: 'sv1',
+            creditedDifficulty: 1024,
+        })]);
+    });
+
+    it('should accept TLS SV1 protocol labels for accounting', async () => {
+        const repository = {
+            create: jest.fn(value => value),
+            insert: jest.fn().mockResolvedValue({}),
+        };
+        process.env.SHARE_ACCOUNTING_BATCH_SIZE = '1';
+        const service = new ShareAccountingService(repository as any);
+
+        await expect(service.recordAcceptedShare({
+            ...buildRecord('sv1-tls'),
+            protocol: 'sv1_tls',
+        })).resolves.toEqual(expect.objectContaining({
+            protocol: 'sv1_tls',
+        }));
+
+        expect(repository.insert).toHaveBeenCalledWith([expect.objectContaining({
+            protocol: 'sv1_tls',
+        })]);
+    });
+
+    it('should batch accepted share inserts until the batch size is reached', async () => {
+        process.env.SHARE_ACCOUNTING_BATCH_SIZE = '2';
+        process.env.SHARE_ACCOUNTING_FLUSH_INTERVAL_MS = '1000';
+
+        const repository = {
+            create: jest.fn(value => value),
+            insert: jest.fn().mockResolvedValue({}),
+        };
+        const service = new ShareAccountingService(repository as any);
+
+        const first = service.recordAcceptedShare(buildRecord('1'));
+        expect(repository.insert).not.toHaveBeenCalled();
+
+        const second = service.recordAcceptedShare(buildRecord('2'));
+        await expect(Promise.all([first, second])).resolves.toHaveLength(2);
+
+        expect(repository.insert).toHaveBeenCalledTimes(1);
+        expect(repository.insert).toHaveBeenCalledWith([
+            expect.objectContaining({ jobId: '1' }),
+            expect.objectContaining({ jobId: '2' }),
+        ]);
+    });
+
+    it('should flush partial batches on the flush interval', async () => {
+        jest.useFakeTimers();
+        process.env.SHARE_ACCOUNTING_BATCH_SIZE = '10';
+        process.env.SHARE_ACCOUNTING_FLUSH_INTERVAL_MS = '25';
+
+        const repository = {
+            create: jest.fn(value => value),
+            insert: jest.fn().mockResolvedValue({}),
+        };
+        const service = new ShareAccountingService(repository as any);
+
+        const pending = service.recordAcceptedShare(buildRecord('interval'));
+        expect(repository.insert).not.toHaveBeenCalled();
+
+        jest.advanceTimersByTime(25);
+        await expect(pending).resolves.toEqual(expect.objectContaining({ jobId: 'interval' }));
+        expect(repository.insert).toHaveBeenCalledTimes(1);
+    });
+
+    it('should reject accepted shares when the accounting queue is full', async () => {
+        process.env.SHARE_ACCOUNTING_BATCH_SIZE = '10';
+        process.env.SHARE_ACCOUNTING_FLUSH_INTERVAL_MS = '1000';
+        process.env.SHARE_ACCOUNTING_MAX_QUEUE_SIZE = '1';
+
+        const repository = {
+            create: jest.fn(value => value),
+            insert: jest.fn().mockResolvedValue({}),
+        };
+        const service = new ShareAccountingService(repository as any);
+
+        const queued = service.recordAcceptedShare(buildRecord('queued'));
+
+        await expect(service.recordAcceptedShare(buildRecord('overflow')))
+            .rejects
+            .toThrow('Share accounting queue is full');
+        await service.flushPendingShares();
+        await expect(queued).resolves.toEqual(expect.objectContaining({ jobId: 'queued' }));
+    });
+
+    it('should return numeric accounting summaries from the share rollup', async () => {
+        const repository = {
+            query: jest.fn()
+                .mockResolvedValueOnce([{
+                    totalAcceptedShares: '3',
+                    totalCreditedDifficulty: '96',
+                    acceptedSharesLast10Minutes: '2',
+                    creditedDifficultyLast10Minutes: '64',
+                    acceptedSharesLastHour: '3',
+                    creditedDifficultyLastHour: '96',
+                    acceptedSharesLastDay: '3',
+                    creditedDifficultyLastDay: '96',
+                    hashRateLast10Minutes: '458129844.9',
+                    hashRateLastHour: '114532461.2',
+                    latestShareAt: new Date('2026-06-07T12:10:00Z'),
+                }]),
+        };
+        const service = new ShareAccountingService(repository as any);
+
+        await expect(service.getAddressSummary('bc1qtest')).resolves.toEqual({
+            totalAcceptedShares: 3,
+            totalCreditedDifficulty: 96,
+            acceptedSharesLast10Minutes: 2,
+            creditedDifficultyLast10Minutes: 64,
+            acceptedSharesLastHour: 3,
+            creditedDifficultyLastHour: 96,
+            acceptedSharesLastDay: 3,
+            creditedDifficultyLastDay: 96,
+            hashRateLast10Minutes: 458129844.9,
+            hashRateLastHour: 114532461.2,
+            bestSubmissionDifficulty: 0,
+            bestSubmissionDifficultyAt: null,
+            workSinceLastBlock: 0,
+            currentRoundAcceptedShares: 0,
+            currentRoundNetworkDifficulty: 0,
+            networkDifficultyPercent: 0,
+            blockCandidateCount: 0,
+            latestShareAt: '2026-06-07T12:10:00.000Z',
+            protocolBreakdown: [],
+        });
+        expect(repository.query).toHaveBeenNthCalledWith(
+            1,
+            expect.stringContaining('"accepted_share_10m"'),
+            ['bc1qtest'],
+        );
+        expect(repository.query).toHaveBeenCalledTimes(1);
+    });
+
+    it('should serve API-only address accounting from the share rollup instead of empty summaries', async () => {
+        process.env.API_ONLY = 'true';
+        const repository = {
+            query: jest.fn()
+                .mockResolvedValueOnce([{
+                    totalAcceptedShares: '12',
+                    totalCreditedDifficulty: '384',
+                    acceptedSharesLast10Minutes: '4',
+                    creditedDifficultyLast10Minutes: '128',
+                    acceptedSharesLastHour: '10',
+                    creditedDifficultyLastHour: '320',
+                    acceptedSharesLastDay: '12',
+                    creditedDifficultyLastDay: '384',
+                    hashRateLast10Minutes: '916259689.8',
+                    hashRateLastHour: '381774870.2',
+                    latestShareAt: new Date('2026-06-07T12:30:00Z'),
+                }]),
+        };
+        const service = new ShareAccountingService(repository as any);
+
+        await expect(service.getAddressSummary('bc1qapi')).resolves.toEqual(expect.objectContaining({
+            totalAcceptedShares: 12,
+            totalCreditedDifficulty: 384,
+            acceptedSharesLast10Minutes: 4,
+            creditedDifficultyLast10Minutes: 128,
+            hashRateLast10Minutes: 916259689.8,
+            latestShareAt: '2026-06-07T12:30:00.000Z',
+        }));
+        expect(repository.query).toHaveBeenCalledWith(
+            expect.stringContaining('FROM "accepted_share_10m"'),
+            ['bc1qapi'],
+        );
+        expect(repository.query).not.toHaveBeenCalledWith(
+            expect.stringContaining('FROM "accepted_share_entity"'),
+            expect.anything(),
+        );
+    });
+
+    it('should use Redis cache for share accounting summaries across API workers', async () => {
+        process.env.SHARE_ACCOUNTING_SUMMARY_CACHE_MS = '0';
+        const repository = {
+            query: jest.fn()
+                .mockResolvedValueOnce([{
+                    totalAcceptedShares: '1',
+                    totalCreditedDifficulty: '32',
+                    acceptedSharesLast10Minutes: '1',
+                    creditedDifficultyLast10Minutes: '32',
+                    acceptedSharesLastHour: '1',
+                    creditedDifficultyLastHour: '32',
+                    acceptedSharesLastDay: '1',
+                    creditedDifficultyLastDay: '32',
+                    hashRateLast10Minutes: '1',
+                    hashRateLastHour: '1',
+                    latestShareAt: null,
+                }]),
+        };
+        const redis = {
+            getJsonCache: jest.fn()
+                .mockResolvedValueOnce(null)
+                .mockResolvedValueOnce({
+                    ...new ShareAccountingService(repository as any).emptySummary(),
+                    totalAcceptedShares: 1,
+                }),
+            setJsonCache: jest.fn().mockResolvedValue(undefined),
+        };
+        const service = new ShareAccountingService(repository as any, redis as any);
+
+        await service.getAddressSummary('bc1qcached');
+        await expect(service.getAddressSummary('bc1qcached')).resolves.toEqual(expect.objectContaining({
+            totalAcceptedShares: 1,
+        }));
+
+        expect(repository.query).toHaveBeenCalledTimes(1);
+        expect(redis.setJsonCache).toHaveBeenCalledWith(
+            expect.stringContaining('accounting:summary:'),
+            expect.objectContaining({ totalAcceptedShares: 1 }),
+            30000,
+        );
+    });
+
+    it('should refresh pool summaries from completed rollup buckets and current round rollups', async () => {
+        const redis = {
+            getJsonCache: jest.fn().mockResolvedValue(null),
+            setJsonCache: jest.fn().mockResolvedValue(undefined),
+        };
+        const repository = {
+            query: jest.fn()
+                .mockResolvedValueOnce([{
+                    totalAcceptedShares: '3',
+                    totalCreditedDifficulty: '96',
+                    acceptedSharesLast10Minutes: '2',
+                    creditedDifficultyLast10Minutes: '64',
+                    acceptedSharesLastHour: '3',
+                    creditedDifficultyLastHour: '96',
+                    acceptedSharesLastDay: '3',
+                    creditedDifficultyLastDay: '96',
+                    hashRateLast10Minutes: '458129844.9',
+                    hashRateLastHour: '114532461.2',
+                    latestShareAt: new Date('2026-06-07T12:10:00Z'),
+                }])
+                .mockResolvedValueOnce([{
+                    bestSubmissionDifficulty: '4096',
+                    bestSubmissionDifficultyAt: new Date('2026-06-07T12:10:00Z'),
+                    currentRoundAcceptedShares: '11',
+                    workSinceLastBlock: '352',
+                    currentRoundNetworkDifficulty: '1000',
+                }]),
+        };
+        const service = new ShareAccountingService(repository as any, redis as any);
+
+        await expect(service.refreshPoolSummary()).resolves.toEqual(expect.objectContaining({
+            acceptedSharesLast10Minutes: 2,
+            creditedDifficultyLast10Minutes: 64,
+            hashRateLast10Minutes: 458129844.9,
+            bestSubmissionDifficulty: 4096,
+            bestSubmissionDifficultyAt: '2026-06-07T12:10:00.000Z',
+            workSinceLastBlock: 352,
+            currentRoundAcceptedShares: 11,
+            currentRoundNetworkDifficulty: 1000,
+            networkDifficultyPercent: 35.2,
+            latestShareAt: '2026-06-07T12:10:00.000Z',
+        }));
+        expect(repository.query).toHaveBeenNthCalledWith(
+            2,
+            expect.stringContaining('FROM "accepted_share_block_10m"'),
+        );
+        expect(repository.query).not.toHaveBeenCalledWith(
+            expect.stringContaining('FROM "accepted_share_entity"'),
+        );
+    });
+
+    it('should cache accounting summaries briefly to protect hot dashboard endpoints', async () => {
+        process.env.SHARE_ACCOUNTING_SUMMARY_CACHE_MS = '1000';
+        const repository = {
+            query: jest.fn()
+                .mockResolvedValueOnce([{
+                    totalAcceptedShares: '1',
+                    totalCreditedDifficulty: '32',
+                    acceptedSharesLast10Minutes: '1',
+                    creditedDifficultyLast10Minutes: '32',
+                    acceptedSharesLastHour: '1',
+                    creditedDifficultyLastHour: '32',
+                    acceptedSharesLastDay: '1',
+                    creditedDifficultyLastDay: '32',
+                    hashRateLast10Minutes: '1',
+                    hashRateLastHour: '1',
+                    latestShareAt: null,
+                }]),
+        };
+        const service = new ShareAccountingService(repository as any);
+
+        await service.getPoolSummary();
+        await service.getPoolSummary();
+
+        expect(repository.query).toHaveBeenCalledTimes(1);
+    });
+
+    it('should finalize accepted shares into an append-only share rollup batch', async () => {
+        const manager = {
+            query: jest.fn()
+                .mockResolvedValueOnce([{ locked: true }])
+                .mockResolvedValueOnce([{ lastProcessedShareIndex: '10' }])
+                .mockResolvedValueOnce([{ startShareIndex: '11', endShareIndex: '20', acceptedShareCount: 10 }])
+                .mockResolvedValueOnce([{
+                    startAcceptedAt: new Date('2026-06-07T12:00:00Z'),
+                    endAcceptedAt: new Date('2026-06-07T12:00:30Z'),
+                    acceptedShareCount: '10',
+                    creditedDifficulty: '2048',
+                }])
+                .mockResolvedValueOnce([{ batchId: '7' }])
+                .mockResolvedValueOnce([]),
+        };
+        const repository = {
+            manager: {
+                transaction: jest.fn(callback => callback(manager)),
+            },
+        };
+        const service = new ShareAccountingService(repository as any);
+
+        await expect(service.processPendingShareRollupBatch()).resolves.toEqual({
+            processed: true,
+            batchId: '7',
+            startShareIndex: '11',
+            endShareIndex: '20',
+            acceptedShareCount: 10,
+            creditedDifficulty: 2048,
+        });
+
+        expect(repository.manager.transaction).toHaveBeenCalledTimes(1);
+        expect(manager.query).toHaveBeenNthCalledWith(
+            1,
+            expect.stringContaining('pg_try_advisory_xact_lock'),
+            ['1780962600'],
+        );
+        expect(manager.query).toHaveBeenNthCalledWith(
+            6,
+            expect.stringContaining('INSERT INTO "share_rollup_batch_summary"'),
+            ['7', '11', '20'],
+        );
+    });
+
+    it('should skip share rollup work when another process holds the advisory lock', async () => {
+        const manager = {
+            query: jest.fn().mockResolvedValueOnce([{ locked: false }]),
+        };
+        const repository = {
+            manager: {
+                transaction: jest.fn(callback => callback(manager)),
+            },
+        };
+        const service = new ShareAccountingService(repository as any);
+
+        await expect(service.processPendingShareRollupBatch()).resolves.toEqual({
+            processed: false,
+            reason: 'locked',
+        });
+
+        expect(manager.query).toHaveBeenCalledTimes(1);
+    });
+});
+
+function buildRecord(jobId: string) {
+    return {
+        protocol: 'sv1' as const,
+        acceptedAt: new Date('2026-06-07T12:00:00Z'),
+        address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+        clientName: 'worker',
+        sessionId: '57a6f098',
+        clientId: '6df7beea-921a-46cb-b7dc-e8075f916232',
+        jobId,
+        jobTemplateId: 'template',
+        blockHeight: 900000,
+        creditedDifficulty: 1024,
+        submissionDifficulty: 2048,
+        networkDifficulty: 100000,
+        nonce: 123,
+        ntime: 456,
+        version: 536870912,
+        extraNonce2: 'c708000000000000',
+        isBlockCandidate: false,
+        blockSubmissionResult: null,
+    };
+}

src/ORM/share-accounting/share-accounting.service.ts

@@ -0,0 +1,770 @@
+import { Injectable, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { AcceptedShareEntity } from '../accepted-share/accepted-share.entity';
+import { RedisMessagingService } from '../../services/redis-messaging.service';
+
+export interface AcceptedShareRecord {
+    protocol: 'sv1' | 'sv1_tls' | 'sv2' | 'sv2_jdp' | 'datum';
+    workSource?: 'pool_template' | 'miner_template';
+    workProtocol?: 'pool' | 'sv2_jdp' | 'datum';
+    acceptedAt?: Date;
+    address: string;
+    clientName: string;
+    sessionId: string;
+    clientId: string;
+    jobId: string;
+    jobTemplateId: string;
+    blockHeight: number;
+    creditedDifficulty: number;
+    submissionDifficulty: number;
+    networkDifficulty: number;
+    nonce: string | number;
+    ntime: string | number;
+    version: string | number;
+    extraNonce2: string;
+    isBlockCandidate: boolean;
+    blockSubmissionResult?: string | null;
+}
+
+export interface ShareAccountingSummary {
+    totalAcceptedShares: number;
+    totalCreditedDifficulty: number;
+    acceptedSharesLast10Minutes: number;
+    creditedDifficultyLast10Minutes: number;
+    acceptedSharesLastHour: number;
+    creditedDifficultyLastHour: number;
+    acceptedSharesLastDay: number;
+    creditedDifficultyLastDay: number;
+    hashRateLast10Minutes: number;
+    hashRateLastHour: number;
+    bestSubmissionDifficulty: number;
+    bestSubmissionDifficultyAt: string | null;
+    workSinceLastBlock: number;
+    currentRoundAcceptedShares: number;
+    currentRoundNetworkDifficulty: number;
+    networkDifficultyPercent: number;
+    blockCandidateCount: number;
+    latestShareAt: string | null;
+    protocolBreakdown: {
+        protocol: string;
+        acceptedShares: number;
+        creditedDifficulty: number;
+    }[];
+}
+
+export interface SessionShareSummary {
+    clientId: string;
+    latestShareAt: string | null;
+    hashRateLast10Minutes: number;
+    bestSubmissionDifficulty: number;
+}
+
+export interface ShareRollupBatchResult {
+    processed: boolean;
+    reason?: 'disabled' | 'locked' | 'no-shares';
+    batchId?: string;
+    startShareIndex?: string;
+    endShareIndex?: string;
+    acceptedShareCount?: number;
+    creditedDifficulty?: number;
+}
+
+interface AccountingFilter {
+    address?: string;
+    clientName?: string;
+    clientId?: string;
+}
+
+const HASHES_PER_DIFFICULTY = 4294967296;
+const ROLLUP_BUCKET_SECONDS = 600;
+const DEFAULT_BATCH_SIZE = 500;
+const DEFAULT_FLUSH_INTERVAL_MS = 25;
+const DEFAULT_MAX_QUEUE_SIZE = 50000;
+const DEFAULT_SUMMARY_CACHE_MS = 2500;
+const DEFAULT_SUMMARY_CACHE_MAX = 10000;
+const DEFAULT_REDIS_SUMMARY_CACHE_MS = 30000;
+const DEFAULT_ROLLUP_INTERVAL_MS = 60000;
+const DEFAULT_ROLLUP_SAFETY_LAG_SECONDS = 10;
+const DEFAULT_ROLLUP_MAX_SHARES_PER_BATCH = 5000000;
+const SHARE_ROLLUP_ADVISORY_LOCK = '1780962600';
+
+@Injectable()
+export class ShareAccountingService implements OnModuleInit, OnModuleDestroy {
+    private pendingShares: PendingShare[] = [];
+    private flushTimer: NodeJS.Timeout | null = null;
+    private activeFlush: Promise<void> | null = null;
+    private rollupTimer: NodeJS.Timeout | null = null;
+    private activeRollup: Promise<void> | null = null;
+    private summaryCache = new Map<string, SummaryCacheEntry>();
+    private readonly poolSummaryCacheKey = 'accounting:pool-summary';
+    private readonly batchSize = this.readPositiveInt('SHARE_ACCOUNTING_BATCH_SIZE', DEFAULT_BATCH_SIZE);
+    private readonly flushIntervalMs = this.readPositiveInt('SHARE_ACCOUNTING_FLUSH_INTERVAL_MS', DEFAULT_FLUSH_INTERVAL_MS);
+    private readonly maxQueueSize = this.readPositiveInt('SHARE_ACCOUNTING_MAX_QUEUE_SIZE', DEFAULT_MAX_QUEUE_SIZE);
+    private readonly summaryCacheMs = this.readNonNegativeInt('SHARE_ACCOUNTING_SUMMARY_CACHE_MS', DEFAULT_SUMMARY_CACHE_MS);
+    private readonly summaryCacheMax = this.readPositiveInt('SHARE_ACCOUNTING_SUMMARY_CACHE_MAX', DEFAULT_SUMMARY_CACHE_MAX);
+    private readonly redisSummaryCacheMs = this.readNonNegativeInt('SHARE_ACCOUNTING_REDIS_SUMMARY_CACHE_MS', DEFAULT_REDIS_SUMMARY_CACHE_MS);
+    private readonly shareRollupEnabled = this.readBoolean('SHARE_ROLLUP_ENABLED', true);
+    private readonly shareRollupIntervalMs = this.readPositiveInt('SHARE_ROLLUP_INTERVAL_MS', DEFAULT_ROLLUP_INTERVAL_MS);
+    private readonly shareRollupSafetyLagSeconds = this.readNonNegativeInt('SHARE_ROLLUP_SAFETY_LAG_SECONDS', DEFAULT_ROLLUP_SAFETY_LAG_SECONDS);
+    private readonly shareRollupMaxSharesPerBatch = this.readPositiveInt('SHARE_ROLLUP_MAX_SHARES_PER_BATCH', DEFAULT_ROLLUP_MAX_SHARES_PER_BATCH);
+
+    constructor(
+        @InjectRepository(AcceptedShareEntity)
+        private readonly acceptedShareRepository: Repository<AcceptedShareEntity>,
+        private readonly redisMessagingService?: RedisMessagingService,
+    ) { }
+
+    public onModuleInit(): void {
+        this.startShareRollupTimer();
+    }
+
+    public async recordAcceptedShare(record: AcceptedShareRecord): Promise<AcceptedShareEntity> {
+        const acceptedShare = this.acceptedShareRepository.create({
+            ...record,
+            workSource: record.workSource ?? 'pool_template',
+            workProtocol: record.workProtocol ?? 'pool',
+            acceptedAt: record.acceptedAt ?? new Date(),
+            nonce: record.nonce.toString(),
+            ntime: record.ntime.toString(),
+            version: record.version.toString(),
+            blockSubmissionResult: record.blockSubmissionResult == null
+                ? null
+                : record.blockSubmissionResult.toString(),
+        });
+
+        if (this.pendingShares.length >= this.maxQueueSize) {
+            throw new Error(`Share accounting queue is full (${this.maxQueueSize})`);
+        }
+
+        return await new Promise<AcceptedShareEntity>((resolve, reject) => {
+            this.pendingShares.push({ entity: acceptedShare, resolve, reject });
+
+            if (this.pendingShares.length >= this.batchSize) {
+                this.startFlush();
+                return;
+            }
+
+            this.scheduleFlush();
+        });
+    }
+
+    public async flushPendingShares(): Promise<void> {
+        while (this.pendingShares.length > 0 || this.activeFlush != null) {
+            if (this.activeFlush != null) {
+                await this.activeFlush;
+                continue;
+            }
+
+            this.startFlush();
+        }
+    }
+
+    public async onModuleDestroy(): Promise<void> {
+        if (this.rollupTimer != null) {
+            clearInterval(this.rollupTimer);
+            this.rollupTimer = null;
+        }
+        if (this.activeRollup != null) {
+            await this.activeRollup;
+        }
+        await this.flushPendingShares();
+    }
+
+    public async processPendingShareRollupBatch(): Promise<ShareRollupBatchResult> {
+        if (!this.shareRollupEnabled) {
+            return { processed: false, reason: 'disabled' };
+        }
+
+        return this.acceptedShareRepository.manager.transaction(async manager => {
+            const [lockRow] = await manager.query(`
+                SELECT pg_try_advisory_xact_lock($1::bigint) AS "locked"
+            `, [SHARE_ROLLUP_ADVISORY_LOCK]);
+
+            if (lockRow?.locked !== true) {
+                return { processed: false, reason: 'locked' };
+            }
+
+            const [lastRow] = await manager.query(`
+                SELECT COALESCE(MAX("endShareIndex"), 0)::text AS "lastProcessedShareIndex"
+                FROM "share_rollup_batch"
+                WHERE "status" = 'finalized'
+            `);
+            const lastProcessedShareIndex = lastRow?.lastProcessedShareIndex ?? '0';
+
+            const [rangeRow] = await manager.query(`
+                WITH last_state AS MATERIALIZED (
+                    SELECT $1::bigint AS "lastProcessedShareIndex"
+                ),
+                first_unstable AS MATERIALIZED (
+                    SELECT MIN("shareIndex") AS "firstUnstableShareIndex"
+                    FROM "accepted_share_entity", last_state
+                    WHERE "shareIndex" > last_state."lastProcessedShareIndex"
+                      AND "acceptedAt" > NOW() - ($2::int * INTERVAL '1 second')
+                ),
+                stable_bound AS MATERIALIZED (
+                    SELECT
+                        CASE
+                            WHEN (SELECT "firstUnstableShareIndex" FROM first_unstable) IS NULL THEN (
+                                SELECT MAX("shareIndex")
+                                FROM "accepted_share_entity", last_state
+                                WHERE "shareIndex" > last_state."lastProcessedShareIndex"
+                            )
+                            ELSE (SELECT "firstUnstableShareIndex" FROM first_unstable) - 1
+                        END AS "maxStableShareIndex"
+                ),
+                bounded AS MATERIALIZED (
+                    SELECT "shareIndex"
+                    FROM "accepted_share_entity", last_state, stable_bound
+                    WHERE "shareIndex" > last_state."lastProcessedShareIndex"
+                      AND "shareIndex" <= stable_bound."maxStableShareIndex"
+                    ORDER BY "shareIndex" ASC
+                    LIMIT $3::int
+                )
+                SELECT
+                    MIN("shareIndex")::text AS "startShareIndex",
+                    MAX("shareIndex")::text AS "endShareIndex",
+                    COUNT(*)::int AS "acceptedShareCount"
+                FROM bounded
+            `, [
+                lastProcessedShareIndex,
+                this.shareRollupSafetyLagSeconds,
+                this.shareRollupMaxSharesPerBatch,
+            ]);
+
+            if (rangeRow?.startShareIndex == null || rangeRow?.endShareIndex == null || this.toNumber(rangeRow.acceptedShareCount) === 0) {
+                return { processed: false, reason: 'no-shares' };
+            }
+
+            const [statsRow] = await manager.query(`
+                SELECT
+                    MIN("acceptedAt") AS "startAcceptedAt",
+                    MAX("acceptedAt") AS "endAcceptedAt",
+                    COUNT(*)::bigint AS "acceptedShareCount",
+                    COALESCE(SUM("creditedDifficulty"), 0)::numeric AS "creditedDifficulty"
+                FROM "accepted_share_entity"
+                WHERE "shareIndex" >= $1::bigint
+                  AND "shareIndex" <= $2::bigint
+            `, [rangeRow.startShareIndex, rangeRow.endShareIndex]);
+
+            if (statsRow?.startAcceptedAt == null || this.toNumber(statsRow.acceptedShareCount) === 0) {
+                return { processed: false, reason: 'no-shares' };
+            }
+
+            const [batchRow] = await manager.query(`
+                INSERT INTO "share_rollup_batch" (
+                    "startShareIndex",
+                    "endShareIndex",
+                    "startAcceptedAt",
+                    "endAcceptedAt",
+                    "acceptedShareCount",
+                    "creditedDifficulty",
+                    "status",
+                    "finalizedAt"
+                ) VALUES (
+                    $1::bigint,
+                    $2::bigint,
+                    $3::timestamptz,
+                    $4::timestamptz,
+                    $5::bigint,
+                    $6::numeric,
+                    'finalized',
+                    NOW()
+                )
+                RETURNING "id"::text AS "batchId"
+            `, [
+                rangeRow.startShareIndex,
+                rangeRow.endShareIndex,
+                statsRow.startAcceptedAt,
+                statsRow.endAcceptedAt,
+                statsRow.acceptedShareCount,
+                statsRow.creditedDifficulty,
+            ]);
+
+            await manager.query(`
+                INSERT INTO "share_rollup_batch_summary" (
+                    "batchId",
+                    "address",
+                    "clientName",
+                    "protocol",
+                    "blockHeight",
+                    "creditedDifficulty",
+                    "acceptedShareCount",
+                    "bestSubmissionDifficulty",
+                    "firstShareAt",
+                    "lastShareAt"
+                )
+                SELECT
+                    $1::bigint AS "batchId",
+                    "address",
+                    "clientName",
+                    "protocol",
+                    "blockHeight",
+                    SUM("creditedDifficulty") AS "creditedDifficulty",
+                    COUNT(*)::bigint AS "acceptedShareCount",
+                    MAX("submissionDifficulty") AS "bestSubmissionDifficulty",
+                    MIN("acceptedAt") AS "firstShareAt",
+                    MAX("acceptedAt") AS "lastShareAt"
+                FROM "accepted_share_entity"
+                WHERE "shareIndex" >= $2::bigint
+                  AND "shareIndex" <= $3::bigint
+                GROUP BY "address", "clientName", "protocol", "blockHeight"
+            `, [
+                batchRow.batchId,
+                rangeRow.startShareIndex,
+                rangeRow.endShareIndex,
+            ]);
+
+            return {
+                processed: true,
+                batchId: batchRow.batchId,
+                startShareIndex: rangeRow.startShareIndex,
+                endShareIndex: rangeRow.endShareIndex,
+                acceptedShareCount: this.toNumber(statsRow.acceptedShareCount),
+                creditedDifficulty: this.toNumber(statsRow.creditedDifficulty),
+            };
+        });
+    }
+
+    public async getPoolSummary(): Promise<ShareAccountingSummary> {
+        const cached = await this.redisMessagingService
+            ?.getJsonCache<ShareAccountingSummary>(this.poolSummaryCacheKey)
+            .catch(error => {
+                console.error(`Pool accounting summary cache read failed: ${error.message}`);
+                return null;
+            });
+        if (cached != null) {
+            return cached;
+        }
+
+        if (process.env.API_ONLY === 'true') {
+            return this.emptySummary();
+        }
+
+        return this.getSummary({});
+    }
+
+    public async refreshPoolSummary(): Promise<ShareAccountingSummary> {
+        const summary = await this.withPoolRollupOverlay(await this.getSummary({}));
+        await this.redisMessagingService
+            ?.setJsonCache(this.poolSummaryCacheKey, summary, 10 * 60 * 1000)
+            .catch(error => {
+                console.error(`Pool accounting summary cache write failed: ${error.message}`);
+            });
+        return summary;
+    }
+
+    private async withPoolRollupOverlay(summary: ShareAccountingSummary): Promise<ShareAccountingSummary> {
+        if (process.env.API_ONLY === 'true') {
+            return summary;
+        }
+
+        const [currentRoundRow] = await this.acceptedShareRepository.query(`
+                WITH latest_found_block AS (
+                    SELECT COALESCE(MAX("height"), 0) AS "height"
+                    FROM "blocks_entity"
+                ),
+                filtered_rows AS (
+                    SELECT "accepted_share_block_10m".*
+                    FROM "accepted_share_block_10m", latest_found_block
+                    WHERE "blockHeight" > latest_found_block."height"
+                ),
+                best_share AS (
+                    SELECT
+                        "bestSubmissionDifficulty",
+                        "bucket"
+                    FROM filtered_rows
+                    ORDER BY "bestSubmissionDifficulty" DESC, "bucket" DESC
+                    LIMIT 1
+                )
+                SELECT
+                    COALESCE(SUM("acceptedCount"), 0)::int AS "currentRoundAcceptedShares",
+                    COALESCE(SUM("shares"), 0)::float AS "workSinceLastBlock",
+                    COALESCE(MAX("networkDifficulty"), 0)::float AS "currentRoundNetworkDifficulty",
+                    COALESCE((SELECT "bestSubmissionDifficulty" FROM best_share), 0)::float AS "bestSubmissionDifficulty",
+                    (SELECT "bucket" FROM best_share) AS "bestSubmissionDifficultyAt"
+                FROM filtered_rows
+        `);
+        const currentRoundNetworkDifficulty = this.toNumber(currentRoundRow?.currentRoundNetworkDifficulty);
+        const workSinceLastBlock = this.toNumber(currentRoundRow?.workSinceLastBlock);
+
+        return {
+            ...summary,
+            bestSubmissionDifficulty: this.toNumber(currentRoundRow?.bestSubmissionDifficulty),
+            bestSubmissionDifficultyAt: currentRoundRow?.bestSubmissionDifficultyAt == null
+                ? null
+                : new Date(currentRoundRow.bestSubmissionDifficultyAt).toISOString(),
+            workSinceLastBlock,
+            currentRoundAcceptedShares: this.toNumber(currentRoundRow?.currentRoundAcceptedShares),
+            currentRoundNetworkDifficulty,
+            networkDifficultyPercent: currentRoundNetworkDifficulty > 0
+                ? this.roundPercent((workSinceLastBlock / currentRoundNetworkDifficulty) * 100)
+                : 0,
+        };
+    }
+
+    public emptySummary(): ShareAccountingSummary {
+        return {
+            totalAcceptedShares: 0,
+            totalCreditedDifficulty: 0,
+            acceptedSharesLast10Minutes: 0,
+            creditedDifficultyLast10Minutes: 0,
+            acceptedSharesLastHour: 0,
+            creditedDifficultyLastHour: 0,
+            acceptedSharesLastDay: 0,
+            creditedDifficultyLastDay: 0,
+            hashRateLast10Minutes: 0,
+            hashRateLastHour: 0,
+            bestSubmissionDifficulty: 0,
+            bestSubmissionDifficultyAt: null,
+            workSinceLastBlock: 0,
+            currentRoundAcceptedShares: 0,
+            currentRoundNetworkDifficulty: 0,
+            networkDifficultyPercent: 0,
+            blockCandidateCount: 0,
+            latestShareAt: null,
+            protocolBreakdown: [],
+        };
+    }
+
+    public async getAddressSummary(address: string): Promise<ShareAccountingSummary> {
+        return this.getSummary({ address });
+    }
+
+    public async getWorkerGroupSummary(address: string, clientName: string): Promise<ShareAccountingSummary> {
+        return this.getSummary({ address, clientName });
+    }
+
+    public async getSessionSummary(clientId: string): Promise<ShareAccountingSummary> {
+        return this.getSummary({ clientId });
+    }
+
+    public async getSessionSummaries(clientIds: string[]): Promise<Map<string, SessionShareSummary>> {
+        const uniqueClientIds = [...new Set(clientIds.filter(clientId => clientId != null))];
+        const summaries = new Map<string, SessionShareSummary>();
+        if (uniqueClientIds.length === 0 || process.env.API_ONLY === 'true') {
+            return summaries;
+        }
+
+        const rows = await this.acceptedShareRepository.query(`
+            WITH clock AS MATERIALIZED (
+                SELECT
+                    time_bucket(INTERVAL '10 minutes', NOW()) AS "currentBucket"
+            ),
+            latest_bucket AS MATERIALIZED (
+                SELECT "bucket"
+                FROM "accepted_share_10m", clock
+                WHERE "bucket" < clock."currentBucket"
+                ORDER BY "bucket" DESC
+                LIMIT 1
+            ),
+            bounds AS MATERIALIZED (
+                SELECT
+                    "currentBucket",
+                    COALESCE(
+                        (SELECT "bucket" FROM latest_bucket),
+                        "currentBucket" - INTERVAL '10 minutes'
+                    ) AS "latestCompletedBucket"
+                FROM clock
+            ),
+            filtered_rows AS (
+                SELECT "accepted_share_10m".*, bounds."latestCompletedBucket"
+                FROM "accepted_share_10m", bounds
+                WHERE "clientId" = ANY($1::uuid[])
+            )
+            SELECT
+                "clientId",
+                MAX("bucket") AS "latestShareAt",
+                COALESCE((SUM("shares") FILTER (WHERE "bucket" = "latestCompletedBucket") * ${HASHES_PER_DIFFICULTY}) / ${ROLLUP_BUCKET_SECONDS}, 0)::float AS "hashRateLast10Minutes"
+            FROM filtered_rows
+            GROUP BY "clientId"
+        `, [uniqueClientIds]);
+
+        rows.forEach(row => {
+            summaries.set(row.clientId, {
+                clientId: row.clientId,
+                latestShareAt: row.latestShareAt == null
+                    ? null
+                    : new Date(row.latestShareAt).toISOString(),
+                hashRateLast10Minutes: this.toNumber(row.hashRateLast10Minutes),
+                bestSubmissionDifficulty: 0,
+            });
+        });
+
+        return summaries;
+    }
+
+    private async getSummary(filter: AccountingFilter): Promise<ShareAccountingSummary> {
+        const cacheKey = this.getSummaryCacheKey(filter);
+        const cached = this.summaryCache.get(cacheKey);
+        const now = Date.now();
+
+        if (cached != null && cached.expiresAt > now) {
+            return cached.value;
+        }
+
+        const value = this.loadCachedSummary(filter, cacheKey).catch(error => {
+            this.summaryCache.delete(cacheKey);
+            throw error;
+        });
+
+        if (this.summaryCacheMs > 0) {
+            this.summaryCache.set(cacheKey, {
+                expiresAt: now + this.summaryCacheMs,
+                value,
+            });
+            this.trimSummaryCache();
+        }
+
+        return value;
+    }
+
+    private async loadCachedSummary(filter: AccountingFilter, cacheKey: string): Promise<ShareAccountingSummary> {
+        const redisCacheKey = `accounting:summary:${cacheKey}`;
+        const cached = await this.redisMessagingService
+            ?.getJsonCache<ShareAccountingSummary>(redisCacheKey)
+            .catch(error => {
+                console.error(`Share accounting summary cache read failed: ${error.message}`);
+                return null;
+            });
+        if (cached != null) {
+            return cached;
+        }
+
+        const summary = await this.loadSummary(filter);
+
+        await this.redisMessagingService
+            ?.setJsonCache(redisCacheKey, summary, this.redisSummaryCacheMs)
+            .catch(error => {
+                console.error(`Share accounting summary cache write failed: ${error.message}`);
+            });
+
+        return summary;
+    }
+
+    private async loadSummary(filter: AccountingFilter): Promise<ShareAccountingSummary> {
+        const { whereSql, params } = this.buildWhereClause(filter);
+        const [summary] = await this.acceptedShareRepository.query(`
+            WITH clock AS MATERIALIZED (
+                SELECT
+                    time_bucket(INTERVAL '10 minutes', NOW()) AS "currentBucket"
+            ),
+            latest_bucket AS MATERIALIZED (
+                SELECT "bucket"
+                FROM "accepted_share_10m", clock
+                WHERE "bucket" < clock."currentBucket"
+                ORDER BY "bucket" DESC
+                LIMIT 1
+            ),
+            bounds AS MATERIALIZED (
+                SELECT
+                    "currentBucket",
+                    COALESCE(
+                        (SELECT "bucket" FROM latest_bucket),
+                        "currentBucket" - INTERVAL '10 minutes'
+                    ) AS "latestCompletedBucket"
+                FROM clock
+            ),
+            filtered_rows AS (
+                SELECT "accepted_share_10m".*, bounds."currentBucket", bounds."latestCompletedBucket"
+                FROM "accepted_share_10m", bounds
+                ${whereSql.length > 0
+                    ? `${whereSql} AND "accepted_share_10m"."bucket" <= bounds."latestCompletedBucket"`
+                    : `WHERE "accepted_share_10m"."bucket" <= bounds."latestCompletedBucket"`}
+            )
+            SELECT
+                COALESCE(SUM("acceptedCount"), 0)::int AS "totalAcceptedShares",
+                COALESCE(SUM("shares"), 0)::float AS "totalCreditedDifficulty",
+                COALESCE(SUM("acceptedCount") FILTER (WHERE "bucket" = "latestCompletedBucket"), 0)::int AS "acceptedSharesLast10Minutes",
+                COALESCE(SUM("shares") FILTER (WHERE "bucket" = "latestCompletedBucket"), 0)::float AS "creditedDifficultyLast10Minutes",
+                COALESCE(SUM("acceptedCount") FILTER (WHERE "bucket" > "latestCompletedBucket" - INTERVAL '1 hour' AND "bucket" <= "latestCompletedBucket"), 0)::int AS "acceptedSharesLastHour",
+                COALESCE(SUM("shares") FILTER (WHERE "bucket" > "latestCompletedBucket" - INTERVAL '1 hour' AND "bucket" <= "latestCompletedBucket"), 0)::float AS "creditedDifficultyLastHour",
+                COALESCE(SUM("acceptedCount") FILTER (WHERE "bucket" > "latestCompletedBucket" - INTERVAL '1 day' AND "bucket" <= "latestCompletedBucket"), 0)::int AS "acceptedSharesLastDay",
+                COALESCE(SUM("shares") FILTER (WHERE "bucket" > "latestCompletedBucket" - INTERVAL '1 day' AND "bucket" <= "latestCompletedBucket"), 0)::float AS "creditedDifficultyLastDay",
+                COALESCE((SUM("shares") FILTER (WHERE "bucket" = "latestCompletedBucket") * ${HASHES_PER_DIFFICULTY}) / ${ROLLUP_BUCKET_SECONDS}, 0)::float AS "hashRateLast10Minutes",
+                COALESCE((SUM("shares") FILTER (WHERE "bucket" > "latestCompletedBucket" - INTERVAL '1 hour' AND "bucket" <= "latestCompletedBucket") * ${HASHES_PER_DIFFICULTY}) / 3600, 0)::float AS "hashRateLastHour",
+                MAX("bucket") AS "latestShareAt"
+            FROM filtered_rows
+        `, params);
+
+        return {
+            totalAcceptedShares: this.toNumber(summary?.totalAcceptedShares),
+            totalCreditedDifficulty: this.toNumber(summary?.totalCreditedDifficulty),
+            acceptedSharesLast10Minutes: this.toNumber(summary?.acceptedSharesLast10Minutes),
+            creditedDifficultyLast10Minutes: this.toNumber(summary?.creditedDifficultyLast10Minutes),
+            acceptedSharesLastHour: this.toNumber(summary?.acceptedSharesLastHour),
+            creditedDifficultyLastHour: this.toNumber(summary?.creditedDifficultyLastHour),
+            acceptedSharesLastDay: this.toNumber(summary?.acceptedSharesLastDay),
+            creditedDifficultyLastDay: this.toNumber(summary?.creditedDifficultyLastDay),
+            hashRateLast10Minutes: this.toNumber(summary?.hashRateLast10Minutes),
+            hashRateLastHour: this.toNumber(summary?.hashRateLastHour),
+            bestSubmissionDifficulty: 0,
+            bestSubmissionDifficultyAt: null,
+            workSinceLastBlock: 0,
+            currentRoundAcceptedShares: 0,
+            currentRoundNetworkDifficulty: 0,
+            networkDifficultyPercent: 0,
+            blockCandidateCount: 0,
+            latestShareAt: summary?.latestShareAt == null
+                ? null
+                : new Date(summary.latestShareAt).toISOString(),
+            protocolBreakdown: [],
+        };
+    }
+
+    private scheduleFlush(): void {
+        if (this.flushTimer != null || this.activeFlush != null) {
+            return;
+        }
+
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.startFlush();
+        }, this.flushIntervalMs);
+        this.flushTimer.unref?.();
+    }
+
+    private startFlush(): void {
+        if (this.activeFlush != null) {
+            return;
+        }
+
+        if (this.flushTimer != null) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+
+        const batch = this.pendingShares.splice(0, this.batchSize);
+        if (batch.length === 0) {
+            return;
+        }
+
+        this.activeFlush = this.flushBatch(batch).finally(() => {
+            this.activeFlush = null;
+
+            if (this.pendingShares.length >= this.batchSize) {
+                this.startFlush();
+                return;
+            }
+
+            if (this.pendingShares.length > 0) {
+                this.scheduleFlush();
+            }
+        });
+    }
+
+    private async flushBatch(batch: PendingShare[]): Promise<void> {
+        try {
+            await this.acceptedShareRepository.insert(batch.map(item => item.entity));
+            batch.forEach(item => item.resolve(item.entity));
+        } catch (error) {
+            batch.forEach(item => item.reject(error));
+        }
+    }
+
+    private startShareRollupTimer(): void {
+        if (!this.shareRollupEnabled || process.env.MASTER !== 'true') {
+            return;
+        }
+
+        this.rollupTimer = setInterval(() => {
+            if (this.activeRollup != null) {
+                return;
+            }
+
+            this.activeRollup = this.processPendingShareRollupBatch()
+                .then(result => {
+                    if (result.processed) {
+                        console.log(`Share rollup batch ${result.batchId} finalized: indexes ${result.startShareIndex}-${result.endShareIndex}, shares ${result.acceptedShareCount}, difficulty ${result.creditedDifficulty}`);
+                    }
+                })
+                .catch(error => {
+                    console.error(`Share rollup batch failed: ${error.message}`);
+                })
+                .finally(() => {
+                    this.activeRollup = null;
+                });
+        }, this.shareRollupIntervalMs);
+        this.rollupTimer.unref?.();
+    }
+
+    private buildWhereClause(filter: AccountingFilter): { whereSql: string; params: string[] } {
+        const where: string[] = [];
+        const params: string[] = [];
+
+        if (filter.address != null) {
+            params.push(filter.address);
+            where.push(`"address" = $${params.length}`);
+        }
+        if (filter.clientName != null) {
+            params.push(filter.clientName);
+            where.push(`"clientName" = $${params.length}`);
+        }
+        if (filter.clientId != null) {
+            params.push(filter.clientId);
+            where.push(`"clientId" = $${params.length}`);
+        }
+
+        return {
+            whereSql: where.length > 0 ? `WHERE ${where.join(' AND ')}` : '',
+            params,
+        };
+    }
+
+    private toNumber(value: unknown): number {
+        const parsed = Number(value ?? 0);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+
+    private roundPercent(value: number): number {
+        return Math.round(value * 1_000_000) / 1_000_000;
+    }
+
+    private getSummaryCacheKey(filter: AccountingFilter): string {
+        return JSON.stringify({
+            address: filter.address ?? null,
+            clientName: filter.clientName ?? null,
+            clientId: filter.clientId ?? null,
+        });
+    }
+
+    private trimSummaryCache(): void {
+        while (this.summaryCache.size > this.summaryCacheMax) {
+            const firstKey = this.summaryCache.keys().next().value;
+            if (firstKey == null) {
+                return;
+            }
+            this.summaryCache.delete(firstKey);
+        }
+    }
+
+    private readPositiveInt(name: string, defaultValue: number): number {
+        const value = Number(process.env[name]);
+        return Number.isInteger(value) && value > 0 ? value : defaultValue;
+    }
+
+    private readNonNegativeInt(name: string, defaultValue: number): number {
+        const value = Number(process.env[name]);
+        return Number.isInteger(value) && value >= 0 ? value : defaultValue;
+    }
+
+    private readBoolean(name: string, defaultValue: boolean): boolean {
+        const value = process.env[name]?.toLowerCase();
+        if (value == null || value.length === 0) {
+            return defaultValue;
+        }
+        return value === 'true' || value === '1' || value === 'yes';
+    }
+}
+
+interface PendingShare {
+    entity: AcceptedShareEntity;
+    resolve: (entity: AcceptedShareEntity) => void;
+    reject: (error: unknown) => void;
+}
+
+interface SummaryCacheEntry {
+    expiresAt: number;
+    value: Promise<ShareAccountingSummary>;
+}

src/app.controller.ts

@@ -8,15 +8,17 @@ import { AddressSettingsService } from './ORM/address-settings/address-settings.
 import { BlocksService } from './ORM/blocks/blocks.service';
 import { ClientStatisticsService } from './ORM/client-statistics/client-statistics.service';
 import { ClientService } from './ORM/client/client.service';
-import { HomeGraphService } from './ORM/home-graph/home-graph.service';
 import { BitcoinRpcService } from './services/bitcoin-rpc.service';
 import { UserAgentReportView } from './ORM/_views/user-agent-report/user-agent-report.view';
 import { StratumV2Service } from './services/stratum-v2.service';
+import { ShareAccountingService } from './ORM/share-accounting/share-accounting.service';
+import { RedisMessagingService } from './services/redis-messaging.service';
 
 @Controller()
 export class AppController {
 
   private uptime = new Date();
+  private siteInfoRefreshPromise: Promise<SiteInfoResponse> | null = null;
 
   constructor(
     @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
@@ -24,27 +26,62 @@ export class AppController {
     private readonly clientStatisticsService: ClientStatisticsService,
     private readonly blocksService: BlocksService,
     private readonly bitcoinRpcService: BitcoinRpcService,
-    private readonly homeGraphService: HomeGraphService,
     private readonly addressSettingsService: AddressSettingsService,
     private readonly userAgentReportService: UserAgentReportService,
-    private readonly stratumV2Service: StratumV2Service
+    private readonly stratumV2Service: StratumV2Service,
+    private readonly shareAccountingService: ShareAccountingService,
+    private readonly redisMessagingService: RedisMessagingService
   ) { }
 
   @Get('info')
   public async info() {
-
-
     const CACHE_KEY = 'SITE_INFO';
-    const cachedResult = await this.cacheManager.get(CACHE_KEY);
+    const STALE_CACHE_KEY = 'SITE_INFO_STALE';
+    const cachedResult = await this.getCached(CACHE_KEY, 5 * 60 * 1000);
 
     if (cachedResult != null) {
       return cachedResult;
     }
 
+    const staleResult = await this.getCached<SiteInfoResponse>(STALE_CACHE_KEY, 60 * 60 * 1000);
+    if (staleResult != null) {
+      void this.refreshSiteInfo(staleResult);
+      return staleResult;
+    }
 
-    const blockData = await this.blocksService.getFoundBlocks();
+    return await this.refreshSiteInfo(null);
-    const highScores = await this.addressSettingsService.getHighScores();
+
-    const poolAuthority = await this.stratumV2Service.getPoolAuthorityPublicKey();
+  }
+
+  private async refreshSiteInfo(staleInfo: SiteInfoResponse | null): Promise<SiteInfoResponse> {
+    if (this.siteInfoRefreshPromise != null) {
+      return this.siteInfoRefreshPromise;
+    }
+
+    this.siteInfoRefreshPromise = this.loadSiteInfo(staleInfo)
+      .finally(() => {
+        this.siteInfoRefreshPromise = null;
+      });
+
+    return this.siteInfoRefreshPromise;
+  }
+
+  private async loadSiteInfo(staleInfo: SiteInfoResponse | null): Promise<SiteInfoResponse> {
+    const CACHE_KEY = 'SITE_INFO';
+    const STALE_CACHE_KEY = 'SITE_INFO_STALE';
+    const withInfoTimeout = async <T>(label: string, promise: Promise<T>, fallback: T): Promise<T> => {
+      return await this.withTimeout(label, promise, fallback);
+    };
+
+    const [blockData, highScores, poolAuthority, userAgentReport] = await Promise.all([
+      withInfoTimeout('found blocks', this.blocksService.getFoundBlocks(), staleInfo?.blockData ?? []),
+      withInfoTimeout('high scores', this.addressSettingsService.getHighScores(), staleInfo?.highScores ?? []),
+      withInfoTimeout('SV2 authority', this.stratumV2Service.getPoolAuthorityPublicKey(), {
+        publicKey: staleInfo?.sv2?.poolAuthorityPublicKey ?? '',
+        configured: staleInfo?.sv2?.authorityKeyConfigured ?? false
+      }),
+      withInfoTimeout<UserAgentReportView[]>('user agent report', this.userAgentReportService.getReport(), staleInfo?.userAgents ?? []),
+    ]);
 
     const other: {
       count: number,
@@ -55,7 +92,7 @@ export class AppController {
       bestDifficulty: 0,
       totalHashRate: 0
     };
-    const userAgents: UserAgentReportView[] = (await this.userAgentReportService.getReport()).reduce((pre, cur, idx, arr) => {
+    const userAgents: UserAgentReportView[] = userAgentReport.reduce((pre, cur, idx, arr) => {
       // If less than 10Th/s and less than 100 devices, add to 'other'
       if (parseInt(cur.totalHashRate) < 10000000000000 && parseInt(cur.count) < 200) {
         other.totalHashRate += parseFloat(cur.totalHashRate);
@@ -69,9 +106,11 @@ export class AppController {
       return pre;
     }, []);
 
+    if (other.count > 0) {
       userAgents.push({ userAgent: 'Other', count: other.count.toString(), bestDifficulty: other.bestDifficulty, totalHashRate: other.totalHashRate.toString() })
+    }
 
-    const data = {
+    const data: SiteInfoResponse = {
       blockData,
       userAgents,
       highScores,
@@ -82,18 +121,35 @@ export class AppController {
       uptime: this.uptime
     };
 
-    //5 min
+    // Cache a complete response even when one slow component falls back to stale data.
-    await this.cacheManager.set(CACHE_KEY, data, 5 * 60 * 1000);
+    // A short retry loop here causes repeated DB work because timed-out TypeORM queries are not cancelled.
+    await this.setCached(CACHE_KEY, data, 5 * 60 * 1000);
+    await this.setCached(STALE_CACHE_KEY, data, 60 * 60 * 1000);
 
     return data;
+  }
 
+  @Get('info/accounting')
+  public async infoAccounting() {
+    const CACHE_KEY = 'SITE_ACCOUNTING';
+    const cachedResult = await this.getCached(CACHE_KEY, 15 * 1000);
+
+    if (cachedResult != null) {
+      return cachedResult;
+    }
+
+    const data = await this.shareAccountingService.getPoolSummary();
+
+    //15 sec
+    await this.setCached(CACHE_KEY, data, 15 * 1000);
+
+    return data;
   }
 
   @Get('pool')
   public async pool() {
-
     const CACHE_KEY = 'POOL_INFO';
-    const cachedResult = await this.cacheManager.get(CACHE_KEY);
+    const cachedResult = await this.getCached(CACHE_KEY, 15 * 1000);
 
     if (cachedResult != null) {
       return cachedResult;
@@ -114,36 +170,111 @@ export class AppController {
       fee: 0
     }
 
-    //5 min
+    // Keep online miner counts responsive after reconnect cleanup.
-    await this.cacheManager.set(CACHE_KEY, data, 5 * 60 * 1000);
+    await this.setCached(CACHE_KEY, data, 15 * 1000);
 
     return data;
   }
 
   @Get('network')
   public async network() {
-    return this.bitcoinRpcService.miningInfo;
+    return this.bitcoinRpcService.miningInfo ?? {};
   }
 
   @Get('info/chart')
   public async infoChart() {
-
-
     const CACHE_KEY = 'SITE_HASHRATE_GRAPH';
-    const cachedResult = await this.cacheManager.get(CACHE_KEY);
+    const cachedResult = await this.getCached(CACHE_KEY, 10 * 60 * 1000);
 
     if (cachedResult != null) {
       return cachedResult;
     }
 
-    const chartData = await this.homeGraphService.getChartDataForSite();
+    const chartData = await this.clientStatisticsService.getChartDataForSite();
 
     //10 min
-    await this.cacheManager.set(CACHE_KEY, chartData, 10 * 60 * 1000);
+    await this.setCached(CACHE_KEY, chartData, 10 * 60 * 1000);
 
     return chartData;
 
 
   }
 
+  private async getCached<T>(key: string, localTtlMs: number): Promise<T | null> {
+    const local = await this.cacheManager.get<T>(key);
+    if (local != null) {
+      return local;
+    }
+
+    const shared = await this.withSecondaryCacheTimeout(
+      this.redisMessagingService.getJsonCache<T>(`api:${key}`).catch(error => {
+        console.error(`Shared API cache read failed for ${key}: ${error.message}`);
+        return null;
+      }),
+      100
+    );
+    if (shared != null) {
+      await this.cacheManager.set(key, shared, localTtlMs);
+      return shared;
+    }
+
+    return null;
+  }
+
+  private async setCached(key: string, value: unknown, ttlMs: number): Promise<void> {
+    await this.cacheManager.set(key, value, ttlMs);
+    void this.redisMessagingService.setJsonCache(`api:${key}`, value, ttlMs).catch(error => {
+      console.error(`Shared API cache write failed for ${key}: ${error.message}`);
+    });
+  }
+
+  private async withTimeout<T>(
+    label: string,
+    promise: Promise<T>,
+    fallback: T,
+    onTimeout: () => void = () => undefined,
+    timeoutMs = 1500
+  ): Promise<T> {
+    let timeout: NodeJS.Timeout;
+    const timeoutPromise = new Promise<T>(resolve => {
+      timeout = setTimeout(() => {
+        onTimeout();
+        console.error(`/api/info ${label} timed out after ${timeoutMs}ms`);
+        resolve(fallback);
+      }, timeoutMs);
+      timeout.unref?.();
+    });
+
+    try {
+      return await Promise.race([promise, timeoutPromise]);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private async withSecondaryCacheTimeout<T>(promise: Promise<T | null>, timeoutMs: number): Promise<T | null> {
+    let timeout: NodeJS.Timeout;
+    const timeoutPromise = new Promise<null>(resolve => {
+      timeout = setTimeout(() => resolve(null), timeoutMs);
+      timeout.unref?.();
+    });
+
+    try {
+      return await Promise.race([promise, timeoutPromise]);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+}
+
+interface SiteInfoResponse {
+  blockData: unknown[];
+  userAgents: UserAgentReportView[];
+  highScores: unknown[];
+  sv2: {
+    poolAuthorityPublicKey: string;
+    authorityKeyConfigured: boolean;
+  };
+  uptime: Date;
 }

src/app.module.ts

@@ -9,33 +9,33 @@ import { AppController } from './app.controller';
 import { AddressController } from './controllers/address/address.controller';
 import { ClientController } from './controllers/client/client.controller';
 import { BitcoinAddressValidator } from './models/validators/bitcoin-address.validator';
-import { UniqueNonceIndex } from './ORM/_migrations/UniqueNonceIndex';
 import { UserAgentReportModule } from './ORM/_views/user-agent-report/user-agent-report.module';
-import { UserAgentReportView } from './ORM/_views/user-agent-report/user-agent-report.view';
-import { AddressSettingsEntity } from './ORM/address-settings/address-settings.entity';
 import { AddressSettingsModule } from './ORM/address-settings/address-settings.module';
-import { BlocksEntity } from './ORM/blocks/blocks.entity';
 import { BlocksModule } from './ORM/blocks/blocks.module';
-import { ClientStatisticsEntity } from './ORM/client-statistics/client-statistics.entity';
 import { ClientStatisticsModule } from './ORM/client-statistics/client-statistics.module';
-import { ClientEntity } from './ORM/client/client.entity';
 import { ClientModule } from './ORM/client/client.module';
-import { HomeGraphEntity } from './ORM/home-graph/home-graph.entity';
+import { PayoutSnapshotModule } from './ORM/payout-snapshot/payout-snapshot.module';
-import { HomeGraphModule } from './ORM/home-graph/home-graph.module';
-import { RpcBlockEntity } from './ORM/rpc-block/rpc-block.entity';
 import { RpcBlocksModule } from './ORM/rpc-block/rpc-block.module';
-import { TelegramSubscriptionsEntity } from './ORM/telegram-subscriptions/telegram-subscriptions.entity';
+import { ShareAccountingModule } from './ORM/share-accounting/share-accounting.module';
 import { TelegramSubscriptionsModule } from './ORM/telegram-subscriptions/telegram-subscriptions.module';
+import { createDatabaseOptions } from './database.config';
 import { AppService } from './services/app.service';
 import { BitcoinRpcService } from './services/bitcoin-rpc.service';
 import { BraiinsService } from './services/braiins.service';
 import { BTCPayService } from './services/btc-pay.service';
 import { DiscordService } from './services/discord.service';
+import { CustomWorkService } from './services/custom-work.service';
+import { DatumService } from './services/datum.service';
 import { NotificationService } from './services/notification.service';
+import { RedisMessagingModule } from './services/redis-messaging.module';
 import { StratumV1JobsService } from './services/stratum-v1-jobs.service';
 import { StratumV1Service } from './services/stratum-v1.service';
+import { Sv2JobDeclarationRegistryService } from './services/sv2-job-declaration-registry.service';
+import { Sv2JobDeclarationService } from './services/sv2-job-declaration.service';
+import { Sv2TemplateDistributionService } from './services/sv2-template-distribution.service';
 import { StratumV2Service } from './services/stratum-v2.service';
 import { TelegramService } from './services/telegram.service';
+import { TemplateProviderService } from './services/template-provider.service';
 
 
 const ORMModules = [
@@ -45,8 +45,9 @@ const ORMModules = [
     TelegramSubscriptionsModule,
     BlocksModule,
     RpcBlocksModule,
-    HomeGraphModule,
+    UserAgentReportModule,
-    UserAgentReportModule
+    ShareAccountingModule,
+    PayoutSnapshotModule
 ]
 
 @Module({
@@ -54,30 +55,16 @@ const ORMModules = [
         ConfigModule.forRoot(),
         TypeOrmModule.forRootAsync({
             useFactory: (configService: ConfigService) => {
-                return {
+                return createDatabaseOptions({
-                    type: 'postgres',
+                    ...process.env,
-                    host: configService.get('DB_HOST'),
+                    DB_HOST: configService.get('DB_HOST'),
-                    port: parseInt(configService.get('DB_PORT')),
+                    DB_PORT: configService.get('DB_PORT'),
-                    username: configService.get('DB_USERNAME'),
+                    DB_USERNAME: configService.get('DB_USERNAME'),
-                    password: configService.get('DB_PASSWORD'),
+                    DB_PASSWORD: configService.get('DB_PASSWORD'),
-                    database: configService.get('DB_DATABASE'),
+                    DB_DATABASE: configService.get('DB_DATABASE'),
-                    entities: [
+                    DB_LOGGING: configService.get('DB_LOGGING'),
-                        ClientEntity,
+                    DB_POOL_SIZE: configService.get('DB_POOL_SIZE'),
-                        AddressSettingsEntity,
+                });
-                        BlocksEntity,
-                        ClientStatisticsEntity,
-                        RpcBlockEntity,
-                        TelegramSubscriptionsEntity,
-                        HomeGraphEntity,
-                        UserAgentReportView
-                    ],
-                    synchronize: configService.get('PRODUCTION') != 'true',
-                    logging: false,
-                    poolSize: 10,
-                    migrations: [
-                        UniqueNonceIndex
-                    ]
-                }
             },
             imports: [ConfigModule],
             inject: [ConfigService]
@@ -85,6 +72,7 @@ const ORMModules = [
         CacheModule.register(),
         ScheduleModule.forRoot(),
         HttpModule,
+        RedisMessagingModule,
         ...ORMModules
     ],
     controllers: [
@@ -102,6 +90,12 @@ const ORMModules = [
         BitcoinAddressValidator,
         StratumV1JobsService,
         StratumV2Service,
+        TemplateProviderService,
+        Sv2JobDeclarationRegistryService,
+        Sv2JobDeclarationService,
+        Sv2TemplateDistributionService,
+        CustomWorkService,
+        DatumService,
         BTCPayService,
         BraiinsService
     ],

src/controllers/client/client.controller.spec.ts

@@ -1,37 +1,103 @@
 import { Test, TestingModule } from '@nestjs/testing';
-import { TypeOrmModule } from '@nestjs/typeorm';
 
-import { AddressSettingsModule } from '../../ORM/address-settings/address-settings.module';
+import { AddressSettingsService } from '../../ORM/address-settings/address-settings.service';
-import { ClientStatisticsModule } from '../../ORM/client-statistics/client-statistics.module';
+import { ClientStatisticsService } from '../../ORM/client-statistics/client-statistics.service';
-import { ClientModule } from '../../ORM/client/client.module';
+import { ClientService } from '../../ORM/client/client.service';
+import { ShareAccountingService } from '../../ORM/share-accounting/share-accounting.service';
+import { RedisMessagingService } from '../../services/redis-messaging.service';
 import { ClientController } from './client.controller';
 
 describe('ClientController', () => {
   let controller: ClientController;
+  let addressSettingsService: { getSettings: jest.Mock };
+  let shareAccountingService: {
+    getAddressSummary: jest.Mock;
+    getWorkerGroupSummary: jest.Mock;
+    getSessionSummary: jest.Mock;
+    getSessionSummaries: jest.Mock;
+  };
+  let redisMessagingService: { getClientPresenceByAddress: jest.Mock };
 
     beforeEach(async () => {
         const module: TestingModule = await Test.createTestingModule({
-      imports: [
-        TypeOrmModule.forRoot({
-          type: 'better-sqlite3',
-          database: ':memory:',
-          synchronize: true,
-          autoLoadEntities: true,
-          cache: true,
-          logging: false
-        }),
-        AddressSettingsModule,
-        ClientModule,
-        ClientStatisticsModule
-      ],
             controllers: [ClientController],
+            providers: [
+                {
+                    provide: ClientService,
+                    useValue: {
+                        getByAddress: jest.fn(),
+                        getByName: jest.fn(),
+                        getBySessionId: jest.fn(),
+                    },
+                },
+                {
+                    provide: ClientStatisticsService,
+                    useValue: {
+                        getChartDataForAddress: jest.fn(),
+                        getChartDataForGroup: jest.fn(),
+                        getChartDataForSession: jest.fn(),
+                    },
+                },
+                {
+                    provide: AddressSettingsService,
+                    useValue: {
+                        getSettings: jest.fn(),
+                    },
+                },
+                {
+                    provide: ShareAccountingService,
+                    useValue: {
+                        getAddressSummary: jest.fn(),
+                        getWorkerGroupSummary: jest.fn(),
+                        getSessionSummary: jest.fn(),
+                        getSessionSummaries: jest.fn().mockResolvedValue(new Map()),
+                    },
+                },
+                {
+                    provide: RedisMessagingService,
+                    useValue: {
+                        getClientPresenceByAddress: jest.fn().mockResolvedValue([]),
+                    },
+                },
+            ],
 
         }).compile();
 
     controller = module.get<ClientController>(ClientController);
+    addressSettingsService = module.get(AddressSettingsService);
+    shareAccountingService = module.get(ShareAccountingService);
+    redisMessagingService = module.get(RedisMessagingService);
   });
 
   it('should be defined', () => {
     expect(controller).toBeDefined();
   });
+
+  it('should expose the existing address best difficulty in accounting when rollup best is empty', async () => {
+    redisMessagingService.getClientPresenceByAddress.mockResolvedValue([
+      {
+        clientId: '92f5302f-5e32-487e-af67-f56fd78b13c7',
+        sessionId: 'abcd1234',
+        clientName: 'worker',
+        bestDifficulty: 64,
+        hashRate: 1024,
+        startTime: '2026-06-08T12:00:00.000Z',
+        lastSeen: '2026-06-08T12:10:00.000Z',
+      },
+    ]);
+    addressSettingsService.getSettings.mockResolvedValue({ bestDifficulty: 4096 });
+    shareAccountingService.getSessionSummaries.mockResolvedValue(new Map());
+    shareAccountingService.getAddressSummary.mockResolvedValue({
+      totalAcceptedShares: 10,
+      totalCreditedDifficulty: 100,
+      bestSubmissionDifficulty: 0,
+    });
+
+    await expect(controller.getClientInfo('bc1qtest')).resolves.toEqual(expect.objectContaining({
+      bestDifficulty: 4096,
+      accounting: expect.objectContaining({
+        bestSubmissionDifficulty: 4096,
+      }),
+    }));
+  });
 });

src/controllers/client/client.controller.ts

@@ -3,6 +3,8 @@ import { Controller, Get, NotFoundException, Param } from '@nestjs/common';
 import { AddressSettingsService } from '../../ORM/address-settings/address-settings.service';
 import { ClientStatisticsService } from '../../ORM/client-statistics/client-statistics.service';
 import { ClientService } from '../../ORM/client/client.service';
+import { ShareAccountingService } from '../../ORM/share-accounting/share-accounting.service';
+import { RedisMessagingService } from '../../services/redis-messaging.service';
 
 
 @Controller('client')
@@ -11,45 +13,63 @@ export class ClientController {
     constructor(
         private readonly clientService: ClientService,
         private readonly clientStatisticsService: ClientStatisticsService,
-        private readonly addressSettingsService: AddressSettingsService
+        private readonly addressSettingsService: AddressSettingsService,
+        private readonly shareAccountingService: ShareAccountingService,
+        private readonly redisMessagingService: RedisMessagingService
     ) { }
 
 
     @Get(':address')
     async getClientInfo(@Param('address') address: string) {
+        const workers = await this.redisMessagingService.getClientPresenceByAddress(address);
+        const sessionSummaries = await this.shareAccountingService.getSessionSummaries(workers.map(worker => worker.clientId));
 
-        const workers = await this.clientService.getByAddress(address);
+        const addressSettings = process.env.API_ONLY === 'true'
+            ? null
+            : await this.addressSettingsService.getSettings(address, false);
+        const bestDifficulty = addressSettings?.bestDifficulty ?? workers.reduce((best, worker) => {
+            return Math.max(best, Number(worker.bestDifficulty ?? 0));
+        }, 0);
+        const accounting = this.withBestSubmissionDifficulty(
+            await this.shareAccountingService.getAddressSummary(address),
+            bestDifficulty,
+        );
 
-        const addressSettings = await this.addressSettingsService.getSettings(address, false);
+        const response = {
-
+            bestDifficulty,
-        return {
-            bestDifficulty: addressSettings?.bestDifficulty,
             workersCount: workers.length,
+            accounting,
             workers: await Promise.all(
                 workers.map(async (worker) => {
+                    const sessionSummary = sessionSummaries.get(worker.clientId);
+                    const bestDifficulty = Math.max(
+                        Number(worker.bestDifficulty ?? 0),
+                        Number(sessionSummary?.bestSubmissionDifficulty ?? 0),
+                    );
                     return {
                         sessionId: worker.sessionId,
                         name: worker.clientName,
-                        bestDifficulty: parseFloat(worker.bestDifficulty as any).toFixed(2),
+                        bestDifficulty: bestDifficulty.toFixed(2),
-                        hashRate: worker.hashRate,
+                        hashRate: sessionSummary?.hashRateLast10Minutes ?? worker.hashRate,
                         startTime: worker.startTime,
-                        lastSeen: worker.updatedAt
+                        lastSeen: sessionSummary?.latestShareAt ?? worker.lastSeen
                     };
                 })
             )
         }
+        return response;
     }
 
     @Get(':address/chart')
     async getClientInfoChart(@Param('address') address: string) {
-        const chartData = await this.clientStatisticsService.getChartDataForAddress(address);
+        return await this.clientStatisticsService.getChartDataForAddress(address);
-        return chartData;
     }
 
     @Get(':address/:workerName')
     async getWorkerGroupInfo(@Param('address') address: string, @Param('workerName') workerName: string) {
-
+        const addressWorkers = await this.redisMessagingService.getClientPresenceByAddress(address);
-        const workers = await this.clientService.getByName(address, workerName);
+        const workers = addressWorkers
+            .filter(worker => worker.clientName === workerName);
 
         const bestDifficulty = workers.reduce((pre, cur, idx, arr) => {
             if (cur.bestDifficulty > pre) {
@@ -59,30 +79,69 @@ export class ClientController {
         }, 0);
 
         const chartData = await this.clientStatisticsService.getChartDataForGroup(address, workerName);
-        return {
+        const accounting = this.withBestSubmissionDifficulty(
+            await this.shareAccountingService.getWorkerGroupSummary(address, workerName),
+            bestDifficulty,
+        );
+        const response = {
 
             name: workerName,
             bestDifficulty: Math.floor(bestDifficulty),
+            accounting,
             chartData: chartData,
 
         }
+        return response;
     }
 
     @Get(':address/:workerName/:sessionId')
     async getWorkerInfo(@Param('address') address: string, @Param('workerName') workerName: string, @Param('sessionId') sessionId: string) {
-
+        const addressWorkers = await this.redisMessagingService.getClientPresenceByAddress(address);
-        const worker = await this.clientService.getBySessionId(address, workerName, sessionId);
+        const presenceWorker = addressWorkers
+            .find(worker => worker.clientName === workerName && worker.sessionId === sessionId);
+        const worker = presenceWorker == null
+            ? await this.clientService.getBySessionId(address, workerName, sessionId)
+            : {
+                id: presenceWorker.clientId,
+                sessionId: presenceWorker.sessionId,
+                clientName: presenceWorker.clientName,
+                bestDifficulty: presenceWorker.bestDifficulty,
+                startTime: presenceWorker.startTime,
+            };
         if (worker == null) {
             return new NotFoundException();
         }
         const chartData = await this.clientStatisticsService.getChartDataForSession(worker.id);
+        const accounting = this.withBestSubmissionDifficulty(
+            await this.shareAccountingService.getSessionSummary(worker.id),
+            worker.bestDifficulty,
+        );
 
-        return {
+        const response = {
             sessionId: worker.sessionId,
             name: worker.clientName,
             bestDifficulty: Math.floor(worker.bestDifficulty),
+            accounting,
             chartData: chartData,
             startTime: worker.startTime
         }
+        return response;
+    }
+
+    private withBestSubmissionDifficulty<T extends { bestSubmissionDifficulty?: number }>(
+        accounting: T,
+        fallbackBestDifficulty: unknown,
+    ): T {
+        const existing = Number(accounting?.bestSubmissionDifficulty ?? 0);
+        const fallback = Number(fallbackBestDifficulty ?? 0);
+
+        if (!Number.isFinite(fallback) || fallback <= existing) {
+            return accounting;
+        }
+
+        return {
+            ...accounting,
+            bestSubmissionDifficulty: fallback,
+        };
     }
 }

src/data-source.ts

@@ -0,0 +1,7 @@
+import 'dotenv/config';
+import 'reflect-metadata';
+import { DataSource } from 'typeorm';
+
+import { createDatabaseOptions } from './database.config';
+
+export const AppDataSource = new DataSource(createDatabaseOptions(process.env));

src/database.config.ts

@@ -0,0 +1,77 @@
+import { TypeOrmModuleOptions } from '@nestjs/typeorm';
+import { DataSourceOptions } from 'typeorm';
+
+import { InitialTimescaleSchema1780859300000 } from './ORM/_migrations/InitialTimescaleSchema1780859300000';
+import { ActiveOnlyUserAgentReport1780860200000 } from './ORM/_migrations/ActiveOnlyUserAgentReport1780860200000';
+import { TimescaleOperationalHardening1780861200000 } from './ORM/_migrations/TimescaleOperationalHardening1780861200000';
+import { AcceptedShareIndex1780862400000 } from './ORM/_migrations/AcceptedShareIndex1780862400000';
+import { AcceptedShareRollupIndexes1780865400000 } from './ORM/_migrations/AcceptedShareRollupIndexes1780865400000';
+import { PoolAccountingDashboardIndexes1780867200000 } from './ORM/_migrations/PoolAccountingDashboardIndexes1780867200000';
+import { CurrentRoundBestShareIndex1780897600000 } from './ORM/_migrations/CurrentRoundBestShareIndex1780897600000';
+import { CurrentRoundWorkRollup1780899000000 } from './ORM/_migrations/CurrentRoundWorkRollup1780899000000';
+import { ShareRollupBatches1780962600000 } from './ORM/_migrations/ShareRollupBatches1780962600000';
+import { AcceptedShareRetentionCompression1780966200000 } from './ORM/_migrations/AcceptedShareRetentionCompression1780966200000';
+import { PayoutSnapshots1780969800000 } from './ORM/_migrations/PayoutSnapshots1780969800000';
+import { AcceptedShareProtocolMetadata1781130600000 } from './ORM/_migrations/AcceptedShareProtocolMetadata1781130600000';
+import { BlocksSubmissionMetadata1781220000000 } from './ORM/_migrations/BlocksSubmissionMetadata1781220000000';
+import { UserAgentReportView } from './ORM/_views/user-agent-report/user-agent-report.view';
+import { AcceptedShareEntity } from './ORM/accepted-share/accepted-share.entity';
+import { AddressSettingsEntity } from './ORM/address-settings/address-settings.entity';
+import { BlocksEntity } from './ORM/blocks/blocks.entity';
+import { ClientEntity } from './ORM/client/client.entity';
+import { PayoutBalanceEntity } from './ORM/payout-snapshot/payout-balance.entity';
+import { PayoutHistoryEntity } from './ORM/payout-snapshot/payout-history.entity';
+import { PayoutSnapshotEntity } from './ORM/payout-snapshot/payout-snapshot.entity';
+import { PayoutSnapshotEntryEntity } from './ORM/payout-snapshot/payout-snapshot-entry.entity';
+import { RpcBlockEntity } from './ORM/rpc-block/rpc-block.entity';
+import { TelegramSubscriptionsEntity } from './ORM/telegram-subscriptions/telegram-subscriptions.entity';
+
+export const databaseEntities = [
+    ClientEntity,
+    AddressSettingsEntity,
+    BlocksEntity,
+    RpcBlockEntity,
+    TelegramSubscriptionsEntity,
+    UserAgentReportView,
+    AcceptedShareEntity,
+    PayoutBalanceEntity,
+    PayoutHistoryEntity,
+    PayoutSnapshotEntity,
+    PayoutSnapshotEntryEntity,
+];
+
+export const databaseMigrations = [
+    InitialTimescaleSchema1780859300000,
+    ActiveOnlyUserAgentReport1780860200000,
+    TimescaleOperationalHardening1780861200000,
+    AcceptedShareIndex1780862400000,
+    AcceptedShareRollupIndexes1780865400000,
+    PoolAccountingDashboardIndexes1780867200000,
+    CurrentRoundBestShareIndex1780897600000,
+    CurrentRoundWorkRollup1780899000000,
+    ShareRollupBatches1780962600000,
+    AcceptedShareRetentionCompression1780966200000,
+    PayoutSnapshots1780969800000,
+    AcceptedShareProtocolMetadata1781130600000,
+    BlocksSubmissionMetadata1781220000000,
+];
+
+export function createDatabaseOptions(env: NodeJS.ProcessEnv): TypeOrmModuleOptions & DataSourceOptions {
+    return {
+        type: 'postgres',
+        host: env.DB_HOST,
+        port: parseInt(env.DB_PORT ?? '5432', 10),
+        username: env.DB_USERNAME,
+        password: env.DB_PASSWORD,
+        database: env.DB_DATABASE,
+        entities: databaseEntities,
+        synchronize: false,
+        logging: env.DB_LOGGING === 'true',
+        poolSize: parseInt(env.DB_POOL_SIZE ?? '10', 10),
+        ssl: env.DB_SSL === 'true'
+            ? { rejectUnauthorized: env.DB_SSL_REJECT_UNAUTHORIZED !== 'false' }
+            : undefined,
+        migrations: databaseMigrations,
+        migrationsTransactionMode: 'none',
+    };
+}

src/main.ts

@@ -15,7 +15,9 @@ async function bootstrap() {
     return;
   }
 
-  const secure = process.env.API_SECURE?.toLowerCase() === 'true';
+  const apiEnabled = process.env.API_ENABLED?.toLowerCase();
+  const serveApi = apiEnabled == null ? process.env.MASTER !== 'false' : apiEnabled === 'true';
+  const secure = serveApi && process.env.API_SECURE?.toLowerCase() === 'true';
   const currentDirectory = process.cwd();
   const keyPath = path.join(currentDirectory, 'secrets', 'key.pem');
   const certPath = path.join(currentDirectory, 'secrets', 'cert.pem');
@@ -57,6 +59,12 @@ async function bootstrap() {
   // Taproot
   bitcoinjs.initEccLib(ecc);
 
+  if (!serveApi) {
+    await app.init();
+    console.log('Worker process skipping API listener');
+    return;
+  }
+
   await app.listen(process.env.API_PORT, '0.0.0.0', (err, address) => {
     if (err) {
       console.error(err);

src/models/MiningJob.spec.ts

@@ -64,6 +64,25 @@ describe('MiningJob', () => {
             .toContain(`${extraNonce1}${extraNonce2}`);
     });
 
+    it('should support exact satoshi payout outputs', () => {
+        const firstAmount = Math.floor(jobTemplate.blockData.coinbasevalue / 3);
+        const secondAmount = jobTemplate.blockData.coinbasevalue - firstAmount;
+        const exactPayoutJob = new MiningJob(
+            bitcoinjs.networks.testnet,
+            '2',
+            [
+                { address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4', amountSats: firstAmount },
+                { address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4', amountSats: secondAmount },
+            ],
+            jobTemplate
+        );
+        const coinbase = exactPayoutJob.cloneCoinbaseTransaction();
+
+        expect(coinbase.outs[0].value).toBe(firstAmount);
+        expect(coinbase.outs[1].value).toBe(secondAmount);
+        expect(coinbase.outs[2].value).toBe(0);
+    });
+
     it('should update block nonce, timestamp, version mask, and coinbase script', () => {
         const extraNonce1 = '57a6f098';
         const extraNonce2 = 'c708000000000000';

src/models/MiningJob.ts

@@ -2,14 +2,16 @@ import { AddressType, getAddressInfo } from 'bitcoin-address-validation';
 import * as bitcoinjs from 'bitcoinjs-lib';
 
 import { IJobTemplate } from '../services/stratum-v1-jobs.service';
+import { hash256 } from '../utils/hash.utils';
 import { eResponseMethod } from './enums/eResponseMethod';
 import { IMiningNotify } from './stratum-messages/IMiningNotify';
 import { TOTAL_EXTRANONCE_SIZE_BYTES } from './stratum.constants';
 
 
-interface AddressObject {
+export interface AddressObject {
     address: string;
-    percent: number;
+    percent?: number;
+    amountSats?: number;
 }
 export class MiningJob {
 
@@ -96,7 +98,7 @@ export class MiningJob {
             Buffer.from(`${extraNonce}${extraNonce2}`, 'hex'),
             this.coinbasePart2Buffer,
         ]);
-        const coinbaseHash = bitcoinjs.crypto.hash256(coinbaseBuffer);
+        const coinbaseHash = hash256(coinbaseBuffer);
         const merkleRoot = this.calculateMerkleRootHash(coinbaseHash, this.merkleBranchBuffers);
 
         let version = jobTemplate.block.version;
@@ -154,7 +156,7 @@ export class MiningJob {
 
         for (let i = 0; i < merkleBranches.length; i++) {
             bothMerkles.set(merkleBranches[i], 32);
-            newRoot = bitcoinjs.crypto.hash256(bothMerkles);
+            newRoot = hash256(bothMerkles);
             bothMerkles.set(newRoot);
         }
 
@@ -176,7 +178,9 @@ export class MiningJob {
         let rewardBalance = reward;
 
         addresses.forEach(recipientAddress => {
-            const amount = Math.floor((recipientAddress.percent / 100) * reward);
+            const amount = recipientAddress.amountSats == null
+                ? Math.floor(((recipientAddress.percent ?? 0) / 100) * reward)
+                : recipientAddress.amountSats;
             rewardBalance -= amount;
             coinbaseTransaction.addOutput(this.getPaymentScript(recipientAddress.address), amount);
         })

src/models/StratumV1Client.spec.ts

@@ -1,24 +1,15 @@
 import { ConfigService } from '@nestjs/config';
-import { Test, TestingModule } from '@nestjs/testing';
-import { TypeOrmModule } from '@nestjs/typeorm';
 import { Socket } from 'net';
 import { BehaviorSubject } from 'rxjs';
-import { DataSource } from 'typeorm';
 
 import { MockRecording1 } from '../../test/models/MockRecording1';
-import { AddressSettingsModule } from '../ORM/address-settings/address-settings.module';
 import { AddressSettingsService } from '../ORM/address-settings/address-settings.service';
-import { BlocksEntity } from '../ORM/blocks/blocks.entity';
 import { BlocksService } from '../ORM/blocks/blocks.service';
-import { ClientStatisticsEntity } from '../ORM/client-statistics/client-statistics.entity';
-import { ClientStatisticsModule } from '../ORM/client-statistics/client-statistics.module';
-import { ClientStatisticsService } from '../ORM/client-statistics/client-statistics.service';
-import { ClientEntity } from '../ORM/client/client.entity';
-import { ClientModule } from '../ORM/client/client.module';
 import { ClientService } from '../ORM/client/client.service';
 import { BitcoinRpcService as MockBitcoinRpcService } from '../services/bitcoin-rpc.service';
 import { NotificationService } from '../services/notification.service';
 import { StratumV1JobsService } from '../services/stratum-v1-jobs.service';
+import { DifficultyUtils } from '../utils/difficulty.utils';
 import { IBlockTemplate } from './bitcoin-rpc/IBlockTemplate';
 import { MiningJob } from './MiningJob';
 import { StratumV1Client } from './StratumV1Client';
@@ -45,10 +36,12 @@ describe('StratumV1Client', () => {
     let bitcoinRpcService: MockBitcoinRpcService;
 
     let clientService: ClientService;
-    let clientStatisticsService: ClientStatisticsService;
     let notificationService: NotificationService;
     let blocksService: BlocksService;
     let configService: ConfigService;
+    let addressSettings: AddressSettingsService;
+    let shareAccountingService: { recordAcceptedShare: jest.Mock };
+    let redisMessagingService: { setClientPresence: jest.Mock; removeClientPresence: jest.Mock };
 
     let client: StratumV1Client;
 
@@ -60,28 +53,36 @@ describe('StratumV1Client', () => {
 
     let newBlockEmitter: BehaviorSubject<IBlockTemplate> = new BehaviorSubject(MockRecording1.BLOCK_TEMPLATE);
 
-    let moduleRef: TestingModule;
+    beforeEach(async () => {
 
-    beforeAll(async () => {
+        jest.useFakeTimers({ advanceTimers: true })
-        moduleRef = await Test.createTestingModule({
+        jest.setSystemTime(new Date(parseInt(MockRecording1.TIME, 16) * 1000));
-            imports: [
+        consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
-                TypeOrmModule.forRoot({
+        consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
-                    type: 'better-sqlite3',
+        consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
-                    database: ':memory:',
+
-                    synchronize: true,
+        const clients = new Map<string, any>();
-                    autoLoadEntities: true,
+        let nextClientId = 1;
-                    cache: true,
+        clientService = {
-                    logging: false,
+            insert: jest.fn(async (partialClient) => {
-                    entities: [ClientEntity, ClientStatisticsEntity, BlocksEntity]
+                const clientEntity = {
+                    id: `00000000-0000-4000-8000-${String(nextClientId++).padStart(12, '0')}`,
+                    hashRate: 0,
+                    updatedAt: new Date(),
+                    deletedAt: null,
+                    ...partialClient,
+                };
+                clients.set(clientEntity.id, clientEntity);
+                return clientEntity;
             }),
-                ClientModule,
+            delete: jest.fn(async (id: string) => {
-                ClientStatisticsModule,
+                clients.delete(id);
-                AddressSettingsModule
+            }),
-            ],
+            connectedClientCount: jest.fn(async () => clients.size),
-            providers: [
+            updateBestDifficultyIfHigher: jest.fn().mockResolvedValue({ affected: 1 }),
-                {
+        } as any;
-                    provide: ConfigService,
+
-                    useValue: {
+        configService = {
             get: jest.fn((key: string) => {
                 switch (key) {
                     case 'DEV_FEE_ADDRESS':
@@ -91,44 +92,7 @@ describe('StratumV1Client', () => {
                 }
                 return null;
             })
-                    }
+        } as any;
-                }
-            ],
-        }).compile();
-
-
-    })
-
-
-    beforeEach(async () => {
-
-        jest.useFakeTimers({ advanceTimers: true })
-        jest.setSystemTime(new Date(parseInt(MockRecording1.TIME, 16) * 1000));
-        consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
-        consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
-        consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
-
-        clientService = moduleRef.get<ClientService>(ClientService);
-
-        const dataSource = moduleRef.get<DataSource>(DataSource);
-
-        await dataSource.getRepository(ClientStatisticsEntity).clear();
-        await dataSource.getRepository(ClientEntity).clear();
-        await dataSource.getRepository(BlocksEntity).clear();
-
-
-        clientStatisticsService = moduleRef.get<ClientStatisticsService>(ClientStatisticsService);
-
-        configService = moduleRef.get<ConfigService>(ConfigService);
-        (configService.get as jest.Mock).mockImplementation((key: string) => {
-            switch (key) {
-                case 'DEV_FEE_ADDRESS':
-                    return 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4';
-                case 'NETWORK':
-                    return 'testnet';
-            }
-            return null;
-        });
         (StratumV1Client as any).blockedUserAgentLogState.clear();
         (StratumV1Client as any).validationErrorLogState.clear();
 
@@ -154,13 +118,24 @@ describe('StratumV1Client', () => {
         socket.end = jest.fn();
         jest.spyOn(socket, 'destroy').mockImplementation(() => socket);
 
-        const addressSettings = moduleRef.get<AddressSettingsService>(AddressSettingsService);
+        addressSettings = {
+            getSettings: jest.fn().mockResolvedValue(null),
+            updateBestDifficultyIfHigher: jest.fn().mockResolvedValue({ affected: 1 }),
+            resetBestDifficultyAndShares: jest.fn().mockResolvedValue(undefined),
+        } as any;
         notificationService = {
             notifySubscribersBlockFound: jest.fn().mockResolvedValue(undefined)
         } as any;
         blocksService = {
             save: jest.fn().mockResolvedValue(undefined)
         } as any;
+        shareAccountingService = {
+            recordAcceptedShare: jest.fn().mockResolvedValue(undefined),
+        };
+        redisMessagingService = {
+            setClientPresence: jest.fn().mockResolvedValue(undefined),
+            removeClientPresence: jest.fn().mockResolvedValue(undefined),
+        };
 
 
         client = new StratumV1Client(
@@ -168,11 +143,12 @@ describe('StratumV1Client', () => {
             stratumV1JobsService,
             bitcoinRpcService,
             clientService,
-            clientStatisticsService,
             notificationService,
             blocksService,
             configService,
-            addressSettings
+            addressSettings,
+            shareAccountingService as any,
+            redisMessagingService as any
         );
 
         client.extraNonceAndSessionId = MockRecording1.EXTRA_NONCE;
@@ -193,6 +169,36 @@ describe('StratumV1Client', () => {
         expect(socket.on).toHaveBeenCalled();
     });
 
+    it('should clean up socket state only once when destroyed repeatedly', async () => {
+        const unsubscribe = jest.fn();
+        const timer = setInterval(() => undefined, 1000);
+        const removeListenerSpy = jest.spyOn(socket, 'removeListener');
+
+        (client as any).clientEntity = {
+            id: '00000000-0000-4000-8000-000000000001',
+            address: 'tb1qcleanup',
+        };
+        (client as any).stratumSubscription = { unsubscribe };
+        (client as any).backgroundWork = [timer];
+        (client as any).miningSubmissionHashes.add('submitted-share');
+        (client as any).buffer = 'partial-message';
+
+        await Promise.all([client.destroy(), client.destroy()]);
+
+        expect(redisMessagingService.removeClientPresence).toHaveBeenCalledTimes(1);
+        expect(redisMessagingService.removeClientPresence).toHaveBeenCalledWith(
+            '00000000-0000-4000-8000-000000000001',
+            'tb1qcleanup',
+        );
+        expect(clientService.delete).toHaveBeenCalledTimes(1);
+        expect(clientService.delete).toHaveBeenCalledWith('00000000-0000-4000-8000-000000000001');
+        expect(unsubscribe).toHaveBeenCalledTimes(1);
+        expect(removeListenerSpy).toHaveBeenCalledWith('data', expect.any(Function));
+        expect((client as any).backgroundWork).toEqual([]);
+        expect((client as any).miningSubmissionHashes.size).toBe(0);
+        expect((client as any).buffer).toBe('');
+    });
+
     it('should close socket on invalid JSON', () => {
         emitMessage('INVALID');
         jest.spyOn(socket, 'destroy');
@@ -211,6 +217,17 @@ describe('StratumV1Client', () => {
 
     });
 
+    it('should disable application idle timeout after Stratum initialization', async () => {
+        const setTimeoutSpy = jest.spyOn(socket, 'setTimeout').mockImplementation(() => socket);
+        jest.spyOn(client as any, 'write').mockImplementation(() => Promise.resolve(true));
+
+        emitMessage(MockRecording1.MINING_SUBSCRIBE);
+        emitMessage(MockRecording1.MINING_AUTHORIZE);
+        await new Promise((r) => setTimeout(r, 100));
+
+        expect(setTimeoutSpy).toHaveBeenCalledWith(0);
+    });
+
     it('should block non-compliant user agents on subscribe without allocating a session', async () => {
         (configService.get as jest.Mock).mockImplementation((key: string) => {
             switch (key) {
@@ -263,11 +280,10 @@ describe('StratumV1Client', () => {
             stratumV1JobsService,
             bitcoinRpcService,
             clientService,
-            clientStatisticsService,
             notificationService,
             blocksService,
             configService,
-            moduleRef.get<AddressSettingsService>(AddressSettingsService)
+            addressSettings
         );
 
         socketEmitter(Buffer.from(`{"id":1,"method":"mining.subscribe","params":["NMMiner/1.0"]}\n`));
@@ -308,6 +324,26 @@ describe('StratumV1Client', () => {
         expect(socket.write).toHaveBeenCalledWith(`{"id":null,"method":"mining.set_difficulty","params":[512]}\n`, expect.any(Function));
     });
 
+    it('should clamp suggested difficulty to the configured minimum', async () => {
+        (configService.get as jest.Mock).mockImplementation((key: string) => {
+            switch (key) {
+                case 'STRATUM_MIN_DIFFICULTY':
+                    return '1';
+                case 'DEV_FEE_ADDRESS':
+                    return 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4';
+                case 'NETWORK':
+                    return 'testnet';
+            }
+            return null;
+        });
+        jest.spyOn(socket, 'write').mockImplementation((data) => true);
+
+        emitMessage(`{"id":4,"method":"mining.suggest_difficulty","params":[0]}`);
+        await new Promise((r) => setTimeout(r, 1));
+
+        expect(socket.write).toHaveBeenCalledWith(`{"id":null,"method":"mining.set_difficulty","params":[1]}\n`, expect.any(Function));
+    });
+
     it('should set difficulty', async () => {
         jest.spyOn(client as any, 'write').mockImplementation((data) => Promise.resolve(true));
 
@@ -369,6 +405,21 @@ describe('StratumV1Client', () => {
         await new Promise((r) => setTimeout(r, 1000));
 
         expect((client as any).write).lastCalledWith(`{\"id\":5,\"error\":null,\"result\":true}\n`);
+        expect(shareAccountingService.recordAcceptedShare).toHaveBeenCalledWith(expect.objectContaining({
+            protocol: 'sv1',
+            address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+            clientName: 'bitaxe3',
+            sessionId: MockRecording1.EXTRA_NONCE,
+            jobId: '1',
+            jobTemplateId: '1',
+            creditedDifficulty: 0,
+            isBlockCandidate: false,
+        }));
+        expect(redisMessagingService.setClientPresence).toHaveBeenCalledWith(expect.objectContaining({
+            address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+            clientName: 'bitaxe3',
+            sessionId: MockRecording1.EXTRA_NONCE,
+        }));
 
 
     });
@@ -421,9 +472,9 @@ describe('StratumV1Client', () => {
         jest.spyOn(client as any, 'write').mockImplementation((data) => Promise.resolve(true));
         jest.spyOn(client as any, 'calculateDifficulty').mockReturnValue({
             submissionDifficulty: 1024,
-            submissionHash: 'share'
+            submissionHash: 'share',
+            hashBuffer: DifficultyUtils.difficultyToTarget(1024),
         });
-        const addressSettings = moduleRef.get<AddressSettingsService>(AddressSettingsService);
         const getSettingsSpy = jest.spyOn(addressSettings, 'getSettings');
         const updateIfHigherSpy = jest.spyOn(addressSettings as any, 'updateBestDifficultyIfHigher').mockResolvedValue({ affected: 1 });
         const clientUpdateIfHigherSpy = jest.spyOn(clientService as any, 'updateBestDifficultyIfHigher').mockResolvedValue({ affected: 1 });
@@ -446,6 +497,27 @@ describe('StratumV1Client', () => {
         expect(getSettingsSpy).not.toHaveBeenCalled();
     });
 
+    it('should reject shares by exact target even when reported difficulty is huge', async () => {
+        jest.spyOn(client as any, 'write').mockImplementation((data) => Promise.resolve(true));
+        jest.spyOn(client as any, 'calculateDifficulty').mockReturnValue({
+            submissionDifficulty: Number.MAX_SAFE_INTEGER,
+            submissionHash: 'too-easy',
+            hashBuffer: Buffer.alloc(32, 0xff),
+        });
+
+        emitMessage(MockRecording1.MINING_SUBSCRIBE);
+        emitMessage(`{"id": 4, "method": "mining.suggest_difficulty", "params": [1024]}`);
+        emitMessage(MockRecording1.MINING_AUTHORIZE);
+        await new Promise((r) => setTimeout(r, 100));
+
+        emitMessage(MockRecording1.MINING_SUBMIT);
+        jest.useRealTimers();
+        await new Promise((r) => setTimeout(r, 1000));
+
+        expect((client as any).write).lastCalledWith(`{"id":5,"result":null,"error":[23,"Difficulty too low",""]}\n`);
+        expect(shareAccountingService.recordAcceptedShare).not.toHaveBeenCalled();
+    });
+
     it('should reject duplicate submissions', async () => {
         jest.spyOn(client as any, 'write').mockImplementation((data) => Promise.resolve(true));
 
@@ -546,11 +618,10 @@ describe('StratumV1Client', () => {
             stratumV1JobsService,
             bitcoinRpcService,
             clientService,
-            clientStatisticsService,
             notificationService,
             blocksService,
             configService,
-            moduleRef.get<AddressSettingsService>(AddressSettingsService)
+            addressSettings
         );
         jest.spyOn(secondClient as any, 'write').mockImplementation((data) => Promise.resolve(true));
         jest.spyOn(secondClient as any, 'getRandomHexString').mockReturnValue(MockRecording1.EXTRA_NONCE);
@@ -575,12 +646,13 @@ describe('StratumV1Client', () => {
     });
 
     it('should submit and persist found blocks', async () => {
+        (bitcoinRpcService.SUBMIT_BLOCK as jest.Mock).mockResolvedValue('SUCCESS!');
         jest.spyOn(client as any, 'write').mockImplementation((data) => Promise.resolve(true));
         jest.spyOn(client as any, 'calculateDifficulty').mockReturnValue({
             submissionDifficulty: Number.MAX_SAFE_INTEGER,
-            submissionHash: 'block-share'
+            submissionHash: 'block-share',
+            hashBuffer: Buffer.alloc(32),
         });
-        const addressSettings = moduleRef.get<AddressSettingsService>(AddressSettingsService);
         jest.spyOn(addressSettings, 'resetBestDifficultyAndShares').mockResolvedValue(undefined);
 
         emitMessage(MockRecording1.MINING_SUBSCRIBE);

src/models/StratumV1Client.ts

@@ -9,16 +9,20 @@ import { clearInterval } from 'timers';
 
 import { AddressSettingsService } from '../ORM/address-settings/address-settings.service';
 import { BlocksService } from '../ORM/blocks/blocks.service';
-import { ClientStatisticsService } from '../ORM/client-statistics/client-statistics.service';
 import { ClientEntity } from '../ORM/client/client.entity';
 import { ClientService } from '../ORM/client/client.service';
+import { PayoutSnapshotService } from '../ORM/payout-snapshot/payout-snapshot.service';
+import { ShareAccountingService } from '../ORM/share-accounting/share-accounting.service';
 import { BitcoinRpcService } from '../services/bitcoin-rpc.service';
 import { NotificationService } from '../services/notification.service';
+import { RedisMessagingService } from '../services/redis-messaging.service';
 import { IJobTemplate, StratumV1JobsService } from '../services/stratum-v1-jobs.service';
+import { DifficultyUtils } from '../utils/difficulty.utils';
+import { hash256 } from '../utils/hash.utils';
 import { eRequestMethod } from './enums/eRequestMethod';
 import { eResponseMethod } from './enums/eResponseMethod';
 import { eStratumErrorCode } from './enums/eStratumErrorCode';
-import { MiningJob } from './MiningJob';
+import { AddressObject, MiningJob } from './MiningJob';
 import { AuthorizationMessage } from './stratum-messages/AuthorizationMessage';
 import { ConfigurationMessage } from './stratum-messages/ConfigurationMessage';
 import { MiningSubmitMessage } from './stratum-messages/MiningSubmitMessage';
@@ -31,6 +35,7 @@ import { StratumV1ClientStatistics } from './StratumV1ClientStatistics';
 const TRUE_DIFF_ONE = 2.695953529101131e67;
 const BLOCKED_USER_AGENT_LOG_INTERVAL_MS = 60 * 1000;
 const VALIDATION_ERROR_LOG_INTERVAL_MS = 60 * 1000;
+const DEFAULT_MIN_DIFFICULTY = 0.001;
 
 export class StratumV1Client {
     private static blockedUserAgentLogState = new Map<string, { nextLogAt: number, suppressed: number }>();
@@ -42,11 +47,14 @@ export class StratumV1Client {
     private clientSuggestedDifficulty: SuggestDifficulty;
     private stratumSubscription: Subscription;
     private backgroundWork: NodeJS.Timeout[] = [];
+    private readonly socketDataHandler: (data: Buffer) => void;
+    private destroyPromise: Promise<void> | null = null;
 
     private statistics: StratumV1ClientStatistics;
     private stratumInitialized = false;
     private usedSuggestedDifficulty = false;
     private sessionDifficulty: number = 100000;
+    private sessionDifficultyTarget: Buffer = DifficultyUtils.difficultyToTarget(this.sessionDifficulty);
 
     private clientEntity: ClientEntity;
     private creatingEntity: Promise<void>;
@@ -67,19 +75,66 @@ export class StratumV1Client {
         private readonly stratumV1JobsService: StratumV1JobsService,
         private readonly bitcoinRpcService: BitcoinRpcService,
         private readonly clientService: ClientService,
-        private readonly clientStatisticsService: ClientStatisticsService,
         private readonly notificationService: NotificationService,
         private readonly blocksService: BlocksService,
         private readonly configService: ConfigService,
-        private readonly addressSettingsService: AddressSettingsService
+        private readonly addressSettingsService: AddressSettingsService,
+        private readonly shareAccountingService?: ShareAccountingService,
+        private readonly redisMessagingService?: RedisMessagingService,
+        private readonly payoutSnapshotService?: PayoutSnapshotService,
+        private readonly accountingProtocol: 'sv1' | 'sv1_tls' = 'sv1',
     ) {
 
-        this.socket.on('data', (data: Buffer) => {
+        this.socketDataHandler = (data: Buffer) => {
+            void this.handleSocketData(data);
+        };
+        this.socket.on('data', this.socketDataHandler);
+
+
+    }
+
+    public async destroy(): Promise<void> {
+        if (this.destroyPromise != null) {
+            return this.destroyPromise;
+        }
+
+        this.destroyPromise = this.destroyInternal();
+        return this.destroyPromise;
+    }
+
+    private async destroyInternal(): Promise<void> {
+        this.connectionClosed = true;
+        this.socket.removeListener('data', this.socketDataHandler);
+        this.buffer = '';
+
+        if (this.stratumSubscription != null) {
+            this.stratumSubscription.unsubscribe();
+            this.stratumSubscription = null;
+        }
+
+        for (const work of this.backgroundWork) {
+            clearInterval(work);
+        }
+        this.backgroundWork = [];
+        this.miningSubmissionHashes.clear();
+
+        if (this.clientEntity?.id) {
+            const clientId = this.clientEntity.id;
+            const address = this.clientEntity.address;
+            await this.redisMessagingService?.removeClientPresence(clientId, address);
+            await this.clientService.delete(clientId);
+        }
+    }
+
+    private async handleSocketData(data: Buffer): Promise<void> {
+        if (this.connectionClosed || this.socket.destroyed || this.socket.writableEnded) {
+            return;
+        }
+
         this.buffer += data.toString();
-            let lines = this.buffer.split('\n');
+        const lines = this.buffer.split('\n');
         this.buffer = lines.pop() || ''; // Save the last part of the data (incomplete line) to the buffer
 
-            (async () => {
         for (const m of lines.filter(l => l.length > 0)) {
             if (this.connectionClosed || this.socket.destroyed || this.socket.writableEnded) {
                 break;
@@ -91,25 +146,6 @@ export class StratumV1Client {
                 console.error(e);
             }
         }
-            })();
-        });
-
-
-    }
-
-    public async destroy() {
-
-        if (this.clientEntity?.id) {
-            await this.clientService.delete(this.clientEntity.id);
-        }
-
-        if (this.stratumSubscription != null) {
-            this.stratumSubscription.unsubscribe();
-        }
-
-        this.backgroundWork.forEach(work => {
-            clearInterval(work);
-        });
     }
 
     private getRandomHexString() {
@@ -156,7 +192,7 @@ export class StratumV1Client {
 
                     if (this.sessionStart == null) {
                         this.sessionStart = new Date();
-                        this.statistics = new StratumV1ClientStatistics(this.clientStatisticsService);
+                        this.statistics = new StratumV1ClientStatistics(this.getMinimumDifficulty());
                         this.extraNonceAndSessionId = this.getRandomHexString();
                         //console.log(`New client ID: : ${this.extraNonceAndSessionId}, ${this.socket.remoteAddress}:${this.socket.remotePort}`);
                     }
@@ -238,6 +274,7 @@ export class StratumV1Client {
                     this.clientAuthorization = authorizationMessage;
                     if (this.clientSuggestedDifficulty == null && this.clientAuthorization.startingDiff != null && this.clientAuthorization.startingDiff > this.sessionDifficulty) {
                         this.sessionDifficulty = this.clientAuthorization.startingDiff;
+                        this.sessionDifficultyTarget = DifficultyUtils.difficultyToTarget(this.sessionDifficulty);
                     }
                     const success = await this.write(JSON.stringify(this.clientAuthorization.response()) + '\n');
                     if (!success) {
@@ -278,7 +315,8 @@ export class StratumV1Client {
                 if (errors.length === 0) {
 
                     this.clientSuggestedDifficulty = suggestDifficultyMessage;
-                    this.sessionDifficulty = suggestDifficultyMessage.suggestedDifficulty;
+                    this.sessionDifficulty = this.clampDifficulty(suggestDifficultyMessage.suggestedDifficulty);
+                    this.sessionDifficultyTarget = DifficultyUtils.difficultyToTarget(this.sessionDifficulty);
                     const success = await this.write(JSON.stringify(this.clientSuggestedDifficulty.response(this.sessionDifficulty)) + '\n');
                     if (!success) {
                         return;
@@ -366,6 +404,7 @@ export class StratumV1Client {
 
     private async initStratum() {
         this.stratumInitialized = true;
+        this.socket.setTimeout(0);
 
         if (this.isBlockedUserAgent(this.clientSubscription.userAgent)) {
             this.logBlockedUserAgent(this.clientSubscription.userAgent);
@@ -373,12 +412,6 @@ export class StratumV1Client {
             return;
         }
 
-        switch (this.clientSubscription.userAgent) {
-            case 'cpuminer': {
-                this.sessionDifficulty = 0.1;
-            }
-        }
-
         if (this.clientSuggestedDifficulty == null) {
             //console.log(`Setting difficulty to ${this.sessionDifficulty}`)
             const setDifficulty = JSON.stringify(new SuggestDifficulty().response(this.sessionDifficulty));
@@ -415,14 +448,11 @@ export class StratumV1Client {
 
     private async sendNewMiningJob(jobTemplate: IJobTemplate) {
 
-        let payoutInformation= [
+        let payoutInformation = this.getPayoutInformation(jobTemplate, this.clientAuthorization.address);
-            { address: this.clientAuthorization.address, percent: 100 }
-        ];
         // const devFeeAddress = this.configService.get('DEV_FEE_ADDRESS');
         // //50Th/s
         // this.noFee = false;
         // if (this.clientEntity) {
-        //     this.hashRate = await this.clientStatisticsService.getHashRateForSession(this.clientEntity.id);
         //     // 250Gh/s
         //     if(this.hashRate < 250000000000){
         //         this.statistics.targetSubmitShareEveryNSeconds = 10;
@@ -491,12 +521,35 @@ export class StratumV1Client {
                     startTime: new Date(),
                     bestDifficulty: 0
                 });
+                await this.updateClientPresence(new Date());
             })();
         }
 
         await this.creatingEntity;
     }
 
+    private async updateClientPresence(lastSeen: Date): Promise<void> {
+        if (this.clientEntity == null) {
+            return;
+        }
+
+        try {
+            await this.redisMessagingService?.setClientPresence({
+                clientId: this.clientEntity.id,
+                address: this.clientEntity.address,
+                clientName: this.clientEntity.clientName,
+                sessionId: this.clientEntity.sessionId,
+                userAgent: this.clientEntity.userAgent,
+                startTime: new Date(this.clientEntity.startTime).toISOString(),
+                lastSeen: lastSeen.toISOString(),
+                hashRate: this.statistics?.hashRate ?? 0,
+                bestDifficulty: Number(this.clientEntity.bestDifficulty ?? 0),
+            });
+        } catch (error) {
+            console.error(`Failed to update SV1 client presence: ${error.message}`);
+        }
+    }
+
     private async handleMiningSubmission(submission: MiningSubmitMessage) {
 
         const job = this.stratumV1JobsService.getJobById(submission.jobId);
@@ -563,18 +616,23 @@ export class StratumV1Client {
             submission.extraNonce2,
             timestamp
         );
-        const { submissionDifficulty } = this.calculateDifficulty(header);
+        const { submissionDifficulty, hashBuffer } = this.calculateDifficulty(header);
 
         //console.log(`DIFF: ${submissionDifficulty} of ${this.sessionDifficulty} from ${this.clientAuthorization.worker + '.' + this.extraNonceAndSessionId}`);
 
 
-        if (submissionDifficulty >= this.sessionDifficulty) {
+        if (DifficultyUtils.meetsTarget(hashBuffer, this.sessionDifficultyTarget)) {
             const success = await this.write(JSON.stringify(submission.response()) + '\n');
             if (!success) {
                 return false;
             }
 
-            if (submissionDifficulty >= jobTemplate.blockData.networkDifficulty) {
+            let blockSubmissionResult: string = null;
+            const isBlockCandidate = DifficultyUtils.meetsTarget(
+                hashBuffer,
+                DifficultyUtils.difficultyToTarget(jobTemplate.blockData.networkDifficulty),
+            );
+            if (isBlockCandidate) {
                 console.log('!!! BLOCK FOUND !!!');
                 const updatedJobBlock = job.copyAndUpdateBlock(
                     jobTemplate,
@@ -585,30 +643,56 @@ export class StratumV1Client {
                     timestamp
                 );
                 const blockHex = updatedJobBlock.toHex(false);
-                const result = await this.bitcoinRpcService.SUBMIT_BLOCK(blockHex);
+                blockSubmissionResult = await this.bitcoinRpcService.SUBMIT_BLOCK(blockHex);
                 await this.blocksService.save({
                     height: jobTemplate.blockData.height,
                     minerAddress: this.clientAuthorization.address,
                     worker: this.clientAuthorization.worker,
                     sessionId: this.extraNonceAndSessionId,
-                    blockData: blockHex
+                    blockData: blockHex,
+                    blockSubmissionResult,
+                    payoutSnapshotId: jobTemplate.blockData.payoutSnapshotId ?? null,
+                });
+                await this.payoutSnapshotService?.finalizeSnapshotForBlock({
+                    payoutSnapshotId: jobTemplate.blockData.payoutSnapshotId,
+                    blockHeight: jobTemplate.blockData.height,
+                    blockSubmissionResult,
                 });
 
-                await this.notificationService.notifySubscribersBlockFound(this.clientAuthorization.address, jobTemplate.blockData.height, updatedJobBlock, result);
+                await this.notificationService.notifySubscribersBlockFound(this.clientAuthorization.address, jobTemplate.blockData.height, updatedJobBlock, blockSubmissionResult);
                 //success
-                if (result == null) {
+                if (this.isSuccessfulBlockSubmission(blockSubmissionResult)) {
                     await this.addressSettingsService.resetBestDifficultyAndShares();
                 }
             }
             await this.ensureClientEntity();
             try {
+                await this.shareAccountingService?.recordAcceptedShare({
+                    protocol: this.accountingProtocol,
+                    address: this.clientAuthorization.address,
+                    clientName: this.clientAuthorization.worker,
+                    sessionId: this.extraNonceAndSessionId,
+                    clientId: this.clientEntity.id,
+                    jobId: job.jobId,
+                    jobTemplateId: job.jobTemplateId,
+                    blockHeight: jobTemplate.blockData.height,
+                    creditedDifficulty: this.sessionDifficulty,
+                    submissionDifficulty,
+                    networkDifficulty: jobTemplate.blockData.networkDifficulty,
+                    nonce: submission.nonce,
+                    ntime: submission.ntime,
+                    version: Number.isFinite(versionMask)
+                        ? (jobTemplate.block.version ^ versionMask).toString(16)
+                        : jobTemplate.block.version.toString(16),
+                    extraNonce2: submission.extraNonce2,
+                    isBlockCandidate,
+                    blockSubmissionResult,
+                });
                 await this.statistics.addShares(this.clientEntity, this.sessionDifficulty);
                 const now = new Date();
-                // only update every minute
-                //if (this.clientEntity.updatedAt == null || now.getTime() - this.clientEntity.updatedAt.getTime() > 1000 * 60) {
-                this.clientService.heartbeatBulkAsync(this.clientEntity.id, this.statistics.hashRate, now);
                 this.clientEntity.updatedAt = now;
-                //}
+                this.clientEntity.hashRate = this.statistics.hashRate;
+                await this.updateClientPresence(now);
 
             } catch (e) {
                 console.log(e);
@@ -618,6 +702,7 @@ export class StratumV1Client {
                 await this.clientService.updateBestDifficultyIfHigher(this.clientEntity.id, submissionDifficulty);
                 this.clientEntity.bestDifficulty = submissionDifficulty;
                 await this.addressSettingsService.updateBestDifficultyIfHigher(this.clientAuthorization.address, submissionDifficulty, this.clientEntity.userAgent);
+                await this.updateClientPresence(new Date());
             }
 
 
@@ -642,7 +727,7 @@ export class StratumV1Client {
     }
 
     private async checkDifficulty() {
-        const targetDiff = this.statistics.getSuggestedDifficulty(this.sessionDifficulty);
+        const targetDiff = this.clampDifficulty(this.statistics.getSuggestedDifficulty(this.sessionDifficulty));
         if (targetDiff == null) {
             return;
         }
@@ -650,6 +735,7 @@ export class StratumV1Client {
         if (targetDiff != this.sessionDifficulty) {
             //console.log(`Adjusting ${this.extraNonceAndSessionId} difficulty from ${this.sessionDifficulty} to ${targetDiff}`);
             this.sessionDifficulty = targetDiff;
+            this.sessionDifficultyTarget = DifficultyUtils.difficultyToTarget(this.sessionDifficulty);
 
             const data = JSON.stringify({
                 id: null,
@@ -680,13 +766,13 @@ export class StratumV1Client {
         }
     }
 
-    private calculateDifficulty(header: Buffer): { submissionDifficulty: number, submissionHash: string } {
+    private calculateDifficulty(header: Buffer): { submissionDifficulty: number, submissionHash: string, hashBuffer: Buffer } {
 
-        const hashResult = bitcoinjs.crypto.hash256(header);
+        const hashResult = hash256(header);
 
         const target = this.le256todouble(hashResult);
         const submissionDifficulty = target === 0 ? Number.POSITIVE_INFINITY : TRUE_DIFF_ONE / target;
-        return { submissionDifficulty, submissionHash: hashResult.toString('hex') };
+        return { submissionDifficulty, submissionHash: hashResult.toString('hex'), hashBuffer: hashResult };
     }
 
 
@@ -778,6 +864,39 @@ export class StratumV1Client {
         return ` sample=${values.join(',')}`;
     }
 
+    private clampDifficulty(difficulty: number | null): number | null {
+        if (difficulty == null || !Number.isFinite(difficulty)) {
+            return null;
+        }
+        const configuredMinimum = this.getConfiguredMinimumDifficulty();
+        return configuredMinimum == null ? difficulty : Math.max(difficulty, configuredMinimum);
+    }
+
+    private getMinimumDifficulty(): number {
+        return this.getConfiguredMinimumDifficulty() ?? DEFAULT_MIN_DIFFICULTY;
+    }
+
+    private getConfiguredMinimumDifficulty(): number | null {
+        const configured = parseFloat(
+            this.configService.get<string>('STRATUM_MIN_DIFFICULTY')
+            ?? process.env.STRATUM_MIN_DIFFICULTY
+            ?? '',
+        );
+        return Number.isFinite(configured) && configured > 0 ? configured : null;
+    }
+
+    private getPayoutInformation(jobTemplate: IJobTemplate, fallbackAddress: string): AddressObject[] {
+        if (this.configService.get('PAYOUT_COINBASE_MODE') === 'snapshot' && jobTemplate.blockData.payoutOutputs?.length > 0) {
+            return jobTemplate.blockData.payoutOutputs;
+        }
+
+        return [{ address: fallbackAddress, percent: 100 }];
+    }
+
+    private isSuccessfulBlockSubmission(result?: string | null): boolean {
+        return result == null || result === 'SUCCESS!';
+    }
+
     private closeSocket() {
         this.connectionClosed = true;
         if (!this.socket.destroyed) {

src/models/StratumV1ClientStatistics.spec.ts

@@ -8,73 +8,31 @@ describe('StratumV1ClientStatistics', () => {
         sessionId: '57a6f098'
     } as any;
 
-    let clientStatisticsService: {
-        insert: jest.Mock,
-        updateBulkAsync: jest.Mock
-    };
     let statistics: StratumV1ClientStatistics;
 
     beforeEach(() => {
         jest.useFakeTimers();
         jest.setSystemTime(new Date('2026-05-06T12:00:00Z'));
-        clientStatisticsService = {
+        statistics = new StratumV1ClientStatistics();
-            insert: jest.fn().mockResolvedValue(undefined),
-            updateBulkAsync: jest.fn().mockResolvedValue(undefined)
-        };
-        statistics = new StratumV1ClientStatistics(clientStatisticsService as any);
     });
 
     afterEach(() => {
         jest.useRealTimers();
     });
 
-    it('should insert the first share bucket', async () => {
+    it('should keep runtime hashrate at zero before enough time passes', async () => {
         await statistics.addShares(client, 64);
 
-        expect(clientStatisticsService.insert).toHaveBeenCalledWith({
+        expect(statistics.hashRate).toBe(0);
-            time: new Date('2026-05-06T12:00:00Z').getTime(),
-            clientId: client.id,
-            shares: 64,
-            acceptedCount: 1,
-            address: client.address,
-            clientName: client.clientName,
-            sessionId: client.sessionId
-        });
     });
 
-    it('should update the current share bucket for additional shares', async () => {
+    it('should update runtime hashrate from accepted shares', async () => {
+        for (let i = 0; i < 3; i++) {
+            jest.setSystemTime(new Date(Date.parse('2026-05-06T12:00:00Z') + (i * 31000)));
             await statistics.addShares(client, 64);
-        await statistics.addShares(client, 32);
+        }
 
-        expect(clientStatisticsService.updateBulkAsync).toHaveBeenCalledWith({
+        expect(statistics.hashRate).toBeGreaterThan(0);
-            time: new Date('2026-05-06T12:00:00Z').getTime(),
-            clientId: client.id,
-            shares: 96,
-            acceptedCount: 2
-        });
-    });
-
-    it('should create a new share bucket when the time slot changes', async () => {
-        await statistics.addShares(client, 64);
-        jest.setSystemTime(new Date('2026-05-06T12:10:00Z'));
-
-        await statistics.addShares(client, 32);
-
-        expect(clientStatisticsService.updateBulkAsync).toHaveBeenCalledWith({
-            time: new Date('2026-05-06T12:00:00Z').getTime(),
-            clientId: client.id,
-            shares: 64,
-            acceptedCount: 1
-        });
-        expect(clientStatisticsService.insert).toHaveBeenLastCalledWith({
-            time: new Date('2026-05-06T12:10:00Z').getTime(),
-            clientId: client.id,
-            shares: 32,
-            acceptedCount: 1,
-            address: client.address,
-            clientName: client.clientName,
-            sessionId: client.sessionId
-        });
     });
 
     it('should not suggest a difficulty change before enough time or shares have passed', () => {
@@ -104,4 +62,11 @@ describe('StratumV1ClientStatistics', () => {
 
         expect(statistics.getSuggestedDifficulty(128)).toBe(16);
     });
+
+    it('should not suggest a difficulty below the configured minimum', () => {
+        statistics = new StratumV1ClientStatistics(1);
+        jest.setSystemTime(new Date('2026-05-06T12:06:00Z'));
+
+        expect(statistics.getSuggestedDifficulty(1)).toBe(1);
+    });
 });

src/models/StratumV1ClientStatistics.ts

@@ -1,38 +1,22 @@
-import { ClientStatisticsService } from '../ORM/client-statistics/client-statistics.service';
 import { ClientEntity } from '../ORM/client/client.entity';
 
 const CACHE_SIZE = 30;
-const MIN_DIFF = 0.001;
+const DEFAULT_MIN_DIFF = 0.001;
 export class StratumV1ClientStatistics {
 
     public targetSubmitShareEveryNSeconds: number = 30;
     public hashRate = 0;
 
-    private shares: number = 0;
-    private acceptedCount: number = 0;
-
     private submissionCacheStart: Date;
     private submissionCache: { time: Date, difficulty: number }[] = [];
     private submissionCacheDifficultySum = 0;
 
-    private currentTimeSlot: number = null;
+    constructor(private readonly minDifficulty = DEFAULT_MIN_DIFF) {
-
-    constructor(
-        private readonly clientStatisticsService: ClientStatisticsService,
-    ) {
         this.submissionCacheStart = new Date();
     }
 
-
+    public async addShares(_client: ClientEntity, targetDifficulty: number) {
-
-    // We don't want to save them here because it can be DB intensive, instead do it every once in
-    // awhile with saveShares()
-    public async addShares(client: ClientEntity, targetDifficulty: number) {
-
-        // 10 min
-        var coeff = 1000 * 60 * 10;
         var date = new Date();
-        var timeSlot = new Date(Math.floor(date.getTime() / coeff) * coeff).getTime();
 
         if (this.submissionCache.length > CACHE_SIZE) {
             this.submissionCacheDifficultySum -= this.submissionCache[0].difficulty;
@@ -44,55 +28,6 @@ export class StratumV1ClientStatistics {
         });
         this.submissionCacheDifficultySum += targetDifficulty;
 
-        if (this.currentTimeSlot == null) {
-            // First record, insert it
-            this.currentTimeSlot = timeSlot;
-            this.shares += targetDifficulty;
-            this.acceptedCount++;
-            await this.clientStatisticsService.insert({
-                time: this.currentTimeSlot,
-                clientId: client.id,
-                shares: this.shares,
-                acceptedCount: this.acceptedCount,
-                address: client.address,
-                clientName: client.clientName,
-                sessionId: client.sessionId
-            });
-        } else if (this.currentTimeSlot != timeSlot) {
-            // Transitioning to a new time slot,
-            // First update the old time slot with the latest data
-            this.clientStatisticsService.updateBulkAsync({
-                time: this.currentTimeSlot,
-                clientId: client.id,
-                shares: this.shares,
-                acceptedCount: this.acceptedCount,
-            });
-            // Set the new time slot and add incoming shares then insert it
-            this.currentTimeSlot = timeSlot;
-            this.shares = targetDifficulty;
-            this.acceptedCount = 1
-            await this.clientStatisticsService.insert({
-                time: this.currentTimeSlot,
-                clientId: client.id,
-                shares: this.shares,
-                acceptedCount: this.acceptedCount,
-                address: client.address,
-                clientName: client.clientName,
-                sessionId: client.sessionId
-            });
-        } else {
-            // Accept the shares if none of the prior conditions are met,
-            // saving to memory for storing later
-            this.shares += targetDifficulty;
-            this.acceptedCount++;
-            this.clientStatisticsService.updateBulkAsync({
-                time: this.currentTimeSlot,
-                clientId: client.id,
-                shares: this.shares,
-                acceptedCount: this.acceptedCount,
-            });
-        }
-
         const time = new Date().getTime() - this.submissionCache[0].time.getTime();
         if(time > 60000 && this.submissionCache.length > 2) { 
             this.hashRate = (this.submissionCacheDifficultySum * 4294967296) / (time / 1000);
@@ -132,8 +67,8 @@ export class StratumV1ClientStatistics {
         if (val === 0) {
             return null;
         }
-        if (val < MIN_DIFF) {
+        if (val < this.minDifficulty) {
-            return MIN_DIFF;
+            return this.minDifficulty;
         }
         let x = val | (val >> 1);
         x = x | (x >> 2);
@@ -142,8 +77,8 @@ export class StratumV1ClientStatistics {
         x = x | (x >> 16);
         x = x | (x >> 32);
         const res = x - (x >> 1);
-        if (res == 0 && val * 100 < MIN_DIFF) {
+        if (res == 0 && val * 100 < this.minDifficulty) {
-            return MIN_DIFF;
+            return this.minDifficulty;
         }
         if (res == 0) {
             return this.nearestPowerOfTwo(val * 100) / 100;

src/models/StratumV2Client.spec.ts

@@ -1,19 +1,27 @@
 import { ConfigService } from '@nestjs/config';
+import * as bitcoinjs from 'bitcoinjs-lib';
 import { Socket } from 'net';
 import { BehaviorSubject, firstValueFrom } from 'rxjs';
 
 import { MockRecording1 } from '../../test/models/MockRecording1';
 import { ClientEntity } from '../ORM/client/client.entity';
+import { CustomWorkService } from '../services/custom-work.service';
 import { StratumV1JobsService } from '../services/stratum-v1-jobs.service';
 import { BufferReader } from './sv2/sv2-binary-codec';
-import { SV2_CHANNEL_MSG_FLAG, Sv2MsgType } from './sv2/sv2-constants';
+import { SV2_CHANNEL_MSG_FLAG, Sv2MiningSetupFlags, Sv2MsgType, Sv2Protocol } from './sv2/sv2-constants';
 import {
     deserializeOpenExtendedMiningChannelSuccess,
     deserializeNewExtendedMiningJob,
     serializeOpenExtendedMiningChannel,
     serializeSubmitSharesExtended,
 } from './sv2/sv2-extended-messages';
-import { deserializeSetNewPrevHash, deserializeSubmitSharesError } from './sv2/sv2-messages';
+import { deserializeSetNewPrevHash, deserializeSubmitSharesError, serializeSetupConnection } from './sv2/sv2-messages';
+import {
+    deserializeSetCustomMiningJobError,
+    deserializeSetCustomMiningJobSuccess,
+    serializeSetCustomMiningJob,
+} from './sv2/sv2-jdp-messages';
+import { MiningJob } from './MiningJob';
 import { StratumV2Client } from './StratumV2Client';
 
 describe('StratumV2Client extended channels', () => {
@@ -58,7 +66,7 @@ describe('StratumV2Client extended channels', () => {
         const success = deserializeOpenExtendedMiningChannelSuccess(new BufferReader(successFrame.payload));
         expect(success.requestId).toBe(7);
         expect(success.channelId).toBe(1);
-        expect(success.extranonceSize).toBe(8);
+        expect(success.extranonceSize).toBe(10);
         expect(success.extranoncePrefix).toEqual(Buffer.from('00000001', 'hex'));
 
         expect(jobFrame?.extensionType).toBe(SV2_CHANNEL_MSG_FLAG);
@@ -107,7 +115,215 @@ describe('StratumV2Client extended channels', () => {
         expect(error.errorCode).toBe('invalid-extranonce-size');
     });
 
-    async function createClient(): Promise<{ client: StratumV2Client; sentFrames: any[] }> {
+    it('accepts SV2 work-selection setup and SetCustomMiningJob without sending pool work', async () => {
+        const { client, sentFrames } = await createClient();
+        await (client as any).handleSetupConnection(serializeSetupConnection({
+            protocol: Sv2Protocol.MINING,
+            minVersion: 2,
+            maxVersion: 2,
+            flags: Sv2MiningSetupFlags.REQUIRES_WORK_SELECTION | Sv2MiningSetupFlags.REQUIRES_VERSION_ROLLING,
+            endpoint_host: 'localhost',
+            endpoint_port: 3333,
+            vendor: 'jd-client',
+            hardwareVersion: '',
+            firmwareVersion: '',
+            deviceId: '',
+        }));
+
+        await (client as any).handleOpenExtendedMiningChannel(serializeOpenExtendedMiningChannel({
+            requestId: 1,
+            userIdentity: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4.worker',
+            nominalHashRate: 0,
+            maxTarget: Buffer.alloc(32, 0xff),
+            minExtranonceSize: 8,
+        }));
+        expect(sentFrames.some(frame => frame.msgType === Sv2MsgType.NEW_EXTENDED_MINING_JOB)).toBe(false);
+
+        sentFrames.length = 0;
+        await (client as any).handleSetCustomMiningJob(serializeSetCustomMiningJob({
+            channelId: 1,
+            requestId: 99,
+            token: Buffer.from('aa', 'hex'),
+            version: MockRecording1.BLOCK_TEMPLATE.version,
+            prevHash: Buffer.alloc(32, 1),
+            minNtime: parseInt(MockRecording1.TIME, 16),
+            nBits: parseInt(MockRecording1.BLOCK_TEMPLATE.bits, 16),
+            coinbaseTxVersion: 2,
+            coinbasePrefix: Buffer.from('51', 'hex'),
+            coinbaseTxInputNSequence: 0xffffffff,
+            coinbaseTxOutputs: Buffer.from('010000000000000000016a', 'hex'),
+            coinbaseTxLocktime: 0,
+            merklePath: [],
+        }));
+
+        const successFrame = sentFrames.find(frame => frame.msgType === Sv2MsgType.SET_CUSTOM_MINING_JOB_SUCCESS);
+        const success = deserializeSetCustomMiningJobSuccess(new BufferReader(successFrame.payload));
+        expect(success.channelId).toBe(1);
+        expect(success.requestId).toBe(99);
+        expect((client as any).channels.get(1).extendedJobs.get(success.jobId).workProtocol).toBe('sv2_jdp');
+    });
+
+    it('rejects SetCustomMiningJob when work selection was not negotiated', async () => {
+        const { client, sentFrames } = await createClient();
+        await (client as any).handleOpenExtendedMiningChannel(serializeOpenExtendedMiningChannel({
+            requestId: 1,
+            userIdentity: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4.worker',
+            nominalHashRate: 0,
+            maxTarget: Buffer.alloc(32, 0xff),
+            minExtranonceSize: 8,
+        }));
+
+        sentFrames.length = 0;
+        await (client as any).handleSetCustomMiningJob(serializeSetCustomMiningJob({
+            channelId: 1,
+            requestId: 100,
+            token: Buffer.from('aa', 'hex'),
+            version: MockRecording1.BLOCK_TEMPLATE.version,
+            prevHash: Buffer.alloc(32, 1),
+            minNtime: parseInt(MockRecording1.TIME, 16),
+            nBits: parseInt(MockRecording1.BLOCK_TEMPLATE.bits, 16),
+            coinbaseTxVersion: 2,
+            coinbasePrefix: Buffer.from('51', 'hex'),
+            coinbaseTxInputNSequence: 0xffffffff,
+            coinbaseTxOutputs: Buffer.from('010000000000000000016a', 'hex'),
+            coinbaseTxLocktime: 0,
+            merklePath: [],
+        }));
+
+        const errorFrame = sentFrames.find(frame => frame.msgType === Sv2MsgType.SET_CUSTOM_MINING_JOB_ERROR);
+        const error = deserializeSetCustomMiningJobError(new BufferReader(errorFrame.payload));
+        expect(error.channelId).toBe(1);
+        expect(error.requestId).toBe(100);
+        expect(error.errorCode).toBe('work-selection-not-negotiated');
+        expect((client as any).channels.get(1).extendedJobs.has(100)).toBe(false);
+    });
+
+    it('records accepted SV2 shares before presence updates', async () => {
+        const { client, shareAccountingService, redisMessagingService, jobTemplate } = await createClient();
+        (client as any).address = 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4';
+        (client as any).workerName = 'worker';
+        (client as any).sessionId = 'sv2-session';
+        (client as any).userAgent = 'test/sv2';
+
+        await (client as any).recordAcceptedShare(
+            2048,
+            1024,
+            jobTemplate,
+            null,
+            {
+                jobId: '1',
+                nonce: 123,
+                ntime: parseInt(MockRecording1.TIME, 16),
+                version: jobTemplate.block.version,
+                extraNonce2: 'c708000000000000',
+            },
+        );
+
+        expect(shareAccountingService.recordAcceptedShare).toHaveBeenCalledWith(expect.objectContaining({
+            protocol: 'sv2',
+            address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+            clientName: 'worker',
+            sessionId: 'sv2-session',
+            jobId: '1',
+            creditedDifficulty: 1024,
+            submissionDifficulty: 2048,
+            nonce: 123,
+            extraNonce2: 'c708000000000000',
+        }));
+        const accountingCallOrder = shareAccountingService.recordAcceptedShare.mock.invocationCallOrder[0];
+        const postAccountingPresenceUpdates = redisMessagingService.setClientPresence.mock.invocationCallOrder
+            .filter(callOrder => callOrder > accountingCallOrder);
+        expect(postAccountingPresenceUpdates.length).toBeGreaterThan(0);
+    });
+
+    it('does not submit a block when only the reported SV2 difficulty is huge', async () => {
+        const { client, shareAccountingService, bitcoinRpcService, blocksService, jobTemplate } = await createClient();
+        (client as any).address = 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4';
+        (client as any).workerName = 'worker';
+        (client as any).sessionId = 'sv2-session';
+        (client as any).userAgent = 'test/sv2';
+
+        const job = new MiningJob(
+            bitcoinjs.networks.testnet,
+            '1',
+            [{ address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4', percent: 100 }],
+            jobTemplate,
+        );
+
+        await (client as any).handleAcceptedShare(
+            {
+                nonce: 123,
+                ntime: parseInt(MockRecording1.TIME, 16),
+                version: jobTemplate.block.version,
+            },
+            { extranoncePrefix: Buffer.from(MockRecording1.EXTRA_NONCE, 'hex') },
+            job,
+            jobTemplate,
+            Number.MAX_SAFE_INTEGER,
+            1024,
+            Buffer.alloc(32, 0xff),
+        );
+
+        expect(bitcoinRpcService.SUBMIT_BLOCK).not.toHaveBeenCalled();
+        expect(blocksService.save).not.toHaveBeenCalled();
+        expect(shareAccountingService.recordAcceptedShare).toHaveBeenCalledWith(expect.objectContaining({
+            submissionDifficulty: Number.MAX_SAFE_INTEGER,
+            isBlockCandidate: false,
+        }));
+    });
+
+    it('submits a block when the SV2 hash target exactly meets network target', async () => {
+        const { client, bitcoinRpcService, blocksService, notificationService, addressSettingsService, jobTemplate } = await createClient();
+        bitcoinRpcService.SUBMIT_BLOCK.mockResolvedValue('SUCCESS!');
+        (client as any).address = 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4';
+        (client as any).workerName = 'worker';
+        (client as any).sessionId = 'sv2-session';
+        (client as any).userAgent = 'test/sv2';
+
+        const job = new MiningJob(
+            bitcoinjs.networks.testnet,
+            '1',
+            [{ address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4', percent: 100 }],
+            jobTemplate,
+        );
+
+        await (client as any).handleAcceptedShare(
+            {
+                nonce: 123,
+                ntime: parseInt(MockRecording1.TIME, 16),
+                version: jobTemplate.block.version,
+            },
+            { extranoncePrefix: Buffer.from(MockRecording1.EXTRA_NONCE, 'hex') },
+            job,
+            jobTemplate,
+            1,
+            1024,
+            Buffer.alloc(32),
+        );
+
+        expect(bitcoinRpcService.SUBMIT_BLOCK).toHaveBeenCalledWith(expect.any(String));
+        expect(blocksService.save).toHaveBeenCalledWith(expect.objectContaining({
+            height: MockRecording1.BLOCK_TEMPLATE.height,
+            minerAddress: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+            worker: 'worker',
+            sessionId: 'sv2-session',
+            blockData: expect.any(String),
+        }));
+        expect(notificationService.notifySubscribersBlockFound).toHaveBeenCalled();
+        expect(addressSettingsService.resetBestDifficultyAndShares).toHaveBeenCalled();
+    });
+
+    async function createClient(): Promise<{
+        client: StratumV2Client;
+        sentFrames: any[];
+        bitcoinRpcService: { SUBMIT_BLOCK: jest.Mock };
+        blocksService: { save: jest.Mock };
+        notificationService: { notifySubscribersBlockFound: jest.Mock };
+        addressSettingsService: { resetBestDifficultyAndShares: jest.Mock; updateBestDifficultyIfHigher: jest.Mock };
+        shareAccountingService: { recordAcceptedShare: jest.Mock };
+        redisMessagingService: { setClientPresence: jest.Mock; removeClientPresence: jest.Mock };
+        jobTemplate: any;
+    }> {
         const blockTemplate$ = new BehaviorSubject(MockRecording1.BLOCK_TEMPLATE);
         const bitcoinRpcService = {
             newBlockTemplate$: blockTemplate$.asObservable(),
@@ -115,7 +331,7 @@ describe('StratumV2Client extended channels', () => {
             SUBMIT_BLOCK: jest.fn().mockResolvedValue(null),
         };
         const stratumV1JobsService = new StratumV1JobsService(bitcoinRpcService as any);
-        await firstValueFrom(stratumV1JobsService.newMiningJob$);
+        const jobTemplate = await firstValueFrom(stratumV1JobsService.newMiningJob$);
 
         const mockSocket: any = {
             destroyed: false,
@@ -138,11 +354,34 @@ describe('StratumV2Client extended channels', () => {
             address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
             clientName: 'worker',
             userAgent: 'test/sv2',
+            startTime: new Date(),
             bestDifficulty: 0,
         } as unknown as ClientEntity;
 
         let nextChannelId = 1;
         const sentFrames: any[] = [];
+        const clientService = {
+            insert: jest.fn().mockResolvedValue(clientEntity),
+            delete: jest.fn().mockResolvedValue(undefined),
+            updateBestDifficultyIfHigher: jest.fn().mockResolvedValue(undefined),
+        };
+        const shareAccountingService = {
+            recordAcceptedShare: jest.fn().mockResolvedValue(undefined),
+        };
+        const notificationService = {
+            notifySubscribersBlockFound: jest.fn().mockResolvedValue(undefined),
+        };
+        const blocksService = {
+            save: jest.fn().mockResolvedValue(undefined),
+        };
+        const redisMessagingService = {
+            setClientPresence: jest.fn().mockResolvedValue(undefined),
+            removeClientPresence: jest.fn().mockResolvedValue(undefined),
+        };
+        const addressSettingsService = {
+            resetBestDifficultyAndShares: jest.fn().mockResolvedValue(undefined),
+            updateBestDifficultyIfHigher: jest.fn().mockResolvedValue(undefined),
+        };
         const client = new StratumV2Client(
             socket,
             Buffer.alloc(0),
@@ -163,22 +402,14 @@ describe('StratumV2Client extended channels', () => {
                 generateExtranoncePrefix: () => Buffer.from('00000002', 'hex'),
                 allocateExtendedExtranoncePrefix: jest.fn(() => Buffer.from('00000001', 'hex')),
                 releaseExtendedExtranoncePrefix: jest.fn(),
-                getExtendedMinerExtranonceSize: () => 8,
+                getExtendedMinerExtranonceSize: () => 10,
+                getExtendedTotalExtranonceSize: () => 14,
             } as any,
             stratumV1JobsService,
             bitcoinRpcService as any,
-            {
+            clientService as any,
-                insert: jest.fn().mockResolvedValue(clientEntity),
+            notificationService as any,
-                delete: jest.fn().mockResolvedValue(undefined),
+            blocksService as any,
-                heartbeatBulkAsync: jest.fn(),
-                updateBestDifficultyIfHigher: jest.fn().mockResolvedValue(undefined),
-            } as any,
-            {
-                insert: jest.fn().mockResolvedValue(undefined),
-                updateBulkAsync: jest.fn(),
-            } as any,
-            { notifySubscribersBlockFound: jest.fn().mockResolvedValue(undefined) } as any,
-            { save: jest.fn().mockResolvedValue(undefined) } as any,
             {
                 get: jest.fn((key: string) => {
                     switch (key) {
@@ -191,16 +422,33 @@ describe('StratumV2Client extended channels', () => {
                     }
                 }),
             } as unknown as ConfigService,
+            addressSettingsService as any,
+            new CustomWorkService(),
             {
-                resetBestDifficultyAndShares: jest.fn().mockResolvedValue(undefined),
+                hasKnownToken: jest.fn().mockReturnValue(true),
-                updateBestDifficultyIfHigher: jest.fn().mockResolvedValue(undefined),
+                getDeclaredJob: jest.fn().mockReturnValue({
+                    validationMode: 'full_template',
+                    job: { version: MockRecording1.BLOCK_TEMPLATE.version },
+                }),
             } as any,
+            shareAccountingService as any,
+            redisMessagingService as any,
         );
         (client as any).sendFrame = jest.fn((msgType: number, payload: Buffer, extensionType = 0) => {
             sentFrames.push({ msgType, payload, extensionType });
             return Promise.resolve();
         });
 
-        return { client, sentFrames };
+        return {
+            client,
+            sentFrames,
+            bitcoinRpcService,
+            blocksService,
+            notificationService,
+            addressSettingsService,
+            shareAccountingService,
+            redisMessagingService,
+            jobTemplate,
+        };
     }
 });

src/models/StratumV2Client.ts

@@ -7,18 +7,22 @@ import { firstValueFrom, Subscription } from 'rxjs';
 
 import { AddressSettingsService } from '../ORM/address-settings/address-settings.service';
 import { BlocksService } from '../ORM/blocks/blocks.service';
-import { ClientStatisticsService } from '../ORM/client-statistics/client-statistics.service';
 import { ClientEntity } from '../ORM/client/client.entity';
 import { ClientService } from '../ORM/client/client.service';
+import { PayoutSnapshotService } from '../ORM/payout-snapshot/payout-snapshot.service';
+import { ShareAccountingService } from '../ORM/share-accounting/share-accounting.service';
 import { BitcoinRpcService } from '../services/bitcoin-rpc.service';
+import { CustomWorkService } from '../services/custom-work.service';
 import { NotificationService } from '../services/notification.service';
+import { RedisMessagingService } from '../services/redis-messaging.service';
 import { StratumV2Service } from '../services/stratum-v2.service';
 import { IJobTemplate, StratumV1JobsService } from '../services/stratum-v1-jobs.service';
+import { Sv2JobDeclarationRegistryService } from '../services/sv2-job-declaration-registry.service';
 import { patchCoinbasePrefixVarint } from '../utils/coinbase-prefix.utils';
 import { DifficultyUtils } from '../utils/difficulty.utils';
-import { MiningJob } from './MiningJob';
+import { hash256 } from '../utils/hash.utils';
+import { AddressObject, MiningJob } from './MiningJob';
 import { StratumV1ClientStatistics } from './StratumV1ClientStatistics';
-import { TOTAL_EXTRANONCE_SIZE_BYTES } from './stratum.constants';
 import { BufferReader } from './sv2/sv2-binary-codec';
 import {
     SV2_CHANNEL_MSG_FLAG,
@@ -55,8 +59,14 @@ import {
     Sv2SubmitSharesExtended,
 } from './sv2/sv2-extended-messages';
 import { Sv2NoiseSession } from './sv2/sv2-noise';
+import {
+    deserializeSetCustomMiningJob,
+    serializeSetCustomMiningJobError,
+    serializeSetCustomMiningJobSuccess,
+} from './sv2/sv2-jdp-messages';
 
 const DEFAULT_START_DIFFICULTY = 100000;
+const DEFAULT_MIN_DIFFICULTY = 0.001;
 const DEFAULT_TARGET_SHARES_PER_MINUTE = 2;
 const DEFAULT_DIFFICULTY_CHECK_INTERVAL_MS = 60 * 1000;
 const FIXED_STANDARD_EXTRANONCE2 = '0000000000000000';
@@ -74,6 +84,7 @@ interface ExtendedJobData {
     miningJob: MiningJob;
     retiredAt?: number;
     creation: number;
+    workProtocol?: 'pool' | 'sv2_jdp';
 }
 
 interface ChannelState {
@@ -120,6 +131,7 @@ export class StratumV2Client {
     private clientEntity: ClientEntity = null;
     private creatingEntity: Promise<void> = null;
     private readonly firstChunkSummary: string;
+    private workSelectionEnabled = false;
 
     constructor(
         private readonly socket: Socket,
@@ -128,18 +140,22 @@ export class StratumV2Client {
         private readonly stratumV1JobsService: StratumV1JobsService,
         private readonly bitcoinRpcService: BitcoinRpcService,
         private readonly clientService: ClientService,
-        private readonly clientStatisticsService: ClientStatisticsService,
         private readonly notificationService: NotificationService,
         private readonly blocksService: BlocksService,
         private readonly configService: ConfigService,
         private readonly addressSettingsService: AddressSettingsService,
+        private readonly customWorkService: CustomWorkService,
+        private readonly jobDeclarationRegistry: Sv2JobDeclarationRegistryService,
+        private readonly shareAccountingService?: ShareAccountingService,
+        private readonly redisMessagingService?: RedisMessagingService,
+        private readonly payoutSnapshotService?: PayoutSnapshotService,
     ) {
         this.firstChunkSummary = this.describeChunk(firstChunk);
         this.noiseSession = new Sv2NoiseSession(this.stratumV2Service.getNoiseConfig());
         this.sessionDifficulty = this.getInitialDifficulty();
         this.targetSharesPerMinute = this.getTargetSharesPerMinute();
         this.difficultyCheckIntervalMs = this.getDifficultyCheckIntervalMs();
-        this.statistics = new StratumV1ClientStatistics(this.clientStatisticsService);
+        this.statistics = new StratumV1ClientStatistics(this.getMinimumDifficulty());
         this.statistics.targetSubmitShareEveryNSeconds = 60 / this.targetSharesPerMinute;
         this.network = this.getNetwork();
 
@@ -171,6 +187,7 @@ export class StratumV2Client {
         }
         this.channels.clear();
         if (this.clientEntity?.id != null) {
+            await this.redisMessagingService?.removeClientPresence(this.clientEntity.id, this.clientEntity.address);
             await this.clientService.delete(this.clientEntity.id);
         }
     }
@@ -253,6 +270,9 @@ export class StratumV2Client {
             case Sv2MsgType.SUBMIT_SHARES_EXTENDED:
                 await this.handleSubmitSharesExtended(payload);
                 break;
+            case Sv2MsgType.SET_CUSTOM_MINING_JOB:
+                await this.handleSetCustomMiningJob(payload);
+                break;
             case Sv2MsgType.UPDATE_CHANNEL:
                 await this.handleUpdateChannel(payload);
                 break;
@@ -294,6 +314,7 @@ export class StratumV2Client {
         }
 
         const supportedFlags = Sv2MiningSetupFlags.REQUIRES_STANDARD_JOBS
+            | Sv2MiningSetupFlags.REQUIRES_WORK_SELECTION
             | Sv2MiningSetupFlags.REQUIRES_VERSION_ROLLING;
         const unsupportedFlags = message.flags & ~supportedFlags;
         if (unsupportedFlags !== 0) {
@@ -309,6 +330,7 @@ export class StratumV2Client {
         }
 
         const versionRolling = (message.flags & Sv2MiningSetupFlags.REQUIRES_VERSION_ROLLING) !== 0;
+        this.workSelectionEnabled = (message.flags & Sv2MiningSetupFlags.REQUIRES_WORK_SELECTION) !== 0;
         const successFlags = versionRolling ? 0 : Sv2MiningSetupSuccessFlags.REQUIRES_FIXED_VERSION;
         await this.sendFrame(
             Sv2MsgType.SETUP_CONNECTION_SUCCESS,
@@ -354,10 +376,10 @@ export class StratumV2Client {
                 this.targetSharesPerMinute,
             );
             if (Number.isFinite(calculatedDifficulty) && calculatedDifficulty > 0) {
-                channelDifficulty = calculatedDifficulty;
+                channelDifficulty = this.clampDifficulty(calculatedDifficulty);
             }
         }
-        channelDifficulty = DifficultyUtils.clampDifficultyToMaxTarget(channelDifficulty, message.maxTarget);
+        channelDifficulty = this.clampDifficulty(DifficultyUtils.clampDifficultyToMaxTarget(channelDifficulty, message.maxTarget));
         this.sessionDifficulty = channelDifficulty;
 
         const channel: ChannelState = {
@@ -382,6 +404,7 @@ export class StratumV2Client {
         }
 
         await this.ensureClientEntity();
+        this.disableApplicationIdleTimeout();
         await this.sendFrame(
             Sv2MsgType.OPEN_STANDARD_MINING_CHANNEL_SUCCESS,
             serializeOpenStandardMiningChannelSuccess({
@@ -393,10 +416,12 @@ export class StratumV2Client {
             }),
         );
 
+        if (!this.workSelectionEnabled) {
             const jobTemplate = await firstValueFrom(this.stratumV1JobsService.newMiningJob$);
             await this.sendNewMiningJob(channel, jobTemplate, true);
+        }
 
-        if (isFirstChannel) {
+        if (isFirstChannel && !this.workSelectionEnabled) {
             this.subscribeToJobs();
             this.startDifficultyTimer();
         }
@@ -430,14 +455,18 @@ export class StratumV2Client {
 
         const channelId = this.stratumV2Service.getNextChannelId();
         const extranoncePrefix = this.stratumV2Service.allocateExtendedExtranoncePrefix(channelId);
-        const maxMinerExtranonceSize = Math.max(0, TOTAL_EXTRANONCE_SIZE_BYTES - extranoncePrefix.length);
+        const maxMinerExtranonceSize = Math.max(0, this.stratumV2Service.getExtendedTotalExtranonceSize() - extranoncePrefix.length);
         const defaultMinerExtranonceSize = Math.min(
             this.stratumV2Service.getExtendedMinerExtranonceSize(),
             maxMinerExtranonceSize,
         );
-        const extranonceSize = message.minExtranonceSize > 0
+        const requestedMinerExtranonceSize = Math.max(0, message.minExtranonceSize);
-            ? Math.min(message.minExtranonceSize, maxMinerExtranonceSize)
+        const extranonceSize = Math.max(defaultMinerExtranonceSize, requestedMinerExtranonceSize);
-            : defaultMinerExtranonceSize;
+        if (extranonceSize > maxMinerExtranonceSize) {
+            this.stratumV2Service.releaseExtendedExtranoncePrefix(channelId);
+            await this.sendOpenChannelError(message.requestId, 'min-extranonce-size-too-large');
+            return;
+        }
 
         let channelDifficulty = this.sessionDifficulty;
         if (Number.isFinite(message.nominalHashRate) && message.nominalHashRate > 0) {
@@ -446,10 +475,10 @@ export class StratumV2Client {
                 this.targetSharesPerMinute,
             );
             if (Number.isFinite(calculatedDifficulty) && calculatedDifficulty > 0) {
-                channelDifficulty = calculatedDifficulty;
+                channelDifficulty = this.clampDifficulty(calculatedDifficulty);
             }
         }
-        channelDifficulty = DifficultyUtils.clampDifficultyToMaxTarget(channelDifficulty, message.maxTarget);
+        channelDifficulty = this.clampDifficulty(DifficultyUtils.clampDifficultyToMaxTarget(channelDifficulty, message.maxTarget));
         this.sessionDifficulty = channelDifficulty;
 
         const channel: ChannelState = {
@@ -474,6 +503,7 @@ export class StratumV2Client {
         }
 
         await this.ensureClientEntity();
+        this.disableApplicationIdleTimeout();
         await this.sendFrame(
             Sv2MsgType.OPEN_EXTENDED_MINING_CHANNEL_SUCCESS,
             serializeOpenExtendedMiningChannelSuccess({
@@ -486,10 +516,12 @@ export class StratumV2Client {
             }),
         );
 
+        if (!this.workSelectionEnabled) {
             const jobTemplate = await firstValueFrom(this.stratumV1JobsService.newMiningJob$);
             await this.sendNewExtendedMiningJob(channel, jobTemplate, true);
+        }
 
-        if (isFirstChannel) {
+        if (isFirstChannel && !this.workSelectionEnabled) {
             this.subscribeToJobs();
             this.startDifficultyTimer();
         }
@@ -554,7 +586,7 @@ export class StratumV2Client {
         );
 
         channel.acceptedShareCount++;
-        await this.handleAcceptedShare(submission, channel, job, jobTemplate, submissionDifficulty, jobDifficulty);
+        await this.handleAcceptedShare(submission, channel, job, jobTemplate, submissionDifficulty, jobDifficulty, hashBuffer);
     }
 
     private async handleSubmitSharesExtended(payload: Buffer): Promise<void> {
@@ -602,12 +634,12 @@ export class StratumV2Client {
             submission.extranonce,
             extendedJob.coinbaseSuffix,
         ]);
-        let merkleRoot = bitcoinjs.crypto.hash256(coinbaseTxBytes);
+        let merkleRoot = hash256(coinbaseTxBytes);
         const merklePair = Buffer.alloc(64);
         for (const sibling of extendedJob.merklePath) {
             merklePair.set(merkleRoot, 0);
             merklePair.set(sibling, 32);
-            merkleRoot = bitcoinjs.crypto.hash256(merklePair);
+            merkleRoot = hash256(merklePair);
         }
 
         const header = this.buildHeader(
@@ -644,10 +676,134 @@ export class StratumV2Client {
 
         channel.acceptedShareCount++;
         let updatedJobBlock: bitcoinjs.Block = null;
-        if (submissionDifficulty >= extendedJob.jobTemplate.blockData.networkDifficulty) {
+        let blockCandidateResult: string | null = null;
+        if (DifficultyUtils.meetsTarget(
+            hashBuffer,
+            DifficultyUtils.difficultyToTarget(extendedJob.jobTemplate.blockData.networkDifficulty),
+        )) {
+            if (extendedJob.workProtocol === 'sv2_jdp') {
+                blockCandidateResult = 'sv2-jdp-client-submit-expected';
+            } else {
                 updatedJobBlock = this.reconstructExtendedBlock(extendedJob, submission, merkleRoot, channel.extranoncePrefix);
             }
-        await this.recordAcceptedShare(submissionDifficulty, jobDifficulty, extendedJob.jobTemplate, updatedJobBlock);
+        }
+        await this.recordAcceptedShare(submissionDifficulty, jobDifficulty, extendedJob.jobTemplate, updatedJobBlock, {
+            jobId: submission.jobId.toString(16),
+            nonce: submission.nonce,
+            ntime: submission.ntime,
+            version: submission.version,
+            extraNonce2: submission.extranonce.toString('hex'),
+        }, {
+            workProtocol: extendedJob.workProtocol ?? 'pool',
+            blockCandidateResult,
+        });
+    }
+
+    private async handleSetCustomMiningJob(payload: Buffer): Promise<void> {
+        const msg = deserializeSetCustomMiningJob(new BufferReader(payload));
+        if (!this.workSelectionEnabled) {
+            await this.sendFrame(
+                Sv2MsgType.SET_CUSTOM_MINING_JOB_ERROR,
+                serializeSetCustomMiningJobError({
+                    channelId: msg.channelId,
+                    requestId: msg.requestId,
+                    errorCode: 'work-selection-not-negotiated',
+                }),
+            );
+            return;
+        }
+        const channel = this.channels.get(msg.channelId);
+        if (channel == null) {
+            await this.sendFrame(
+                Sv2MsgType.SET_CUSTOM_MINING_JOB_ERROR,
+                serializeSetCustomMiningJobError({
+                    channelId: msg.channelId,
+                    requestId: msg.requestId,
+                    errorCode: 'invalid-channel-id',
+                }),
+            );
+            return;
+        }
+        if (channel.channelType !== 'extended') {
+            await this.sendFrame(
+                Sv2MsgType.SET_CUSTOM_MINING_JOB_ERROR,
+                serializeSetCustomMiningJobError({
+                    channelId: msg.channelId,
+                    requestId: msg.requestId,
+                    errorCode: 'invalid-channel-type',
+                }),
+            );
+            return;
+        }
+        const declaredJob = this.jobDeclarationRegistry?.getDeclaredJob(msg.token);
+        if (declaredJob == null || declaredJob.validationMode !== 'full_template') {
+            await this.sendFrame(
+                Sv2MsgType.SET_CUSTOM_MINING_JOB_ERROR,
+                serializeSetCustomMiningJobError({
+                    channelId: msg.channelId,
+                    requestId: msg.requestId,
+                    errorCode: 'invalid-mining-job-token',
+                }),
+            );
+            return;
+        }
+        if (declaredJob.job.version !== msg.version) {
+            await this.sendFrame(
+                Sv2MsgType.SET_CUSTOM_MINING_JOB_ERROR,
+                serializeSetCustomMiningJobError({
+                    channelId: msg.channelId,
+                    requestId: msg.requestId,
+                    errorCode: 'declared-job-mismatch',
+                }),
+            );
+            return;
+        }
+
+        const latestTemplate = await firstValueFrom(this.stratumV1JobsService.newMiningJob$);
+        const jobIdHex = this.stratumV1JobsService.getNextId();
+        const jobId = parseInt(jobIdHex, 16);
+        const split = this.customWorkService.buildSv2CoinbaseSplit(
+            msg,
+            channel.extranoncePrefix.length + channel.extranonceSize,
+        );
+        const placeholderJob = new MiningJob(
+            this.network,
+            jobIdHex,
+            this.getPayoutInformation(latestTemplate, this.address),
+            latestTemplate,
+        );
+        this.stratumV1JobsService.addJob(placeholderJob);
+
+        channel.jobIdToDifficulty.set(jobId, channel.sessionDifficulty);
+        channel.extendedJobs.set(jobId, {
+            coinbasePrefix: split.coinbasePrefix,
+            coinbaseSuffix: split.coinbaseSuffix,
+            merklePath: msg.merklePath.map(branch => Buffer.from(branch)),
+            prevHash: Buffer.from(msg.prevHash),
+            nBits: msg.nBits,
+            minNtime: msg.minNtime,
+            jobTemplate: {
+                ...latestTemplate,
+                block: Object.assign(new bitcoinjs.Block(), latestTemplate.block, {
+                    prevHash: Buffer.from(msg.prevHash),
+                    bits: msg.nBits,
+                    version: msg.version,
+                    timestamp: msg.minNtime,
+                }),
+            },
+            miningJob: placeholderJob,
+            creation: Date.now(),
+            workProtocol: 'sv2_jdp',
+        });
+
+        await this.sendFrame(
+            Sv2MsgType.SET_CUSTOM_MINING_JOB_SUCCESS,
+            serializeSetCustomMiningJobSuccess({
+                channelId: msg.channelId,
+                requestId: msg.requestId,
+                jobId,
+            }),
+        );
     }
 
     private async handleAcceptedShare(
@@ -657,9 +813,13 @@ export class StratumV2Client {
         jobTemplate: IJobTemplate,
         submissionDifficulty: number,
         jobDifficulty: number,
+        hashBuffer: Buffer,
     ): Promise<void> {
         let updatedJobBlock: bitcoinjs.Block = null;
-        if (submissionDifficulty >= jobTemplate.blockData.networkDifficulty) {
+        if (DifficultyUtils.meetsTarget(
+            hashBuffer,
+            DifficultyUtils.difficultyToTarget(jobTemplate.blockData.networkDifficulty),
+        )) {
             const versionMask = submission.version ^ jobTemplate.block.version;
             updatedJobBlock = job.copyAndUpdateBlock(
                 jobTemplate,
@@ -671,7 +831,13 @@ export class StratumV2Client {
             );
         }
 
-        await this.recordAcceptedShare(submissionDifficulty, jobDifficulty, jobTemplate, updatedJobBlock);
+        await this.recordAcceptedShare(submissionDifficulty, jobDifficulty, jobTemplate, updatedJobBlock, {
+            jobId: job.jobId,
+            nonce: submission.nonce,
+            ntime: submission.ntime,
+            version: submission.version,
+            extraNonce2: FIXED_STANDARD_EXTRANONCE2,
+        });
     }
 
     private async recordAcceptedShare(
@@ -679,35 +845,67 @@ export class StratumV2Client {
         jobDifficulty: number,
         jobTemplate: IJobTemplate,
         updatedJobBlock: bitcoinjs.Block | null,
+        share: { jobId: string; nonce: number; ntime: number; version: number; extraNonce2: string },
+        metadata: { workProtocol?: 'pool' | 'sv2_jdp'; blockCandidateResult?: string | null } = {},
     ): Promise<void> {
         await this.ensureClientEntity();
 
+        let blockSubmissionResult: string = metadata.blockCandidateResult ?? null;
         if (updatedJobBlock != null) {
             console.log(`[SV2 ${this.sessionId}] BLOCK FOUND at height ${jobTemplate.blockData.height}`);
             const blockHex = updatedJobBlock.toHex(false);
-            const result = await this.bitcoinRpcService.SUBMIT_BLOCK(blockHex);
+            blockSubmissionResult = await this.bitcoinRpcService.SUBMIT_BLOCK(blockHex);
             await this.blocksService.save({
                 height: jobTemplate.blockData.height,
                 minerAddress: this.address,
                 worker: this.workerName,
                 sessionId: this.sessionId,
                 blockData: blockHex,
+                blockSubmissionResult,
+                payoutSnapshotId: jobTemplate.blockData.payoutSnapshotId ?? null,
+            });
+            await this.payoutSnapshotService?.finalizeSnapshotForBlock({
+                payoutSnapshotId: jobTemplate.blockData.payoutSnapshotId,
+                blockHeight: jobTemplate.blockData.height,
+                blockSubmissionResult,
             });
             await this.notificationService.notifySubscribersBlockFound(
                 this.address,
                 jobTemplate.blockData.height,
                 updatedJobBlock,
-                result,
+                blockSubmissionResult,
             );
-            if (result == null) {
+            if (this.isSuccessfulBlockSubmission(blockSubmissionResult)) {
                 await this.addressSettingsService.resetBestDifficultyAndShares();
             }
         }
 
+        await this.shareAccountingService?.recordAcceptedShare({
+            protocol: metadata.workProtocol === 'sv2_jdp' ? 'sv2_jdp' : 'sv2',
+            workSource: metadata.workProtocol === 'sv2_jdp' ? 'miner_template' : 'pool_template',
+            workProtocol: metadata.workProtocol ?? 'pool',
+            address: this.address,
+            clientName: this.workerName,
+            sessionId: this.sessionId,
+            clientId: this.clientEntity.id,
+            jobId: share.jobId,
+            jobTemplateId: jobTemplate.blockData.id,
+            blockHeight: jobTemplate.blockData.height,
+            creditedDifficulty: jobDifficulty,
+            submissionDifficulty,
+            networkDifficulty: jobTemplate.blockData.networkDifficulty,
+            nonce: share.nonce,
+            ntime: share.ntime,
+            version: share.version,
+            extraNonce2: share.extraNonce2,
+            isBlockCandidate: updatedJobBlock != null || metadata.blockCandidateResult != null,
+            blockSubmissionResult,
+        });
         await this.statistics.addShares(this.clientEntity, jobDifficulty);
         const now = new Date();
-        this.clientService.heartbeatBulkAsync(this.clientEntity.id, this.statistics.hashRate, now);
         this.clientEntity.updatedAt = now;
+        this.clientEntity.hashRate = this.statistics.hashRate;
+        await this.updateClientPresence(now);
 
         if (submissionDifficulty > this.clientEntity.bestDifficulty) {
             await this.clientService.updateBestDifficultyIfHigher(this.clientEntity.id, submissionDifficulty);
@@ -717,6 +915,7 @@ export class StratumV2Client {
                 submissionDifficulty,
                 this.userAgent,
             );
+            await this.updateClientPresence(new Date());
         }
     }
 
@@ -733,7 +932,7 @@ export class StratumV2Client {
         const coinbaseTx = extendedJob.miningJob.cloneCoinbaseTransaction();
         const script = coinbaseTx.ins[0].script;
         coinbaseTx.ins[0].script = Buffer.concat([
-            script.subarray(0, script.length - TOTAL_EXTRANONCE_SIZE_BYTES),
+            script.subarray(0, script.length - (extranoncePrefix.length + submission.extranonce.length)),
             extranoncePrefix,
             submission.extranonce,
         ]);
@@ -759,10 +958,10 @@ export class StratumV2Client {
                 this.targetSharesPerMinute,
             );
             if (Number.isFinite(nextDifficulty) && nextDifficulty > 0) {
-                channel.sessionDifficulty = DifficultyUtils.clampDifficultyToMaxTarget(
+                channel.sessionDifficulty = this.clampDifficulty(DifficultyUtils.clampDifficultyToMaxTarget(
                     nextDifficulty,
                     channel.declaredMaxTarget,
-                );
+                ));
                 await this.sendSetTarget(channel);
             }
         }
@@ -838,17 +1037,17 @@ export class StratumV2Client {
     }
 
     private async checkDifficulty(): Promise<void> {
-        const targetDiff = this.statistics.getSuggestedDifficulty(this.sessionDifficulty);
+        const targetDiff = this.clampDifficulty(this.statistics.getSuggestedDifficulty(this.sessionDifficulty));
         if (targetDiff == null || targetDiff === this.sessionDifficulty || !Number.isFinite(targetDiff)) {
             return;
         }
 
         this.sessionDifficulty = targetDiff;
         for (const channel of this.channels.values()) {
-            channel.sessionDifficulty = DifficultyUtils.clampDifficultyToMaxTarget(
+            channel.sessionDifficulty = this.clampDifficulty(DifficultyUtils.clampDifficultyToMaxTarget(
                 targetDiff,
                 channel.declaredMaxTarget,
-            );
+            ));
             await this.sendSetTarget(channel);
         }
 
@@ -879,7 +1078,7 @@ export class StratumV2Client {
         const job = new MiningJob(
             this.network,
             jobIdHex,
-            [{ address: this.address, percent: 100 }],
+            this.getPayoutInformation(jobTemplate, this.address),
             jobTemplate,
         );
         this.stratumV1JobsService.addJob(job);
@@ -933,7 +1132,7 @@ export class StratumV2Client {
         const job = new MiningJob(
             this.network,
             jobIdHex,
-            [{ address: this.address, percent: 100 }],
+            this.getPayoutInformation(jobTemplate, this.address),
             jobTemplate,
         );
         this.stratumV1JobsService.addJob(job);
@@ -1085,12 +1284,35 @@ export class StratumV2Client {
                     startTime: new Date(),
                     bestDifficulty: 0,
                 });
+                await this.updateClientPresence(new Date());
             })();
         }
 
         await this.creatingEntity;
     }
 
+    private async updateClientPresence(lastSeen: Date): Promise<void> {
+        if (this.clientEntity == null) {
+            return;
+        }
+
+        try {
+            await this.redisMessagingService?.setClientPresence({
+                clientId: this.clientEntity.id,
+                address: this.clientEntity.address,
+                clientName: this.clientEntity.clientName,
+                sessionId: this.clientEntity.sessionId,
+                userAgent: this.clientEntity.userAgent,
+                startTime: new Date(this.clientEntity.startTime).toISOString(),
+                lastSeen: lastSeen.toISOString(),
+                hashRate: this.statistics.hashRate,
+                bestDifficulty: Number(this.clientEntity.bestDifficulty ?? 0),
+            });
+        } catch (error) {
+            console.error(`Failed to update SV2 client presence: ${error.message}`);
+        }
+    }
+
     private parseUserIdentity(userIdentity: string): { address: string; workerName: string } {
         const parts = userIdentity.split('.');
         const rawAddress = parts[0] ?? '';
@@ -1130,7 +1352,35 @@ export class StratumV2Client {
             ?? this.configService.get<string>('STRATUM_START_DIFFICULTY')
             ?? '',
         );
-        return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_START_DIFFICULTY;
+        const difficulty = Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_START_DIFFICULTY;
+        return this.clampDifficulty(difficulty);
+    }
+
+    private getMinimumDifficulty(): number {
+        return this.getConfiguredMinimumDifficulty() ?? DEFAULT_MIN_DIFFICULTY;
+    }
+
+    private getConfiguredMinimumDifficulty(): number | null {
+        const configured = parseFloat(
+            this.configService.get<string>('STRATUM_MIN_DIFFICULTY')
+            ?? process.env.STRATUM_MIN_DIFFICULTY
+            ?? '',
+        );
+        return Number.isFinite(configured) && configured > 0 ? configured : null;
+    }
+
+    private clampDifficulty(difficulty: number | null): number | null {
+        if (difficulty == null || !Number.isFinite(difficulty)) {
+            return null;
+        }
+        const configuredMinimum = this.getConfiguredMinimumDifficulty();
+        return configuredMinimum == null ? difficulty : Math.max(difficulty, configuredMinimum);
+    }
+
+    private disableApplicationIdleTimeout(): void {
+        if (typeof this.socket.setTimeout === 'function') {
+            this.socket.setTimeout(0);
+        }
     }
 
     private getTargetSharesPerMinute(): number {
@@ -1143,6 +1393,18 @@ export class StratumV2Client {
         return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_DIFFICULTY_CHECK_INTERVAL_MS;
     }
 
+    private getPayoutInformation(jobTemplate: IJobTemplate, fallbackAddress: string): AddressObject[] {
+        if (this.configService.get('PAYOUT_COINBASE_MODE') === 'snapshot' && jobTemplate.blockData.payoutOutputs?.length > 0) {
+            return jobTemplate.blockData.payoutOutputs;
+        }
+
+        return [{ address: fallbackAddress, percent: 100 }];
+    }
+
+    private isSuccessfulBlockSubmission(result?: string | null): boolean {
+        return result == null || result === 'SUCCESS!';
+    }
+
     private getNetwork(): bitcoinjs.networks.Network {
         const networkConfig = this.configService.get('NETWORK');
         if (networkConfig === 'mainnet') {

src/models/bitcoin-rpc/IBlockTemplate.ts

@@ -7,6 +7,13 @@ export interface IBlockTemplateTx {
     sigops: number,                        // (numeric) total SigOps cost, as counted for purposes of block limits; if key is not present, sigop cost is unknown and clients MUST NOT assume it is zero
     weight: number                         // (numeric) total transaction weight, as counted for purposes of block limits
 }
+
+export interface IBlockTemplatePayoutOutput {
+    address: string;
+    percent?: number;
+    amountSats?: number;
+}
+
 export interface IBlockTemplate {
     // (json object)
     version: number;                       // (numeric) The preferred block version
@@ -35,5 +42,7 @@ export interface IBlockTemplate {
     height: number,                        // (numeric) The height of the next block
     default_witness_commitment: string     // (string, optional) a valid witness commitment for the unmodified block template
     capabilities: string[]
+    payoutSnapshotId?: string;
+    payoutOutputs?: IBlockTemplatePayoutOutput[];
 
 }

src/models/datum/datum-codec.spec.ts

@@ -0,0 +1,257 @@
+import {
+    DATUM_INITIAL_HEADER_KEY,
+    DATUM_EXTRANONCE_SIZE,
+    DatumFrameReader,
+    DatumMiningCommand,
+    DatumProtocolCommand,
+    DatumShareResponseStatus,
+    datumHeaderXorFeedback,
+    decodeDatumHeader,
+    deserializeDatumCoinbaserFetch,
+    deserializeDatumJobValidationResponse,
+    deserializeDatumMiningCommand,
+    deserializeDatumPowSubmit,
+    encodeDatumFrame,
+    encodeDatumHeader,
+    serializeDatumJobValidationFullTransactionBlobRequest,
+    serializeDatumJobValidationFullTransactionsRequest,
+    serializeDatumJobValidationShortTxIdsRequest,
+    serializeDatumCoinbaserFetchResponse,
+    serializeDatumMiningCommand,
+    serializeDatumShareResponse,
+} from './datum-codec';
+
+describe('datum-codec', () => {
+    it('round-trips DATUM packed headers with XOR key', () => {
+        const encoded = encodeDatumHeader({
+            cmdLen: 1234,
+            reserved: 0,
+            isSigned: true,
+            isEncryptedPubkey: false,
+            isEncryptedChannel: true,
+            protoCmd: DatumProtocolCommand.MINING,
+        }, DATUM_INITIAL_HEADER_KEY);
+
+        expect(decodeDatumHeader(encoded, DATUM_INITIAL_HEADER_KEY)).toEqual({
+            cmdLen: 1234,
+            reserved: 0,
+            isSigned: true,
+            isEncryptedPubkey: false,
+            isEncryptedChannel: true,
+            protoCmd: DatumProtocolCommand.MINING,
+        });
+    });
+
+    it('matches the DATUM header feedback function for stable inputs', () => {
+        expect(datumHeaderXorFeedback(0).toString(16)).toBe('74a55cf6');
+        expect(datumHeaderXorFeedback(0xdc871829).toString(16)).toBe('88e1697d');
+    });
+
+    it('splits framed DATUM payloads', () => {
+        const first = encodeDatumFrame({
+            header: {
+                cmdLen: 0,
+                reserved: 0,
+                isSigned: false,
+                isEncryptedPubkey: false,
+                isEncryptedChannel: true,
+                protoCmd: DatumProtocolCommand.MINING,
+            },
+            payload: serializeDatumMiningCommand(DatumMiningCommand.TEMPLATE_REFRESH),
+        });
+        const second = encodeDatumFrame({
+            header: {
+                cmdLen: 0,
+                reserved: 0,
+                isSigned: false,
+                isEncryptedPubkey: false,
+                isEncryptedChannel: true,
+                protoCmd: DatumProtocolCommand.MINING,
+            },
+            payload: serializeDatumMiningCommand(DatumMiningCommand.FETCH_COINBASER, Buffer.alloc(8)),
+        }, datumHeaderXorFeedback(DATUM_INITIAL_HEADER_KEY));
+
+        const frames = new DatumFrameReader().feed(Buffer.concat([first, second]));
+        expect(frames).toHaveLength(2);
+        expect(deserializeDatumMiningCommand(frames[0].payload).command).toBe(DatumMiningCommand.TEMPLATE_REFRESH);
+        expect(deserializeDatumMiningCommand(frames[1].payload).command).toBe(DatumMiningCommand.FETCH_COINBASER);
+    });
+
+    it('serializes coinbaser fetch responses', () => {
+        const response = serializeDatumCoinbaserFetchResponse(50n, [
+            { value: 50n, scriptPubKey: Buffer.from('6a', 'hex') },
+        ]);
+        const mining = deserializeDatumMiningCommand(response);
+        expect(mining.command).toBe(DatumMiningCommand.FETCH_COINBASER_RESPONSE);
+        expect(mining.body.readBigUInt64LE(0)).toBe(50n);
+        expect(mining.body.readUInt32LE(8)).toBe(11);
+    });
+
+    it('deserializes coinbaser fetch requests', () => {
+        const payload = Buffer.alloc(8);
+        payload.writeBigUInt64LE(123n, 0);
+        expect(deserializeDatumCoinbaserFetch(payload)).toEqual({ rewardValue: 123n });
+    });
+
+    it('deserializes fixed DATUM POW submissions', () => {
+        const username = Buffer.from('bc1ptest.worker\0', 'utf8');
+        const extranonce = Buffer.from('000102030405060708090a0b', 'hex');
+        const payload = Buffer.alloc(17 + DATUM_EXTRANONCE_SIZE);
+        payload[0] = 7;
+        payload[1] = 1;
+        payload[2] = 0x01;
+        payload[3] = 4;
+        payload.writeUInt32LE(100, 4);
+        payload.writeUInt32LE(200, 8);
+        payload.writeUInt32LE(0x20000000, 12);
+        payload[16] = DATUM_EXTRANONCE_SIZE;
+        extranonce.copy(payload, 17);
+        const parsed = deserializeDatumPowSubmit(Buffer.concat([
+            payload,
+            username,
+            Buffer.alloc(4),
+            Buffer.from([0xfe]),
+        ]));
+
+        expect(parsed.jobId).toBe(7);
+        expect(parsed.coinbaseId).toBe(1);
+        expect(parsed.isBlock).toBe(true);
+        expect(parsed.extranonce).toEqual(extranonce);
+        expect(parsed.username).toBe('bc1ptest.worker');
+    });
+
+    it('deserializes cached DATUM POW context sections', () => {
+        const username = Buffer.from('bc1ptest.worker\0', 'utf8');
+        const extranonce = Buffer.from('000102030405060708090a0b', 'hex');
+        const base = Buffer.alloc(17 + DATUM_EXTRANONCE_SIZE);
+        base[0] = 3;
+        base[1] = 2;
+        base[2] = 0;
+        base[3] = 0x12;
+        base.writeUInt32LE(100, 4);
+        base.writeUInt32LE(200, 8);
+        base.writeUInt32LE(0x20000000, 12);
+        base[16] = DATUM_EXTRANONCE_SIZE;
+        extranonce.copy(base, 17);
+
+        const templateSection = Buffer.concat([
+            Buffer.from([0x01]),
+            Buffer.alloc(32, 0xaa),
+            Buffer.from([0x09, 0x00]),
+            Buffer.from('ffff7f20', 'hex'),
+            Buffer.from([7]),
+            Buffer.from('64000000', 'hex'),
+            Buffer.from('0100000000000000', 'hex'),
+            Buffer.from('02000000', 'hex'),
+            Buffer.from('03000000', 'hex'),
+            Buffer.from('04000000', 'hex'),
+            Buffer.from('05000000', 'hex'),
+            Buffer.from([1]),
+            Buffer.alloc(32, 0xbb),
+        ]);
+        const coinbaseSection = Buffer.concat([
+            Buffer.from([0x02, 2]),
+            Buffer.from([0x02, 0x00]),
+            Buffer.from([0x03, 0x00]),
+            Buffer.from('abcd', 'hex'),
+            Buffer.from('010203', 'hex'),
+        ]);
+
+        const parsed = deserializeDatumPowSubmit(Buffer.concat([
+            base,
+            username,
+            Buffer.alloc(4),
+            templateSection,
+            coinbaseSection,
+            Buffer.from([0xfe]),
+        ]));
+
+        expect(parsed.jobId).toBe(3);
+        expect(parsed.coinbaseId).toBe(2);
+        expect(parsed.targetByte).toBe(0x12);
+        expect(parsed.prevBlockHash?.equals(Buffer.alloc(32, 0xaa))).toBe(true);
+        expect(parsed.targetByteIndex).toBe(9);
+        expect(parsed.nBits?.toString('hex')).toBe('ffff7f20');
+        expect(parsed.height).toBe(100);
+        expect(parsed.merkleBranches?.[0].equals(Buffer.alloc(32, 0xbb))).toBe(true);
+        expect(parsed.coinbasePairs.get(2)?.coinb1.toString('hex')).toBe('abcd');
+        expect(parsed.coinbasePairs.get(2)?.coinb2.toString('hex')).toBe('010203');
+    });
+
+    it('rejects DATUM POW submissions with non-standard extranonce sizes', () => {
+        const payload = Buffer.alloc(18);
+        payload[16] = 1;
+        payload[17] = 0xaa;
+
+        expect(() => deserializeDatumPowSubmit(payload)).toThrow('Unsupported DATUM extranonce size 1');
+    });
+
+    it('serializes share responses', () => {
+        const response = serializeDatumShareResponse({
+            status: DatumShareResponseStatus.ACCEPTED,
+            reasonCode: 0,
+            nonce: 123,
+            targetByte: 4,
+            jobId: 7,
+        });
+        expect(response.toString('hex')).toBe('8f5000007b0000000407');
+    });
+
+    it('serializes DATUM job validation requests', () => {
+        expect(serializeDatumJobValidationShortTxIdsRequest(7).toString('hex')).toBe('501007');
+        expect(serializeDatumJobValidationFullTransactionBlobRequest(7).toString('hex')).toBe('501207');
+        expect(serializeDatumJobValidationFullTransactionsRequest(7, [1, 258]).toString('hex')).toBe('501107020001000201');
+    });
+
+    it('deserializes DATUM short transaction ID validation responses', () => {
+        const payload = Buffer.concat([
+            Buffer.from([0x90, 7, 0x01]),
+            Buffer.from('0200', 'hex'),
+            Buffer.from('010203040506', 'hex'),
+            Buffer.from('111213141516', 'hex'),
+            Buffer.alloc(32, 0xaa),
+            Buffer.from([0xfe, 0x00, 0x00]),
+        ]);
+
+        const parsed = deserializeDatumJobValidationResponse(payload);
+        expect(parsed.kind).toBe('short-txids');
+        expect(parsed.jobId).toBe(7);
+        expect(parsed.status).toBe(1);
+        expect(parsed.transactionCount).toBe(2);
+        if (parsed.kind !== 'short-txids') {
+            throw new Error(`Unexpected DATUM validation response kind ${parsed.kind}`);
+        }
+        expect(parsed.shortTxIds.map(id => id.toString('hex'))).toEqual(['010203040506', '111213141516']);
+        expect(parsed.crosscheck?.equals(Buffer.alloc(32, 0xaa))).toBe(true);
+    });
+
+    it('deserializes DATUM full transaction blob validation responses', () => {
+        const tx = Buffer.from(
+            '0100000001'
+            + '0000000000000000000000000000000000000000000000000000000000000000'
+            + 'ffffffff00ffffffff'
+            + '01000000000000000000'
+            + '00000000',
+            'hex',
+        );
+        const txSize = Buffer.alloc(3);
+        txSize.writeUIntLE(tx.length, 0, 3);
+        const payload = Buffer.concat([
+            Buffer.from([0x92, 9, 0x01]),
+            Buffer.from('0100', 'hex'),
+            txSize,
+            tx,
+            Buffer.from([0xfe]),
+        ]);
+
+        const parsed = deserializeDatumJobValidationResponse(payload);
+        expect(parsed.kind).toBe('full-transaction-blob');
+        expect(parsed.jobId).toBe(9);
+        expect(parsed.status).toBe(1);
+        expect(parsed.transactionCount).toBe(1);
+        if (parsed.kind !== 'full-transaction-blob') {
+            throw new Error(`Unexpected DATUM validation response kind ${parsed.kind}`);
+        }
+        expect(parsed.transactions[0]).toEqual(tx);
+    });
+});

src/models/datum/datum-codec.ts

@@ -0,0 +1,506 @@
+import { BufferReader, BufferWriter } from '../sv2/sv2-binary-codec';
+
+export const DATUM_PROTOCOL_VERSION = 'v0.4.1-beta';
+export const DATUM_INITIAL_HEADER_KEY = 0xdc871829;
+export const DATUM_MAX_PAYLOAD_SIZE = 4194304;
+export const DATUM_MAX_JOBS = 8;
+export const DATUM_EXTRANONCE_SIZE = 12;
+
+export enum DatumProtocolCommand {
+    PING = 0x01,
+    HANDSHAKE_INIT = 0x01,
+    HANDSHAKE_RESPONSE = 0x02,
+    MINING = 0x05,
+}
+
+export enum DatumMiningCommand {
+    FETCH_COINBASER = 0x10,
+    FETCH_COINBASER_RESPONSE = 0x11,
+    SUBMIT_POW = 0x27,
+    JOB_VALIDATION = 0x50,
+    SHARE_RESPONSE = 0x8f,
+    CLIENT_CONFIGURE = 0x99,
+    TEMPLATE_REFRESH = 0xf9,
+}
+
+export enum DatumJobValidationCommand {
+    REQUEST_SHORT_TX_IDS = 0x10,
+    REQUEST_FULL_TRANSACTIONS = 0x11,
+    REQUEST_FULL_TRANSACTION_BLOB = 0x12,
+    SHORT_TX_IDS_RESPONSE = 0x90,
+    FULL_TRANSACTIONS_RESPONSE = 0x91,
+    FULL_TRANSACTION_BLOB_RESPONSE = 0x92,
+}
+
+export enum DatumJobValidationStatus {
+    SUCCESS = 0x01,
+}
+
+export enum DatumShareResponseStatus {
+    ACCEPTED = 0x50,
+    ACCEPTED_TENTATIVE = 0x55,
+    REJECTED = 0x66,
+}
+
+export enum DatumRejectReason {
+    BAD_JOB_ID = 10,
+    BAD_COINBASE_ID = 11,
+    BAD_EXTRANONCE_SIZE = 12,
+    BAD_TARGET = 13,
+    BAD_USERNAME = 14,
+    BAD_COINBASER_ID = 15,
+    BAD_MERKLE_COUNT = 16,
+    BAD_COINBASE_TOO_LARGE = 17,
+    COINBASE_MISSING = 18,
+    TARGET_MISMATCH = 19,
+    HIGH_HASH = 21,
+    BAD_NTIME = 23,
+    BAD_VERSION = 24,
+    STALE_BLOCK = 25,
+    DUPLICATE_WORK = 29,
+    OTHER = 30,
+}
+
+export interface DatumHeader {
+    cmdLen: number;
+    reserved: number;
+    isSigned: boolean;
+    isEncryptedPubkey: boolean;
+    isEncryptedChannel: boolean;
+    protoCmd: number;
+}
+
+export interface DatumFrame {
+    header: DatumHeader;
+    payload: Buffer;
+}
+
+export interface DatumCoinbaserFetch {
+    rewardValue: bigint;
+}
+
+export interface DatumPayoutOutput {
+    value: bigint;
+    scriptPubKey: Buffer;
+}
+
+export interface DatumPowSubmit {
+    jobId: number;
+    coinbaseId: number;
+    isBlock: boolean;
+    subsidyOnly: boolean;
+    quickDiff: boolean;
+    targetByte: number;
+    ntime: number;
+    nonce: number;
+    version: number;
+    extranonce: Buffer;
+    username: string;
+    reserved: Buffer;
+    prevBlockHash?: Buffer;
+    targetByteIndex?: number;
+    nBits?: Buffer;
+    coinbaserId?: number;
+    height?: number;
+    coinbaseValue?: bigint;
+    transactionCount?: number;
+    totalWeight?: number;
+    totalSize?: number;
+    totalSigops?: number;
+    merkleBranches?: Buffer[];
+    coinbasePairs: Map<number, { coinb1: Buffer; coinb2: Buffer }>;
+    subsidyOnlyCoinbase?: { coinb1: Buffer; coinb2: Buffer };
+}
+
+export interface DatumShortTxIdsResponse {
+    kind: 'short-txids';
+    jobId: number;
+    status: number;
+    transactionCount: number;
+    shortTxIds: Buffer[];
+    crosscheck: Buffer | null;
+}
+
+export interface DatumFullTransactionsResponse {
+    kind: 'full-transactions';
+    jobId: number;
+    status: number;
+    transactionCount: number;
+    transactions: Buffer[];
+}
+
+export interface DatumFullTransactionBlobResponse {
+    kind: 'full-transaction-blob';
+    jobId: number;
+    status: number;
+    transactionCount: number;
+    transactions: Buffer[];
+}
+
+export type DatumJobValidationResponse =
+    | DatumShortTxIdsResponse
+    | DatumFullTransactionsResponse
+    | DatumFullTransactionBlobResponse;
+
+export function encodeDatumHeader(header: DatumHeader, xorKey = 0): Buffer {
+    if (header.cmdLen < 0 || header.cmdLen > DATUM_MAX_PAYLOAD_SIZE - 1) {
+        throw new RangeError(`DATUM payload length ${header.cmdLen} exceeds protocol limit`);
+    }
+
+    let raw = header.cmdLen & 0x3fffff;
+    raw |= (header.reserved & 0x03) << 22;
+    raw |= (header.isSigned ? 1 : 0) << 24;
+    raw |= (header.isEncryptedPubkey ? 1 : 0) << 25;
+    raw |= (header.isEncryptedChannel ? 1 : 0) << 26;
+    raw |= (header.protoCmd & 0x1f) << 27;
+
+    const out = Buffer.alloc(4);
+    out.writeUInt32LE((raw ^ xorKey) >>> 0, 0);
+    return out;
+}
+
+export function decodeDatumHeader(input: Buffer, xorKey = 0): DatumHeader {
+    if (input.length < 4) {
+        throw new RangeError('DATUM header requires 4 bytes');
+    }
+    const raw = (input.readUInt32LE(0) ^ xorKey) >>> 0;
+    return {
+        cmdLen: raw & 0x3fffff,
+        reserved: (raw >>> 22) & 0x03,
+        isSigned: ((raw >>> 24) & 0x01) !== 0,
+        isEncryptedPubkey: ((raw >>> 25) & 0x01) !== 0,
+        isEncryptedChannel: ((raw >>> 26) & 0x01) !== 0,
+        protoCmd: (raw >>> 27) & 0x1f,
+    };
+}
+
+export function datumHeaderXorFeedback(input: number): number {
+    let h = 0xb10cfeed >>> 0;
+    let k = input >>> 0;
+    k = Math.imul(k, 0xcc9e2d51) >>> 0;
+    k = (((k << 15) >>> 0) | (k >>> 17)) >>> 0;
+    k = Math.imul(k, 0x1b873593) >>> 0;
+    h = (h ^ k) >>> 0;
+    h = (((h << 13) >>> 0) | (h >>> 19)) >>> 0;
+    h = (Math.imul(h, 5) + 0xe6546b64) >>> 0;
+    h = (h ^ 4) >>> 0;
+    h = (h ^ (h >>> 16)) >>> 0;
+    h = Math.imul(h, 0x85ebca6b) >>> 0;
+    h = (h ^ (h >>> 13)) >>> 0;
+    h = Math.imul(h, 0xc2b2ae35) >>> 0;
+    h = (h ^ (h >>> 16)) >>> 0;
+    return h >>> 0;
+}
+
+export class DatumFrameReader {
+    private buffer = Buffer.alloc(0);
+
+    constructor(private headerXorKey = DATUM_INITIAL_HEADER_KEY) {}
+
+    public setHeaderXorKey(headerXorKey: number): void {
+        this.headerXorKey = headerXorKey >>> 0;
+    }
+
+    public feed(data: Buffer): DatumFrame[] {
+        this.buffer = Buffer.concat([this.buffer, data]);
+        const frames: DatumFrame[] = [];
+
+        while (this.buffer.length >= 4) {
+            const header = decodeDatumHeader(this.buffer.subarray(0, 4), this.headerXorKey);
+            if (header.cmdLen > DATUM_MAX_PAYLOAD_SIZE) {
+                throw new RangeError(`DATUM payload length ${header.cmdLen} exceeds protocol limit`);
+            }
+            if (this.buffer.length < 4 + header.cmdLen) {
+                break;
+            }
+
+            frames.push({
+                header,
+                payload: Buffer.from(this.buffer.subarray(4, 4 + header.cmdLen)),
+            });
+            this.buffer = this.buffer.subarray(4 + header.cmdLen);
+            if (header.isEncryptedChannel) {
+                this.headerXorKey = datumHeaderXorFeedback(this.headerXorKey);
+            }
+        }
+
+        return frames;
+    }
+}
+
+export function encodeDatumFrame(frame: DatumFrame, xorKey = DATUM_INITIAL_HEADER_KEY): Buffer {
+    return Buffer.concat([
+        encodeDatumHeader({ ...frame.header, cmdLen: frame.payload.length }, xorKey),
+        frame.payload,
+    ]);
+}
+
+export function deserializeDatumMiningCommand(payload: Buffer): { command: DatumMiningCommand; body: Buffer } {
+    if (payload.length < 1) {
+        throw new RangeError('DATUM mining command requires a sub-command byte');
+    }
+    return {
+        command: payload[0],
+        body: Buffer.from(payload.subarray(1)),
+    };
+}
+
+export function serializeDatumMiningCommand(command: DatumMiningCommand, body = Buffer.alloc(0)): Buffer {
+    return Buffer.concat([Buffer.from([command]), body]);
+}
+
+export function serializeDatumJobValidationShortTxIdsRequest(jobId: number): Buffer {
+    return serializeDatumMiningCommand(DatumMiningCommand.JOB_VALIDATION, Buffer.from([
+        DatumJobValidationCommand.REQUEST_SHORT_TX_IDS,
+        jobId & 0xff,
+    ]));
+}
+
+export function serializeDatumJobValidationFullTransactionBlobRequest(jobId: number): Buffer {
+    return serializeDatumMiningCommand(DatumMiningCommand.JOB_VALIDATION, Buffer.from([
+        DatumJobValidationCommand.REQUEST_FULL_TRANSACTION_BLOB,
+        jobId & 0xff,
+    ]));
+}
+
+export function serializeDatumJobValidationFullTransactionsRequest(jobId: number, transactionIndexes: number[]): Buffer {
+    if (transactionIndexes.length > 0xffff) {
+        throw new RangeError('DATUM requested transaction index count must fit in u16');
+    }
+    const w = new BufferWriter();
+    w.writeU8(DatumJobValidationCommand.REQUEST_FULL_TRANSACTIONS);
+    w.writeU8(jobId);
+    w.writeU16(transactionIndexes.length);
+    for (const index of transactionIndexes) {
+        if (!Number.isInteger(index) || index < 0 || index > 0xffff) {
+            throw new RangeError(`Invalid DATUM transaction index ${index}`);
+        }
+        w.writeU16(index);
+    }
+    return serializeDatumMiningCommand(DatumMiningCommand.JOB_VALIDATION, Buffer.from(w.toBuffer()));
+}
+
+export function deserializeDatumJobValidationResponse(payload: Buffer): DatumJobValidationResponse {
+    const reader = new BufferReader(payload);
+    const responseCommand = reader.readU8();
+    const jobId = reader.readU8();
+    const status = reader.readU8();
+
+    if (responseCommand === DatumJobValidationCommand.SHORT_TX_IDS_RESPONSE) {
+        if (status !== DatumJobValidationStatus.SUCCESS) {
+            return {
+                kind: 'short-txids',
+                jobId,
+                status,
+                transactionCount: 0,
+                shortTxIds: [],
+                crosscheck: null,
+            };
+        }
+        const transactionCount = reader.readU16();
+        const shortTxIds: Buffer[] = [];
+        for (let i = 0; i < transactionCount; i++) {
+            shortTxIds.push(reader.readBytes(6));
+        }
+        const crosscheck = reader.remaining >= 32 ? reader.readBytes(32) : null;
+        consumeDatumTerminatorAndPadding(reader);
+        return {
+            kind: 'short-txids',
+            jobId,
+            status,
+            transactionCount,
+            shortTxIds,
+            crosscheck,
+        };
+    }
+
+    if (responseCommand === DatumJobValidationCommand.FULL_TRANSACTIONS_RESPONSE) {
+        return deserializeDatumTransactionListResponse('full-transactions', reader, jobId, status);
+    }
+
+    if (responseCommand === DatumJobValidationCommand.FULL_TRANSACTION_BLOB_RESPONSE) {
+        return deserializeDatumTransactionListResponse('full-transaction-blob', reader, jobId, status);
+    }
+
+    throw new RangeError(`Unsupported DATUM job validation response 0x${responseCommand.toString(16)}`);
+}
+
+export function deserializeDatumCoinbaserFetch(payload: Buffer): DatumCoinbaserFetch {
+    if (payload.length < 8) {
+        throw new RangeError('DATUM coinbaser fetch requires reward value');
+    }
+    return { rewardValue: payload.readBigUInt64LE(0) };
+}
+
+export function serializeDatumCoinbaserFetchResponse(rewardValue: bigint, outputs: DatumPayoutOutput[]): Buffer {
+    const w = new BufferWriter();
+    w.writeU64(rewardValue);
+    const outputsBuffer = serializeDatumPayoutOutputs(outputs);
+    w.writeU32(outputsBuffer.length);
+    w.writeBytes(outputsBuffer);
+    return serializeDatumMiningCommand(DatumMiningCommand.FETCH_COINBASER_RESPONSE, Buffer.from(w.toBuffer()));
+}
+
+export function serializeDatumPayoutOutputs(outputs: DatumPayoutOutput[]): Buffer {
+    if (outputs.length > 255) {
+        throw new RangeError('DATUM payout output count must fit in one byte');
+    }
+    const w = new BufferWriter();
+    w.writeU8(outputs.length);
+    for (const output of outputs) {
+        if (output.scriptPubKey.length > 255) {
+            throw new RangeError('DATUM scriptPubKey length must fit in one byte');
+        }
+        w.writeU64(output.value);
+        w.writeU8(output.scriptPubKey.length);
+        w.writeBytes(output.scriptPubKey);
+    }
+    return w.toBuffer();
+}
+
+export function deserializeDatumPowSubmit(payload: Buffer): DatumPowSubmit {
+    const reader = new BufferReader(payload);
+    const jobId = reader.readU8();
+    const coinbaseId = reader.readU8();
+    const flags = reader.readU8();
+    const targetByte = reader.readU8();
+    const ntime = reader.readU32();
+    const nonce = reader.readU32();
+    const version = reader.readU32();
+    const extranonceSize = reader.readU8();
+    if (extranonceSize !== DATUM_EXTRANONCE_SIZE) {
+        throw new RangeError(`Unsupported DATUM extranonce size ${extranonceSize}`);
+    }
+    const extranonce = reader.readBytes(extranonceSize);
+    const username = readNullTerminatedString(reader);
+    const reserved = reader.readBytes(Math.min(4, reader.remaining));
+    const coinbasePairs = new Map<number, { coinb1: Buffer; coinb2: Buffer }>();
+    const result: DatumPowSubmit = {
+        jobId,
+        coinbaseId,
+        isBlock: (flags & 0x01) !== 0,
+        subsidyOnly: (flags & 0x02) !== 0,
+        quickDiff: (flags & 0x04) !== 0,
+        targetByte,
+        ntime,
+        nonce,
+        version,
+        extranonce,
+        username,
+        reserved,
+        coinbasePairs,
+    };
+
+    while (reader.remaining > 0) {
+        const section = reader.readU8();
+        if (section === 0xfe) {
+            break;
+        }
+        if (section === 0x01) {
+            result.prevBlockHash = reader.readBytes(32);
+            result.targetByteIndex = reader.readU16();
+            result.nBits = reader.readBytes(4);
+            result.coinbaserId = reader.readU8();
+            result.height = reader.readU32();
+            result.coinbaseValue = reader.readU64();
+            result.transactionCount = reader.readU32();
+            result.totalWeight = reader.readU32();
+            result.totalSize = reader.readU32();
+            result.totalSigops = reader.readU32();
+            const merkleBranchCount = reader.readU8();
+            result.merkleBranches = [];
+            for (let i = 0; i < merkleBranchCount; i++) {
+                result.merkleBranches.push(reader.readBytes(32));
+            }
+            continue;
+        }
+        if (section === 0x02) {
+            const coinbaseType = reader.readU8();
+            const coinb1Len = reader.readU16();
+            const coinb2Len = reader.readU16();
+            const coinbase = {
+                coinb1: reader.readBytes(coinb1Len),
+                coinb2: reader.readBytes(coinb2Len),
+            };
+            if (coinbaseType === 255 || coinbaseId === 255) {
+                result.subsidyOnlyCoinbase = coinbase;
+            } else {
+                coinbasePairs.set(coinbaseType, coinbase);
+            }
+            continue;
+        }
+        throw new RangeError(`Unsupported DATUM POW section 0x${section.toString(16)}`);
+    }
+
+    return result;
+}
+
+export function serializeDatumShareResponse(input: {
+    status: DatumShareResponseStatus;
+    reasonCode: number;
+    nonce: number;
+    targetByte: number;
+    jobId: number;
+}): Buffer {
+    const w = new BufferWriter();
+    w.writeU8(input.status);
+    w.writeU16(input.reasonCode);
+    w.writeU32(input.nonce);
+    w.writeU8(input.targetByte);
+    w.writeU8(input.jobId);
+    return serializeDatumMiningCommand(DatumMiningCommand.SHARE_RESPONSE, Buffer.from(w.toBuffer()));
+}
+
+function deserializeDatumTransactionListResponse(
+    kind: 'full-transactions' | 'full-transaction-blob',
+    reader: BufferReader,
+    jobId: number,
+    status: number,
+): DatumFullTransactionsResponse | DatumFullTransactionBlobResponse {
+    if (status !== DatumJobValidationStatus.SUCCESS) {
+        return {
+            kind,
+            jobId,
+            status,
+            transactionCount: 0,
+            transactions: [],
+        };
+    }
+
+    const transactionCount = reader.readU16();
+    const transactions: Buffer[] = [];
+    for (let i = 0; i < transactionCount; i++) {
+        const transactionSize = reader.readU24();
+        transactions.push(reader.readBytes(transactionSize));
+    }
+    consumeDatumTerminatorAndPadding(reader);
+    return {
+        kind,
+        jobId,
+        status,
+        transactionCount,
+        transactions,
+    };
+}
+
+function consumeDatumTerminatorAndPadding(reader: BufferReader): void {
+    if (reader.remaining <= 0) {
+        return;
+    }
+    const terminator = reader.readU8();
+    if (terminator !== 0xfe) {
+        throw new RangeError(`DATUM job validation response missing terminator; got 0x${terminator.toString(16)}`);
+    }
+}
+
+function readNullTerminatedString(reader: BufferReader): string {
+    const bytes: number[] = [];
+    while (reader.remaining > 0) {
+        const byte = reader.readU8();
+        if (byte === 0) {
+            break;
+        }
+        bytes.push(byte);
+    }
+    return Buffer.from(bytes).toString('utf8');
+}

src/models/datum/datum-crypto.spec.ts

@@ -0,0 +1,94 @@
+import * as sodium from 'libsodium-wrappers-sumo';
+import {
+    DATUM_INITIAL_HEADER_KEY,
+    DatumProtocolCommand,
+    datumHeaderXorFeedback,
+    decodeDatumHeader,
+    encodeDatumFrame,
+} from './datum-codec';
+import { DatumCryptoSession } from './datum-crypto';
+
+describe('DatumCryptoSession', () => {
+    it('derives stable DATUM public keys from a configured seed', async () => {
+        await sodium.ready;
+        const seed = Buffer.from('000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f', 'hex');
+
+        const first = DatumCryptoSession.generateKeyPairFromSeed(seed);
+        const second = DatumCryptoSession.generateKeyPairFromSeed(seed);
+
+        expect(Buffer.concat([first.edPublicKey, first.xPublicKey]).toString('hex'))
+            .toBe(Buffer.concat([second.edPublicKey, second.xPublicKey]).toString('hex'));
+        expect(first.edSecretKey).toEqual(second.edSecretKey);
+    });
+
+    it('opens signed sealed handshakes and builds encrypted responses', async () => {
+        await sodium.ready;
+        const serverIdentity = DatumCryptoSession.generateKeyPair();
+        const serverSessionKeys = DatumCryptoSession.generateKeyPair();
+        const clientIdentity = DatumCryptoSession.generateKeyPair();
+        const clientSessionKeys = DatumCryptoSession.generateKeyPair();
+        const server = await DatumCryptoSession.create(serverIdentity, serverSessionKeys);
+        const nextHeaderKey = 0x12345678;
+
+        const signedBody = Buffer.concat([
+            clientIdentity.edPublicKey,
+            clientIdentity.xPublicKey,
+            clientSessionKeys.edPublicKey,
+            clientSessionKeys.xPublicKey,
+            Buffer.from('datum-test/0\0', 'utf8'),
+            Buffer.from([0xfe]),
+            uint32(nextHeaderKey),
+            Buffer.from([1, 2, 3]),
+        ]);
+        const signature = Buffer.from(sodium.crypto_sign_detached(signedBody, clientIdentity.edSecretKey));
+        const encrypted = Buffer.from(sodium.crypto_box_seal(
+            Buffer.concat([signedBody, signature]),
+            serverIdentity.xPublicKey,
+        ));
+        const frame = encodeDatumFrame({
+            header: {
+                cmdLen: encrypted.length,
+                reserved: 0,
+                isSigned: true,
+                isEncryptedPubkey: true,
+                isEncryptedChannel: false,
+                protoCmd: DatumProtocolCommand.HANDSHAKE_INIT,
+            },
+            payload: encrypted,
+        }, DATUM_INITIAL_HEADER_KEY);
+        const header = decodeDatumHeader(frame.subarray(0, 4), DATUM_INITIAL_HEADER_KEY);
+
+        const hello = server.openHandshake(frame.subarray(4, 4 + header.cmdLen));
+        expect(hello.userAgent).toBe('datum-test/0');
+        expect(hello.nextHeaderKey).toBe(nextHeaderKey);
+        expect(hello.sessionXPublicKey).toEqual(clientSessionKeys.xPublicKey);
+
+        const response = server.buildHandshakeResponse(hello, 'motd');
+        const responseHeader = decodeDatumHeader(response.subarray(0, 4), datumHeaderXorFeedback((~nextHeaderKey) >>> 0));
+        expect(responseHeader.protoCmd).toBe(DatumProtocolCommand.HANDSHAKE_RESPONSE);
+        expect(responseHeader.isSigned).toBe(true);
+        expect(responseHeader.isEncryptedPubkey).toBe(true);
+        const opened = Buffer.from(sodium.crypto_box_seal_open(
+            response.subarray(4),
+            clientSessionKeys.xPublicKey,
+            clientSessionKeys.xSecretKey,
+        ));
+        expect(opened.subarray(0, 32)).toEqual(clientIdentity.edPublicKey);
+        expect(opened.subarray(128, 160)).toEqual(serverSessionKeys.edPublicKey);
+
+        const ping = server.encryptChannelFrame(DatumProtocolCommand.PING, Buffer.alloc(0));
+        const pingHeader = decodeDatumHeader(
+            ping.subarray(0, 4),
+            datumHeaderXorFeedback(datumHeaderXorFeedback((~nextHeaderKey) >>> 0)),
+        );
+        expect(pingHeader.protoCmd).toBe(DatumProtocolCommand.PING);
+        expect(pingHeader.isEncryptedChannel).toBe(true);
+        expect(pingHeader.cmdLen).toBe(sodium.crypto_box_MACBYTES);
+    });
+});
+
+function uint32(value: number): Buffer {
+    const result = Buffer.alloc(4);
+    result.writeUInt32LE(value >>> 0, 0);
+    return result;
+}

src/models/datum/datum-crypto.ts

@@ -0,0 +1,245 @@
+import * as crypto from 'crypto';
+import * as sodium from 'libsodium-wrappers-sumo';
+import {
+    DATUM_INITIAL_HEADER_KEY,
+    DatumFrame,
+    DatumProtocolCommand,
+    decodeDatumHeader,
+    encodeDatumFrame,
+    datumHeaderXorFeedback,
+} from './datum-codec';
+
+export interface DatumKeyPair {
+    edPublicKey: Buffer;
+    edSecretKey: Buffer;
+    xPublicKey: Buffer;
+    xSecretKey: Buffer;
+}
+
+export interface DatumHello {
+    identityEdPublicKey: Buffer;
+    identityXPublicKey: Buffer;
+    sessionEdPublicKey: Buffer;
+    sessionXPublicKey: Buffer;
+    userAgent: string;
+    nextHeaderKey: number;
+}
+
+export class DatumCryptoSession {
+    private initialized = false;
+    private sharedSecret: Uint8Array | null = null;
+    private receiveNonce: Buffer | null = null;
+    private sendNonce: Buffer | null = null;
+    private receiveHeaderKey = DATUM_INITIAL_HEADER_KEY;
+    private sendHeaderKey = DATUM_INITIAL_HEADER_KEY;
+    private clientIdentityXPublicKey: Buffer | null = null;
+
+    private constructor(
+        private readonly identityKeys: DatumKeyPair,
+        private readonly sessionKeys: DatumKeyPair,
+    ) {}
+
+    public static async create(identityKeys?: DatumKeyPair, sessionKeys?: DatumKeyPair): Promise<DatumCryptoSession> {
+        await sodium.ready;
+        return new DatumCryptoSession(
+            identityKeys ?? DatumCryptoSession.generateKeyPair(),
+            sessionKeys ?? DatumCryptoSession.generateKeyPair(),
+        );
+    }
+
+    public get publicKeyHex(): string {
+        return Buffer.concat([this.identityKeys.edPublicKey, this.identityKeys.xPublicKey]).toString('hex');
+    }
+
+    public get currentReceiveHeaderKey(): number {
+        return this.receiveHeaderKey;
+    }
+
+    public get currentSendHeaderKey(): number {
+        return this.sendHeaderKey;
+    }
+
+    public openHandshake(framePayload: Buffer): DatumHello {
+        const opened = Buffer.from(sodium.crypto_box_seal_open(
+            framePayload,
+            this.identityKeys.xPublicKey,
+            this.identityKeys.xSecretKey,
+        ));
+        if (opened.length < 32 * 4 + 1 + 4 + sodium.crypto_sign_BYTES) {
+            throw new Error('DATUM handshake payload is too short');
+        }
+
+        const signature = opened.subarray(opened.length - sodium.crypto_sign_BYTES);
+        const signedPayload = opened.subarray(0, opened.length - sodium.crypto_sign_BYTES);
+        const clientIdentityEdPublicKey = signedPayload.subarray(0, 32);
+        if (!sodium.crypto_sign_verify_detached(signature, signedPayload, clientIdentityEdPublicKey)) {
+            throw new Error('DATUM handshake signature verification failed');
+        }
+
+        let offset = 0;
+        const hello: DatumHello = {
+            identityEdPublicKey: Buffer.from(signedPayload.subarray(offset, offset += 32)),
+            identityXPublicKey: Buffer.from(signedPayload.subarray(offset, offset += 32)),
+            sessionEdPublicKey: Buffer.from(signedPayload.subarray(offset, offset += 32)),
+            sessionXPublicKey: Buffer.from(signedPayload.subarray(offset, offset += 32)),
+            userAgent: '',
+            nextHeaderKey: 0,
+        };
+
+        const userAgentStart = offset;
+        while (offset < signedPayload.length && signedPayload[offset] !== 0) {
+            offset++;
+        }
+        hello.userAgent = signedPayload.subarray(userAgentStart, offset).toString('utf8');
+        offset++;
+
+        if (signedPayload[offset] !== 0xfe) {
+            throw new Error('DATUM handshake missing key delimiter');
+        }
+        offset++;
+        hello.nextHeaderKey = signedPayload.readUInt32LE(offset);
+
+        this.clientIdentityXPublicKey = hello.identityXPublicKey;
+        this.sharedSecret = sodium.crypto_box_beforenm(hello.sessionXPublicKey, this.sessionKeys.xSecretKey);
+        this.receiveHeaderKey = datumHeaderXorFeedback(hello.nextHeaderKey);
+        this.sendHeaderKey = datumHeaderXorFeedback((~hello.nextHeaderKey) >>> 0);
+        this.initializeNonces(hello.nextHeaderKey, hello.sessionEdPublicKey);
+        this.initialized = true;
+
+        return hello;
+    }
+
+    public buildHandshakeResponse(hello: DatumHello, motd: string): Buffer {
+        if (this.clientIdentityXPublicKey == null) {
+            throw new Error('Cannot build DATUM handshake response before opening client hello');
+        }
+
+        const body = Buffer.concat([
+            hello.identityEdPublicKey,
+            hello.identityXPublicKey,
+            hello.sessionEdPublicKey,
+            hello.sessionXPublicKey,
+            this.sessionKeys.edPublicKey,
+            this.sessionKeys.xPublicKey,
+            Buffer.from(`${motd}\0`, 'utf8'),
+        ]);
+        const signature = Buffer.from(sodium.crypto_sign_detached(body, this.identityKeys.edSecretKey));
+        const encrypted = Buffer.from(sodium.crypto_box_seal(
+            Buffer.concat([body, signature]),
+            hello.sessionXPublicKey,
+        ));
+
+        const response = encodeDatumFrame({
+            header: {
+                cmdLen: encrypted.length,
+                reserved: 0,
+                isSigned: true,
+                isEncryptedPubkey: true,
+                isEncryptedChannel: false,
+                protoCmd: DatumProtocolCommand.HANDSHAKE_RESPONSE,
+            },
+            payload: encrypted,
+        }, this.sendHeaderKey);
+        this.sendHeaderKey = datumHeaderXorFeedback(this.sendHeaderKey);
+        return response;
+    }
+
+    public decryptChannelPayload(payload: Buffer): Buffer {
+        if (!this.initialized || this.sharedSecret == null || this.receiveNonce == null) {
+            throw new Error('DATUM channel is not initialized');
+        }
+        const opened = sodium.crypto_box_open_easy_afternm(payload, this.receiveNonce, this.sharedSecret);
+        this.incrementNonce(this.receiveNonce);
+        this.receiveHeaderKey = datumHeaderXorFeedback(this.receiveHeaderKey);
+        return Buffer.from(opened);
+    }
+
+    public encryptChannelFrame(protoCmd: DatumProtocolCommand, payload: Buffer, signed = false): Buffer {
+        if (!this.initialized || this.sharedSecret == null || this.sendNonce == null) {
+            throw new Error('DATUM channel is not initialized');
+        }
+        const signedPayload = signed
+            ? Buffer.concat([payload, Buffer.from(sodium.crypto_sign_detached(payload, this.sessionKeys.edSecretKey))])
+            : payload;
+        const encrypted = Buffer.from(sodium.crypto_box_easy_afternm(signedPayload, this.sendNonce, this.sharedSecret));
+        const frame = encodeDatumFrame({
+            header: {
+                cmdLen: encrypted.length,
+                reserved: 0,
+                isSigned: signed,
+                isEncryptedPubkey: false,
+                isEncryptedChannel: true,
+                protoCmd,
+            },
+            payload: encrypted,
+        }, this.sendHeaderKey);
+        this.incrementNonce(this.sendNonce);
+        this.sendHeaderKey = datumHeaderXorFeedback(this.sendHeaderKey);
+        return frame;
+    }
+
+    public decodeHeader(headerBytes: Buffer): ReturnType<typeof decodeDatumHeader> {
+        return decodeDatumHeader(headerBytes, this.receiveHeaderKey);
+    }
+
+    private initializeNonces(nextHeaderKey: number, clientSessionEdPublicKey: Buffer): void {
+        const receiver = Buffer.alloc(sodium.crypto_box_NONCEBYTES);
+        let key = ((nextHeaderKey - 42) ^ clientSessionEdPublicKey.readUInt32LE(7)) >>> 0;
+        for (let i = 0; i < receiver.length; i += 4) {
+            receiver.writeUInt32LE(datumHeaderXorFeedback((key - 42) >>> 0), i);
+            key = (~receiver.readUInt32LE(i)) >>> 0;
+        }
+
+        const sender = Buffer.alloc(receiver.length);
+        for (let i = 0; i < receiver.length; i += 4) {
+            sender.writeUInt32LE((receiver.readUInt32LE(i) ^ 0x57575757) >>> 0, i);
+        }
+
+        this.sendNonce = receiver;
+        this.receiveNonce = sender;
+    }
+
+    private incrementNonce(nonce: Buffer): void {
+        for (let offset = 0; offset < nonce.length; offset += 4) {
+            const next = (nonce.readUInt32LE(offset) + 1) >>> 0;
+            nonce.writeUInt32LE(next, offset);
+            if (next !== 0) {
+                return;
+            }
+        }
+    }
+
+    public static generateKeyPair(): DatumKeyPair {
+        const seed = crypto.randomBytes(32);
+        return DatumCryptoSession.generateKeyPairFromSeed(seed);
+    }
+
+    public static generateKeyPairFromSeed(seed: Buffer): DatumKeyPair {
+        if (seed.length !== 32) {
+            throw new RangeError(`DATUM key seed must be 32 bytes, got ${seed.length}`);
+        }
+        const ed = sodium.crypto_sign_seed_keypair(seed);
+        const xPublicKey = sodium.crypto_sign_ed25519_pk_to_curve25519(ed.publicKey);
+        const xSecretKey = sodium.crypto_sign_ed25519_sk_to_curve25519(ed.privateKey);
+        return {
+            edPublicKey: Buffer.from(ed.publicKey),
+            edSecretKey: Buffer.from(ed.privateKey),
+            xPublicKey: Buffer.from(xPublicKey),
+            xSecretKey: Buffer.from(xSecretKey),
+        };
+    }
+}
+
+export function buildDatumPlainFrame(protoCmd: DatumProtocolCommand, payload: Buffer): DatumFrame {
+    return {
+        header: {
+            cmdLen: payload.length,
+            reserved: 0,
+            isSigned: false,
+            isEncryptedPubkey: false,
+            isEncryptedChannel: false,
+            protoCmd,
+        },
+        payload,
+    };
+}

src/models/stratum-messages/MiningSubmitMessage.spec.ts

@@ -37,6 +37,10 @@ describe('MiningSubmitMessage', () => {
             expect(errors).toEqual([]);
         });
 
+        it('should hash submissions deterministically', () => {
+            expect(message.hash()).toBe('t2bFzhZ6mketRxa5nOoKrNxG3RkFIZuOwY1WewFtv9k=');
+        });
+
         it('should reject short extranonce2 submissions', async () => {
             const shortMessage = plainToInstance(
                 MiningSubmitMessage,

src/models/stratum-messages/MiningSubmitMessage.ts

@@ -4,7 +4,7 @@ import { ArrayMaxSize, ArrayMinSize, IsArray, IsString, Length } from 'class-val
 import { eRequestMethod } from '../enums/eRequestMethod';
 import { EXTRANONCE2_SIZE_BYTES } from '../stratum.constants';
 import { StratumBaseMessage } from './StratumBaseMessage';
-import * as bitcoinjs from 'bitcoinjs-lib';
+import { hash256 } from '../../utils/hash.utils';
 
 
 export class MiningSubmitMessage extends StratumBaseMessage {
@@ -69,7 +69,7 @@ export class MiningSubmitMessage extends StratumBaseMessage {
 
     public hash(): string{
         const buffer = Buffer.from(this.versionMask + this.nonce + this.extraNonce2 + this.ntime + this.jobId);
-        return bitcoinjs.crypto.hash256(buffer).toString('base64');
+        return hash256(buffer).toString('base64');
     }
 
 

src/models/stratum.constants.ts

@@ -1,3 +1,5 @@
 export const EXTRANONCE1_SIZE_BYTES = 4;
 export const EXTRANONCE2_SIZE_BYTES = 8;
 export const TOTAL_EXTRANONCE_SIZE_BYTES = EXTRANONCE1_SIZE_BYTES + EXTRANONCE2_SIZE_BYTES;
+export const SV2_EXTENDED_EXTRANONCE2_SIZE_BYTES = 10;
+export const SV2_EXTENDED_TOTAL_EXTRANONCE_SIZE_BYTES = EXTRANONCE1_SIZE_BYTES + SV2_EXTENDED_EXTRANONCE2_SIZE_BYTES;

src/models/sv2/sv2-extranonce-manager.spec.ts

@@ -27,6 +27,9 @@ describe('Sv2ExtranonceManager', () => {
   });
 
   it('minerExtranonceSize is total minus prefix', () => {
+    const defaultMgr = new Sv2ExtranonceManager();
+    expect(defaultMgr.minerExtranonceSize).toBe(10);
+
     const mgr = new Sv2ExtranonceManager(4, 8);
     expect(mgr.minerExtranonceSize).toBe(4);
 

src/models/sv2/sv2-extranonce-manager.ts

@@ -1,4 +1,6 @@
-// ── SV2 Extranonce Manager ──────────────────────────────────────────
+import { SV2_EXTENDED_TOTAL_EXTRANONCE_SIZE_BYTES } from '../stratum.constants';
+
+// -- SV2 Extranonce Manager ------------------------------------------
 // Manages extranonce prefix allocation for extended mining channels.
 // Ensures no two channels share the same prefix to prevent hash collisions.
 
@@ -13,13 +15,11 @@ export class Sv2ExtranonceManager {
 
   /**
    * @param prefixSize Bytes used for pool-assigned prefix (default 4)
-   * @param totalExtranonceSize Total extranonce bytes (default 12: 4 prefix + 8 miner-controlled).
+   * @param totalExtranonceSize Total extranonce bytes (default 14: 4 prefix + 10 miner/JDC-controlled).
-   *        Must match MiningJob.ts's coinbase slot size (12 bytes) — both
+   *        SV2 extended jobs patch the coinbase script length when the
-   *        protocols share the same coinbase template. Bumped from the
+   *        negotiated total differs from the SV1-compatible template slot.
-   *        previous 8-byte total because the Braiins Hashpower marketplace
-   *        requires extranonce2_size >= 7 (compatibility spec).
    */
-  constructor(prefixSize = 4, totalExtranonceSize = 12) {
+  constructor(prefixSize = 4, totalExtranonceSize = SV2_EXTENDED_TOTAL_EXTRANONCE_SIZE_BYTES) {
     this.prefixSize = prefixSize;
     this.totalExtranonceSize = totalExtranonceSize;
 
@@ -34,6 +34,10 @@ export class Sv2ExtranonceManager {
     return this.totalExtranonceSize - this.prefixSize;
   }
 
+  get totalSize(): number {
+    return this.totalExtranonceSize;
+  }
+
   /**
    * Allocate a unique extranonce prefix for a channel.
    * Returns a Buffer of `prefixSize` bytes.

src/scripts/run-migrations.ts

@@ -0,0 +1,16 @@
+import { AppDataSource } from '../data-source';
+
+async function main() {
+    await AppDataSource.initialize();
+    try {
+        const migrations = await AppDataSource.runMigrations();
+        console.log(`Ran ${migrations.length} database migrations`);
+    } finally {
+        await AppDataSource.destroy();
+    }
+}
+
+main().catch(error => {
+    console.error('Database migration failed:', error);
+    process.exit(1);
+});

src/scripts/start-docker.ts

@@ -0,0 +1,68 @@
+import { spawn } from 'child_process';
+import * as net from 'net';
+
+async function main() {
+    await waitForTcp(process.env.DB_HOST, parseInt(process.env.DB_PORT ?? '5432', 10), 'TimescaleDB');
+    const redisUrl = new URL(process.env.REDIS_URL ?? 'redis://redis:6379');
+    await waitForTcp(redisUrl.hostname, parseInt(redisUrl.port || '6379', 10), 'Redis');
+    await run('node', ['dist/scripts/run-migrations.js']);
+
+    if (process.env.PM2_ENABLED === 'false') {
+        await run('node', ['dist/main.js'], true);
+        return;
+    }
+
+    await run('./node_modules/.bin/pm2-runtime', ['ecosystem.config.js'], true);
+}
+
+function waitForTcp(host: string, port: number, label: string): Promise<void> {
+    const deadline = Date.now() + parseInt(process.env.STARTUP_WAIT_TIMEOUT_MS ?? '60000', 10);
+
+    return new Promise((resolve, reject) => {
+        const attempt = () => {
+            const socket = net.createConnection({ host, port });
+            socket.once('connect', () => {
+                socket.destroy();
+                console.log(`${label} is reachable at ${host}:${port}`);
+                resolve();
+            });
+            socket.once('error', () => {
+                socket.destroy();
+                if (Date.now() > deadline) {
+                    reject(new Error(`${label} was not reachable at ${host}:${port}`));
+                    return;
+                }
+                setTimeout(attempt, 1000);
+            });
+        };
+
+        attempt();
+    });
+}
+
+function run(command: string, args: string[], inherit = false): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: inherit ? 'inherit' : 'pipe',
+            env: process.env,
+        });
+
+        if (!inherit) {
+            child.stdout?.on('data', data => process.stdout.write(data));
+            child.stderr?.on('data', data => process.stderr.write(data));
+        }
+
+        child.once('exit', code => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`${command} ${args.join(' ')} exited with ${code}`));
+        });
+    });
+}
+
+main().catch(error => {
+    console.error(error);
+    process.exit(1);
+});

src/services/app.service.ts

@@ -1,22 +1,20 @@
 import { Injectable, OnModuleInit } from '@nestjs/common';
-import { DataSource } from 'typeorm';
 
 import { UserAgentReportService } from '../ORM/_views/user-agent-report/user-agent-report.service';
-import { ClientStatisticsService } from '../ORM/client-statistics/client-statistics.service';
 import { ClientService } from '../ORM/client/client.service';
-import { HomeGraphService } from '../ORM/home-graph/home-graph.service';
 import { RpcBlockService } from '../ORM/rpc-block/rpc-block.service';
+import { ShareAccountingService } from '../ORM/share-accounting/share-accounting.service';
 
 @Injectable()
 export class AppService implements OnModuleInit {
+    private refreshingLiveUserAgentReport = false;
+    private refreshingPoolSummary = false;
 
     constructor(
-        private readonly clientStatisticsService: ClientStatisticsService,
         private readonly clientService: ClientService,
         private readonly rpcBlockService: RpcBlockService,
-        private readonly homeGraphService: HomeGraphService,
+        private readonly userAgentReportService: UserAgentReportService,
-        private readonly dataSource: DataSource,
+        private readonly shareAccountingService: ShareAccountingService
-        private readonly userAgentReportService: UserAgentReportService
     ) {
 
     }
@@ -25,25 +23,26 @@ export class AppService implements OnModuleInit {
         if (process.env.MASTER == 'true') {
 
             setInterval(async () => {
-                await this.deleteOldStatistics();
+                await this.deleteOldClients();
             }, 1000 * 60 * 60);
 
-            setInterval(async () => {
-                console.log('Killing dead clients');
-                while (await this.clientService.killDeadClients()) {
-
-                }
-                console.log('Finished killing clients');
-            }, 1000 * 60 * 5);
-
             setInterval(async () => {
                 console.log('Deleting Old Blocks');
                 await this.rpcBlockService.deleteOldBlocks();
             }, 1000 * 60 * 60 * 24);
 
             setInterval(async () => {
-                await this.updateChart();
+                await this.refreshLiveUserAgentReport();
-            }, 1000 * 60 * 10);
+            }, 1000 * 30);
+
+            setTimeout(async () => {
+                await this.refreshLiveUserAgentReport();
+                await this.refreshPoolSummary();
+            }, 1000 * 15);
+
+            setInterval(async () => {
+                await this.refreshPoolSummary();
+            }, 1000 * 60 * 5);
 
             setInterval(async () => {
                 console.log('Refreshing user agent report view')
@@ -52,61 +51,43 @@ export class AppService implements OnModuleInit {
             }, 1000 * 60 * 5);
 
         }
-
-        setInterval(async () => {
-            //console.log('Bulk update client stats');
-            await this.clientStatisticsService.doBulkAsyncUpdate();
-        }, 1000 * 30);
-
-        setInterval(async () => {
-            //console.log('Bulk update client stats');
-            await this.clientService.doBulkHeartbeatUpdate();
-        }, 1000 * 30);
-
-
     }
 
-    private async deleteOldStatistics() {
+    private async deleteOldClients() {
-        console.log('Deleting statistics');
+        console.log('Deleting old clients');
 
-        const deletedStatistics = await this.clientStatisticsService.deleteOldStatistics();
-        console.log(`Deleted ${deletedStatistics.affected} old statistics`);
         const deletedClients = await this.clientService.deleteOldClients();
         console.log(`Deleted ${deletedClients.affected} old clients`);
 
     }
 
-
+    private async refreshLiveUserAgentReport() {
-    private async updateChart() {
+        if (this.refreshingLiveUserAgentReport) {
-        console.log('Updating Chart');
-
-        const latestGraphUpdate = await this.homeGraphService.getLatestTime();
-
-
-        const data = await this.dataSource.query(`
-            SELECT
-                time AS label,
-                ROUND(((SUM(shares) * 4294967296) / 600)) AS data
-            FROM
-                client_statistics_entity AS entry
-            WHERE
-                entry.time > ${latestGraphUpdate.getTime()}
-            GROUP BY
-                time
-            ORDER BY
-                time
-            LIMIT 144;
-        `)
-
-        console.log(`Fetched ${data.length} rows`);
-
-        if (data.length < 2) {
             return;
         }
 
-        const result = data.slice(0, data.length - 1);
+        this.refreshingLiveUserAgentReport = true;
+        try {
+            await this.userAgentReportService.refreshLiveReport();
+        } catch (error) {
+            console.error(`Failed refreshing live user agent report: ${error.message}`);
+        } finally {
+            this.refreshingLiveUserAgentReport = false;
+        }
+    }
 
-        this.homeGraphService.save(result);
+    private async refreshPoolSummary() {
+        if (this.refreshingPoolSummary) {
+            return;
+        }
 
+        this.refreshingPoolSummary = true;
+        try {
+            await this.shareAccountingService.refreshPoolSummary();
+        } catch (error) {
+            console.error(`Failed refreshing pool accounting summary: ${error.message}`);
+        } finally {
+            this.refreshingPoolSummary = false;
+        }
     }
 }

src/services/bitcoin-rpc.service.ts

@@ -1,13 +1,14 @@
-import { Injectable, OnModuleInit } from '@nestjs/common';
+import { Injectable, OnModuleInit, Optional } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import axios, { AxiosInstance } from 'axios';
 import { asyncScheduler, BehaviorSubject, delay, filter, from, interval, scheduled, shareReplay, startWith, Subject, switchMap } from 'rxjs';
+import { PayoutSnapshotService } from '../ORM/payout-snapshot/payout-snapshot.service';
 import { RpcBlockService } from '../ORM/rpc-block/rpc-block.service';
 import * as zmq from 'zeromq';
 
 import { IBlockTemplate } from '../models/bitcoin-rpc/IBlockTemplate';
 import { IMiningInfo } from '../models/bitcoin-rpc/IMiningInfo';
-import * as PGPubsub from 'pg-pubsub';
+import { RedisMessagingService } from './redis-messaging.service';
 
 @Injectable()
 export class BitcoinRpcService implements OnModuleInit {
@@ -15,7 +16,6 @@ export class BitcoinRpcService implements OnModuleInit {
     
     private client: AxiosInstance;
     private _newBlockTemplate$: BehaviorSubject<IBlockTemplate> = new BehaviorSubject(undefined);
-    private pubsubInstance: PGPubsub;
     private resetTemplateInterval$ = new Subject<void>();
     private rpcRequestId = 0;
 
@@ -24,16 +24,16 @@ export class BitcoinRpcService implements OnModuleInit {
 
     constructor(
         private readonly configService: ConfigService,
-        private rpcBlockService: RpcBlockService
+        private rpcBlockService: RpcBlockService,
+        private readonly redisMessagingService: RedisMessagingService,
+        @Optional()
+        private readonly payoutSnapshotService?: PayoutSnapshotService
     ) {
 
     }
 
     async onModuleInit() {
 
-        this.pubsubInstance = new PGPubsub('postgres://' + this.configService.get('DB_USERNAME') + ':' + this.configService.get('DB_PASSWORD') + '@' + this.configService.get('DB_HOST') + ':' + this.configService.get('DB_PORT') + '/' + this.configService.get('DB_DATABASE'))
-
-
         const url = this.configService.get('BITCOIN_RPC_URL');
         const user = this.configService.get('BITCOIN_RPC_USER');
         const pass = this.configService.get('BITCOIN_RPC_PASSWORD');
@@ -50,6 +50,23 @@ export class BitcoinRpcService implements OnModuleInit {
             }
         });
 
+        console.log(`MASTER? ${process.env.MASTER}`)
+        if (process.env.MASTER != 'true') {
+            await this.loadLatestMiningInfoForReplayProcess();
+            if (process.env.API_ONLY != 'true') {
+                await this.loadLatestTemplateForWorker();
+            }
+            await this.redisMessagingService.subscribeMiningInfoUpdates(async (miningInfo: IMiningInfo) => {
+                this.miningInfo = miningInfo;
+                if (process.env.API_ONLY != 'true') {
+                    await this.loadTemplateForWorker(miningInfo.blocks);
+                }
+            });
+            if (process.env.API_ONLY == 'true') {
+                console.log('API-only process using Redis mining info replay');
+            }
+            return;
+        } else {
             this.callRpc('getrpcinfo').then((res) => {
                 console.log('Bitcoin RPC connected');
             }, () => {
@@ -57,16 +74,6 @@ export class BitcoinRpcService implements OnModuleInit {
             });
 
             this.miningInfo = await this.getMiningInfo();
-
-        console.log(`MASTER? ${process.env.MASTER}`)
-        if (process.env.MASTER != 'true') {
-            this.pubsubInstance.addChannel('miningInfo', async (miningInfo: IMiningInfo) => {
-                //console.log('PG Sub. new template');
-                this.miningInfo = miningInfo;
-                const savedBlockTemplate = await this.rpcBlockService.getSavedBlockTemplate(miningInfo.blocks);
-                this._newBlockTemplate$.next(JSON.parse(savedBlockTemplate.data));
-            });
-        } else {
             console.log('Using ZMQ');
             const sock = new zmq.Subscriber;
 
@@ -95,6 +102,13 @@ export class BitcoinRpcService implements OnModuleInit {
 
     }
 
+    private async loadLatestMiningInfoForReplayProcess() {
+        const latestMiningInfo = await this.redisMessagingService.getLatestMiningInfo();
+        if (latestMiningInfo != null) {
+            this.miningInfo = latestMiningInfo;
+        }
+    }
+
     private async listenForNewBlocks(sock: zmq.Subscriber) {
         for await (const [topic, msg] of sock) {
             console.log("New Block");
@@ -107,9 +121,48 @@ export class BitcoinRpcService implements OnModuleInit {
     }
 
     public async getAndBroadcastLatestTemplate() {
+        if (this.miningInfo?.blocks == null) {
+            console.warn('Skipping block template broadcast because mining info is not available');
+            return;
+        }
+
         const blockTemplate = await this.loadBlockTemplate(this.miningInfo.blocks);
+        if (blockTemplate == null) {
+            console.warn(`Skipping block template broadcast for height ${this.miningInfo.blocks}; block template is not available`);
+            return;
+        }
+
         this._newBlockTemplate$.next(blockTemplate);
-        await this.pubsubInstance.publish('miningInfo', this.miningInfo);
+        await this.redisMessagingService.setLatestMiningInfo(this.miningInfo);
+        await this.redisMessagingService.setBlockTemplate(this.miningInfo.blocks, blockTemplate);
+        await this.redisMessagingService.publishMiningInfoUpdate(this.miningInfo);
+    }
+
+    private async loadLatestTemplateForWorker() {
+        const latestMiningInfo = await this.redisMessagingService.getLatestMiningInfo();
+        if (latestMiningInfo != null) {
+            this.miningInfo = latestMiningInfo;
+            await this.loadTemplateForWorker(latestMiningInfo.blocks);
+            return;
+        }
+
+        const latestBlockTemplate = await this.redisMessagingService.getLatestBlockTemplate();
+        if (latestBlockTemplate != null) {
+            this._newBlockTemplate$.next(latestBlockTemplate);
+        }
+    }
+
+    private async loadTemplateForWorker(blockHeight: number) {
+        const redisBlockTemplate = await this.redisMessagingService.getBlockTemplate(blockHeight);
+        if (redisBlockTemplate != null) {
+            this._newBlockTemplate$.next(redisBlockTemplate);
+            return;
+        }
+
+        const savedBlockTemplate = await this.rpcBlockService.getSavedBlockTemplate(blockHeight);
+        if (savedBlockTemplate?.data != null) {
+            this._newBlockTemplate$.next(JSON.parse(savedBlockTemplate.data));
+        }
     }
 
     private async loadBlockTemplate(blockHeight: number) {
@@ -118,6 +171,7 @@ export class BitcoinRpcService implements OnModuleInit {
 
         let blockTemplate: IBlockTemplate;
         while (blockTemplate == null) {
+            try {
                 blockTemplate = await this.callRpc<IBlockTemplate>('getblocktemplate', [
                     {
                         rules: ['segwit'],
@@ -125,6 +179,24 @@ export class BitcoinRpcService implements OnModuleInit {
                         capabilities: ['serverlist', 'proposal']
                     }
                 ]);
+            } catch (e) {
+                console.warn(`Block template is not available yet: ${e.message ?? e}`);
+                await new Promise(resolve => setTimeout(resolve, 10_000));
+            }
+        }
+
+        try {
+            const payoutSnapshot = await this.payoutSnapshotService?.createSnapshotForTemplate({
+                blockHeight,
+                coinbaseValueSats: blockTemplate.coinbasevalue,
+                networkDifficulty: this.calculateNetworkDifficulty(parseInt(blockTemplate.bits, 16)),
+            });
+            if (payoutSnapshot != null) {
+                blockTemplate.payoutSnapshotId = payoutSnapshot.id;
+                blockTemplate.payoutOutputs = payoutSnapshot.payoutOutputs;
+            }
+        } catch (e) {
+            console.error('Error creating payout snapshot', e);
         }
 
         try {
@@ -159,13 +231,25 @@ export class BitcoinRpcService implements OnModuleInit {
             console.log(hexdata);
             console.log(JSON.stringify(response));
         } catch (e) {
-            response = e;
+            response = e instanceof Error ? e.message : String(e);
-            console.log(`BLOCK SUBMISSION RESPONSE ERROR: ${e}`);
+            console.log(`BLOCK SUBMISSION RESPONSE ERROR: ${response}`);
         }
         return response;
 
     }
 
+    public async TEST_MEMPOOL_ACCEPT(rawTransactions: Buffer[]): Promise<Array<{
+        txid?: string;
+        wtxid?: string;
+        allowed: boolean;
+        rejectReason?: string;
+        rejectDetails?: string;
+    }>> {
+        return this.callRpc('testmempoolaccept', [
+            rawTransactions.map(tx => tx.toString('hex')),
+        ]);
+    }
+
     private async callRpc<T>(method: string, params: unknown[] = []): Promise<T> {
         const response = await this.client.post('', {
             jsonrpc: '1.0',
@@ -181,6 +265,14 @@ export class BitcoinRpcService implements OnModuleInit {
         return response.data.result;
     }
 
+    private calculateNetworkDifficulty(nBits: number) {
+        const mantissa: number = nBits & 0x007fffff;
+        const exponent: number = (nBits >> 24) & 0xff;
+        const target: number = mantissa * Math.pow(256, (exponent - 3));
+        const maxTarget = Math.pow(2, 208) * 65535;
+        return maxTarget / target;
+    }
+
     private buildRpcUrl(url: string, port: number): string {
         const normalizedUrl = /^https?:\/\//i.test(url) ? url : `http://${url}`;
         const rpcUrl = new URL(normalizedUrl);

src/services/custom-work.service.spec.ts

@@ -0,0 +1,94 @@
+import { CustomWorkService } from './custom-work.service';
+
+describe('CustomWorkService', () => {
+    const service = new CustomWorkService();
+
+    it('builds SV2 custom-job coinbase splits around the extranonce', () => {
+        const split = service.buildSv2CoinbaseSplit({
+            channelId: 1,
+            requestId: 2,
+            token: Buffer.from('01', 'hex'),
+            version: 0x20000000,
+            prevHash: Buffer.alloc(32),
+            minNtime: 1,
+            nBits: 0x170fffff,
+            coinbaseTxVersion: 2,
+            coinbasePrefix: Buffer.from('51', 'hex'),
+            coinbaseTxInputNSequence: 0xffffffff,
+            coinbaseTxOutputs: Buffer.from('010000000000000000016a', 'hex'),
+            coinbaseTxLocktime: 0,
+            merklePath: [],
+        }, 12);
+
+        expect(split.coinbasePrefix.subarray(0, 4).toString('hex')).toBe('02000000');
+        expect(split.coinbasePrefix.includes(Buffer.from([13]))).toBe(true);
+        expect(split.coinbasePrefix.subarray(-1).toString('hex')).toBe('51');
+        expect(split.coinbaseSuffix.subarray(0, 4).toString('hex')).toBe('ffffffff');
+        expect(split.coinbaseSuffix.subarray(-4).toString('hex')).toBe('00000000');
+    });
+
+    it('encodes Bitcoin varints at boundary values', () => {
+        expect(service.encodeBitcoinVarInt(0xfc).toString('hex')).toBe('fc');
+        expect(service.encodeBitcoinVarInt(0xfd).toString('hex')).toBe('fdfd00');
+        expect(service.encodeBitcoinVarInt(0xffff).toString('hex')).toBe('fdffff');
+        expect(service.encodeBitcoinVarInt(0x10000).toString('hex')).toBe('fe00000100');
+    });
+
+    it('validates a trivial custom share against a very easy target', () => {
+        const result = service.validateShare({
+            coinbasePrefix: Buffer.from('0200000001000000000000000000000000000000000000000000000000000000000000000000000000ffffffff01', 'hex'),
+            coinbaseSuffix: Buffer.from('ffffffff010000000000000000016a00000000', 'hex'),
+            merklePath: [],
+            extranoncePrefix: Buffer.alloc(4),
+            extranonce: Buffer.alloc(8),
+            prevHash: Buffer.alloc(32),
+            nBits: 0x207fffff,
+            version: 0x20000000,
+            ntime: 1,
+            nonce: 1,
+            shareDifficulty: 0.00000001,
+            networkDifficulty: Number.MAX_SAFE_INTEGER,
+        });
+
+        expect(result.header).toHaveLength(80);
+        expect(result.merkleRoot).toHaveLength(32);
+        expect(result.submissionDifficulty).toBeGreaterThan(0);
+        expect(result.accepted).toBe(true);
+        expect(result.isBlockCandidate).toBe(false);
+    });
+
+    it('patches DATUM coinbase target byte before computing the merkle root', () => {
+        const baseInput = {
+            coinbasePrefix: Buffer.from('02000000ff', 'hex'),
+            coinbaseSuffix: Buffer.from('ffffffff010000000000000000016a00000000', 'hex'),
+            merklePath: [],
+            extranoncePrefix: Buffer.alloc(0),
+            extranonce: Buffer.alloc(12),
+            prevHash: Buffer.alloc(32),
+            nBits: 0x207fffff,
+            version: 0x20000000,
+            ntime: 1,
+            nonce: 1,
+            shareDifficulty: 0.00000001,
+            networkDifficulty: Number.MAX_SAFE_INTEGER,
+        };
+
+        const placeholder = service.validateShare(baseInput);
+        const patched = service.validateShare({
+            ...baseInput,
+            coinbaseTargetByteIndex: 4,
+            coinbaseTargetByte: 0x12,
+        });
+        const manuallyPatched = service.computeMerkleRoot(
+            Buffer.concat([
+                Buffer.from('0200000012', 'hex'),
+                Buffer.alloc(12),
+                baseInput.coinbaseSuffix,
+            ]),
+            [],
+        );
+
+        expect(patched.merkleRoot.equals(placeholder.merkleRoot)).toBe(false);
+        expect(patched.merkleRoot.equals(manuallyPatched)).toBe(true);
+    });
+});

src/services/custom-work.service.ts

@@ -0,0 +1,161 @@
+import { Injectable } from '@nestjs/common';
+import { BufferReader } from '../models/sv2/sv2-binary-codec';
+import { Sv2SetCustomMiningJob } from '../models/sv2/sv2-jdp-messages';
+import { DifficultyUtils } from '../utils/difficulty.utils';
+import { hash256 } from '../utils/hash.utils';
+
+export interface CustomWorkCoinbaseSplit {
+    coinbasePrefix: Buffer;
+    coinbaseSuffix: Buffer;
+}
+
+export interface CustomWorkShareValidationInput {
+    coinbasePrefix: Buffer;
+    coinbaseSuffix: Buffer;
+    coinbaseTargetByteIndex?: number;
+    coinbaseTargetByte?: number;
+    merklePath: Buffer[];
+    extranoncePrefix: Buffer;
+    extranonce: Buffer;
+    prevHash: Buffer;
+    nBits: number;
+    version: number;
+    ntime: number;
+    nonce: number;
+    shareDifficulty: number;
+    networkDifficulty: number;
+}
+
+export interface CustomWorkShareValidationResult {
+    header: Buffer;
+    merkleRoot: Buffer;
+    hashBuffer: Buffer;
+    submissionDifficulty: number;
+    accepted: boolean;
+    isBlockCandidate: boolean;
+}
+
+@Injectable()
+export class CustomWorkService {
+    public buildSv2CoinbaseSplit(job: Sv2SetCustomMiningJob, totalExtranonceSize: number): CustomWorkCoinbaseSplit {
+        const scriptSigLen = job.coinbasePrefix.length + totalExtranonceSize;
+        const scriptSigLenVarint = this.encodeBitcoinVarInt(scriptSigLen);
+
+        const txVersion = Buffer.alloc(4);
+        txVersion.writeUInt32LE(job.coinbaseTxVersion >>> 0, 0);
+
+        const nullOutpoint = Buffer.alloc(36);
+        nullOutpoint.writeUInt32LE(0xffffffff, 32);
+
+        const sequence = Buffer.alloc(4);
+        sequence.writeUInt32LE(job.coinbaseTxInputNSequence >>> 0, 0);
+
+        const locktime = Buffer.alloc(4);
+        locktime.writeUInt32LE(job.coinbaseTxLocktime >>> 0, 0);
+
+        return {
+            coinbasePrefix: Buffer.concat([
+                txVersion,
+                Buffer.from([0x01]),
+                nullOutpoint,
+                scriptSigLenVarint,
+                job.coinbasePrefix,
+            ]),
+            coinbaseSuffix: Buffer.concat([
+                sequence,
+                job.coinbaseTxOutputs,
+                locktime,
+            ]),
+        };
+    }
+
+    public validateShare(input: CustomWorkShareValidationInput): CustomWorkShareValidationResult {
+        const coinbaseTx = Buffer.concat([
+            input.coinbasePrefix,
+            input.extranoncePrefix,
+            input.extranonce,
+            input.coinbaseSuffix,
+        ]);
+        if (input.coinbaseTargetByteIndex != null || input.coinbaseTargetByte != null) {
+            if (input.coinbaseTargetByteIndex == null || input.coinbaseTargetByte == null) {
+                throw new RangeError('Both coinbase target byte index and value are required');
+            }
+            if (input.coinbaseTargetByteIndex < 0 || input.coinbaseTargetByteIndex >= coinbaseTx.length) {
+                throw new RangeError(`Coinbase target byte index ${input.coinbaseTargetByteIndex} is outside coinbase length ${coinbaseTx.length}`);
+            }
+            coinbaseTx[input.coinbaseTargetByteIndex] = input.coinbaseTargetByte & 0xff;
+        }
+        const merkleRoot = this.computeMerkleRoot(coinbaseTx, input.merklePath);
+        const header = this.buildHeader(input.prevHash, merkleRoot, input.version, input.ntime, input.nBits, input.nonce);
+        const { submissionDifficulty, hashBuffer } = DifficultyUtils.calculateDifficulty(header);
+
+        return {
+            header,
+            merkleRoot,
+            hashBuffer,
+            submissionDifficulty,
+            accepted: DifficultyUtils.meetsTarget(hashBuffer, DifficultyUtils.difficultyToTarget(input.shareDifficulty)),
+            isBlockCandidate: DifficultyUtils.meetsTarget(hashBuffer, DifficultyUtils.difficultyToTarget(input.networkDifficulty)),
+        };
+    }
+
+    public computeMerkleRoot(coinbaseTx: Buffer, merklePath: Buffer[]): Buffer {
+        let merkleRoot = hash256(coinbaseTx);
+        const pair = Buffer.alloc(64);
+        for (const sibling of merklePath) {
+            pair.fill(0);
+            merkleRoot.copy(pair, 0);
+            sibling.copy(pair, 32);
+            merkleRoot = hash256(pair);
+        }
+        return merkleRoot;
+    }
+
+    public buildHeader(prevHash: Buffer, merkleRoot: Buffer, version: number, timestamp: number, nBits: number, nonce: number): Buffer {
+        const header = Buffer.alloc(80);
+        header.writeInt32LE(version, 0);
+        prevHash.copy(header, 4);
+        merkleRoot.copy(header, 36);
+        header.writeUInt32LE(timestamp >>> 0, 68);
+        header.writeUInt32LE(nBits >>> 0, 72);
+        header.writeUInt32LE(nonce >>> 0, 76);
+        return header;
+    }
+
+    public encodeBitcoinVarInt(value: number): Buffer {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new RangeError(`Invalid Bitcoin varint value ${value}`);
+        }
+        if (value < 0xfd) {
+            return Buffer.from([value]);
+        }
+        if (value <= 0xffff) {
+            const result = Buffer.alloc(3);
+            result[0] = 0xfd;
+            result.writeUInt16LE(value, 1);
+            return result;
+        }
+        if (value <= 0xffffffff) {
+            const result = Buffer.alloc(5);
+            result[0] = 0xfe;
+            result.writeUInt32LE(value, 1);
+            return result;
+        }
+        const result = Buffer.alloc(9);
+        result[0] = 0xff;
+        result.writeBigUInt64LE(BigInt(value), 1);
+        return result;
+    }
+
+    public readDatumNullTerminatedString(reader: BufferReader): string {
+        const bytes: number[] = [];
+        while (reader.remaining > 0) {
+            const byte = reader.readU8();
+            if (byte === 0) {
+                break;
+            }
+            bytes.push(byte);
+        }
+        return Buffer.from(bytes).toString('utf8');
+    }
+}

src/services/datum.service.spec.ts

@@ -0,0 +1,156 @@
+import { Socket } from 'net';
+import { DatumProtocolCommand } from '../models/datum/datum-codec';
+import { DatumService } from './datum.service';
+import { TemplateProviderService } from './template-provider.service';
+
+function createService(): DatumService {
+    const templateProvider = {
+        validateTransactionData: jest.fn(({ transactionList, expectedCount, maxTotalBytes }) => {
+            if (expectedCount != null && transactionList.length !== expectedCount) {
+                return { valid: false, errorCode: 'transaction-count-mismatch' };
+            }
+            const totalBytes = transactionList.reduce((sum: number, tx: Buffer) => sum + tx.length, 0);
+            if (maxTotalBytes != null && totalBytes > maxTotalBytes) {
+                return { valid: false, errorCode: 'transaction-bytes-exceed-limit' };
+            }
+            return { valid: true, totalBytes };
+        }),
+    };
+    return new DatumService(
+        {} as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        templateProvider as unknown as TemplateProviderService,
+        undefined,
+    );
+}
+
+function createSocket(): Socket {
+    return {
+        destroyed: false,
+        writableEnded: false,
+        write: jest.fn((_data: Buffer, callback: (error?: Error) => void) => callback()),
+    } as any;
+}
+
+function createState(cache: any): any {
+    return {
+        sessionId: 'datum-test',
+        session: {
+            encryptChannelFrame: jest.fn((_command: DatumProtocolCommand, payload: Buffer) => payload),
+        },
+        datumJobs: new Map([[7, cache]]),
+    };
+}
+
+describe('DatumService job validation', () => {
+    it('requests short transaction IDs once a DATUM job advertises transactions', async () => {
+        const service = createService() as any;
+        const socket = createSocket();
+        const cache: any = {
+            transactionCount: 2,
+            coinbasePairs: new Map(),
+        };
+        const state = createState(cache);
+
+        await service.maybeRequestDatumJobValidation(socket, state, 7, cache);
+
+        expect(cache.validationState).toBe('requested-short-txids');
+        expect((socket.write as jest.Mock).mock.calls[0][0].toString('hex')).toBe('501007');
+        expect(state.session.encryptChannelFrame).toHaveBeenCalledWith(DatumProtocolCommand.MINING, expect.any(Buffer));
+    });
+
+    it('follows short transaction IDs with a full transaction blob request', async () => {
+        const service = createService() as any;
+        const socket = createSocket();
+        const cache: any = {
+            transactionCount: 1,
+            coinbasePairs: new Map(),
+        };
+        const state = createState(cache);
+        const shortIdsResponse = Buffer.concat([
+            Buffer.from([0x90, 7, 0x01]),
+            Buffer.from('0100', 'hex'),
+            Buffer.from('010203040506', 'hex'),
+            Buffer.alloc(32, 0xaa),
+            Buffer.from([0xfe]),
+        ]);
+
+        await service.handleJobValidationResponse(socket, state, shortIdsResponse);
+
+        expect(cache.validationState).toBe('requested-full-transaction-blob');
+        expect(cache.validationShortTxIds.map((id: Buffer) => id.toString('hex'))).toEqual(['010203040506']);
+        expect((socket.write as jest.Mock).mock.calls[0][0].toString('hex')).toBe('501207');
+    });
+
+    it('fails DATUM job validation when short transaction ID counts disagree', async () => {
+        const service = createService() as any;
+        const socket = createSocket();
+        const warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+        const cache: any = {
+            transactionCount: 2,
+            coinbasePairs: new Map(),
+        };
+        const state = createState(cache);
+        const shortIdsResponse = Buffer.concat([
+            Buffer.from([0x90, 7, 0x01]),
+            Buffer.from('0100', 'hex'),
+            Buffer.from('010203040506', 'hex'),
+            Buffer.alloc(32, 0xaa),
+            Buffer.from([0xfe]),
+        ]);
+
+        await service.handleJobValidationResponse(socket, state, shortIdsResponse);
+
+        expect(cache.validationState).toBe('failed');
+        expect(cache.validationError).toBe('short txid count mismatch: advertised 2, received 1');
+        expect(socket.write).not.toHaveBeenCalled();
+        warn.mockRestore();
+    });
+
+    it('validates and caches full DATUM transaction blobs', async () => {
+        const service = createService() as any;
+        const socket = createSocket();
+        const tx = Buffer.from(
+            '0100000001'
+            + '0000000000000000000000000000000000000000000000000000000000000000'
+            + 'ffffffff00ffffffff'
+            + '01000000000000000000'
+            + '00000000',
+            'hex',
+        );
+        const txSize = Buffer.alloc(3);
+        txSize.writeUIntLE(tx.length, 0, 3);
+        const cache: any = {
+            transactionCount: 1,
+            totalSize: tx.length,
+            merkleBranches: [Buffer.alloc(32, 0xbb)],
+            coinbasePairs: new Map(),
+        };
+        const state = createState(cache);
+        const fullBlobResponse = Buffer.concat([
+            Buffer.from([0x92, 7, 0x01]),
+            Buffer.from('0100', 'hex'),
+            txSize,
+            tx,
+            Buffer.from([0xfe]),
+        ]);
+
+        await service.handleJobValidationResponse(socket, state, fullBlobResponse);
+
+        expect(cache.validationState).toBe('validated');
+        expect(cache.validationTransactions).toEqual([tx]);
+        expect(cache.validationError).toBeUndefined();
+        expect((service as any).templateProvider.validateTransactionData).toHaveBeenCalledWith({
+            transactionList: [tx],
+            expectedCount: 1,
+            maxTotalBytes: tx.length,
+            expectedCoinbaseMerklePath: [Buffer.alloc(32, 0xbb)],
+        });
+        expect(socket.write).not.toHaveBeenCalled();
+    });
+});

src/services/datum.service.ts

@@ -0,0 +1,722 @@
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { getAddressInfo } from 'bitcoin-address-validation';
+import * as bitcoinjs from 'bitcoinjs-lib';
+import { firstValueFrom } from 'rxjs';
+import { Server, Socket } from 'net';
+
+import { BlocksService } from '../ORM/blocks/blocks.service';
+import { ClientEntity } from '../ORM/client/client.entity';
+import { ClientService } from '../ORM/client/client.service';
+import { ShareAccountingService } from '../ORM/share-accounting/share-accounting.service';
+import {
+    DATUM_INITIAL_HEADER_KEY,
+    DatumFrameReader,
+    DatumMiningCommand,
+    DatumProtocolCommand,
+    DatumRejectReason,
+    DatumShareResponseStatus,
+    DatumPowSubmit,
+    DatumJobValidationStatus,
+    DatumJobValidationResponse,
+    deserializeDatumCoinbaserFetch,
+    deserializeDatumJobValidationResponse,
+    deserializeDatumMiningCommand,
+    deserializeDatumPowSubmit,
+    encodeDatumFrame,
+    serializeDatumJobValidationFullTransactionBlobRequest,
+    serializeDatumJobValidationShortTxIdsRequest,
+    serializeDatumCoinbaserFetchResponse,
+    serializeDatumShareResponse,
+} from '../models/datum/datum-codec';
+import { DatumCryptoSession } from '../models/datum/datum-crypto';
+import { BitcoinRpcService } from './bitcoin-rpc.service';
+import { CustomWorkService } from './custom-work.service';
+import { RedisMessagingService } from './redis-messaging.service';
+import { StratumV1JobsService } from './stratum-v1-jobs.service';
+import { DatumKeyPair } from '../models/datum/datum-crypto';
+import { TemplateProviderService } from './template-provider.service';
+
+const DEFAULT_DATUM_SHARE_DIFFICULTY = 1;
+const DEFAULT_DATUM_PING_INTERVAL_MS = 30_000;
+
+@Injectable()
+export class DatumService implements OnModuleInit {
+    private readonly servers: Server[] = [];
+    private identityKeys: DatumKeyPair | null = null;
+
+    constructor(
+        private readonly configService: ConfigService,
+        private readonly jobsService: StratumV1JobsService,
+        private readonly bitcoinRpcService: BitcoinRpcService,
+        private readonly clientService: ClientService,
+        private readonly blocksService: BlocksService,
+        private readonly shareAccountingService: ShareAccountingService,
+        private readonly customWorkService: CustomWorkService,
+        private readonly templateProvider: TemplateProviderService,
+        private readonly redisMessagingService?: RedisMessagingService,
+    ) {}
+
+    public async onModuleInit(): Promise<void> {
+        if (process.env.API_ONLY === 'true' || process.env.MASTER === 'true') {
+            return;
+        }
+
+        const ports = this.getPorts();
+        if (ports.length === 0) {
+            return;
+        }
+
+        this.identityKeys = this.getIdentityKeys();
+        console.log(`DATUM server public key: ${Buffer.concat([this.identityKeys.edPublicKey, this.identityKeys.xPublicKey]).toString('hex')}`);
+
+        for (const port of ports) {
+            await this.startServer(port);
+        }
+    }
+
+    private async startServer(port: number): Promise<void> {
+        const server = new Server(socket => {
+            void this.handleSocket(socket);
+        });
+        server.on('error', error => {
+            console.error(`DATUM server error on port ${port}: ${error.message}`);
+        });
+        server.listen(port, () => {
+            console.log(`DATUM server is listening on port ${port}`);
+        });
+        this.servers.push(server);
+    }
+
+    private async handleSocket(socket: Socket): Promise<void> {
+        socket.setKeepAlive(true, 60_000);
+        socket.setNoDelay(true);
+
+        const session = await DatumCryptoSession.create(this.identityKeys ?? undefined);
+        const reader = new DatumFrameReader(DATUM_INITIAL_HEADER_KEY);
+        const state: DatumClientState = {
+            sessionId: Math.random().toString(16).slice(2, 10),
+            session,
+            clientEntity: null,
+            address: null,
+            workerName: 'default',
+            userAgent: 'datum/unknown',
+            pingTimer: null,
+            datumJobs: new Map(),
+        };
+        console.log(`[DATUM ${state.sessionId}] connection accepted from ${socket.remoteAddress}:${socket.remotePort}`);
+
+        const close = () => {
+            void this.destroyClient(state);
+            if (!socket.destroyed) {
+                socket.destroy();
+            }
+        };
+
+        socket.on('data', data => {
+            void (async () => {
+                try {
+                    reader.setHeaderXorKey(session.currentReceiveHeaderKey);
+                    const frames = reader.feed(data);
+                    for (const frame of frames) {
+                        let payload = frame.payload;
+                        if (frame.header.isEncryptedChannel) {
+                            payload = session.decryptChannelPayload(payload);
+                        }
+                        await this.handleFrame(socket, state, frame.header.protoCmd, payload);
+                        reader.setHeaderXorKey(session.currentReceiveHeaderKey);
+                    }
+                } catch (error) {
+                    console.error(`[DATUM ${state.sessionId}] ${error.message}`);
+                    close();
+                }
+            })();
+        });
+        socket.on('error', close);
+        socket.on('close', () => void this.destroyClient(state));
+    }
+
+    private async handleFrame(socket: Socket, state: DatumClientState, protoCmd: number, payload: Buffer): Promise<void> {
+        if (protoCmd === DatumProtocolCommand.HANDSHAKE_INIT) {
+            const hello = state.session.openHandshake(payload);
+            state.userAgent = hello.userAgent || 'datum/unknown';
+            console.log(`[DATUM ${state.sessionId}] handshake init from ${state.userAgent}`);
+            await this.writeRaw(socket, state.session.buildHandshakeResponse(hello, 'public-pool DATUM'));
+            console.log(`[DATUM ${state.sessionId}] handshake response sent`);
+            await this.sendDatumClientConfigure(socket, state);
+            console.log(`[DATUM ${state.sessionId}] client configure sent`);
+            this.startDatumPing(socket, state);
+            return;
+        }
+
+        if (protoCmd !== DatumProtocolCommand.MINING) {
+            return;
+        }
+
+        const mining = deserializeDatumMiningCommand(payload);
+        switch (mining.command) {
+            case DatumMiningCommand.FETCH_COINBASER:
+                await this.handleCoinbaserFetch(socket, state, mining.body);
+                break;
+            case DatumMiningCommand.SUBMIT_POW:
+                await this.handlePowSubmit(socket, state, mining.body);
+                break;
+            case DatumMiningCommand.JOB_VALIDATION:
+                await this.handleJobValidationResponse(socket, state, mining.body);
+                break;
+            case DatumMiningCommand.TEMPLATE_REFRESH:
+                break;
+            default:
+                console.warn(`[DATUM ${state.sessionId}] Ignoring unsupported mining command 0x${mining.command.toString(16)}`);
+                break;
+        }
+    }
+
+    private async sendDatumClientConfigure(socket: Socket, state: DatumClientState): Promise<void> {
+        const payoutAddress = this.getDatumPoolPayoutAddress();
+        if (!payoutAddress) {
+            throw new Error('DATUM_POOL_PAYOUT_ADDRESS or DEV_FEE_ADDRESS must be set before DATUM client configuration can be sent');
+        }
+
+        const payoutScript = bitcoinjs.address.toOutputScript(payoutAddress, this.getNetwork());
+        if (payoutScript.length > 255) {
+            throw new Error(`DATUM payout script is too long: ${payoutScript.length}`);
+        }
+
+        const coinbaseTag = Buffer.from('public-pool', 'utf8');
+        if (coinbaseTag.length > 255) {
+            throw new Error(`DATUM coinbase tag is too long: ${coinbaseTag.length}`);
+        }
+
+        const minDifficulty = Math.max(1, Math.floor(this.getDatumShareDifficulty()));
+        const vardiffMin = 1n << BigInt(Math.ceil(Math.log2(minDifficulty)));
+        const vardiffMinBuffer = Buffer.alloc(8);
+        vardiffMinBuffer.writeBigUInt64LE(vardiffMin, 0);
+
+        const payload = Buffer.concat([
+            Buffer.from([DatumMiningCommand.CLIENT_CONFIGURE]),
+            Buffer.from([1, payoutScript.length]),
+            payoutScript,
+            uint32le(0x50554250),
+            Buffer.from([coinbaseTag.length]),
+            coinbaseTag,
+            vardiffMinBuffer,
+            Buffer.from([0, 0xfe]),
+        ]);
+        await this.writeRaw(socket, state.session.encryptChannelFrame(DatumProtocolCommand.MINING, payload, true));
+    }
+
+    private async handleCoinbaserFetch(socket: Socket, state: DatumClientState, payload: Buffer): Promise<void> {
+        const fetch = deserializeDatumCoinbaserFetch(payload);
+        const payoutAddress = this.getDatumPoolPayoutAddress();
+        if (!payoutAddress) {
+            throw new Error('DATUM_POOL_PAYOUT_ADDRESS or DEV_FEE_ADDRESS must be set before DATUM coinbaser fetches can be served');
+        }
+
+        const scriptPubKey = bitcoinjs.address.toOutputScript(payoutAddress, this.getNetwork());
+        const response = serializeDatumCoinbaserFetchResponse(fetch.rewardValue, [{
+            value: fetch.rewardValue,
+            scriptPubKey,
+        }]);
+        await this.writeRaw(socket, state.session.encryptChannelFrame(DatumProtocolCommand.MINING, response));
+    }
+
+    private async handlePowSubmit(socket: Socket, state: DatumClientState, payload: Buffer): Promise<void> {
+        const pow = deserializeDatumPowSubmit(payload);
+        const { address, workerName } = this.parseUserIdentity(pow.username);
+        if (!this.isValidAddress(address)) {
+            await this.sendShareResponse(socket, state, DatumShareResponseStatus.REJECTED, DatumRejectReason.BAD_USERNAME, pow.nonce, pow.targetByte, pow.jobId);
+            return;
+        }
+
+        state.address = address;
+        state.workerName = workerName;
+        await this.ensureClientEntity(state);
+
+        const datumJob = this.updateDatumJobCache(state, pow);
+        await this.maybeRequestDatumJobValidation(socket, state, pow.jobId, datumJob);
+        const coinbase = this.getDatumCoinbase(datumJob, pow);
+        if (coinbase == null || datumJob.prevBlockHash == null || datumJob.nBits == null || datumJob.merkleBranches == null) {
+            await this.sendShareResponse(socket, state, DatumShareResponseStatus.REJECTED, DatumRejectReason.COINBASE_MISSING, pow.nonce, pow.targetByte, pow.jobId);
+            return;
+        }
+        if (datumJob.targetByteIndex == null) {
+            await this.sendShareResponse(socket, state, DatumShareResponseStatus.REJECTED, DatumRejectReason.BAD_TARGET, pow.nonce, pow.targetByte, pow.jobId);
+            return;
+        }
+
+        const latestTemplate = await firstValueFrom(this.jobsService.newMiningJob$);
+        const templateValidation = this.templateProvider.validateDatumTemplateFastPath({
+            prevBlockHash: datumJob.prevBlockHash,
+            nBits: datumJob.nBits,
+            height: datumJob.height,
+            version: pow.version,
+            coinbaseValue: datumJob.coinbaseValue,
+            totalWeight: datumJob.totalWeight,
+            totalSize: datumJob.totalSize,
+            totalSigops: datumJob.totalSigops,
+            merkleBranches: datumJob.merkleBranches,
+        });
+        if (!templateValidation.valid) {
+            await this.sendShareResponse(
+                socket,
+                state,
+                DatumShareResponseStatus.REJECTED,
+                this.mapDatumTemplateRejectReason(templateValidation.errorCode),
+                pow.nonce,
+                pow.targetByte,
+                pow.jobId,
+            );
+            return;
+        }
+        if (datumJob.validationState === 'failed') {
+            await this.sendShareResponse(socket, state, DatumShareResponseStatus.REJECTED, DatumRejectReason.OTHER, pow.nonce, pow.targetByte, pow.jobId);
+            return;
+        }
+
+        const shareDifficulty = this.getDatumShareDifficulty();
+        const nBits = datumJob.nBits.readUInt32LE(0);
+        const validation = this.customWorkService.validateShare({
+            coinbasePrefix: coinbase.coinb1,
+            coinbaseSuffix: coinbase.coinb2,
+            coinbaseTargetByteIndex: datumJob.targetByteIndex,
+            coinbaseTargetByte: pow.targetByte,
+            merklePath: datumJob.merkleBranches,
+            extranoncePrefix: Buffer.alloc(0),
+            extranonce: pow.extranonce,
+            prevHash: datumJob.prevBlockHash,
+            nBits,
+            version: pow.version,
+            ntime: pow.ntime,
+            nonce: pow.nonce,
+            shareDifficulty,
+            networkDifficulty: latestTemplate.blockData.networkDifficulty,
+        });
+
+        if (!validation.accepted) {
+            await this.sendShareResponse(socket, state, DatumShareResponseStatus.REJECTED, DatumRejectReason.HIGH_HASH, pow.nonce, pow.targetByte, pow.jobId);
+            return;
+        }
+
+        const isBlockCandidate = validation.isBlockCandidate || pow.isBlock;
+        const blockSubmissionResult = validation.isBlockCandidate ? 'datum-gateway-submit-expected' : null;
+
+        await this.sendShareResponse(socket, state, DatumShareResponseStatus.ACCEPTED, 0, pow.nonce, pow.targetByte, pow.jobId);
+        if (isBlockCandidate) {
+            await this.blocksService.save({
+                height: datumJob.height ?? latestTemplate.blockData.height,
+                minerAddress: address,
+                worker: workerName,
+                sessionId: state.sessionId,
+                blockData: validation.header.toString('hex'),
+                blockSubmissionResult,
+                payoutSnapshotId: null,
+            });
+        }
+        await this.shareAccountingService.recordAcceptedShare({
+            protocol: 'datum',
+            workSource: 'miner_template',
+            workProtocol: 'datum',
+            address,
+            clientName: workerName,
+            sessionId: state.sessionId,
+            clientId: state.clientEntity.id,
+            jobId: pow.jobId.toString(16),
+            jobTemplateId: latestTemplate.blockData.id,
+            blockHeight: datumJob.height ?? latestTemplate.blockData.height,
+            creditedDifficulty: shareDifficulty,
+            submissionDifficulty: validation.submissionDifficulty,
+            networkDifficulty: latestTemplate.blockData.networkDifficulty,
+            nonce: pow.nonce,
+            ntime: pow.ntime,
+            version: pow.version,
+            extraNonce2: pow.extranonce.toString('hex'),
+            isBlockCandidate,
+            blockSubmissionResult,
+        });
+        await this.redisMessagingService?.setClientPresence({
+            clientId: state.clientEntity.id,
+            address,
+            clientName: workerName,
+            sessionId: state.sessionId,
+            userAgent: state.userAgent,
+            startTime: new Date(state.clientEntity.startTime).toISOString(),
+            lastSeen: new Date().toISOString(),
+            hashRate: 0,
+            bestDifficulty: validation.submissionDifficulty,
+        });
+    }
+
+    private updateDatumJobCache(state: DatumClientState, pow: DatumPowSubmit): DatumJobCache {
+        let cache = state.datumJobs.get(pow.jobId);
+        if (cache == null || pow.prevBlockHash != null) {
+            cache = {
+                coinbasePairs: new Map(),
+            };
+            state.datumJobs.set(pow.jobId, cache);
+        }
+
+        if (pow.prevBlockHash != null) {
+            cache.prevBlockHash = pow.prevBlockHash;
+        }
+        if (pow.targetByteIndex != null) {
+            cache.targetByteIndex = pow.targetByteIndex;
+        }
+        if (pow.nBits != null) {
+            cache.nBits = pow.nBits;
+        }
+        if (pow.coinbaserId != null) {
+            cache.coinbaserId = pow.coinbaserId;
+        }
+        if (pow.height != null) {
+            cache.height = pow.height;
+        }
+        if (pow.coinbaseValue != null) {
+            cache.coinbaseValue = pow.coinbaseValue;
+        }
+        if (pow.transactionCount != null) {
+            cache.transactionCount = pow.transactionCount;
+        }
+        if (pow.totalWeight != null) {
+            cache.totalWeight = pow.totalWeight;
+        }
+        if (pow.totalSize != null) {
+            cache.totalSize = pow.totalSize;
+        }
+        if (pow.totalSigops != null) {
+            cache.totalSigops = pow.totalSigops;
+        }
+        if (pow.merkleBranches != null) {
+            cache.merkleBranches = pow.merkleBranches;
+        }
+        for (const [coinbaseId, coinbase] of pow.coinbasePairs) {
+            cache.coinbasePairs.set(coinbaseId, coinbase);
+        }
+        if (pow.subsidyOnlyCoinbase != null) {
+            cache.subsidyOnlyCoinbase = pow.subsidyOnlyCoinbase;
+        }
+
+        return cache;
+    }
+
+    private async maybeRequestDatumJobValidation(
+        socket: Socket,
+        state: DatumClientState,
+        jobId: number,
+        cache: DatumJobCache,
+    ): Promise<void> {
+        if (cache.transactionCount == null || cache.validationState != null) {
+            return;
+        }
+        if (cache.transactionCount === 0) {
+            cache.validationState = 'validated';
+            cache.validationTransactions = [];
+            return;
+        }
+
+        cache.validationState = 'requested-short-txids';
+        cache.validationRequestedAt = new Date();
+        await this.writeRaw(
+            socket,
+            state.session.encryptChannelFrame(
+                DatumProtocolCommand.MINING,
+                serializeDatumJobValidationShortTxIdsRequest(jobId),
+            ),
+        );
+    }
+
+    private async handleJobValidationResponse(socket: Socket, state: DatumClientState, payload: Buffer): Promise<void> {
+        const response = deserializeDatumJobValidationResponse(payload);
+        const cache = state.datumJobs.get(response.jobId);
+        if (cache == null) {
+            console.warn(`[DATUM ${state.sessionId}] Ignoring validation response for unknown job ${response.jobId}`);
+            return;
+        }
+
+        if (response.status !== DatumJobValidationStatus.SUCCESS) {
+            cache.validationState = 'failed';
+            cache.validationError = `gateway returned status 0x${response.status.toString(16)}`;
+            console.warn(`[DATUM ${state.sessionId}] Job ${response.jobId} validation failed: ${cache.validationError}`);
+            return;
+        }
+
+        if (response.kind === 'short-txids') {
+            if (cache.transactionCount != null && response.transactionCount !== cache.transactionCount) {
+                cache.validationState = 'failed';
+                cache.validationError = `short txid count mismatch: advertised ${cache.transactionCount}, received ${response.transactionCount}`;
+                console.warn(`[DATUM ${state.sessionId}] Job ${response.jobId} validation failed: ${cache.validationError}`);
+                return;
+            }
+            cache.validationShortTxIds = response.shortTxIds;
+            cache.validationShortTxCrosscheck = response.crosscheck ?? undefined;
+            cache.validationState = 'requested-full-transaction-blob';
+            await this.writeRaw(
+                socket,
+                state.session.encryptChannelFrame(
+                    DatumProtocolCommand.MINING,
+                    serializeDatumJobValidationFullTransactionBlobRequest(response.jobId),
+                ),
+            );
+            return;
+        }
+
+        if (response.kind === 'full-transaction-blob' || response.kind === 'full-transactions') {
+            const validationError = this.validateDatumTransactionResponse(cache, response);
+            if (validationError != null) {
+                cache.validationState = 'failed';
+                cache.validationError = validationError;
+                console.warn(`[DATUM ${state.sessionId}] Job ${response.jobId} transaction validation failed: ${validationError}`);
+                return;
+            }
+
+            cache.validationState = 'validated';
+            cache.validationError = undefined;
+            cache.validationTransactions = response.transactions;
+            cache.validationCompletedAt = new Date();
+        }
+    }
+
+    private validateDatumTransactionResponse(
+        cache: DatumJobCache,
+        response: DatumJobValidationResponse,
+    ): string | null {
+        if (response.kind === 'short-txids') {
+            return null;
+        }
+        if (cache.transactionCount != null && response.transactionCount !== cache.transactionCount) {
+            return `transaction count mismatch: advertised ${cache.transactionCount}, received ${response.transactionCount}`;
+        }
+
+        const validation = this.templateProvider.validateTransactionData({
+            transactionList: response.transactions,
+            expectedCount: cache.transactionCount,
+            maxTotalBytes: cache.totalSize,
+            expectedCoinbaseMerklePath: cache.merkleBranches,
+        });
+        if (!validation.valid) {
+            return validation.errorCode ?? 'invalid-transaction-data';
+        }
+
+        return null;
+    }
+
+    private getDatumCoinbase(cache: DatumJobCache, pow: DatumPowSubmit): { coinb1: Buffer; coinb2: Buffer } | undefined {
+        if (pow.subsidyOnly) {
+            return cache.subsidyOnlyCoinbase ?? cache.coinbasePairs.get(pow.coinbaseId);
+        }
+        return cache.coinbasePairs.get(pow.coinbaseId) ?? cache.subsidyOnlyCoinbase;
+    }
+
+    private async sendShareResponse(
+        socket: Socket,
+        state: DatumClientState,
+        status: DatumShareResponseStatus,
+        reasonCode: number,
+        nonce: number,
+        targetByte: number,
+        jobId: number,
+    ): Promise<void> {
+        const payload = serializeDatumShareResponse({ status, reasonCode, nonce, targetByte, jobId });
+        await this.writeRaw(socket, state.session.encryptChannelFrame(DatumProtocolCommand.MINING, payload));
+    }
+
+    private async ensureClientEntity(state: DatumClientState): Promise<void> {
+        if (state.clientEntity != null) {
+            return;
+        }
+        state.clientEntity = await this.clientService.insert({
+            sessionId: state.sessionId,
+            address: state.address,
+            clientName: state.workerName,
+            userAgent: state.userAgent,
+            startTime: new Date(),
+            bestDifficulty: 0,
+        });
+    }
+
+    private async destroyClient(state: DatumClientState): Promise<void> {
+        this.stopDatumPing(state);
+        if (state.clientEntity?.id == null) {
+            return;
+        }
+        await this.redisMessagingService?.removeClientPresence(state.clientEntity.id, state.clientEntity.address);
+        await this.clientService.delete(state.clientEntity.id);
+        state.clientEntity = null;
+    }
+
+    private startDatumPing(socket: Socket, state: DatumClientState): void {
+        this.stopDatumPing(state);
+        state.pingTimer = setInterval(() => {
+            if (socket.destroyed || socket.writableEnded) {
+                this.stopDatumPing(state);
+                return;
+            }
+            void this.writeRaw(
+                socket,
+                state.session.encryptChannelFrame(DatumProtocolCommand.PING, Buffer.alloc(0)),
+            ).catch(error => {
+                console.error(`[DATUM ${state.sessionId}] ping failed: ${error.message}`);
+                if (!socket.destroyed) {
+                    socket.destroy();
+                }
+            });
+        }, this.getDatumPingIntervalMs());
+        state.pingTimer.unref?.();
+    }
+
+    private stopDatumPing(state: DatumClientState): void {
+        if (state.pingTimer != null) {
+            clearInterval(state.pingTimer);
+            state.pingTimer = null;
+        }
+    }
+
+    private async writeRaw(socket: Socket, data: Buffer): Promise<void> {
+        if (socket.destroyed || socket.writableEnded) {
+            return;
+        }
+        await new Promise<void>((resolve, reject) => {
+            socket.write(data, error => error ? reject(error) : resolve());
+        });
+    }
+
+    private parseUserIdentity(userIdentity: string): { address: string; workerName: string } {
+        const parts = userIdentity.split('.');
+        const address = parts[0] ?? '';
+        return {
+            address: this.normalizeAddress(address),
+            workerName: parts.length > 1 ? parts.slice(1).join('.') : 'default',
+        };
+    }
+
+    private normalizeAddress(address: string): string {
+        if (/^(bc1|tb1|bcrt1)/i.test(address)) {
+            return address.toLowerCase();
+        }
+        return address;
+    }
+
+    private isValidAddress(address: string): boolean {
+        try {
+            getAddressInfo(address);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    private getDatumPoolPayoutAddress(): string {
+        return this.configService.get<string>('DATUM_POOL_PAYOUT_ADDRESS')
+            || this.configService.get<string>('PAYOUT_FEE_ADDRESS')
+            || this.configService.get<string>('DEV_FEE_ADDRESS')
+            || '';
+    }
+
+    private getDatumShareDifficulty(): number {
+        const configured = parseFloat(this.configService.get<string>('DATUM_SHARE_DIFFICULTY') ?? '');
+        return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_DATUM_SHARE_DIFFICULTY;
+    }
+
+    private mapDatumTemplateRejectReason(errorCode?: string): DatumRejectReason {
+        switch (errorCode) {
+            case 'prevhash-mismatch':
+            case 'height-mismatch':
+                return DatumRejectReason.STALE_BLOCK;
+            case 'nbits-mismatch':
+            case 'weight-limit-exceeded':
+            case 'size-limit-exceeded':
+            case 'sigop-limit-exceeded':
+            case 'coinbase-value-too-high':
+                return DatumRejectReason.OTHER;
+            case 'version-mismatch':
+                return DatumRejectReason.BAD_VERSION;
+            case 'bad-merkle-branch':
+                return DatumRejectReason.BAD_MERKLE_COUNT;
+            default:
+                return DatumRejectReason.OTHER;
+        }
+    }
+
+    private getDatumPingIntervalMs(): number {
+        const configured = parseInt(this.configService.get<string>('DATUM_PING_INTERVAL_MS') ?? '', 10);
+        return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_DATUM_PING_INTERVAL_MS;
+    }
+
+    private getIdentityKeys(): DatumKeyPair {
+        const seedHex = this.configService.get<string>('DATUM_IDENTITY_SEED')?.trim();
+        if (!seedHex) {
+            const keys = DatumCryptoSession.generateKeyPair();
+            console.warn('DATUM_IDENTITY_SEED is not set; generated an ephemeral DATUM server identity key');
+            return keys;
+        }
+        if (!/^[0-9a-fA-F]{64}$/.test(seedHex)) {
+            throw new Error('DATUM_IDENTITY_SEED must be a 32-byte hex string');
+        }
+        return DatumCryptoSession.generateKeyPairFromSeed(Buffer.from(seedHex, 'hex'));
+    }
+
+    private getPorts(): number[] {
+        const configured = this.configService.get<string>('DATUM_PORTS');
+        if (!configured?.trim()) {
+            return [];
+        }
+        return Array.from(new Set(configured
+            .split(',')
+            .map(port => parseInt(port.trim(), 10))
+            .filter(port => Number.isInteger(port) && port > 0 && port <= 65535)));
+    }
+
+    private getNetwork(): bitcoinjs.networks.Network {
+        const networkConfig = this.configService.get('NETWORK');
+        if (networkConfig === 'mainnet') {
+            return bitcoinjs.networks.bitcoin;
+        }
+        if (networkConfig === 'testnet') {
+            return bitcoinjs.networks.testnet;
+        }
+        if (networkConfig === 'regtest') {
+            return bitcoinjs.networks.regtest;
+        }
+        throw new Error('Invalid network configuration');
+    }
+}
+
+interface DatumClientState {
+    sessionId: string;
+    session: DatumCryptoSession;
+    clientEntity: ClientEntity | null;
+    address: string | null;
+    workerName: string;
+    userAgent: string;
+    pingTimer: NodeJS.Timeout | null;
+    datumJobs: Map<number, DatumJobCache>;
+}
+
+interface DatumJobCache {
+    prevBlockHash?: Buffer;
+    targetByteIndex?: number;
+    nBits?: Buffer;
+    coinbaserId?: number;
+    height?: number;
+    coinbaseValue?: bigint;
+    transactionCount?: number;
+    totalWeight?: number;
+    totalSize?: number;
+    totalSigops?: number;
+    merkleBranches?: Buffer[];
+    coinbasePairs: Map<number, { coinb1: Buffer; coinb2: Buffer }>;
+    subsidyOnlyCoinbase?: { coinb1: Buffer; coinb2: Buffer };
+    validationState?: 'requested-short-txids' | 'requested-full-transaction-blob' | 'validated' | 'failed';
+    validationRequestedAt?: Date;
+    validationCompletedAt?: Date;
+    validationShortTxIds?: Buffer[];
+    validationShortTxCrosscheck?: Buffer;
+    validationTransactions?: Buffer[];
+    validationError?: string;
+}
+
+function uint32le(value: number): Buffer {
+    const result = Buffer.alloc(4);
+    result.writeUInt32LE(value >>> 0, 0);
+    return result;
+}

src/services/notification.service.ts

@@ -14,6 +14,10 @@ export class NotificationService implements OnModuleInit {
     ) { }
 
     async onModuleInit(): Promise<void> {
+        if (process.env.MASTER !== 'true') {
+            return;
+        }
+
         await this.discordService.notifyRestarted();
     }
 

src/services/redis-messaging.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+
+import { RedisMessagingService } from './redis-messaging.service';
+
+@Global()
+@Module({
+    imports: [ConfigModule],
+    providers: [RedisMessagingService],
+    exports: [RedisMessagingService],
+})
+export class RedisMessagingModule { }

src/services/redis-messaging.service.spec.ts

@@ -0,0 +1,187 @@
+import { ConfigService } from '@nestjs/config';
+import { createClient } from 'redis';
+
+import { RedisMessagingService } from './redis-messaging.service';
+
+jest.mock('redis', () => ({
+    createClient: jest.fn(),
+}));
+
+describe('RedisMessagingService', () => {
+    let clients: any[];
+    let service: RedisMessagingService;
+
+    beforeEach(() => {
+        store.clear();
+        sets.clear();
+        clientsByRole.publisher = null;
+        clientsByRole.subscriber = null;
+        clients = [createRedisClient(), createRedisClient()];
+        (createClient as jest.Mock).mockImplementation(() => clients.shift());
+        service = new RedisMessagingService({
+            get: jest.fn((key: string) => key === 'REDIS_URL' ? 'redis://test-redis:6379' : null),
+        } as unknown as ConfigService);
+    });
+
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should store and replay latest mining info and block templates', async () => {
+        await service.connect();
+
+        await service.setLatestMiningInfo({ blocks: 900000 } as any);
+        await service.setBlockTemplate(900000, { height: 900000, transactions: [] } as any);
+
+        expect(await service.getLatestMiningInfo()).toEqual({ blocks: 900000 });
+        expect(await service.getBlockTemplate(900000)).toEqual({ height: 900000, transactions: [] });
+        expect(await service.getLatestBlockTemplate()).toEqual({ height: 900000, transactions: [] });
+    });
+
+    it('should publish and subscribe to mining info updates', async () => {
+        await service.connect();
+        const handler = jest.fn().mockResolvedValue(undefined);
+
+        await service.subscribeMiningInfoUpdates(handler);
+        await service.publishMiningInfoUpdate({ blocks: 900001 } as any);
+
+        expect(handler).toHaveBeenCalledWith({ blocks: 900001 });
+    });
+
+    it('should ignore malformed pubsub messages', async () => {
+        await service.connect();
+        const handler = jest.fn();
+        const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+
+        await service.subscribeMiningInfoUpdates(handler);
+        await clientsByRole.subscriber.callback('{bad json');
+
+        expect(handler).not.toHaveBeenCalled();
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Invalid Redis mining info update'));
+        consoleSpy.mockRestore();
+    });
+
+    it('should store, index, and remove client presence', async () => {
+        await service.connect();
+
+        await service.setClientPresence({
+            clientId: '00000000-0000-4000-8000-000000000001',
+            address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+            clientName: 'worker',
+            sessionId: '57a6f098',
+            userAgent: 'bitaxe',
+            startTime: '2026-06-07T12:00:00.000Z',
+            lastSeen: '2026-06-07T12:01:00.000Z',
+            hashRate: 100,
+            bestDifficulty: 200,
+        });
+
+        expect(await service.getClientPresence('00000000-0000-4000-8000-000000000001'))
+            .toEqual(expect.objectContaining({
+                clientId: '00000000-0000-4000-8000-000000000001',
+                address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+                hashRate: 100,
+                bestDifficulty: 200,
+            }));
+        expect(await service.getClientPresenceByAddress('tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4'))
+            .toHaveLength(1);
+        expect(await service.getAllClientPresence()).toHaveLength(1);
+
+        await service.removeClientPresence('00000000-0000-4000-8000-000000000001');
+
+        expect(await service.getAllClientPresence()).toHaveLength(0);
+    });
+
+    it('should clear all client presence keys', async () => {
+        await service.connect();
+
+        await service.setClientPresence({
+            clientId: '00000000-0000-4000-8000-000000000001',
+            address: 'tb1qumezefzdeqqwn5zfvgdrhxjzc5ylr39uhuxcz4',
+            clientName: 'worker',
+            sessionId: '57a6f098',
+            userAgent: 'bitaxe',
+            startTime: '2026-06-07T12:00:00.000Z',
+            lastSeen: '2026-06-07T12:01:00.000Z',
+            hashRate: 100,
+            bestDifficulty: 200,
+        });
+
+        await service.clearClientPresence();
+
+        expect(await service.getAllClientPresence()).toHaveLength(0);
+        expect([...store.keys()].filter(key => key.startsWith('client-presence'))).toHaveLength(0);
+        expect([...sets.keys()].filter(key => key.startsWith('client-presence'))).toHaveLength(0);
+    });
+});
+
+const store = new Map<string, string>();
+const sets = new Map<string, Set<string>>();
+const clientsByRole: { publisher?: any; subscriber?: any } = {};
+
+function createRedisClient() {
+    const client = {
+        connect: jest.fn().mockResolvedValue(undefined),
+        quit: jest.fn().mockResolvedValue(undefined),
+        on: jest.fn(),
+        set: jest.fn((key: string, value: string) => {
+            store.set(key, value);
+            return Promise.resolve('OK');
+        }),
+        setEx: jest.fn((key: string, seconds: number, value: string) => {
+            store.set(key, value);
+            return Promise.resolve('OK');
+        }),
+        get: jest.fn((key: string) => Promise.resolve(store.get(key) ?? null)),
+        mGet: jest.fn((keys: string[]) => Promise.resolve(keys.map(key => store.get(key) ?? null))),
+        del: jest.fn((...args: (string | string[])[]) => {
+            const keys = args.flatMap(key => Array.isArray(key) ? key : [key]);
+            let deleted = 0;
+            keys.forEach(item => {
+                deleted += store.delete(item) ? 1 : 0;
+                deleted += sets.delete(item) ? 1 : 0;
+            });
+            return Promise.resolve(deleted);
+        }),
+        sAdd: jest.fn((key: string, value: string) => {
+            const set = sets.get(key) ?? new Set<string>();
+            set.add(value);
+            sets.set(key, set);
+            return Promise.resolve(1);
+        }),
+        sRem: jest.fn((key: string, value: string | string[]) => {
+            const set = sets.get(key);
+            const values = Array.isArray(value) ? value : [value];
+            let deleted = 0;
+            values.forEach(item => {
+                deleted += set?.delete(item) ? 1 : 0;
+            });
+            return Promise.resolve(deleted);
+        }),
+        sMembers: jest.fn((key: string) => Promise.resolve([...sets.get(key) ?? []])),
+        scanIterator: jest.fn(async function* scanIterator({ MATCH }: { MATCH: string }) {
+            const prefix = MATCH.replace('*', '');
+            for (const key of [...store.keys(), ...sets.keys()]) {
+                if (key.startsWith(prefix)) {
+                    yield key;
+                }
+            }
+        }),
+        publish: jest.fn((channel: string, value: string) => {
+            void clientsByRole.subscriber?.callback(value);
+            return Promise.resolve(1);
+        }),
+        subscribe: jest.fn((channel: string, callback: (message: string) => Promise<void>) => {
+            clientsByRole.subscriber.callback = callback;
+            return Promise.resolve();
+        }),
+    };
+
+    if (clientsByRole.publisher == null) {
+        clientsByRole.publisher = client;
+    } else {
+        clientsByRole.subscriber = client;
+    }
+
+    return client;
+}