Balance Semantics — Available vs Confirmed Funds
WAproxy must distinguish between confirmed funds
and available spendable balance.
Not all visible balance is immediately spendable.
------------------------------------------------------------
CONFIRMED BALANCE
------------------------------------------------------------
Confirmed balance represents:
- UTXOs included in blocks
- funds with >= required confirmations
- economically finalized funds
Confirmed balance is stable.
------------------------------------------------------------
AVAILABLE BALANCE
------------------------------------------------------------
Available balance represents:
confirmed_balance
minus pending outgoing transactions
minus reserved safety margins (if applicable)
Available balance is execution-ready.
------------------------------------------------------------
UNCONFIRMED INCOMING
------------------------------------------------------------
Unconfirmed incoming funds:
- may appear in mempool
- may not be final
- must not be treated as confirmed
Application layer may choose to:
- accept 0-conf
- require N confirmations
WAproxy exposes state.
Policy belongs to application.
------------------------------------------------------------
OUTGOING PENDING STATE
------------------------------------------------------------
When wallet_send is broadcast:
- funds become pending
- available balance decreases immediately
- confirmation determines final settlement
This prevents double spending attempts.
------------------------------------------------------------
EXECUTION RULE
------------------------------------------------------------
Before send:
available_balance >= amount_sat + safety_margin
Not:
confirmed_balance >= amount_sat
------------------------------------------------------------
WHY THIS MATTERS
------------------------------------------------------------
Clear balance semantics prevent:
- accidental overspending
- double execution attempts
- confirmation race errors
- inconsistent accounting
------------------------------------------------------------
ARCHITECTURAL STATEMENT
------------------------------------------------------------
WAproxy separates confirmation state
from execution eligibility.
Balance visibility and balance usability
are not the same concept.