Skip to content

feat(core): implement configurable extension jitter (#500) - #547

Merged
AbdulmalikAlayande merged 1 commit into
TegoLabs:mainfrom
Peolite1:feat/configurable-extension-jitter
Jul 30, 2026
Merged

AbdulmalikAlayande merged 1 commit into
TegoLabs:mainfrom
Peolite1:feat/configurable-extension-jitter

Conversation

@Peolite1

Copy link
Copy Markdown
Contributor

What does this PR do?

This PR implements a configurable jitter window for auto-extension submissions, which is applied when multiple extensions are queued in a single daemon cycle. Closes #500.

Why?

If many watched contracts cross their extension threshold in the same cycle, the daemon previously submitted all extension transactions synchronously back-to-back. At fleet scale, this can cause self-inflicted network fee spikes. Spreading the submissions out randomly within a configured window (using the new opt-in --extension-jitter-ms flag) avoids these thundering-herd fee pressures while maintaining the correct rate-limit behavior.

Does this touch secret-key handling or transaction submission?

This touches src/core/extension.ts (specifically runAutoExtensions). A small asynchronous delay is introduced immediately prior to acquiring secret keys and submitting the transaction, spacing out the concurrent promises when jitter is enabled.

  • Yes — see notes above
  • No

Checklist

  • Tests pass (npm test)
  • Type check passes (npx tsc --noEmit)
  • Lint passes (npm run lint)
  • Tests cover the new functionality (TDD preferred — see CONTRIBUTING.md)
  • No unnecessary dependencies added
  • Commit messages follow conventional format
  • No console.log in core logic
  • ADR added if this is a significant design decision (see docs/adr)
  • E2E sandbox tested, if this touches RPC or daemon behavior (see docs/e2e-sandbox.md)

Closes #500

@drips-wave

drips-wave Bot commented Jul 29, 2026

Copy link
Copy Markdown

@Peolite1 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

coderabbitai Bot commented Jul 29, 2026 •

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Summary by CodeRabbit

  • New Features

    • Added an optional --extension-jitter-ms command-line setting to stagger extension processing.
    • Extension tasks now wait for a randomized delay when jitter is enabled, helping distribute processing over time.
  • Bug Fixes

    • Improved extension scheduling by processing only contracts with extensions pending, avoiding unnecessary work.

Walkthrough

Changes

Extension jitter scheduling

Layer / File(s) Summary
Precompute and jitter extension tasks
src/core/extension.ts
Eligible contracts are precomputed into tasks, and enabled jitter adds a random bounded delay before concurrent extension processing.
CLI option wiring
src/index.ts
The CLI accepts --extension-jitter-ms and exports the parsed value through EXTENSION_JITTER_MS.
Timing validation
tests/core/extension.test.ts
Tests cover default immediate execution and delayed execution with deterministic jitter.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant runAutoExtensions
  participant ExtensionTasks
  participant RPC
  CLI->>CLI: Parse --extension-jitter-ms
  CLI->>runAutoExtensions: Provide EXTENSION_JITTER_MS
  runAutoExtensions->>ExtensionTasks: Precompute queued contracts
  ExtensionTasks->>ExtensionTasks: Apply random per-task delays
  ExtensionTasks->>RPC: Submit extension transactions
Loading

Possibly related PRs

Suggested reviewers: abdulmalikalayande

Poem

I’m a rabbit with a jittery beat,
Spreading extension hops down the street.
No jitter? We race.
With jitter? More space.
Transactions nibble fees nice and neat.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly matches the main change: configurable extension jitter in core auto-extension handling.
Description check ✅ Passed The description is directly about configurable extension jitter and the new CLI flag.
Linked Issues check ✅ Passed The changes implement the jitter flag, randomized submission delay, and timing tests requested by #500.
Out of Scope Changes check ✅ Passed The edits stay within the requested core logic, CLI wiring, and tests for the jitter feature.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ 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

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 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 343-346: The jitter in the eligibleTasks scheduling at
src/core/extension.ts lines 343-346 must enforce nonzero separation between
submissions rather than starting independent timers; retain the configured
extensionJitterMs upper bound and update the scheduling logic accordingly. In
tests/core/extension.test.ts lines 869-877, record each submission timestamp and
assert that consecutive submissions are separated, replacing the
total-runtime-only assertion.

In `@src/index.ts`:
- Around line 32-33: Validate the CLI jitter option in src/index.ts near the
option definition as a non-negative integer strictly below the configured
polling interval, rejecting invalid values. Apply equivalent validation or a
safe cap to the environment-derived jitter in src/core/extension.ts around the
extension submission configuration so direct environment values cannot delay
submissions beyond the polling cycle.
- Around line 55-59: Update the extensionJitterMs environment-variable
assignment after program.opts() to check whether opts.extensionJitterMs is
undefined rather than relying on truthiness, so an explicit zero value
overwrites any inherited EXTENSION_JITTER_MS.

In `@tests/core/extension.test.ts`:
- Around line 813-842: Update the test case around runAutoExtensions to
explicitly unset EXTENSION_JITTER_MS before execution and restore its prior
environment value afterward. Use the test’s existing environment helper pattern,
ensuring cleanup occurs even if the assertion or async operation fails, while
preserving the duration assertion for the default no-jitter 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: ab94e270-5fc9-47af-97d2-4eaceb382b81

📥 Commits

Reviewing files that changed from the base of the PR and between 35d9237 and 79488fd.

📒 Files selected for processing (3)
  • src/core/extension.ts
  • src/index.ts
  • tests/core/extension.test.ts

Comment thread src/core/extension.ts
Comment thread src/index.ts
Comment thread src/index.ts
Comment thread tests/core/extension.test.ts
@gitguardian

gitguardian Bot commented Jul 29, 2026

Copy link
Copy Markdown

⚠️ 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


🦉 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.

@AbdulmalikAlayande
AbdulmalikAlayande merged commit 5bc1e7a into TegoLabs:main Jul 30, 2026
3 of 5 checks passed
@AbdulmalikAlayande

Copy link
Copy Markdown
Collaborator

Merged as 5bc1e7a on main — configurable extension jitter (--extension-jitter-ms), default 0 (no behavior change) as intended. Verified the global flag parses correctly both before and after the daemon subcommand. Verified locally: lint, typecheck, full suite (1100/1100, including all 30 extension tests), build, and audit all clean. Closing #500 as shipped.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(core): implement configurable extension jitter to avoid thundering-herd fee spikes across many contracts

2 participants