@aztec/validator-ha-signer 0.0.1-commit.0208eb9

package/dest/db/postgres.js

@@ -0,0 +1,210 @@
+/**
+ * PostgreSQL implementation of SlashingProtectionDatabase
+ */ import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { makeBackoff, retry } from '@aztec/foundation/retry';
+import { CLEANUP_OLD_DUTIES, CLEANUP_OUTDATED_ROLLUP_DUTIES, CLEANUP_OWN_STUCK_DUTIES, DELETE_DUTY, INSERT_OR_GET_DUTY, SCHEMA_VERSION, UPDATE_DUTY_SIGNED } from './schema.js';
+import { getBlockIndexFromDutyIdentifier } from './types.js';
+/**
+ * PostgreSQL implementation of the slashing protection database
+ */ export class PostgresSlashingProtectionDatabase {
+    pool;
+    log;
+    constructor(pool){
+        this.pool = pool;
+        this.log = createLogger('slashing-protection:postgres');
+    }
+    /**
+   * Verify that database migrations have been run and schema version matches.
+   * Should be called once at startup.
+   *
+   * @throws Error if migrations haven't been run or schema version is outdated
+   */ async initialize() {
+        let dbVersion;
+        try {
+            const result = await this.pool.query(`SELECT version FROM schema_version ORDER BY version DESC LIMIT 1`);
+            if (result.rows.length === 0) {
+                throw new Error('No version found');
+            }
+            dbVersion = result.rows[0].version;
+        } catch  {
+            throw new Error('Database schema not initialized. Please run migrations first: aztec migrate-ha-db up --database-url <url>');
+        }
+        if (dbVersion < SCHEMA_VERSION) {
+            throw new Error(`Database schema version ${dbVersion} is outdated (expected ${SCHEMA_VERSION}). Please run migrations: aztec migrate-ha-db up --database-url <url>`);
+        }
+        if (dbVersion > SCHEMA_VERSION) {
+            throw new Error(`Database schema version ${dbVersion} is newer than expected (${SCHEMA_VERSION}). Please update your application.`);
+        }
+        this.log.info('Database schema verified', {
+            version: dbVersion
+        });
+    }
+    /**
+   * Atomically try to insert a new duty record, or get the existing one if present.
+   *
+   * @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.
+   */ async tryInsertOrGetExisting(params) {
+        // create a token for ownership verification
+        const lockToken = randomBytes(16).toString('hex');
+        // Use fast retries with custom backoff: 10ms, 20ms, 30ms (then stop)
+        const fastBackoff = makeBackoff([
+            0.01,
+            0.02,
+            0.03
+        ]);
+        // Get the normalized block index using type-safe helper
+        const blockIndexWithinCheckpoint = getBlockIndexFromDutyIdentifier(params);
+        const result = await retry(async ()=>{
+            const queryResult = await this.pool.query(INSERT_OR_GET_DUTY, [
+                params.rollupAddress.toString(),
+                params.validatorAddress.toString(),
+                params.slot.toString(),
+                params.blockNumber.toString(),
+                blockIndexWithinCheckpoint,
+                params.dutyType,
+                params.messageHash,
+                params.nodeId,
+                lockToken
+            ]);
+            // Throw error if no rows to trigger retry
+            if (queryResult.rows.length === 0) {
+                throw new Error('INSERT_OR_GET_DUTY returned no rows');
+            }
+            return queryResult;
+        }, `INSERT_OR_GET_DUTY for node ${params.nodeId}`, fastBackoff, this.log, true);
+        if (result.rows.length === 0) {
+            // this should never happen as the retry function should throw if it still fails after retries
+            throw new Error('INSERT_OR_GET_DUTY returned no rows after retries');
+        }
+        if (result.rows.length > 1) {
+            // this should never happen if database constraints are correct (PRIMARY KEY should prevent duplicates)
+            throw new Error(`INSERT_OR_GET_DUTY returned ${result.rows.length} rows (expected exactly 1).`);
+        }
+        const row = result.rows[0];
+        return {
+            isNew: row.is_new,
+            record: this.rowToRecord(row)
+        };
+    }
+    /**
+   * Update a duty to 'signed' status with the signature.
+   * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+   *
+   * @returns true if the update succeeded, false if token didn't match or duty not found
+   */ async updateDutySigned(rollupAddress, validatorAddress, slot, dutyType, signature, lockToken, blockIndexWithinCheckpoint) {
+        const result = await this.pool.query(UPDATE_DUTY_SIGNED, [
+            signature,
+            rollupAddress.toString(),
+            validatorAddress.toString(),
+            slot.toString(),
+            dutyType,
+            blockIndexWithinCheckpoint,
+            lockToken
+        ]);
+        if (result.rowCount === 0) {
+            this.log.warn('Failed to update duty to signed status: invalid token or duty not found', {
+                rollupAddress: rollupAddress.toString(),
+                validatorAddress: validatorAddress.toString(),
+                slot: slot.toString(),
+                dutyType,
+                blockIndexWithinCheckpoint
+            });
+            return false;
+        }
+        return true;
+    }
+    /**
+   * Delete a duty record.
+   * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+   * Used when signing fails to allow another node/attempt to retry.
+   *
+   * @returns true if the delete succeeded, false if token didn't match or duty not found
+   */ async deleteDuty(rollupAddress, validatorAddress, slot, dutyType, lockToken, blockIndexWithinCheckpoint) {
+        const result = await this.pool.query(DELETE_DUTY, [
+            rollupAddress.toString(),
+            validatorAddress.toString(),
+            slot.toString(),
+            dutyType,
+            blockIndexWithinCheckpoint,
+            lockToken
+        ]);
+        if (result.rowCount === 0) {
+            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;
+        }
+        return true;
+    }
+    /**
+   * Convert a database row to a ValidatorDutyRecord
+   */ rowToRecord(row) {
+        return {
+            rollupAddress: EthAddress.fromString(row.rollup_address),
+            validatorAddress: EthAddress.fromString(row.validator_address),
+            slot: SlotNumber.fromString(row.slot),
+            blockNumber: BlockNumber.fromString(row.block_number),
+            blockIndexWithinCheckpoint: row.block_index_within_checkpoint,
+            dutyType: row.duty_type,
+            status: row.status,
+            messageHash: row.message_hash,
+            signature: row.signature ?? undefined,
+            nodeId: row.node_id,
+            lockToken: row.lock_token,
+            startedAt: row.started_at,
+            completedAt: row.completed_at ?? undefined,
+            errorMessage: row.error_message ?? undefined
+        };
+    }
+    /**
+   * Close the database connection pool
+   */ async close() {
+        await this.pool.end();
+        this.log.info('Database connection pool closed');
+    }
+    /**
+   * Cleanup own stuck duties
+   * @returns the number of duties cleaned up
+   */ async cleanupOwnStuckDuties(nodeId, maxAgeMs) {
+        const cutoff = new Date(Date.now() - maxAgeMs);
+        const result = await this.pool.query(CLEANUP_OWN_STUCK_DUTIES, [
+            nodeId,
+            cutoff
+        ]);
+        return result.rowCount ?? 0;
+    }
+    /**
+   * 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
+   */ async cleanupOutdatedRollupDuties(currentRollupAddress) {
+        const result = await this.pool.query(CLEANUP_OUTDATED_ROLLUP_DUTIES, [
+            currentRollupAddress.toString()
+        ]);
+        return result.rowCount ?? 0;
+    }
+    /**
+   * 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
+   */ async cleanupOldDuties(maxAgeMs) {
+        const cutoff = new Date(Date.now() - maxAgeMs);
+        const result = await this.pool.query(CLEANUP_OLD_DUTIES, [
+            cutoff
+        ]);
+        return result.rowCount ?? 0;
+    }
+}

package/dest/db/schema.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SQL schema for the validator_duties table
+ *
+ * This table is used for distributed locking and slashing protection across multiple validator nodes.
+ * The PRIMARY KEY constraint ensures that only one node can acquire the lock for a given validator,
+ * slot, and duty type combination.
+ */
+/**
+ * Current schema version
+ */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * SQL to create the validator_duties table
+ */
+export declare const CREATE_VALIDATOR_DUTIES_TABLE = "\nCREATE TABLE IF NOT EXISTS validator_duties (\n  rollup_address VARCHAR(42) NOT NULL,\n  validator_address VARCHAR(42) NOT NULL,\n  slot BIGINT NOT NULL,\n  block_number BIGINT NOT NULL,\n  block_index_within_checkpoint INTEGER NOT NULL DEFAULT 0,\n  duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'CHECKPOINT_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS', 'GOVERNANCE_VOTE', 'SLASHING_VOTE')),\n  status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed')),\n  message_hash VARCHAR(66) NOT NULL,\n  signature VARCHAR(132),\n  node_id VARCHAR(255) NOT NULL,\n  lock_token VARCHAR(64) NOT NULL,\n  started_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  completed_at TIMESTAMP,\n  error_message TEXT,\n\n  PRIMARY KEY (rollup_address, validator_address, slot, duty_type, block_index_within_checkpoint),\n  CHECK (completed_at IS NULL OR completed_at >= started_at)\n);\n";
+/**
+ * SQL to create index on status and started_at for cleanup queries
+ */
+export declare const CREATE_STATUS_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_validator_duties_status\nON validator_duties(status, started_at);\n";
+/**
+ * SQL to create index for querying duties by node
+ */
+export declare const CREATE_NODE_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_validator_duties_node\nON validator_duties(node_id, started_at);\n";
+/**
+ * SQL to create the schema_version table for tracking migrations
+ */
+export declare const CREATE_SCHEMA_VERSION_TABLE = "\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n";
+/**
+ * SQL to initialize schema version
+ */
+export declare const INSERT_SCHEMA_VERSION = "\nINSERT INTO schema_version (version)\nVALUES ($1)\nON CONFLICT (version) DO NOTHING;\n";
+/**
+ * Complete schema setup - all statements in order
+ */
+export declare const SCHEMA_SETUP: readonly ["\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n", "\nCREATE TABLE IF NOT EXISTS validator_duties (\n  rollup_address VARCHAR(42) NOT NULL,\n  validator_address VARCHAR(42) NOT NULL,\n  slot BIGINT NOT NULL,\n  block_number BIGINT NOT NULL,\n  block_index_within_checkpoint INTEGER NOT NULL DEFAULT 0,\n  duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'CHECKPOINT_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS', 'GOVERNANCE_VOTE', 'SLASHING_VOTE')),\n  status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed')),\n  message_hash VARCHAR(66) NOT NULL,\n  signature VARCHAR(132),\n  node_id VARCHAR(255) NOT NULL,\n  lock_token VARCHAR(64) NOT NULL,\n  started_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  completed_at TIMESTAMP,\n  error_message TEXT,\n\n  PRIMARY KEY (rollup_address, validator_address, slot, duty_type, block_index_within_checkpoint),\n  CHECK (completed_at IS NULL OR completed_at >= started_at)\n);\n", "\nCREATE INDEX IF NOT EXISTS idx_validator_duties_status\nON validator_duties(status, started_at);\n", "\nCREATE INDEX IF NOT EXISTS idx_validator_duties_node\nON validator_duties(node_id, started_at);\n"];
+/**
+ * Query to get current schema version
+ */
+export declare const GET_SCHEMA_VERSION = "\nSELECT version FROM schema_version ORDER BY version DESC LIMIT 1;\n";
+/**
+ * Atomic insert-or-get query.
+ * Tries to insert a new duty record. If a record already exists (conflict),
+ * returns the existing record instead.
+ *
+ * Returns the record with an `is_new` flag indicating whether we inserted or got existing.
+ *
+ * Note: In high concurrency scenarios, if the INSERT conflicts and another transaction
+ * just committed the row, there's a small window where the SELECT might not see it yet.
+ * The application layer should retry if no rows are returned.
+ */
+export declare const INSERT_OR_GET_DUTY = "\nWITH inserted AS (\n  INSERT INTO validator_duties (\n    rollup_address,\n    validator_address,\n    slot,\n    block_number,\n    block_index_within_checkpoint,\n    duty_type,\n    status,\n    message_hash,\n    node_id,\n    lock_token,\n    started_at\n  ) VALUES ($1, $2, $3, $4, $5, $6, 'signing', $7, $8, $9, CURRENT_TIMESTAMP)\n  ON CONFLICT (rollup_address, validator_address, slot, duty_type, block_index_within_checkpoint) DO NOTHING\n  RETURNING\n    rollup_address,\n    validator_address,\n    slot,\n    block_number,\n    block_index_within_checkpoint,\n    duty_type,\n    status,\n    message_hash,\n    signature,\n    node_id,\n    lock_token,\n    started_at,\n    completed_at,\n    error_message,\n    TRUE as is_new\n)\nSELECT * FROM inserted\nUNION ALL\nSELECT\n  rollup_address,\n  validator_address,\n  slot,\n  block_number,\n  block_index_within_checkpoint,\n  duty_type,\n  status,\n  message_hash,\n  signature,\n  node_id,\n  '' as lock_token,\n  started_at,\n  completed_at,\n  error_message,\n  FALSE as is_new\nFROM validator_duties\nWHERE rollup_address = $1\n  AND validator_address = $2\n  AND slot = $3\n  AND duty_type = $6\n  AND block_index_within_checkpoint = $5\n  AND NOT EXISTS (SELECT 1 FROM inserted);\n";
+/**
+ * Query to update a duty to 'signed' status
+ */
+export declare const UPDATE_DUTY_SIGNED = "\nUPDATE validator_duties\nSET status = 'signed',\n    signature = $1,\n    completed_at = CURRENT_TIMESTAMP\nWHERE rollup_address = $2\n  AND validator_address = $3\n  AND slot = $4\n  AND duty_type = $5\n  AND block_index_within_checkpoint = $6\n  AND status = 'signing'\n  AND lock_token = $7;\n";
+/**
+ * Query to delete a duty
+ * Only deletes if the lockToken matches
+ */
+export declare const DELETE_DUTY = "\nDELETE FROM validator_duties\nWHERE rollup_address = $1\n  AND validator_address = $2\n  AND slot = $3\n  AND duty_type = $4\n  AND block_index_within_checkpoint = $5\n  AND status = 'signing'\n  AND lock_token = $6;\n";
+/**
+ * Query to clean up old signed duties (for maintenance)
+ * Removes signed duties older than a specified timestamp
+ */
+export declare const CLEANUP_OLD_SIGNED_DUTIES = "\nDELETE FROM validator_duties\nWHERE status = 'signed'\n  AND completed_at < $1;\n";
+/**
+ * Query to clean up old duties (for maintenance)
+ * Removes SIGNED duties older than a specified timestamp
+ */
+export declare const CLEANUP_OLD_DUTIES = "\nDELETE FROM validator_duties\nWHERE status = 'signed'\n  AND started_at < $1;\n";
+/**
+ * Query to cleanup own stuck duties
+ * Removes duties in 'signing' status for a specific node that are older than maxAgeMs
+ */
+export declare const CLEANUP_OWN_STUCK_DUTIES = "\nDELETE FROM validator_duties\nWHERE node_id = $1\n  AND status = 'signing'\n  AND started_at < $2;\n";
+/**
+ * Query to 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
+ */
+export declare const CLEANUP_OUTDATED_ROLLUP_DUTIES = "\nDELETE FROM validator_duties\nWHERE rollup_address != $1;\n";
+/**
+ * SQL to drop the validator_duties table
+ */
+export declare const DROP_VALIDATOR_DUTIES_TABLE = "DROP TABLE IF EXISTS validator_duties;";
+/**
+ * SQL to drop the schema_version table
+ */
+export declare const DROP_SCHEMA_VERSION_TABLE = "DROP TABLE IF EXISTS schema_version;";
+/**
+ * Query to get stuck duties (for monitoring/alerting)
+ * Returns duties in 'signing' status that have been stuck for too long
+ */
+export declare const GET_STUCK_DUTIES = "\nSELECT\n  rollup_address,\n  validator_address,\n  slot,\n  block_number,\n  block_index_within_checkpoint,\n  duty_type,\n  status,\n  message_hash,\n  node_id,\n  started_at,\n  EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - started_at)) as age_seconds\nFROM validator_duties\nWHERE status = 'signing'\n  AND started_at < $1\nORDER BY started_at ASC;\n";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZGIvc2NoZW1hLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7R0FNRztBQUVIOztHQUVHO0FBQ0gsZUFBTyxNQUFNLGNBQWMsSUFBSSxDQUFDO0FBRWhDOztHQUVHO0FBQ0gsZUFBTyxNQUFNLDZCQUE2QixzNUJBb0J6QyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0sbUJBQW1CLHlHQUcvQixDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0saUJBQWlCLHdHQUc3QixDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0sMkJBQTJCLG1KQUt2QyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0scUJBQXFCLDZGQUlqQyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0sWUFBWSxpd0NBS2YsQ0FBQztBQUVYOztHQUVHO0FBQ0gsZUFBTyxNQUFNLGtCQUFrQiwwRUFFOUIsQ0FBQztBQUVGOzs7Ozs7Ozs7O0dBVUc7QUFDSCxlQUFPLE1BQU0sa0JBQWtCLDZ1Q0EwRDlCLENBQUM7QUFFRjs7R0FFRztBQUNILGVBQU8sTUFBTSxrQkFBa0IsK1NBWTlCLENBQUM7QUFFRjs7O0dBR0c7QUFDSCxlQUFPLE1BQU0sV0FBVyxpT0FTdkIsQ0FBQztBQUVGOzs7R0FHRztBQUNILGVBQU8sTUFBTSx5QkFBeUIsd0ZBSXJDLENBQUM7QUFFRjs7O0dBR0c7QUFDSCxlQUFPLE1BQU0sa0JBQWtCLHNGQUk5QixDQUFDO0FBRUY7OztHQUdHO0FBQ0gsZUFBTyxNQUFNLHdCQUF3QiwyR0FLcEMsQ0FBQztBQUVGOzs7O0dBSUc7QUFDSCxlQUFPLE1BQU0sOEJBQThCLGtFQUcxQyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0sMkJBQTJCLDJDQUEyQyxDQUFDO0FBRXBGOztHQUVHO0FBQ0gsZUFBTyxNQUFNLHlCQUF5Qix5Q0FBeUMsQ0FBQztBQUVoRjs7O0dBR0c7QUFDSCxlQUFPLE1BQU0sZ0JBQWdCLGtXQWlCNUIsQ0FBQyJ9

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/db/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;GAEG;AACH,eAAO,MAAM,6BAA6B,s5BAoBzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,yGAG/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,wGAG7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,mJAKvC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,6FAIjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,iwCAKf,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,kBAAkB,0EAE9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,6uCA0D9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,+SAY9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,iOASvB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,wFAIrC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,sFAI9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,2GAKpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,kEAG1C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,2CAA2C,CAAC;AAEpF;;GAEG;AACH,eAAO,MAAM,yBAAyB,yCAAyC,CAAC;AAEhF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,kWAiB5B,CAAC"}

package/dest/db/schema.js

@@ -0,0 +1,229 @@
+/**
+ * SQL schema for the validator_duties table
+ *
+ * This table is used for distributed locking and slashing protection across multiple validator nodes.
+ * The PRIMARY KEY constraint ensures that only one node can acquire the lock for a given validator,
+ * slot, and duty type combination.
+ */ /**
+ * Current schema version
+ */ export const SCHEMA_VERSION = 1;
+/**
+ * SQL to create the validator_duties table
+ */ export const CREATE_VALIDATOR_DUTIES_TABLE = `
+CREATE TABLE IF NOT EXISTS validator_duties (
+  rollup_address VARCHAR(42) NOT NULL,
+  validator_address VARCHAR(42) NOT NULL,
+  slot BIGINT NOT NULL,
+  block_number BIGINT NOT NULL,
+  block_index_within_checkpoint INTEGER NOT NULL DEFAULT 0,
+  duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'CHECKPOINT_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS', 'GOVERNANCE_VOTE', 'SLASHING_VOTE')),
+  status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed')),
+  message_hash VARCHAR(66) NOT NULL,
+  signature VARCHAR(132),
+  node_id VARCHAR(255) NOT NULL,
+  lock_token VARCHAR(64) NOT NULL,
+  started_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  completed_at TIMESTAMP,
+  error_message TEXT,
+
+  PRIMARY KEY (rollup_address, validator_address, slot, duty_type, block_index_within_checkpoint),
+  CHECK (completed_at IS NULL OR completed_at >= started_at)
+);
+`;
+/**
+ * SQL to create index on status and started_at for cleanup queries
+ */ export const CREATE_STATUS_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_validator_duties_status
+ON validator_duties(status, started_at);
+`;
+/**
+ * SQL to create index for querying duties by node
+ */ export const CREATE_NODE_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_validator_duties_node
+ON validator_duties(node_id, started_at);
+`;
+/**
+ * SQL to create the schema_version table for tracking migrations
+ */ export const CREATE_SCHEMA_VERSION_TABLE = `
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+`;
+/**
+ * SQL to initialize schema version
+ */ export const INSERT_SCHEMA_VERSION = `
+INSERT INTO schema_version (version)
+VALUES ($1)
+ON CONFLICT (version) DO NOTHING;
+`;
+/**
+ * Complete schema setup - all statements in order
+ */ export const SCHEMA_SETUP = [
+    CREATE_SCHEMA_VERSION_TABLE,
+    CREATE_VALIDATOR_DUTIES_TABLE,
+    CREATE_STATUS_INDEX,
+    CREATE_NODE_INDEX
+];
+/**
+ * Query to get current schema version
+ */ export const GET_SCHEMA_VERSION = `
+SELECT version FROM schema_version ORDER BY version DESC LIMIT 1;
+`;
+/**
+ * Atomic insert-or-get query.
+ * Tries to insert a new duty record. If a record already exists (conflict),
+ * returns the existing record instead.
+ *
+ * Returns the record with an `is_new` flag indicating whether we inserted or got existing.
+ *
+ * Note: In high concurrency scenarios, if the INSERT conflicts and another transaction
+ * just committed the row, there's a small window where the SELECT might not see it yet.
+ * The application layer should retry if no rows are returned.
+ */ export const INSERT_OR_GET_DUTY = `
+WITH inserted AS (
+  INSERT INTO validator_duties (
+    rollup_address,
+    validator_address,
+    slot,
+    block_number,
+    block_index_within_checkpoint,
+    duty_type,
+    status,
+    message_hash,
+    node_id,
+    lock_token,
+    started_at
+  ) VALUES ($1, $2, $3, $4, $5, $6, 'signing', $7, $8, $9, CURRENT_TIMESTAMP)
+  ON CONFLICT (rollup_address, validator_address, slot, duty_type, block_index_within_checkpoint) DO NOTHING
+  RETURNING
+    rollup_address,
+    validator_address,
+    slot,
+    block_number,
+    block_index_within_checkpoint,
+    duty_type,
+    status,
+    message_hash,
+    signature,
+    node_id,
+    lock_token,
+    started_at,
+    completed_at,
+    error_message,
+    TRUE as is_new
+)
+SELECT * FROM inserted
+UNION ALL
+SELECT
+  rollup_address,
+  validator_address,
+  slot,
+  block_number,
+  block_index_within_checkpoint,
+  duty_type,
+  status,
+  message_hash,
+  signature,
+  node_id,
+  '' as lock_token,
+  started_at,
+  completed_at,
+  error_message,
+  FALSE as is_new
+FROM validator_duties
+WHERE rollup_address = $1
+  AND validator_address = $2
+  AND slot = $3
+  AND duty_type = $6
+  AND block_index_within_checkpoint = $5
+  AND NOT EXISTS (SELECT 1 FROM inserted);
+`;
+/**
+ * Query to update a duty to 'signed' status
+ */ export const UPDATE_DUTY_SIGNED = `
+UPDATE validator_duties
+SET status = 'signed',
+    signature = $1,
+    completed_at = CURRENT_TIMESTAMP
+WHERE rollup_address = $2
+  AND validator_address = $3
+  AND slot = $4
+  AND duty_type = $5
+  AND block_index_within_checkpoint = $6
+  AND status = 'signing'
+  AND lock_token = $7;
+`;
+/**
+ * Query to delete a duty
+ * Only deletes if the lockToken matches
+ */ export const DELETE_DUTY = `
+DELETE FROM validator_duties
+WHERE rollup_address = $1
+  AND validator_address = $2
+  AND slot = $3
+  AND duty_type = $4
+  AND block_index_within_checkpoint = $5
+  AND status = 'signing'
+  AND lock_token = $6;
+`;
+/**
+ * Query to clean up old signed duties (for maintenance)
+ * Removes signed duties older than a specified timestamp
+ */ export const CLEANUP_OLD_SIGNED_DUTIES = `
+DELETE FROM validator_duties
+WHERE status = 'signed'
+  AND completed_at < $1;
+`;
+/**
+ * Query to clean up old duties (for maintenance)
+ * Removes SIGNED duties older than a specified timestamp
+ */ export const CLEANUP_OLD_DUTIES = `
+DELETE FROM validator_duties
+WHERE status = 'signed'
+  AND started_at < $1;
+`;
+/**
+ * Query to cleanup own stuck duties
+ * Removes duties in 'signing' status for a specific node that are older than maxAgeMs
+ */ export const CLEANUP_OWN_STUCK_DUTIES = `
+DELETE FROM validator_duties
+WHERE node_id = $1
+  AND status = 'signing'
+  AND started_at < $2;
+`;
+/**
+ * Query to 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
+ */ export const CLEANUP_OUTDATED_ROLLUP_DUTIES = `
+DELETE FROM validator_duties
+WHERE rollup_address != $1;
+`;
+/**
+ * SQL to drop the validator_duties table
+ */ export const DROP_VALIDATOR_DUTIES_TABLE = `DROP TABLE IF EXISTS validator_duties;`;
+/**
+ * SQL to drop the schema_version table
+ */ export const DROP_SCHEMA_VERSION_TABLE = `DROP TABLE IF EXISTS schema_version;`;
+/**
+ * Query to get stuck duties (for monitoring/alerting)
+ * Returns duties in 'signing' status that have been stuck for too long
+ */ export const GET_STUCK_DUTIES = `
+SELECT
+  rollup_address,
+  validator_address,
+  slot,
+  block_number,
+  block_index_within_checkpoint,
+  duty_type,
+  status,
+  message_hash,
+  node_id,
+  started_at,
+  EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - started_at)) as age_seconds
+FROM validator_duties
+WHERE status = 'signing'
+  AND started_at < $1
+ORDER BY started_at ASC;
+`;

package/dest/db/test_helper.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Test helpers for database setup
+ */
+import type { PGlite } from '@electric-sql/pglite';
+/**
+ * Set up the database schema for testing.
+ * This runs the same SQL that migrations would apply.
+ */
+export declare function setupTestSchema(pglite: PGlite): Promise<void>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVzdF9oZWxwZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi90ZXN0X2hlbHBlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUNILE9BQU8sS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBSW5EOzs7R0FHRztBQUNILHdCQUFzQixlQUFlLENBQUMsTUFBTSxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBS25FIn0=

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

@@ -0,0 +1 @@
+{"version":3,"file":"test_helper.d.ts","sourceRoot":"","sources":["../../src/db/test_helper.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAInD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnE"}

package/dest/db/test_helper.js

@@ -0,0 +1,14 @@
+/**
+ * Test helpers for database setup
+ */ import { INSERT_SCHEMA_VERSION, SCHEMA_SETUP, SCHEMA_VERSION } from './schema.js';
+/**
+ * Set up the database schema for testing.
+ * This runs the same SQL that migrations would apply.
+ */ export async function setupTestSchema(pglite) {
+    for (const statement of SCHEMA_SETUP){
+        await pglite.query(statement);
+    }
+    await pglite.query(INSERT_SCHEMA_VERSION, [
+        SCHEMA_VERSION
+    ]);
+}