Skip to content

docs: prepare Mocha-5 network restart - #2546

Draft
jcstein wants to merge 6 commits into
mainfrom
jcstein/update-docs-mocha-5
Draft

docs: prepare Mocha-5 network restart#2546
jcstein wants to merge 6 commits into
mainfrom
jcstein/update-docs-mocha-5

Conversation

@jcstein

@jcstein jcstein commented Jul 28, 2026

Copy link
Copy Markdown
Member

Summary

  • switch the shared Mocha chain ID from mocha-4 to mocha-5
  • make the Go blob-submission examples resolve the shared chain-ID constant instead of hard-coding it
  • document the Mocha-5 restart, snapshot cutoff, and state that does not carry over
  • give existing consensus operators a separate-home migration path, so a stale priv_validator_state.json does not block signing on a chain that restarts at height 1
  • state that retaining mocha-4 data is not an operator responsibility, that an exported copy of the final state will be available for one month after the restart, and that anyone depending on mocha-4 transaction history should export it before the restart
  • remove the provider-specific AlphaB mocha-4 staking link

Closes PROTOCO-2189.

Why

Mocha-5 is a new height-1 chain rather than an in-place upgrade. Only account balances at the selected mocha-4 snapshot height carry over; later activity does not. Account sequences reset, staking positions become liquid balances, and the validator set, governance proposals, IBC channels, Hyperlane state, community pool, and other chain state do not carry over. The docs need to distinguish that restart from a routine network upgrade and stop emitting mocha-4 in current setup commands.

Impact

Once the launch artifacts are ready, Mocha node initialization, genesis/peer lookup, node-store paths, IBC configuration, and code examples will resolve to mocha-5. Existing consensus operators are instructed to initialize mocha-5 under $HOME/.celestia-app-mocha-5 and avoid copying old chain data or validator state into the new home. Keeping the mocha-4 home around is framed as an optional cutover fallback, not as an archival duty. An exported copy of the final mocha-4 state will be available for one month after the restart; its download location still needs to be added.

Draft blockers

This PR is intentionally not ready to merge. Before cutover:

  • publish and verify the final mocha-4 state export URL; the export will remain available for one month after the restart
  • publish and verify celestiaorg/networks/mocha-5 genesis, seeds, and peers
  • replace the mocha-4 genesis hash and validator count on the network page
  • update the Mocha celestia-app and celestia-node release metadata
  • verify production/community RPC, REST, gRPC, and DA endpoints
  • verify migrated faucet, explorer, staking, and analytics links
  • confirm the final initial-validator/gentx key-restoration instructions and launch timing
  • rerun external link and endpoint checks when the new services are live

Related work is tracked in PROTOCO-2187 (services and infrastructure), PROTOCO-2188 (celestia-app), PROTOCO-2190 (celestia-node), and DEVX-99 (validator outreach/gentx coordination).

Validation

  • npm run lint — passes with one pre-existing unrelated warning in NodeAPIContent.tsx
  • npm run build — passes, including static export, LLM-ready Markdown generation, and Pagefind indexing
  • generated Go documentation resolves p2p.Network("mocha-5")
  • generated Mocha Markdown includes the complete separate-home command sequence
  • git diff --check — passes
  • CI link checking runs successfully but reports the same three pre-existing broken external links currently reported on main, all in app/build/blobstream/integrate-contracts/page.mdx; this PR does not change those links or the link checker

@github-actions

Copy link
Copy Markdown
Contributor

🚀 Preview Deployment

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

@jcstein
jcstein requested review from mindstyle85 and rach-id July 28, 2026 18:52
@mindstyle85

Copy link
Copy Markdown
Collaborator

generally this looks good to me, only thing im unsure of is this? "give existing consensus operators a separate-home migration path that preserves mocha-4 data during cutover"

so basically what we need here is to make sure all docs are updated, explorers will be since all explorer operators are also validators (except Celenium maybe?).. and as for the snapshot/data preservation, all that is needed is an exported file that lives somewhere for a while imo

jcstein and others added 2 commits July 28, 2026 14:20
Review feedback: preserving mocha-4 history is a central
responsibility, not something each consensus operator should carry.
State that the Foundation will publish and host an exported copy of the
final mocha-4 state, and that operator-side retention is optional.

Keep the separate-home instructions, but justify them by their actual
reason -- a reused home carries a mocha-4 priv_validator_state.json
whose last-signed height blocks signing on a chain that restarts at
height 1 -- rather than framing them as data preservation.

The hosting location and retirement date are still TBD and are marked
with a placeholder callout plus a draft blocker on the PR.

Co-Authored-By: Claude <noreply@anthropic.com>
Drop the claim that the Foundation will publish and host an export of
final mocha-4 state; that has not been decided. Say only that operators
are not expected to retain mocha-4 data, that community-hosted archives
or endpoints may exist without guarantee, and that anyone depending on
mocha-4 history should export it before the restart.

Co-Authored-By: Claude <noreply@anthropic.com>

@rach-id rach-id left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

LGTM 👍

@jcstein jcstein self-assigned this Jul 30, 2026
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.

3 participants