​
Purpose

The purpose of this rule is to provide limits on the amount of tokens received from a source address for accounts at the application level based on an application defined segment of users. The segments are defined as the access levels of the accounts. This rule may be used to provide gated accumulation of assets from the source address to ensure accounts cannot accumulate more assets without performing other actions defined by the application. NOTE: access levels are restricted from 0 to 4.

​
Scope

This rule works at the application level which means that all tokens in the app will have no choice but to comply with this rule when active.

​
Data Structure

A account-max-received-by-access-level rule is composed of a single component:
  • accountMaxReceivedLimits (mapping(uint8 =>uint48)): the maximum USD worth of application assets that accounts can receive from the source address per access level.
 mapping(uint8 => uint48);
see IRuleStorage
NOTE: access levels are restricted from 0 to 4. These rules are stored in a mapping indexed by ruleId(uint32) in order of creation: 
 /// Account Max Received By Access Level
    struct AccountMaxReceivedByAccessLevelS {
        mapping(uint32 => IApplicationRules.AccountMaxReceivedByAccessLevel) accountMaxReceivedByAccessLevelRules;
        uint32 accountMaxReceivedByAccessLevelIndex; /// increments every time someone adds a rule
    }
see IRuleStorage

​
Configuration and Enabling/Disabling

  • This rule can only be configured in the protocol by a rule administrator.
  • This rule can only be set in the application handler by a rule administrator.
  • This rule can only be activated/deactivated in the application handler by a rule administrator.
  • This rule can only be updated in the application handler by a rule administrator.

​
Rule Evaluation

The rule will be evaluated with the following logic:
  1. The handler determines if the rule is active from the supplied action. If not, processing does not continue past this step.
  2. The application manager sends to the protocol’s rule processor the dollar value of application assets received from the source address, the access level of the account, the ruleId, and the dollar amount to be transferred in the transaction.
  3. The processor retrieves the maximum amount allowed for the rule with the ruleId passed, and for the access level of the account. If the transfer amount plus received exceeds the maximum allowed by the rule in the case of a successful transactions, then the transaction reverts.
  4. If it’s a non-custodial style Sell
    1. When the Buy action is also active, checks steps 1-3 for to address.
The list of available actions rules can be applied to can be found at ACTION_TYPES
see ApplicationAccessLevelProcessorFacet -> checkAccountMaxReceivedByAccessLevel

​
Evaluation Exceptions

  • This rule doesn’t apply when a treasuryAccount address is in either the from or the to side of the transaction. This doesn’t necessarily mean that if an treasury account is the one executing the transaction it will bypass the rule, unless the aforementioned condition is true.

​
Revert Message

The rule processor will revert with the following error if the rule check fails: 
error OverMaxReceivedByAccessLevel();
The selector for this error is 0x3ebf4f43.

​
Create Function

Adding a account-max-received-by-access-level rule is done through the function: 
function addAccountMaxReceivedByAccessLevel(
            address _appManagerAddr,
            uint48[] calldata _receivedAmounts
        )
        external
        ruleAdministratorOnly(_appManagerAddr)
        returns (uint32);
see AppRuleDataFacet
The add function will return the protocol ID of the rule.

​
Parameters:

  • _appManagerAddr (address): the address of the application manager to verify that the caller has rule administrator privileges.
  • _receivedAmounts (uint48[]): array of max value limits for each 5 levels (levels 0 to 4) in whole USD amounts (1 -> 1 USD; 1000 -> 1000 USD). Note that the position within the array matters. Position 0 represents access level 0, and position 4 represents level 4.

​
Parameter Optionality:

There are no options for the parameters of this rule.

​
Parameter Validation:

The following validation will be carried out by the add function in order to ensure that these parameters are valid and make sense:
  • The _receivedAmounts array has length 5.
  • The elements of the _receivedAmounts array are in ascending order.
see AppRuleDataFacet

​
Other Functions:

  • In Protocol Rule Processor:
    • Function to get a rule by its Id: 
      function getAccountMaxReceivedByAccessLevel(uint32 _index, uint8 _accessLevel) external view returns (uint48);
    • Function to get current amount of rules in the protocol: 
      function getTotalAccountMaxReceivedByAccessLevel() external view returns (uint32);
  • In Protocol Rule Processor:
    • Function that evaluates the rule: 
      function checkAccountMaxReceivedByAccessLevel(
            uint32 _ruleId,
            uint8 _accessLevel,
            uint128 _usdTotalReceived,
            address _from,
            uint128 _usdAmountTransferring
        )
        external
        view;
  • In the Application Handler:
    • Function to set and activate at the same time the rule for the supplied actions in the application handler: 
      function setAccountMaxReceivedByAccessLevelId(ActionTypes[] calldata _actions, uint32 _ruleId) external ruleAdministratorOnly(appManagerAddress);
    • Function to atomically set and activate at the same time the rule for the supplied actions in the application handler: 
      function setAccountMaxReceivedByAccessLevelIdFull(ActionTypes[] calldata _actions, uint32[] calldata _ruleIds) external ruleAdministratorOnly(appManagerAddress);
    • Function to activate/deactivate the rule for the supplied actions in the application handler: 
      function activateAccountMaxReceivedByAccessLevel(ActionTypes[] calldata _actions, bool _on) external ruleAdministratorOnly(appManagerAddress);
    • Function to know the activation state of the rule for the supplied action in an application handler: 
      function isAccountMaxReceivedByAccessLevelActive(ActionTypes _action, ) external view returns (bool);
    • Function to get the rule Id for the supplied action from the application handler: 
      function getAccountMaxReceivedByAccessLevelId(ActionTypes _action) external view returns (uint32);

​
Return Data

This rule doesn’t return any data.

​
Data Recorded

This rule doesn’t require of any data to be recorded.

​
Events

  • event AD1467_ProtocolRuleCreated(bytes32 indexed ruleType, uint32 indexed ruleId, bytes32[] extraTags):
    • Emitted when: the rule has been created in the protocol.
    • Parameters:
      • ruleType: “ACC_MAX_RECEIVED_ACCESS_LEVEL”.
      • ruleId: the index of the rule created in the protocol by rule type.
      • extraTags: empty array.
  • event AD1467_ApplicationRuleApplied(bytes32 indexed ruleType, ActionTypes action, uint32 indexed ruleId);:
    • Emitted when: rule has been applied in an application handler.
    • Parameters:
      • ruleType: “ACC_MAX_RECEIVED_ACCESS_LEVEL”.
      • action: the protocol action the rule is being applied to.
      • ruleId: the ruleId set for this rule in the handler.
  • event AD1467_ApplicationRuleAppliedFull(bytes32 indexed ruleType, ActionTypes[] actions, uint32[] ruleIds);:
    • Emitted when: rule has been applied in an application manager handler.
    • Parameters:
      • ruleType: “ACC_MAX_RECEIVED_ACCESS_LEVEL”.
      • actions: the protocol actions the rule is being applied to.
      • ruleIds: the ruleIds set for each action on this rule in the handler.

​
Dependencies

This rule depends on:
  • Pricing contracts: pricing contracts for ERC20s and ERC721s need to be setup in the application handler in order for this rule to work.