IPIDController

Git Source

Inherits: IAuthorizable, IModifiable

Functions

seedProposer

Returns the address allowed to call computeRate method

function seedProposer() external view returns (address _seedProposer);

params

Getter for the contract parameters struct

function params() external view returns (PIDControllerParams memory _pidParams);

Returns

NameTypeDescription
_pidParamsPIDControllerParamsThe PID controller parameters struct

_params

Getter for the unpacked contract parameters struct

function _params()
  external
  view
  returns (
    uint256 _integralPeriodSize,
    uint256 _perSecondCumulativeLeak,
    uint256 _noiseBarrier,
    uint256 _feedbackOutputUpperBound,
    int256 _feedbackOutputLowerBound
  );

Returns

NameTypeDescription
_integralPeriodSizeuint256The minimum delay between two computeRate calls
_perSecondCumulativeLeakuint256The per second leak applied to priceDeviationCumulative before the latest deviation is added [ray]
_noiseBarrieruint256The minimum percentage deviation from the redemption price that allows the contract to calculate a non null redemption rate [wad]
_feedbackOutputUpperBounduint256The maximum value allowed for the redemption rate [ray]
_feedbackOutputLowerBoundint256The minimum value allowed for the redemption rate [ray]

deviationObservation

Returns the last deviation observation, containing latest timestamp, proportional and integral terms

function deviationObservation() external view returns (DeviationObservation memory __deviationObservation);

Returns

NameTypeDescription
__deviationObservationDeviationObservationThe last deviation observation struct

_deviationObservation

Raw data about the last deviation observation

function _deviationObservation() external view returns (uint256 _timestamp, int256 _proportional, int256 _integral);

Returns

NameTypeDescription
_timestampuint256The timestamp when this observation was stored
_proportionalint256The proportional term stored in this observation
_integralint256The integral term stored in this observation

controllerGains

Returns the Kp and Ki values used in this calculator

The values are expressed in WAD, Kp stands for proportional and Ki for integral terms

function controllerGains() external view returns (ControllerGains memory _cGains);

_controllerGains

Raw data about the Kp and Ki values used in this calculator

function _controllerGains() external view returns (int256 _kp, int256 _ki);

Returns

NameTypeDescription
_kpint256This value is multiplied with the proportional term
_kiint256This value is multiplied with priceDeviationCumulative

getBoundedRedemptionRate

Return a redemption rate bounded by feedbackOutputLowerBound and feedbackOutputUpperBound as well as the timeline over which that rate will take effect

function getBoundedRedemptionRate(int256 _piOutput) external view returns (uint256 _redemptionRate);

Parameters

NameTypeDescription
_piOutputint256The raw redemption rate computed from the proportional and integral terms

Returns

NameTypeDescription
_redemptionRateuint256The bounded redemption rate

computeRate

Compute a new redemption rate

function computeRate(uint256 _marketPrice, uint256 _redemptionPrice) external returns (uint256 _redemptionRate);

Parameters

NameTypeDescription
_marketPriceuint256The system coin market price
_redemptionPriceuint256The system coin redemption price

Returns

NameTypeDescription
_redemptionRateuint256The computed redemption rate

getGainAdjustedPIOutput

Apply Kp to the proportional term and Ki to the integral term (by multiplication) and then sum P and I

function getGainAdjustedPIOutput(
  int256 _proportionalTerm,
  int256 _integralTerm
) external view returns (int256 _piOutput);

Parameters

NameTypeDescription
_proportionalTermint256The proportional term
_integralTermint256The integral term

Returns

NameTypeDescription
_piOutputint256The sum of P and I

getGainAdjustedTerms

Independently return and calculate P * Kp and I * Ki

function getGainAdjustedTerms(
  int256 _proportionalTerm,
  int256 _integralTerm
) external view returns (int256 _proportionalGain, int256 _integralGain);

Parameters

NameTypeDescription
_proportionalTermint256The proportional term
_integralTermint256The integral term

Returns

NameTypeDescription
_proportionalGainint256The proportional gain
_integralGainint256The integral gain

getNextDeviationCumulative

Compute a new priceDeviationCumulative (integral term)

function getNextDeviationCumulative(
  int256 _proportionalTerm,
  uint256 _accumulatedLeak
) external returns (int256 _priceDeviationCumulative, int256 _timeAdjustedDeviation);

Parameters

NameTypeDescription
_proportionalTermint256The proportional term (redemptionPrice - marketPrice)
_accumulatedLeakuint256The total leak applied to priceDeviationCumulative before it is summed with the new time adjusted deviation

Returns

NameTypeDescription
_priceDeviationCumulativeint256The new priceDeviationCumulative
_timeAdjustedDeviationint256The new time adjusted deviation

breaksNoiseBarrier

Returns whether the P + I sum exceeds the noise barrier

function breaksNoiseBarrier(uint256 _piSum, uint256 _redemptionPrice) external view returns (bool _breaksNb);

Parameters

NameTypeDescription
_piSumuint256Represents a sum between P + I
_redemptionPriceuint256The system coin redemption price

Returns

NameTypeDescription
_breaksNbboolWhether the P + I sum exceeds the noise barrier

getNextRedemptionRate

Compute and return the upcoming redemption rate

function getNextRedemptionRate(
  uint256 _marketPrice,
  uint256 _redemptionPrice,
  uint256 _accumulatedLeak
) external view returns (uint256 _redemptionRate, int256 _proportionalTerm, int256 _integralTerm);

Parameters

NameTypeDescription
_marketPriceuint256The system coin market price
_redemptionPriceuint256The system coin redemption price
_accumulatedLeakuint256The total leak applied to priceDeviationCumulative before it is summed with the proportionalTerm

Returns

NameTypeDescription
_redemptionRateuint256The upcoming redemption rate
_proportionalTermint256The upcoming proportional term
_integralTermint256The upcoming integral term

timeSinceLastUpdate

Returns the time elapsed since the last computeRate call

function timeSinceLastUpdate() external view returns (uint256 _timeSinceLastValue);

Events

UpdateDeviation

Emitted when the state of the controller is updated

event UpdateDeviation(int256 _proportionalDeviation, int256 _integralDeviation, int256 _deltaIntegralDeviation);

Parameters

NameTypeDescription
_proportionalDeviationint256The new proportional term
_integralDeviationint256The new integral term
_deltaIntegralDeviationint256The delta between the new and the previous integral term

Errors

PIDController_OnlySeedProposer

Throws if the caller of updateRate is not the seed proposer

error PIDController_OnlySeedProposer();

PIDController_ComputeRateCooldown

Throws if the call to updateRate is too soon since last update

error PIDController_ComputeRateCooldown();

PIDController_CannotSetPriceDeviationCumulative

Throws when trying to set the integral term with the integral gain set on

error PIDController_CannotSetPriceDeviationCumulative();

Structs

PIDControllerParams

struct PIDControllerParams {
  uint256 integralPeriodSize;
  uint256 perSecondCumulativeLeak;
  uint256 noiseBarrier;
  uint256 feedbackOutputUpperBound;
  int256 feedbackOutputLowerBound;
}

DeviationObservation

struct DeviationObservation {
  uint256 timestamp;
  int256 proportional;
  int256 integral;
}

ControllerGains

struct ControllerGains {
  int256 kp;
  int256 ki;
}