[jcstein]

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.

• Add pruned/archival start examples and warn that omitting --archival on a later start converts the store to pruned mode and deletes historical data. Switching back requires a fresh store.
• Name the 169-hour storage window through a shared constant and distinguish live consensus-block fetching, header peer fallback, and DASer share retrieval.
• Document header sync defaults and explain why header retention settings alone do not make a node archival.
• Explain archival trimming and custom-network genesis-field requirements, and add the archival flag to the existing local-devnet example.
• Align Mainnet Beta, Mocha, consensus setup, and troubleshooting guidance on pruned consensus endpoints. Historical availability still depends on peers retaining the data; no public endpoint's retention is assumed.
• Preserve existing hardware figures and the removal of Arabica.

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 in NodeAPIContent.tsx.
• yarn build: passes, including Markdown generation and search indexing.
• Inspected generated HTML and Markdown for all seven pages changed in the follow-up; the archival warning and resolved window values survive export.
• yarn check-links -- --all: all 178 internal links pass; seven existing audit-PDF URLs return 404 in unchanged app/learn/audits/page.mdx.
• No full historical sync or end-to-end Docker devnet run; historical peer completeness is not assumed.

[gemini-code-assist]

Summary of Changes

Hello @jcstein, I'm Gemini Code Assist¹! 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

• Default Pruning for Bridge Nodes: Bridge nodes will now default to pruning mode, significantly reducing storage requirements by only storing recent blocks within the availability window. This is a breaking change for existing operators.
• New Archival Mode and Flag: A new --archival flag has been introduced for bridge nodes that need to store all historical data from genesis. This mode is necessary for applications requiring full historical access or for serving data outside the availability window.
• Migration Guide for Existing Operators: Comprehensive instructions are provided for existing bridge node operators to either adapt to the new default pruning mode or migrate to archival mode using the --archival flag.
• Private Network Genesis Hash Requirements: Documentation clarifies that bridge nodes on private networks, when running in pruned mode, must explicitly provide a genesis hash configuration or use the --archival flag to start successfully.
• Routing Exchange Optimization: The documentation includes details on an automatic routing exchange optimization for bridge nodes, which enhances header synchronization without requiring any configuration.

🧠 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

• app/operate/data-availability/bridge-node/page.mdx
  • Added a prominent warning callout about bridge nodes defaulting to pruning mode and the requirement for the --archival flag.
  • Introduced new sections detailing 'Pruning vs archival modes' and 'Choosing between modes', explaining their functionalities and use cases.
  • Included an informational callout about the 'Routing Exchange Optimization' for header synchronization.
  • Updated celestia bridge init and celestia bridge start command examples to include both default (pruned) and --archival options across different networks.
  • Added a new 'Migration guide for existing bridge nodes' section, providing step-by-step instructions for adapting to the pruning changes, including specific advice for private networks.
• app/operate/data-availability/config-reference/page.mdx
  • Added a new subsection 'Pruning Configuration (Bridge Nodes)' detailing PruningWindow, SyncFromHeight, SyncFromHash, and the --archival flag.
  • Provided example TOML configuration for pruned bridge nodes and bash commands for archival bridge nodes.
• app/operate/data-availability/custom-networks/page.mdx
  • Added an important note for bridge nodes on private networks, emphasizing the need for --archival or genesis hash configuration.
  • Updated the celestia <node-type> start command examples to differentiate between pruned (default) and archival bridge nodes.
  • Introduced a new 'Bridge node specific configuration' section outlining three options for private network operators: archival mode, genesis hash configuration, or syncing from a specific height/hash.
• app/operate/getting-started/hardware-requirements/page.mdx
  • Renamed 'Non-archival data availability nodes' to 'Non-archival data availability nodes (pruned)'.
  • Added a note indicating that bridge nodes now default to pruning mode and that the listed specifications are for pruned nodes.
  • Updated the 'Bridge node' entry in the archival table to 'Bridge node (--archival flag)'.
  • Added an important note clarifying that the --archival flag is required to run an archival bridge node.
• app/operate/networks/arabica-devnet/page.mdx
  • Added a note to the 'Running Bridge Nodes' bullet point, indicating that bridge nodes will default to pruning mode in an upcoming release.
• app/operate/networks/local-devnet/page.mdx
  • Added a note above the docker-compose.yml example explaining that the bridge node uses --archival mode to simplify private network setup.
  • Added the --archival flag to the celestia-bridge service in the docker-compose.yml example.
• app/operate/networks/mainnet-beta/page.mdx
  • Added a note to the 'Running Bridge Nodes' bullet point, indicating the upcoming default pruning mode and the use of --archival for full history.
  • Introduced a warning callout in the 'Bridge node requirements' section about the default pruning change.
  • Expanded the 'Bridge node requirements' section to clearly distinguish between requirements for archival bridge nodes (using --archival) and pruned bridge nodes (default).
• app/operate/networks/mocha-testnet/page.mdx
  • Added a note to the 'Bridge node' bullet point, indicating that bridge nodes will default to pruning mode in an upcoming release.

Activity

• The pull request is currently a Work In Progress (WIP), as indicated by the title and description.
• There are several placeholder [TODO: Add version from PR #4768] entries that need to be updated once the relevant celestia-node release version is known.
• The author has provided a detailed 'TODO Before Merging' list, outlining remaining tasks such as confirming release versions, replacing placeholders, updating PR references, testing command examples, and verifying genesis hash behavior.
• The pull request includes a review checklist, with most items marked as complete, but version number addition is pending the release.
• The author has requested a review from @vgonkivs once the version is finalized.

Using Gemini Code Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

🚀 Preview Deployment

Your preview is ready: https://celestiaorg.github.io/docs-preview/pr-2402/

[gbarros]

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>)

[devin-ai-integration]

Devin Review found 1 potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)