@aztec/validator-ha-signer 0.0.1-commit.7d4e6cd → 0.0.1-commit.7ffbba4

package/README.md

@@ -9,39 +9,21 @@ Distributed locking and slashing protection for Aztec validators running in high
 - **Automatic Retry**: Failed signing attempts are cleared, allowing other nodes to retry
 - **PostgreSQL Backend**: Shared database for coordination across nodes
 
-## Quick Start
+## Integration with Validator Client
 
-### Option 1: Automatic Migrations (Simplest)
+The HA signer is automatically integrated into the validator client when `VALIDATOR_HA_SIGNING_ENABLED=true` is set. The validator client will:
 
-```typescript
-import { createHASigner } from '@aztec/validator-ha-signer/factory';
-
-// Migrations run automatically on startup
-const { signer, db } = await createHASigner({
-  databaseUrl: process.env.DATABASE_URL,
-  enabled: true,
-  nodeId: 'validator-node-1',
-  pollingIntervalMs: 100,
-  signingTimeoutMs: 3000,
-});
+1. Create the HA signer using `createHASigner()` from the factory
+2. Wrap the base keystore with `HAKeyStore` to provide HA-protected signing
+3. Automatically start/stop the signer lifecycle
 
-// Start background cleanup tasks
-signer.start();
+No manual integration is required when using the validator client.
 
-// Sign with protection
-const signature = await signer.signWithProtection(
-  validatorAddress,
-  messageHash,
-  { slot: 100n, blockNumber: 50n, dutyType: 'BLOCK_PROPOSAL' },
-  async root => localSigner.signMessage(root),
-);
+## Manual Usage
 
-// Cleanup on shutdown
-await signer.stop();
-await db.close();
-```
+For advanced use cases or testing, you can use the HA signer directly. **Note**: Database migrations must be run separately before creating the signer (see [Database Migrations](#database-migrations) below).
 
-### Option 2: Manual Migrations (Recommended for Production)
+### Basic Usage
 
 ```bash
 # 1. Run migrations separately (once per deployment)
@@ -54,7 +36,6 @@ import { createHASigner } from '@aztec/validator-ha-signer/factory';
 
 const { signer, db } = await createHASigner({
   databaseUrl: process.env.DATABASE_URL,
-  enabled: true,
   nodeId: 'validator-node-1',
   pollingIntervalMs: 100,
   signingTimeoutMs: 3000,
@@ -63,6 +44,14 @@ const { signer, db } = await createHASigner({
 // Start background cleanup tasks
 signer.start();
 
+// Sign with protection
+const signature = await signer.signWithProtection(
+  validatorAddress,
+  messageHash,
+  { slot: 100n, blockNumber: 50n, blockIndexWithinCheckpoint: 0, dutyType: 'BLOCK_PROPOSAL' },
+  async root => localSigner.signMessage(root),
+);
+
 // On shutdown
 await signer.stop();
 await db.close();
@@ -73,7 +62,7 @@ await db.close();
 If you need custom pool configuration (e.g., max connections, idle timeout) or want to share a connection pool across multiple components:
 
 > **Note**: You still need to run migrations separately before using this approach.
-> See [Option 2](#option-2-manual-migrations-recommended-for-production) above.
+> See [Database Migrations](#database-migrations) below.
 
 ```typescript
 import { PostgresSlashingProtectionDatabase } from '@aztec/validator-ha-signer/db';
@@ -91,11 +80,10 @@ const db = new PostgresSlashingProtectionDatabase(pool);
 await db.initialize();
 
 const signer = new ValidatorHASigner(db, {
-  enabled: true,
   nodeId: 'validator-node-1',
   pollingIntervalMs: 100,
   signingTimeoutMs: 3000,
-  maxStuckDutiesAgeMs: 72000,
+  maxStuckDutiesAgeMs: 144000,
 });
 
 // Start background cleanup tasks
@@ -111,11 +99,15 @@ await pool.end(); // You manage the pool lifecycle
 Set via environment variables or config object:
 
 - `VALIDATOR_HA_DATABASE_URL`: PostgreSQL connection string (e.g., `postgresql://user:pass@host:port/db`)
-- `SLASHING_PROTECTION_ENABLED`: Whether slashing protection is enabled (default: true)
-- `SLASHING_PROTECTION_NODE_ID`: Unique identifier for this validator node
-- `SLASHING_PROTECTION_POLLING_INTERVAL_MS`: How often to check duty status (default: 100)
-- `SLASHING_PROTECTION_SIGNING_TIMEOUT_MS`: Max wait for in-progress signing (default: 3000)
-- `SLASHING_PROTECTION_MAX_STUCK_DUTIES_AGE_MS`: Max age of stuck duties before cleanup (default: 72000)
+- `VALIDATOR_HA_SIGNING_ENABLED`: Whether HA signing / slashing protection is enabled (default: false)
+- `VALIDATOR_HA_NODE_ID`: Unique identifier for this validator node (required when enabled)
+- `VALIDATOR_HA_POLLING_INTERVAL_MS`: How often to check duty status (default: 100)
+- `VALIDATOR_HA_SIGNING_TIMEOUT_MS`: Max wait for in-progress signing (default: 3000)
+- `VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS`: Max age of stuck duties before cleanup (default: 2 \* aztecSlotDuration)
+- `VALIDATOR_HA_POOL_MAX`: Maximum number of connections in the pool (default: 10)
+- `VALIDATOR_HA_POOL_MIN`: Minimum number of connections in the pool (default: 0)
+- `VALIDATOR_HA_POOL_IDLE_TIMEOUT_MS`: Idle timeout for pool connections (default: 10000)
+- `VALIDATOR_HA_POOL_CONNECTION_TIMEOUT_MS`: Connection timeout (default: 0, no timeout)
 
 ## Database Migrations
 
@@ -170,9 +162,30 @@ When multiple validator nodes attempt to sign:
 
 1. First node acquires lock and signs
 2. Other nodes receive `DutyAlreadySignedError` (expected)
-3. If different data detected: `SlashingProtectionError` (likely for block builder signing)
+3. If different data detected: `SlashingProtectionError` (prevents slashing)
 4. Failed attempts are auto-cleaned, allowing retry
 
+### Signing Context
+
+All signing operations require a `SigningContext` that includes:
+
+- `slot`: The slot number
+- `blockNumber`: The block number within the checkpoint
+- `blockIndexWithinCheckpoint`: The index of the block within the checkpoint (use `-1` for N/A contexts)
+- `dutyType`: The type of duty (e.g., `BLOCK_PROPOSAL`, `CHECKPOINT_ATTESTATION`, `AUTH_REQUEST`)
+
+Note: `AUTH_REQUEST` duties bypass HA protection since signing multiple times is safe for authentication requests.
+
+## Important Limitations
+
+### Database Isolation Per Rollup Version
+
+**You cannot use the same database to provide slashing protection for validator nodes running on different rollup versions** (e.g., current rollup and old rollup simultaneously).
+
+When the HA signer performs background cleanup via `cleanupOutdatedRollupDuties()`, it removes all duties where the rollup address doesn't match the current rollup address. If two validators running on different rollup versions share the same database, they will delete each other's duties during cleanup.
+
+**Solution**: Use separate databases for validators running on different rollup versions. Each rollup version requires its own isolated slashing protection database.
+
 ## Development
 
 ```bash

package/dest/db/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
 export * from './schema.js';
 export * from './postgres.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGVBQWUsQ0FBQyJ9
+export * from './lmdb.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLFdBQVcsQ0FBQyJ9

package/dest/db/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC"}

package/dest/db/index.js

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './schema.js';
 export * from './postgres.js';
+export * from './lmdb.js';

package/dest/db/lmdb.d.ts

@@ -0,0 +1,66 @@
+/**
+ * LMDB implementation of SlashingProtectionDatabase
+ *
+ * Provides local (single-node) double-signing protection using LMDB as the backend.
+ * Suitable for nodes that do NOT run in a high-availability multi-node setup.
+ *
+ * The LMDB store is single-writer, making setIfNotExists inherently atomic.
+ * This means we get crash-restart protection without needing an external database.
+ */
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { DateProvider } from '@aztec/foundation/timer';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { SlashingProtectionDatabase, TryInsertOrGetResult } from '../types.js';
+import { type CheckAndRecordParams, DutyType } from './types.js';
+/**
+ * LMDB-backed implementation of SlashingProtectionDatabase.
+ *
+ * Provides single-node double-signing protection that survives crashes and restarts.
+ * Does not provide cross-node coordination (that requires the PostgreSQL implementation).
+ */
+export declare class LmdbSlashingProtectionDatabase implements SlashingProtectionDatabase {
+    private readonly store;
+    private readonly dateProvider;
+    static readonly SCHEMA_VERSION = 1;
+    private readonly duties;
+    private readonly log;
+    constructor(store: AztecAsyncKVStore, dateProvider: DateProvider);
+    /**
+     * Atomically try to insert a new duty record, or get the existing one if present.
+     *
+     * LMDB is single-writer so the read-then-write inside transactionAsync is naturally atomic.
+     */
+    tryInsertOrGetExisting(params: CheckAndRecordParams): Promise<TryInsertOrGetResult>;
+    /**
+     * Update a duty to 'signed' status with the signature.
+     * Only succeeds if the lockToken matches.
+     */
+    updateDutySigned(rollupAddress: EthAddress, validatorAddress: EthAddress, slot: SlotNumber, dutyType: DutyType, signature: string, lockToken: string, blockIndexWithinCheckpoint: number): Promise<boolean>;
+    /**
+     * Delete a duty record.
+     * Only succeeds if the lockToken matches.
+     */
+    deleteDuty(rollupAddress: EthAddress, validatorAddress: EthAddress, slot: SlotNumber, dutyType: DutyType, lockToken: string, blockIndexWithinCheckpoint: number): Promise<boolean>;
+    /**
+     * Cleanup own stuck duties (SIGNING status older than maxAgeMs).
+     */
+    cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number>;
+    /**
+     * Cleanup duties with outdated rollup address.
+     *
+     * This is always a no-op for the LMDB implementation: the underlying store is created via
+     * DatabaseVersionManager (in factory.ts), which already resets the entire data directory at
+     * startup whenever the rollup address changes.
+     */
+    cleanupOutdatedRollupDuties(_currentRollupAddress: EthAddress): Promise<number>;
+    /**
+     * Cleanup old signed duties older than maxAgeMs.
+     */
+    cleanupOldDuties(maxAgeMs: number): Promise<number>;
+    /**
+     * Close the underlying LMDB store.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG1kYi5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2RiL2xtZGIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7O0dBUUc7QUFDSCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFFN0QsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBRTNELE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzVELE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFpQixNQUFNLGlCQUFpQixDQUFDO0FBRXhFLE9BQU8sS0FBSyxFQUFFLDBCQUEwQixFQUFFLG9CQUFvQixFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ3BGLE9BQU8sRUFDTCxLQUFLLG9CQUFvQixFQUV6QixRQUFRLEVBSVQsTUFBTSxZQUFZLENBQUM7QUFZcEI7Ozs7O0dBS0c7QUFDSCxxQkFBYSw4QkFBK0IsWUFBVywwQkFBMEI7SUFPN0UsT0FBTyxDQUFDLFFBQVEsQ0FBQyxLQUFLO0lBQ3RCLE9BQU8sQ0FBQyxRQUFRLENBQUMsWUFBWTtJQVAvQixnQkFBdUIsY0FBYyxLQUFLO0lBRTFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsTUFBTSxDQUEwQztJQUNqRSxPQUFPLENBQUMsUUFBUSxDQUFDLEdBQUcsQ0FBUztJQUU3QixZQUNtQixLQUFLLEVBQUUsaUJBQWlCLEVBQ3hCLFlBQVksRUFBRSxZQUFZLEVBSTVDO0lBRUQ7Ozs7T0FJRztJQUNVLHNCQUFzQixDQUFDLE1BQU0sRUFBRSxvQkFBb0IsR0FBRyxPQUFPLENBQUMsb0JBQW9CLENBQUMsQ0E0Qy9GO0lBRUQ7OztPQUdHO0lBQ0ksZ0JBQWdCLENBQ3JCLGFBQWEsRUFBRSxVQUFVLEVBQ3pCLGdCQUFnQixFQUFFLFVBQVUsRUFDNUIsSUFBSSxFQUFFLFVBQVUsRUFDaEIsUUFBUSxFQUFFLFFBQVEsRUFDbEIsU0FBUyxFQUFFLE1BQU0sRUFDakIsU0FBUyxFQUFFLE1BQU0sRUFDakIsMEJBQTBCLEVBQUUsTUFBTSxHQUNqQyxPQUFPLENBQUMsT0FBTyxDQUFDLENBMENsQjtJQUVEOzs7T0FHRztJQUNJLFVBQVUsQ0FDZixhQUFhLEVBQUUsVUFBVSxFQUN6QixnQkFBZ0IsRUFBRSxVQUFVLEVBQzVCLElBQUksRUFBRSxVQUFVLEVBQ2hCLFFBQVEsRUFBRSxRQUFRLEVBQ2xCLFNBQVMsRUFBRSxNQUFNLEVBQ2pCLDBCQUEwQixFQUFFLE1BQU0sR0FDakMsT0FBTyxDQUFDLE9BQU8sQ0FBQyxDQXlCbEI7SUFFRDs7T0FFRztJQUNJLHFCQUFxQixDQUFDLE1BQU0sRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsTUFBTSxDQUFDLENBZTlFO0lBRUQ7Ozs7OztPQU1HO0lBQ0ksMkJBQTJCLENBQUMscUJBQXFCLEVBQUUsVUFBVSxHQUFHLE9BQU8sQ0FBQyxNQUFNLENBQUMsQ0FFckY7SUFFRDs7T0FFRztJQUNJLGdCQUFnQixDQUFDLFFBQVEsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQW1CekQ7SUFFRDs7T0FFRztJQUNVLEtBQUssSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLENBR2xDO0NBQ0YifQ==

package/dest/db/lmdb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lmdb.d.ts","sourceRoot":"","sources":["../../src/db/lmdb.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAE7D,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,iBAAiB,CAAC;AAExE,OAAO,KAAK,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EACL,KAAK,oBAAoB,EAEzB,QAAQ,EAIT,MAAM,YAAY,CAAC;AAYpB;;;;;GAKG;AACH,qBAAa,8BAA+B,YAAW,0BAA0B;IAO7E,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAP/B,gBAAuB,cAAc,KAAK;IAE1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YACmB,KAAK,EAAE,iBAAiB,EACxB,YAAY,EAAE,YAAY,EAI5C;IAED;;;;OAIG;IACU,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA4C/F;IAED;;;OAGG;IACI,gBAAgB,CACrB,aAAa,EAAE,UAAU,EACzB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,0BAA0B,EAAE,MAAM,GACjC,OAAO,CAAC,OAAO,CAAC,CA0ClB;IAED;;;OAGG;IACI,UAAU,CACf,aAAa,EAAE,UAAU,EACzB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,0BAA0B,EAAE,MAAM,GACjC,OAAO,CAAC,OAAO,CAAC,CAyBlB;IAED;;OAEG;IACI,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAe9E;IAED;;;;;;OAMG;IACI,2BAA2B,CAAC,qBAAqB,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAErF;IAED;;OAEG;IACI,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBzD;IAED;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAGlC;CACF"}

package/dest/db/lmdb.js

@@ -0,0 +1,188 @@
+/**
+ * LMDB implementation of SlashingProtectionDatabase
+ *
+ * Provides local (single-node) double-signing protection using LMDB as the backend.
+ * Suitable for nodes that do NOT run in a high-availability multi-node setup.
+ *
+ * The LMDB store is single-writer, making setIfNotExists inherently atomic.
+ * This means we get crash-restart protection without needing an external database.
+ */ import { randomBytes } from '@aztec/foundation/crypto/random';
+import { createLogger } from '@aztec/foundation/log';
+import { DutyStatus, getBlockIndexFromDutyIdentifier, recordFromFields } from './types.js';
+function dutyKey(rollupAddress, validatorAddress, slot, dutyType, blockIndexWithinCheckpoint) {
+    return `${rollupAddress}:${validatorAddress}:${slot}:${dutyType}:${blockIndexWithinCheckpoint}`;
+}
+/**
+ * LMDB-backed implementation of SlashingProtectionDatabase.
+ *
+ * Provides single-node double-signing protection that survives crashes and restarts.
+ * Does not provide cross-node coordination (that requires the PostgreSQL implementation).
+ */ export class LmdbSlashingProtectionDatabase {
+    store;
+    dateProvider;
+    static SCHEMA_VERSION = 1;
+    duties;
+    log;
+    constructor(store, dateProvider){
+        this.store = store;
+        this.dateProvider = dateProvider;
+        this.log = createLogger('slashing-protection:lmdb');
+        this.duties = store.openMap('signing-protection-duties');
+    }
+    /**
+   * Atomically try to insert a new duty record, or get the existing one if present.
+   *
+   * LMDB is single-writer so the read-then-write inside transactionAsync is naturally atomic.
+   */ async tryInsertOrGetExisting(params) {
+        const blockIndexWithinCheckpoint = getBlockIndexFromDutyIdentifier(params);
+        const key = dutyKey(params.rollupAddress.toString(), params.validatorAddress.toString(), params.slot.toString(), params.dutyType, blockIndexWithinCheckpoint);
+        const lockToken = randomBytes(16).toString('hex');
+        const now = this.dateProvider.now();
+        const result = await this.store.transactionAsync(async ()=>{
+            const existing = await this.duties.getAsync(key);
+            if (existing) {
+                return {
+                    isNew: false,
+                    record: {
+                        ...existing,
+                        lockToken: ''
+                    }
+                };
+            }
+            const newRecord = {
+                rollupAddress: params.rollupAddress.toString(),
+                validatorAddress: params.validatorAddress.toString(),
+                slot: params.slot.toString(),
+                blockNumber: params.blockNumber.toString(),
+                blockIndexWithinCheckpoint,
+                dutyType: params.dutyType,
+                status: DutyStatus.SIGNING,
+                messageHash: params.messageHash,
+                nodeId: params.nodeId,
+                lockToken,
+                startedAtMs: now
+            };
+            await this.duties.set(key, newRecord);
+            return {
+                isNew: true,
+                record: newRecord
+            };
+        });
+        if (result.isNew) {
+            this.log.debug(`Acquired lock for duty ${params.dutyType} at slot ${params.slot}`, {
+                validatorAddress: params.validatorAddress.toString(),
+                nodeId: params.nodeId
+            });
+        }
+        return {
+            isNew: result.isNew,
+            record: recordFromFields(result.record)
+        };
+    }
+    /**
+   * Update a duty to 'signed' status with the signature.
+   * Only succeeds if the lockToken matches.
+   */ updateDutySigned(rollupAddress, validatorAddress, slot, dutyType, signature, lockToken, blockIndexWithinCheckpoint) {
+        const key = dutyKey(rollupAddress.toString(), validatorAddress.toString(), slot.toString(), dutyType, blockIndexWithinCheckpoint);
+        return this.store.transactionAsync(async ()=>{
+            const existing = await this.duties.getAsync(key);
+            if (!existing) {
+                this.log.warn('Failed to update duty to signed: duty not found', {
+                    rollupAddress: rollupAddress.toString(),
+                    validatorAddress: validatorAddress.toString(),
+                    slot: slot.toString(),
+                    dutyType,
+                    blockIndexWithinCheckpoint
+                });
+                return false;
+            }
+            if (existing.lockToken !== lockToken) {
+                this.log.warn('Failed to update duty to signed: invalid token', {
+                    rollupAddress: rollupAddress.toString(),
+                    validatorAddress: validatorAddress.toString(),
+                    slot: slot.toString(),
+                    dutyType,
+                    blockIndexWithinCheckpoint
+                });
+                return false;
+            }
+            await this.duties.set(key, {
+                ...existing,
+                status: DutyStatus.SIGNED,
+                signature,
+                completedAtMs: this.dateProvider.now()
+            });
+            return true;
+        });
+    }
+    /**
+   * Delete a duty record.
+   * Only succeeds if the lockToken matches.
+   */ deleteDuty(rollupAddress, validatorAddress, slot, dutyType, lockToken, blockIndexWithinCheckpoint) {
+        const key = dutyKey(rollupAddress.toString(), validatorAddress.toString(), slot.toString(), dutyType, blockIndexWithinCheckpoint);
+        return this.store.transactionAsync(async ()=>{
+            const existing = await this.duties.getAsync(key);
+            if (!existing || existing.lockToken !== lockToken) {
+                this.log.warn('Failed to delete duty: invalid token or duty not found', {
+                    rollupAddress: rollupAddress.toString(),
+                    validatorAddress: validatorAddress.toString(),
+                    slot: slot.toString(),
+                    dutyType,
+                    blockIndexWithinCheckpoint
+                });
+                return false;
+            }
+            await this.duties.delete(key);
+            return true;
+        });
+    }
+    /**
+   * Cleanup own stuck duties (SIGNING status older than maxAgeMs).
+   */ cleanupOwnStuckDuties(nodeId, maxAgeMs) {
+        const cutoffMs = this.dateProvider.now() - maxAgeMs;
+        return this.store.transactionAsync(async ()=>{
+            const keysToDelete = [];
+            for await (const [key, record] of this.duties.entriesAsync()){
+                if (record.nodeId === nodeId && record.status === DutyStatus.SIGNING && record.startedAtMs < cutoffMs) {
+                    keysToDelete.push(key);
+                }
+            }
+            for (const key of keysToDelete){
+                await this.duties.delete(key);
+            }
+            return keysToDelete.length;
+        });
+    }
+    /**
+   * Cleanup duties with outdated rollup address.
+   *
+   * This is always a no-op for the LMDB implementation: the underlying store is created via
+   * DatabaseVersionManager (in factory.ts), which already resets the entire data directory at
+   * startup whenever the rollup address changes.
+   */ cleanupOutdatedRollupDuties(_currentRollupAddress) {
+        return Promise.resolve(0);
+    }
+    /**
+   * Cleanup old signed duties older than maxAgeMs.
+   */ cleanupOldDuties(maxAgeMs) {
+        const cutoffMs = this.dateProvider.now() - maxAgeMs;
+        return this.store.transactionAsync(async ()=>{
+            const keysToDelete = [];
+            for await (const [key, record] of this.duties.entriesAsync()){
+                if (record.status === DutyStatus.SIGNED && record.completedAtMs !== undefined && record.completedAtMs < cutoffMs) {
+                    keysToDelete.push(key);
+                }
+            }
+            for (const key of keysToDelete){
+                await this.duties.delete(key);
+            }
+            return keysToDelete.length;
+        });
+    }
+    /**
+   * Close the underlying LMDB store.
+   */ async close() {
+        await this.store.close();
+        this.log.debug('LMDB slashing protection database closed');
+    }
+}

package/dest/db/postgres.d.ts

@@ -1,14 +1,26 @@
+/**
+ * PostgreSQL implementation of SlashingProtectionDatabase
+ */
+import { SlotNumber } from '@aztec/foundation/branded-types';
 import { EthAddress } from '@aztec/foundation/eth-address';
-import type { Pool } from 'pg';
+import type { QueryResult, QueryResultRow } from 'pg';
 import type { SlashingProtectionDatabase, TryInsertOrGetResult } from '../types.js';
 import type { CheckAndRecordParams, DutyType } from './types.js';
+/**
+ * Minimal pool interface for database operations.
+ * Both pg.Pool and test adapters (e.g., PGlite) satisfy this interface.
+ */
+export interface QueryablePool {
+    query<R extends QueryResultRow = any>(text: string, values?: any[]): Promise<QueryResult<R>>;
+    end(): Promise<void>;
+}
 /**
  * PostgreSQL implementation of the slashing protection database
  */
 export declare class PostgresSlashingProtectionDatabase implements SlashingProtectionDatabase {
     private readonly pool;
     private readonly log;
-    constructor(pool: Pool);
+    constructor(pool: QueryablePool);
     /**
      * Verify that database migrations have been run and schema version matches.
      * Should be called once at startup.
@@ -21,6 +33,9 @@ export declare class PostgresSlashingProtectionDatabase implements SlashingProte
      *
      * @returns { isNew: true, record } if we successfully inserted and acquired the lock
      * @returns { isNew: false, record } if a record already exists. lock_token is empty if the record already exists.
+     *
+     * Retries if no rows are returned, which can happen under high concurrency
+     * when another transaction just committed the row but it's not yet visible.
      */
     tryInsertOrGetExisting(params: CheckAndRecordParams): Promise<TryInsertOrGetResult>;
     /**
@@ -29,7 +44,7 @@ export declare class PostgresSlashingProtectionDatabase implements SlashingProte
      *
      * @returns true if the update succeeded, false if token didn't match or duty not found
      */
-    updateDutySigned(validatorAddress: EthAddress, slot: bigint, dutyType: DutyType, signature: string, lockToken: string): Promise<boolean>;
+    updateDutySigned(rollupAddress: EthAddress, validatorAddress: EthAddress, slot: SlotNumber, dutyType: DutyType, signature: string, lockToken: string, blockIndexWithinCheckpoint: number): Promise<boolean>;
     /**
      * Delete a duty record.
      * Only succeeds if the lockToken matches (caller must be the one who created the duty).
@@ -37,9 +52,11 @@ export declare class PostgresSlashingProtectionDatabase implements SlashingProte
      *
      * @returns true if the delete succeeded, false if token didn't match or duty not found
      */
-    deleteDuty(validatorAddress: EthAddress, slot: bigint, dutyType: DutyType, lockToken: string): Promise<boolean>;
+    deleteDuty(rollupAddress: EthAddress, validatorAddress: EthAddress, slot: SlotNumber, dutyType: DutyType, lockToken: string, blockIndexWithinCheckpoint: number): Promise<boolean>;
     /**
-     * Convert a database row to a ValidatorDutyRecord
+     * Convert a database row to a ValidatorDutyRecord.
+     * Maps snake_case column names to StoredDutyRecord (camelCase, ms timestamps),
+     * then delegates to the shared recordFromFields() converter.
      */
     private rowToRecord;
     /**
@@ -51,5 +68,19 @@ export declare class PostgresSlashingProtectionDatabase implements SlashingProte
      * @returns the number of duties cleaned up
      */
     cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number>;
+    /**
+     * Cleanup duties with outdated rollup address.
+     * Removes all duties where the rollup address doesn't match the current one.
+     * Used after a rollup upgrade to clean up duties for the old rollup.
+     * @returns the number of duties cleaned up
+     */
+    cleanupOutdatedRollupDuties(currentRollupAddress: EthAddress): Promise<number>;
+    /**
+     * Cleanup old signed duties.
+     * Removes only signed duties older than the specified age.
+     * Does not remove 'signing' duties as they may be in progress.
+     * @returns the number of duties cleaned up
+     */
+    cleanupOldDuties(maxAgeMs: number): Promise<number>;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9zdGdyZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi9wb3N0Z3Jlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFJQSxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFHM0QsT0FBTyxLQUFLLEVBQUUsSUFBSSxFQUFlLE1BQU0sSUFBSSxDQUFDO0FBRTVDLE9BQU8sS0FBSyxFQUFFLDBCQUEwQixFQUFFLG9CQUFvQixFQUFFLE1BQU0sYUFBYSxDQUFDO0FBUXBGLE9BQU8sS0FBSyxFQUFFLG9CQUFvQixFQUFXLFFBQVEsRUFBdUMsTUFBTSxZQUFZLENBQUM7QUFFL0c7O0dBRUc7QUFDSCxxQkFBYSxrQ0FBbUMsWUFBVywwQkFBMEI7SUFHdkUsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJO0lBRmpDLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFTO0lBRTdCLFlBQTZCLElBQUksRUFBRSxJQUFJLEVBRXRDO0lBRUQ7Ozs7O09BS0c7SUFDRyxVQUFVLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQWdDaEM7SUFFRDs7Ozs7T0FLRztJQUNHLHNCQUFzQixDQUFDLE1BQU0sRUFBRSxvQkFBb0IsR0FBRyxPQUFPLENBQUMsb0JBQW9CLENBQUMsQ0F3QnhGO0lBRUQ7Ozs7O09BS0c7SUFDRyxnQkFBZ0IsQ0FDcEIsZ0JBQWdCLEVBQUUsVUFBVSxFQUM1QixJQUFJLEVBQUUsTUFBTSxFQUNaLFFBQVEsRUFBRSxRQUFRLEVBQ2xCLFNBQVMsRUFBRSxNQUFNLEVBQ2pCLFNBQVMsRUFBRSxNQUFNLEdBQ2hCLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FrQmxCO0lBRUQ7Ozs7OztPQU1HO0lBQ0csVUFBVSxDQUNkLGdCQUFnQixFQUFFLFVBQVUsRUFDNUIsSUFBSSxFQUFFLE1BQU0sRUFDWixRQUFRLEVBQUUsUUFBUSxFQUNsQixTQUFTLEVBQUUsTUFBTSxHQUNoQixPQUFPLENBQUMsT0FBTyxDQUFDLENBaUJsQjtJQUVEOztPQUVHO0lBQ0gsT0FBTyxDQUFDLFdBQVc7SUFpQm5COztPQUVHO0lBQ0csS0FBSyxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FHM0I7SUFFRDs7O09BR0c7SUFDRyxxQkFBcUIsQ0FBQyxNQUFNLEVBQUUsTUFBTSxFQUFFLFFBQVEsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUk3RTtDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9zdGdyZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi9wb3N0Z3Jlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUNILE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUU3RCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFJM0QsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLGNBQWMsRUFBRSxNQUFNLElBQUksQ0FBQztBQUV0RCxPQUFPLEtBQUssRUFBRSwwQkFBMEIsRUFBRSxvQkFBb0IsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQVVwRixPQUFPLEtBQUssRUFBRSxvQkFBb0IsRUFBVyxRQUFRLEVBQXVDLE1BQU0sWUFBWSxDQUFDO0FBRy9HOzs7R0FHRztBQUNILE1BQU0sV0FBVyxhQUFhO0lBQzVCLEtBQUssQ0FBQyxDQUFDLFNBQVMsY0FBYyxHQUFHLEdBQUcsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sQ0FBQyxFQUFFLEdBQUcsRUFBRSxHQUFHLE9BQU8sQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUM3RixHQUFHLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0NBQ3RCO0FBRUQ7O0dBRUc7QUFDSCxxQkFBYSxrQ0FBbUMsWUFBVywwQkFBMEI7SUFHdkUsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJO0lBRmpDLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFTO0lBRTdCLFlBQTZCLElBQUksRUFBRSxhQUFhLEVBRS9DO0lBRUQ7Ozs7O09BS0c7SUFDRyxVQUFVLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQWdDaEM7SUFFRDs7Ozs7Ozs7T0FRRztJQUNHLHNCQUFzQixDQUFDLE1BQU0sRUFBRSxvQkFBb0IsR0FBRyxPQUFPLENBQUMsb0JBQW9CLENBQUMsQ0FvRHhGO0lBRUQ7Ozs7O09BS0c7SUFDRyxnQkFBZ0IsQ0FDcEIsYUFBYSxFQUFFLFVBQVUsRUFDekIsZ0JBQWdCLEVBQUUsVUFBVSxFQUM1QixJQUFJLEVBQUUsVUFBVSxFQUNoQixRQUFRLEVBQUUsUUFBUSxFQUNsQixTQUFTLEVBQUUsTUFBTSxFQUNqQixTQUFTLEVBQUUsTUFBTSxFQUNqQiwwQkFBMEIsRUFBRSxNQUFNLEdBQ2pDLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FzQmxCO0lBRUQ7Ozs7OztPQU1HO0lBQ0csVUFBVSxDQUNkLGFBQWEsRUFBRSxVQUFVLEVBQ3pCLGdCQUFnQixFQUFFLFVBQVUsRUFDNUIsSUFBSSxFQUFFLFVBQVUsRUFDaEIsUUFBUSxFQUFFLFFBQVEsRUFDbEIsU0FBUyxFQUFFLE1BQU0sRUFDakIsMEJBQTBCLEVBQUUsTUFBTSxHQUNqQyxPQUFPLENBQUMsT0FBTyxDQUFDLENBcUJsQjtJQUVEOzs7O09BSUc7SUFDSCxPQUFPLENBQUMsV0FBVztJQW1CbkI7O09BRUc7SUFDRyxLQUFLLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUczQjtJQUVEOzs7T0FHRztJQUNHLHFCQUFxQixDQUFDLE1BQU0sRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsTUFBTSxDQUFDLENBRzdFO0lBRUQ7Ozs7O09BS0c7SUFDRywyQkFBMkIsQ0FBQyxvQkFBb0IsRUFBRSxVQUFVLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUduRjtJQUVEOzs7OztPQUtHO0lBQ0csZ0JBQWdCLENBQUMsUUFBUSxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsTUFBTSxDQUFDLENBR3hEO0NBQ0YifQ==

package/dest/db/postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/db/postgres.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAG3D,OAAO,KAAK,EAAE,IAAI,EAAe,MAAM,IAAI,CAAC;AAE5C,OAAO,KAAK,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAQpF,OAAO,KAAK,EAAE,oBAAoB,EAAW,QAAQ,EAAuC,MAAM,YAAY,CAAC;AAE/G;;GAEG;AACH,qBAAa,kCAAmC,YAAW,0BAA0B;IAGvE,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YAA6B,IAAI,EAAE,IAAI,EAEtC;IAED;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAgChC;IAED;;;;;OAKG;IACG,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAwBxF;IAED;;;;;OAKG;IACG,gBAAgB,CACpB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAkBlB;IAED;;;;;;OAMG;IACG,UAAU,CACd,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAiBlB;IAED;;OAEG;IACH,OAAO,CAAC,WAAW;IAiBnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;IAED;;;OAGG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7E;CACF"}
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/db/postgres.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAE7D,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAI3D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAEtD,OAAO,KAAK,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAUpF,OAAO,KAAK,EAAE,oBAAoB,EAAW,QAAQ,EAAuC,MAAM,YAAY,CAAC;AAG/G;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,kCAAmC,YAAW,0BAA0B;IAGvE,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YAA6B,IAAI,EAAE,aAAa,EAE/C;IAED;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAgChC;IAED;;;;;;;;OAQG;IACG,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAoDxF;IAED;;;;;OAKG;IACG,gBAAgB,CACpB,aAAa,EAAE,UAAU,EACzB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,0BAA0B,EAAE,MAAM,GACjC,OAAO,CAAC,OAAO,CAAC,CAsBlB;IAED;;;;;;OAMG;IACG,UAAU,CACd,aAAa,EAAE,UAAU,EACzB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,0BAA0B,EAAE,MAAM,GACjC,OAAO,CAAC,OAAO,CAAC,CAqBlB;IAED;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAmBnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;IAED;;;OAGG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7E;IAED;;;;;OAKG;IACG,2BAA2B,CAAC,oBAAoB,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGnF;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxD;CACF"}