System Design: Airbnb-Style Wallet with Ledger, Holds, FX, and Idempotency
Context
You are asked to design and implement an Airbnb-style wallet system that supports customer deposits, booking holds and captures, refunds, host payouts, multi-currency balances with FX conversion, and a double-entry append-only ledger. The system must be auditable, concurrency-safe, and idempotent.
Assumptions (explicit and minimal):
-
Amounts are stored in minor units (integers) to avoid floating-point errors.
-
Each user has a wallet with per-currency sub-accounts. Platform and hosts are also modeled as accounts.
-
A double-entry ledger ensures that for every entry, debits equal credits; balances are derived from the ledger. For performance, a materialized balances table is maintained transactionally.
-
Booking currency is used for hold and capture; users may convert between currencies within their wallet via an explicit convert operation.
Requirements
-
Create user accounts and allow deposits.
-
Support booking holds/authorizations and later captures at check-in.
-
Allow hold release on cancellation or expiry.
-
Process partial/full refunds.
-
Pay out hosts after platform fees and taxes.
-
Enforce spendable vs. total balance with no negative spendable balance.
-
Support multi-currency balances with FX conversion and rounding rules.
-
Ensure idempotent operations via client-supplied idempotency keys.
-
Guarantee concurrency safety for duplicate or overlapping requests.
-
Maintain an append-only auditable ledger and derive balances from it.
-
Provide reconciliation to detect inconsistencies.
-
Define persistence schema (tables or classes) and transaction isolation choices.
-
Expose clear APIs/methods and include a minimal main() to run sample scenarios.
-
Write unit tests for happy paths and edge cases (insufficient funds, expired holds, double-capture attempts, partial refunds, FX rate changes). Include core classes (Wallet, Account, Transaction, Hold, Capture, Refund, Payout, LedgerEntry, FXConverter), their relationships, method signatures, and analyze time/space complexity of critical operations.