Add balance settlement feature for small remaining balances #4

New issue

Open

opened 2026-01-01 16:14:03 +00:00 by padreug · 0 comments

padreug commented

2026-01-01 16:14:03 +00:00

Owner

Feature Request

Problem

The proportional distribution algorithm creates a "Zeno's paradox" situation for clients with small remaining balances. When a client has a much smaller balance relative to others, they receive proportionally tiny payouts that asymptotically approach zero but never fully settle.

Example:

Bob has 100 GTQ remaining balance
Alice has 900 GTQ remaining balance
A 1,000 GTQ transaction comes in
Alice receives 900 GTQ worth of sats (90%), Bob receives 100 GTQ worth (10%)
Next round: Bob has ~10 GTQ, Alice has ~90 GTQ
Bob continues receiving diminishing payouts indefinitely

This creates a poor user experience where small-balance clients see tiny, drawn-out payments instead of being settled promptly.

Proposed Solution

1. Manual Settlement (Admin-Initiated)

Allow admins to manually initiate a custom payment to settle all or part of a client's remaining balance at the current exchange rate. The operator uses their own funds to make the client "square."

Add "Settle Balance" action in client management UI
Allow specifying a custom amount or "settle full remaining balance"
Use current BTC/fiat rate for the settlement calculation
Record as a special settlement payment in audit trail

2. Automatic Settlement (Threshold-Based)

Optionally automate settlements when balances fall below configurable thresholds:

Threshold Options:

Absolute threshold: Settle when balance < X GTQ (e.g., 50 GTQ)
Percentage threshold: Settle when balance < X% of original deposit (e.g., 5%)

Configuration:

Enable/disable auto-settlement
Choose threshold type (absolute or percentage)
Set threshold value
Designate settlement funding wallet

Implementation Ideas

New settlement_payments table or flag on existing dca_payments
Configuration fields in lamassu_config for auto-settlement rules
Settlement job runs after each distribution cycle
Clear UI indication that a payment was a settlement vs. regular distribution

Use Case

Bob deposits 1,000 GTQ and receives payouts over time
After several distribution cycles, Bob has 47 GTQ remaining
Auto-settlement threshold is set to 50 GTQ
System automatically settles Bob's remaining balance at current rate
Bob receives final payment and his balance goes to zero
Bob is notified his DCA cycle is complete

Benefits

Better user experience - clients see clean, complete settlements
Reduced operational overhead from managing many small balances
Eliminates the "infinite tail" of diminishing payments
Gives operators control over when to absorb small remainders
Clear audit trail distinguishing settlements from regular distributions

## Feature Request ### Problem The proportional distribution algorithm creates a "Zeno's paradox" situation for clients with small remaining balances. When a client has a much smaller balance relative to others, they receive proportionally tiny payouts that asymptotically approach zero but never fully settle. **Example:** - Bob has 100 GTQ remaining balance - Alice has 900 GTQ remaining balance - A 1,000 GTQ transaction comes in - Alice receives 900 GTQ worth of sats (90%), Bob receives 100 GTQ worth (10%) - Next round: Bob has ~10 GTQ, Alice has ~90 GTQ - Bob continues receiving diminishing payouts indefinitely This creates a poor user experience where small-balance clients see tiny, drawn-out payments instead of being settled promptly. ### Proposed Solution #### 1. Manual Settlement (Admin-Initiated) Allow admins to manually initiate a custom payment to settle all or part of a client's remaining balance at the current exchange rate. The operator uses their own funds to make the client "square." - Add "Settle Balance" action in client management UI - Allow specifying a custom amount or "settle full remaining balance" - Use current BTC/fiat rate for the settlement calculation - Record as a special settlement payment in audit trail #### 2. Automatic Settlement (Threshold-Based) Optionally automate settlements when balances fall below configurable thresholds: **Threshold Options:** - **Absolute threshold**: Settle when balance < X GTQ (e.g., 50 GTQ) - **Percentage threshold**: Settle when balance < X% of original deposit (e.g., 5%) **Configuration:** - Enable/disable auto-settlement - Choose threshold type (absolute or percentage) - Set threshold value - Designate settlement funding wallet ### Implementation Ideas - New `settlement_payments` table or flag on existing `dca_payments` - Configuration fields in `lamassu_config` for auto-settlement rules - Settlement job runs after each distribution cycle - Clear UI indication that a payment was a settlement vs. regular distribution ### Use Case 1. Bob deposits 1,000 GTQ and receives payouts over time 2. After several distribution cycles, Bob has 47 GTQ remaining 3. Auto-settlement threshold is set to 50 GTQ 4. System automatically settles Bob's remaining balance at current rate 5. Bob receives final payment and his balance goes to zero 6. Bob is notified his DCA cycle is complete ### Benefits - Better user experience - clients see clean, complete settlements - Reduced operational overhead from managing many small balances - Eliminates the "infinite tail" of diminishing payments - Gives operators control over when to absorb small remainders - Clear audit trail distinguishing settlements from regular distributions

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: aiolabs/satmachineadmin#4

No description provided.

Rows
Columns