Withdrawal Troubleshooting

Purpose of Withdrawal Troubleshooting

This page defines the deterministic framework used to analyze, explain, and resolve withdrawal-related issues without mutating historical settlement records. Withdrawal troubleshooting is treated as a verification and reconciliation process, not an ad hoc operational response.

Separation Between Request, Execution, and Settlement

A withdrawal consists of three distinct phases: request validation, execution on the underlying network, and settlement finalization in the internal ledger. Troubleshooting begins by identifying which phase is incomplete or inconsistent, ensuring that failures are localized rather than assumed to be global.

Request Validation Failures

If a withdrawal does not progress beyond the request phase, the system verifies account state, balance sufficiency, limits, and authorization status at the time of request. No settlement mutation occurs until all validation conditions are satisfied, preventing partial or ambiguous debits.

Execution-Level Issues

Execution issues occur when a withdrawal request is approved but the corresponding on-chain transaction is delayed, rejected, or reverted. In this state, the internal ledger reflects a reserved or pending status rather than a finalized debit, preserving balance invariants while execution is unresolved.

On-Chain Confirmation and Reorganization Checks

Once an execution transaction is broadcast, troubleshooting verifies inclusion, confirmation depth, and chain stability. Transactions affected by congestion or reorganization remain non-final until stability thresholds are met, ensuring that settlement state does not diverge from canonical chain outcomes.

Settlement Finalization Conditions

A withdrawal is finalized only when execution success and stability criteria are both satisfied. At this point, the internal ledger transitions deterministically from pending to settled. If criteria are not met, the system does not finalize settlement and instead maintains an auditable pending state.

Handling Failed or Reverted Withdrawals

Withdrawals that fail or revert after execution attempt do not result in silent balance changes. The reserved amount is released through a deterministic reversal entry, preserving historical traceability and preventing manual balance correction.

Audit and Replay Implications

All troubleshooting outcomes are recorded as explicit state transitions. Independent systems can replay withdrawal history, observe each decision point, and reproduce final balances without relying on external explanations or operational context.

Defined Non-Goals

This framework does not provide customer support guidance or user-facing instructions. It defines system-level behavior only, ensuring that withdrawal handling remains deterministic, auditable, and reproducible under all failure conditions.

Scope and Dependencies

This page is a derivative specification within GMG Engine. It does not define or redefine core primitives such as settlement, determinism, finality, proof, or exception handling. All authoritative definitions are inherited from the locked GMG Engine core primitives.

Related Core Primitives

This page depends on the authoritative definitions established in: Deterministic Outcomes, Settlement Ledger Format, Settlement Finality, Transaction Proof.