CredibleBlockGuard

Git Source

Title: CredibleBlockGuard

Author: Phylax Systems

Reusable mixin that gates functions on block credibility. Inherit it and apply the onlyCredibleBlock modifier to any function that should only execute while the current block is credible, i.e. built by a Credible Layer builder that enforces assertions. When the credible builder set is offline the guard fails open so the protected contract is never bricked.

This is the general-purpose form of the credibility gate. {CredibleSafeGuard} is the same decision wired into a Safe transaction guard; protocols that want to protect their own functions directly should inherit this contract instead. Decision in _checkCredibleBlock (run by onlyCredibleBlock before the function body):

1. If the credible builder set looks offline (the most recent credible block is more than failOpenBlockThreshold blocks behind the current block), FAIL OPEN and allow the call. This prevents a stalled builder set from permanently locking the contract.
2. Otherwise the builder set is live, so the current block MUST be credible; if it is not, the call is blocked with NonCredibleBlock.
3. If the current block is itself credible, the call is always allowed. Fail-open window. The product requirement is “fail open after ~15 minutes with no credible blocks”. The {ICredibleRegistry} records credibility by block number and does not expose timestamps, so the window is expressed as a block count that the credible builder set would produce in ~15 minutes on the target chain, e.g.:

• ~12s blocks (Ethereum mainnet): 15 min ~= 75 blocks
• ~2s blocks (typical L2): 15 min ~= 450 blocks
• ~1s blocks: 15 min ~= 900 blocks Both the registry address and the fail-open threshold are immutable; re-pointing or re-tuning means redeploying the inheriting contract. (Configurable per deployment.)

Constants

credibleRegistry

The on-chain Credible Registry queried for block credibility.

ICredibleRegistry public immutable credibleRegistry

failOpenBlockThreshold

Number of blocks the most recent credible block may lag the current block before the guard fails open. Should approximate the chain’s 15-minute block budget.

uint256 public immutable failOpenBlockThreshold

Functions

constructor

constructor(ICredibleRegistry credibleRegistry_, uint256 failOpenBlockThreshold_) ;

Parameters

onlyCredibleBlock

Reverts the call unless the current block is credible or the guard is failing open.

Apply to any function that must only run under credible-block protection.

modifier onlyCredibleBlock() ;

isCurrentBlockAllowed

Whether a call guarded by onlyCredibleBlock would currently be allowed.

View helper mirroring _checkCredibleBlock’s decision for off-chain inspection.

function isCurrentBlockAllowed() public view returns (bool);

Returns

failOpenActive

Whether the guard is currently failing open because the builder set looks offline.

function failOpenActive() public view returns (bool);

Returns

_checkCredibleBlock

Core gate: fail open when the builder set is offline, otherwise require credibility.

function _checkCredibleBlock() internal view;

_failOpenActive

Fail-open is active when the current block is strictly more than failOpenBlockThreshold blocks ahead of the last credible block. The block.number > lastCredibleBlock_ guard avoids underflow if the registry ever reports a last credible block at or beyond the current block.

function _failOpenActive() internal view returns (bool);

Errors

NonCredibleBlock

Thrown when the current block is not credible and the builder set is live.

error NonCredibleBlock();

ZeroCredibleRegistryAddress

Thrown when constructed with the zero address as the registry.

error ZeroCredibleRegistryAddress();

ZeroFailOpenBlockThreshold

Thrown when constructed with a zero fail-open threshold.

error ZeroFailOpenBlockThreshold();