RulesEnginePolicyFacet - 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 policy management.

This contract serves as the primary data facet for the Rules Engine. It is responsible for creating, updating, retrieving, and managing policies and 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)
    public
    policyAdminOnly(_policyId, msg.sender)
    notCemented(_policyId)
    returns (uint256);

Parameters

Name	Type	Description
`_policyId`	`uint256`	ID of the policy the rule will be added to.
`_rule`	`Rule`	The rule to create.

Returns

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

_storeRule

Stores a rule in storage.

Validates the policy existence before storing the rule.

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

Parameters

Name	Type	Description
`_data`	`RuleS`	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.

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)
    external
    policyAdminOnly(_policyId, msg.sender)
    notCemented(_policyId)
    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.

Returns

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

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.

deleteRule

Deletes a rule from storage.

function deleteRule(uint256 _policyId, uint256 _ruleId)
    public
    policyAdminOnly(_policyId, msg.sender)
    notCemented(_policyId);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy the rule belongs to.
`_ruleId`	`uint256`	The ID of the rule to delete.

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 function signatures.

updatePolicy

Updates a policy in storage.

Updates the policy type, function signatures, and associated rules.

function updatePolicy(
    uint256 _policyId,
    bytes4[] calldata _signatures,
    uint256[] calldata _functionSignatureIds,
    uint256[][] calldata _ruleIds,
    PolicyType _policyType
) external policyAdminOnly(_policyId, msg.sender) notCemented(_policyId) returns (uint256);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to update.
`_signatures`	`bytes4[]`	The function signatures in the policy.
`_functionSignatureIds`	`uint256[]`	The IDs of the function signatures.
`_ruleIds`	`uint256[][]`	A two-dimensional array of rule IDs associated with the policy.
`_policyType`	`PolicyType`	The type of the policy (CLOSED_POLICY or OPEN_POLICY).

Returns

Name	Type	Description
`<none>`	`uint256`	policyId The updated policy ID.

closePolicy

Closes a policy by changing its type to CLOSED_POLICY.

This function ensures that only policy admins can close a policy and that the policy is not cemented.

function closePolicy(uint256 _policyId) external policyAdminOnly(_policyId, msg.sender) notCemented(_policyId);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to close.

openPolicy

Opens a policy by changing its type to OPEN_POLICY.

This function ensures that only policy admins can open a policy and that the policy is not cemented.

function openPolicy(uint256 _policyId) external policyAdminOnly(_policyId, msg.sender) notCemented(_policyId);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to open.

isClosedPolicy

Checks if a policy is closed.

function isClosedPolicy(uint256 _policyId) external view returns (bool);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to check.

Returns

Name	Type	Description
`<none>`	`bool`	bool True if the policy is closed, false otherwise.

deletePolicy

Deletes a policy from storage.

Removes the policy and all associated rules, trackers, and foreign calls. Ensures the policy is not cemented.

function deletePolicy(uint256 _policyId) public policyAdminOnly(_policyId, msg.sender) notCemented(_policyId);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to delete.

applyPolicy

Applies policies to a specified contract.

Ensures that only calling contract admins can apply policies and validates policy types.

function applyPolicy(address _contractAddress, uint256[] calldata _policyIds)
    external
    callingContractAdminOnly(_contractAddress, msg.sender);

Parameters

Name	Type	Description
`_contractAddress`	`address`	The address of the contract to apply policies to.
`_policyIds`	`uint256[]`	The IDs of the policies to apply.

getAppliedPolicyIds

Retrieves the IDs of policies applied to a specific contract.

function getAppliedPolicyIds(address _contractAddress) external view returns (uint256[] memory);

Parameters

Name	Type	Description
`_contractAddress`	`address`	The address of the contract.

Returns

Name	Type	Description
`<none>`	`uint256[]`	uint256[] An array of applied policy IDs.

createPolicy

Creates a new policy and assigns a policy admin.

Generates a policy ID and initializes the policy with the specified type.

function createPolicy(
    FunctionSignatureStorageSet[] calldata _functionSignatures,
    Rule[] calldata _rules,
    PolicyType _policyType
) external returns (uint256);

Parameters

Name	Type	Description
`_functionSignatures`	`FunctionSignatureStorageSet[]`	The function signatures associated with the policy.
`_rules`	`Rule[]`	The rules associated with the policy.
`_policyType`	`PolicyType`	The type of the policy (CLOSED_POLICY or OPEN_POLICY).

Returns

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

_storePolicyData

Internal helper function for creating and updating policy data.

This function processes and stores policy data, including function signatures, rules, and policy type.

The parameters are complex because nested structs are not allowed for externally facing functions.

function _storePolicyData(
    uint256 _policyId,
    bytes4[] calldata _signatures,
    uint256[] calldata _functionSignatureIds,
    uint256[][] calldata _ruleIds,
    PolicyType _policyType
) internal returns (uint256);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_signatures`	`bytes4[]`	All function signatures in the policy.
`_functionSignatureIds`	`uint256[]`	Corresponding signature IDs in the policy. Each element matches one-to-one with the elements in `_signatures`.
`_ruleIds`	`uint256[][]`	A two-dimensional array of rule IDs. The first level represents function signatures, and the second level contains rule IDs for each signature.
`_policyType`	`PolicyType`	The type of the policy (OPEN or CLOSED).

Returns

Name	Type	Description
`<none>`	`uint256`	policyId The updated policy ID.

_processPolicyTypeChange

Internal helper function to handle data cleanup during policy type changes.

This function removes applied contract associations when transitioning to a CLOSED policy.

function _processPolicyTypeChange(uint256 _policyId, PolicyType _policyType) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_policyType`	`PolicyType`	The new type of the policy (OPEN or CLOSED).

getPolicy

Retrieves a policy from storage.

Since Policy contains nested mappings, the data is broken into arrays for external return.

function getPolicy(uint256 _policyId)
    external
    view
    returns (bytes4[] memory functionSigs, uint256[] memory functionSigIds, uint256[][] memory ruleIds);

Parameters

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

Returns

Name	Type	Description
`functionSigs`	`bytes4[]`	The function signatures within the policy.
`functionSigIds`	`uint256[]`	The function signature IDs corresponding to each function signature.
`ruleIds`	`uint256[][]`	The rule IDs corresponding to each function signature.

_isCemented

Checks if a policy is cemented.

function _isCemented(uint256 _policyId) internal view returns (bool _cemented);

Parameters

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

Returns

Name	Type	Description
`_cemented`	`bool`	True if the policy is cemented, false otherwise.

notCemented

Modifier to ensure that cemented policies cannot be modified.

modifier notCemented(uint256 _policyId);

Parameters

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

cementPolicy

Marks a policy as cemented, preventing further modifications.

function cementPolicy(uint256 _policyId) external policyAdminOnly(_policyId, msg.sender);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to cement.

_isFunctionSignatureSet

This section is for internal functions used for validation of components. They are here to optimize gas consumption.

Checks if a function signature is set for the specified policy.

Validates whether the function signature exists in the policy’s storage.

function _isFunctionSignatureSet(uint256 _policyId, uint256 _functionSignatureId) internal view returns (bool);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy the function signature is associated with.
`_functionSignatureId`	`uint256`	The ID of the function signature to check.

Returns

Name	Type	Description
`<none>`	`bool`	set True if the function signature is set, false otherwise.

_isForeignCallSet

Checks if a foreign call is set for the specified policy.

Validates whether the foreign call exists in the policy’s storage.

function _isForeignCallSet(uint256 _policyId, uint256 _foreignCallId) internal view returns (bool);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy the foreign call is associated with.
`_foreignCallId`	`uint256`	The ID of the foreign call to check.

Returns

Name	Type	Description
`<none>`	`bool`	set True if the foreign call is set, false otherwise.

_isTrackerSet

Checks if a tracker is set for the specified policy.

Validates whether the tracker exists in the policy’s storage.

function _isTrackerSet(uint256 _policyId, uint256 _index) public view returns (bool);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy the tracker is associated with.
`_index`	`uint256`	The index of the tracker to check.

Returns

Name	Type	Description
`<none>`	`bool`	set True if the tracker is set, false otherwise.

Reference

​Functions

​createRule

​_storeRule

​updateRule

​getRule

​deleteRule

​getAllRules

​updatePolicy

​closePolicy

​openPolicy

​isClosedPolicy

​deletePolicy

​applyPolicy

​getAppliedPolicyIds

​createPolicy

​_storePolicyData

​_processPolicyTypeChange

​getPolicy

​_isCemented

​notCemented

​cementPolicy

​_isFunctionSignatureSet

​_isForeignCallSet

​_isTrackerSet

Functions

createRule

_storeRule

updateRule

getRule

deleteRule

getAllRules

updatePolicy

closePolicy

openPolicy

isClosedPolicy

deletePolicy

applyPolicy

getAppliedPolicyIds

createPolicy

_storePolicyData

_processPolicyTypeChange

getPolicy

_isCemented

notCemented

cementPolicy

_isFunctionSignatureSet

_isForeignCallSet

_isTrackerSet