Idempotency Persistence and Conflict Guarantees
WAproxy enforces persistent idempotency guarantees across restarts and retries.
Idempotency is not a temporary cache.
It is a durable execution contract.
------------------------------------------------------------
IDEMPOTENCY SCOPE
------------------------------------------------------------
Idempotency keys are scoped per wallet_id (WID).
Same idempotency key may exist across different WIDs,
but must never conflict within the same WID.
Key uniqueness rule:
(wallet_id, idempotency_key) must be unique.
------------------------------------------------------------
PERSISTENCE REQUIREMENT
------------------------------------------------------------
For every successful broadcast:
- txid must be stored
- amount_sat must be stored
- recipient address must be stored
- idempotency_key must be stored
- timestamp must be stored
This record must survive restart.
------------------------------------------------------------
RETRY BEHAVIOR
------------------------------------------------------------
If client retries with identical:
wallet_id
to
amount_sat
idempotency_key
WAproxy must:
- return stored tx result
- not rebroadcast
------------------------------------------------------------
CONFLICT RULE
------------------------------------------------------------
If client retries with same idempotency_key
but different parameters:
- Reject execution
- Return deterministic conflict error
- Do not mutate state
Example conflict:
Original:
amount_sat = 15000
Retry:
amount_sat = 20000
Result:
error_idempotency_conflict
------------------------------------------------------------
WHY THIS MATTERS
------------------------------------------------------------
Persistent idempotency prevents:
- duplicate economic execution
- race-condition double spend
- retry-induced loss
- inconsistent ledger history
------------------------------------------------------------
DESIGN PRINCIPLE
------------------------------------------------------------
An idempotency key represents
a financial execution intent.
Intent must either:
- execute exactly once
OR
- never execute
Never execute twice.
------------------------------------------------------------
ARCHITECTURAL STATEMENT
------------------------------------------------------------
Persistent idempotency is mandatory
for deterministic value transport
under unreliable network conditions.