Sidestream EA has been asked to assist BA labs with creating a keeper for the upcoming yUSDS module. The main objective is to deliver the calculation of the values required by the keeper, as well as the update logic for the upcoming audit slot on July 28th.

:::warning
Note: this is a work-in-progress document
:::

## Background

- The [initial proposal to implement the module](https://forum.sky.money/t/sky-staking-and-yusds-further-simplifying-activation-and-sealing/26104) includes a first outline of the rate management formula
- The [formula is analysed by BA labs here](https://docs.google.com/document/d/1o5JWKH6McasUl-ECSth-GZrWu4ZOjEu2pzdrdB_FFqg/edit?tab=t.0#heading=h.6l3ugn223go9)

- The idea to implement a permissioned keeper comes from the consultation with auditors, outlined in the [yUSDS hackmd doc](https://hackmd.io/@la5trodeo/BkVXvVOblx), which also includes security-related shortcomings of this solution

## Technical requirements

The `YUsdsRateSetter.sol` contract which which the keeper will interact is currently [developed in this PR](https://github.com/sky-ecosystem/yusds/pull/3). The keeper would need to:

- Call `set` function that [accepts 4 arguments](https://github.com/sky-ecosystem/yusds/blob/b006b9d55825436b22cde50c758a12c5a96828df/src/YUsdsRateSetter.sol#L185):
- `uint256 syrBps`
- drips `yusds`
- updates `yusds.syr` ([yUSDS savings rate](https://github.com/sky-ecosystem/yusds/blob/7f03656f47c2901750eceab2795f7cf3f11d18df/src/YUsds.sol#L76C30-L76C51))
- reverts if not within `max`/`min`/`step`
- `uint256 dutyBps`
- drips `jug[ilk]`
- updates `jug.ilks(ilk).duty` ([ilk stability fee](https://github.com/sky-ecosystem/dss/blob/fa4f6630afb0624d04a003e920b0d71a00331d98/src/jug.sol#L46))
- reverts if not within `max`/`min`/`step`
- `uint256 line`
- updates `yusds.line` ([borrow max ceiling](https://github.com/sky-ecosystem/yusds/blob/7f03656f47c2901750eceab2795f7cf3f11d18df/src/YUsds.sol#L78C30-L78C48))
- reverts if more than `maxLine`
- `uint256 cap`
- updates `yusds.cap` ([supply max deposits](https://github.com/sky-ecosystem/yusds/blob/7f03656f47c2901750eceab2795f7cf3f11d18df/src/YUsds.sol#L77C30-L77C49))
- reverts if more than `maxCap`
- Take into account [9 on-chain meta-parameters](https://github.com/sky-ecosystem/yusds/blob/b006b9d55825436b22cde50c758a12c5a96828df/src/YUsdsRateSetter.sol#L42-L47):
- `syrCfg` (`min`, `max`, `step`) – acts similar to SP-BEAM, defining limits to the `syr` value that can be set via the keeper
- `dutyCfg` (`min`, `max`, `step`) – acts similar to SP-BEAM, defining limits to the `jug.ilks(ilk).duty` value that can be set via the keeper
- `maxLine` – acts as a maximum line that can be set via the keeper
- `maxCap` – acts as a maximum cap that can be set via the keeper
- `tau` – acts as cooldown period applied to any keeper calls even if they don't change anything

## Risk-specific requirements

BA labs, based on the risk assessment and the potential manipulation strategies [outlined by the auditors](https://hackmd.io/@la5trodeo/BkVXvVOblx) should provide a design specification (in a form of a document or a reference implementation) for the following components:
- `A)` a formula to determine "average utilisation"
- `B)` a formula to calculate `syrBps`, `dutyBps` rates (on which [the doc](https://docs.google.com/document/d/1o5JWKH6McasUl-ECSth-GZrWu4ZOjEu2pzdrdB_FFqg/edit?tab=t.0#heading=h.6l3ugn223go9) is mostly focused on)
- `C)` a formula to calculate `line` and `cap`
- `D)` a formula to determine if the update needs to happen (threshold-based, as proposed in the doc, but as there are 4 different parameters, it needs to be more concrete than it is now)
- `E)` A list of required off-chain meta-parameters (like the expected `threshold`) together with the proposed values

## Development roadmap

- [ ] Agree on the roadmap
- [ ] [BA labs] Provide specification of the risk-specific components (outlined above) till July 28th
- [ ] [Auditors] Review and feedback the formulas
- [ ] [Gov facilitators] Agree on the initial manual update strategy
- [ ] [Gov facilitators + Spell teams] Init the yUSDS module on-chain
- [ ] [Sidestream] Implement keeper logic using provided components
- [ ] [Techops] Run the keeper