refactor: EscrowBackend seam — Cashu foundation CF-0

[grunch]

Summary

CF-0, the Wave-0 precursor of the Cashu foundation (docs/cashu/01-fundamentals.md §6). Behaviour-preserving refactor only — no new runtime behaviour, no config, no Cashu logic.

• src/escrow.rs (new): narrow, hold-invoice-shaped EscrowBackend trait (create_hold_invoice / settle_hold_invoice / cancel_hold_invoice), per locked decision §4.7 (the trait keeps the LN shape; Cashu behaviour will come from branching handlers on escrow_mode(), never from widening this trait).
  • impl EscrowBackend for LndConnector: literal pass-through to the inherent methods. The cancel delegation preserves the code=<Code> error-prefix contract that bond release relies on.
  • CashuBackend stub: every method returns a typed HoldInvoiceError("… not implemented …") — never panics.
• release_action now takes &mut dyn EscrowBackend; the app.rs call site coerces the existing &mut LndConnector implicitly.
• settle_seller_hold_invoice (util.rs) takes the seam too.

Deviation from the spec'd conflict surface (one file)

The spec lists CF-0's surface as src/escrow.rs + src/app/release.rs. Routing release_action through the seam necessarily drags settle_seller_hold_invoice (in util.rs) with it — that's the helper release_action settles through. Its other caller (admin_settle) passes its &mut LndConnector unchanged via implicit coercion, so no other file is touched. Flagging it here so the docs can be amended if maintainers prefer.

Trait return types (design note)

The spec doesn't pin the trait's return types. The LND inherent methods return gRPC response types (AddHoldInvoiceResp, etc.); the trait uses domain shapes instead — (payment_request, preimage, hash) for create, () for settle/cancel — so the seam doesn't leak fedimint_tonic_lnd types. The only routed call today (settle) discarded the response anyway, so this is still a pure pass-through.

Backwards-compat guarantee (CF-0 merge gate)

Lightning calls flow through the pass-through impl unchanged; the pre-existing suite passes unmodified.

Test plan

• cargo fmt --all
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test — 504 passed (503 pre-existing unmodified + 1 new: cashu_backend_stub_returns_typed_error_without_panicking)

Part of the CF-0…CF-5 foundation series; CF-1 (config + escrow mode) follows independently.

Summary by CodeRabbit

• New Features

  • Added support for a shared escrow interface, enabling release and settlement flows to work through a broader payment backend.
  • Introduced a placeholder escrow option for future non-LN settlement support.

• Bug Fixes

  • Updated hold-invoice settlement to use the active escrow backend, improving consistency across release flows.
  • Added safer fallback behavior for unsupported escrow actions, returning clear “not implemented” errors instead of failing unexpectedly.

[coderabbitai]

Walkthrough

Introduces an EscrowBackend trait abstraction with implementations for LndConnector and a stub CashuBackend. Wires the new escrow module into main.rs, and updates release_action and settle_seller_hold_invoice to accept &mut dyn EscrowBackend instead of &mut LndConnector, delegating settlement through the trait.

Changes

Escrow Backend Abstraction

Layer / File(s)	Summary
EscrowBackend trait and implementations src/escrow.rs	Defines EscrowBackend trait (create/settle/cancel hold invoice), implements it for LndConnector by delegating to inherent methods, adds a CashuBackend stub returning typed "not implemented" errors, plus a unit test verifying stub error content.
Module export and call site rewiring src/main.rs, src/util.rs, src/app/release.rs	Exports the escrow module, changes settle_seller_hold_invoice and release_action signatures from &mut LndConnector to &mut dyn EscrowBackend, and routes hold-invoice settlement through the new trait.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• MostroP2P/mostro#760: Both PRs introduce the same EscrowBackend abstraction and update the same release_action/settle_seller_hold_invoice call sites to use &mut dyn EscrowBackend.
• MostroP2P/mostro#765: Both PRs refactor the hold-invoice settlement path to route through EscrowBackend instead of a direct ln_client.
• MostroP2P/mostro#788: Documents the same CF-0 seam implemented here via EscrowBackend/CashuBackend.

Suggested reviewers: ermeme, Catrya

Poem

A rabbit hops through code so neat,
Trading ln_client for a trait so sweet,
Cashu waits behind a stub's disguise,
"Not implemented" — no surprise!
Hold invoices settle, safe and sound,
Escrow's seam is finally found. 🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main change: introducing an EscrowBackend seam for the Cashu foundation refactor.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cashu-cf0-escrow-seam

---

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.}

[grunch]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

src/escrow.rs (1)

1-14: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Place the escrow seam under the documented runtime module layout.

src/escrow.rs introduces runtime code at the src/ root, while the project layout rule keeps runtime code under the listed subdirectories. Consider moving this seam under the closest existing domain subtree, likely src/app/escrow.rs for order/business flow routing or src/lightning/escrow.rs if the module is intended to remain Lightning-adjacent, then update imports accordingly.

As per coding guidelines, "src/**/*.rs: Runtime code lives in src/ with subdirectories: src/app/ for order flows and business logic, src/lightning/ for LND bindings and Lightning helpers, src/rpc/ for gRPC service and types, and src/config/ for settings and loaders".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/escrow.rs` around lines 1 - 14, The escrow seam is placed at the runtime
root instead of the documented module subtree, so move the `EscrowBackend` trait
from `src/escrow.rs` into the appropriate domain module, likely
`src/app/escrow.rs` for flow routing or `src/lightning/escrow.rs` if it stays
Lightning-specific, and update the module declarations/imports that reference
it. Keep the trait and its `LndConnector` dependency in the same domain area so
the runtime layout matches the project convention and any callers continue to
use the new module path.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/escrow.rs`:
- Around line 1-14: The escrow seam is placed at the runtime root instead of the
documented module subtree, so move the `EscrowBackend` trait from
`src/escrow.rs` into the appropriate domain module, likely `src/app/escrow.rs`
for flow routing or `src/lightning/escrow.rs` if it stays Lightning-specific,
and update the module declarations/imports that reference it. Keep the trait and
its `LndConnector` dependency in the same domain area so the runtime layout
matches the project convention and any callers continue to use the new module
path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c6ebba46-d36a-4d17-9fbd-b97b74310fc7

📥 Commits

Reviewing files that changed from the base of the PR and between 53e0086 and b13a376.

📒 Files selected for processing (4)

• src/app/release.rs
• src/escrow.rs
• src/main.rs
• src/util.rs

[grunch]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: b13a3765ab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".