RulesEngineComponentFacet - Forte Rules Engine

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

createForeignCall

Creates a foreign call and stores it in the contract’s storage.

Builds a foreign call structure and maps it to the associated policy ID.

function createForeignCall(uint256 _policyId, ForeignCall calldata _foreignCall, string calldata foreignCallName)
    external
    policyAdminOnly(_policyId, msg.sender)
    returns (uint256);

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the foreign call will be mapped to.
`_foreignCall`	`ForeignCall`	The definition of the foreign call to create.
`foreignCallName`	`string`

Returns

Name	Type	Description
`<none>`	`uint256`	The index of the created foreign call.

updateForeignCall

Updates a foreign call in the contract’s storage.

function updateForeignCall(uint256 policyId, uint256 foreignCallId, ForeignCall calldata foreignCall)
    external
    policyAdminOnly(policyId, msg.sender)
    returns (ForeignCall memory fc);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the foreign call is associated with.
`foreignCallId`	`uint256`	The ID of the foreign call to update.
`foreignCall`	`ForeignCall`	The updated foreign call structure.

Returns

Name	Type	Description
`fc`	`ForeignCall`	The updated foreign call structure.

deleteForeignCall

Deletes a foreign call from the contract’s storage.

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

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the foreign call is associated with.
`foreignCallId`	`uint256`	The ID of the foreign call to delete.

getAllForeignCalls

Retrieve Foreign Call Set from storage

function getAllForeignCalls(uint256 policyId) external view returns (ForeignCall[] memory fc);

Parameters

Name	Type	Description
`policyId`	`uint256`	the policy Id of the foreign call to retrieve

Returns

Name	Type	Description
`fc`	`ForeignCall[]`	the foreign call set structure

getForeignCall

Retrieves a foreign call from the contract’s storage.

function getForeignCall(uint256 policyId, uint256 foreignCallId) public view returns (ForeignCall memory fc);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID of the foreign call to retrieve.
`foreignCallId`	`uint256`	The ID of the foreign call to retrieve.

Returns

Name	Type	Description
`fc`	`ForeignCall`	The foreign call structure.

getForeignCallMetadata

retrieves the foreign call metadata

function getForeignCallMetadata(uint256 policyId, uint256 foreignCallId) public view returns (string memory fcMeta);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the foreign call is associated with.
`foreignCallId`	`uint256`	The identifier for the foreign call

Returns

Name	Type	Description
`fcMeta`	`string`	the metadata for the foreign call

_storeForeignCall

Stores a foreign call in the contract’s storage.

Ensures the foreign call is properly set before storing it.

function _storeForeignCall(uint256 _policyId, ForeignCall memory _foreignCall) internal;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the foreign call is associated with.
`_foreignCall`	`ForeignCall`	The foreign call to store.

_incrementForeignCallIndex

Helper function to increment the foreign call index

Ensures the foreign call is properly set before storing it.

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

Parameters

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

_storeForeignCallData

Helper function to store the foreign call data

Ensures the foreign call is properly set before storing it.

function _storeForeignCallData(uint256 _policyId, ForeignCall calldata _foreignCall, uint256 _foreignCallIndex)
    private;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the foreign call is associated with.
`_foreignCall`	`ForeignCall`	The foreign call to store.
`_foreignCallIndex`	`uint256`	The index of the foreign call.

_storeForeignCallMetadata

Helper function to store the foreign call metadata

function _storeForeignCallMetadata(uint256 _policyId, uint256 _foreignCallIndex, string calldata _foreignCallName)
    private;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the foreign call is associated with.
`_foreignCallIndex`	`uint256`	The index of the foreign call.
`_foreignCallName`	`string`	The name of the foreign call.

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

Parameters

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

Returns

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

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

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.

deleteTracker

Deletes a tracker from the tracker storage mapping.

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

Parameters

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

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.

getTrackerMetadata

retrieves the tracker metadata

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

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
`trMeta`	`string`	the metadata for the tracker

getTracker

Retrieves a tracker from the tracker storage mapping.

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

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
`tracker`	`Trackers`	The tracker data.

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

_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 calldata _tracker) private;

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`

_storeTrackerMetadata

Helper function to store tracker metadata

function _storeTrackerMetadata(uint256 _policyId, uint256 _trackerIndex, string calldata _trackerName) private;

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

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

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>`	`uint256`	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,
    uint256 callingFunctionID,
    bytes4 functionSignature,
    ParamTypes[] memory pTypes
) external policyAdminOnly(policyId, msg.sender) returns (uint256);

Parameters

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

Returns

Name	Type	Description
`<none>`	`uint256`	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, uint256 callingFunctionId)
    external
    policyAdminOnly(policyId, msg.sender);

Parameters

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

getCallingFunction

Retrieves a calling function from storage.

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

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the calling function is associated with.
`callingFunctionId`	`uint256`	The ID 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, uint256 callingFunctionId)
    public
    view
    returns (CallingFunctionHashMapping memory);

Parameters

Name	Type	Description
`policyId`	`uint256`	The policy ID the calling function is associated with.
`callingFunctionId`	`uint256`	The identifier 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.

_incrementFunctionId

Helper function to increment function ID

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

Parameters

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

_storeCallingFunctionData

Helper function to store calling function data

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

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the calling function is associated with.
`_functionId`	`uint256`	The ID of the function
`_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,
    uint256 _functionId,
    bytes4 _functionSignature,
    string memory _callingFunctionName,
    string memory _encodedValues
) private;

Parameters

Name	Type	Description
`_policyId`	`uint256`	The policy ID the calling function is associated with.
`_functionId`	`uint256`	The ID of the function
`_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
    policyAdminOnly(policyId, msg.sender);

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

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.

reference

​Functions

​createForeignCall

​updateForeignCall

​deleteForeignCall

​getAllForeignCalls

​getForeignCall

​getForeignCallMetadata

​_storeForeignCall

​_incrementForeignCallIndex

​_storeForeignCallData

​_storeForeignCallMetadata

​createTracker

​updateTracker

​deleteTracker

​getAllTrackers

​getTrackerMetadata

​getTracker

​_storeTracker

​_incrementTrackerIndex

​_storeTrackerData

​_storeTrackerMetadata

​createCallingFunction

​updateCallingFunction

​deleteCallingFunction

​getCallingFunction

​getCallingFunctionMetadata

​getAllCallingFunctions

​_incrementFunctionId

​_storeCallingFunctionData

​_storeCallingFunctionMetadata

​addClosedPolicySubscriber

​removeClosedPolicySubscriber

​isClosedPolicySubscriber

​_notCemented

Functions

createForeignCall

updateForeignCall

deleteForeignCall

getAllForeignCalls

getForeignCall

getForeignCallMetadata

_storeForeignCall

_incrementForeignCallIndex

_storeForeignCallData

_storeForeignCallMetadata

createTracker

updateTracker

deleteTracker

getAllTrackers

getTrackerMetadata

getTracker

_storeTracker

_incrementTrackerIndex

_storeTrackerData

_storeTrackerMetadata

createCallingFunction

updateCallingFunction

deleteCallingFunction

getCallingFunction

getCallingFunctionMetadata

getAllCallingFunctions

_incrementFunctionId

_storeCallingFunctionData

_storeCallingFunctionMetadata

addClosedPolicySubscriber

removeClosedPolicySubscriber

isClosedPolicySubscriber

_notCemented