RulesEnginePolicyFacet - Forte Rules Engine

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

updatePolicy

Updates a policy in storage.

Updates the policy type, calling functions, and associated rules.

function updatePolicy(
    uint256 policyId,
    bytes4[] calldata callingFunctions,
    uint256[] calldata callingFunctionIds,
    uint256[][] calldata ruleIds,
    PolicyType policyType
) external policyAdminOnly(policyId, msg.sender) returns (uint256);

Parameters

Name	Type	Description
`policyId`	`uint256`	The ID of the policy to update.
`callingFunctions`	`bytes4[]`	The function signatures of the calling functions in the policy.
`callingFunctionIds`	`uint256[]`	The IDs of the calling functions.
`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);

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

Parameters

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

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.

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

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.

unapplyPolicy

Unapplies policies from a specified contract.

Ensures that only calling contract admins can unapply policies. Removes associations between the contract and the specified policies.

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

Parameters

Name	Type	Description
`_contractAddress`	`address`	The address of the contract from which policies will be unapplied.
`_policyIds`	`uint256[]`	The IDs of the policies to unapply.

createPolicy

Creates a new policy and assigns a policy admin.

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

function createPolicy(PolicyType policyType) external returns (uint256);

Parameters

Name	Type	Description
`policyType`	`PolicyType`	The type of the policy (CLOSED_POLICY or OPEN_POLICY).

Returns

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

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.

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.

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 callingFunctions, uint256[] memory callingFunctionIds, uint256[][] memory ruleIds);

Parameters

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

Returns

Name	Type	Description
`callingFunctions`	`bytes4[]`	The calling functions within the policy.
`callingFunctionIds`	`uint256[]`	The calling function IDs corresponding to each calling function.
`ruleIds`	`uint256[][]`	The rule IDs corresponding to each calling function.

_storePolicyData

Internal helper function for creating and updating policy data.

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

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

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

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_callingFunctions`	`bytes4[]`	All callingFunctions in the policy.
`_callingFunctionIds`	`uint256[]`	Corresponding Calling Function IDs in the policy. Each element matches one-to-one with the elements in `_callingFunctions`.
`_ruleIds`	`uint256[][]`	A two-dimensional array of rule IDs. The first level represents calling functions, and the second level contains rule IDs for each calling function.
`_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).

reference

​Functions

​updatePolicy

​closePolicy

​openPolicy

​cementPolicy

​deletePolicy

​applyPolicy

​unapplyPolicy

​createPolicy

​getAppliedPolicyIds

​isClosedPolicy

​getPolicy

​_storePolicyData

​_processPolicyTypeChange

Functions

updatePolicy

closePolicy

openPolicy

cementPolicy

deletePolicy

applyPolicy

unapplyPolicy

createPolicy

getAppliedPolicyIds

isClosedPolicy

getPolicy

_storePolicyData

_processPolicyTypeChange