Validator docs: Tier 1 onboarding guide and admin-guide polish#2427
Open
rice2000 wants to merge 12 commits into
Open
Validator docs: Tier 1 onboarding guide and admin-guide polish#2427rice2000 wants to merge 12 commits into
rice2000 wants to merge 12 commits into
Conversation
|
Preview is available here: |
- Add Tier 1 Organizations page covering requirements, estimated costs, evaluation criteria, and a step-by-step onboarding path. - Add a "one archive per node" caution to publishing-history-archives.mdx. - Add a Quick-Reference Health Indicators table and a Grafana dashboard table to monitoring.mdx. - Expand hardware requirements detail in prerequisites.mdx. - Add Tier 1 quality rating note to configuring.mdx. - Add a tip in the validators README pointing to the Tier 1 page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Stellarbeat has been sunset; Obsrvr Radar (https://radar.withobsrvr.com/) is its successor for validator monitoring and quorum visualization. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Restructure tier-1-orgs.mdx: move Step-by-Step checklist up to lead the actionable content, drop sections fully covered by the admin guide (history archives, quorum set, SEP-20 declaration, monitoring). - Trim Tier 1 requirements table; drop week-range phase labels. - Note in configuring.mdx that HIGH quality requires a history archive. - Fix `#validators` -> `#validator` in Discord channel references across ledgers.mdx, maintenance.mdx, tier-1-orgs.mdx. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rice2000
force-pushed
the
validator-docs-improvements
branch
from
3774b92 to
dc28042
Compare
|
Preview is available here: |
Replace the speculative line-item table with three setup archetypes (Lean, Standard, Hyperscaler) reflecting actual choices made by current Tier 1 operators. Add commentary on the dominant cost driver (history archive bandwidth) and the variance between hyperscaler and bare-metal providers. Date-stamp the section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
Replace the stale storage breakdown with current figures: buckets directory as the primary store under BucketListDB (default since stellar-core 21.0), SQL database reduced to a few GB for metadata. Add a "Why local disk stays bounded" section explaining state archival, off-validator history archives, and why CATCHUP_COMPLETE is rarely the right choice. Drop the obsolete "Plan for growth" tip and 200 GB recommendation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Prettier escaped the asterisks in the {/* */} JSX-style comment block,
breaking MDX parsing. Switch to a regular HTML comment (<!-- -->),
which matches the existing convention elsewhere in the file and
survives the formatter.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Something went wrong with PR preview build please check |
|
Preview is available here: |
- Add an "In short" admonition right after the intro paragraphs so an AI or skimming human can answer "what does it take?" without reading the full page. Includes inline links to Obsrvr Radar, SEP-20, SEP-1. - Reorder for what / why / cost / bar / how-to-start flow: move "Why Three Validators" up to follow the requirements table; move "What SDF and Existing Tier 1 Organizations Evaluate" up to precede the Step-by-Step checklist. - Add a one-line teaser at the top of "Step-by-Step Path" pointing to the evaluation framework, so the checklist isn't read as necessary-and-sufficient. - Drop the "Block storage / 200 GB NVMe" bullet from "Other Line Items" — vestigial and inconsistent with the reworked storage framing in prerequisites.mdx. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
Drop the "+" from the IOPS spec — the original verification was at 10,000 IOPS, not "10,000 or more." Restore the operational guidance that PostgreSQL co-located on the same machine performs well, which was lost when the standalone April-2024 paragraph was replaced. Keep the vendor-neutral "8 vCPUs" phrasing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- running-node.mdx: rewrite the catchup paragraph so it stops recommending CATCHUP_COMPLETE=true for new Full Validators. The reworked Storage section in prerequisites.mdx says this is almost never the right choice and points to stellar-archivist mirror as the standard backfill path; the old running-node text directly contradicted that guidance. - prerequisites.mdx: anchor the "30-day retention window" footnote to the Disk column in the hardware table. The asterisk was orphaned after a recent column rework. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
1 similar comment
|
Preview is available here: |
- Merge "Coordinate With Other Validators" + "Get in Touch" into "Working with the Tier 1 Community". Operator coordination bullets stay; the Discord callout and prospective-candidate outreach merge into one closing paragraph. - Merge "Stay Informed" + "Key Resources" into a single "Resources" table. Drops the Obsrvr Radar and Stellar Dev Discord duplicates that previously appeared in both tables, and the SDF Blog entry. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
State archival is a Soroban-only mechanism — only contract data and contract code entries carry a rent balance and get evicted. Classic ledger entries (accounts, trustlines, offers, claimable balances, liquidity pool shares, data entries) don't expire. The previous text implied the rent model applied universally, which is wrong. Split the explanation into two paragraphs: one for Soroban entries (bounded by archival), one for classic entries (bounded by reserve requirements as anti-spam friction). Keep the practical bottom line that the working set still lands in the 30-60 GB range. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Preview is available here: |
1 similar comment
|
Preview is available here: |
Contributor
There was a problem hiding this comment.
Pull request overview
Expands the validator documentation to make “Tier 1” onboarding (running three geographically dispersed Full Validators and joining the Tier 1 quorum) more discoverable and actionable, while also polishing key Admin Guide sections around monitoring, storage requirements, history archive publishing, and catchup guidance.
Changes:
- Adds a comprehensive Tier 1 onboarding page with requirements, rationale, cost estimates, evaluation criteria, and a phased checklist.
- Updates Admin Guide guidance for catchup behavior, storage sizing (BucketListDB + state archival context), monitoring quick-reference indicators, and history archive publishing constraints.
- Fixes/standardizes validator operator coordination channel references (
#validator) and adds cross-links from validator intro docs.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/validators/tier-1-orgs.mdx | New/expanded Tier 1 onboarding guide: requirements, costs, evaluation rubric, and phased checklist. |
| docs/validators/README.mdx | Adds a Tier 1 tip that routes readers to the new Tier 1 guide. |
| docs/validators/admin-guide/running-node.mdx | Updates catchup guidance to discourage CATCHUP_COMPLETE=true for new validators; recommends stellar-archivist mirror for backfill. |
| docs/validators/admin-guide/publishing-history-archives.mdx | Adds explicit caution that each node must publish to its own archive. |
| docs/validators/admin-guide/prerequisites.mdx | Refreshes hardware/storage guidance for BucketListDB defaults and bounded local disk rationale; adds Tier 1 planning note. |
| docs/validators/admin-guide/monitoring.mdx | Adds a quick-reference health indicator table and converts Grafana dashboard recommendations into a table. |
| docs/validators/admin-guide/maintenance.mdx | Updates Discord channel reference to #validator. |
| docs/validators/admin-guide/configuring.mdx | Fixes typo and clarifies Tier 1 “HIGH” quality expectations + history archive requirement. |
| docs/learn/fundamentals/stellar-data-structures/ledgers.mdx | Updates Discord channel reference to #validator for upgrade coordination. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
anupsdf
reviewed
May 8, 2026
Contributor
anupsdf
left a comment
anupsdf
left a comment
There was a problem hiding this comment.
Thanks for improving the docs.
|
|
||
| A common misconception is that validators need to provision storage proportional to network history. They do not. | ||
|
|
||
| **Soroban (smart contract) state is bounded by [state archival](https://developers.stellar.org/docs/learn/encyclopedia/storage/state-archival).** Contract data and contract code entries carry a rent balance; when the balance reaches zero, the entry is archived and removed from live state. Validators store the live Soroban state plus a small "Hot Archive" of recently archived entries; when the Hot Archive fills, it is published to the History Archive, the validator retains only the Merkle root of the published tree, and the archived entries themselves are deleted from the validator. |
Contributor
There was a problem hiding this comment.
when the Hot Archive fills, it is published to the History Archive, the validator retains only the Merkle root of the published tree, and the archived entries themselves are deleted from the validator.
We haven't implemented the part 2 of State Archival where hot archive entries get deleted.
So for now the best thing to talk about would be that (you can rephrase it): Temporary Contract Data entries get deleted from Live state after they expire which keeps the state bounded. Temp entries, being cheaper than persistent entries, dominate the total Contract data entries so when they get deleted, a lot of state is freed up.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands the validator docs to make Tier 1 onboarding more discoverable and actionable, and adds quick-reference content to the admin guide.
tier-1-orgs.mdx): an "In short" executive summary up top, requirements table, why-three-validators rationale, estimated costs, evaluation framework, and a step-by-step path with a checklist. Section ordering follows what / why / cost / bar / how-to-start.monitoring.mdx.publishing-history-archives.mdx.configuring.mdxthatHIGHquality requires a history archive.prerequisites.mdxto reflect BucketListDB (default since stellar-core 21.0) and state archival, with a "Why local disk stays bounded" explanation. Refines the Hardware Requirements table (vendor-neutral CPU phrasing, IOPS moved into the table, restored PostgreSQL co-location guidance). Adds Tier 1 hardware-planning context.running-node.mdxto align with the new prerequisites guidance: do not useCATCHUP_COMPLETE=truefor new Full Validators; sync against current state and usestellar-archivist mirrorto backfill if you want a complete archive.#validators→#validatorStellar Dev Discord channel references.The Estimated Costs section in the Tier 1 page is grounded in figures shared by current Tier 1 operators (May 2026): three setup archetypes (Lean, Standard, Hyperscaler) with provider examples, plus commentary on the dominant cost driver (history archive bandwidth) and the variance between hyperscaler and bare-metal providers.
Open questions for review
Test plan