Update readme #564

grunch · 2026-01-15T21:56:50Z

Summary by CodeRabbit

Documentation
- Extensive README expansion with new sections covering Quick Start, Key Features, deployment options (Native, Docker, StartOS, Regtest), configuration guides, architecture overview, installation instructions, development workflows, client information, and operator support resources. Added visual diagrams and configuration examples for improved clarity.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2026-01-15T21:56:59Z

Walkthrough

Comprehensive overhaul of README.md with extensive new sections covering features, deployment options, configuration, architecture, installation guides, development workflows, and operator guidance. Documentation expanded from concise overview to multi-section reference material with code examples and visual diagrams.

Changes

Cohort / File(s)	Summary
Documentation Restructuring `README.md`	Replaced concise overview with comprehensive multi-section documentation. Added Quick Links, Key Features, How It Works (Order & Dispute Flow), Architecture, Installation (prerequisites, native, Docker, StartOS, Regtest), Configuration templates (Lightning, Nostr, Business Logic, RPC, Database), Clients reference, Development Workflow, Testing, Communication Channels, and Operator guidance. Added development fee distribution diagrams, Mermaid/Nostr flow visualizations, and code snippets. Net change: +1014/-65 lines.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

MostroP2P/mostro#401: Overlapping README.md documentation updates with Docker-compose and link modifications that represent a subset of this PR's broader documentation restructuring effort.

Poem

🐰 A warren of words, now neat and so clear,
From trading to ops, we've laid it out here!
With diagrams dancing and guides galore,
The docs leap forward—much more, much more!
Mostro's tale told, from whisker to ear,
Let all who come seeking find treasure so dear! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Update readme' is generic and vague, failing to convey the substantial scope of changes including new sections, deployment options, configuration guidance, and operator documentation.	Consider a more descriptive title that captures the major additions, such as 'Add comprehensive documentation for deployment, configuration, and operator guidance' or 'Expand README with architecture, installation, and operator guides'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

🧹 Recent nitpick comments

README.md (4)
709-788: Comprehensive client documentation!

The clients section effectively covers both official clients and guidance for building custom clients. The Rust code example (lines 759-779) provides a clear starting point for client developers.

However, there are several bare URLs that should be converted to proper markdown links for better accessibility:

Lines 716, 736: Repository URLs should use markdown link format
Lines 782-783: Documentation URLs should be proper markdown links
📝 Suggested improvements for markdown links
 #### mostro-cli (Command-Line Interface)
-**Repository**: https://github.com/MostroP2P/mostro-cli
+**Repository**: [MostroP2P/mostro-cli](https://github.com/MostroP2P/mostro-cli)
 **Status**: Production-ready

 #### mostro-web (Web Interface)
-**Repository**: https://github.com/MostroP2P/mostro-web
+**Repository**: [MostroP2P/mostro-web](https://github.com/MostroP2P/mostro-web)
 **Status**: In development

 **Resources**:
-- Protocol specification: https://mostro.network/protocol/
-- mostro-core docs: https://docs.rs/mostro-core/
+- [Protocol specification](https://mostro.network/protocol/)
+- [mostro-core docs](https://docs.rs/mostro-core/)
 - Example implementations: See mostro-cli source code
843-875: Add language specifier to code block.

The project structure tree would benefit from a language specifier for better syntax highlighting and accessibility.
📝 Suggested improvement
 ### Project Structure

-```
+```text
 mostro/
 ├── src/
 │   ├── main.rs              # Entry point, initialization
911-924: Convert bare URLs to proper markdown links.

Several URLs in the "Finding Issues to Work On" and "Communication Channels" sections should be formatted as proper markdown links for better accessibility.
📝 Suggested improvements
 ### Finding Issues to Work On

-- **Good first issues**: https://github.com/MostroP2P/mostro/labels/good%20first%20issue
-- **Rewards board**: https://github.com/orgs/MostroP2P/projects/2/views/1 (bounties available)
-- **Help wanted**: https://github.com/MostroP2P/mostro/labels/help%20wanted
+- **Good first issues**: [GitHub label](https://github.com/MostroP2P/mostro/labels/good%20first%20issue)
+- **Rewards board**: [GitHub Projects](https://github.com/orgs/MostroP2P/projects/2/views/1) (bounties available)
+- **Help wanted**: [GitHub label](https://github.com/MostroP2P/mostro/labels/help%20wanted)
1037-1067: Comprehensive documentation index!

The documentation section effectively organizes all available resources by category. This makes it easy for users to find the right documentation for their needs.

However, several bare URLs should be converted to proper markdown links:

Lines 1040-1042: Official documentation URLs
Line 1060: mostro-core docs URL
Lines 1064-1066: External resource URLs
📝 Suggested improvements for markdown links
 ### Official Documentation
-- **Protocol Specification**: https://mostro.network/protocol/ - Complete Nostr protocol specification
-- **FAQ (English)**: https://mostro.network/docs-english/ - Frequently asked questions
-- **FAQ (Español)**: https://mostro.network/docs-spanish/ - Preguntas frecuentes
+- **[Protocol Specification](https://mostro.network/protocol/)** - Complete Nostr protocol specification
+- **[FAQ (English)](https://mostro.network/docs-english/)** - Frequently asked questions
+- **[FAQ (Español)](https://mostro.network/docs-spanish/)** - Preguntas frecuentes

 ### API Documentation
 - **Rust Docs**: Run `cargo doc --open` to generate and browse API documentation
-- **mostro-core**: https://docs.rs/mostro-core/ - Protocol library for building clients
+- **[mostro-core](https://docs.rs/mostro-core/)** - Protocol library for building clients
 - **Protocol Buffers**: [proto/admin.proto](proto/admin.proto) - RPC service definitions

 ### External Resources
-- **Mostro Network**: https://mostro.network/ - Official website
-- **GitHub Organization**: https://github.com/MostroP2P - All Mostro projects
-- **Rewards Board**: https://github.com/orgs/MostroP2P/projects/2/views/1 - Bounties and incentives
+- **[Mostro Network](https://mostro.network/)** - Official website
+- **[GitHub Organization](https://github.com/MostroP2P)** - All Mostro projects
+- **[Rewards Board](https://github.com/orgs/MostroP2P/projects/2/views/1)** - Bounties and incentives

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 11cb35f and 3f61042.

📒 Files selected for processing (1)

README.md

🧰 Additional context used

🧠 Learnings (3)

📚 Learning: 2025-02-28T15:32:19.572Z

Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 0
File: :0-0
Timestamp: 2025-02-28T15:32:19.572Z
Learning: In the Mostro project, docstrings should be added for documentation purposes, but doctests (examples in documentation that run as tests) aren't applicable since it's a binary application rather than a library.

Applied to files:

README.md

📚 Learning: 2025-08-21T10:00:43.096Z

Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 513
File: src/config/types.rs:96-97
Timestamp: 2025-08-21T10:00:43.096Z
Learning: In the Mostro project, all configuration parameters present in settings.tpl.toml are required for the mostro daemon to start. The daemon will not start if any parameter is missing from the settings.toml file. This means serde defaults are not relevant for backward compatibility since users must explicitly configure all values during upgrades.

Applied to files:

README.md

📚 Learning: 2025-12-17T13:04:13.036Z

Learnt from: grunch
Repo: MostroP2P/mostro PR: 554
File: docs/DEV_FEE_TECHNICAL_SPEC.md:1-434
Timestamp: 2025-12-17T13:04:13.036Z
Learning: In the Mostro development fee implementation, the Lightning address `mostro_p2psats.mobi` in src/config/constants.rs is temporary for testing purposes. The production address will be `developmentmostro.network` as documented in docs/DEV_FEE_TECHNICAL_SPEC.md. This intentional mismatch is planned to be resolved before production deployment.

Applied to files:

README.md

🪛 LanguageTool

README.md

[grammar] ~338-~338: Ensure spelling is correct
Context: ... Native Build Dependencies: Ubuntu/Debian: bash sudo apt update sudo apt install -y cmake build-essential libsqlite3-dev pkg-config protobuf-compiler macOS: ```bash brew update brew install ...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

[uncategorized] ~941-~941: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...ion Testing**: Use mostro-regtest for full stack testing ```bash git clone https://githu...

(EN_COMPOUND_ADJECTIVE_INTERNAL)

[grammar] ~964-~964: Ensure spelling is correct
Context: ...RIBUTING.md). --- ## Running Your Own Mostro Mostro's open-source design enables anyo...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

[grammar] ~968-~968: Ensure spelling is correct
Context: ...istant ecosystem. ### Why Run Your Own Mostro? For the Network: - *Decentralization...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)

README.md

716-716: Bare URL used

(MD034, no-bare-urls)

736-736: Bare URL used

(MD034, no-bare-urls)

782-782: Bare URL used

(MD034, no-bare-urls)

783-783: Bare URL used

(MD034, no-bare-urls)

844-844: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

913-913: Bare URL used

(MD034, no-bare-urls)

914-914: Bare URL used

(MD034, no-bare-urls)

915-915: Bare URL used

(MD034, no-bare-urls)

1040-1040: Bare URL used

(MD034, no-bare-urls)

1041-1041: Bare URL used

(MD034, no-bare-urls)

1042-1042: Bare URL used

(MD034, no-bare-urls)

1060-1060: Bare URL used

(MD034, no-bare-urls)

1064-1064: Bare URL used

(MD034, no-bare-urls)

1065-1065: Bare URL used

(MD034, no-bare-urls)

1066-1066: Bare URL used

(MD034, no-bare-urls)

⏰ 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: test

🔇 Additional comments (9)

README.md (9)

1-18: Excellent header and navigation improvements!

The updated badges provide clear version information, and the Quick Links section makes navigation much easier for users. The production-ready tagline accurately reflects the project's maturity.

21-67: Well-structured features and motivation!

The "Why Mostro Exists" narrative effectively communicates the project's purpose and differentiates it from @lnp2pBot. The categorized features section makes it easy for different audiences (users, operators, developers) to understand Mostro's capabilities.

69-234: Outstanding visual documentation!

The Mermaid diagrams provide excellent visual explanations of the order lifecycle, dispute resolution, and development fee flows. The specific examples (100k sats order with fee breakdowns) make the abstract concepts concrete and easy to understand.

235-320: Clear architectural overview!

The architecture diagram effectively communicates the system's modular design and external dependencies. Including specific version numbers for key dependencies (nostr-sdk v0.43, sqlx v0.6) is helpful for developers.

323-461: Comprehensive installation guidance!

The multiple installation options cater to different user personas (production operators, developers, Start9 users). The progression from quick-start commands to production setup with systemd is logical and user-friendly.

464-599: Thorough configuration documentation!

The configuration examples with inline TOML snippets make it easy to understand each parameter's purpose. The configuration tips at the end (lines 592-598) provide practical operational guidance. This section effectively covers all key configuration areas.

603-707: Practical operational guidance!

The usage section provides concrete, copy-paste-ready commands for common operations. The monitoring queries and audit event examples are particularly valuable for operators. This section effectively bridges the gap between installation and day-to-day operations.

964-1034: Excellent operator guidance!

This section provides transparent and realistic expectations for running a Mostro instance. The breakdown of technical prerequisites, operational commitments, and financial considerations helps potential operators make informed decisions. The emphasis on reputation-based accountability is particularly valuable.

1070-1100: Comprehensive and transparent acknowledgments!

The Credits & Acknowledgments section appropriately recognizes the broader ecosystem (contributors, grants, @lnp2pBot, Nostr, Bitcoin/LN) while explaining the sustainability model. The transparency about the development fee system (lines 1090-1095) aligns well with the project's open-source ethos.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

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

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

Update readme

3f61042

grunch merged commit 726c6c0 into main Jan 15, 2026
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update readme #564

Update readme #564

Uh oh!

grunch commented Jan 15, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Jan 15, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Update readme #564

Update readme #564

Uh oh!

Conversation

grunch commented Jan 15, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

grunch commented Jan 15, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jan 15, 2026 •

edited

Loading