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

[EthTobi]

Summary

Adds a minimum-balance safety check () that verifies channel accounts have sufficient funds to cover transaction fees and base reserves before submitting extension transactions. When the balance is insufficient or unknown, the extension is skipped and alerts are fired through configured alert channels.

The CLI command is also enhanced to display balance information and highlight low-balance accounts.

Closes #504

What Changed

• Defines — the minimum XLM threshold required for channel accounts.
• In , after acquiring a channel account slot and resolving the secret key, checks the account balance:
  • If balance is / → skips extension with an error message
  • If balance < → skips extension, records an error, and fires alerts through the contract's configured alert channels
  • If balance ≥ → proceeds normally
• The balance check runs before transaction submission, preventing unnecessary RPC calls for doomed transactions.
• Channel slot is released in the block regardless of balance outcome.

• Imports from .
• Updated to display balance information for each channel account:
  • Balance ≥ threshold → dimmed
  • Balance < threshold → red
  • Balance unknown → dimmed

• Skip on low balance: seeds a channel account with balance below threshold and verifies skips extension.
• Fire alerts on skip: verifies that skipping due to low balance triggers alert delivery.
• Proceed on sufficient balance: verifies extensions proceed when balance meets threshold.
• Skip on unknown balance: verifies extension is skipped when channel account balance is /.

• Low-balance warning displayed: verifies the red label appears when balance < .
• No warning for sufficient balance: verifies the warning is omitted when balance ≥ threshold.

Testing

• All existing tests pass
• New tests cover:
  • Low balance → extension skipped + alerts fired
  • Sufficient balance → extension proceeds
  • Unknown balance → extension skipped
  • CLI balance display for low/normal/unknown balances

Checklist

• Tests written first (TDD)
• All existing tests pass
• No new dependencies added
• Balance threshold is configurable via constant
• CLI output includes actionable balance warnings
• Alerts fire on blocked extensions for observability

[drips-wave]

@EthTobi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Channel listings now show each account’s XLM balance.
  • Low balances are clearly marked, while unavailable balances are shown as unknown.
  • Automatic extensions now observe a five-minute cooldown and require sufficient channel-account funds.
  • Low-balance accounts can trigger configured alerts.

• Bug Fixes

  • Prevented extensions for recently processed, underfunded, or unknown-balance accounts.

Walkthrough

The change adds a five-minute extension cooldown, enforces a minimum channel-account balance before submission, sends alerts for low balances, and displays balance status in the channels list. Tests cover cooldown, balance validation, alerts, successful extension, and unknown balances.

Changes

Extension safety checks

Layer / File(s)	Summary
Balance threshold and channel listing src/core/extension.ts, src/commands/channels.ts, tests/commands/channels.test.ts	The exported minimum balance constant is used to display account balances and mark low balances with LOW.
Per-entry cooldown filtering src/core/extension.ts, tests/core/extension.test.ts, tests/core/rate_limiter.test.ts	Automatic extensions exclude recently extended entries. Tests use timestamps outside the cooldown period.
Pre-submission balance validation src/core/extension.ts, tests/core/extension.test.ts	Unknown or insufficient balances skip submission. Low balances record errors and trigger configured alert delivery. Sufficient balances proceed normally.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant runAutoExtensions
  participant channel_accounts repository
  participant alert dispatcher
  participant extension submission
  runAutoExtensions->>channel_accounts repository: read balance and extension history
  runAutoExtensions->>runAutoExtensions: filter cooldown-ineligible entries
  runAutoExtensions->>channel_accounts repository: validate channel-account balance
  runAutoExtensions->>alert dispatcher: deliver low-balance alert
  runAutoExtensions->>extension submission: submit eligible extensions

Loading

Possibly related PRs

• AbdulmalikAlayande/sorokeep#224 — Related channel listing and channel-account balance handling.
• AbdulmalikAlayande/sorokeep#225 — Related channel-account balance checks in extension processing.
• AbdulmalikAlayande/sorokeep#586 — Related per-entry cooldown logic and auto-extension tests.

Suggested reviewers: abdulmalikalayande

Poem

A rabbit checks the balance bright,
And keeps old extensions out of sight.
Low funds flash red, alerts take flight,
Strong accounts extend just right.
Cooldown guards the queue tonight.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR also adds extension cooldown filtering and related test changes, which are not part of issue #504.	Remove the cooldown-related implementation and test changes, or provide an explicit linked requirement that authorizes this additional scope.
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: a configurable minimum-balance safety check before extension submission.
Description check	✅ Passed	The description directly explains the balance checks, alert behavior, CLI updates, and test coverage.
Linked Issues check	✅ Passed	The changes satisfy issue #504 by checking balances, skipping unsafe submissions, firing alerts, updating CLI output, and adding tests.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gitguardian]

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

Since your pull request originates from a forked repository, GitGuardian is not able to associate the secrets uncovered with secret incidents on your GitGuardian dashboard.
Skipping this check run and merging your pull request will create secret incidents on your GitGuardian dashboard.

🔎 Detected hardcoded secret in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
-	-	Generic High Entropy Secret	ded54f4	tests/commands/guard-cli-export-import.test.ts	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secret safely. Learn here the best practices.
3. Revoke and rotate this secret.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/extension.ts`:
- Around line 450-471: Reuse the in-scope channelAccounts collection instead of
calling getChannelAccounts inside the extension loop, and find the matching
account from that collection. Replace the getContract(db, contract.id) re-fetch
with the existing contract object when configuring the alert, preserving the
current alert behavior and contract data usage.
- Around line 473-486: Update the threshold_crossed event construction in the
low-balance alert path to pass config.threshold_ledgers as configuredLedgers
instead of MINIMUM_BALANCE_XLM, preserving TTL severity calculations against the
configured ledger threshold. Extend the low-balance test to verify the delivered
event payload fields, including configuredLedgers and the TTL-related values.
- Around line 449-460: The unknown-balance warning in the slot handling flow
should direct users to the operation that actually refreshes balances, rather
than `sorokeep channels list`. Update the message constructed in the `balance
=== null || balance === undefined` branch while preserving the existing logging,
error collection, pool release, and return behavior.
- Around line 487-497: Update the low-balance alert path around
deliverSingleAlert to use the existing alerts_fired state and suppress repeat
notifications across extension cycles, matching the TTL threshold behavior.
Preserve error logging for failed deliveries, and ensure the alert state is
checked and recorded consistently before dispatch.
- Around line 39-57: Replace the hardcoded MINIMUM_BALANCE_XLM value with
configuration loading through loadConfig(), using 5 as the fallback when no
threshold is configured. Update the balance-checking flow to consume this
configured value while preserving the existing reserve and fee validation
behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e474b520-741b-41c7-9876-191ca3a306b7

📥 Commits

Reviewing files that changed from the base of the PR and between 1e4a880 and 381b28d.

📒 Files selected for processing (5)

• src/commands/channels.ts
• src/core/extension.ts
• tests/commands/channels.test.ts
• tests/core/extension.test.ts
• tests/core/rate_limiter.test.ts

📜 Review details

🧰 Additional context used

🪛 OpenGrep (1.26.0)

tests/core/extension.test.ts

[ERROR] 783-786: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.

(coderabbit.command-injection.exec-js)

🔇 Additional comments (8)

src/core/extension.ts (2)

384-421: LGTM!

---

504-504: LGTM!

src/commands/channels.ts (1)

6-6: LGTM!

Also applies to: 60-73

tests/commands/channels.test.ts (1)

6-6: LGTM!

Also applies to: 227-267

tests/core/extension.test.ts (3)

11-13: LGTM!

Also applies to: 39-45

---

782-787: LGTM!

---

897-1161: LGTM!

tests/core/rate_limiter.test.ts (1)

94-101: LGTM!

[coderabbitai]

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if loadConfig is used elsewhere in extension.ts
rg -n 'loadConfig' src/core/extension.ts

# Check the config schema/type for a balance-threshold-like field
rg -n -i 'balance|minimum|threshold|reserve' src/utils/config.ts

Repository: AbdulmalikAlayande/sorokeep

Length of output: 262

---

🏁 Script executed:

#!/bin/bash
set -u

printf '--- extension.ts around imports/config uses ---\n'
sed -n '1,90p' src/core/extension.ts
printf '\n--- extension.ts around config line 724 ---\n'
sed -n '700,745p' src/core/extension.ts

printf '\n--- config schema/type files ---\n'
fd -a 'config\.(ts|tsx|js)$' . | sed 's#^\./##' | sort
rg -n -i 'interface .*config|type .*config|class .*config|loaded|load|balance|minimum|threshold|reserve|channel' src/utils/config.ts src -g '*.ts' -g '*.js' | head -200

Repository: AbdulmalikAlayande/sorokeep

Length of output: 24227

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '--- src/utils/config.ts ---\n'
sed -n '1,110p' src/utils/config.ts

printf '\n--- occurrences of MINIMUM_BALANCE_XLM ---\n'
rg -n 'MINIMUM_BALANCE_XLM\b' src

printf '\n--- channel list/list balance command files ---\n'
fd -a '(^channels\.ts$|.*channels.*)' src/commands src | sort | sed 's#^\./##'
rg -n -i 'list|refresh|balance_xlm|run .channels|sorokeep channels' src/commands src -g '*.ts' | head -200

Repository: AbdulmalikAlayande/sorokeep

Length of output: 256

---

Make the minimum balance threshold configurable.

MINIMUM_BALANCE_XLM is a hardcoded constant, while issue #504 requires a configurable threshold covering transaction fees and the Stellar base reserve. Read the threshold from loadConfig() with 5 as the default instead of fixing it in source.

♻️ Proposed direction

-export const MINIMUM_BALANCE_XLM = 5;
+export function getMinimumBalanceXlm(): number {
+    const config = loadConfig();
+    return config.minimumChannelBalanceXlm ?? 5;
+}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/core/extension.ts` around lines 39 - 57, Replace the hardcoded
MINIMUM_BALANCE_XLM value with configuration loading through loadConfig(), using
5 as the fallback when no threshold is configured. Update the balance-checking
flow to consume this configured value while preserving the existing reserve and
fee validation behavior.

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find where balance_xlm actually gets updated from network data
rg -n 'updateChannelBalance\(' src -g '!**/tests/**'

# Confirm the actual behavior of 'channels list'
rg -n -A5 'command\("list"\)' src/commands/channels.ts

Repository: AbdulmalikAlayande/sorokeep

Length of output: 722

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate files =="
git ls-files | rg 'src/(core/extension\.ts|commands/channels\.ts|db/repositories\.ts|core/channels\.ts)$' || true

echo
echo "== extension warning context =="
sed -n '430,475p' src/core/extension.ts 2>/dev/null || true

echo
echo "== channels list implementation =="
sed -n '1,90p' src/commands/channels.ts 2>/dev/null || true

echo
echo "== getChannelAccounts / updateChannelBalance refs =="
rg -n "getChannelAccounts|updateChannelBalance|balance_xlm|xlm|SorobanRPC|getLedgerEntries|getBalance" src -g '!**/tests/**' | head -n 200 || true

Repository: AbdulmalikAlayande/sorokeep

Length of output: 19176

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== core/channels.ts balance refresh implementation =="
sed -n '1,190p' src/core/channels.ts

echo
echo "== updateChannelBalance definition =="
sed -n '990,1012p' src/db/repositories.ts

echo
echo "== all updateChannelBalance call sites outside tests =="
rg -n 'updateChannelBalance\(' src -g '!**/tests/**'

Repository: AbdulmalikAlayande/sorokeep

Length of output: 7543

---

Correct the unknown-balance guidance.

channels list only reads stored balance_xlm; it does not call the RPC or call refreshBalances(). If balance_xlm is null/undefined, the warning should reference the actual refresh operation instead of sorokeep channels list.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/core/extension.ts` around lines 449 - 460, The unknown-balance warning in
the slot handling flow should direct users to the operation that actually
refreshes balances, rather than `sorokeep channels list`. Update the message
constructed in the `balance === null || balance === undefined` branch while
preserving the existing logging, error collection, pool release, and return
behavior.

[coderabbitai]

🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Avoid re-fetching data already available in scope.

getChannelAccounts(db, network) at line 450 re-queries the full channel-account table even though channelAccounts was already fetched at line 341 and is in scope. getContract(db, contract.id) at line 470 likewise re-fetches a record that is likely already present on the contract object from eligibleContracts (sourced from getAllContracts).

Reuse the already-fetched values instead of issuing new queries per eligible task.

♻️ Proposed fix

             if (slot) {
-                const accounts = getChannelAccounts(db, network);
-                const channelAccount = accounts.find(a => a.public_key === slot!.publicKey);
+                const channelAccount = channelAccounts.find(a => a.public_key === slot!.publicKey);
                 const balance = channelAccount?.balance_xlm;

                     const sampleEntry = needsExtension[0]!;
-                    const contractRecord = getContract(db, contract.id);
+                    const contractRecord = contract;
                     const alertConfigs = getAlertConfigsForContract(db, contract.id);

Confirm contract already carries a name field matching Contract:

#!/bin/bash
ast-grep run --pattern 'interface Contract { $$$ }' --lang typescript src

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/core/extension.ts` around lines 450 - 471, Reuse the in-scope
channelAccounts collection instead of calling getChannelAccounts inside the
extension loop, and find the matching account from that collection. Replace the
getContract(db, contract.id) re-fetch with the existing contract object when
configuring the alert, preserving the current alert behavior and contract data
usage.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
sed -n '1,60p' src/alerts/types.ts
rg -n 'threshold_crossed|alert_resolved|low_balance' src/alerts --type ts

Repository: AbdulmalikAlayande/sorokeep

Length of output: 6912

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== extension relevant section =="
sed -n '430,520p' src/core/extension.ts

echo
echo "== constants and config usages =="
rg -n "MINIMUM_BALANCE_XLM|threshold_ledgers|buildAlertEvent|deliverSingleAlert|alert_config" src/core/extension.ts src -g '*.ts'

echo
echo "== alerts builder/contracts =="
sed -n '70,130p' src/alerts/types.ts
rg -n "function buildAlertEvent|type AlertEvent|interface .*Event|makeAlertEvent" src/alerts --type ts

echo
echo "== test coverage section =="
sed -n '995,1095p' tests/core/extension.test.ts

Repository: AbdulmalikAlayande/sorokeep

Length of output: 31145

---

Pass the TTL threshold into the low-balance alert event.

buildAlertEvent expects configuredLedgers to match the configured ledger threshold for threshold_crossed/alert_resolved events. This path uses MINIMUM_BALANCE_XLM for an XLM balance alert, but the event type is still TTL; this makes the payload read “configured ledgers: 5” and computes severity against that value instead of config.threshold_ledgers. Use the config’s ledger threshold here or create a balance-alert event type instead of overloading threshold_crossed. Also extend the low-balance test to assert the delivered event fields, not just that delivery was called.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/core/extension.ts` around lines 473 - 486, Update the threshold_crossed
event construction in the low-balance alert path to pass
config.threshold_ledgers as configuredLedgers instead of MINIMUM_BALANCE_XLM,
preserving TTL severity calculations against the configured ledger threshold.
Extend the low-balance test to verify the delivered event payload fields,
including configuredLedgers and the TTL-related values.

[coderabbitai]

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check other call sites of deliverSingleAlert/buildAlertEvent for a dedup/state-tracking wrapper
rg -n -B3 -A15 'deliverSingleAlert\(' src --type ts
rg -n 'alert_history|already_fired|last_alert|alert_state' src --type ts

Repository: AbdulmalikAlayande/sorokeep

Length of output: 6511

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== files =="
git ls-files 'src/**/*.ts' | sed -n '1,220p'

echo
echo "== extension outline/section =="
wc -l src/core/extension.ts
ast-grep outline src/core/extension.ts --match runAutoExtensions --view expanded || true
sed -n '440,510p' src/core/extension.ts

echo
echo "== promises/runAutoExtensions call sites =="
rg -n -B4 -A12 'runAutoExtensions|Promise\.all\(eligibleTasks|runPolling|cron|process\.on\(' src --type ts

echo
echo "== alert state/dedup/search =="
rg -n 'alert_history|already_fired|last_alert|alert_state|sentAlert|alert_sent|cooldown|ttl|firedAtLedger|FiredAtLedger|buildAlertEvent|buildTestEvent|send\(.*event|send\(' src --type ts | sed -n '1,260p'

echo
echo "== dispatcher relevant section =="
sed -n '150,210p' src/alerts/dispatcher.ts

Repository: AbdulmalikAlayande/sorokeep

Length of output: 26494

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== daemon startDaemon section =="
wc -l src/daemon/loop.ts
sed -n '1,260p' src/daemon/loop.ts

echo
echo "== monitor full alert resolution loop for dedupe =="
sed -n '220,310p' src/core/monitor.ts

echo
echo "== extension task loop full and alert firing section =="
sed -n '360,502p' src/core/extension.ts

echo
echo "== repositories alert fired helpers =="
sed -n '330,380p' src/db/repositories.ts
rg -n -B8 -A20 'function readAlertFiredRows|const readAlertFiredRows|export .*readAlertFiredRows|firedAtLedger|fired_at_ledger|ttl_at_fire' src/db/repositories.ts src/core/monitor.ts src/core/extension.ts | sed -n '1,240p'

Repository: AbdulmalikAlayande/sorokeep

Length of output: 38844

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== daemon commands usage =="
sed -n '1,130p' src/commands/daemon.ts

echo
echo "== entrypoint / program references =="
rg -n 'startDaemon|command\("\s*daemon|run.*daemon|executeCycle|process\.exit|process\.on\("SIG|SIGTERM|SIGINT' src --type ts

echo
echo "== CLI entrypoint =="
sed -n '1,180p' src/cli/program.ts

Repository: AbdulmalikAlayande/sorokeep

Length of output: 16440

---

Check low-balance alert spam before making this a blocking await.

This path calls deliverSingleAlert(...).catch(...) without adding the promise to a collectible set before Promise.all(eligibleTasks.map(...)), so delivery errors are still logged, but the warning should not be framed as silently dropped. The larger actionable concern is that this code does not insert/check an alerts_fired state like the TTL threshold path, so low-balance alerts can fire every extension cycle.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/core/extension.ts` around lines 487 - 497, Update the low-balance alert
path around deliverSingleAlert to use the existing alerts_fired state and
suppress repeat notifications across extension cycles, matching the TTL
threshold behavior. Preserve error logging for failed deliveries, and ensure the
alert state is checked and recorded consistently before dispatch.

[AbdulmalikAlayande]

Merged via 3cb8517 on main (ported from PR #656, your reconciled combination branch, since it represented your own final tested state including two real fixes — UTC timestamp parsing and remainingTTL clamping — beyond the original #587).

The design was exactly right: pre-flight balance check against the base reserve + fee margin, alert-fire-and-skip instead of attempt-and-fail, low-balance indicator in channels list. Applied as-is.

Only merged the min-balance delta here — the cooldown feature (#510/#586) is a separate issue and will be handled on its own. Thanks for reconciling the two branches so cleanly, that made this much easier to review.