Escrow looks simple from the outside. The path is short:
- A client funds a milestone.
- The freelancer works.
- The client approves.
- The money moves.
That sounds like four states and three transitions. It was the least forgiving thing we have built, because every ambiguity becomes a question about somebody’s money.
Boolean flags leave too many legal-looking states
The tempting model is a few flags on a record:
- funded
- submitted
- approved
- paid
That reads well, and it fails the first time two things happen at once. A client approving while a freelancer resubmits, on a row with four independent booleans, has sixteen possible combinations and only a handful are legal.
An explicit state column with an enumerated set of transitions gives the record one named stage and a controlled set of next moves. That makes the illegal combinations unrepresentable. It is more work to write and considerably less work to reason about at two in the morning.
The history matters as much as the current state
Storing the current state tells you where a milestone is. It does not tell you how it got there, and during a dispute that is the only question anyone asks. We record every transition with:
- its actor
- its timestamp
- what triggered it
We treat the current state as a projection of that history rather than the source of truth.
Repeated release requests must return the same outcome
A network timeout on a release request must not be able to release twice. Every state-changing request carries a key, and a repeat of the same key returns the original outcome rather than performing the action again. Engineers call this idempotency.
That is a small amount of work at build time and an extremely expensive conversation to have afterwards.
Approval should cause release directly
The design decision that removed the most complexity was making approval directly cause release, rather than setting a flag that some later process reads. Every intermediate step between a client approving and a freelancer being paid is a place where money can sit while somebody investigates.
Marketplaces are only one example. Any system where a thing moves through stages and the stages have consequences benefits from the same treatment. When the thing is money, you find out quickly whether you got it right.
