Problem Description

Design and implement an in-app wallet system for an Airbnb-style platform, supporting both guests and hosts. The system must manage wallet balances, facilitate payments from guests to an escrow account at booking time, process refunds from escrow to guests, and handle payouts from escrow to hosts after a stay. A robust transaction recording mechanism and comprehensive error handling are essential.

Assumptions

• Currency: All transactions occur in a single currency (e.g., USD). Amounts are represented as integers in cents to prevent floating-point inaccuracies.
• Escrow: Funds are temporarily held in a central platform escrow account during the period between a guest's payment and the subsequent payout to a host or refund to a guest.
• Storage & Concurrency: For this exercise, an in-memory storage solution is acceptable, and concurrency control can be kept simple.

Requirements

1. Roles and Accounts

• User Wallets: Each Guest and Host user must have a dedicated wallet.
• Platform Escrow: A central platform escrow account is required to manage funds held in trust.

2. Core Operations

The system must support the following financial operations:

• Deposit: Funds transfer from an external source into a guest's wallet.
• Payment: Transfer of funds from a guest's wallet to the platform escrow account, linked to a specific booking_id.
• Refund: Transfer of funds from the platform escrow account back to a guest's wallet, identified by booking_id.
• Payout: Transfer of funds from the platform escrow account to a host's wallet, identified by booking_id.
• Balance Lookup: Ability to query the current balance for any guest wallet, host wallet, or the platform escrow account.

3. Transaction Recording

Every operation must be recorded as an immutable transaction with the following attributes:

• id: Unique transaction identifier.
• kind: Type of operation (e.g., 'deposit', 'payment', 'refund', 'payout').
• amount: Transaction value in cents.
• currency: The currency used (e.g., 'USD').
• from_account: Identifier of the source account.
• to_account: Identifier of the destination account.
• booking_id: Optional identifier linking the transaction to a booking.
• timestamp: Time of the transaction.
• idempotency_key: Optional key to prevent duplicate processing.

The system should also allow listing or querying transactions by booking_id.

4. Error Handling

The system must gracefully handle and prevent the following error conditions:

• Insufficient Funds: Attempting to debit an account with insufficient balance.
• Over-Refund/Over-Payout: Attempting to refund or payout an amount exceeding the funds currently held in escrow for a specific booking_id.
• Currency Mismatch: Operations involving different currencies (though assumed single currency for this problem, the design should account for it).
• Invalid Operation: Negative or zero amounts, or operations involving unknown users/bookings.
• Idempotency: Duplicate requests with the same idempotency_key must not result in double-spending or double-application. If a duplicate request with the same key has differing parameters, an error should be raised.

Deliverables

• Runnable Code: Provide a functional, in-memory reference implementation in a chosen programming language (e.g., Python, Java).
• Demonstration: Include a main function or equivalent that demonstrates and asserts the following scenarios:
  • Creation of a guest and a host.
  • A deposit of $100 to the guest's wallet.
  • A payment of $60 for booking_id "b1".
  • A refund of $10 for booking_id "b1".
  • A payout of $50 for booking_id "b1" to the host.
  • Demonstration that an idempotent duplicate request does not apply twice.
  • Demonstration that an error case (e.g., an over-refund attempt) is correctly raised.
• Output: The demonstration should print the final balances of all accounts and a complete transaction log.

Design Notes

• Object-Oriented Design (OOD): Prioritize a clean, extensible object-oriented design.
• Invariants: Focus on the clarity and correctness of financial invariants, such as double-entry accounting principles and accurate tracking of escrowed funds per booking. These are more critical than advanced infrastructure considerations for this problem.