feat(core): add configurable minimum-balance safety check before extension submission

src/commands/channels.ts

@@ -3,6 +3,7 @@ import chalk from "chalk";
 import { getDatabase } from "../db/database.js";
 import { getChannelAccounts } from "../db/repositories.js";
 import { addChannel, fundChannels } from "../core/channels.js";
+import { MINIMUM_BALANCE_XLM } from "../core/extension.js";
 import { formatContractID } from "../utils/formatting.js";
 
 export function registerChannelsCommand(program: Command): void {
@@ -56,7 +57,20 @@ export function registerChannelsCommand(program: Command): void {
             for (const account of accounts) {
                 const fundedBadge = account.funded ? chalk.green(" [funded]") : chalk.dim(" [unfunded]");
                 const label = account.label ? chalk.yellow(` ${account.label}`) : "";
-                console.log(`  ${chalk.cyan(account.public_key)}${label}${fundedBadge}`);
+
+                // Surface balance info and low-balance warning (issue #504)
+                let balanceInfo: string;
+                if (account.balance_xlm !== null && account.balance_xlm !== undefined) {
+                    const isLow = account.balance_xlm < MINIMUM_BALANCE_XLM;
+                    const balanceStr = `${account.balance_xlm} XLM`;
+                    balanceInfo = isLow
+                        ? chalk.red(` [balance: ${balanceStr} LOW]`)
+                        : chalk.dim(` [balance: ${balanceStr}]`);
+                } else {
+                    balanceInfo = chalk.dim(" [balance: unknown]");
+                }
+
+                console.log(`  ${chalk.cyan(account.public_key)}${label}${fundedBadge}${balanceInfo}`);
             }
             console.log();
         });

src/core/extension.ts

@@ -6,20 +6,24 @@ import {
     getEntriesForContract,
     getExtensionPolicy,
     getChannelAccounts,
+    getAlertConfigsForContract,
     recordExtension,
     upsertEntry,
     updateLastCheckedLedger,
     getAverageResourceUsage,
     getBudget,
     addBudgetSpent,
     countExtensionsInLastHour,
+    getExtensionHistory,
 
 } from "../db/repositories.js";
 import { ChannelAccountPool } from "./channels.js";
 import { getLogger } from "../logging/index.js";
 import { formatSecretKey } from "../utils/formatting.js";
 import { VaultResolver } from "./vault.js";
 import { loadConfig } from "../utils/config.js";
+import { deliverSingleAlert } from "../alerts/dispatcher.js";
+import { buildAlertEvent } from "../alerts/types.js";
 
 const logger = getLogger().child({ component: "Extension" });
 
@@ -32,6 +36,25 @@ const logger = getLogger().child({ component: "Extension" });
  */
 export const HOURLY_RATE_LIMIT = 5;
 
+/**
+ * Minimum time (in milliseconds) that must pass between two consecutive
+ * extensions of the same contract entry.  Prevents the same entry being
+ * extended twice in quick succession when the threshold is very tight
+ * relative to the target TTL.
+ *
+ * Default 5 minutes — slightly below the typical polling interval so it
+ * does not interfere with normal operation.
+ */
+export const EXTENSION_COOLDOWN_MS = 5 * 60 * 1000;
+
+/**
+ * Minimum XLM balance a channel account must hold before Sorokeep will submit
+ * an extension transaction through it.  Covers the base reserve (1 XLM) plus
+ * a safety margin for transaction fees.  Accounts below this threshold are
+ * skipped and an alert is fired rather than attempting a failing transaction.
+ */
+export const MINIMUM_BALANCE_XLM = 5;
+
 /**
  * Check whether the given contract has reached its hourly auto-extension rate limit.
  *
@@ -358,6 +381,44 @@ export async function runAutoExtensions(
                 return;
             }
 
+            // ── Cooldown check per entry (issue #510) ──────────────────────
+            // Filter out entries that were extended within the cooldown window
+            // to prevent redundant back-to-back extensions of the same entry.
+            const recentHistory = getExtensionHistory(db, contract.id, 1);
+            const lastExtendedAt = new Map<number, Date>();
+            for (const record of recentHistory) {
+                const entryId = record.contract_entry_id;
+                // executed_at is stored as UTC (SQLite CURRENT_TIMESTAMP); append
+                // "Z" so the timestamp is parsed as UTC regardless of the host
+                // machine's timezone.
+                const executedAt = new Date(record.executed_at + "Z");
+                const existing = lastExtendedAt.get(entryId);
+                if (!existing || executedAt > existing) {
+                    lastExtendedAt.set(entryId, executedAt);
+                }
+            }
+
+            const cooldownEligible = needsExtension.filter(e => {
+                const lastExt = lastExtendedAt.get(e.id);
+                if (!lastExt) return true; // never extended → eligible
+                const elapsed = Date.now() - lastExt.getTime();
+                if (elapsed < EXTENSION_COOLDOWN_MS) {
+                    logger.info(
+                        `Entry ${e.entry_key_xdr} for ${contract.id} was extended ` +
+                        `${Math.round(elapsed / 1000)}s ago — skipping (cooldown: ${EXTENSION_COOLDOWN_MS / 1000}s)`,
+                    );
+                    return false;
+                }
+                return true;
+            });
+
+            if (cooldownEligible.length === 0) {
+                logger.info(
+                    `All ${needsExtension.length} entries for ${contract.id} are within cooldown — skipping`,
+                );
+                return;
+            }
+
             // Resolve secret key: prefer channel pool, fall back to policy keypair
             let secretKey: string | null = null;
             let slot: import("./channels.js").ChannelSlot | null = null;
@@ -382,7 +443,65 @@ export async function runAutoExtensions(
                 return;
             }
 
-            const entryKeys = needsExtension.map(e => e.entry_key_xdr);
+            // ── Minimum-balance check (issue #504) ──────────────────────────
+            // If using a channel account, verify it has enough XLM to cover the
+            // transaction fee and base reserve before attempting submission.
+            if (slot) {
+                const accounts = getChannelAccounts(db, network);
+                const channelAccount = accounts.find(a => a.public_key === slot!.publicKey);
+                const balance = channelAccount?.balance_xlm;
+
+                if (balance === null || balance === undefined) {
+                    const msg = `Contract ${contract.id}: Channel account ${slot.publicKey} balance is unknown — skipping extension. Run 'sorokeep channels list' to refresh balances.`;
+                    logger.warn(msg);
+                    result.errors.push(msg);
+                    pool!.release(slot.publicKey);
+                    return;
+                }
+
+                if (balance < MINIMUM_BALANCE_XLM) {
+                    const msg = `Contract ${contract.id}: Channel account ${slot.publicKey} balance ${balance} XLM is below minimum ${MINIMUM_BALANCE_XLM} XLM — skipping extension.`;
+                    logger.warn(msg);
+                    result.errors.push(msg);
+
+                    // Fire alert through the contract's configured alert channels
+                    // using the first entry that needed extension as context
+                    const sampleEntry = needsExtension[0]!;
+                    const contractRecord = getContract(db, contract.id);
+                    const alertConfigs = getAlertConfigsForContract(db, contract.id);
+                    for (const config of alertConfigs) {
+                        const event = buildAlertEvent({
+                            type: "threshold_crossed",
+                            contractId: contract.id,
+                            contractName: contractRecord?.name ?? null,
+                            network,
+                            entryKeyXdr: sampleEntry.entry_key_xdr,
+                            entryType: sampleEntry.entry_type,
+                            entryLabel: sampleEntry.label,
+                            configuredLedgers: MINIMUM_BALANCE_XLM,
+                            remainingTTL: sampleEntry.live_until_ledger
+                                ? Math.max(0, sampleEntry.live_until_ledger - latestLedger)
+                                : 0,
+                            firedAtLedger: latestLedger,
+                        });
+                        deliverSingleAlert(
+                            config.channel_type,
+                            config.channel_target,
+                            event,
+                            config.webhook_secret,
+                        ).catch((err: unknown) => {
+                            logger.warn(
+                                `Low-balance alert delivery failed for channel ${config.channel_type}: ${err instanceof Error ? err.message : String(err)}`,
+                            );
+                        });
+                    }
+
+                    pool!.release(slot.publicKey);
+                    return;
+                }
+            }
+
+            const entryKeys = cooldownEligible.map(e => e.entry_key_xdr);
 
             logger.info(
                 `Auto-extending ${entryKeys.length} entries for ${contract.id} ` +

tests/commands/channels.test.ts

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import type Database from "better-sqlite3";
 import { getDatabaseForTesting } from "../../src/db/database";
 import { registerChannelsCommand } from "../../src/commands/channels";
-import { getChannelAccounts, insertChannelAccount } from "../../src/db/repositories";
+import { getChannelAccounts, insertChannelAccount, updateChannelBalance } from "../../src/db/repositories";
 
 let mockDb: Database.Database;
 
@@ -224,4 +224,45 @@ describe("channels command", () => {
             );
         });
     });
+
+    // ── Issue #504: channels list shows low-balance warning ──────────────
+
+    describe("channels list low-balance", () => {
+        it("shows a warning for channel accounts with low balance", () => {
+            insertChannelAccount(mockDb, {
+                public_key: "GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH85FYDNE5VRLJQJN5",
+                label: "low-bal",
+                network: "testnet",
+            });
+            updateChannelBalance(mockDb, "GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH85FYDNE5VRLJQJN5", 1.5);
+
+            const program = new Command();
+            registerChannelsCommand(program);
+
+            program.parse(["node", "sorokeep", "channels", "list", "--network", "testnet"]);
+
+            expect(consoleLogSpy).toHaveBeenCalledWith(
+                expect.stringContaining("GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH85FYDNE5VRLJQJN5")
+            );
+            const allCalls = consoleLogSpy.mock.calls.flat().join(" ");
+            expect(allCalls).toMatch(/LOW/);
+        });
+
+        it("does not show warning for accounts with sufficient balance", () => {
+            insertChannelAccount(mockDb, {
+                public_key: "GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH85FYDNE5VRLJQJN5",
+                label: "rich",
+                network: "testnet",
+            });
+            updateChannelBalance(mockDb, "GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH85FYDNE5VRLJQJN5", 50.0);
+
+            const program = new Command();
+            registerChannelsCommand(program);
+
+            program.parse(["node", "sorokeep", "channels", "list", "--network", "testnet"]);
+
+            const allCalls = consoleLogSpy.mock.calls.flat().join(" ");
+            expect(allCalls).not.toMatch(/LOW/);
+        });
+    });
 });