Add referral program with lightning/NWC payouts

[Copilot]

Implements a referral program allowing users to earn payouts when referred users make their first payment. Supports automatic payouts via lightning address or NWC wallet.

DB Layer

• Migration: New referral (user enrollment, unique code per user) and referral_payout tables with invoice VARCHAR(2048), pre_image BINARY(32), currency VARCHAR(5), and amount BIGINT UNSIGNED columns
• Models: Referral and ReferralPayout added to lnvps_db; ReferralPayout includes invoice (BOLT11 lightning invoice) and pre_image (32-byte SHA256 hash revealed on payment)
• Trait: New methods on LNVpsDbBase:
  • CRUD for referral and referral_payout tables
  • list_referral_usage(code) — returns the first paid VM payment per referred VM (same logic as the admin referral report), used to compute per-currency earnings in application code
  • count_failed_referrals(code) — counts referred VMs that never made a paid payment

API (/api/v1/referral)

Method	Description
POST	Enroll — requires lightning_address and/or use_nwc; validates NWC is configured if requested; auto-generates 8-char base63 code
GET	Returns referral info, per-currency earnings breakdown, full payout history line-by-line, and success/failed referral counts
PATCH	Update payout options (nullable lightning_address, toggle use_nwc)

API Response Design

Since referrals can be paid in different currencies (EUR, BTC, etc.) that cannot be summed, and FIAT→BTC conversion happens at payout time with fluctuating rates, the GET response avoids single-currency aggregates and instead returns:

• earned: [{currency, amount}] — per-currency breakdown of amounts earned from referrals (sum of first payments per referred VM, grouped by currency)
• payouts: [...] — full payout history line-by-line (includes invoice, is_paid, etc.)
• referrals_success / referrals_failed — referral counts

Code Generation

Referral codes are 8 random bytes each mapped to a 63-char alphabet (A-Za-z0-9_).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Referral Program</issue_title>
<issue_description>Allow users to sign up for a referral program where they can enter a lightning address to have automatic payouts.
If users already have NWC configured on their account they can also select to have payouts sent to nwc wallet.

Referral codes should be auto-generated, base32 8 digit codes.

The backend should create 2 new tables, referral and referral_payout or something similar.

The user facing api should include endpoints to sign-up for referral program, update payment options, and get the current payout amount including number of referrals successful / unsuccessful as well as the total lifetime payout.

To calculate the pending/paid amounts compare the total referral amount against the completed referral_payout payouts.

Getting the current referral state should use a single query to compute the totals.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Referral Program #17

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• git.v0l.io
  • Triggering command: /home/REDACTED/.rustup/toolchains/stable-x86_64-REDACTED-linux-gnu/bin/cargo /home/REDACTED/.rustup/toolchains/stable-x86_64-REDACTED-linux-gnu/bin/cargo metadata --format-version 1 --all-features --manifest-path /home/REDACTED/work/api/api/Cargo.toml --filter-platform x86_64-REDACTED-linux-gnu --lockfile-path /tmp/rust-analyzerf64-0/Cargo.lock -Zunstable-options (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[v0l]

@copilot