Upgrades, bugfixes and improvements

.cspell.json

@@ -71,6 +71,7 @@
     "peerready",
     "peersendheaders",
     "pgadmin",
+    "PGCOPY",
     "pghero",
     "pino",
     "pkey",
@@ -97,12 +98,17 @@
     "sendheaders",
     "statefulset",
     "statefulsets",
+    "subquery",
     "symlinks",
     "templating",
     "txindex",
     "unintuitive",
+    "unnest",
     "unpruned",
     "upserting",
+    "UTXO",
+    "UTXOs",
+    "varint",
     "verack",
     "xprivkey",
     "xpubkey"

.github/workflows/ci.yaml

@@ -4,6 +4,13 @@ on: [push, pull_request]
 jobs:
   e2e-tests:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        write-path: [sql, copy]
+    name: e2e-tests (write path ${{ matrix.write-path }})
+    env:
+      CHAINGRAPH_WRITE_PATH: ${{ matrix.write-path }}
     services:
       postgres:
         image: postgres:14
@@ -20,36 +27,36 @@ jobs:
           - 5432:5432
     steps:
       - name: Check out repository code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           submodules: 'true'
       - name: Install Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v7
         with:
           node-version: '18'
       - run: yarn install --immutable --immutable-cache
       - run: yarn test
       - run: yarn cov:lcov
       - name: Upload test coverage
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v7
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Save E2E test logs
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v7
         if: always()
         with:
-          name: e2e-test-log
+          name: e2e-test-log-${{ matrix.write-path }}
           path: data/chaingraph/log-e2e.ndjson
 
   check-yarn-cache:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           submodules: 'true'
       - name: Install Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v7
         with:
           node-version: '18'
       - run: yarn install --immutable --immutable-cache --check-cache

.github/workflows/image-agent.yaml

@@ -17,23 +17,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v4
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           submodules: 'true'
       - name: Get tag
         run: |
           echo "::set-output name=commit::$(git rev-parse --short HEAD)"
         id: get_tag
       - name: Login to DockerHub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_TOKEN }}
       - name: Build, tag, push
         id: docker_build
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: images/agent/Dockerfile

.github/workflows/image-bchn.yaml

@@ -12,21 +12,21 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v4
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - name: Get version
         run: |
           echo "::set-output name=version::$(grep -F 'ENV BITCOIN_VERSION' images/bitcoin-cash-node/Dockerfile | grep -oE '[0-9.]+')"
         id: get_version
       - name: Login to DockerHub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_TOKEN }}
       - name: Build, tag, push
         id: docker_build
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v7
         with:
           context: images/bitcoin-cash-node
           push: true

.github/workflows/image-hasura.yaml

@@ -12,21 +12,21 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v4
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - name: Get tag
         run: |
           echo "::set-output name=commit::$(git rev-parse --short HEAD)"
         id: get_tag
       - name: Login to DockerHub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_TOKEN }}
       - name: Build, tag, push
         id: docker_build
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v7
         with:
           context: images/hasura
           push: true

.github/workflows/release-chart.yaml

@@ -10,15 +10,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - name: Configure Git
         run: |
           git config user.name "$GITHUB_ACTOR"
           git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
       - name: Install Helm
-        uses: azure/setup-helm@v3
+        uses: azure/setup-helm@v5
       - name: Run chart-releaser
         uses: helm/chart-releaser-action@v1.5.0
         with:

.gitignore

@@ -14,3 +14,4 @@ package-lock.json
 data
 .env
 client/generated
+.scratch

charts/chaingraph/templates/agent.yaml

@@ -8,6 +8,14 @@ metadata:
     {{- include "chaingraph.labels" . | nindent 4 }}
 spec:
   replicas: 1
+  # The agent is a singleton writer: never run two concurrently. Recreate
+  # terminates the old pod before starting its replacement, at the cost of a
+  # brief indexing gap (the agent catches up on restart).
+  strategy:
+    type: Recreate
+    # Explicit null clears the server-defaulted rollingUpdate block left by
+    # previous RollingUpdate deployments (Helm three-way merge).
+    rollingUpdate: null
   selector:
     matchLabels:
       app: chaingraph-agent
@@ -41,6 +49,8 @@ spec:
           value: {{ .Values.agent.synchronousCommit | quote }}
         - name: CHAINGRAPH_BLOCK_BUFFER_TARGET_SIZE_MB
           value: {{ .Values.agent.blockBufferTargetSizeMb | quote }}
+        - name: CHAINGRAPH_INCOMPLETE_BLOCK_REPAIR_BATCH_SIZE
+          value: {{ .Values.agent.repairBlocksBatchSize | quote }}
         - name: CHAINGRAPH_GENESIS_BLOCKS
           value: {{ .Values.agent.genesisBlocks | quote }}
         - name: CHAINGRAPH_TRUSTED_NODES
@@ -68,13 +78,17 @@ spec:
           timeoutSeconds: 15
           successThreshold: 1
           failureThreshold: 3
+        # Readiness is tight so rollouts report Ready seconds after the
+        # internal API is up. Liveness (above) stays coarse on purpose: a
+        # CPU-bound catch-up can block the event loop (and /health-check),
+        # and a twitchy liveness probe would kill the agent mid-recovery.
         readinessProbe:
           httpGet:
             path: /health-check
             port: {{ .Values.agent.port }}
-          initialDelaySeconds: 30
-          periodSeconds: 60
-          timeoutSeconds: 15
+          initialDelaySeconds: 5
+          periodSeconds: 10
+          timeoutSeconds: 5
           successThreshold: 1
           failureThreshold: 3
         resources: {}

charts/chaingraph/values.yaml

@@ -18,12 +18,15 @@ agent:
   # The maximum number of connections the agent should maintain to the database.
   # For best performance, this should be set to the number of CPUs available to Postgres. If not set, Chaingraph will assume that Postgres is running on hardware equivalent to its own. (This is ideal if Postgres is running on either the same machine or an equivalent one from a homogenous Kubernetes node pool.)
   maxConnections: ''
-# If set to false, the Postgres database will be configured to use "synchronous_commit = off" during initial sync.
-# In real-world testing, this usually reduces the speed of Chaingraph's initial sync, so Chaingraph leaves "synchronous_commit = on" by default.
+  # If set to false, the Postgres database will be configured to use "synchronous_commit = off" during initial sync.
+  # In real-world testing, this usually reduces the speed of Chaingraph's initial sync, so Chaingraph leaves "synchronous_commit = on" by default.
   synchronousCommit: true
   # The target size (in MB) of the buffer which holds downloaded blocks waiting to be saved to the database. This primarily affects memory usage during the initial chain sync.
   # For best performance, this should be around `maxConnections * maximum block size`, while leaving enough memory available to the host machine. If left unset (recommended), Chaingraph will measure free memory at startup and attempt to select a reasonable value.
   blockBufferTargetSizeMb: ''
+  # Self-healing for https://github.com/bitauth/chaingraph/issues/74: after initial sync, the agent scans saved blocks in batches to find blocks whose linked transactions don't match the saved block size, then repairs those blocks by re-requesting them from trusted nodes.
+  # Set to 0 to disable the startup repair task. Completed scans are recorded per node in the incomplete_block_audit table, so later startups only audit blocks saved since the last completed scan; delete its rows to force a full re-audit.
+  repairBlocksBatchSize: 10000
   # A mapping of network magic bytes to hex-encoded genesis blocks.
   # Format: `NETWORK_MAGIC:RAW_GENESIS_BLOCK_HEX`, comma separated.
   # E.g. CHAINGRAPH_GENESIS_BLOCKS=e3e1f3e8:rawblockhex,deadbeef:rawblockhex

defaults.env

@@ -12,10 +12,43 @@ CHAINGRAPH_POSTGRES_MAX_CONNECTIONS=
 # In real-world testing, this usually reduces the speed of Chaingraph's initial sync, so Chaingraph leaves "synchronous_commit = on" by default.
 CHAINGRAPH_POSTGRES_SYNCHRONOUS_COMMIT=true
 
+# How block data is written to Postgres: `sql` sends each block as multi-row `INSERT … VALUES` statements; `copy` streams the rows with binary `COPY` into per-connection temporary staging tables and inserts from there (same constraints and `ON CONFLICT DO NOTHING` semantics, much less SQL text to build, send, parse and plan).
+CHAINGRAPH_WRITE_PATH=sql
+
 # The target size (in MB) of the buffer which holds downloaded blocks waiting to be saved to the database. This primarily affects memory usage during the initial chain sync.
 # For best performance, this should be around `CHAINGRAPH_POSTGRES_MAX_CONNECTIONS * maximum block size`, while leaving enough memory available to the host machine. If not set, Chaingraph will measure free memory at startup and attempt to select a reasonable value.
 CHAINGRAPH_BLOCK_BUFFER_TARGET_SIZE_MB=
 
+# Self-healing for https://github.com/bitauth/chaingraph/issues/74: after
+# initial sync, the agent scans saved blocks in batches to find blocks whose
+# linked transactions don't match the saved block size, then repairs those
+# blocks by re-requesting them from trusted nodes. Set to 0 to disable the
+# startup repair task. Completed scans are recorded per node in the
+# incomplete_block_audit table, so later startups only audit blocks saved since
+# the last completed scan; delete its rows to force a full re-audit.
+CHAINGRAPH_INCOMPLETE_BLOCK_REPAIR_BATCH_SIZE=10000
+
+# BCHN expires transactions from the mempool after 336 hours but does not announce
+# those expirations. At initial sync and periodically thereafter the agent scans for
+# node_transaction rows expiring soon and schedules each row to be archived to
+# node_transaction_history at its exact expiry time. The existing mempool
+# invalidation cascade archives same-node descendants. See bitauth/chaingraph#73.
+CHAINGRAPH_MEMPOOL_TRANSACTION_EXPIRATION_MS=1209600000
+CHAINGRAPH_MEMPOOL_TRANSACTION_EXPIRATION_SCAN_INTERVAL_MS=3600000
+
+# BCHN does not re-announce transactions that a re-organization returns to its
+# mempool. When enabled, the agent sends each trusted node a BIP35 `mempool`
+# request after mempool tracking is enabled, after the node reconnects, and
+# after each re-organization reported by that node, so the answering `inv`
+# re-records `node_transaction` rows. Replies only add rows. Requests to each
+# node are rate-limited to one per CHAINGRAPH_MEMPOOL_RESYNC_MIN_INTERVAL_MS;
+# requests during that window are coalesced into one request when it ends.
+# The node must answer `mempool` requests: BCHN does when NODE_BLOOM is enabled
+# (`-peerbloomfilters`, the default) or the agent has the `mempool` permission
+# (e.g. `-whitelist=mempool@<agent-ip>`). See bitauth/chaingraph#81.
+CHAINGRAPH_MEMPOOL_RESYNC=true
+CHAINGRAPH_MEMPOOL_RESYNC_MIN_INTERVAL_MS=30000
+
 # A mapping of network magic bytes to hex-encoded genesis blocks.
 # Format: `NETWORK_MAGIC:RAW_GENESIS_BLOCK_HEX`, comma separated.
 # E.g. CHAINGRAPH_GENESIS_BLOCKS=e3e1f3e8:rawblockhex,deadbeef:rawblockhex

images/agent/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:18-alpine AS build-stage
+FROM node:24-alpine AS build-stage
 WORKDIR /chaingraph
 COPY package.json yarn.lock .yarnrc.yml ./
 COPY .yarn .yarn
@@ -10,7 +10,7 @@ RUN yarn build
 # Use Yarn plugin-production-install to copy only production dependencies (https://gitlab.com/Larry1123/yarn-contrib/-/tree/master/packages/plugin-production-install)
 RUN yarn prod-install ./production-dependencies
 
-FROM node:18-alpine AS production
+FROM node:24-alpine AS production
 WORKDIR /chaingraph
 COPY --from=build-stage /chaingraph/production-dependencies ./
 COPY --from=build-stage /chaingraph/defaults.env ./

images/bitcoin-cash-node/Dockerfile

@@ -7,9 +7,9 @@ RUN set -ex \
   && apt-get install -qq --no-install-recommends ca-certificates gosu wget \
   && rm -rf /var/lib/apt/lists/*
 
-ENV BITCOIN_VERSION 28.0.2
-ENV BITCOIN_URL https://download.bitcoincashnode.org/misc/builds/upgrade12_temp/linux/bitcoin-cash-node-28.0.2-x86_64-linux-gnu.tar.gz
-ENV BITCOIN_SHA256 140b44fd76a4f9428354bfbec4800d58fd39fb723320e761a035f15c2dd43596
+ENV BITCOIN_VERSION 29.0.0
+ENV BITCOIN_URL https://github.com/bitcoin-cash-node/bitcoin-cash-node/releases/download/v29.0.0/bitcoin-cash-node-29.0.0-x86_64-linux-gnu.tar.gz
+ENV BITCOIN_SHA256 6125d1cbecc1db476f2b6b7b91da5acde92d2311b8e738124e3db64ca84b33e1
 
 # install bitcoin binaries
 RUN set -ex \

images/hasura/Dockerfile

@@ -1,5 +1,10 @@
 
-FROM hasura/graphql-engine:v2.16.1.cli-migrations-v3
+# Multi-arch tag; digest of the manifest list as of 2026-07-20:
+# sha256:da573f6420bfbc330023dd4b816c1e6fcb50ab6a00fd3e1d8c70088532d5fa7f
+# NOTE: first startup against an existing database performs a ONE-WAY
+# metadata catalog upgrade (47 -> current). Snapshot/backup hdb_catalog
+# before deploying to an instance you may want to roll back.
+FROM hasura/graphql-engine:v2.49.5.cli-migrations-v3
 
 COPY hasura-data /hasura-data
 

images/hasura/hasura-data/migrations/default/1778151011521_cascade_invalidate_mempool_descendants/down.sql

@@ -0,0 +1,2 @@
+DROP TRIGGER IF EXISTS trigger_public_node_transaction_history_insert ON node_transaction_history;
+DROP FUNCTION IF EXISTS trigger_node_transaction_history_insert();