RulesEngineProcessorFacet - Forte Rules Engine

Author: @mpetersoCode55, @ShaneDuncan602, @TJ-Everett, @VoR0220

This contract is a critical component of the Rules Engine, enabling secure and flexible rule evaluation and effect execution.

This contract serves as the core processor for evaluating rules and executing effects in the Rules Engine. It provides functionality for evaluating policies, rules, and conditions, as well as executing effects based on rule outcomes. The contract also supports foreign calls, dynamic argument handling, and tracker updates.

Functions

checkPolicies

Evaluates the conditions associated with all applicable rules and returns the result.

Primary entry point for policy checks.

function checkPolicies(bytes calldata arguments) public returns (uint256 retVal);

Parameters

Name	Type	Description
`arguments`	`bytes`	Function arguments, including the function signature and the arguments to be passed to the function.

Returns

Name	Type	Description
`retVal`	`uint256`	1 if all rules pass, 0 if any rule fails. TODO: refine the parameters to this function. contractAddress is not necessary as it’s the message caller

evaluateForeignCalls

Evaluates foreign calls within the rules engine processor.

This function processes and evaluates calls to external contracts or systems as part of the rules engine’s logic. Ensure that the necessary validations and security checks are in place when interacting with foreign calls.

function evaluateForeignCalls(
    uint256 policyId,
    bytes calldata callingFunctionArgs,
    uint256 foreignCallIndex,
    bytes[] memory retVals
) public returns (ForeignCallReturnValue memory returnValue);

Parameters

Name	Type	Description
`policyId`	`uint256`	Id of the policy.
`callingFunctionArgs`	`bytes`	representation of the calling function arguments
`foreignCallIndex`	`uint256`	Index of the foreign call.
`retVals`	`bytes[]`	array of return values from previous foreign calls, trackers, etc.

Returns

Name	Type	Description
`returnValue`	`ForeignCallReturnValue`	The output of the foreign call.

evaluateForeignCallForRule

encodes the arguments and places a foreign call, returning the calls return value as long as it is successful

function evaluateForeignCallForRule(ForeignCall memory fc, bytes calldata functionArguments, bytes[] memory retVals)
    public
    returns (ForeignCallReturnValue memory retVal);

Parameters

Name	Type	Description
`fc`	`ForeignCall`	the Foreign Call structure
`functionArguments`	`bytes`	the arguments of the rules calling function (to be passed to the foreign call as needed)
`retVals`	`bytes[]`

Returns

Name	Type	Description
`retVal`	`ForeignCallReturnValue`	the foreign calls return value

_checkPolicy

Checks a specific policy for compliance.

function _checkPolicy(uint256 _policyId, address _contractAddress, bytes calldata _arguments)
    internal
    returns (bool retVal);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to check.
`_contractAddress`	`address`	The address of the contract being evaluated.
`_arguments`	`bytes`	Function arguments for the policy evaluation.

Returns

Name	Type	Description
`retVal`	`bool`	True if the policy passes, false otherwise.

_evaluateRulesAndExecuteEffects

Evaluates rules and executes their effects based on the evaluation results.

function _evaluateRulesAndExecuteEffects(
    mapping(uint256 ruleId => RuleStorageSet) storage _ruleData,
    uint256 _policyId,
    uint256[] memory _applicableRules,
    bytes calldata _callingFunctionArgs
) internal returns (bool _retVal);

Parameters

Name	Type	Description
`_ruleData`	`mapping(uint256 ruleId => RuleStorageSet)`	The mapping of rule IDs to rule storage sets.
`_policyId`	`uint256`	The ID of the policy being evaluated.
`_applicableRules`	`uint256[]`	An array of applicable rule IDs.
`_callingFunctionArgs`	`bytes`	The arguments for the calling function.

Returns

Name	Type	Description
`_retVal`	`bool`	True if all rules pass, false otherwise.

_evaluateIndividualRule

evaluates an individual rules condition(s)

function _evaluateIndividualRule(Rule storage _rule, uint256 _policyId, bytes calldata _callingFunctionArgs)
    internal
    returns (bool response);

Parameters

Name	Type	Description
`_rule`	`Rule`	the rule structure containing the instruction set, with placeholders, to execute
`_policyId`	`uint256`	Policy id being evaluated.
`_callingFunctionArgs`	`bytes`	the values to replace the placeholders in the instruction set with.

Returns

Name	Type	Description
`response`	`bool`	the result of the rule condition evaluation

_buildArguments

Constructs the arguments required for building the rule’s place holders.

function _buildArguments(Rule storage _rule, uint256 _policyId, bytes calldata _callingFunctionArgs, bool _effect)
    internal
    returns (bytes[] memory, Placeholder[] memory);

Parameters

Name	Type	Description
`_rule`	`Rule`	The storage reference to the Rule struct containing the rule’s details.
`_policyId`	`uint256`	The unique identifier of the policy associated with the rule.
`_callingFunctionArgs`	`bytes`	The calldata containing the arguments for the calling function.
`_effect`	`bool`	A boolean indicating whether the rule has an effect or not.

Returns

Name	Type	Description
`<none>`	`bytes[]`	A tuple containing: - An array of bytes representing the constructed arguments. - An array of Placeholder structs used for argument substitution.
`<none>`	`Placeholder[]`

_run

Internal function to decode the arguments and do the comparisons.

function _run(uint256[] memory _prog, Placeholder[] memory _placeHolders, uint256 _policyId, bytes[] memory _arguments)
    internal
    returns (bool _ans);

Parameters

Name	Type	Description
`_prog`	`uint256[]`	An array of uint256 representing the program to be executed.
`_placeHolders`	`Placeholder[]`	An array of Placeholder structs used within the program.
`_policyId`	`uint256`	The ID of the policy associated with the program execution.
`_arguments`	`bytes[]`	An array of bytes containing additional arguments for the program.

Returns

Name	Type	Description
`_ans`	`bool`	A boolean indicating the result of the program execution.

_updateTrackerValue

This function updates the tracker value with the information provided

function _updateTrackerValue(uint256 _policyId, uint256 _trackerId, uint256 _trackerValue) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	Policy id being evaluated.
`_trackerId`	`uint256`	ID of the tracker to update.
`_trackerValue`	`uint256`	Value to update within the tracker

_updateTrackerValue

Internal function to update the value of a tracker associated with a specific policy.

function _updateTrackerValue(uint256 _policyId, uint256 _trackerId, bytes memory _trackerValue) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to which the tracker belongs.
`_trackerId`	`uint256`	The ID of the tracker whose value is being updated.
`_trackerValue`	`bytes`	The new value to be assigned to the tracker, encoded as bytes.

_loadApplicableRules

Loads applicable rules for a given calling function.

function _loadApplicableRules(
    mapping(uint256 ruleId => RuleStorageSet) storage _ruleData,
    Policy storage _policy,
    bytes4 _callingFunction
) internal view returns (uint256[] memory);

Parameters

Name	Type	Description
`_ruleData`	`mapping(uint256 ruleId => RuleStorageSet)`	The mapping of rule IDs to rule storage sets.
`_policy`	`Policy`	The policy structure containing the rules.
`_callingFunction`	`bytes4`	The function signature to match rules against.

Returns

Name	Type	Description
`<none>`	`uint256[]`	An array of applicable rule IDs.

_getAbsoluteAssembly

Calculates the absolute value of a signed integer.

function _getAbsoluteAssembly(int256 _value) internal pure returns (uint256);

Parameters

Name	Type	Description
`_value`	`int256`	The signed integer value to convert to its absolute value.

Returns

Name	Type	Description
`<none>`	`uint256`	result The absolute value of the input number as an unsigned integer.

_doEffects

Internal function to process the effects of a rule.

function _doEffects(
    Rule storage _rule,
    uint256 _policyId,
    Effect[] memory _effects,
    bytes calldata _callingFunctionArgs
) internal;

Parameters

Name	Type	Description
`_rule`	`Rule`	The rule being processed, stored in the contract’s storage.
`_policyId`	`uint256`	The ID of the policy associated with the rule.
`_effects`	`Effect[]`	An array of effects to be applied as part of the rule execution.
`_callingFunctionArgs`	`bytes`	Encoded calldata containing arguments for the calling function.

_buildEvent

Define event to be fired

function _buildEvent(
    Rule storage _rule,
    bool _isDynamicParam,
    uint256 _policyId,
    bytes32 _message,
    Effect memory _effectStruct,
    bytes calldata _callingFunctionArgs
) internal;

Parameters

Name	Type	Description
`_rule`	`Rule`	the rule struct event is associated to
`_isDynamicParam`	`bool`	static or dynamic event parameters
`_policyId`	`uint256`	policy Id
`_message`	`bytes32`	Event Message String
`_effectStruct`	`Effect`	effect struct
`_callingFunctionArgs`	`bytes`	calling function arguments

_fireDynamicEvent

Fire dynamic Event

function _fireDynamicEvent(Rule storage _rule, uint256 _policyId, bytes32 _message, bytes calldata _callingFunctionArgs)
    internal;

Parameters

Name	Type	Description
`_rule`	`Rule`	the rule struct event is associated to
`_policyId`	`uint256`	policy Id
`_message`	`bytes32`	Event Message String
`_callingFunctionArgs`	`bytes`	calling function arguments

_fireEvent

Internal function to trigger an event based on the provided policy ID, message, and effect structure.

function _fireEvent(uint256 _policyId, bytes32 _message, Effect memory _effectStruct) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The unique identifier of the policy associated with the event.
`_message`	`bytes32`	A bytes32 message that provides context or details about the event.
`_effectStruct`	`Effect`	A struct containing the effect data to be processed during the event.

_evaluateExpression

Evaluate an effect expression

function _evaluateExpression(
    Rule storage _rule,
    uint256 _policyId,
    bytes calldata _callingFunctionArgs,
    uint256[] memory _instructionSet
) internal;

Parameters

Name	Type	Description
`_rule`	`Rule`	the rule structure containing the instruction set, with placeholders, to execute
`_policyId`	`uint256`	the policy id
`_callingFunctionArgs`	`bytes`	arguments of the calling function
`_instructionSet`	`uint256[]`	instruction set

_doRevert

Internal pure function to revert the transaction with a custom error message.

function _doRevert(string memory _message) internal pure;

Parameters

Name	Type	Description
`_message`	`string`	The custom error message to include in the revert.

_getDynamicVariableFromCalldata

Extracts a dynamic variable from the provided calldata at the specified index.

This function is a pure function and does not modify state.

function _getDynamicVariableFromCalldata(bytes calldata _data, uint256 _index)
    internal
    pure
    returns (bytes memory _retVal);

Parameters

Name	Type	Description
`_data`	`bytes`	The calldata containing the dynamic variables.
`_index`	`uint256`	The index of the dynamic variable to extract.

Returns

Name	Type	Description
`_retVal`	`bytes`	The extracted dynamic variable as a bytes array.

_getDynamicValueArrayData

Retrieves a portion of dynamic value array data from the provided inputs.

This function extracts a segment of dynamic data based on the specified length and offset.

function _getDynamicValueArrayData(
    bytes calldata _data,
    bytes memory _dynamicData,
    uint256 _length,
    uint256 _lengthToAppend,
    uint256 _offset
) internal pure returns (bytes memory, uint256);

Parameters

Name	Type	Description
`_data`	`bytes`	The calldata input containing the original data.
`_dynamicData`	`bytes`	The memory input containing the dynamic data to process.
`_length`	`uint256`	The total length of the dynamic data array.
`_lengthToAppend`	`uint256`	The length of data to append to the result.
`_offset`	`uint256`	The starting position in the dynamic data array to begin extraction.

Returns

Name	Type	Description
`<none>`	`bytes`	A tuple containing: - A bytes memory object representing the extracted data. - A uint256 value indicating the updated offset after extraction.
`<none>`	`uint256`

reference

​Functions

​checkPolicies

​evaluateForeignCalls

​evaluateForeignCallForRule

​_checkPolicy

​_evaluateRulesAndExecuteEffects

​_evaluateIndividualRule

​_buildArguments

​_run

​_updateTrackerValue

​_updateTrackerValue

​_loadApplicableRules

​_getAbsoluteAssembly

​_doEffects

​_buildEvent

​_fireDynamicEvent

​_fireEvent

​_evaluateExpression

​_doRevert

​_getDynamicVariableFromCalldata

​_getDynamicValueArrayData

Functions

checkPolicies

evaluateForeignCalls

evaluateForeignCallForRule

_checkPolicy

_evaluateRulesAndExecuteEffects

_evaluateIndividualRule

_buildArguments

_run

_updateTrackerValue

_updateTrackerValue

_loadApplicableRules

_getAbsoluteAssembly

_doEffects

_buildEvent

_fireDynamicEvent

_fireEvent

_evaluateExpression

_doRevert

_getDynamicVariableFromCalldata

_getDynamicValueArrayData