Skip to content

Referral program: on-chain payout mode with minimum threshold #184

Description

@v0l

Problem

Referral commission payouts currently support Lightning only (ReferralPayoutMode::LightningAddress and Nwc, plus the not-yet-implemented AccountCredit). Referrers who prefer an on-chain address — or whose balances exceed what's practical over Lightning — have no on-chain option.

Proposal

Add an on-chain payout mode to the referral program, gated by a minimum threshold so we never pay out amounts where on-chain fees would eat the payout.

Changes

  • ReferralPayoutMode::OnChain = 3 (append-only enum in lnvps_db) with FromStr/Display ("onchain" / "on_chain" aliases)
  • Referrer settings: store an on-chain payout address (validate network/format on save; consider requiring re-confirmation when changed)
  • Threshold: new min_onchain_payout_sats in the [referral] settings block (alongside the existing min_payout_sats used for Lightning). Balances below the threshold simply accrue until the next run — same pattern as the Lightning minimum
  • Payout worker (ReferralPayoutHandler): handle the new mode using the existing LND on-chain provider (send from the configured on-chain PaymentMethodConfig wallet); record txid on the payout record
  • Fee handling: decide whether the network fee is deducted from the payout or absorbed — should be explicit in the payout record either way
  • API: expose the new mode + address on the referral settings endpoints (user PATCH + admin), update ADMIN_API_ENDPOINTS.md / API_DOCUMENTATION.md / API_CHANGELOG.md

Notes

  • On-chain sending infra exists since the on-chain payments work (On-chain bitcoin payments #180 / f518b6a): the LND OnChainProviderConfig in payment_method_config can be reused for outbound
  • Threshold default should be conservative (e.g. 100k sats) since payouts compete with mempool fee conditions; possibly also check a max feerate before sending and defer if fees are high

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpaymentsPayment/invoice logic

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions