Update known blocks subcommand

[LesnyRumcajs]

Summary of changes

Changes introduced in this pull request:

• totally vibe coded, AI was wrong in so many places, but I made it work in the end. It's not a critical piece of code and there are explicit links to verify all is good.
• no changelog entry because it's not a user-facing feature.

Reference issue to close (if applicable)

Part of #3264 - just need to modify the workflow in a separate PR

Other information and links

Sample output

❯ forest-dev update-checkpointsReading known blocks from: build/known_blocks.yaml=== Updating Calibnet Checkpoints ===Fetching chain head for calibnet...Current epoch: 3455852Existing max checkpoint epoch: 2937600Latest checkpoint epoch should be: 3369600Need to add 5 checkpoint(s)Fetching checkpoints via RPC... ✓ Epoch 3024000: bafy2bzacebc3obhbqtb5375alsxaqyypjsh4ho3fqq5baspzblw7tewryfqb6 Verify at: https://beryx.io/fil/calibration/block-cid/bafy2bzacebc3obhbqtb5375alsxaqyypjsh4ho3fqq5baspzblw7tewryfqb6 ✓ Epoch 3110397 (requested 3110400, no blocks at exact height): bafy2bzaceb7fz2umktqqckzbygfhcun4avpd6g5pgrmhg4w4rvsuywbbptm6e Verify at: https://beryx.io/fil/calibration/block-cid/bafy2bzaceb7fz2umktqqckzbygfhcun4avpd6g5pgrmhg4w4rvsuywbbptm6e ✓ Epoch 3196800: bafy2bzaceaokv4ccti3mso3jtp3dtp5m3viaazp72qdj64ycj7bcqjys7m74k Verify at: https://beryx.io/fil/calibration/block-cid/bafy2bzaceaokv4ccti3mso3jtp3dtp5m3viaazp72qdj64ycj7bcqjys7m74k ✓ Epoch 3283200: bafy2bzaceb7hvytlh7mfz7sne5mgve4xzmzlgwqpab2c2vqmokaezv5fberam Verify at: https://beryx.io/fil/calibration/block-cid/bafy2bzaceb7hvytlh7mfz7sne5mgve4xzmzlgwqpab2c2vqmokaezv5fberam ✓ Epoch 3369600: bafy2bzacecvz2ji6npz7kpgddib33uvprficdoabxghftivjcipy62msc3adi Verify at: https://beryx.io/fil/calibration/block-cid/bafy2bzacecvz2ji6npz7kpgddib33uvprficdoabxghftivjcipy62msc3adiAdding 5 new checkpoint(s) to the file...=== Updating Mainnet Checkpoints ===Fetching chain head for mainnet...Current epoch: 5756520Existing max checkpoint epoch: 5270400Latest checkpoint epoch should be: 5702400Need to add 5 checkpoint(s)Fetching checkpoints via RPC... ✓ Epoch 5356800: bafy2bzacecjskrcifcteuotqxwq5u5e7ol6z4zejqafn2ycco4abttt3vqmgy Verify at: https://beryx.io/fil/mainnet/block-cid/bafy2bzacecjskrcifcteuotqxwq5u5e7ol6z4zejqafn2ycco4abttt3vqmgy ✓ Epoch 5443200: bafy2bzacedisdelql35luibjoxk5jyw7iai5if4eezrjslwhtuqmcczdjahb2 Verify at: https://beryx.io/fil/mainnet/block-cid/bafy2bzacedisdelql35luibjoxk5jyw7iai5if4eezrjslwhtuqmcczdjahb2 ✓ Epoch 5529600: bafy2bzaceds5jrbauggh3jay6tmxzlagyahhprhfc6sdajaswsrmk3jcki4dc Verify at: https://beryx.io/fil/mainnet/block-cid/bafy2bzaceds5jrbauggh3jay6tmxzlagyahhprhfc6sdajaswsrmk3jcki4dc ✓ Epoch 5616000: bafy2bzacedzxdn25txdhu74gx4eqp45qmu4elbtgqq4b2nd65xcqkcdibvajm Verify at: https://beryx.io/fil/mainnet/block-cid/bafy2bzacedzxdn25txdhu74gx4eqp45qmu4elbtgqq4b2nd65xcqkcdibvajm ✓ Epoch 5702400: bafy2bzacebfnyqgjovmuybzo2e7whwm3exc7sviltvsjf42rij56o2dcaer2y Verify at: https://beryx.io/fil/mainnet/block-cid/bafy2bzacebfnyqgjovmuybzo2e7whwm3exc7sviltvsjf42rij56o2dcaer2yAdding 5 new checkpoint(s) to the file...=== Writing Updated Checkpoints ===Successfully updated: build/known_blocks.yaml

Change checklist

• I have performed a self-review of my own code,
• I have made corresponding changes to the documentation. All new code adheres to the team's documentation standards,
• I have added tests that prove my fix is effective or that my feature works (if possible),
• I have made sure the CHANGELOG is up-to-date. All user-facing changes should be reflected in this document.

Outside contributions

• I have read and agree to the CONTRIBUTING document.
• I have read and agree to the AI Policy document. I understand that failure to comply with the guidelines will lead to rejection of the pull request.

Summary by CodeRabbit

• New Features
  • Added a new CLI subcommand to update checkpoint data from RPC endpoints for Calibnet and/or Mainnet networks.
  • Supports dry-run mode to preview changes without writing to disk.
  • Automatically fetches and aggregates missing checkpoints at regular intervals.

[coderabbitai]

Walkthrough

The PR introduces a new CLI subcommand UpdateCheckpoints that programmatically updates the known_blocks.yaml checkpoint file by fetching checkpoint blocks from RPC endpoints for calibnet and/or mainnet networks, with support for dry-run mode and selective network targeting.

Changes

Cohort / File(s)	Summary
Dictionary Configuration .config/forest.dic	Incremental numeric update (73→75) and addition of two new entries (Filfox, YAML).
Subcommand Module Integration src/dev/subcommands/mod.rs	Wiring of new UpdateCheckpoints subcommand variant and its dispatch in the run() method.
Subcommand Implementation src/dev/subcommands/update_checkpoints_cmd.rs	New UpdateCheckpointsCommand struct and Network enum with logic to fetch checkpoints from RPC endpoints, compute missing epochs at 86400-epoch intervals, update YAML structure, and write back to disk with dry-run support.

Sequence Diagram

sequenceDiagram
participant User
participant CLI as UpdateCheckpoints<br/>Command
participant File as YAML File<br/>(known_blocks.yaml)
participant RPC as RPC Endpoint<br/>(Calibnet/Mainnet)
User->>CLI: Execute with network & RPC config
CLI->>File: Read known_blocks.yaml
File-->>CLI: Existing checkpoints
CLI->>RPC: Fetch chain head
RPC-->>CLI: Latest checkpoint height
CLI->>CLI: Compute missing epochs<br/>(86400 interval)
loop For each missing epoch
CLI->>RPC: fetch_checkpoint_at_height()
RPC-->>CLI: Block & CID
end
CLI->>CLI: Aggregate & sort checkpoints<br/>(descending by epoch)
alt dry_run mode
CLI->>User: Print updated YAML
else normal mode
CLI->>File: Write updated checkpoints
File-->>CLI: Write complete
end
CLI-->>User: Success/Error result

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related issues

• cron: update known_blocks.yaml #6378: This PR implements the automated checkpoint update mechanism for known_blocks.yaml that addresses the need for programmatic maintenance updates discussed in the issue.

Possibly related PRs

• chore: update known blocks #6388: Both PRs interact with the known_blocks.yaml checkpoint file—this PR adds programmatic discovery and update capability while the related PR performs manual checkpoint data updates.
• chore: update known blocks #5887: Directly related as both work with known_blocks.yaml to add missing epoch-to-block mappings, with this PR automating the process via RPC.
• chore: update known blocks #6602: Related through shared focus on updating known_blocks.yaml checkpoint data; this PR automates checkpoint discovery while the other performs manual updates.

Suggested labels

RPC

Suggested reviewers

• akaladarshi
• sudo-shashank
• hanabi1224

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Update known blocks subcommand' directly and clearly summarizes the main change: implementing/updating the known blocks subcommand functionality for checkpoint management.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch update-known-blocks-subcommand

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/dev/subcommands/update_checkpoints_cmd.rs`:
- Around line 68-70: Add a doc comment for the public async method
UpdateCheckpointsCommand::run describing what the command does, its behavior,
and the Result it returns; locate the impl UpdateCheckpointsCommand block and
add a /// comment above pub async fn run(self) -> anyhow::Result<()> that
summarizes purpose, side effects, and error conditions so the public API is
documented.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 149 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.20%. Comparing base (ca1ae7b) to head (e03f072).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/dev/subcommands/update_checkpoints_cmd.rs	0.00%	148 Missing ⚠️
src/dev/subcommands/mod.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/dev/subcommands/mod.rs	24.61% <0.00%> (-0.39%)	⬇️
src/dev/subcommands/update_checkpoints_cmd.rs	0.00% <0.00%> (ø)

... and 7 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ca1ae7b...e03f072. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.