Protocol Risk Score Structure

​

Purpose

Application developers may wish to assign risk scores to addresses that they determine have a higher potential for behavior that is detrimental to their economy. These scores can range from 0-99. Risk administrators are the only admins that can assign risk scores to addresses.

Rule administrators can add and activate RISK-RULES via the application handler contract. These rules are applied at the application level, meaning all assets within the application will be subjected to these rules.

​

Scope

Risk scores can be applied to individual accounts or addresses of contracts. Risk scores are used to facilitate risk rule checks throughout the protocol. When an account (user) is given a risk score, they will be subject to any risk rules that are active. When a risk rule is added and activated every user with a risk score will be subjected to this risk rule. This means if the Account Max Tx Value by Risk Score is active and a has the following rule values:

riskLevel = [25, 50, 75];
maxSize = [500, 250, 50];

The max values per period will be as follows:

see RISK-RULES

​

Data Structure

Risk scores are a uint8 value stored in a mapping inside the RiskScores data contract.

///     address   => riskScore
mapping(address => uint8) public scores;

see RiskScores

​

Enabling/Disabling

• Risk scores can only be added in the app manager by an risk administrator.
• Risk scores can only be removed in the app manager by an risk administrator.

​

Revert Messages

The transaction will revert with the following error if the risk score assigned is out of range when assigning risck scores:

error riskScoreOutOfRange();

The selector for this error is 0xb3cbc6f3.

​

Add Functions

Adding a risk score is done through the function:

function addRiskScore(address _account, uint8 _score) external onlyRole(RISK_ADMIN_ROLE);

Adding multiple risk scores to a single account or address is done through the function:

function addRiskScoreToMultipleAccounts(address[] memory _accounts, uint8 _score) external onlyRole(RISK_ADMIN_ROLE);

Adding multiple risk scores to multiple addresses is done through the function:

function addMultipleRiskScores(address[] memory _accounts, uint8[] memory _scores) external onlyRole(RISK_ADMIN_ROLE);

​

Remove Function

Removing a risk score from an address is done through the function:

function removeRiskScore(address _account) external onlyRole(RISK_ADMIN_ROLE);

see App Manager

​

Parameters:

• _score (uint8): risk score for an account.
• _scores (uint8): array of risk scores for an account.
• _account (address): address of the account for the risk score
• _accounts (address[]): array of addresses to for the risk scores

​

Parameter Optionality:

There are no options for the parameters for the add functions.

​

Parameter Validation:

The following validation will be carried out by the addRiskScore function in order to ensure that these parameters are valid and make sense:

• _score is within the 0-99 score range.
• _account is not the zero address.

see RiskScores

​

Other Functions:

• In App Manager:
  • Function to check the score of an address:

    function getRiskScore(address _account) external view virtual returns (uint8);
    

  • Function to deploy new data contracts:

    function deployDataContracts() private;
    

  • Function to retrieve risk scores data contract address:

    function getRiskDataAddress() external view returns (address);
    

  • Function to propose data contract migration to new handler:

    function proposeDataContractMigration(address _newOwner) external  onlyRole(APP_ADMIN_ROLE);
    

  • Function to confirm migration of data contracts to new handler:

    function confirmDataContractMigration(address _oldHandlerAddress) external  onlyRole(APP_ADMIN_ROLE);
    

​

Events

• AD1467_RiskScoreAdded(address indexed _address, uint8 _score): emitted when:
  • A risk score has been added.
• AD1467_RiskScoreRemoved(address indexed _address): emitted when:
  • A risk score is removed.
• AD1467_RiskProviderSet(address indexed _address): emitted when:
  • A risk score data contract has been migrated to the app manager address