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.