mostro

Imported from MostroP2P/mostro (AGENTS.md). Install upstream with npx skills add MostroP2P/mostro. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• Runtime code lives in src/.
  • src/app/ – order flows and business logic.
  • src/lightning/ – LND bindings and Lightning helpers.
  • src/rpc/ – gRPC service and types.
  • src/config/ – settings and loaders.
• DB migrations in migrations/. Reusable assets in static/.
• Docker assets in docker/. Cross‑compile targets in archs/.

Build, Test, and Development Commands

• cargo build – compile daemon (debug).
• cargo run – start Mostro using current settings.toml.
• cargo test – run module tests; keep green before pushing.
• cargo fmt – apply Rustfmt profile.
• cargo clippy --all-targets --all-features – lints must be clean.
• make docker-up / make docker-down – start/stop local relay stack.
• After schema changes: add a file under migrations/; mostrod applies pending migrations on connect.

Coding Style & Naming Conventions

• Rust 2021: 4‑space indent, snake_case functions, PascalCase types, SCREAMING_SNAKE constants.
• Document non‑obvious public APIs with ///.
• Prefer tracing spans over ad‑hoc logging.
• Keep config templates in settings.tpl.toml.

Testing Guidelines

• Co‑locate tests in their modules under mod tests.
• Name descriptively, e.g., handles_expired_hold_invoice.
• Mirror fixtures under src/app/ where applicable.
• Run cargo test locally after schema or query changes.

Commit & Pull Request Guidelines

• Write in English. Commit messages, PR titles and bodies, issue and review comments, documentation, and code comments are all English, regardless of the language a contributor or maintainer is speaking in elsewhere. Mostro has contributors who do not read Spanish, and a repository that mixes languages is one they cannot review.
• Base work on main; keep topics scoped.
• Commit subject: imperative, ≤50 chars; sign with git commit -S.
• Squash fixups before review.
• PRs: link the motivating issue, include cargo test output, and call out schema or config changes to ease verification.
• Protocol/tag changes: prefer single-kind (single event domain) PRs. Cross-kind changes require a scope declaration and compatibility statement in the PR body (see CONTRIBUTING.md § Protocol / Tag Changes).

Before opening a pull request

If you are an AI agent preparing a pull request, follow CONTRIBUTING.md § Contribution quality bar. In short:

• Link an issue labelled status: accepted (Closes #N). If there is no accepted issue, do not open the pull request; comment on the issue instead.
• Fill in every section of .github/pull_request_template.md, including Manual testing: steps a person ran by hand against a mostrod, with mostro-cli or Mostro Mobile. Do not present steps nobody ran as results. Ortsom is an internal tool of the Mostro developers; do not use or cite it.
• For a fix, the first commit is test: and adds a regression test that fails on main.
• If you could not build or run mostrod, say so in the pull request instead of claiming results.

A pull request that only changes Markdown files is exempt from the first three points (see the exemptions in that section); commits are still signed.

Documentation Guidelines

• Do not hardcode source code line numbers in documentation (e.g., src/app/take_buy.rs:11). Line numbers drift as the codebase evolves, misleading developers. Reference file paths (src/app/take_buy.rs) or function names (fn take_buy_action) instead, which are far more stable and easily searchable.
• Add a language specifier to every fenced code block. Static analysis (markdownlint MD040) flags blocks without a language identifier. Example: ```flutter test instead of bare ```.

Security & Configuration Tips

• Do not commit populated settings.toml. Copy from settings.tpl.toml to ~/.mostro/settings.toml for local runs.
• Protect LND credentials before make docker-build.
• Scrub logs that might leak invoices or Nostr keys; rotate secrets promptly if exposed.