Repository navigation
Conversation
Add comprehensive documentation updates for upcoming bridge node changes: - Document new default pruning mode for bridge nodes (PR #4768) - Add --archival flag documentation for full historical data retention - Include routing exchange optimization notes (PR #4758) - Update hardware requirements to clarify pruned vs archival modes - Add migration guide for existing bridge node operators - Update custom networks docs with genesis hash requirements - Add breaking change warnings across all relevant pages Note: Version placeholders (TODO) added pending release of PR #4768 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Summary of ChangesHello @jcstein, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request updates the Celestia documentation to reflect significant changes in bridge node behavior, primarily the shift to default pruning mode and the introduction of an explicit archival mode. It provides crucial information for operators on how to manage their nodes, including a migration guide and specific considerations for private networks. The updates aim to clarify the new operational paradigms and ensure users can configure their bridge nodes appropriately for their specific needs, whether for reduced storage or full historical data access. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
|
🚀 Preview Deployment Your preview is ready: https://celestiaorg.github.io/docs-preview/pr-2402/ |
- Fixed confusing description that incorrectly implied 0 was default for non-archival nodes - Clarified that 0 disables pruning (archival mode) - Added note about typical default window for non-archival nodes
| - Required if you need to serve data to light nodes for blocks outside the availability window | ||
|
|
||
| <Callout type="info"> | ||
| **Routing Exchange Optimization**: Bridge nodes automatically optimize header synchronization using a routing exchange mechanism. Requests within the data availability window are routed to the core exchange for complete blocks, while requests outside the window are routed to the P2P exchange for headers only. This optimization happens automatically without any configuration needed. |
There was a problem hiding this comment.
before merging, review if this is necessary
- Removed premature migration instructions for unreleased feature - Will add proper guidance once PR #4768 is released with version info - Avoids confusion with untested migration steps
- Added tabs component to show pruned (default) vs archival mode options - Cleaner presentation that reduces repetition in documentation - Makes it clear which mode is the default behavior
…' into jcstein/review-pr-2402-relevance
jcstein
changed the title
Merge current main and preserve newer network and hardware guidance.
gbarros
left a comment
gbarros
left a comment
There was a problem hiding this comment.
Default pruning, passing --archival on every start, and Q4 trimming match celestia-node v0.33.2 and v0.34.2-mocha. Inline notes are the gaps in this diff.
Three pages this PR does not change still say a bridge needs an archival consensus node:
app/operate/consensus-validators/consensus-node/page.mdx(min-retain-blocks = 0)app/operate/networks/mocha-testnet/page.mdx(full-history core RPC, and the public endpoint)app/operate/maintenance/troubleshooting/page.mdx(<archival-consensus-endpoint>)
| > **Warning:** Choose archival mode before the node's first start and include | ||
| > `--archival` every time it starts, including in a systemd service or another | ||
| > process manager. A store previously started in pruned mode cannot switch to | ||
| > archival mode; initialise a fresh store to sync from genesis. |
There was a problem hiding this comment.
Omitting --archival on a later start does not error. It converts the node to pruned and deletes historical blocks, not only the Q4 quadrant (convertToPruned in nodebuilder/pruner/module.go). Worth stating next to the pruned-to-archival warning.
There was a problem hiding this comment.
Addressed in a976cf5. The warning now states that omitting --archival permits startup, converts the store to pruned mode, and deletes historical headers and original data outside the storage window. It also states that adding the flag again cannot reverse the conversion.
| Both modes can use a non-archival consensus endpoint, provided it retains the | ||
| recent blocks needed for syncing. During header sync, the bridge node routes | ||
| recent ranges to the consensus endpoint and older ranges to the peer-to-peer | ||
| network. Historical data is fetched separately from DA peers. This routing is | ||
| automatic, but it does not replace missing recent blocks at the consensus | ||
| endpoint or guarantee that peers retain the full history. |
There was a problem hiding this comment.
Name the window. In v0.33.2, "recent" is StorageWindow (169h). The listener still needs those blocks from consensus. Header fetches can fall back to peers when core lacks a height; share data is filled in by the DASer.
There was a problem hiding this comment.
Addressed in a976cf5. Named the 169h storage window, backed by a shared constant, and separated live consensus-block fetching from header fallback and DASer share retrieval. Also corrected the three related pages from your review summary: consensus setup no longer requires full block history, Mocha explains the retention/peer requirements without claiming the public endpoint satisfies them, and troubleshooting uses <consensus_endpoint> with archival startup guidance.
| and for specific use cases that require reliable access to full block | ||
| history, such as: |
There was a problem hiding this comment.
This sentence still says the list is for full block history, after the bridge-node bullet was removed. The remaining items do not need an archive consensus node.
There was a problem hiding this comment.
Addressed in a976cf5. Production-provider guidance now describes service reliability and SLAs without requiring full block history. Applied the same correction to Mocha.
| Bridge nodes run in pruned mode by default. Both pruned and archival bridge | ||
| nodes can use a non-archival consensus endpoint that retains the recent blocks | ||
| needed for syncing. Older header ranges and historical data are retrieved from | ||
| DA peers that still hold them; full historical availability is not guaranteed. | ||
|
|
||
| Check the [production endpoints](#production-rpc-endpoints) or the [community dashboard](https://celestia-tools.brightlystake.com/) to identify which endpoints are archive nodes with full historical data. | ||
|
|
||
| Alternatively, you can run your own consensus node with no pruning for your bridge node. | ||
| To retain full history locally, start the bridge node with `--archival` and | ||
| provision the [archival hardware requirements](/operate/getting-started/hardware-requirements#archival-data-availability-nodes). |
There was a problem hiding this comment.
Same 169h window as the bridge page. Older header ranges come from the header peer exchange; historical share data comes from DA peers.
The section below still says archival DA nodes store the chain without pruning, which conflicts with Q4 trimming.
There was a problem hiding this comment.
Addressed in a976cf5. Mainnet Beta now names the 169h storage window, distinguishes the header peer exchange from DASer share retrieval, and explains that archival nodes retain original data while trimming redundant erasure-coded data.
| If you provide `GENESIS_HASH`, make sure it matches the network genesis. Bridge | ||
| nodes prune by default. To run the bridge node without pruning, pass | ||
| `--archival` every time you start it. |
There was a problem hiding this comment.
Archival startup calls GenesisFor. If CELESTIA_CUSTOM has no genesis field, that lookup fails and the bridge does not start. A wrong hash is used as SyncFromHash. Separate that from the pruning note.
There was a problem hiding this comment.
Addressed in a976cf5. Separated custom-network genesis configuration from pruning. The page now distinguishes an omitted genesis field (archival startup fails), a non-empty hash (used as SyncFromHash and must identify genesis), and an explicitly empty field (syncs from height 1). Checked the parser and archival syncer constructor in both pinned releases.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
There was a problem hiding this comment.
Devin Review found 1 potential issue.
1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)
This branch has not been deployed
2 participants
Bridge-node setup currently tells operators that an archival consensus endpoint is required. Current celestia-node releases prune bridge nodes by default and can retrieve older header ranges and data from DA peers. This change documents those behaviours and explains when to use
--archival.--archivalon a later start converts the store to pruned mode and deletes historical data. Switching back requires a fresh store.Behaviour checked against the pinned Mainnet Beta v0.33.2 and Mocha v0.34.2-mocha sources: header defaults, archival startup, header routing, header fallback, mode conversion, archival retention, and custom-network parsing.
Validation at
a976cf53:yarn lint: passes with one existing unused eslint-disable warning inNodeAPIContent.tsx.yarn build: passes, including Markdown generation and search indexing.yarn check-links -- --all: all 178 internal links pass; seven existing audit-PDF URLs return 404 in unchangedapp/learn/audits/page.mdx.