RulesEnginePolicyFacet

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