Wallet Ledger: Transfers, Retries and Scheduled Payments

Wallet Ledger: Transfers, Retries and Scheduled Payments

You've joined the payments team that owns the wallet ledger: the service that holds customer balances and moves money between wallets. Support has escalated two money-movement bugs, and the roadmap has three features queued behind them. All amounts are integer cents.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh ledger and returns one result per operation. Every operation is [name, ts, ...args]; ts is an integer number of seconds and never decreases. Errors are returned as strings, never raised.

• Each error is returned as "error: <code>", e.g. "error: insufficient funds".
• An unknown operation name returns "error: unknown operation". A wrong number of arguments or a non-integer ts returns "error: invalid arguments", as does open_account with an empty or non-string account_id or owner.
• A valid amount is an integer > 0 (true/false are not amounts).
• Account ids are case-sensitive strings. A closed account still answers balance and history.
• For transfer, "account not found" and "account closed" check the source before the target.
• Transfer ids are "tr-1", "tr-2", ... in the order transfers succeed. A rejected transfer does not use up an id.
• Statement lines: deposit +$50.00, withdrawal -$7.00, tr-1 to bob -$12.50, tr-1 from alice +$12.50 (thousands are comma-separated: +$1,234.56).

Worked example

[["open_account", 1, "alice", "Alice Ng"],
 ["open_account", 2, "bob", "Bob Ortiz"],
 ["deposit", 3, "alice", 5000],
 ["transfer", 4, "alice", "bob", 1250],
 ["withdraw", 5, "bob", 2000],
 ["history", 6, "alice"]]

returns

[true, true, 5000, "tr-1", "error: insufficient funds", ["deposit +$50.00", "tr-1 to bob -$12.50"]]

Part 1 — Fix two money-movement bugs (SUP-2291, SUP-2304)

Goal: make transfers and withdrawals follow the rules in the table above.

Customer reports:

1. "I tried to empty my wallet before closing it, but sending or withdrawing my entire balance is declined with *insufficient funds*. I can only move out one cent less than I have."
2. "I sent money to a friend's wallet that had already been closed, and it went through. The money is now stuck in the closed account."

Rules

1. A withdrawal or transfer of exactly the available balance succeeds and leaves a balance of 0. Anything above the balance fails with insufficient funds.
2. A transfer whose source or target is closed fails with account closed and changes nothing.
3. The error order in the table must hold (e.g. a transfer to a closed account from an account without enough money reports account closed).

tests/test_service.py::test_customer_can_send_entire_balance currently fails.

Part 2 — Idempotent retries with request ids (PAY-1183)

Goal: mobile clients retry requests when a response is lost; a retry must never move money twice.

Rules

1. deposit, withdraw and transfer (and, after Part 3, schedule and cancel_payment) accept one optional extra argument at the end: a request id (non-empty string). Any other operation given an extra argument, or a request id that is not a non-empty string, returns "error: invalid arguments".
2. The first time a request id is used, the operation runs normally and its result is stored — including error results like "error: insufficient funds".
3. A later operation with the same request id, the same operation name and the same arguments (ignoring ts) returns the stored result and has no effect (no money moves, no new transfer id).
4. Same request id but a different operation name or different arguments returns "error: idempotency key reused" and has no effect. That response is not stored.
5. Request ids are global (not per account). Operations without a request id are never deduplicated.
6. A request id is remembered for 86 400 seconds: an operation at ts < first_ts + 86400 is a replay; at ts >= first_ts + 86400 the id is forgotten and the operation runs as a brand-new request (whose result is then stored with the new first_ts).

Example (after opening alice and bob)

[["deposit", 3, "alice", 5000, "req-1"],
 ["transfer", 4, "alice", "bob", 1000, "req-2"],
 ["transfer", 9, "alice", "bob", 1000, "req-2"],
 ["transfer", 10, "alice", "bob", 2500, "req-2"],
 ["balance", 11, "alice"]]

returns [5000, "tr-1", "tr-1", "error: idempotency key reused", 4000].

Part 3 — Scheduled and recurring payments (PAY-1207)

Goal: implement PaymentScheduler so customers can schedule future and recurring transfers.

Rules

1. due_ts must be an integer greater than ts, and interval an integer >= 0; otherwise invalid schedule. A payment_id that is not a non-empty string returns invalid arguments. interval = 0 is a one-off payment; interval > 0 repeats every interval seconds (due_ts, due_ts + interval, ...). At schedule time only the checks in the table run — balances and closed accounts are checked when the payment executes.
2. Payments run lazily. Before handling *any* operation whose ts is an integer (reads, replays and operations that end up failing included), every occurrence with due time <= ts runs first, in order of due time, ties broken by the order the payments were created. Recurring payments catch up on every missed occurrence.
3. Each occurrence is an ordinary transfer (same rules as Part 1, next transfer id, appears in history). If it succeeds, runs increases; a one-off payment becomes completed.
4. If an occurrence fails for any reason, the payment becomes failed and never runs again.
5. cancel_payment works only on a scheduled payment (else payment not active); because of rule 2, an occurrence due exactly at the cancel's ts runs before the cancel.
6. payment_status returns status ("scheduled", "completed", "failed" or "cancelled"), runs (successful occurrences) and next_due (the next due time, or null unless scheduled).
7. schedule and cancel_payment support request ids exactly as in Part 2.

Example (after opening alice, bob and depositing 5000 to alice)

[["schedule", 10, "rent", "alice", "bob", 1500, 100, 0],
 ["balance", 99, "bob"],
 ["balance", 100, "bob"],
 ["payment_status", 101, "rent"]]

returns [true, 0, 1500, {"status": "completed", "runs": 1, "next_due": null}].

Part 4 — Spending leaderboard at scale (stretch)

Goal: add ["top_spenders", ts, k], returning the k accounts that have sent the most money.

Rules

1. An account's spend is the total of its successful outgoing transfers, including scheduled ones. Deposits, withdrawals and incoming transfers do not count; replays do not count twice.
2. Return [[account_id, spend], ...], largest spend first, ties by account_id ascending (plain string order). Accounts with zero spend are omitted; closed accounts are included. Fewer than k qualifying accounts → return all of them.
3. k must be an integer >= 1, otherwise "error: invalid arguments".
4. Hidden tests run tens of thousands of scheduled executions and hundreds of top_spenders calls in one run; the whole suite has a few seconds. Rescanning the journal on every call is too slow.

Notes

• money.py, statements.py, journal.py and accounts.py are known-good.
• You may use the AI assistant freely; you are expected to verify what it produces.
• Later parts must not break earlier ones; hidden tests re-check earlier behaviour.
• Parts 1-3 is a strong result. Part 4 is a stretch.