Interest Model

Interest Model Contract Address: inj1ftech0pdjrjawltgejlmpx57cyhsz6frdx2dhq

The Interest Model Contract is a core component of the Neptune protocol. It is responsible for managing and computing the interest rates applied to borrowing assets. Using a configurable PID controller, the contract accrues and updates per-asset interest parameters based on market utilization and other metrics. This data is then used by the Market contract to properly adjust borrowing and lending rates.

Query Messages

1. Get Borrow Rate

Query: get_borrow_rate

Purpose: Retrieves the current borrow rate for a specified asset.

Query Input:

{
  "get_borrow_rate": {
    "asset": {
      "native_token": { "denom": "inj" }
    }
  }
}

Parameter	Type	Description	Required
asset	object	The asset for which the borrow rate is queried	Yes
asset. native_token	object	The token type for the target token	Yes
asset. native_token. denom	string	The denomination of the native token	Yes

Query Response:

"0.032602136599636308"

Parameter	Type	Description
rate	decimal256	The computed borrow rate with 18 decimal precision

---

2. Get Borrow Rates

Query: get_borrow_rates

Purpose: Retrieves borrow rates for multiple assets.

Query Input:

{
  "get_borrow_rates": {
    "assets": [
      { "native_token": { "denom": "inj" } },
      { "native_token": { "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9" } }
    ]
  }
}

Parameter	Type	Description	Required
assets	array	List of assets for which to fetch rates	Yes
assets. native_token	object	Target token type	Yes
assets. native_token. denom	string	The denomination of the native token for each asset	Yes

Query Response:

[
  [
    {
      "native_token": {
        "denom": "inj"
      }
    },
    "0.032602136599636308"
  ],
  [
    {
      "native_token": {
        "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
      }
    },
    "0.028516145899841711"
  ]
]

Parameter	Type	Description
native_token	object	Token type
native_token.denom	string	The denomination of the native token
rate	deciaml256	The computed borrow rate with 18 decimal precision

---

3. Get All Borrow Rates

Query: get_all_borrow_rates

Purpose: Retrieves borrow rates for all assets with optional pagination.

Query Input:

{
  "get_all_borrow_rates": {
    "start_after": {
      "native_token": { "denom": "inj" }
    },
    "limit": 2
  }
}

Parameter	Type	Description	Required
start_after	object	Object containing information of the token to start after	No
start_after. native_token	object	Token type	Yes
start_after. native_token. denom	string	Denomination of native token	Yes
limit	u64	Number of responses to return	No

Query Response:

[
  [
    {
      "native_token": {
        "denom": "peggy0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    },
    "0.024581462271495318"
  ],
  [
    {
      "native_token": {
        "denom": "peggy0xdAC17F958D2ee523a2206206994597C13D831ec7"
      }
    },
    "0.122192747997619433"
  ]
]

Parameter	Type	Description
native_token	object	Token type
native_token.denom	string	The denomination of the native token
rate	string	The computed borrow rate with 18 decimal precision

---

4. Get All Lending Rates

Query: get_all_lending_rates

Purpose: Retrieves lending rates for all assets with optional pagination.

Query Input:

{
  "get_all_lending_rates": {
    "start_after": {
      "native_token": { "denom": "inj" }
    },
    "limit": 2
  }
}

Parameter	Type	Description	Required
start_after	object	Object containing information of the token to start after	No
start_after. native_token	object	Token type	Yes
start_after. native_token. denom	string	Denomination of native token	Yes
limit	u64	Number of responses to return	No

Query Response:

[
  [
    {
      "native_token": {
        "denom": "peggy0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    },
    "0.008849338568075437"
  ],
  [
    {
      "native_token": {
        "denom": "peggy0xdAC17F958D2ee523a2206206994597C13D831ec7"
      }
    },
    "0.088057634299353907"
  ]
]

Parameter	Type	Description
native_token	object	Token type
native_token.denom	string	The denomination of the native token
rate	string	The computed lending rate with 18 decimal precision

---

6. Get All Assets

Query: get_all_assets

Purpose: Retrieves detailed interest model information (i.e., both the asset state and its parameters) for all assets with optional pagination.

Query Input:

{
  "get_all_assets": {
    "start_after": {
      "native_token": { "denom": "inj" }
    },
    "limit": 1
  }
}

Parameter	Type	Description	Required
start_after	object	Object containing information of the token to start after	No
start_after. native_token	object	Token type	Yes
start_after. native_token. denom	string	Denomination of native token	Yes
limit	u64	Number of responses to return	No

Query Response:

[
  [
    {
      "native_token": {
        "denom": "peggy0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    },
    {
      "state": {
        "time_last_updated": "1740431284262579521",
        "last_utilization_accumulator": "17044762049054025.396573887122519963",
        "last_control_output": "0.33",
        "pid_state": {
          "prev_measurement": "0.60686996262975328",
          "integral_term": "0.33"
        }
      },
      "params": {
        "pid_params": {
          "kp": "0",
          "ki": "-0.1",
          "kd": "-0.1",
          "upper_p_limit": "0",
          "lower_p_limit": "0",
          "upper_i_limit": "3",
          "lower_i_limit": "0.33",
          "upper_d_limit": "1",
          "lower_d_limit": "-1",
          "upper_output_limit": "3",
          "lower_output_limit": "0.33",
          "setpoint": "0.65"
        },
        "sample_period_min_nanos": 18000000000000,
        "sample_period_max_nanos": 28800000000000,
        "curve": {
          "polynomial": [
            [
              1,
              "0.03"
            ],
            [
              6,
              "0.47"
            ],
            [
              12,
              "1"
            ]
          ]
        }
      }
    }
  ]
]

Parameter	Type	Description
native_token	object	Contains details about the native token
native_token. denom	string	The denomination identifier of the native token
state	object	Contains the state details of the asset
state. time_last_updated	string	Timestamp of the last update in nanoseconds
state. last_utilization_accumulator	string	Accumulated utilization value
state. last_control_output	string	Last computed control output for interest calculations
state. pid_state	object	Contains PID controller state values
state.pid_state. prev_measurement	string	Previous measurement value
state.pid_state. integral_term	string	Integral term for PID computation
params	object	Contains interest model parameters
params. pid_params	object	PID controller parameters for interest rate adjustments
params.pid_params. kp	string	Proportional gain of the PID controller
params.pid_params. ki	string	Integral gain of the PID controller
params.pid_params. kd	string	Derivative gain of the PID controller
params.pid_params. upper_p_limit	string	Upper limit for the proportional component
params.pid_params. lower_p_limit	string	Lower limit for the proportional component
params.pid_params. upper_i_limit	string	Upper limit for the integral component
params.pid_params. lower_i_limit	string	Lower limit for the integral component
params.pid_params. upper_d_limit	string	Upper limit for the derivative component
params.pid_params. lower_d_limit	string	Lower limit for the derivative component
params.pid_params. upper_output_limit	string	Maximum allowed output from the PID controller
params.pid_params. lower_output_limit	string	Minimum allowed output from the PID controller
params.pid_params. setpoint	string	Target setpoint value for the PID controller
params. sample_period_min_nanos	u64	Minimum time interval for sampling in nanoseconds
params. sample_period_max_nanos	u64	Maximum time interval for sampling in nanoseconds
params. curve	object	Polynomial curve defining interest rate adjustments
params.curve. polynomial	array	List of exponent-coefficient pairs defining the curve

---

Execute Messages

1. Add Asset

Execute: add_asset

Purpose: Adds a new asset to the Interest Model. This initializes the asset's interest state with the current block time, an initial control output, and an integral term. It also stores the provided (unvalidated) interest parameters.

NOTE: Only whitelisted addresses can execute add_asset

Execute Input:

{
  "add_asset": {
    "asset": {
      "native_token": {
        "denom": "factory/inj1n636d9gzrqggdk66n2f97th0x8yuhfrtx520e7/ausd"
      }
    },
    "integral_term": "1",
    "last_control_output": "1",
    "params": {
      "curve": {
        "polynomial": [
          [1, "0.15"],
          [20, "1.46"]
        ]
      },
      "pid_params": {
        "kd": "-0.15",
        "ki": "-0.1",
        "kp": "0",
        "lower_d_limit": "-1",
        "lower_i_limit": "0.33",
        "lower_output_limit": "0.33",
        "lower_p_limit": "0",
        "setpoint": "0.8",
        "upper_d_limit": "1",
        "upper_i_limit": "3",
        "upper_output_limit": "3",
        "upper_p_limit": "0"
      },
      "sample_period_max_nanos": 28800000000000,
      "sample_period_min_nanos": 18000000000000
    }
  }
}

Parameter	Type	Description	Required
asset	object	The asset to be added to the interest model	Yes
asset. native_token	object	The token type for the target token	Yes
asset. native_token. denom	string	The denomination of the native token	Yes
integral_term	string	Initial value for the integral term of the PID controller	Yes
last_control_output	string	Initial value for the control output	Yes
params	object	The interest model parameters for the asset	Yes
params. curve	object	The polynomial curve defining interest rate adjustments	Yes
params. curve. polynomial	array	List of exponent-coefficient pairs defining the curve	Yes
params. pid_params	object	PID controller parameters for interest rate adjustments	Yes
params. pid_params. kp	string	Proportional gain of the PID controller	Yes
params. pid_params. ki	string	Integral gain of the PID controller	Yes
params. pid_params. kd	string	Derivative gain of the PID controller	Yes
params. pid_params. upper_p_limit	string	Upper limit for the proportional component	Yes
params. pid_params. lower_p_limit	string	Lower limit for the proportional component	Yes
params. pid_params. upper_i_limit	string	Upper limit for the integral component	Yes
params. pid_params. lower_i_limit	string	Lower limit for the integral component	Yes
params. pid_params. upper_d_limit	string	Upper limit for the derivative component	Yes
params. pid_params. lower_d_limit	string	Lower limit for the derivative component	Yes
params. pid_params. upper_output_limit	string	Maximum allowed output from the PID controller	Yes
params. pid_params. lower_output_limit	string	Minimum allowed output from the PID controller	Yes
params. pid_params. setpoint	string	Target setpoint value for the PID controller	Yes
params. sample_period_min_nanos	u64	Minimum time interval for sampling in nanoseconds	Yes
params. sample_period_max_nanos	u64	Maximum time interval for sampling in nanoseconds	Yes

---

2. Update Asset

Execute: update_asset

Purpose: Updates the interest model parameters for an existing asset. This allows changes to the PID parameters, sample period, or polynomial curve based on current market conditions.

NOTE: Only whitelisted addresses can execute update_asset

Execute Input:

{
  "update_asset": {
    "asset": {
      "native_token": {
        "denom": "inj"
      }
    },
    "params": {
      "curve": {
        "polynomial": [
          [1, "0.04"],
          [20, "1.0"]
        ]
      },
      "pid_params": {
        "kd": "-0.15",
        "ki": "-0.1",
        "kp": "0",
        "lower_d_limit": "-1",
        "lower_i_limit": "0.33",
        "lower_output_limit": "0.33",
        "lower_p_limit": "0",
        "setpoint": "0.8",
        "upper_d_limit": "1",
        "upper_i_limit": "3",
        "upper_output_limit": "3",
        "upper_p_limit": "0"
      },
      "sample_period_max_nanos": 28800000000000,
      "sample_period_min_nanos": 18000000000000
    }
  }
}

Parameter	Type	Description	Required
asset	object	The asset for which to update interest model parameters	Yes
asset. native_token	object	The token type for the target token	Yes
asset. native_token. denom	string	The denomination of the native token	Yes
params	object	The updated interest model parameters	Yes
params. curve	object	The polynomial curve defining interest rate adjustments	Yes
params. curve. polynomial	array	List of exponent-coefficient pairs defining the curve	Yes
params. pid_params	object	PID controller parameters for interest rate adjustments	Yes
params. pid_params. kp	string	Proportional gain of the PID controller	Yes
params. pid_params. ki	string	Integral gain of the PID controller	Yes
params. pid_params. kd	string	Derivative gain of the PID controller	Yes
params. pid_params. upper_p_limit	string	Upper limit for the proportional component	Yes
params. pid_params. lower_p_limit	string	Lower limit for the proportional component	Yes
params. pid_params. upper_i_limit	string	Upper limit for the integral component	Yes
params. pid_params. lower_i_limit	string	Lower limit for the integral component	Yes
params. pid_params. upper_d_limit	string	Upper limit for the derivative component	Yes
params. pid_params. lower_d_limit	string	Lower limit for the derivative component	Yes
params. pid_params. upper_output_limit	string	Maximum allowed output from the PID controller	Yes
params. pid_params. lower_output_limit	string	Minimum allowed output from the PID controller	Yes
params. pid_params. setpoint	string	Target setpoint value for the PID controller	Yes
params. sample_period_min_nanos	u64	Minimum time interval for sampling in nanoseconds	Yes
params. sample_period_max_nanos	u64	Maximum time interval for sampling in nanoseconds	Yes

3. Next Control Outputs

Execute: next_control_outputs

Purpose: Used to calculate the next control output values for all assets using the PID controller. This is part of the interest rate model's dynamic adjustment mechanism.

NOTE: Only whitelisted addresses can execute next_control_outputs

Execute Input:

{
  "next_control_outputs": {
    "assets": [
      {
        "native_token": {
          "denom": "inj"
        }
      },
      {
        "native_token": {
          "denom": "factory/inj1n636d9gzrqggdk66n2f97th0x8yuhfrtx520e7/ausd"
        }
      }
    ]
  }
}

Parameter	Type	Description	Required
assets	array	List of assets for which control outputs are to be computed	Yes
assets. native_token	object	Token type for target token to update	Yes
assets. native_token. denom	string	The denomination identifier for the native token	Yes