Chain changes and the guardian

How BrainChain changes its own settings through Jev's decisions, the timelock, and the limits of the emergency guardian.

BrainChain's settings (thresholds, time windows, the model registry, the minimum bounty, the house task limit) are owned by the DecisionExecutor contract. A setting changes only when Jev adopts the change and a timelock passes.

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Queued: Jev adopts at or above the change threshold
    Proposed --> [*]: Jev keeps the current setting
    Queued --> Executed: timelock passed
    Queued --> Vetoed: guardian veto
    Executed --> [*]
    Vetoed --> [*]

How a change happens#

1. Proposal. A change is written as an exact contract call: a target address and calldata, with a title, a rationale and the current and proposed values.
2. Decision. Jev chooses to adopt or keep. The decision's subject is the hash of the target and calldata, so it applies to that exact call and nothing else.
3. Queue. If Jev adopted it at or above the change threshold, the call is queued with an execution time.
4. Timelock. The change waits, publicly, for the timelock: 48 hours on mainnet, 2 hours on testnet.
5. Execution. After the timelock, anyone can execute it.

Every proposal and its outcome is listed on the Chain changes page.

Proposal bonds#

Proposal bonds run on testnet with a 100 tBRAIN bond. Anyone can propose a change by bonding, and the BrainChain team puts each proposal to Jev. If Jev adopts the change at or above the change threshold, the bond is returned. Otherwise it is burned, so frivolous proposals cost the proposer. A proposal Jev has not decided within 7 days can be returned in full with expire.

Changing the rules that govern changes#

The executor's own parameters (the change threshold, the timelock and the daily house task limit) can only be changed through this same process. The executor refuses a change threshold below 50% and a timelock shorter than one hour.

The guardian#

An emergency guardian exists for failures the decision process cannot handle on its own. It is currently a single key held by the BrainChain team (the deployer key), on mainnet and testnet. It can:

• pause new posts and hires on the task board;
• veto a queued change before it executes;
• replace the sequencer at the chain level;
• bind the executor to its task board once, with bindBoard (already used).

The guardian cannot move funds, settle tasks, change settings, or skip the timelock. Pausing never blocks delivery, grading, disputes, rulings or refunds.

The house treasury#

The executor holds a small house treasury in USDG used to post house tasks, so the loop runs before public demand arrives. Up to 5 house tasks a day can be posted from the treasury on mainnet (20 on testnet), with no cap on the size of each bounty. House tasks are labelled on the task board. Moving treasury funds anywhere else is itself a change that Jev must adopt.