feat(wallet-toolbox): run StorageKnex on Postgres

.github/workflows/ci.yml

@@ -969,6 +969,19 @@ jobs:
           - { id: shard-4, shard: 4 }
           - { id: sync-http-0, latency: 0 }
           - { id: sync-http-1000, latency: 1000 }
+    services:
+      # The Knex storage suites also run against Postgres (RUNPOSTGRES).
+      postgres:
+        image: postgres@sha256:d5daad18926b71c3d663f358af0aea798670cb79fb550c106d19662a9d1627ef # 17-alpine
+        env:
+          POSTGRES_PASSWORD: ${{ github.run_id }}-${{ github.run_attempt }}
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready --host 127.0.0.1 --username postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 30
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
@@ -989,11 +1002,16 @@ jobs:
         env:
           WALLET_SHARD: ${{ matrix.shard }}
           SYNC_LATENCY: ${{ matrix.latency }}
+          POSTGRES_PASSWORD: ${{ github.run_id }}-${{ github.run_attempt }}
         run: |
           # The two real-HTTP latency scenarios run in independent processes;
           # their global transport spies must never overlap in one Jest worker.
           args=(--coverage --coverageDirectory=coverage/${{ matrix.id }})
           if [ -n "$WALLET_SHARD" ]; then
+            export RUNPOSTGRES=1
+            POSTGRES_CONNECTION="$(jq -cn --arg password "$POSTGRES_PASSWORD" \
+              '{host: "127.0.0.1", port: 5432, user: "postgres", password: $password, database: "postgres"}')"
+            export POSTGRES_CONNECTION
             args+=(--testPathIgnorePatterns='man.test.ts|bench.test.ts|test/monitor/Monitor.test.ts|client/test|mobile/test|src/storage/sync/syncTransferHttp.test.ts')
             args+=(--shard="$WALLET_SHARD/4")
           else

infra/wallet-infra/src/KnexPaymentReplayStore.ts

@@ -10,6 +10,7 @@ function isDuplicate(error: unknown): boolean {
     value.code === 'ER_DUP_ENTRY' ||
     value.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' ||
     value.code === 'SQLITE_CONSTRAINT_UNIQUE' ||
+    value.code === '23505' ||
     value.errno === 1062
   )
 }

packages/wallet/wallet-toolbox/README.md

@@ -63,6 +63,20 @@ store already left with unjournaled schema objects by an older version. Preserve
 the database and verified backups and reconcile the exact schema and migration
 journal before recovery; do not delete journal rows or wallet data blindly.
 
+### Postgres storage
+
+`StorageKnex` runs on Postgres through the knex `pg` client. Install `pg` in the
+application and pass a Postgres knex:
+
+```ts
+import { knex as makeKnex } from 'knex'
+
+const knex = makeKnex({ client: 'pg', connection: { host, port, user, password, database } })
+const storage = new StorageKnex({ ...StorageKnex.defaultOptions(), chain: 'main', knex })
+```
+
+`ChaintracksStorageKnex` and `adminStats` do not support Postgres.
+
 ## Overview
 
 The Wallet Toolbox is the reference implementation of the BRC-100 wallet interface. It connects the BSV SDK's cryptographic primitives to real storage backends, network services, and signing flows so that application developers don't have to wire these layers together themselves.

packages/wallet/wallet-toolbox/package.json

@@ -111,6 +111,7 @@
     "fs-extra": "^11.4.0",
     "jest": "^30.5.1",
     "oxlint": "^1.83.0",
+    "pg": "^8.23.0",
     "picocolors": "^1.1.1",
     "ts-jest": "^29.4.12",
     "ts-node": "^10.9.2",

packages/wallet/wallet-toolbox/src/services/chaintracker/chaintracks/Storage/ChaintracksStorageKnex.ts

@@ -14,7 +14,7 @@ import { DBType } from '../../../../storage/StorageReader'
 import { BulkHeaderFileInfo } from '../util/BulkHeaderFile'
 import { HeightRange } from '../util/HeightRange'
 import { Chain } from '../../../../sdk/types'
-import { WERR_INVALID_OPERATION, WERR_INVALID_PARAMETER } from '../../../../sdk/WERR_errors'
+import { WERR_INVALID_OPERATION, WERR_INVALID_PARAMETER, WERR_NOT_IMPLEMENTED } from '../../../../sdk/WERR_errors'
 import { determineDBType } from '../../../../storage/schema/KnexMigrations'
 import { normalizeBulkHeaderFileInfo, normalizeBulkHeaderFileSequence } from '../util/BulkFileDataManager'
 
@@ -94,6 +94,9 @@ export class ChaintracksStorageKnex extends ChaintracksStorageBase implements Ch
     }
     if (!this.isAvailable) {
       this._dbtype = await determineDBType(this.knex)
+      // Chaintracks storage supports SQLite and MySQL only.
+      if (this._dbtype === 'Postgres')
+        throw new WERR_NOT_IMPLEMENTED('ChaintracksStorageKnex does not support Postgres.')
       await super.makeAvailable()
       // Connect the bulk data file manager to the table provided by this storage class.
       await this.bulkManager.setStorage(this, this.log)