BidEscrow v6 contract reference

The complete external surface: storage, constants, every function with its full precondition set, every event, every custom error, and the invariants that hold across all of them. Written for a reader with the source open.

Constants and immutables#

Constructor preconditions#

constructor(address token_, address treasury_, address settler_, address guardian_, uint256 withdrawDelay_) {
    require(token_ != address(0) && treasury_ != address(0) && settler_ != address(0) && guardian_ != address(0), "zero address");
    require(token_.code.length != 0, "token has no code");
    require(withdrawDelay_ >= 1 minutes && withdrawDelay_ <= 7 days, "withdrawDelay out of range");
    require(settler_ != guardian_, "settler is the guardian");
    require(treasury_ != settler_ && treasury_ != guardian_, "treasury is a role key");
    require(treasury_ != address(this) && treasury_ != token_, "treasury is the escrow or the token");
    ...
}

Every one of these guards a value nobody can change afterwards, so every one is checked here rather than in a deploy script that may not be the thing which deploys. The treasury != settler check in particular is what makes the sentence "a stolen settler key cannot steal" true, and it is enforced again in acceptSettler, because a constructor check alone is walked past by two ordinary, fully authorised rotations.

Storage#

Bidder functions#

Always self-signed. None of them is gated on the house, and three of the five are outside the brake.

Credits amount to balanceOf[msg.sender]. Requires a prior ERC-20 approve.

The credited amount is verified against the contract's own balance delta rather than trusted from the argument, so a fee-on-transfer token is refused instead of crediting a bidder more than the escrow actually received:

uint256 before = IERC20Minimal(token).balanceOf(address(this));
if (!IERC20Minimal(token).transferFrom(msg.sender, address(this), amount)) revert TransferFailed();
require(IERC20Minimal(token).balanceOf(address(this)) == before + amount, "balance delta mismatch");

Reverts: ZeroAmount, IsPaused, TransferFailed, or the balance-delta require.

EIP-2612: one signature, one transaction, no prior approve. This is the path the site uses by default because Base USDC supports it.

The permit call is wrapped in try/catch on purpose. A permit can be front-run: anyone may submit the same signature, consuming the nonce and making a second call revert. If the allowance is already in place the deposit should still succeed rather than fail on a griefing transaction that did the user a favour. The transferFrom below it is the real authorisation check.

Moves amount of free balance into pendingWithdrawalOf and sets withdrawableAt = block.timestamp + withdrawDelay. A second request adds to the pending amount and restarts the clock on the whole of it.

The delay is the anti-sniper gap: because freeOf subtracts the pending amount immediately, the house counts a requested withdrawal against bidding power the moment it lands, so funds cannot back a bid and exit before its close.

Reverts: ZeroAmount, InsufficientFree(requested, free).

Transfers the pending amount to msg.sender after the delay. This is the exit, and it is deliberately unconditional: no modifier, and no read of settler, guardian or paused anywhere in the body.

The event is emitted before the token call. The state change is already complete and a failed transfer rolls the log back with it, so emitting first means a token callback that deposits again appears afterwards, matching the final absolute balance in the event stream rather than contradicting it.

Reverts: NothingPending, TooEarly(nowTs, claimableAt), TransferFailed.

Returns the pending amount to bidding power and clears the clock. Reverts: NothingPending.

House functions#

All three are onlySettler and all three are inside the brake. None of them can reach an address the house did not fix at deployment.

Sets the lock for (bidder, lot) to amount, an absolute adjustment, up or down, not a delta. Moves no tokens.

Preconditions, in the order they are checked#

1. msg.sender == settler, else NotSettler.
2. !paused, else IsPaused.
3. No-op short circuit. amount == current returns immediately, writing nothing and emitting nothing. A re-lock at the value already held subtracts zero, writes the value back over itself, refreshes no clock, and used to emit a fully formed Locked anyway: a settlement-grade record of an event that did not occur, in the one stream the contract asks auditors to trust.

On a raise only (amount > current), three further gates:

4. block.timestamp >= lockCooldownUntil[bidder], else LockCoolingDown. Checked only on a raise: lowering or clearing a lock gives collateral back and must never be blocked, least of all during the window that exists to release the bidder.
5. The episode gate. If encumberedSince != 0 and block.timestamp >= encumberedSince + MAX_LOCK_AGE, the raise is refused with EncumbranceDue unless the bidder genuinely starts a fresh clock, meaning lockedOf == 0 and the full exit window elapsed since freeSince.
6. Funding. added = amount - current must be covered by freeOf(bidder), or the shortfall is drawn out of pendingWithdrawalOf, emitting WithdrawReduced. If the shortfall exceeds the pending amount too, InsufficientFree(added, free + pending).

Effects on a raise#

lockedOf[bidder] += added;
lockedAt[bidder][lot] = block.timestamp;
lockExpiresAt[bidder][lot] = block.timestamp + MAX_LOCK_AGE;

Both clocks refresh together. Restarting settlement without refreshing expiry made a raise in the last two minutes of an old lock permissionlessly expirable before it could legally settle: the house could lose collateral it was owed. This was defect M-01, found in the v5 audit.

On a reduction, lockedOf decreases and the clocks are untouched. Setting amount = 0 additionally zeroes both clock slots. Every path then calls _markEncumbrance and emits Locked(bidder, lot, amount, lockedOf[bidder]).

Clears the lock entirely: the bidder was outbid, the lot was withdrawn, or the sale resolved without them. Their balance stays theirs; nothing moves. Idempotent: a double release on a zero lock returns silently.

Why it is pausable. This is the half of the brake that used to be missing. settle is pausable, so the brake stopped the house collecting; release was not, and the server answers a reverted settle by releasing the winner's collateral. Pressing the brake therefore handed every in-flight winner their money back with the invoice unpaid. Inside the brake, the settlement state freezes instead of unwinding. A bidder loses nothing they could rely on: release is onlySettler, so it was never a path they could take. expireLock is, and it is not pausable.

Transfers amount to the immutable treasury in payment of the bidder's invoice, clears the lock, and releases any part of it above amount in the same transaction.

Events precede the token call, for the same reason as in claimWithdraw: if the transfer fails the revert removes both state and logs, while a callback that re-locks this pair leaves its later absolute Locked event as the stream's last word, matching final storage.

Permissionless functions#

Releases a lock that has stood past its own lockExpiresAt. This is the only function that undoes a lock without the settler, and it is what makes the encumbrance bounded rather than indefinite.

The age requirement is waived once the settler has been revoked. The wait exists to give the house time to settle a lock it is entitled to; with no settler there is nobody who can ever settle or release it, so the timer has nothing on the other end and holding a bidder to it would be punishment for the house's incident. settler == address(0) is reachable only through revokeSettler.

The cooldown it writes#

uint256 coolUntil = block.timestamp + 2 * withdrawDelay + SETTLE_DELAY;
if (coolUntil > lockCooldownUntil[bidder]) {
    lockCooldownUntil[bidder] = coolUntil;
    emit LockCooldown(bidder, coolUntil);
}

Twice the delay, and the margin after it is not padding. A withdrawal takes two steps separated by withdrawDelay. A window of one delay is never usable: expire at T and the window closes at T+D; the bidder cannot request before T, so her claim ripens at T+D at the very earliest: the same instant the settler may lock again, decided by ordering within one block. Two delays put a last-moment request's claim at exactly the old boundary, where ordering still wins. SETTLE_DELAY is the smallest security interval this contract already asks the chain to preserve, and it remains after the latest claim can ripen.

Emits Released and LockExpired, never one instead of the other, so an existing indexer stays correct with no schema change.

Views#

Whether a positive increase to any lock for bidder is legal right now, before considering the amount of free collateral. This is the exact non-money precondition lock enforces, published so an off-chain bid gate can refuse an obligation before recording a lead it cannot collateralise.

if (paused || settler == address(0)) return false;
if (block.timestamp < lockCooldownUntil[bidder]) return false;
uint256 since = encumberedSince[bidder];
if (since == 0 || block.timestamp < since + MAX_LOCK_AGE) return true;
return lockedOf[bidder] == 0 && _exitWindowElapsed(freeSince[bidder]);

When this bidder's episode clock falls due: encumberedSince + MAX_LOCK_AGE, or 0 when lockedOf is 0. Since v5 that does not make any lock expirable: it is the instant from which lock refuses to add encumbrance.

return balanceOf[bidder] - lockedOf[bidder] - pendingWithdrawalOf[bidder];

What new bids can be backed by, and what can be requested for withdrawal.

lockedAt + SETTLE_DELAY, or 0 when there is no lock. The server asks this before spending gas on a settle it would only have to re-broadcast.

Public mappings#

Every storage slot in the table above has an automatic getter: balanceOf, lockedOf, lockOf, lockExpiresAt, lockedAt, pendingWithdrawalOf, withdrawableAt, encumberedSince, freeSince, lockCooldownUntil, plus settler, pendingSettler, guardian, pendingGuardian, paused, token, treasury, withdrawDelay, VERSION, MAX_LOCK_AGE, SETTLE_DELAY.

Roles and the brake#

Why the guardian cannot propose a settler#

Letting it looks free, because acceptSettler refuses a caller that already holds the other role. That check compares addresses. Separation of duties is about parties, a guardian with a second address proposes it, accepts from it, and holds both roles: a pause-only key that can then encumber every bidder's free balance and push locked collateral into the treasury. No on-chain check can tell that address apart from an honest new settler key, which is why the power is absent rather than guarded.

Why revokeSettler also pauses#

deposit is the one verb a revoke does not otherwise stop, and a deposit into an escrow that can never lock, settle or release is a trap. The revoke cannot be raced: a thief holding the settler key can propose and accept successors all day, and one revoke ends every one of them, where a rival proposal only ever trades places with the last accept.

Events#

Custom errors#

Invariants#

1. balanceOf[b] >= lockedOf[b] + pendingWithdrawalOf[b] for every b. freeOf would underflow otherwise, and it is unchecked arithmetic by construction rather than by unchecked.
2. lockedOf[b] == Σ lockOf[b][lot] over all lots. Maintained by every path that touches a lock.
3. The token balance of the contract is at least Σ balanceOf. Deposits verify the received delta; the only outflows are claimWithdraw and settle, each of which decrements balanceOf by exactly what it sends.
4. encumberedSince[b] != 0 whenever lockedOf[b] != 0.
5. A settle is impossible earlier than SETTLE_DELAY after the lock's last increase: the property that makes the brake reachable.
6. No function transfers to an address that is neither msg.sender nor the immutable treasury.

On reentrancy#

There is no reentrancy guard, and none is needed: every external token call is the last statement of its function, after all state changes and all event emissions. A malicious token that re-enters finds storage already consistent and the event stream already written, and any state it then creates appears afterwards in both, which is exactly the ordering an indexer should see. The two functions that call out are claimWithdraw and settle; deposit calls out first but re-reads the balance afterwards and reverts on any mismatch.

Integration checklist#

• Assert VERSION() == 6 at startup. The house's own indexer refuses to write a v6 event stamp against an escrow reporting anything else, which is what caught a box pointed at the wrong contract before it wrote a single stamp.
• Call canIncreaseLock, not freeOf, before accepting an off-chain obligation.
• Treat Locked.amount as absolute and Released.amount as a delta.
• Handle WithdrawReduced or your pending-withdrawal figure will drift permanently.
• Book at a depth at least as deep as your reorg assumption. This deployment books at max(confirmations, reorgDepth) = 40 blocks; settling at 3 while treating 40 as replaceable was defect H-08.
• Read settleReadyAt before broadcasting a settle.
• Pin the wallet a lock was taken on to the lot, not to the account. See the auction engine for what goes wrong otherwise.