Design a Crypto Payment Splitter Contract

Problem statement

Design a smart contract that receives inbound payments — native ETH from protocol revenue, ERC-20 tokens from NFT royalties, settlement transfers from a DeFi venue — and automatically allocates them proportionally to a set of beneficiaries, for example 30% dev team, 20% marketing, 50% DAO treasury. The system must support inbound ETH and ERC-20 reception, pre-defined share percentages, governed changes to recipients or shares over time, and complete event logging of every distribution.

This is not a backend fan-out problem. There is no retry queue, no operator who can fix a ledger, and no rollback. Every deposit is a single irreversible transaction against immutable or slowly-governed code, executed in a hostile environment where any caller may probe for reentrancy, rounding dust, token quirks, or governance capture. The design therefore separates three planes: the money plane (deposits, accounting, claims), the control plane (share configuration, ownership, timelocks), and the observation plane (events, indexer, dashboard, alerts).

Why the problem is distinctive

A payment service can retry a failed transfer. A splitter cannot: a push-based loop over recipients that reverts halfway leaves value stranded or double-counted unless the accounting model makes partial failure impossible by construction. The core insight of this answer is that distribution should be pull-based accounting, not push-based transfers: a deposit updates O(1) internal accounting, and each beneficiary claims their own balance in their own transaction, so one poisoned recipient can never block the other nineteen. Motion in a robot fleet is safety-critical; value in a splitter is custody-critical, and the same discipline applies: name the invariant, then make violations unrepresentable.

The attached brief requires inbound reception for tokens and ETH, pre-defined shares, optional dynamic share updates, and distribution logging, plus security against manipulated shares and reentrancy, scalability for many deposits and recipients, reliability where partial distribution cannot fail mid-step, and an optional configuration UI. The section rhythm, visual vocabulary, recap contract, quiz placement, multi-cloud diagrams, and WinSystemDesign Friend rules follow the uploaded orchestrator and master prompt, while the field shapes and multilingual code contract follow the uploaded metadata and the 30-section pacing modeled on the structural reference.

Public operating baseline versus design assumptions

Public evidence establishes that splitter contracts are production infrastructure. OpenZeppelin's PaymentSplitter has been shipped inside OpenZeppelin Contracts since the 2.x line and is one of the most-deployed utility contracts in the ecosystem. 0xSplits runs a singleton SplitMain with composable minimal-proxy splits used by DAOs and creator platforms. Superfluid's General Distribution Agreement streams flow-rate payments to pools with weighted members. Lido accrues a basis-point protocol fee by minting treasury shares rather than sweeping transfers. These are cited public designs, not requirements for our contract. For capacity planning this answer explicitly assumes one splitter instance with 12 initial recipients growing to at most 200, 3,000 deposits per day average with a 10x settlement peak, and 5 supported tokens. Unless a number is tied to a citation, it is a stated design assumption, target, budget, or illustrative threshold.

The three architectural planes

1. Money plane: receive functions, balance-delta ingestion, per-token accumulator accounting, per-recipient claimable balances, claim execution.
2. Control plane: owner, timelock, configuration proposals, share versioning, token allowlist policy, upgrade or redeploy strategy.
3. Observation plane: events, subgraph indexer, dashboard, reconciliation jobs, alerting, verified source and simulation tooling.

A strong interview answer keeps these planes separate. It allows the observation plane to be fully centralized and replaceable while the money plane remains trust-minimized and the control plane remains slow, gated, and auditable.