Skip to content

Conversation

@grunch
Copy link
Member

@grunch grunch commented Dec 12, 2025

Add extensive technical documentation covering architecture, startup sequence, event routing, Lightning operations, RPC interface, and admin capabilities.

New documentation files:

  • docs/README.md: Documentation index with quick links
  • docs/ARCHITECTURE.md: System architecture with module maps and sequence diagrams
  • docs/STARTUP_AND_CONFIG.md: Boot sequence and configuration guide
  • docs/EVENT_ROUTING.md: Event intake pipeline and action routing
  • docs/LIGHTNING_OPS.md: LND integration, invoices, payments, and retry system
  • docs/ORDERS_AND_ACTIONS.md: Order lifecycle and action handlers
  • docs/ADMIN_RPC_AND_DISPUTES.md: Admin operations and dispute resolution

Enhanced existing documentation:

  • docs/RPC.md: Added ValidateDbPassword and GetVersion operations
  • AGENTS.md: Reformatted for improved readability

The documentation includes:

  • Detailed function signatures and entry points
  • Mermaid diagrams for visual architecture representation
  • Code examples for complex workflows
  • Configuration options and global variables
  • Error handling patterns and validation flows
  • GitHub links to source files for easy navigation

Summary by CodeRabbit

  • Documentation

    • Added comprehensive guides for architecture, event routing, Lightning operations, orders/actions workflow, admin RPC & disputes, startup/configuration, and a central docs index.
    • Performed editorial revisions for clarity, formatting, and readability across documentation.
  • New Features

    • Expanded Admin RPC with ValidateDbPassword and GetVersion endpoints, documented accordingly.

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

Add extensive technical documentation covering architecture, startup
sequence, event routing, Lightning operations, RPC interface, and admin
capabilities.

New documentation files:
- docs/README.md: Documentation index with quick links
- docs/ARCHITECTURE.md: System architecture with module maps and sequence diagrams
- docs/STARTUP_AND_CONFIG.md: Boot sequence and configuration guide
- docs/EVENT_ROUTING.md: Event intake pipeline and action routing
- docs/LIGHTNING_OPS.md: LND integration, invoices, payments, and retry system
- docs/ORDERS_AND_ACTIONS.md: Order lifecycle and action handlers
- docs/ADMIN_RPC_AND_DISPUTES.md: Admin operations and dispute resolution

Enhanced existing documentation:
- docs/RPC.md: Added ValidateDbPassword and GetVersion operations
- AGENTS.md: Reformatted for improved readability

The documentation includes:
- Detailed function signatures and entry points
- Mermaid diagrams for visual architecture representation
- Code examples for complex workflows
- Configuration options and global variables
- Error handling patterns and validation flows
- GitHub links to source files for easy navigation
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Dec 12, 2025

Warning

Rate limit exceeded

@grunch has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 7 minutes and 8 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 9e5f645 and 018b0ca.

📒 Files selected for processing (3)
  • docs/README.md (1 hunks)
  • docs/RPC.md (4 hunks)
  • docs/STARTUP_AND_CONFIG.md (1 hunks)

Walkthrough

Adds extensive documentation: architecture, startup/config, event routing, Lightning ops, orders/actions, admin RPC/disputes; editorial edits to AGENTS.md; documents two AdminService RPCs (ValidateDbPassword, GetVersion). No code or exported/public API changes.

Changes

Cohort / File(s) Summary
Editorial updates
AGENTS.md
Reworded and reformatted guideline blocks: project structure, build/dev commands, coding style, testing, commit/PR guidance, and security tips (purely editorial).
Architecture & startup
docs/ARCHITECTURE.md, docs/STARTUP_AND_CONFIG.md
New documentation describing daemon architecture, startup sequence, configuration surfaces, runtime relationships, diagrams, and developer notes.
Event routing
docs/EVENT_ROUTING.md
New document describing the event intake pipeline, dispatch mechanics, trade index semantics, key action flows, error handling, and a sequence diagram.
Lightning operations
docs/LIGHTNING_OPS.md
New documentation of LND connector behavior, hold-invoice flows, outgoing payment lifecycle, validation, retry configuration, node status, and diagrams.
Orders & actions
docs/ORDERS_AND_ACTIONS.md
New document detailing messages/actions, order lifecycle, handler map, typical flow, error variants, and a sequence diagram.
Admin RPC & disputes
docs/ADMIN_RPC_AND_DISPUTES.md
New docs for Admin RPC server configuration and dispute lifecycle, including flow descriptions, handler file references, and an interaction diagram.
Docs index & RPC reference
docs/README.md, docs/RPC.md
Added documentation index and RPC reference; docs/RPC.md documents two AdminService RPCs: ValidateDbPassword and GetVersion (request/response message schemas).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

  • Verify the new RPC signatures in docs/RPC.md match protobuf/service definitions in the repository.
  • Spot-check file path references and handler links in docs/ARCHITECTURE.md, docs/EVENT_ROUTING.md, and docs/ADMIN_RPC_AND_DISPUTES.md.
  • Review diagrams for accurate depiction of runtime interactions (dispatcher, DB, LND, admin components).
  • Confirm no exported/public API or code changes accompany the documented RPCs.

Poem

🐰 I hopped through pages, nibbling lines of lore,
Mapping startup tunnels, and routing paths galore,
Lightning hummed softly below the sod,
RPCs whispered "version" — neat and broad,
Docs sprout leaves — a burrow bright with more.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: add comprehensive technical documentation' accurately summarizes the main change—adding extensive documentation files covering architecture, startup, event routing, Lightning operations, orders, and admin RPC.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 2

🧹 Nitpick comments (3)
docs/ADMIN_RPC_AND_DISPUTES.md (1)

16-19: Admin Cancel section uses parallel structure with earlier sections.

For consistency with the "Dispute Lifecycle" section above (which uses "Action=" notation), consider restructuring the Admin Cancel description to follow the same format, or add a separate "Admin Operations" section header to clarify the distinction. Currently, the transition from the Dispute Lifecycle list to "## Admin Cancel" heading may be slightly abrupt.

docs/ORDERS_AND_ACTIONS.md (1)

23-43: Wrap bare URLs in angle brackets per markdown lint standards.

All GitHub links in the Action → Handler Map table (lines 27–43) are accurate and reference existing files. However, bare URLs trigger MD034 linting warnings. Wrapping them as <https://...> would comply with markdown standards and improve lint compliance.

Apply this to all URL entries:

-| `new-order` | https://github.com/MostroP2P/mostro/blob/main/src/app/order.rs | Validate and create a new order; emit listing event |
+| `new-order` | <https://github.com/MostroP2P/mostro/blob/main/src/app/order.rs> | Validate and create a new order; emit listing event |
docs/README.md (1)

13-15: Tips section is clear and actionable.
Optional: add a short note about SQLx offline prep prerequisites (e.g., having sqlx-cli available and any required env like DATABASE_URL) if contributors commonly hit that snag.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f3d81da and 7e1f2a4.

📒 Files selected for processing (9)
  • AGENTS.md (1 hunks)
  • docs/ADMIN_RPC_AND_DISPUTES.md (1 hunks)
  • docs/ARCHITECTURE.md (1 hunks)
  • docs/EVENT_ROUTING.md (1 hunks)
  • docs/LIGHTNING_OPS.md (1 hunks)
  • docs/ORDERS_AND_ACTIONS.md (1 hunks)
  • docs/README.md (1 hunks)
  • docs/RPC.md (2 hunks)
  • docs/STARTUP_AND_CONFIG.md (1 hunks)
🧰 Additional context used
🧠 Learnings (11)
📓 Common learnings
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.
📚 Learning: 2025-02-21T13:26:17.026Z
Learnt from: grunch
Repo: MostroP2P/mostro PR: 444
File: src/app/take_buy.rs:28-31
Timestamp: 2025-02-21T13:26:17.026Z
Learning: In the Mostro codebase, error messages should be descriptive and specific rather than generic (e.g., prefer `PendingOrderExists` over `InvalidAction`) to help users better understand why their actions were rejected.

Applied to files:

  • docs/ORDERS_AND_ACTIONS.md
📚 Learning: 2025-10-09T14:06:50.067Z
Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 530
File: src/app/order.rs:278-279
Timestamp: 2025-10-09T14:06:50.067Z
Learning: In the Mostro project, tests in files like `src/app/order.rs` may use structural checks to ensure functions like `order_action` do not panic during message construction, rather than validating specific error variants.

Applied to files:

  • docs/ORDERS_AND_ACTIONS.md
  • docs/README.md
  • AGENTS.md
  • docs/ARCHITECTURE.md
📚 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:

  • docs/README.md
  • docs/STARTUP_AND_CONFIG.md
📚 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: Rust doctests (code examples in documentation that are automatically executed as tests) are only available for library code, not for binary applications like Mostro. While docstrings are still valuable for documentation in binary applications, the examples within them won't be automatically tested.

Applied to files:

  • docs/README.md
📚 Learning: 2025-12-10T20:32:01.175Z
Learnt from: CR
Repo: MostroP2P/mostro PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T20:32:01.175Z
Learning: Applies to src/**/*.rs : Runtime code lives under `src/`, with `app/` for order flows, `lightning/` for LND bindings, `rpc/` for the gRPC surface, and `config/` for settings helpers

Applied to files:

  • AGENTS.md
  • docs/STARTUP_AND_CONFIG.md
  • docs/ARCHITECTURE.md
  • docs/LIGHTNING_OPS.md
📚 Learning: 2025-12-10T20:32:01.175Z
Learnt from: CR
Repo: MostroP2P/mostro PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T20:32:01.175Z
Learning: Never commit populated `settings.toml`; use `settings.tpl.toml` as template and copy to `~/.mostro/settings.toml` locally

Applied to files:

  • AGENTS.md
  • docs/STARTUP_AND_CONFIG.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:

  • AGENTS.md
  • docs/STARTUP_AND_CONFIG.md
  • docs/ARCHITECTURE.md
📚 Learning: 2025-05-02T14:21:39.391Z
Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 481
File: src/config/util.rs:48-76
Timestamp: 2025-05-02T14:21:39.391Z
Learning: The `init_default_dir` function in Mostro intentionally exits the process (std::process::exit(0)) after creating a new configuration file so users can edit the configuration before restarting the application.

Applied to files:

  • docs/STARTUP_AND_CONFIG.md
📚 Learning: 2025-07-17T13:51:17.338Z
Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 499
File: src/lightning/invoice.rs:108-114
Timestamp: 2025-07-17T13:51:17.338Z
Learning: In Lightning invoice validation for Mostro buy orders (src/lightning/invoice.rs), zero-amount invoices (amount_sat == 0) should always pass validation even when an expected amount is provided. This is because users can submit invoices at order creation time before knowing the exact satoshi amount they'll receive. The condition `if amount_sat != res && amount_sat != 0` correctly implements this by allowing zero-amount invoices to pass while enforcing exact amount matching for non-zero invoices.

Applied to files:

  • docs/LIGHTNING_OPS.md
📚 Learning: 2025-06-16T15:25:19.185Z
Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 499
File: src/lightning/invoice.rs:130-145
Timestamp: 2025-06-16T15:25:19.185Z
Learning: In Lightning invoice validation (src/lightning/invoice.rs), the expiration window check `if expires_at < latest_date` is correct business logic. It rejects invoices that expire too soon (within the configured window, typically 1 hour) to ensure sufficient time for payment processing. The window represents a minimum acceptable invoice lifetime, not a maximum.

Applied to files:

  • docs/LIGHTNING_OPS.md
🪛 LanguageTool
AGENTS.md

[grammar] ~25-~25: Ensure spelling is correct
Context: ...th ///. - Prefer tracing spans over ad‑hoc logging. - Keep config templates in `se...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)


[grammar] ~28-~28: Ensure spelling is correct
Context: ...ttings.tpl.toml. ## Testing Guidelines - Co‑locate tests in their modules under mod tests...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

docs/ADMIN_RPC_AND_DISPUTES.md

[style] ~16-~16: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...cancels hold or pays out as needed. ## Admin Cancel - File: `src/app/admin_cancel.rs...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🪛 markdownlint-cli2 (0.18.1)
docs/ORDERS_AND_ACTIONS.md

27-27: Bare URL used

(MD034, no-bare-urls)


28-28: Bare URL used

(MD034, no-bare-urls)


29-29: Bare URL used

(MD034, no-bare-urls)


30-30: Bare URL used

(MD034, no-bare-urls)


31-31: Bare URL used

(MD034, no-bare-urls)


32-32: Bare URL used

(MD034, no-bare-urls)


33-33: Bare URL used

(MD034, no-bare-urls)


34-34: Bare URL used

(MD034, no-bare-urls)


35-35: Bare URL used

(MD034, no-bare-urls)


36-36: Bare URL used

(MD034, no-bare-urls)


37-37: Bare URL used

(MD034, no-bare-urls)


38-38: Bare URL used

(MD034, no-bare-urls)


39-39: Bare URL used

(MD034, no-bare-urls)


40-40: Bare URL used

(MD034, no-bare-urls)


41-41: Bare URL used

(MD034, no-bare-urls)


42-42: Bare URL used

(MD034, no-bare-urls)


43-43: 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: build
🔇 Additional comments (15)
AGENTS.md (1)

4-42: LGTM – Excellent editorial refinement.

The formatting improvements enhance clarity without altering substance. The static analysis hints (LanguageTool flags on en-dashes) are false positives; en-dashes in compound adjectives like "ad‑hoc" and "co‑located" are correctly used. Content aligns with project learnings regarding code structure, template usage, and configuration practices.

docs/ARCHITECTURE.md (3)

248-252: Developer pointers are concise and valuable.

References to POW threshold, trade index, SQLx prepare workflow, and settings template practices align with best practices documented in AGENTS.md and learnings from prior PRs. Well-positioned as a quick reference for developers.


1-10: Excellent comprehensive architecture overview.

The module map, startup sequence, and event flow diagrams provide clear visualization of system structure and data dependencies. Cross-references to supplementary documentation (STARTUP_AND_CONFIG.md, EVENT_ROUTING.md, RPC.md) enable easy navigation and reduce redundancy.

Verify that the module map (flowchart, lines 7–37) accurately reflects current directory structure and dependencies by confirming all referenced source files exist: src/main.rs, src/app.rs, src/db.rs, src/config/mod.rs, src/config/constants.rs, src/lightning/mod.rs, src/lightning/invoice.rs, src/rpc/server.rs, src/messages.rs, src/scheduler.rs, and src/util.rs.


66-73: Remove or correct the documentation for development fee constants (lines 66-73).

The file src/config/constants.rs does not exist in the repository, and the referenced constants (MIN_DEV_FEE_PERCENTAGE, MAX_DEV_FEE_PERCENTAGE, DEV_FEE_LIGHTNING_ADDRESS) are not found in the codebase. Either these constants are defined in a different location and the documentation path is incorrect, or they have not been implemented. Verify the actual location of fee-related configuration constants and update the documentation accordingly, or remove this section if these constants have not yet been added.

Likely an incorrect or invalid review comment.

docs/LIGHTNING_OPS.md (3)

1-76: Excellent comprehensive documentation of Lightning operations.

Invoice validation documentation (lines 25–76) is thorough, with clear function signatures, validation step-by-step enumeration, and error cases. The section correctly describes:

  • Amount matching with fee deduction (line 61)
  • Expiration window validation ensuring sufficient payment processing time (line 64)
  • Error variants for invalid/expired/insufficient-window cases

Aligns well with prior learnings regarding invoice validation semantics.


140-146: Zero-amount invoice handling is properly documented.

The documentation correctly explains that zero-amount invoices (invoices without an embedded amount) are supported by populating the amt field in SendPaymentRequest. This aligns with the learning from PR 499 that zero-amount invoices should pass validation even when an expected amount is provided, enabling users to submit invoices before knowing exact satoshi amounts.


77-110: Payment retry system configuration and workflow clearly explained.

The documentation provides good clarity on the scheduler-based retry mechanism, configuration options (payment_attempts, payment_retries_interval), and the retry job workflow. Helps operators understand automatic payment retry behavior and configure it appropriately.

docs/ADMIN_RPC_AND_DISPUTES.md (1)

1-45: Clear documentation of admin RPC and dispute resolution workflow.

The document effectively explains the dispute lifecycle and admin operations. Audit and safety considerations (lines 42–45) appropriately flag the need for authentication, traceability, and log sanitization—important operational safeguards for admin functions.

docs/STARTUP_AND_CONFIG.md (4)

1-27: Comprehensive startup and configuration documentation with excellent pre-boot details.

The overview and pre-boot initialization sections clearly explain the boot sequence and logging setup. The code example for RUST_LOG handling (lines 19–25) aids understanding of debug/release mode detection.


118-149: Global variables and commands sections are concise and accurate.

The global statics documentation (lines 118–144) correctly lists key configuration holders (MOSTRO_CONFIG, NOSTR_CLIENT, DB_POOL, MOSTRO_DB_PASSWORD) and provides access patterns (Settings::get_mostro(), Settings::get_ln(), etc.). The commands section (lines 146–149) includes the important SQLx prepare command reminder.


151-153: Security practices section correctly emphasizes template discipline.

The security section reinforces the critical practice: do not commit populated settings.toml; use settings.tpl.toml as template and place runtime config at ~/.mostro/settings.toml. Aligns with learnings and AGENTS.md guidance.


31-73: Settings and database initialization documentation is accurate and well-documented.

The documentation correctly describes:

  • Directory creation at ~/.mostro/ with template-based configuration copying
  • Database password/encryption handling with Argon2 hashing and interactive prompts via rpassword::read_password()
  • Password storage in global config::MOSTRO_DB_PASSWORD as SecretString
  • Connection pooling via SqlitePool with migrations executed via sqlx::migrate!()
  • File permission restrictions applied immediately after database file creation

Implementation matches all documented behaviors in src/db.rs:480 connect() function and password validation functions.

docs/RPC.md (1)

75-106: New RPC methods correctly documented and implemented.

The two new AdminService RPCs are properly documented and confirmed to be implemented:

  • ValidateDbPassword: Validates encrypted database password. Implementation calls verify_and_set_db_password() and returns success boolean with optional error message (src/rpc/service.rs:306–325).
  • GetVersion: Retrieves daemon version using env!("CARGO_PKG_VERSION") as documented (src/rpc/service.rs:296–305).

Service definition in the protobuf section correctly includes both methods.

docs/EVENT_ROUTING.md (1)

1-45: Well-focused routing documentation with accurate source references.

The document effectively complements ARCHITECTURE.md by detailing event intake and routing mechanics. The sequence diagram clearly illustrates pipeline stages and side effects. All source references are accurate and correctly point to their functions. The Key Actions section provides line numbers for entry points, while architectural-level references (run, handle_message_action, check_trade_index) are appropriately cited without line numbers as they provide directional guidance to the intake pipeline.

docs/ORDERS_AND_ACTIONS.md (1)

1-74: All action names, handler references, and line numbers are verified as accurate.

Verification confirms:

  • All 17 actions in the table are implemented in src/app.rs with correct routing
  • All handler files exist and contain the specified functions at the documented line numbers
  • GitHub links with line anchors (e.g., #L34, #L160, #L319, #L141) correctly point to function definitions
  • Admin actions (admin-cancel, admin-settle, admin-add-solver, admin-take-dispute) are present and properly implemented
  • The rate-user action maps to update_user_reputation_action in src/app/rate_user.rs
  • Documentation accurately reflects the current codebase state

- Fix README.md links: Remove redundant docs/ prefix from all internal
  links to resolve correctly from docs/ directory on GitHub (prevents
  docs/docs/... path resolution)

- Complete settings structure documentation in STARTUP_AND_CONFIG.md:
  - Add missing Database section (url field)
  - Add missing Nostr section (nsec_privkey, relays fields)
  - Expand Mostro section from 4 to 14 fields with logical grouping:
    * Fee configuration (fee, max_routing_fee)
    * Order limits (max_order_amount, min_payment_amount, max_orders_per_response)
    * Expiration settings (expiration_hours, max_expiration_days, expiration_seconds)
    * Publishing intervals (publish_relays_interval, user_rates_sent_interval_seconds, publish_mostro_info_interval)
    * Network/API (pow, bitcoin_price_api_url)
    * Market support (fiat_currencies_accepted)
  - Remove invoice_expiration_window from Mostro section (belongs in Lightning)
  - Add clarification that default values come from settings.tpl.toml template
  - Distinguish between template defaults and Rust defaults (RPC section)
  - Document all 28 configuration fields across 5 sections
  - Include type information and default values from source files
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7e1f2a4 and cff5a85.

📒 Files selected for processing (2)
  • docs/README.md (1 hunks)
  • docs/STARTUP_AND_CONFIG.md (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/README.md
🧰 Additional context used
🧠 Learnings (4)
📚 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:

  • docs/STARTUP_AND_CONFIG.md
📚 Learning: 2025-05-02T14:21:39.391Z
Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 481
File: src/config/util.rs:48-76
Timestamp: 2025-05-02T14:21:39.391Z
Learning: The `init_default_dir` function in Mostro intentionally exits the process (std::process::exit(0)) after creating a new configuration file so users can edit the configuration before restarting the application.

Applied to files:

  • docs/STARTUP_AND_CONFIG.md
📚 Learning: 2025-12-10T20:32:01.175Z
Learnt from: CR
Repo: MostroP2P/mostro PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T20:32:01.175Z
Learning: Never commit populated `settings.toml`; use `settings.tpl.toml` as template and copy to `~/.mostro/settings.toml` locally

Applied to files:

  • docs/STARTUP_AND_CONFIG.md
📚 Learning: 2025-12-10T20:32:01.175Z
Learnt from: CR
Repo: MostroP2P/mostro PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T20:32:01.175Z
Learning: Applies to src/**/*.rs : Runtime code lives under `src/`, with `app/` for order flows, `lightning/` for LND bindings, `rpc/` for the gRPC surface, and `config/` for settings helpers

Applied to files:

  • docs/STARTUP_AND_CONFIG.md
🪛 markdownlint-cli2 (0.18.1)
docs/STARTUP_AND_CONFIG.md

139-139: 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 (2)
docs/STARTUP_AND_CONFIG.md (2)

95-99: Verify DB URL examples (sqlite vs postgres) match actual supported backends.

The documentation shows both sqlite://mostro.db and postgres://user:pass@localhost/dbname as examples, but it's unclear whether the actual implementation supports both backends. If only SQLite is implemented (e.g., if db::connect() hardcodes SqlitePool), the postgres example is misleading and should either be removed or explicitly marked as "not supported". Check src/db.rs and src/config/ to confirm which backends are actually supported by the connection logic.


59-64: Avoid implying the DB password is retained beyond process memory.
Storing the decrypted password in config::MOSTRO_DB_PASSWORD is fine, but the doc should explicitly say it’s in-memory only and must never be logged (since the doc already discusses security).

  - Stores decrypted password in `config::MOSTRO_DB_PASSWORD`
+    - In-memory only; never write or log this value.

Also applies to: 183-185

⛔ Skipped due to learnings
Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 475
File: src/db.rs:0-0
Timestamp: 2025-05-08T13:07:29.484Z
Learning: For the database encryption in Mostro, the developer prefers caching only derived encryption keys rather than caching decrypted master keys in RAM, as a security measure to reduce the attack surface from potential memory dumps or runtime vulnerabilities.
Learnt from: arkanoider
Repo: MostroP2P/mostro PR: 475
File: src/db.rs:98-106
Timestamp: 2025-04-28T13:29:56.092Z
Learning: In the Mostro codebase, empty passwords are allowed by design because encryption is optional. If a user leaves the password empty, the system will not use encryption.

grunch and others added 4 commits December 12, 2025 17:10
Add documentation of the first-run exit behavior when creating config file.

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
- Standardized “Rust Default” wording
    - Replaced “Default impl” phrasing with “Rust Default implementation” and used it consistently.
    - Clarified fallback behavior to “falls back to the Rust Default value.”
- Required-keys guidance
    - docs/STARTUP_AND_CONFIG.md:87 refined sentence for clarity and consistent wording: keys must exist; if present but empty or omitted by tooling, daemon falls
back to Rust Default.
    - docs/STARTUP_AND_CONFIG.md:144 note now uses “Rust Default implementation” and repeats the required-keys rule.
    - docs/RPC.md:15 configuration intro now reads “keys are required; fields have Rust Default implementations but must be present.” Kept explicit defaults
inline per key.
    - docs/README.md: clarified pointer about Startup & Configuration explaining template-required keys and Rust Default.
@grunch grunch merged commit df1e8a8 into main Dec 12, 2025
6 checks passed
@grunch grunch deleted the add-technical-docs branch December 12, 2025 20:35
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.

2 participants