RulesEngineRuleFacet

Git Source Inherits: FacetCommonImports Author: @mpetersoCode55, @ShaneDuncan602, @TJ-Everett, @VoR0220 This contract is a critical component of the Rules Engine, enabling secure and flexible policy management. This contract serves as the primary data facet for the Rules Engine rules. It is responsible for creating, updating, retrieving, and managing rules. It enforces role-based access control and ensures that only authorized users can modify or retrieve data. The contract also supports policy cementing to prevent further modifications.

Functions

createRule

Creates a rule in storage. Adds a new rule to the specified policy. Only accessible by policy admins.

function createRule(uint256 policyId, Rule calldata rule, string calldata ruleName, string calldata ruleDescription)
    external
    returns (uint256);

Parameters

Name	Type	Description
`policyId`	`uint256`	ID of the policy the rule will be added to.
`rule`	`Rule`	The rule to create.
`ruleName`	`string`	The name of the rule
`ruleDescription`	`string`	The description of the rule

Returns

Name	Type	Description
`<none>`	`uint256`	ruleId The generated rule ID.

updateRule

Updates a rule in storage. Modifies an existing rule in the specified policy. Only accessible by policy admins.

function updateRule(
    uint256 policyId,
    uint256 ruleId,
    Rule calldata rule,
    string calldata ruleName,
    string calldata ruleDescription
) external returns (uint256);

Parameters

Name	Type	Description
`policyId`	`uint256`	ID of the policy the rule belongs to.
`ruleId`	`uint256`	The ID of the rule to update.
`rule`	`Rule`	The updated rule data.
`ruleName`	`string`
`ruleDescription`	`string`

Returns

Name	Type	Description
`<none>`	`uint256`	ruleId The updated rule ID.

getAllRules

Retrieves all rules associated with a specific policy.

function getAllRules(uint256 policyId) external view returns (Rule[][] memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The ID of the policy.

Returns

Name	Type	Description
`<none>`	`Rule[][]`	rules A two-dimensional array of rules grouped by calling functions.

getRuleMetadata

Retrieves the metadata of a rule.

function getRuleMetadata(uint256 policyId, uint256 ruleId) external view returns (RuleMetadata memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The ID of the policy the rule belongs to.
`ruleId`	`uint256`	The ID of the rule to retrieve metadata for.

Returns

Name	Type	Description
`<none>`	`RuleMetadata`	RuleMetadata The metadata of the specified rule.

deleteRule

Deletes a rule from storage.

function deleteRule(uint256 policyId, uint256 ruleId) public;

Parameters

Name	Type	Description
`policyId`	`uint256`	The ID of the policy the rule belongs to.
`ruleId`	`uint256`	The ID of the rule to delete.

getRule

Retrieves a rule from storage.

function getRule(uint256 policyId, uint256 ruleId) public view returns (RuleStorageSet memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The ID of the policy the rule belongs to.
`ruleId`	`uint256`	The ID of the rule to retrieve.

Returns

Name	Type	Description
`<none>`	`RuleStorageSet`	ruleStorageSets The rule data.

getMemorySize

function getMemorySize() external pure returns (uint256);

getMaxLoopSize

function getMaxLoopSize() external pure returns (uint256);

getOpsSize1

function getOpsSize1() external pure returns (uint256);

getOpsSizeUpTo2

function getOpsSizeUpTo2() external pure returns (uint256);

getOpsSizeUpTo3

function getOpsSizeUpTo3() external pure returns (uint256);

getOpsTotalSize

function getOpsTotalSize() external pure returns (uint256);

_storeRuleData

Stores rule data in storage. This function is used to store the rule and its metadata.

function _storeRuleData(
    RuleStorage storage data,
    uint256 policyId,
    uint256 ruleId,
    Rule calldata rule,
    string calldata ruleName,
    string calldata ruleDescription
) private;

Parameters

Name	Type	Description
`data`	`RuleStorage`	The rule storage structure.
`policyId`	`uint256`	The ID of the policy the rule belongs to.
`ruleId`	`uint256`	The ID of the rule to store.
`rule`	`Rule`	The rule to store.
`ruleName`	`string`	The name of the rule.
`ruleDescription`	`string`	The description of the rule.

_storeRule

Stores a rule in storage. Validates the policy existence before storing the rule.

function _storeRule(RuleStorage storage _data, uint256 _policyId, uint256 _ruleId, Rule calldata _rule)
    internal
    returns (uint256);

Parameters

Name	Type	Description
`_data`	`RuleStorage`	The rule storage structure.
`_policyId`	`uint256`	The ID of the policy the rule belongs to.
`_ruleId`	`uint256`	The ID of the rule to store.
`_rule`	`Rule`	The rule to store.

Returns

Name	Type	Description
`<none>`	`uint256`	ruleId The stored rule ID.

_updateTrackerIdMapping

Updates the mapping of tracker IDs to rule IDs for a specific policy. This function checks if a tracker is used in the instruction set of the rule and updates the mapping accordingly.

function _updateTrackerIdMapping(RuleStorage storage _data, uint256 _policyId, uint256 _ruleId) internal;

Parameters

Name	Type	Description
`_data`	`RuleStorage`	The rule storage structure.
`_policyId`	`uint256`	The ID of the policy to update the mapping for.
`_ruleId`	`uint256`	The ID of the rule to check for tracker usage.

_removeRuleFromTrackerIdMapping

Removes a rule from the tracker ID mapping. This function checks if a tracker is used in the instruction set of the rule and removes the rule ID from the mapping.

function _removeRuleFromTrackerIdMapping(uint256 _policyId, uint256 _ruleId) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to update the mapping for.
`_ruleId`	`uint256`	The ID of the rule to check for tracker usage.

_incrementRuleId

Increments the rule ID counter for a specific policy. This function is used to generate a new rule ID for a policy.

function _incrementRuleId(RuleStorage storage data, uint256 _policyId) private returns (uint256);

Parameters

Name	Type	Description
`data`	`RuleStorage`	The rule storage structure.
`_policyId`	`uint256`	The ID of the policy to increment the rule ID for.

Returns

Name	Type	Description
`<none>`	`uint256`	The incremented rule ID.

_storeRuleMetadata

function to store the metadata for a rule. This function is used to store the metadata for a rule, such as its name and description.

function _storeRuleMetadata(uint256 _policyId, uint256 _ruleId, string calldata _ruleName, string calldata _description)
    internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy the rule belongs to.
`_ruleId`	`uint256`	The ID of the rule to store metadata for.
`_ruleName`	`string`	The name of the rule.
`_description`	`string`	The description of the rule.

_validateRule

function _validateRule(Rule calldata rule, uint256 policyId) internal view;

_validateEffects

Validates an array of effects.

function _validateEffects(Effect[] calldata effects, uint256 policyId) internal view;

Parameters

Name	Type	Description
`effects`	`Effect[]`	The effects to validate.
`policyId`	`uint256`	The policyId

_validatePlaceholders

Validates an array of placeholders.

function _validatePlaceholders(Placeholder[] calldata placeholders) internal pure;

Parameters

Name	Type	Description
`placeholders`	`Placeholder[]`	The placeholders to validate.

_validateInstructionSet

Validates an instruction set.

function _validateInstructionSet(uint256[] calldata instructionSet, uint256 policyId) internal view;

Parameters

Name	Type	Description
`instructionSet`	`uint256[]`	The instructionSet to validate.
`policyId`	`uint256`	The policyId.

_isLessLimitedOpCode

Determines whether the given operation code’s data is considered “less limited” and can be upwards of the max loop size

function _isLessLimitedOpCode(uint256 opCode) internal pure returns (bool);

Parameters

Name	Type	Description
`opCode`	`uint256`	The operation code to evaluate.

Returns

Name	Type	Description
`<none>`	`bool`	bool Returns `true` if the operation code is less limited, otherwise `false`.

_validateParamType

Validates a paramType.

function _validateParamType(ParamTypes paramType) internal pure;

Parameters

Name	Type	Description
`paramType`	`ParamTypes`	The paramType to validate.

_validateEffectType

Validates an effect type.

function _validateEffectType(EffectTypes effectType) internal pure;

Parameters

Name	Type	Description
`effectType`	`EffectTypes`	The effectType to validate.

_policyAdminOnly

Checks that the caller is a policy admin

function _policyAdminOnly(uint256 _policyId, address _address) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_address`	`address`	The address to check for policy admin status.

Example

Utils

Engine

Client

Functions

createRule

updateRule

getAllRules

getRuleMetadata

deleteRule

getRule

getMemorySize

getMaxLoopSize

getOpsSize1

getOpsSizeUpTo2

getOpsSizeUpTo3

getOpsTotalSize

_storeRuleData

_storeRule

_updateTrackerIdMapping

_removeRuleFromTrackerIdMapping

_incrementRuleId

_storeRuleMetadata

_validateRule

_validateEffects

_validatePlaceholders

_validateInstructionSet

_isLessLimitedOpCode

_validateParamType

_validateEffectType

_policyAdminOnly

Example

Utils

Engine

Client

​Functions

​createRule

​updateRule

​getAllRules

​getRuleMetadata

​deleteRule

​getRule

​getMemorySize

​getMaxLoopSize

​getOpsSize1

​getOpsSizeUpTo2

​getOpsSizeUpTo3

​getOpsTotalSize

​_storeRuleData

​_storeRule

​_updateTrackerIdMapping

​_removeRuleFromTrackerIdMapping

​_incrementRuleId

​_storeRuleMetadata

​_validateRule

​_validateEffects

​_validatePlaceholders

​_validateInstructionSet

​_isLessLimitedOpCode

​_validateParamType

​_validateEffectType

​_policyAdminOnly

Functions

createRule

updateRule

getAllRules

getRuleMetadata

deleteRule

getRule

getMemorySize

getMaxLoopSize

getOpsSize1

getOpsSizeUpTo2

getOpsSizeUpTo3

getOpsTotalSize

_storeRuleData

_storeRule

_updateTrackerIdMapping

_removeRuleFromTrackerIdMapping

_incrementRuleId

_storeRuleMetadata

_validateRule

_validateEffects

_validatePlaceholders

_validateInstructionSet

_isLessLimitedOpCode

_validateParamType

_validateEffectType

_policyAdminOnly