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.

State Variables

version

string public constant version = "v0.5.0";

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 ruleIds,
    PolicyType policyType,
    string calldata policyName,
    string calldata policyDescription
) external 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.
`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).
`policyName`	`string`
`policyDescription`	`string`

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.

disablePolicy

Marks a policy as disabled. A policy will not be checked against if it is in a disabled state.

function disablePolicy(uint256 policyId) external policyAdminOnly(policyId, msg.sender);

Parameters

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

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, string calldata policyName, string calldata policyDescription)
    external
    returns (uint256);

Parameters

Name	Type	Description
`policyType`	`PolicyType`	The type of the policy (CLOSED_POLICY or OPEN_POLICY).
`policyName`	`string`	The name of the policy.
`policyDescription`	`string`	A description of the policy.

Returns

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

_storePolicyMetadata

Internal function to store policy metadata. This function is a placeholder for storing policy metadata such as name and description.

function _storePolicyMetadata(uint256 _policyId, string calldata _policyName, string calldata _policyDescription)
    internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_policyName`	`string`	The name of the policy.
`_policyDescription`	`string`	A description of the policy.

getPolicyMetadata

Retrieves the metadata of a policy.

function getPolicyMetadata(uint256 _policyId) external view returns (PolicyMetadata memory);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy to retrieve metadata for.

Returns

Name	Type	Description
`<none>`	`PolicyMetadata`	PolicyMetadata The metadata of the policy.

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.

isDisabledPolicy

Checks if a policy is disabled.

function isDisabledPolicy(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 disabled, 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 ruleIds);

Parameters

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

Returns

Name	Type	Description
`callingFunctions`	`bytes4[]`	The calling functions within the policy.
`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 _ruleIds,
    PolicyType _policyType,
    string calldata _policyName,
    string calldata _policyDescription
) internal returns (uint256);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_callingFunctions`	`bytes4[]`	All callingFunctions in the policy.
`_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).
`_policyName`	`string`
`_policyDescription`	`string`

Returns

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

_processCallingFunctionsWithRules

Internal helper function to process calling functions with associated rules. This function validates calling functions, maps them to their IDs, and processes rules for each calling function.

function _processCallingFunctionsWithRules(
    uint256 _policyId,
    bytes4[] calldata _callingFunctions,
    uint256[][] calldata _ruleIds,
    Policy storage data
) private;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_callingFunctions`	`bytes4[]`	The function signatures of the calling functions in the policy.
`_ruleIds`	`uint256[][]`	A two-dimensional array of rule IDs associated with the policy.
`data`	`Policy`	The policy data storage structure.

_processCallingFunctionsWithoutRules

Internal helper function to process calling functions without associated rules. This function validates calling functions and maps them to their IDs.

function _processCallingFunctionsWithoutRules(
    uint256 _policyId,
    bytes4[] calldata _callingFunctions,
    Policy storage data
) private;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_callingFunctions`	`bytes4[]`	The function signatures of the calling functions in the policy.
`data`	`Policy`	The policy data storage structure.

_processRulesForCallingFunction

Internal helper function to process rules for a calling function. This function validates placeholders in the rule and maps rules to the calling function.

function _processRulesForCallingFunction(
    uint256 _policyId,
    bytes4 _callingFunction,
    uint256[] calldata _ruleIds,
    Policy storage data
) private;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`_callingFunction`	`bytes4`	The function signature of the calling function.
`_ruleIds`	`uint256[]`	The IDs of the rules associated with the calling function.
`data`	`Policy`	The policy data storage structure.

_validatePlaceholders

Internal helper function to validate placeholders in a policy. This function checks if the placeholders are set correctly and if foreign calls or trackers are valid.

function _validatePlaceholders(uint256 _policyId, Placeholder[] memory placeholders) private view;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The ID of the policy.
`placeholders`	`Placeholder[]`	The array of placeholders to validate.

_validateNoIdenticalFunctionSigs

function _validateNoIdenticalFunctionSigs(bytes4[] calldata sigs) internal pure;

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

isCementedPolicy

Checks if a policy is cemented.

function isCementedPolicy(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 cemented, false otherwise.

_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

State Variables

version

Functions

updatePolicy

closePolicy

openPolicy

cementPolicy

disablePolicy

deletePolicy

applyPolicy

unapplyPolicy

createPolicy

_storePolicyMetadata

getPolicyMetadata

getAppliedPolicyIds

isClosedPolicy

isDisabledPolicy

getPolicy

_storePolicyData

_processCallingFunctionsWithRules

_processCallingFunctionsWithoutRules

_processRulesForCallingFunction

_validatePlaceholders

_validateNoIdenticalFunctionSigs

_processPolicyTypeChange

isCementedPolicy

_policyAdminOnly

Example

Utils

Engine

Client

​State Variables

​version

​Functions

​updatePolicy

​closePolicy

​openPolicy

​cementPolicy

​disablePolicy

​deletePolicy

​applyPolicy

​unapplyPolicy

​createPolicy

​_storePolicyMetadata

​getPolicyMetadata

​getAppliedPolicyIds

​isClosedPolicy

​isDisabledPolicy

​getPolicy

​_storePolicyData

​_processCallingFunctionsWithRules

​_processCallingFunctionsWithoutRules

​_processRulesForCallingFunction

​_validatePlaceholders

​_validateNoIdenticalFunctionSigs

​_processPolicyTypeChange

​isCementedPolicy

​_policyAdminOnly

State Variables

version

Functions

updatePolicy

closePolicy

openPolicy

cementPolicy

disablePolicy

deletePolicy

applyPolicy

unapplyPolicy

createPolicy

_storePolicyMetadata

getPolicyMetadata

getAppliedPolicyIds

isClosedPolicy

isDisabledPolicy

getPolicy

_storePolicyData

_processCallingFunctionsWithRules

_processCallingFunctionsWithoutRules

_processRulesForCallingFunction

_validatePlaceholders

_validateNoIdenticalFunctionSigs

_processPolicyTypeChange

isCementedPolicy

_policyAdminOnly