Add protocol peg keeper allowlist

[mswilkison]

Summary

• add a DAO-governed peg keeper allowlist with deposit and redemption treasury fee waivers
• add delayed BridgeGovernance updates for keeper status via beginPegKeeperUpdate(keeper, allowed) / finalizePegKeeperUpdate()
• prevent a queued peg keeper update from being silently overwritten by another pending keeper update
• add cancelPegKeeperUpdate() so governance can clear an abandoned or misencoded pending keeper update without applying it
• add a proxy-admin-gated V6 Bridge upgrade initializer that seeds an initial non-zero keeper and permanently disables the legacy bridge rebate hook
• keep the legacy rebate staking fallback for non-keeper users until the bridge hook is disabled, and require balanceOwner == redeemer plus an allowlisted redeemer for redemption fee waivers
• add explicit RebateStaking deprecation mode that stops new staking and rebates, sets unstakingPeriod and rebatePerToken to zero, and preserves user-controlled exits
• add an atomic RebateStaking initializeV2_Deprecate() path restricted to the proxy admin for timelock upgradeAndCall execution, plus owner-callable deprecate()
• make initializeV2_Deprecate() idempotent if owner deprecation already happened before the upgrade initializer is executed
• add withdrawStake(receiver) so existing stakers can withdraw the full locked stake in one transaction after deprecation

Deployment notes

• Intended RebateStaking deprecation action: upgrade RebateStaking through ProxyAdmin.upgradeAndCall(... initializeV2_Deprecate()).
• Intended Bridge action: upgrade Bridge through ProxyAdmin.upgradeAndCall(... initializeV6_ConfigurePegKeeper(initialPegKeeper)) to allowlist the initial keeper, clear the bridge rebate hook, and permanently block future rebate hook wiring.
• initializeV6_ConfigurePegKeeper is restricted to the Bridge proxy admin, rejects address(0) as the initial keeper, and emits RebateStakingRepaired(oldRebateStaking, address(0)) when clearing the bridge rebate hook.
• Additional peg keepers can be added through beginPegKeeperUpdate(keeper, true) / finalizePegKeeperUpdate().
• Existing peg keepers can be removed through beginPegKeeperUpdate(keeper, false) / finalizePegKeeperUpdate().
• A new peg keeper update cannot be started while another keeper update is pending; finalize or cancel the pending action before starting another.
• Existing stakers retain custody of locked T. After deprecation, startUnstaking / finalizeUnstaking can complete immediately, and withdrawStake(receiver) exits the whole stake in one call.

Tests

• npm run build
• npm run test -- --grep "RebateStaking"
• npm run test -- --grep "Bridge - Peg keeper"
• npm run test -- ./test/bridge/Bridge.RebateRecovery.test.ts
• npm run test -- ./test/bridge/Bridge.PegKeeper.test.ts ./test/bridge/Bridge.Deposit.test.ts ./test/bridge/Bridge.Redemption.test.ts ./test/bridge/Bridge.Governance.test.ts
• npm run test -- ./test/cross-chain/wormhole/L1BTCDepositorWormhole.test.ts
• npm exec eslint -- test/bridge/Bridge.PegKeeper.test.ts
• npm exec eslint -- test/bridge/Bridge.PegKeeper.test.ts test/bridge/RebateStaking.test.ts
• npm run lint:sol -- contracts/bridge/Bridge.sol contracts/bridge/BridgeGovernance.sol contracts/bridge/BridgeGovernanceParameters.sol contracts/bridge/BridgeState.sol contracts/bridge/Deposit.sol contracts/bridge/Redemption.sol
• npm run lint:sol -- contracts/bridge/RebateStaking.sol contracts/bridge/Bridge.sol contracts/bridge/BridgeGovernance.sol contracts/bridge/BridgeGovernanceParameters.sol contracts/bridge/BridgeState.sol contracts/bridge/Deposit.sol contracts/bridge/Redemption.sol

Notes

• Solidity lint exits with warnings only, matching existing repo-wide lint noise.
• Bridge compiles at 24.454 KB after the review fixes; upgrade-only V2/V5 initializer guards intentionally omit revert strings to preserve size headroom.
• BridgeGovernanceParameters.cancelPegKeeperUpdate is internal so the new cancel path does not add another external library link reference to BridgeGovernance; this avoids the OpenZeppelin validation-cache bytecode failure seen in L1BTCDepositorWormhole CI.
• Left the keeper mapping gas read and inline assembly admin-slot guard as accepted low-severity tradeoffs to avoid more storage/design churn and preserve Bridge size headroom.
• Draft implementation for protocol-as-arbitrageur / peg-keeper review.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 397f7277-799e-4d32-897b-bb1ad1952bce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/protocol-peg-keeper

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}