Address Reservation

Overview

Address Reservation is an intermediate lifecycle state between availability and assignment. The system marks one entry from the Address Pool as unavailable to other requests while it completes the surrounding database or API operation.

Reservation must be atomic. Database row locks, unique constraints, or compare-and-set operations can ensure that two checkout workers do not both believe they reserved the same address.

A reservation can expire if payment creation fails before the address is displayed. However, once the destination has been returned to a client, logged externally, or placed in a QR code, ordinary pool reuse can create late-payment risk.

The reservation should preserve network, asset, intended customer or session, and the operation that created it. This context supports safe conversion into Address Assignment or controlled release.

Monitoring should identify stuck reservations and repeated failures that deplete inventory. Automatic cleanup needs idempotency and audit history so an address is never simultaneously treated as reserved, assigned, and available.

Reservation timeout should reflect how long the surrounding checkout transaction can remain incomplete. If an API response is lost after the address was generated, a retry should first query or reconcile the earlier reservation instead of immediately allocating another address. This prevents address inventory growth and keeps one customer session from having several active destinations.

Reservation cleanup jobs should be safe to run repeatedly and should never release a record that has become assigned. The cleanup query must compare state and version atomically rather than relying only on elapsed time.

Metrics should distinguish reservations released before exposure from addresses abandoned after display, because only the first group is normally safe for immediate reuse.