About Balance Reservations

---

What are balance reservations

Balance reservations are temporary holds placed on wallet balances while an intent is being processed. They guarantee that the funds required to execute the intent will still be available at commit time. This protects the intent from race conditions and double-spend, while making sure that balances will be moved correctly after all participants agreeing on the intent action.

Reservations are created during the two-phase commit (2PC) prepare step status: pending for every debit side that the ledger itself must honor. If an external system (via a Bridge) is responsible for a debit, that external system will perform its own reservation when it receives the prepare request. The ledger always participates as a 2PC participant for native balances and will reserve the needed amount before replying that it is prepared.

Why they matter

• Atomicity safety: Ensure that once all participants report prepared, the intent can be safely committed without balance shortfalls.
• Concurrency safety: Prevent other concurrent intents from consuming the same funds by removing reserved amounts from the available balance calculation.

Flow

Reservations are part of the 2PC step in the pending phase of intent processing:

1. Aspects validate the intent and its claims. No balance change or reservation occurs here.
2. 2PC starts. The coordinator identifies participants, reserve funds for debits and sends prepare requests.
   • Prepare is sent first to all debit sources and then to credit targets. See the note in About Intents.
   • Upon a debit prepare, participants validate the intent on their side.
   • After validating, the participant replies prepared.
3. If all participants are prepared and signature requirements are satisfied, the coordinator proceeds to commit.
4. On commit, reservations are consumed and balances are persisted. On abort, reservations are released after notifying bridges and no balance changes are persisted.

Reservation semantics

• Scope: Reservations are tracked per wallet and symbol for the specific address referenced by a claim.
• Available balance: When checking an incoming intent, the ledger evaluates the available balance as the wallet balance minus any active reservations for pending/prepared intents. By default balances cannot go below 0, so reservations will fail if they would breach that limit.
• Debit-only: Reservations apply to the debit side. Credits do not require a reservation by the ledger core (external targets may perform their own checks on prepare).
• Lifetime: A reservation lives from the moment preparation starts until the intent ends (committed or aborted).
• Timeouts and failures: If any participant fails on prepare or a timeout occurs while waiting for confirmations, the coordinator aborts the intent and all reservations are released.

Commit vs abort behavior

• Commit: Reserved amounts are applied to balances atomically with credits to targets. All reservations in the thread are cleared once the commit succeeds.
• Abort/Reject: No balance changes are persisted. All reservations are released, restoring the funds to available status.

Simple example

Consider an intent to transfer 30 USD from alice to bob. Initial available balances:

• alice 100 USD
• bob 0 USD

1. Aspects pass; 2PC begins.
2. Intent is pending, so core signer reserves 30 USD from alice wallet.

• alice has now 70 USD available and 30 USD reserved.
• bob USD balance remains 0.

2. Prepare for debit alice 30 USD:
   • The participant responsible for alice does their check and prepare.
3. Prepare for credit bob 30 USD: The participant acknowledges it can accept the credit and replies prepared.
4. All participants are prepared and required signatures are collected.
5. Commit:
   • alice is debited 30 USD from reserved amount. Her available balance is not changed.
   • bob is credited 30 USD, so his available balance in ledger is now 30 USD.
   • All reservations for this intent/thread are cleared. Final available balances:

• alice 70 USD.
• bob 30 USD.

If instead any participant failed on prepare (or a timeout was reached), the coordinator would abort the intent and release the reserved 30 USD for alice.

Interactions with Bridges

• If the debit source or credit target references a Bridge, that Bridge is a 2PC participant and must respond to prepare.
• For debits handled by a Bridge, the Bridge performs the equivalent of a reservation in its own system before replying prepared. Ledger still evaluates available balances for any native debits it must honor.
• On commit/abort, Bridges receive the corresponding commands and finalize or release their own holds.

Operational notes

• Intent expiration leads to reserved balances release, since the intent is aborted.
• Model limits explicitly. If a wallet supports overdrafts or custom limits, reservations still respect those limits during prepare.