Design an ATM

public interface ATMState {
    default void insertCard(ATM atm, Card card) { throw invalid(); }
    default void enterPin(ATM atm, String pin) { throw invalid(); }
    default void selectTransaction(ATM atm, TransactionType type) { throw invalid(); }
    default void ejectCard(ATM atm) { throw invalid(); }
 
    private static IllegalStateException invalid() {
        return new IllegalStateException("Operation not valid in current ATM state");
    }
}
 
public final class IdleState implements ATMState {
    public void insertCard(ATM atm, Card card) {
        atm.setCurrentCard(card);
        atm.setState(new CardInsertedState());
    }
}
 
public final class CardInsertedState implements ATMState {
    private int attemptsRemaining = 3;
 
    public void enterPin(ATM atm, String pin) {
        if (atm.getBankClient().authenticate(atm.getCurrentCard(), pin)) {
            atm.setState(new AuthenticatedState());
        } else if (--attemptsRemaining == 0) {
            atm.getCardReader().retainCard();
            atm.setState(new IdleState());
        }
        // else: remain in CardInsertedState, let the customer retry
    }
 
    public void ejectCard(ATM atm) {
        atm.getCardReader().ejectCard();
        atm.setState(new IdleState());
    }
}
 
public final class AuthenticatedState implements ATMState {
    public void selectTransaction(ATM atm, TransactionType type) {
        atm.setState(new TransactionInProgressState());
        atm.beginTransaction(type);
    }
 
    public void ejectCard(ATM atm) {
        atm.getCardReader().ejectCard();
        atm.setState(new IdleState());
    }
}
 
public final class TransactionInProgressState implements ATMState {
    // Withdraw/deposit logic lives in ATM.withdraw()/deposit(), invoked while in this state.
    // On completion (success or failure), ATM transitions back to AuthenticatedState
    // to allow another transaction, or IdleState after ejectCard().
    public void ejectCard(ATM atm) {
        atm.getCardReader().ejectCard();
        atm.setState(new IdleState());
    }
}
 
public final class OutOfServiceState implements ATMState {
    // All operations throw — machine is down for cash replenishment or fault recovery.
}

public final class Account {
    private final String accountId;
    private long balanceMinorUnits;       // store money as integer minor units (paise/cents)
    private final long dailyWithdrawLimitMinorUnits;
    private long withdrawnTodayMinorUnits;
    private LocalDate withdrawnTodayDate = LocalDate.now();
 
    public synchronized boolean canWithdraw(long amountMinorUnits) {
        resetIfNewDay();
        return balanceMinorUnits >= amountMinorUnits
            && withdrawnTodayMinorUnits + amountMinorUnits <= dailyWithdrawLimitMinorUnits;
    }
 
    public synchronized void debit(long amountMinorUnits) {
        resetIfNewDay();
        if (!canWithdraw(amountMinorUnits)) throw new IllegalStateException("Debit not permitted");
        balanceMinorUnits -= amountMinorUnits;
        withdrawnTodayMinorUnits += amountMinorUnits;
    }
 
    public synchronized void credit(long amountMinorUnits) {
        balanceMinorUnits += amountMinorUnits;
    }
 
    private void resetIfNewDay() {
        if (!LocalDate.now().equals(withdrawnTodayDate)) {
            withdrawnTodayMinorUnits = 0;
            withdrawnTodayDate = LocalDate.now();
        }
    }
 
    // constructor, getters omitted for brevity
    private String getAccountId() { return accountId; } // placeholder to keep example self-contained
}
 
public enum Denomination {
    TWO_THOUSAND(2000), FIVE_HUNDRED(500), TWO_HUNDRED(200), HUNDRED(100);
 
    final int value;
    Denomination(int value) { this.value = value; }
}
 
public enum TransactionType { WITHDRAWAL, DEPOSIT, BALANCE_INQUIRY }
public enum TransactionStatus { PENDING, SUCCESS, FAILED, REVERSED }

public final class CashDispenser {
    private final Map<Denomination, Integer> inventory; // sorted access via TreeMap-like ordering
 
    public boolean canDispense(long amount) {
        return dispensePlan(amount) != null;
    }
 
    /** Greedy: largest denomination first. Optimal when denominations are "canonical"
     *  (each divides evenly into reasonable combinations, as most currency systems are). */
    public Map<Denomination, Integer> dispensePlan(long amount) {
        Map<Denomination, Integer> plan = new EnumMap<>(Denomination.class);
        long remaining = amount;
 
        List<Denomination> byValueDesc = Arrays.stream(Denomination.values())
            .sorted(Comparator.comparingInt((Denomination d) -> d.value).reversed())
            .toList();
 
        for (Denomination d : byValueDesc) {
            int available = inventory.getOrDefault(d, 0);
            int notesNeeded = (int) Math.min(remaining / d.value, available);
            if (notesNeeded > 0) {
                plan.put(d, notesNeeded);
                remaining -= (long) notesNeeded * d.value;
            }
        }
        return remaining == 0 ? plan : null; // null = cannot fulfill with current inventory
    }
 
    public synchronized Map<Denomination, Integer> dispense(long amount) {
        Map<Denomination, Integer> plan = dispensePlan(amount);
        if (plan == null) throw new InsufficientCashException(amount);
        plan.forEach((denom, count) -> inventory.merge(denom, -count, Integer::sum));
        return plan;
    }
}

public final class WithdrawalTransaction {
    private final BankServerClient bankClient;
    private final CashDispenser dispenser;
    private final ReceiptPrinter printer;
 
    public TransactionResult execute(String accountId, long amount) {
        // Step 1: reserve funds (bank-side hold, not yet a final debit)
        String reservationId = bankClient.reserveFunds(accountId, amount);
        if (reservationId == null) {
            return TransactionResult.failed("Insufficient funds or limit exceeded");
        }
 
        // Step 2: attempt physical dispensing BEFORE committing the debit
        Map<Denomination, Integer> plan;
        try {
            plan = dispenser.dispense(amount);
        } catch (InsufficientCashException e) {
            bankClient.releaseReservation(reservationId); // undo the hold — no money moved
            return TransactionResult.failed("ATM cannot dispense requested amount");
        } catch (HardwareFaultException e) {
            bankClient.releaseReservation(reservationId);
            return TransactionResult.failed("Dispenser hardware fault");
        }
 
        // Step 3: only now, with cash physically out, commit the debit
        try {
            bankClient.commitReservation(reservationId);
        } catch (Exception e) {
            // Cash is already out and cannot be un-dispensed. This is the one case where
            // ATM and bank ledger can disagree — log for manual reconciliation, never retry blindly.
            AuditLog.critical("Cash dispensed but debit commit failed: " + reservationId);
            return TransactionResult.reconciliationRequired(reservationId);
        }
 
        printer.print(new Transaction(reservationId, TransactionType.WITHDRAWAL, amount, TransactionStatus.SUCCESS));
        return TransactionResult.success(plan);
    }
}