Risk Steward

For the holder of a risk-steward grant (AccessControl.isRiskSteward(addr)) and for whoever operates the automation that signs as one. The role’s place in the authority model: Access Control. Why risk parameters carry no timelock: §4.

1. The role is two functions

Admin.setAssetParamsBounded(address pool, address token, uint128 minLiquidity, uint16 minFeePbps, uint16 vegaBps) and Admin.raiseKappa(address pool, address token, uint16 kappaCovBps), both gated by _onlySteward. That is the entire surface. Neither queues: the call either writes in the same transaction or reverts. On a foreign GEN-1 pool both lanes belong to the pool’s seat, and a protocol steward has no standing there.

setAssetParamsBounded moves minFeePbps and vegaBps inside the owner’s hard fences; a raise lands as is, a lowering is bounded cumulatively to maxDeltaBps below the value at the start of the current 24 h window (AdminParams.StewardWindow). raiseKappa raises kappaCovBps and nothing else, and voids any live UPDATE_RISK op for the leg.

The grant is timelocked and contract-only: AccessControl.queueRole(RISK_STEWARD, s) runs _validateAddr, which reverts NotCode for an address with no code, and executeRole lands it after the LISTING delay. Revocation (revokeRiskSteward) is instant and never policy-checked, by the rule guardians follow: a steward that turns out to be wrong must stay instantly removable.

Everything in the right-hand column is an owner action, except halting, which is a guardian action (Guardian). The steward exists so the fast half of risk management does not require the owner key, and so reaching for it cannot become a back-door to the rest.

2. The clamp rules, exactly

setAssetParamsBounded (AdminParams.setBounded) applies five checks in this order. The order is the difference between a plan that lands and one that reverts opaquely mid-incident.

1. Fences must be armed. RiskFences are per (pool, token) and set by the owner via setRiskFences. If maxDeltaBps == 0 the call reverts NotConfigured(ASSET, token). The lane fails closed until the owner arms it: an unfenced asset is unreachable, not a free-for-all.

2. minLiquidity must pass through unchanged. If the value differs from the live Asset.minLiquidity, the call reverts InvalidInput. Read the live asset and echo the field back.

3. No lowering under a live owner op. If the owner has an UPDATE_ASSET_PARAMS op queued for this leg and that op moves minFeePbps (or vegaBps), a steward lowering of that field reverts AlreadyPending until the op executes or is cancelled. A raise still lands, and the owner’s stale op then fails its own compare-and-swap.

4. Hard fences, absolute and always applied.

5. The 24 h lowering envelope (_loosenOk). A raise, or a value equal to the live one, passes. A lowering must satisfy

new · 10000 >= anchor · (10000 - maxDeltaBps)

where anchor is the field’s value when the current window opened (Admin.stewardWindow, AdminParams.StewardWindow), ratcheted up by any raise on any lane inside the window. A window opens lazily on the first call at or past the previous end and lasts STEWARD_WINDOW = 24 hours. The bound is on cumulative displacement from the anchor, not on the step: N calls in a block compose to one bounded move, and a raise followed by a lowering measures from the raised value.

On success the call emits BoundedAssetParamsUpdated(pool, token, minFeePbps, vegaBps, tighten), with tighten = minFeePbps >= cur.minFeePbps && vegaBps >= cur.vegaBps.

raiseKappa has one rule: kappaCovBps > cur.kappaCovBps, else InvalidInput; the pool’s own bounds still apply ([50, 10000], and a spoke may not exceed its hub). It voids any live UPDATE_RISK op for the leg, because that payload was an absolute RiskConfig authored against the pre-raise κ and its execute would undo the raise; the owner re-queues. It emits RiskConfigUpdated(pool, token, flags).

3. What the owner’s fences mean for you

You consume fences; you never write them. Their shape constrains what plans are expressible:

• maxDeltaBps is in (0, 10000]. It is the 24 h lowering budget for both fenced fields.
• minFeeHardMinPbps is required non-zero. A zero floor is not a floor; it would leave the ratchet open while looking fenced.
• Re-arming a fence (setRiskFences) deletes the leg’s steward window, so the envelope re-opens from the state it was armed on.
• The owner’s own unbounded setAssetParams is still floored by an armed minFeeHardMinPbps (_requireFeeFloor), re-applied at executeSetAssetParams. Lowering below an armed fence is deliberately two transactions, owner or not.
• That fee floor is the only fence that binds the owner lane. vegaHardMinBps / vegaHardMaxBps and maxDeltaBps are read by setAssetParamsBounded alone: the owner path writes any vega the global PoolConfig bounds admit, immediately when the write is a defensive tighten and through the TUNING queue otherwise. The owner is kept out of the fenced lane itself (NotOwner): a key that can widen the fences and write inside them in one transaction would bypass that queue.

If a plan you need is not expressible inside the live fences, the answer is a fence change by the owner, not a sequence of steward calls that walks there.

4. Risk parameters are deliberately not timelocked

setRiskFences, setAssetParamsBounded, raiseKappa and setRiskConfigTighten bypass the timelock entirely. The steward lane writes exactly two fields (minFeePbps, vegaBps) and never queues; minLiquidity is an argument only so the call can prove it is unchanged, and any delta reverts InvalidInput. The matching RiskFences are minFeeHardMinPbps, minFeeHardMaxPbps, vegaHardMinBps, vegaHardMaxBps and maxDeltaBps: a hard min/max pair for each field, plus one cumulative lowering bound over a 24 h window.

A design boundary, not an oversight: BTR’s edge is fast risk-parameter adaptivity, so those calls stay immediate and the control is the bounded envelope plus a dedicated, revocable risk role, not a delay. De-risking is free in every lane. Structural changes (asset add/remove, curve install) route through requestOp at LISTING; bounded numbers in the risk-up direction (UPDATE_RISK, UPDATE_PROFILE, UPDATE_FEES, a weakening setAssetParams) at TUNING.

5. What this key is the last line of defence against

The steward lane is what makes an untimelocked risk parameter safe: a key that can move the fast scalars within the hour, but only inside bounds the owner set in advance and only in steps small enough to be observed and reversed. The exposures it closes:

σ is not a steward lever and does not need to be: it adapts at push cadence through the signed oracle blob with zero governance latency (Oracle Keeper). Sub-hour band adaptation therefore needs only vega to track its target.

Shape is not a steward lever either. Splines are not hot-updatable, so a shape change repoints at a pre-certified preset through the owner’s requestOp(UPDATE_PROFILE) queue at the TUNING tier. The dispersion band’s ceiling is not a lever at all; it is the protocol constant PoolConstantsLib.MAX_DISPERSION_PBPS.

6. The standing invariants

The steward lane fixes a breach; it does not detect one. Detection is the risk keeper’s guardian predicates, which observe and alert only: that module holds no executor and builds no plan, so there is no path from a breach to a transaction. The predicate set and its severities are Observability. The re-page cooldown is six hours per predicate and key, chosen so a standing breach stays visible without training the operator to filter the channel.

The one that couples this role to the oracle keeper:

minFeePbps >= 2θ per supervised pool × asset, where θ is what the push keeper is actually running for that feed, not what the config you are editing says.

A fee floor below twice the push threshold is an anti-pick-off failure: the mark can move by θ between pushes and a round trip inside 2θ is free. The oracle keeper checks the same invariant over its own pools list, which is empty in some shipped configs and therefore silent (Oracle Keeper); the risk keeper checks it over every supervised pool because it already holds both halves of the comparison.

θ and the curve parameters are one optimisation variable. A θ change ships as an atomic bundle (the fast scalars, the preset repoint, and an edit to the push keeper’s oracle.*.toml), never as three independent deploys. A partial deploy silently breaks the between-push discipline.

7. If the automation signs for you

btr-keeper risk is the supervised implementation of this role. What it enforces applies to a manual retune too.

• Double gate. Live requires both --execute and RISK_EXECUTE=1, and signs with a dedicated steward key, never a money-path key.
• Refuses the stronger key. Startup reads AccessControl.owner() and aborts if it equals the configured signer. The fenced lane rejects the owner outright (_onlySteward reverts NotOwner), and a keeper holding that key is a far larger blast radius than the bounded lane.
• Refuses to arm without the role. AccessControl.isRiskSteward(signer) is read at startup: two eth_calls, never per sweep. Fatal when armed; in dry-run it reports and disables transaction simulation, so a NotAuth revert is not the only thing a dry run ever shows.
• Global circuit breaker. max_updates_per_h caps broadcast param updates per rolling hour across every pool and asset, and must land in [1, 30]: an armed keeper rejects 0 and anything above the MAX_UPDATES_PER_H_CEILING of 30. Per-asset limits alone are not a cap: every asset can satisfy its own simultaneously.
• Refuses stale inputs. max_fit_age_h bounds the artifact half, in [1, 8760] hours, and max_measure_age_h the live tape half, in [1, 168]. A class-default fallback row, or one whose tapeStatus is not ok, is refused outright unless allow_provisional is set; with it set the row may only tighten, and a loosen off a provisional row holds as ProvisionalLoosen.
• Asymmetric deadbands and dwell. A tighten crosses a smaller deadband than a loosen, and a tighten bypasses dwell entirely: only a loosen has to persist. The lever decides which floor it persists against, not the word “band”: a θ move or a minDispersionPbps (scale) move takes dwell_shape_s, floored at 24 h, because both re-base the whole quote; the 1 h dwell_band_s floor applies only to the fee/vega FAST lane. cooldown_s is required to be at least dwell_band_s, so the emission tempo can never outrun the fastest dwell, and a successful emission resets the dwell clock rather than carrying the previous window forward.
• An explicit hold list. Assets under review are named in config, because a hold that lives only in a shell comment is not a control.
• A pre-submit mirror of the chain. The clamp rules of §2 are re-implemented off chain and a plan that would revert is never built, so failures read as a named invariant rather than an opaque ThresholdViolation.

None of those numbers are protocol constants and none are on chain. Deadbands, dwell, caps, θ floors and per-asset vega targets are deployment-specific and live in the risk keeper’s risk.<chain>.toml, bounded by the keeper-side floors and ceilings named above, which no config may go under or over. The fences that bound the writes themselves live on chain in Admin.riskFences(pool, token).

8. Before a write

• Read the live asset, IPool(pool).getAsset(token): you need minLiquidity verbatim and the live minFeePbps / vegaBps.
• Read Admin.riskFences(pool, token). maxDeltaBps == 0 means the lane is shut; stop and ask the owner to arm it rather than retrying.
• For any lowering, reconstruct the window anchor: the field’s value at the last window open, raised by any raise since. end is internal; derive it from your own BoundedAssetParamsUpdated history or assume the worst case, that the window is still the one your earlier lowering opened.
• Check for a live owner UPDATE_ASSET_PARAMS op on the leg (TimelockRequested without a matching execute or cancel). A lowering of a field it moves reverts AlreadyPending.
• Check the destination against the hard fences before the envelope, because a lowering inside maxDeltaBps can still land under hardMin.
• Check minFeePbps >= 2θ against the θ the push keeper is running now (§6).
• Simulate. The lane never queues, so there is no window in which to notice a mistake.

9. After a write

• getAsset(token) reflects the new minFeePbps and vegaBps, and minLiquidity is untouched.
• BoundedAssetParamsUpdated is in the receipt, and its tighten flag matches your classification. A mismatch means your model of the live state was stale.
• Realized fee is at or above the new floor: feeAvgBps against minFeePbps / 100 (Observability). There is no maximum; below the floor means mispriced risk.
• The window floor is anchor · (1 - maxDeltaBps/10000); a later lowering in the same window measures against that same anchor, and a raise moves the anchor up, never the floor down.
• The guardian predicates that motivated the change have cleared, and no new one has opened.

Parameter and halt events are snapshot triggers rather than indexed topics, so retuning is not queryable from the indexer (Observability). Verify against chain state.

10. Escalate

Contact and intake: security@btr.markets, Access Control §2.1.

11. Checklist

On grant

• isRiskSteward(you) is true on the AC that Admin.AC() returns, and the granted address is the address that will sign.
• The signing key is not the owner key and not a money-path key.
• riskFences(pool, token) is armed for every asset you are expected to cover: maxDeltaBps, both fee bounds, both vega bounds.
• You can read live getAsset for every covered leg without the front-end.
• You know the θ each covered feed is running, and where that number is configured.

Before each write

• Live Asset read this block; minLiquidity echoed verbatim.
• maxDeltaBps != 0.
• Every lowering fits the 24 h envelope from the window anchor, not from the live value.
• No live owner UPDATE_ASSET_PARAMS op moves a field you are lowering.
• Destination inside every hard fence.
• minFeePbps >= 2θ still holds after the change.
• Simulated against current state, not against the plan that generated it.

After each write

• getAsset matches the intended values; minLiquidity unchanged.
• BoundedAssetParamsUpdated.tighten matches your classification.
• Realized feeAvgBps at or above the new floor once flow resumes.
• The rolling-hour update budget still has headroom for a reversal.
• The originating predicate has cleared and is not re-paging.

12. Related