Lock lifecycle and clocks

Four independent timers govern a lock, and none of them can be collapsed into another. This page states what each one bounds, what it deliberately does not bound, and the exact state transitions a lock can make.

The clocks are the hardest part of this contract to hold in your head, and every serious defect in versions 2 through 5 was a clock doing a job that belonged to a different clock. That history is the argument for keeping them separate, and it is on Threat model.

The four clocks#

lockCooldownUntil is 2 × withdrawDelay + SETTLE_DELAY, which is 2 hours 2 minutes with this deployment's one-hour delay.

Why the lot clock and the bidder clock are separate#

They do different jobs, and the conflict between them is real rather than an implementation detail.

• Freeing collateral the house is still entitled to is destructive. It has to be governed by the lock's own age, so that a lock created against a live lot cannot be voided by a stranger before the house has had its settlement delay.
• Bounding how long a bidder can be held is protective. It has to be keyed to the bidder, because the abuse it prevents (a settler rotating through fresh lot ids to renew a freeze for ever) is invisible to any per-lot clock.

Version 5 resolved this by making them separate mechanisms: only the lot's own clock frees a lock, and the bidder's clock instead refuses to let the settler add encumbrance. Nothing the settler does with lot ids gets past that, because the check does not look at the lot at all, and no honest lock is destroyed to achieve it.

The lock state machine#

Transitions in full#

The cooldown asymmetry#

An episode the settler ends itself, by release, by settle or by locking to zero, stamps no lockCooldownUntil. An episode expireLock ends does. This looks inconsistent and is deliberate: ordinary auction turnover must stay usable, and a cooldown after every outbid would make the escrow unusable for a bidder who loses several lots in an evening.

The bidder is not left exposed by that, because the still-due episode clock requires the same free interval before it may restart. Episodes therefore cannot be chained into a continuous freeze whichever way the previous one ended.

The episode, and its ceiling#

An encumbrance episode begins when lockedOf rises from zero and ends only when the bidder has been at zero for the full exit window. Within one episode the ceiling is 2 × MAX_LOCK_AGE, and the house states that as 60 days rather than 30 because 30 would be a number it could only honour by voiding collateral it had already promised.

1. Day 0: the bidder takes a lead. encumberedSince starts.

2. Days 0–30: the settler may raise, add locks on other lots, and draw on a pending withdrawal. Every raise gives that lock a fresh 30 days of its own.

3. Day 30: the episode falls due. lock now reverts EncumbranceDue on any raise. Existing locks are untouched and remain settleable: a lead taken in good faith before this instant can still be collected.

4. Up to day 60: the last lock creatable was created an instant before day 30 and runs its own 30 days. Locks drain by their own expiries.

5. lockedOf reaches zero. freeSince is stamped.

6. Plus 2h 2m of genuine freedom, and only then may a new episode begin, with a fresh 30-day clock.

function _exitWindowElapsed(uint256 freed) private view returns (bool) {
    return freed != 0 && block.timestamp >= freed + 2 * withdrawDelay + SETTLE_DELAY;
}

The withdrawal clock#

A fifth timer, on the bidder's own side rather than the house's.

The immediate fall in freeOf is the anti-sniper property: the house counts the request against bidding power at once, so funds cannot back a bid and exit before its close. The tokens staying put is what lets lock draw them back if a lead needs collateralising: the correction of version 2's worst defect, and the reason limit 2 exists.

Worked timelines#

An ordinary win#

A raise near the close#

The one-minute wait is why SETTLE_DELAY is two minutes and not twenty: it sits below the five-minute extension window, so a raise this late has already moved the close anyway and no ordinary sale is delayed by it.

A house that stops answering#

If the guardian is still reachable, revokeSettler collapses day 30 to immediately.

Choosing the constants#

The auction engine enforces the first of these from its own side too: every lot create, edit, extend and bid path asserts that the close, plus the invoice period, plus the default grace, plus an operational margin, still fits inside the lock's remaining life, and refuses the operation with escrow-duration if it does not. A protocol bound is not a UI preference.