Add V31 docs

[JohnnyWyles]

What is the purpose of the change

Add upgrade guide for v31
Pending Height, Proposal & Binaries

Testing and Verifying

This change is a trivial rework / code cleanup without any test coverage.

Documentation and Release Note

• Does this pull request introduce a new feature or user-facing behavior changes?
• Changelog entry added to Unreleased section of CHANGELOG.md?

Where is the change documented?

• Specification (x/{module}/README.md)
• Osmosis documentation site
• Code comments?
• N/A

[coderabbitai]

Walkthrough

New comprehensive upgrade guide for Osmosis mainnet transitioning from v30 to v31. Covers hardware requirements, Cosmovisor configuration, automatic and manual upgrade procedures, with explicit command sequences and TODO placeholders for upgrade height and proposal links. Static instructional documentation with no code or API changes.

Changes

Cohort / File(s)	Change Summary
Osmosis v31 Mainnet Upgrade Guide networks/osmosis-1/upgrades/v31/mainnet/guide.md	New comprehensive upgrade documentation covering hardware requirements (64GB RAM, 32GB swap), Cosmovisor setup and configuration, automatic upgrade procedures, manual upgrade fallback steps, and additional resources; includes TODO placeholders for upgrade block height and proposal link

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Review should verify accuracy of all command sequences, clarity of step-by-step instructions, completeness of upgrade procedures (both automatic and manual paths), appropriateness of hardware recommendations, and presence of TODO items requiring completion before publication.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Add V31 docs" directly relates to the main change, which is the addition of a comprehensive Mainnet Upgrade Guide document for Osmosis v31. The title is concise and clear, allowing a teammate scanning commit history to quickly understand that this PR introduces v31 documentation. While the title is generic in not specifying the exact type of documentation (upgrade guide), it remains sufficiently specific to convey the primary change without being vague or misleading.
Description Check	✅ Passed	The pull request description follows the required template structure with all core sections completed. The purpose of the change is clearly stated as "Add upgrade guide for v31" with additional context about pending items. The testing verification section appropriately selects the trivial rework option, and the documentation and release notes section is properly marked as N/A. The absence of a "Closes" line is acceptable per the template's guidance that this can be removed if the PR doesn't close an issue. All required information is present and the description adheres to the template structure.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch johnny/31docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (5)

networks/osmosis-1/upgrades/v31/mainnet/guide.md (5)

53-53: Consider using a newer Cosmovisor version.

v1.0.0 is an older version; latest recommended versions are v1.4+. Pinning to v1.0.0 may miss important bug fixes and security updates. Consider using @latest or documenting why this specific version is required for Osmosis v31.

Please verify with the Osmosis team whether v1.0.0 is intentionally required for v31 compatibility or if a newer version can be used.

---

73-73: Add context for UNSAFE_SKIP_BACKUP=true.

This flag disables safety backups before upgrades. Add a brief explanation of why it's set to true and note the risk, or consider setting it to false with guidance on backup procedures.

---

77-91: Clarify repository path expectations.

The instructions assume the Osmosis repository is cloned at $HOME/osmosis. If this is not the standard setup or if validators may have it elsewhere, consider adding a note to customize the path or verify the repository location.

---

102-107: Note inconsistency with Cosmovisor build process.

The Cosmovisor section uses make build followed by manual binary copy, while manual upgrade uses make install. Both are valid but document why the approaches differ, or standardize them for clarity.

---

94-109: Add recommendation to test the upgrade procedure first.

Best practice for mainnet validators: test the upgrade process on testnet or staging environment before performing on live infrastructure. Consider adding a note recommending this.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 58ee81d and a908485.

⛔ Files ignored due to path filters (1)

• networks/osmosis-1/upgrades/v31/mainnet/v31_binaries.json is excluded by !**/*.json

📒 Files selected for processing (1)

• networks/osmosis-1/upgrades/v31/mainnet/guide.md (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Summary

🔇 Additional comments (2)

networks/osmosis-1/upgrades/v31/mainnet/guide.md (2)

9-34: Clear and practical guidance.

Hardware recommendations and swap configuration are well-documented with helpful external references.

---

113-116: Good resource references.

Clear pointers to official documentation and community support channels.