RulesEngineProcessorFacet - Forte Rules Engine

Inherits: [FacetCommonImports](/v2(/v2/reference/engine/facets/FacetCommonImports.sol/abstract.FacetCommonImports)

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

initialize

Initializes the Rules Engine with the specified owner.

This function sets the initial owner of the diamond and ensures the contract is only initialized once.

function initialize(address _owner) external;

Parameters

Name	Type	Description
`_owner`	`address`	The initial owner of the diamond.

checkPolicies

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

Primary entry point for policy checks.

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

Parameters

Name	Type	Description
`contractAddress`	`address`	The address of the rules-enabled contract, used to pull the applicable rules.
`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

_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.

_loadApplicableRules

Loads applicable rules for a given function signature.

function _loadApplicableRules(
    mapping(uint256 ruleId => RuleStorageSet) storage ruleData,
    Policy storage policy,
    bytes4 functionSignature
) 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.
`functionSignature`	`bytes4`	The function signature to match rules against.

Returns

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

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 functionSignatureArgs
) 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.
`functionSignatureArgs`	`bytes`	The arguments for the function signature.

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 functionSignatureArgs)
    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.
`functionSignatureArgs`	`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 functionSignatureArgs, 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.
`functionSignatureArgs`	`bytes`	The calldata containing the arguments for the function signature.
`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.

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 functionSignatureArgs, uint256 foreignCallIndex)
    public
    returns (ForeignCallReturnValue memory returnValue);

Parameters

Name	Type	Description
`_policyId`	`uint256`	Id of the policy.
`functionSignatureArgs`	`bytes`	representation of the function signature arguments
`foreignCallIndex`	`uint256`	Index of the foreign call.

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)
    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)

Returns

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

_doEffects

Internal function to process the effects of a rule.

function _doEffects(
    Rule storage rule,
    uint256 _policyId,
    Effect[] memory _effects,
    bytes calldata functionSignatureArgs
) 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.
`functionSignatureArgs`	`bytes`	Encoded calldata containing arguments for the function signature.

_buildEvent

Define event to be fired

function _buildEvent(
    Rule storage rule,
    bool isDynamicParam,
    uint256 _policyId,
    bytes32 _message,
    Effect memory effectStruct,
    bytes calldata functionSignatureArgs
) 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
`functionSignatureArgs`	`bytes`	calling function signature arguments

_fireDynamicEvent

Fire dynamic Event

function _fireDynamicEvent(Rule storage rule, uint256 _policyId, bytes32 _message, bytes calldata functionSignatureArgs)
    internal;

Parameters

Name	Type	Description
`rule`	`Rule`	the rule struct event is associated to
`_policyId`	`uint256`	policy Id
`_message`	`bytes32`	Event Message String
`functionSignatureArgs`	`bytes`	calling function signature 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.

_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.

_evaluateExpression

Evaluate an effect expression

function _evaluateExpression(
    Rule storage rule,
    uint256 _policyId,
    bytes calldata functionSignatureArgs,
    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
`functionSignatureArgs`	`bytes`	arguments of the function signature
`instructionSet`	`uint256[]`	instruction set

ui2bool

converts a uint256 to a bool

function ui2bool(uint256 x) public pure returns (bool ans);

Parameters

Name	Type	Description
`x`	`uint256`	the uint256 to convert

bool2ui

converts a bool to an uint256

function bool2ui(bool x) public pure returns (uint256 ans);

Parameters

Name	Type	Description
`x`	`bool`	the bool to convert

ui2addr

converts a uint256 to an address

function ui2addr(uint256 x) public pure returns (address ans);

Parameters

Name	Type	Description
`x`	`uint256`	the uint256 to convert

ui2bytes

converts a uint256 to a bytes

function ui2bytes(uint256 x) public pure returns (bytes memory ans);

Parameters

Name	Type	Description
`x`	`uint256`	the uint256 to convert

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) public 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.

retrieveRawStringFromInstructionSet

Retrieves the raw string associated with a specific instruction set within a rule and policy.

This function is used to fetch a StringVerificationStruct containing the raw string data.

function retrieveRawStringFromInstructionSet(uint256 _policyId, uint256 _ruleId, uint256 instructionSetId)
    public
    view
    returns (StringVerificationStruct memory retVal);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy containing the rule.
`_ruleId`	`uint256`	The ID of the rule containing the instruction set.
`instructionSetId`	`uint256`	The ID of the instruction set to retrieve the raw string from.

Returns

Name	Type	Description
`retVal`	`StringVerificationStruct`	A `StringVerificationStruct` containing the raw string data for the specified instruction set.

retrieveRawAddressFromInstructionSet

Retrieves the raw address from a specific instruction set.

This function is used to fetch the raw address associated with a given policy ID, rule ID, and instruction set ID.

function retrieveRawAddressFromInstructionSet(uint256 _policyId, uint256 _ruleId, uint256 instructionSetId)
    public
    view
    returns (AddressVerificationStruct memory retVal);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to which the rule belongs.
`_ruleId`	`uint256`	The ID of the rule within the policy.
`instructionSetId`	`uint256`	The ID of the instruction set to retrieve the address verification structure from.

Returns

Name	Type	Description
`retVal`	`AddressVerificationStruct`	The AddressVerificationStruct containing the raw address data.

_retreiveRawEncodedFromInstructionSet

Retrieves the raw encoded data and instruction set value from a given instruction set ID.

function _retreiveRawEncodedFromInstructionSet(uint256 _policyId, uint256 _ruleId, uint256 instructionSetId, PT pType)
    internal
    view
    returns (uint256 instructionSetValue, bytes memory encoded);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy associated with the instruction set.
`_ruleId`	`uint256`	The ID of the rule associated with the instruction set.
`instructionSetId`	`uint256`	The ID of the instruction set to retrieve data from.
`pType`	`PT`	The parameter type (PT) associated with the instruction set.

Returns

Name	Type	Description
`instructionSetValue`	`uint256`	The value of the instruction set.
`encoded`	`bytes`	The raw encoded data associated with the instruction set.

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
) public 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

​initialize

​checkPolicies

​_checkPolicy

​_loadApplicableRules

​evaluateRulesAndExecuteEffects

​_evaluateIndividualRule

​_buildArguments

​_run

​_updateTrackerValue

​_updateTrackerValue

​evaluateForeignCalls

​evaluateForeignCallForRule

​_doEffects

​_buildEvent

​_fireDynamicEvent

​_fireEvent

​_doRevert

​_evaluateExpression

​ui2bool

​bool2ui

​ui2addr

​ui2bytes

​getDynamicVariableFromCalldata

​retrieveRawStringFromInstructionSet

​retrieveRawAddressFromInstructionSet

​_retreiveRawEncodedFromInstructionSet

​getDynamicValueArrayData

Functions

initialize

checkPolicies

_checkPolicy

_loadApplicableRules

evaluateRulesAndExecuteEffects

_evaluateIndividualRule

_buildArguments

_run

_updateTrackerValue

_updateTrackerValue

evaluateForeignCalls

evaluateForeignCallForRule

_doEffects

_buildEvent

_fireDynamicEvent

_fireEvent

_doRevert

_evaluateExpression

ui2bool

bool2ui

ui2addr

ui2bytes

getDynamicVariableFromCalldata

retrieveRawStringFromInstructionSet

retrieveRawAddressFromInstructionSet

_retreiveRawEncodedFromInstructionSet

getDynamicValueArrayData