Anatomy of a Build: a Revocable Token-Vesting Vault

The brief

Design a revocable, single-token (ERC-20) vesting vault:

• A project funds the vault and creates cliff + linear release schedules for multiple beneficiaries.
• Beneficiaries claim their vested-but-unclaimed tokens over time.
• The project (a multisig) can revoke a beneficiary's unvested tokens — vested tokens stay with the beneficiary, unvested return to the project.
• Emergency pause halts both claim and revoke.
• Immutable. Two trust boundaries: a privileged owner and untrusted beneficiaries. Hardened against non-standard ERC-20s (fee-on-transfer, missing return values, ERC-777 reentrancy callbacks). Rebasing tokens are explicitly out of support, not hardened against — a negative rebase breaks the conservation invariant and can't be fixed at the contract layer, so it's carried as a deployment caution instead.

This is exactly the kind of thing AI will happily generate in thirty seconds — and exactly the kind of thing that loses real money when the thirty-second version is wrong.

How I built it

The work ran through a five-stage adversarial loop, each stage a separate reviewer that only sees the artifacts — not the reasoning that produced them:

1. Intake → a structured brief: actors, trust boundaries, value flows, failure modes.
2. Contract modeling → storage layout, asset-conservation invariants, the time-based state machine.
3. Interface design → function signatures, revert conditions, events, with checks-effects-interactions annotated.
4. Security architecture → threat model + the implementation spec.
5. A deterministic safety gate, then an independent adversarial security reviewer whose only job is to break the design.

It did not pass on the first try. The first review came back REVISE — three Major findings. That's the system working.

What the review caught — before a line of code

1.A subtraction underflow that would brick every call before the start date.

The linear-release formula was mathematically correct. But the reviewer flagged that if the implementation evaluated the subtraction t - start before checking the branch condition, then for any schedule with a future start date — a completely normal case — the call would underflow and revert. The consequence: every view and every revoke touching that schedule would fail until its start date arrived. The spec's pseudocode had the right branch order but never warned that the subtraction must only be evaluated once the branch condition holds. So I made that explicit and added the acceptance test for it.

2.A missing deployment safeguard.

The design nowhere required the delivery to carry a "this contract custodies value — get an independent third-party audit and run a testnet rehearsal before mainnet" instruction. For a value-custody contract, that omission is itself a defect. Added.

3.An undefined boundary return.

The behavior at timestamp < start (return zero vs. revert) wasn't specified, and nothing tested it. Defined and covered.

All three were closed in a second pass — which, on review, actually hardened the revoke path beyond the original requirement. The second adversarial review returned PASS with no new findings.

The part I'm most proud of: I don't even trust my own gates

The deterministic gate in this build checks five structural red-lines on the design. When I built that gate, it passed 44 green tests. I still put it through an independent adversarial review — and the reviewer found it failing open: a function whose security intent was missing, empty, or even just misspelled (value_transfer with an underscore instead of value-transfer) would be silently skipped by the checks, letting a state-changing function slip past the floor entirely.

Forty-four passing tests said it was fine. It wasn't. I changed the gate to fail safe — block on anything it can't classify, rather than skip it — and the test count went from 44 to 51.

If I hold my own quality checks to "must survive an independent adversary whose only job is to break it — and get fixed when it doesn't," that's the standard your code gets too.

Scope & honesty

I believe the transparency is part of the product, so: this was a design-and-specification engagement. It produced a production-intent design, an interface contract, a threat model, and an implementation spec, hardened through two rounds of adversarial review.

I'd rather tell you exactly what this is than oversell it and get caught in due diligence. That instinct is, not coincidentally, the same one that catches the underflow bug.

Go deeper: the full technical teardown → — the Solidity that shows the trap, the fail-open bug an independent review found in my own gate, and what this does not prove.