xmrcheckout/TODO.md

xmrcheckout — Local TODO / Followups

Notes for ourselves. Not committed (see .gitignore or just left untracked). Kept here so context survives a terminal restart.

Reconciler wallet handling

Understanding (not a bug — design)

• Each merchant has their own Monero view-only wallet (user-<uuid>-<fingerprint>.keys).
• We run 3 monero-wallet-rpc containers as a pool. monero-wallet-rpc can hold one wallet open at a time. We hash-shard wallets across the 3 backends (consistent hashing on wallet_name).
• At any idle moment, 2 out of 3 backends are expected to hold no wallet. That's fine. Wallets open lazily when the reconciler needs to query them (via _ensure_wallet_open).
• open_wallet / close_wallet on the monero-wallet-rpc process is cheap when the wallet is already open in the wallet-rpc process (the wallet-rpc itself short-circuits), but our Python-side backend.current_wallet cache is reset every reconciler loop, so we send redundant RPC calls each loop.

Medium-priority followups

1. Make MoneroWalletService long-lived across reconciler loops. Currently reconciler.main() constructs MoneroWalletService() fresh every iteration, which resets backend.current_wallet = None. The actual monero-wallet-rpc process usually still has the wallet open, but our Python code doesn't know that, so it resends close_wallet + open_wallet on every loop. Harmless but wasteful — ~2 extra RPCs per active invoice per tick. Fix: hoist the service out of the loop, keep it across iterations.

2. Verify wallet-rpc recovery after wallet-rpc container restart. When wallet-rpc containers restart, the _ensure_wallet_open path should reopen wallets on first use. It appears to work in practice but we haven't written a targeted test. Add a test that simulates wallet-rpc restart between two invoice reconciliation passes for the same tenant.

3. Dedicated wallet-rpc backend per busy tenant. The consistent-hash sharding works fine at low tenant count. When one tenant becomes hot (lots of invoices), one backend is hit 100% and the other two sit idle. If we hit scale, think about either pinning hot tenants to dedicated backends, or sharding by invoice rather than tenant.

Webhook payload: amount propagation

• We now include amount (fiat from quote), currency, and amount_crypto in the BTCPay-compat webhook payload. This was added because Medusa's capture workflow needs the amount to flip captured_at — without it, it captures 0 and the payment stays stuck "authorized" even after we fire InvoiceSettled/InvoicePaymentSettled.
• Downstream followups:
  • Consider including amount_atomic (integer atomic units) for any processor that prefers integer arithmetic over Decimal strings.
  • Consider including exchange_rate at webhook time so downstream can reproduce the fiat figure if their Decimal precision differs.

Logging

• Silenced monero.backends.jsonrpc.wallet library logger (set to CRITICAL) in reconciler.py so the -13 No wallet file errors from routine close_wallet calls on idle backends stop polluting logs.
• If we need to debug wallet-rpc issues in the future, temporarily set it back to WARNING and rebuild.

Upstream PRs

Open PRs we submitted upstream (xmrcheckout/xmrcheckout):

• Advisory locks, restore_height lookback, transfer-deletion guard, decimal formatting, webhook retries, reconciler error logging.

Followups for upstream:

• Propose the webhook-amount addition as a PR once we've run it in prod for a week. That's a breaking-ish change for anyone downstream relying on a specific payload shape, so flag it carefully.
• Propose the get_status fix (drop the set_daemon call). Clear win — quiets log noise with no functional change. Low-risk PR.

Known-unfixed

• We do not yet have a way for a tenant to manually trigger re-send of a webhook delivery (e.g. if Medusa was down when the settle fired). Would be a nice admin UI action.
• If wallet-rpc runs out of memory handling many simultaneous wallet opens, we have no backpressure — the reconciler will just keep trying. Should add a circuit-breaker / per-backend queue depth limit at some point.