RulesEngineComponentFacet

Git Source Inherits: FacetCommonImports Author: @mpetersoCode55, @ShaneDuncan602, @TJ-Everett, @VoR0220 This contract is a critical component of the Rules Engine, enabling secure and flexible data management. This contract serves as the data facet for the Rules Engine subcomponents. It provides functionality for managing foreign calls, trackers, calling functions, and policy subscriptions. 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

createTracker

Adds a tracker to the tracker storage mapping. Creates a new tracker and associates it with the specified policy ID.

function createTracker(
    uint256 policyId,
    Trackers calldata tracker,
    string calldata trackerName,
    TrackerArrayTypes arrayType
) external returns (uint256);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the tracker is associated with.
`tracker`	`Trackers`	The tracker to add.
`trackerName`	`string`	Name of the tracker
`arrayType`	`TrackerArrayTypes`

Returns

Name	Type	Description
`<none>`	`uint256`	trackerIndex The index of the created tracker.

createMappedTracker

Adds a mapped tracker to tracker storage. Creates a new tracker and associates it with the specified policy ID and assigns the tracker to addresses.

function createMappedTracker(
    uint256 policyId,
    Trackers memory tracker,
    string calldata trackerName,
    bytes[] calldata trackerKeys,
    bytes[] calldata trackerValues,
    TrackerArrayTypes arrayType
) external returns (uint256);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the tracker is associated with.
`tracker`	`Trackers`	The tracker to add.
`trackerName`	`string`	Names of the trackers
`trackerKeys`	`bytes[]`
`trackerValues`	`bytes[]`
`arrayType`	`TrackerArrayTypes`

Returns

Name	Type	Description
`<none>`	`uint256`	trackerIndex The index of the created tracker.

_validateTrackerType

function _validateTrackerType(Trackers memory _tracker) internal pure;

_validateCallingFunctionPType

function _validateCallingFunctionPType(ParamTypes[] memory types) internal pure;

_incrementTrackerIndex

Helper function to increment tracker index

function _incrementTrackerIndex(uint256 _policyId) private returns (uint256);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the tracker is associated with.

_storeTrackerData

Helper function to store tracker data

function _storeTrackerData(
    uint256 _policyId,
    uint256 _trackerIndex,
    Trackers memory _tracker,
    bytes calldata _trackerKey,
    bytes calldata _trackerValue
) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the tracker is associated with.
`_trackerIndex`	`uint256`	The index of the tracker to store
`_tracker`	`Trackers`	The tracker to store.
`_trackerKey`	`bytes`	The key for the tracker mapping.
`_trackerValue`	`bytes`	The value for the tracker mapping.

_storeTrackerMetadata

Helper function to store tracker metadata

function _storeTrackerMetadata(
    uint256 _policyId,
    uint256 _trackerIndex,
    string calldata _trackerName,
    bytes calldata initialValue,
    TrackerArrayTypes arrayType
) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the tracker is associated with.
`_trackerIndex`	`uint256`	The index of the tracker
`_trackerName`	`string`	Name of the tracker
`initialValue`	`bytes`
`arrayType`	`TrackerArrayTypes`

_storeMappedTrackerMetadata

function _storeMappedTrackerMetadata(
    uint256 _policyId,
    uint256 _trackerIndex,
    string calldata _trackerName,
    bytes[] calldata initialKeys,
    bytes[] calldata initialValues,
    TrackerArrayTypes arrayType
) internal;

_storeTracker

Stores a tracker in the tracker storage mapping. Sets the tracker data and marks it as active.

function _storeTracker(TrackerStorage storage _data, uint256 _policyId, uint256 _trackerIndex, Trackers memory _tracker)
    internal;

Parameters

Name	Type	Description
`_data`	`TrackerStorage`	The tracker storage structure.
`_policyId`	`uint256`	The policy ID the tracker is associated with.
`_trackerIndex`	`uint256`	The index of the tracker to store.
`_tracker`	`Trackers`	The tracker data to store.

_storeTrackerMapping

Stores mapping data in the tracker storage mapping. Sets the tracker mapped bool to active.

function _storeTrackerMapping(
    TrackerStorage storage _data,
    uint256 _policyId,
    uint256 _trackerIndex,
    Trackers memory _tracker,
    bytes memory _trackerKey,
    bytes memory _trackerValue
) internal;

Parameters

Name	Type	Description
`_data`	`TrackerStorage`	The tracker storage structure.
`_policyId`	`uint256`	The policy ID the tracker is associated with.
`_trackerIndex`	`uint256`	The index of the tracker to store.
`_tracker`	`Trackers`	The tracker data to store.
`_trackerKey`	`bytes`	The keys for the tracker mapping.
`_trackerValue`	`bytes`	The values for the tracker mapping.

_storeTrackerData

Helper function to store tracker data

function _storeTrackerData(uint256 _policyId, uint256 _trackerIndex, Trackers calldata _tracker) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the tracker is associated with.
`_trackerIndex`	`uint256`	The index of the tracker to store
`_tracker`	`Trackers`

getTrackerMetadata

retrieves the tracker metadata

function getTrackerMetadata(uint256 policyId, uint256 trackerId) public view returns (TrackerMetadataStruct memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the tracker is associated with.
`trackerId`	`uint256`	The identifier for the tracker

Returns

Name	Type	Description
`<none>`	`TrackerMetadataStruct`	the metadata for the tracker

getAllTrackers

Retrieves all trackers associated with a specific policy ID.

function getAllTrackers(uint256 policyId) external view returns (Trackers[] memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the trackers are associated with.

Returns

Name	Type	Description
`<none>`	`Trackers[]`	trackers An array of tracker data.

getTracker

Retrieves a tracker from the tracker storage mapping.

function getTracker(uint256 policyId, uint256 index) public view returns (Trackers memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the tracker is associated with.
`index`	`uint256`	The index of the tracker to retrieve.

Returns

Name	Type	Description
`<none>`	`Trackers`	The tracker data.

getTrackerToRuleIds

Retrieves the rule IDs associated with a specific tracker index for a given policy ID.

function getTrackerToRuleIds(uint256 policyId, uint256 trackerIndex) external view returns (uint256[] memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the tracker is associated with.
`trackerIndex`	`uint256`	The index of the tracker to retrieve rule IDs for.

Returns

Name	Type	Description
`<none>`	`uint256[]`	An array of rule IDs associated with the specified tracker index.

getMappedTrackerValue

Retrieves a tracker from the tracker storage mapping.

function getMappedTrackerValue(uint256 policyId, uint256 index, bytes memory trackerKey)
    public
    view
    returns (bytes memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the tracker is associated with.
`index`	`uint256`	The index of the tracker to retrieve.
`trackerKey`	`bytes`

Returns

Name	Type	Description
`<none>`	`bytes`	tracker The tracker data.

updateTracker

Updates an existing tracker in the tracker storage mapping. Modifies the tracker associated with the specified policy ID and tracker index.

function updateTracker(uint256 policyId, uint256 trackerIndex, Trackers calldata tracker) external;

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the tracker is associated with.
`trackerIndex`	`uint256`	The index of the tracker to update.
`tracker`	`Trackers`	The updated tracker data.

updateTracker

Updates an existing tracker in the tracker storage mapping. Modifies the tracker associated with the specified policy ID and tracker index.

function updateTracker(
    uint256 _policyId,
    uint256 _trackerIndex,
    Trackers calldata _tracker,
    bytes calldata _trackerKey,
    bytes calldata _trackerValue
) external;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the tracker is associated with.
`_trackerIndex`	`uint256`	The index of the tracker to update.
`_tracker`	`Trackers`	The updated tracker data.
`_trackerKey`	`bytes`	The keys for the tracker mapping.
`_trackerValue`	`bytes`	The values for the tracker mapping.

deleteTracker

Tracker mappings are not deleted, since trackerIds are not reused that data will never clash with new trackers. Helper function to store tracker data

function deleteTracker(uint256 policyId, uint256 trackerIndex) external;

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the tracker is associated with.
`trackerIndex`	`uint256`	The index of the tracker to store

createCallingFunction

Creates a new calling function and stores it in the calling function storage mapping. Associates the calling function with the specified policy ID and parameter types.

function createCallingFunction(
    uint256 policyId,
    bytes4 functionSignature,
    ParamTypes[] memory pTypes,
    string memory callingFunctionName,
    string memory encodedValues
) external returns (bytes4);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the calling function is associated with.
`functionSignature`	`bytes4`	The function signature of the calling function.
`pTypes`	`ParamTypes[]`	The parameter types for the calling function.
`callingFunctionName`	`string`	the name of the calling function (to be stored in metadata)
`encodedValues`	`string`	the string representation of the values encoded with the calling function (to be stored in metadata)

Returns

Name	Type	Description
`<none>`	`bytes4`	functionId The index of the created calling function.

updateCallingFunction

Updates an existing calling function by appending new parameter types. Ensures that the new parameter types are compatible with the existing ones.

function updateCallingFunction(uint256 policyId, bytes4 functionSignature, ParamTypes[] memory pTypes)
    external
    returns (bytes4);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the calling function is associated with.
`functionSignature`	`bytes4`	The function signature of the calling function.
`pTypes`	`ParamTypes[]`	The new parameter types to append.

Returns

Name	Type	Description
`<none>`	`bytes4`	functionId The updated calling function ID.

deleteCallingFunction

Deletes a calling function from storage. Removes the calling function and its associated rules and mappings.

function deleteCallingFunction(uint256 policyId, bytes4 sig) external;

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the calling function is associated with.
`sig`	`bytes4`	The selector of the calling function to delete.

getCallingFunction

Retrieves a calling function from storage.

function getCallingFunction(uint256 policyId, bytes4 sig) public view returns (CallingFunctionStorageSet memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the calling function is associated with.
`sig`	`bytes4`	The selector of the calling function to retrieve.

Returns

Name	Type	Description
`<none>`	`CallingFunctionStorageSet`	CallngFunctionStorageSet The calling function data.

getCallingFunctionMetadata

retrieves the calling function metadata

function getCallingFunctionMetadata(uint256 policyId, bytes4 sig)
    public
    view
    returns (CallingFunctionHashMapping memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the calling function is associated with.
`sig`	`bytes4`	The selector for the calling function

Returns

Name	Type	Description
`<none>`	`CallingFunctionHashMapping`	the metadata for the calling function

getAllCallingFunctions

Retrieves all calling functions associated with a specific policy ID.

function getAllCallingFunctions(uint256 policyId) public view returns (CallingFunctionStorageSet[] memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the calling functions are associated with.

Returns

Name	Type	Description
`<none>`	`CallingFunctionStorageSet[]`	CallingFunctionStorageSet An array of calling function data.

_storeCallingFunctionData

Helper function to store calling function data

function _storeCallingFunctionData(uint256 _policyId, bytes4 _functionSignature, ParamTypes[] memory _pTypes) private;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the calling function is associated with.
`_functionSignature`	`bytes4`	The function signature of the calling function
`_pTypes`	`ParamTypes[]`	The parameter types for the calling function.

_storeCallingFunctionMetadata

Helper function to store calling function metadata

function _storeCallingFunctionMetadata(
    uint256 _policyId,
    bytes4 _functionSignature,
    string memory _callingFunctionName,
    string memory _encodedValues
) private;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the calling function is associated with.
`_functionSignature`	`bytes4`	The function signature of the calling function
`_callingFunctionName`	`string`	Name of the calling function
`_encodedValues`	`string`	Arguments to be encoded

addClosedPolicySubscriber

Adds an address to the subscriber list of a specified policy. Only callable by a policy admin. The policy must not be cemented.

function addClosedPolicySubscriber(uint256 policyId, address subscriber) external;

Parameters

Name	Type	Description
`policyId`	`uint256`	The ID of the policy.
`subscriber`	`address`	The address to add to the policy subscription.

removeClosedPolicySubscriber

Removes an address from the subscriber list of a specified policy. Only callable by a policy admin. The policy must not be cemented.

function removeClosedPolicySubscriber(uint256 policyId, address subscriber) external;

Parameters

Name	Type	Description
`policyId`	`uint256`	The ID of the policy.
`subscriber`	`address`	The address to remove from the policy subscription.

isClosedPolicySubscriber

Checks if an address is a subscriber of the specified policy.

function isClosedPolicySubscriber(uint256 policyId, address subscriber) external view returns (bool);

Parameters

Name	Type	Description
`policyId`	`uint256`	The ID of the policy.
`subscriber`	`address`	The address to check for policy subscription.

Returns

Name	Type	Description
`<none>`	`bool`	bool True if the address is a subscriber, false otherwise.

_notCemented

Checks that a policy is not cemented.

function _notCemented(uint256 _policyId) internal view;

Parameters

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

_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

createTracker

createMappedTracker

_validateTrackerType

_validateCallingFunctionPType

_incrementTrackerIndex

_storeTrackerData

_storeTrackerMetadata

_storeMappedTrackerMetadata

_storeTracker

_storeTrackerMapping

_storeTrackerData

getTrackerMetadata

getAllTrackers

getTracker

getTrackerToRuleIds

getMappedTrackerValue

updateTracker

updateTracker

deleteTracker

createCallingFunction

updateCallingFunction

deleteCallingFunction

getCallingFunction

getCallingFunctionMetadata

getAllCallingFunctions

_storeCallingFunctionData

_storeCallingFunctionMetadata

addClosedPolicySubscriber

removeClosedPolicySubscriber

isClosedPolicySubscriber

_notCemented

_policyAdminOnly

Example

Utils

Engine

Client

​Functions

​createTracker

​createMappedTracker

​_validateTrackerType

​_validateCallingFunctionPType

​_incrementTrackerIndex

​_storeTrackerData

​_storeTrackerMetadata

​_storeMappedTrackerMetadata

​_storeTracker

​_storeTrackerMapping

​_storeTrackerData

​getTrackerMetadata

​getAllTrackers

​getTracker

​getTrackerToRuleIds

​getMappedTrackerValue

​updateTracker

​updateTracker

​deleteTracker

​createCallingFunction

​updateCallingFunction

​deleteCallingFunction

​getCallingFunction

​getCallingFunctionMetadata

​getAllCallingFunctions

​_storeCallingFunctionData

​_storeCallingFunctionMetadata

​addClosedPolicySubscriber

​removeClosedPolicySubscriber

​isClosedPolicySubscriber

​_notCemented

​_policyAdminOnly

Functions

createTracker

createMappedTracker

_validateTrackerType

_validateCallingFunctionPType

_incrementTrackerIndex

_storeTrackerData

_storeTrackerMetadata

_storeMappedTrackerMetadata

_storeTracker

_storeTrackerMapping

_storeTrackerData

getTrackerMetadata

getAllTrackers

getTracker

getTrackerToRuleIds

getMappedTrackerValue

updateTracker

updateTracker

deleteTracker

createCallingFunction

updateCallingFunction

deleteCallingFunction

getCallingFunction

getCallingFunctionMetadata

getAllCallingFunctions

_storeCallingFunctionData

_storeCallingFunctionMetadata

addClosedPolicySubscriber

removeClosedPolicySubscriber

isClosedPolicySubscriber

_notCemented

_policyAdminOnly